Add model card with full documentation

README.md

@@ -0,0 +1,121 @@
+---
+license: apache-2.0
+tags:
+  - code-assistant
+  - kintsugi
+  - bdi
+  - pharos
+  - ollama
+  - agent
+  - security
+---
+
+# Project Rivet
+
+A Kintsugi-based coding agent for the Multiverse Campus codebase. Built on BDI (Belief-Desire-Intention) cognition with a discipline gate that refuses destructive operations against a shared staging/production database.
+
+This is a production code assistant for a real deployed application — 120 tables, 377 migrations, 49 Zustand stores, 75 route files — not a toy example.
+
+## Features
+
+- **BDI cognition engine** — Beliefs carry confidence scores and evidence chains. Plans are recorded as BDI intentions with the beliefs they rest on
+- **DAG-enforced skill prerequisites** — Skills execute in dependency order: evidence gathering (L0) before synthesis (L1) before testing (L2) before discipline gate (L3). No path around the gate
+- **Pharos knowledge injection** — Structured knowledge packs (security patterns, TypeScript patterns, campus architecture) injected at inference time via KV cache or system prompt
+- **Discipline gate** — Refuses destructive migrations (DROP, RENAME, TRUNCATE, DELETE FROM). Earned confidence levels (HIGH/MED/LOW) based on evidence quality. No destructive SQL printed even as negative examples
+- **Full security audit context** — 13-finding security audit loaded as beliefs with confidence scores. Agent reasons from known vulnerabilities, not guesses
+- **Tool harness** — File tools (read, write, search), git tools (diff, log, blame), test tools (tsc, npm test), schema tools (table inspection, migration history)
+
+## Architecture
+
+```
+POST /ask {question, user}
+        |
+  SessionManager        per-user isolation, rate limits
+        |
+  Planner                intent -> BDI intention -> SkillDAG
+        |
+  Kintsugi DAGExecutor   layer-parallel execution
+        |
+  L0: code_analysis, migration_safety, security_review  (evidence)
+  L1: synthesis          (single model call with beliefs + Pharos packs)
+  L2: test_runner        (tsc/npm verification)
+  L3: discipline_gate    (belief checks -> BLOCK/WARN, no path around)
+        |
+  response
+```
+
+## Stack
+
+| Component | Implementation |
+|-----------|---------------|
+| LLM | Qwen2.5-Coder:32B via Ollama |
+| Cognition | Kintsugi BDI engine (vendored) |
+| Knowledge | Pharos pack server (security, TypeScript, architecture packs) |
+| Skills | DAG-ordered: code analysis, migration safety, security review, synthesis, test runner, discipline gate |
+| Target codebase | Node.js 20, TypeScript, Express 4, React 18, PostgreSQL 16, Redis 7 |
+
+## Key Design Decisions
+
+**Shared database constraint.** Staging and production share the same PostgreSQL instance. Every migration must be additive-only, backward compatible, and reversible. The discipline gate enforces this — it is not advisory.
+
+**Suggest, don't decree.** The agent is a colleague, not the lead. It suggests, explains, and flags risk. It defers to the humans who run the system.
+
+**Evidence-based confidence.** Every recommendation carries a confidence level derived from what the agent actually read (source files, schema, audit findings), not from training data assumptions.
+
+## Requirements
+
+- Ollama with `qwen2.5-coder:32b` pulled
+- Pharos pack server (optional, for knowledge injection)
+- Python 3.10+
+
+## Usage
+
+```bash
+cd v2
+pip install -r requirements.txt
+./setup.sh
+python rivet.py
+```
+
+## Repository Structure
+
+```
+v2/
+  rivet.py                 # Entry point
+  kintsugi_core.py         # Kintsugi engine integration
+  kintsugi_config.yaml     # Operator constraints and beliefs
+  engine/
+    planner.py             # BDI intention planning
+    beliefs.py             # Confidence-scored belief store
+    session.py             # Per-user session management
+    synthesis.py           # LLM synthesis (single model call)
+    memory.py              # Conversation memory
+    model_client.py        # Ollama API client
+  skills/
+    code_analysis.py       # Source code reading and analysis
+    migration_safety.py    # Schema + SQL safety checks
+    security_review.py     # Audit-informed security review
+    discipline_gate.py     # Final BLOCK/WARN gate
+    test_runner.py         # tsc/npm test verification
+  tools/
+    file_tools.py          # File read/write/search
+    git_tools.py           # Git diff/log/blame
+    schema_tools.py        # Table inspection, migration history
+    test_tools.py          # Test execution
+    guard.py               # Input validation
+  pharos/
+    pack_loader.py         # Pharos pack loading
+    kv_injector.py         # KV cache injection
+context/
+  architecture_map.md      # Full system architecture
+  audit_findings.md        # 13-finding security audit
+  audit_report.md          # Detailed audit report
+```
+
+## Authors
+
+CC (Coalition Code) and Nexus, Liberation Labs / Transparent Humboldt Coalition
+
+## License
+
+Apache 2.0