docs: refresh planning map and API references

docs/README.md

@@ -39,7 +39,7 @@ docs/
 │   └── design-system.md
 │
 ├── adr/                      # Architecture Decision Records
-│   └── 0001-*.md through 0015-*.md
+│   └── 0001-*.md through 0016-*.md
 │
 ├── Feature Plans/            # Future feature plans
 │   ├── claude-plugin-packaging.md

docs/SYSTEM_ARCHITECTURE.md

@@ -1,7 +1,7 @@
 ---
 document_id: doc.system-architecture
-last_verified: 2026-03-06
-tokens_estimate: 950
+last_verified: 2026-06-15
+tokens_estimate: 1050
 tags:
   - architecture
   - system
@@ -37,13 +37,13 @@ ttl_expires_on: null
 
 ## Overview
 
-Single-user desktop app. Next.js serves UI + API. Electron wraps it. SQLite stores all state locally. RuVector stores embeddings locally. Anthropic API provides LLM. Build agents run in-process via `@anthropic-ai/claude-agent-sdk`.
+Single-user desktop app. Next.js serves UI + API. Electron wraps it. SQLite stores all state locally. RuVector stores embeddings locally. Planning uses the Claude Agent SDK for credentialed users, with Claude CLI fallback when no credential is extractable. Build agents run in-process via `@anthropic-ai/claude-agent-sdk`.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  Electron Shell                                              │
 │  ┌──────────────────────────────────────────────────────┐   │
-│  │  Next.js 15 (standalone)                              │   │
+│  │  Next.js 16 (standalone)                              │   │
 │  │  ┌──────────┐  ┌──────────┐  ┌───────────────────┐   │   │
 │  │  │ React 19 │  │ API      │  │ Claude Agent SDK  │   │   │
 │  │  │ UI       │──│ Routes   │──│ (in-process,      │   │   │
@@ -73,7 +73,7 @@ Single-user desktop app. Next.js serves UI + API. Electron wraps it. SQLite stor
 | UI | React 19 + Tailwind v4 + shadcn/ui | `app/`, `components/` |
 | API | Next.js App Router (route handlers) | `app/api/` |
 | Database | SQLite via better-sqlite3 (local, no Supabase) | `lib/db/` |
-| Planning LLM | Anthropic Claude (streaming + non-streaming) | `lib/llm/` |
+| Planning LLM | Claude Agent SDK `query()` or Claude CLI fallback (streaming + non-streaming) | `lib/llm/` |
 | Build agents | `@anthropic-ai/claude-agent-sdk` `query()` (streaming, in-process) | `lib/orchestration/` |
 | Agent definitions | agentic-flow registry (system prompts only) | `node_modules/agentic-flow/` |
 | Embeddings | all-MiniLM-L6-v2 (ONNX WASM, local) | `lib/memory/embedding.ts` |
@@ -106,12 +106,12 @@ Full schema details: [data-contracts-reference.md](domains/data-contracts-refere
 ## Data Flow (Summaries)
 
 ### Planning
-`User chat → Anthropic streaming API → stream-action-parser → PlanningAction[] → validate → apply → SQLite`
+`User chat → claude-client → Agent SDK query() or Claude CLI fallback → stream-action-parser → PlanningAction[] → validate → apply → SQLite`
 
 Detail: [planning-reference.md](domains/planning-reference.md)
 
 ### Map
-`GET /map → fetchMapSnapshot → PlanningState → buildMapTree → nested JSON for UI`
+`GET /map → getProject + workflows + activities + cards → group by workflow/activity → nested JSON for UI`
 
 Detail: [map-reference.md](domains/map-reference.md)
 
@@ -138,14 +138,14 @@ Two distinct connection patterns exist.
 
 | Concern | Planning LLM | Build Agent |
 |---------|-------------|-------------|
-| Auth | `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` |
-| SDK | `@anthropic-ai/sdk` (Messages API) | `@anthropic-ai/claude-agent-sdk` |
-| Call style | `messages.create` / `messages.stream` | `query()` — async iterator |
+| Auth | `ANTHROPIC_API_KEY`, OAuth token, or Claude CLI auth fallback | `ANTHROPIC_API_KEY` |
+| SDK | `@anthropic-ai/claude-agent-sdk` for credentials; `claude -p` fallback | `@anthropic-ai/claude-agent-sdk` |
+| Call style | `query()` for credentials; CLI subprocess fallback | `query()` — async iterator |
 | Streaming | Optional (non-streaming for simple calls, streaming for chat) | Always streaming (`for await` over messages) |
-| Tools | None (text output only) | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch |
-| CWD | N/A | `worktree_path` (repo clone) |
+| Tools | Agent SDK path: `WebSearch`; plus `Read`, `Glob`, `Grep` when repo cwd is available | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch |
+| CWD | Connected repo clone when available; otherwise none | `worktree_path` (repo clone) |
 | Lifecycle | Request-response per chat turn | Fire-and-forget; result via in-process webhook callback |
-| Model | `claude-haiku-4-5-20251001` (configurable) | `claude-sonnet-4-5-20250929` (configurable) |
+| Model | `claude-haiku-4-5-20251001` for Agent SDK; `claude-sonnet-4-6` CLI default; configurable | `claude-sonnet-4-5-20250929` (configurable) |
 
 ---
 

docs/docs-index.yaml

@@ -6,31 +6,31 @@ docs_index:
   documents:
     - id: doc.system-architecture
       path: SYSTEM_ARCHITECTURE.md
-      tokens_estimate: 1200
+      tokens_estimate: 1050
       tags: [architecture, system, overview]
       anchors:
         - id: overview
           summary: "Self-deployable Next.js app; SQLite + agentic-flow + RuVector"
         - id: data-flow
-          summary: "Planning LLM → actions → DbAdapter; Build → orchestration → agents"
+          summary: "Planning LLM → actions → SQLite; Build → orchestration → agents"
         - id: endpoints
           summary: "REST API under /api/projects; map, actions, artifacts, cards"
       depends_on: []
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.data-contracts
       path: domains/data-contracts-reference.md
-      tokens_estimate: 1800
+      tokens_estimate: 1850
       tags: [schemas, types, api, contracts]
       anchors:
         - id: contract
           summary: "Zod schemas in lib/schemas/; slice-a/b/c + action-payloads"
         - id: core-entities
-          summary: "Project, Workflow, WorkflowActivity, Step, Card hierarchy"
+          summary: "Project, Workflow, WorkflowActivity, Card hierarchy"
         - id: actions
           summary: "PlanningAction payloads and target_ref per action_type"
       depends_on: [doc.system-architecture]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.design-system
       path: design/design-system.md
@@ -44,7 +44,7 @@ docs_index:
 
     - id: doc.user-workflows
       path: product/user-workflows-reference.md
-      tokens_estimate: 900
+      tokens_estimate: 1200
       tags: [ux, workflows, user-journey]
       anchors:
         - id: workflow-a
@@ -54,53 +54,53 @@ docs_index:
         - id: workflow-c
           summary: "Build trigger to draft PR: agents, checks, approval"
       depends_on: [doc.system-architecture]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.api-reference
       path: domains/api-reference.md
-      tokens_estimate: 400
+      tokens_estimate: 550
       tags: [api, endpoints]
       anchors:
         - id: endpoints
-          summary: "REST API under /api/projects; map, actions, artifacts, cards"
+          summary: "REST API groups: setup, GitHub, map, actions, chat, cards, orchestration"
       depends_on: [doc.system-architecture]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.planning
       path: domains/planning-reference.md
-      tokens_estimate: 700
+      tokens_estimate: 900
       tags: [planning, llm, chat]
       anchors:
         - id: contract
           summary: "Planning LLM converts ideas to PlanningAction[]; never code-gen"
         - id: modes
           summary: "Scaffold, populate, full; mode selected by map state"
       depends_on: [doc.system-architecture, doc.data-contracts]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.mutation
       path: domains/mutation-reference.md
-      tokens_estimate: 650
+      tokens_estimate: 800
       tags: [mutation, actions, pipeline]
       anchors:
         - id: contract
           summary: "All map changes via PlanningAction; validate → apply in transaction"
         - id: pipeline
           summary: "validate-action → apply-action; idempotency via key"
       depends_on: [doc.system-architecture, doc.data-contracts]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.map
       path: domains/map-reference.md
-      tokens_estimate: 550
+      tokens_estimate: 650
       tags: [map, snapshot, story-map]
       anchors:
         - id: contract
-          summary: "Map = Project + Workflow→Activity→Step→Card tree; PlanningState"
+          summary: "Map = Project + Workflow→Activity→Card tree; PlanningState"
         - id: build
-          summary: "fetchMapSnapshot → PlanningState; buildMapTree → API response"
+          summary: "GET /map batches project/workflow/activity/card queries into nested response"
       depends_on: [doc.system-architecture, doc.data-contracts]
-      last_verified: "2026-02-18"
+      last_verified: "2026-06-15"
 
     - id: doc.orchestration
       path: domains/orchestration-reference.md
@@ -180,6 +180,16 @@ docs_index:
       depends_on: []
       last_verified: "2026-03-06"
 
+    - id: doc.planning-agent-auth-paths
+      path: adr/0016-planning-agent-two-auth-paths.md
+      tokens_estimate: 650
+      tags: [planning, llm, auth, adr]
+      anchors:
+        - id: decision
+          summary: "Credentialed planning uses Agent SDK; Claude CLI remains fallback"
+      depends_on: [doc.planning]
+      last_verified: "2026-06-15"
+
     - id: doc.desktop-build-distribution
       path: reference/desktop-build-and-distribution.md
       tokens_estimate: 600

docs/domains/api-reference.md

@@ -1,7 +1,7 @@
 ---
 document_id: doc.api-reference
-last_verified: 2026-02-18
-tokens_estimate: 400
+last_verified: 2026-06-15
+tokens_estimate: 550
 tags:
   - api
   - endpoints
@@ -24,13 +24,21 @@ ttl_expires_on: null
 | Group | Base Path | Purpose |
 |-------|-----------|---------|
 | Projects | `/api/projects` | CRUD projects |
-| Map | `/api/projects/[id]/map` | Canonical map snapshot |
+| Setup | `/api/setup`, `/api/setup/status` | Local credential setup status and config writes |
+| GitHub | `/api/github/*` | OAuth, token disconnect, user/repo lookup, repo creation |
+| Map | `/api/projects/[id]/map` | Canonical Workflow → Activity → Card snapshot |
 | Actions | `/api/projects/[id]/actions` | Submit planning actions |
 | Chat | `/api/projects/[id]/chat`, `/chat/stream` | Planning LLM |
 | Artifacts | `/api/projects/[id]/artifacts` | Context artifacts |
+| Card finalize | `/api/projects/[id]/cards/[cardId]/finalize` | Card finalization package and SSE finalization |
 | 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 |
+| Card context links | `/api/projects/[id]/cards/[cardId]/context-artifacts` | Context artifacts linked to a card |
+| Card outputs | `/api/projects/[id]/cards/[cardId]/produced-files`, `/push` | Changed files and feature-branch push |
 | Files | `/api/projects/[id]/files` | File tree (planned or repo); `?source=repo` for produced code |
+| Repository sync | `/api/projects/[id]/repo/sync` | Align local clone default branch with GitHub |
+| Memory | `/api/projects/[id]/memory` | Project memory units and local storage paths |
+| Orchestration | `/api/projects/[id]/orchestration/*` | Build runs, assignments, checks, approvals, PR candidates |
 
 ## Related
 - [data-contracts-reference.md](data-contracts-reference.md)

docs/domains/data-contracts-reference.md

@@ -1,7 +1,7 @@
 ---
 document_id: doc.data-contracts
-last_verified: 2026-02-18
-tokens_estimate: 1800
+last_verified: 2026-06-15
+tokens_estimate: 1850
 tags:
   - schemas
   - types
@@ -11,7 +11,7 @@ anchors:
   - id: contract
     summary: "Zod schemas in lib/schemas/; slice-a/b/c + action-payloads"
   - id: core-entities
-    summary: "Project, Workflow, WorkflowActivity, Step, Card hierarchy"
+    summary: "Project, Workflow, WorkflowActivity, Card hierarchy"
   - id: card-context
     summary: "ContextArtifact, CardPlannedFile, knowledge items"
   - id: actions
@@ -53,9 +53,7 @@ ttl_expires_on: null
 Project
   └── Workflow[] (position-ordered)
         └── WorkflowActivity[] (position-ordered)
-              ├── Step[] (position-ordered)
-              │     └── Card[] (step_id or activity-level)
-              └── Card[] (activity-level, no step)
+              └── Card[] (position/priority-ordered)
 ```
 
 ### Project
@@ -91,13 +89,13 @@ Project
 |-------|------|-------|
 | id | uuid | |
 | workflow_activity_id | uuid | |
-| step_id | uuid \| null | optional, for step-scoped cards |
 | title | string (min 1) | |
 | description | string \| null | optional |
 | status | enum | todo\|active\|questions\|review\|production |
 | priority | int | |
 | position | int | |
 | quick_answer | string \| null | optional |
+| finalized_at | datetime \| null | set by card finalization endpoint |
 
 ---
 
@@ -147,18 +145,23 @@ All actions: `{ id, project_id, action_type, target_ref, payload }`
 
 | action_type | target_ref | payload |
 |-------------|------------|---------|
-| updateProject | `{ project_id }` | `{ name?, description? }` |
+| updateProject | `{ project_id }` | `{ name?, description?, customer_personas?, tech_stack?, deployment?, design_inspiration? }` |
 | createWorkflow | `{ project_id }` | `{ title, description?, position }` |
 | createActivity | `{ workflow_id }` | `{ title, color?, position }` |
 | createCard | `{ workflow_activity_id }` | `{ title, description?, status, priority, position }` |
 | updateCard | `{ card_id }` | `{ title?, description?, status?, priority?, quick_answer? }` |
 | reorderCard | `{ card_id }` | `{ new_position }` |
+| deleteWorkflow | `{ workflow_id }` | `{}` |
+| deleteActivity | `{ workflow_activity_id }` | `{}` |
+| deleteCard | `{ card_id }` | `{}` |
 | linkContextArtifact | `{ card_id }` | `{ context_artifact_id, linked_by?, usage_hint? }` |
 | createContextArtifact | `{ project_id }` | `{ name, type, title?, content, card_id? }` |
 | upsertCardPlannedFile | `{ card_id }` | `{ logical_file_name, artifact_kind, action, intent_summary, contract_notes?, position, planned_file_id? }` |
-| approveCardPlannedFile | `{ card_id }` | `{ planned_file_id, status: "approved"\|"proposed" }` |
 | upsertCardKnowledgeItem | `{ card_id }` | `{ item_type, text, evidence_source?, confidence?, position, knowledge_item_id? }` |
-| setCardKnowledgeStatus | `{ card_id }` | `{ knowledge_item_id, status }` |
+
+Notes:
+- Planned-file approval is a card planned-file REST update (`PATCH /api/projects/[projectId]/cards/[cardId]/planned-files/[fileId]`), not a PlanningAction.
+- Knowledge-item status changes are handled by the relevant knowledge-item REST routes, not a PlanningAction.
 
 ---