rwliebs · cursor · Mar 30, 2026
diff --git a/README.md b/README.md
@@ -141,7 +141,7 @@ Your browser will open to **http://localhost:3000**. First run creates `~/.dossi
 
 On first run you'll be guided through API key setup, or navigate directly to `/setup`.
 
-**Prerequisites:** Node.js 20+, [Anthropic API key](https://console.anthropic.com/). A [GitHub token](https://github.com/settings/tokens) with `repo` scope is needed only if you want agents to open PRs; agents can write files locally without it.
+**Prerequisites:** Node.js 20+, and Anthropic credentials. For planning, you can use an [Anthropic API key](https://console.anthropic.com/) or an authenticated Claude CLI install. Build orchestration requires `ANTHROPIC_API_KEY`. A [GitHub token](https://github.com/settings/tokens) with `repo` scope is needed only if you want agents to open PRs; agents can write files locally without it.
 
 > **Windows users:** Dossier uses native SQLite, which requires a C++ compiler during install. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) with the **"Desktop development with C++"** workload, or run this from an elevated PowerShell:
 > ```powershell
@@ -165,7 +165,7 @@ On first run you'll be guided through API key setup, or navigate directly to `/s
 
 Configuration (API keys, GitHub token) can be set via the web UI at `/setup` or by editing `~/.dossier/config`. See [.env.example](.env.example) for all options.
 
-NEW: Use your Claude MAX account directly, no extra setup required (if you've got Claude Code installed locally.)
+NEW: You can use your Claude CLI authentication for planning workflows. Build orchestration still requires `ANTHROPIC_API_KEY`.
 
 ---
 

diff --git a/docs/development-reference.md b/docs/development-reference.md
@@ -1,6 +1,6 @@
 ---
 document_id: doc.development
-last_verified: 2026-02-18
+last_verified: 2026-03-30
 tokens_estimate: 700
 tags:
   - development
@@ -46,6 +46,7 @@ pnpm install   # or: npm install
 - **Development**: Copy `.env.example` to `.env.local`; fill `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`
 - **Self-deploy**: Use `/setup` or edit `~/.dossier/config`
 - Precedence: `process.env` > `.env.local` > `~/.dossier/config`
+- Planning can run through Claude CLI auth when API key is absent; build orchestration still requires `ANTHROPIC_API_KEY`
 
 ---
 
@@ -89,6 +90,52 @@ Override: `DOSSIER_DATA_DIR` or `SQLITE_PATH`
 
 ---
 
+## Operational Runbook (Common Tasks)
+
+### Sync local clone after merging on GitHub
+
+Use:
+
+`POST /api/projects/[projectId]/repo/sync`
+
+This fetches and syncs local `<default_branch>` in `~/.dossier/repos/<projectId>/` to `origin/<default_branch>`.
+
+### Push a completed card branch
+
+Use:
+
+`POST /api/projects/[projectId]/cards/[cardId]/push`
+
+Requires:
+- Connected repository on project
+- Completed assignment for the card
+- `GITHUB_TOKEN` configured
+
+### View app from cloned project during development
+
+Use:
+
+`POST /api/dev/restart-and-open` with `{ "projectId": "..." }`
+
+Behavior:
+- Dev-only (`NODE_ENV=development`)
+- Starts `npm run dev` in clone path
+- Picks first free port in `3001..3010`
+
+---
+
+## Troubleshooting
+
+- **Planning works but build trigger fails with Anthropic credential error**
+  - Planning may be running via Claude CLI auth.
+  - Build path uses orchestration/Agent SDK and requires `ANTHROPIC_API_KEY`.
+- **Push/sync endpoints failing with auth errors**
+  - Verify `GITHUB_TOKEN` is set in env or `~/.dossier/config`.
+- **Finalize blocked**
+  - Card finalize requires project finalized state, at least one requirement, and at least one planned file.
+
+---
+
 ## Verification
 - [ ] `npm run dev` starts on 3000
 - [ ] `npm run test` passes

diff --git a/docs/domains/api-reference.md b/docs/domains/api-reference.md
@@ -1,6 +1,6 @@
 ---
 document_id: doc.api-reference
-last_verified: 2026-02-18
+last_verified: 2026-03-30
 tokens_estimate: 400
 tags:
   - api
@@ -30,7 +30,14 @@ ttl_expires_on: null
 | Artifacts | `/api/projects/[id]/artifacts` | Context artifacts |
 | Card knowledge | `/api/projects/[id]/cards/[cardId]/{requirements,facts,assumptions,questions}` | Knowledge items |
 | Planned files | `/api/projects/[id]/cards/[cardId]/planned-files` | Card planned files |
+| Finalize | `/api/projects/[id]/cards/[cardId]/finalize` | Card finalization package + SSE finalize pipeline |
+| Orchestration build | `/api/projects/[id]/orchestration/build` | Trigger card/workflow build runs |
+| Orchestration runs | `/api/projects/[id]/orchestration/runs` | Create/list runs, assignments, checks |
+| Approvals & PR candidates | `/api/projects/[id]/orchestration/{approvals,pull-requests}` | Human-gated approval + PR metadata lifecycle |
+| Repo sync/push | `/api/projects/[id]/repo/sync`, `/cards/[cardId]/push` | Sync local base branch and push card feature branch |
 | Files | `/api/projects/[id]/files` | File tree (planned or repo); `?source=repo` for produced code |
+| Setup & GitHub | `/api/setup`, `/api/setup/status`, `/api/github/repos` | First-run credentials and GitHub repo list/create |
+| Docs & memory | `/api/docs`, `/api/projects/[id]/memory` | Docs index/content and memory inspection |
 
 ## Related
 - [data-contracts-reference.md](data-contracts-reference.md)

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-03-30
 tokens_estimate: 750
 tags:
   - planning
@@ -25,6 +25,7 @@ ttl_expires_on: null
 - INVARIANT: Planning LLM outputs PlanningAction[] only; never production code or file contents
 - INVARIANT: Code-generation intents rejected; respond with clarification redirect
 - INVARIANT: IDs in actions must exist in current map state; new entities get fresh UUIDs
+- INVARIANT: Planning auth can use API key or Claude CLI; build orchestration remains API-key-based
 
 ### Boundaries
 - ALLOWED: createWorkflow, createActivity, createCard, updateCard, linkContextArtifact, upsertCardPlannedFile, createContextArtifact, etc.
@@ -49,20 +50,28 @@ Mode selected by `lib/llm/planning-prompt.ts` based on map state.
 ```
 User message → POST /chat/stream
   → buildPlanningSystemPrompt() | buildScaffoldSystemPrompt() | buildPopulateSystemPrompt() | buildFinalizeSystemPrompt()
-  → Claude API (streaming)
+  → auth resolution (API key or Claude CLI)
+  → Claude call (SDK stream or CLI stream-json)
   → stream-action-parser (parse JSON blocks)
   → PlanningAction[] emitted
   → POST /actions (validate + apply)
 ```
 
+### Auth + Transport Paths
+
+| Path | When used | Transport |
+|------|-----------|-----------|
+| API key path | `ANTHROPIC_API_KEY` available via env/config/CLI settings file | Anthropic SDK bridge (`runPlanningQuery` / `streamPlanningQuery`) |
+| CLI path | No API key resolved, but `claude` CLI is installed/authenticated | `claude -p` subprocess (`--output-format json` or `stream-json`) |
+
+Build agents do not use the CLI path; they require `ANTHROPIC_API_KEY`.
+
 ### 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
+  → SSE pipeline: link project docs + generate e2e test artifact + stamp finalized_at
+  → Optional memory ingest for build retrieval context
+  → Card becomes build-ready
 ```
 
 ### Key Files
@@ -71,8 +80,8 @@ User clicks "Finalize" on card → POST /cards/[cardId]/finalize
 | `lib/llm/planning-prompt.ts` | System prompts; mode selection |
 | `lib/llm/stream-action-parser.ts` | Parse streaming JSON → actions |
 | `lib/llm/build-preview-response.ts` | Preview response before apply |
-| `lib/llm/claude-client.ts` | Planning LLM client (Messages API) |
-| `lib/llm/planning-credential.ts` | Resolves ANTHROPIC_API_KEY from env or ~/.dossier/config |
+| `lib/llm/claude-client.ts` | Planning auth/router (API-key SDK path or Claude CLI subprocess path) |
+| `lib/llm/planning-credential.ts` | Resolves planning credential from env/config/`~/.claude/settings.json` |
 | `app/api/projects/[id]/chat/route.ts` | Non-streaming chat |
 | `app/api/projects/[id]/chat/stream/route.ts` | Streaming chat (scaffold, populate, finalize) |
 | `app/api/projects/[id]/cards/[cardId]/finalize/route.ts` | Per-card finalize endpoint |