rwliebs · cursor · Apr 13, 2026
diff --git a/docs/development-reference.md b/docs/development-reference.md
@@ -1,6 +1,6 @@
 ---
 document_id: doc.development
-last_verified: 2026-04-06
+last_verified: 2026-04-13
 tokens_estimate: 700
 tags:
   - development
@@ -116,11 +116,15 @@ Default: `~/.dossier/`
 ~/.dossier/
   config       # API keys, settings (KEY=VALUE)
   dossier.db   # SQLite database
-  ruvector/   # Vector embeddings (future)
+  ruvector/    # Vector index storage used by memory plane
 ```
 
 Override: `DOSSIER_DATA_DIR` or `SQLITE_PATH`
 
+Inspect memory contents via:
+- `GET /api/projects/<projectId>/memory`
+- [domains/memory-reference.md](domains/memory-reference.md)
+
 ---
 
 ## Workflow

diff --git a/docs/domains/planning-reference.md b/docs/domains/planning-reference.md
@@ -1,6 +1,6 @@
 ---
 document_id: doc.planning
-last_verified: 2026-03-06
+last_verified: 2026-04-13
 tokens_estimate: 750
 tags:
   - planning
@@ -57,14 +57,22 @@ User message → POST /chat/stream
 
 ### Per-Card Finalize Flow
 ```
-User clicks "Finalize" on card → POST /cards/[cardId]/finalize
-  → Assemble: project-wide docs + card context + e2e tests
-  → Return finalization package for review
-  → User edits (optional)
-  → POST /cards/[cardId]/finalize/confirm
-  → Set card.finalized_at → card is build-ready
+User opens finalize panel → GET /cards/[cardId]/finalize
+  → Return package: card + project_docs + card_artifacts + requirements + planned_files
+User confirms finalize → POST /cards/[cardId]/finalize (SSE)
+  → link_docs step: link project doc/spec/design artifacts to card
+  → test_gen step: generate e2e test/context artifact actions via LLM
+  → confirm step: set card.finalized_at, optionally ingest memory context
+  → Emit done
 ```
 
+Per-card finalize preconditions (enforced by route):
+- project must already be approved (`project.finalized_at` exists)
+- card must contain at least one requirement
+- card must contain at least one planned file/folder
+- card must not already be finalized
+- planning LLM flag must be enabled
+
 ### Key Files
 | File | Purpose |
 |------|---------|

diff --git a/docs/reference/api-endpoints.md b/docs/reference/api-endpoints.md
@@ -81,6 +81,68 @@ Update project.
 
 ---
 
+## Planning Chat
+
+### POST /api/projects/[projectId]/chat
+
+Non-streaming planning endpoint. Supports scaffold, populate, and finalize modes.
+
+**Request body:**
+```json
+{
+  "message": "Plan auth and profile flows",
+  "mode": "scaffold|populate|finalize (optional)",
+  "workflow_id": "uuid (required when mode=populate)",
+  "conversationHistory": [
+    { "role": "user|agent", "content": "string" }
+  ],
+  "mock_response": "string (test-only)"
+}
+```
+
+Behavior:
+- `mode=finalize` runs multi-step finalization and sets `project.finalized_at` on success.
+- `mode=populate` with `workflow_id` adds activities/cards for a single workflow.
+- no mode defaults to scaffold for empty maps or full planning for structured maps.
+
+**Response:** `200` (`ChatResponse`)
+```json
+{
+  "status": "success|error",
+  "responseType": "clarification|actions|mixed",
+  "message": "string",
+  "applied": 2,
+  "workflow_ids_created": ["uuid"],
+  "errors": [{ "action_type": "createCard", "reason": "..." }]
+}
+```
+
+### POST /api/projects/[projectId]/chat/stream
+
+Streaming SSE variant of planning chat. Supports `scaffold`, `populate`, and `finalize`.
+
+**Request body:**
+```json
+{
+  "message": "Create initial workflows",
+  "mode": "scaffold|populate|finalize (optional; defaults to scaffold)",
+  "workflow_id": "uuid (required when mode=populate)",
+  "mock_response": "string (test-only)"
+}
+```
+
+Common SSE events include:
+- `action` - parsed planning action
+- `error` - step failure
+- `phase_complete` - scaffold/populate/finalize phase completion metadata
+- `done` - terminal event
+
+Notes:
+- Both chat endpoints return `503` when planning is disabled (`NEXT_PUBLIC_PLANNING_LLM_ENABLED=false`).
+- Both validate request shape with Zod and return `400` on schema failures.
+
+---
+
 ## Setup & GitHub Integration
 
 ### GET /api/setup/status
@@ -283,6 +345,54 @@ Submit planning actions. Validates, applies, and persists. Rejects on first fail
 
 Code-generation intents are rejected.
 
+### POST /api/projects/[projectId]/actions/preview
+
+Dry-run action preview. Computes deltas/summaries without writing to the database.
+
+**Request body:** Same as `POST /actions`
+
+**Response:** `200`
+```json
+{
+  "success": true,
+  "previews": [{ "summary": "Create workflow 'Checkout'" }],
+  "summary": ["Create workflow 'Checkout'"]
+}
+```
+
+---
+
+## Memory Plane
+
+### GET /api/projects/[projectId]/memory
+
+Lists memory units linked to the project and reports storage locations.
+
+Use this endpoint to verify that finalize/ingestion actually produced memory data.
+
+**Response:** `200`
+```json
+{
+  "projectId": "uuid",
+  "count": 3,
+  "units": [
+    {
+      "id": "uuid",
+      "title": "Auth constraints",
+      "content_type": "text",
+      "status": "active",
+      "updated_at": "2026-04-01T12:00:00.000Z",
+      "content_preview": "First 200 chars...",
+      "link_url": null
+    }
+  ],
+  "storage": {
+    "sqlite": "/home/user/.dossier/dossier.db",
+    "ruvector": "/home/user/.dossier/ruvector/vectors.db"
+  }
+}
+```
+
 ---
 
 ## Context Artifacts
@@ -406,6 +516,69 @@ Delete planned file.
 
 ---
 
+## Card Finalization & Build Outputs
+
+### GET /api/projects/[projectId]/cards/[cardId]/finalize
+
+Returns the finalization package used for card approval:
+- card record
+- project-wide docs (`doc`, `spec`, `design`)
+- linked card artifacts
+- card requirements
+- planned files
+- current `finalized_at`
+
+**Response:** `200` object with keys:
+`card`, `project_docs`, `card_artifacts`, `requirements`, `planned_files`, `finalized_at`
+
+### POST /api/projects/[projectId]/cards/[cardId]/finalize
+
+Approves a card through a 3-step SSE workflow:
+1. link project docs to card
+2. generate e2e test/context artifact(s) via planning LLM
+3. stamp `card.finalized_at` and trigger memory ingestion when enabled
+
+Preconditions:
+- card belongs to project
+- project is already approved (`project.finalized_at` present)
+- card has at least one requirement
+- card has at least one planned file/folder
+- card is not already finalized
+
+**Response:** `200` `text/event-stream`
+
+Key events:
+- `finalize_progress` (step status updates)
+- `action` (created action/artifact events from LLM sub-step)
+- `phase_complete` (`responseType=card_finalize_complete`)
+- `error`
+- `done`
+
+### GET /api/projects/[projectId]/cards/[cardId]/produced-files
+
+Returns added/modified files from the latest completed assignment for this card.
+
+**Response:** `200`
+```json
+[
+  { "path": "src/app/page.tsx", "status": "modified" },
+  { "path": "src/lib/new-module.ts", "status": "added" }
+]
+```
+
+### POST /api/projects/[projectId]/cards/[cardId]/push
+
+Pushes the card's completed feature branch to GitHub.
+
+Common statuses:
+- `200` pushed successfully (`{ "success": true, "branch": "feature/..." }`)
+- `400` repository not connected
+- `401` token/auth failure
+- `409` no completed build assignment for card
+- `502` upstream push error
+
+---
+
 ## Project Files (Planned + Repository)
 
 ### GET /api/projects/[projectId]/files
@@ -534,8 +707,62 @@ Resumes a previously blocked assignment after user input is provided.
 - `GET /api/projects/[projectId]/orchestration/pull-requests/[prId]` - read single candidate
 - `PATCH /api/projects/[projectId]/orchestration/pull-requests/[prId]` - update status (`status=not_created|draft_open|open|merged|closed`, optional `pr_url`)
 
+### Run & Assignment APIs
+
+- `GET /api/projects/[projectId]/orchestration/runs` - list runs; optional query filters: `scope`, `status`, `limit`
+- `POST /api/projects/[projectId]/orchestration/runs` - create run (`scope`, `workflow_id`/`card_id`, `initiated_by`, `repo_url`, `base_branch`, `run_input_snapshot`, optional `worktree_root`)
+- `GET /api/projects/[projectId]/orchestration/runs/[runId]` - fetch run
+- `PATCH /api/projects/[projectId]/orchestration/runs/[runId]` - update run status with guarded transitions
+
+- `GET /api/projects/[projectId]/orchestration/runs/[runId]/assignments` - list run assignments
+- `POST /api/projects/[projectId]/orchestration/runs/[runId]/assignments` - create assignment (`card_id`, `agent_role`, `agent_profile`, `feature_branch`, `allowed_paths`, ...)
+- `GET /api/projects/[projectId]/orchestration/runs/[runId]/assignments/[assignmentId]` - fetch assignment
+- `POST /api/projects/[projectId]/orchestration/runs/[runId]/assignments/[assignmentId]/dispatch` - dispatch queued assignment; returns `202` with `executionId`
+
+### Run Checks
+
+- `GET /api/projects/[projectId]/orchestration/runs/[runId]/checks` - list checks for a run
+- `POST /api/projects/[projectId]/orchestration/runs/[runId]/checks` - record check (`check_type`, `status`, optional `output`)
+- `GET /api/projects/[projectId]/orchestration/runs/[runId]/checks/[checkId]` - fetch one check
+
+### Agent Webhook Receiver
+
+#### POST /api/projects/[projectId]/orchestration/webhooks/agentic-flow
+
+Receives agent execution callbacks and updates orchestration state.
+
+Required body fields:
+- `event_type`: `execution_started|commit_created|execution_completed|execution_failed|execution_blocked`
+- `assignment_id`: card assignment UUID
+
+**Response:** `202` `{ "received": true, "processed": true }`
+
 ---
 
+## Docs API
+
+### GET /api/docs
+
+Returns docs index parsed from `docs/docs-index.yaml`.
+
+**Response:** `200`
+```json
+{
+  "documents": [
+    { "id": "doc.system", "path": "SYSTEM_ARCHITECTURE.md", "tags": ["architecture"] }
+  ]
+}
+```
+
+### GET /api/docs?path=product/user-workflows-reference.md
+
+Returns a single documentation page from the `docs/` directory.
+
+Response:
+- `200` `{ "content": "..." }`
+- `400` invalid path traversal attempt
+- `404` file not found
+
 ## Developer Utilities
 
 ### POST /api/dev/restart-and-open
@@ -567,4 +794,4 @@ Behavior and constraints:
 
 - **Mutations**: All map changes go through the actions endpoint; no direct writes.
 - **Auth**: No auth/RLS; endpoints use anon access (single-user desktop app).
-- **Database**: SQLite only; no Supabase or Postgres.
+- **Database**: SQLite is the only implemented adapter. `DB_DRIVER=postgres` currently throws "Postgres adapter not yet implemented".
diff --git a/docs/reference/configuration-reference.md b/docs/reference/configuration-reference.md
@@ -1,6 +1,6 @@
 ---
 document_id: doc.configuration
-last_verified: 2026-02-18
+last_verified: 2026-04-13
 tokens_estimate: 600
 tags:
   - configuration
@@ -51,14 +51,18 @@ Anthropic credential (API key or Claude CLI config) and GitHub token:
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| DB_DRIVER | sqlite | `sqlite` or `postgres` |
-| DATABASE_URL | — | Postgres connection string (when DB_DRIVER=postgres) |
+| DB_DRIVER | sqlite | `sqlite` (implemented) or `postgres` (currently not implemented) |
+| DATABASE_URL | — | Required only if testing future Postgres adapter paths |
 | DOSSIER_DATA_DIR | ~/.dossier | Data directory |
 | SQLITE_PATH | ~/.dossier/dossier.db | Override SQLite path |
 | EMBEDDING_MODEL | all-MiniLM-L6-v2 | RuVector embedding model |
 | PLANNING_LLM_MODEL | claude-haiku-4-5-20251001 | Planning LLM model |
 | DOSSIER_STALE_RUN_MINUTES | 0 | Minutes before marking stuck runs as failed. 0 = disabled (no timeout). |
 
+Current implementation note:
+- `DB_DRIVER=postgres` will throw at startup (`lib/db/index.ts`): "Postgres adapter not yet implemented."
+- Use SQLite for local and production-like runs until a Postgres adapter is shipped.
+
 ---
 
 ## Feature Flags (NEXT_PUBLIC_*)