ai-spector 0.8.47 → 0.8.49

package/README.md

@@ -1,10 +1,10 @@
 # AI Spector
 
-Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS, basic design, and UI prototypes (static HTML or SPA static build). **Describe what you need in chat** — skills route the agent, which runs `ai-spector` CLI or MCP tools. You usually do not run CLI yourself.
+Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS, basic design, and UI prototypes (static HTML or SPA). **Describe what you need in chat** — an orchestrator routes to specialized workers that run `ai-spector` MCP tools. You rarely touch the terminal.
 
 **Needs:** Node 20+, Git, [Cursor](https://cursor.com) and/or [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(optional — CocoIndex semantic search)*.
 
-**Course (step-by-step):** [docs/course/README.md](docs/course/README.md)
+**Learn:** `npx ai-spector course serve --open` · [Course](docs/course/README.md) *(13 lessons, ~10 min each)*
 
 **Tiếng Việt:** [README.vi.md](README.vi.md)
 
@@ -19,21 +19,29 @@ Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS
 | Node.js ≥ 20 | `node --version` |
 | Git repository | `git status` |
 | Cursor and/or Claude Code | IDE open in project root |
-| Python ≥ 3.11 *(optional)* | only for CocoIndex semantic search |
+| Python ≥ 3.11 *(optional)* | CocoIndex semantic search |
 
----
+### Step 1 — Install & scaffold *(CLI)*
 
-### Step 1 — Scaffold *(only CLI step)*
+Run once at your project root. **Install the package first**, then run the init wizard.
 
-Run once at your project root. On the **first** run, pass `--registry` so `npx` can download the package from the internal Verdaccio registry (`http://10.101.0.239:4873`). No `npm login` required.
+**Internal registry** (Verdaccio — no `npm login` required):
 
 ```bash
-npx ai-spector@latest init --registry http://10.101.0.239:4873
+npm install ai-spector --registry http://10.101.0.239:4873
+npx ai-spector init
 ```
 
-The wizard prompts for editor (Cursor, Claude Code, or both), languages, git hook, and optional CocoIndex.
+**Public npm:**
 
-This creates:
+```bash
+npm install ai-spector
+npx ai-spector init
+```
+
+The init wizard prompts for editor (Cursor, Claude Code, or both), languages, git hook, and optional CocoIndex.
+
+Creates:
 
 - `.ai-spector/` — config, graph, templates
 - `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
@@ -41,129 +49,124 @@ This creates:
 - **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
 - Pre-commit hook (when git is available)
 
----
-
 ### Step 2 — Finish setup in chat
 
-Open the project in **Cursor** or **Claude Code** and say:
-
 ```text
 setup ai-spector project
 ```
 
-The agent installs the npm dependency (if needed), verifies the checklist, offers CocoIndex, and reminds you what is left to do manually.
-
----
+The agent installs the npm dependency (if needed), verifies the checklist, and reminds you of any manual steps.
 
 ### Step 3 — Enable the agent *(manual, one-time)*
 
-**Cursor**
-
-1. **Settings → Rules → Agent Skills** — enable **all** folders under `.cursor/skills/` (see `.cursor/skills/README.md`)
-2. **Reload MCP** — `.cursor/mcp.json` registers the `ai-spector` MCP server
-
-**Claude Code**
+**Cursor:** Settings → Rules → **Agent Skills** — enable **all** folders under `.cursor/skills/`. Reload MCP (`.cursor/mcp.json`).
 
-1. Skills load automatically from `.claude/skills/` (see `CLAUDE.md`)
-2. **Reload MCP** — `.mcp.json` registers the `ai-spector` MCP server
-
----
+**Claude Code:** Skills load from `.claude/skills/`. Reload MCP (`.mcp.json`).
 
 ### Step 4 — Add source material
 
-Drop requirements docs, meeting notes, user stories, or any input into `docs/data-source/`. Supported formats: `.md`, `.txt`, `.pdf`.
-
----
+Drop requirements into `docs/data-source/` (`.md`, `.txt`, `.pdf`).
 
 ### Step 5 — Start the pipeline
 
-In chat:
-
 ```text
 analyze my data source
 ```
 
-Then continue in chat as needed — see [Workflow](#workflow) below.
+Continue in chat — see [Workflow](#workflow) below.
 
 ---
 
-### Optional — CocoIndex semantic search
-
-Enables `docs_search` and `graph_query_fuzzy` MCP tools. Requires Python ≥ 3.11.
-
-In chat:
+## Workflow
 
-```text
-enable CocoIndex for this project
-```
+After `init`, see `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) for the full skill map.
 
-See [docs/setup-guide.md](docs/setup-guide.md) for Postgres / OpenAI embedding options.
+### How chat routing works
 
----
+| Layer | Role |
+|-------|------|
+| **Orchestrator** | Classifies your message, asks clarifying questions, spawns a worker |
+| **Worker** | One job (analyze, generate SRS, review docs, …) with a saved task state |
 
-### Add another editor later
+Say what you want in natural language — same in Cursor and Claude Code. If intent is unclear (especially **“approve”**), the agent asks once before acting.
 
-In chat:
+### First run
 
 ```text
-add Claude Code support to ai-spector
-sync ai-spector cursor skills
+analyze the data source
+validate the graph
+generate the SRS
 ```
 
-After upgrading ai-spector, say **"sync ai-spector cursor skills"** in chat.
-
----
-
-## Workflow
-
-See `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) after `init`.
+Generation is **gated**: workspace check → clarifying questions → plan table → your **yes, go ahead** → waves of writing → optional **SPEC-NNN** approval → index.
 
-### First run
-
-Say in chat:
+Then as needed:
 
 ```text
-“analyze the data source”
-“validate the graph”
-“generate the SRS”
-“refresh the index”
+generate basic design
+generate prototype
+refresh the index
+review documents
 ```
 
-Then: **“generate basic design”** as needed.
-
-**Prototype** — static HTML (default) or SPA (React/Vue/etc. built to static files in `prototype/dist/`). Say **“generate prototype”** or **“generate HTML prototype”** for plain HTML; **“generate prototype with Vue”** (or React) for SPA. If no theme is saved, the agent recommends 3 themes, opens previews, and waits for you to pick. Or name one upfront: **“prototype with stripe theme”**.
-
-Then: **“generate prototype for all screens”**. For SPA, run the framework build and `npx ai-spector prototype sync`.
+**Prototype** — static HTML (default) or SPA (React/Vue → `prototype/dist/`). Say **“generate prototype”** or **“generate prototype with Vue”**. For themes: **“help me pick a theme”** or **“prototype with stripe theme”**. SPA: run framework build, then `npx ai-spector prototype sync`.
 
 ### Day to day
 
 | When | Say (examples) |
 |------|----------------|
-| New or changed data source | “analyze data source” |
-| Check graph | “validate the graph” |
-| Regenerate docs | “generate SRS”, “generate basic design”, … |
-| Prototype (HTML or SPA) | “generate prototype”, “generate prototype with Vue”, “prototype with stripe theme” |
-| Choose a theme | “help me pick a prototype theme”, “show me theme options” |
-| After doc edits | “re-index the graph” |
-| Multi-language sync | “add language vi”, “resolve translations”, “translation status” — [Work 10](docs/course/10-multi-language.md) |
-| Custom templates | “set up template pack”, “template list”, `generate <pack-name>` — [Work 17](docs/course/17-custom-template-packs.md) |
-| What to redo | “what’s the impact of my changes” |
-| Review comments | “resolve comments” |
-| Explore graph | “visualize the graph” |
+| New or changed sources | “analyze data source” |
+| Check graph | “validate the graph”, “graph report” |
+| Regenerate docs | “generate SRS”, “generate basic design” |
+| Pause / resume work | “active tasks”, “resume my SRS”, “pause task” |
+| One feature or section | “I want to add login with Google”, “update the auth section” |
+| After doc edits | “refresh the index”, “re-index the graph” |
+| Document sign-off | “review documents”, “approve srs/01-overview”, “what needs review” |
+| Comment threads | “resolve comments”, “show open comments” |
+| Impact / what to redo | “what’s the impact of my changes” |
+| Prototype | “generate prototype”, “prototype with stripe theme” |
+| Multi-language | “add language vi”, “resolve translations” — [course](docs/course/05-prototype/01-translations.md) |
+| Custom templates | “set up template pack”, `generate <pack-name>` — [course](docs/course/07-advanced/01-custom-templates.md) |
+| Semantic search *(CocoIndex)* | “find all mentions of rate limiting” |
+| Explore graph | “show the graph”, `npx ai-spector graph visualize --open` |
+| Check workspace | “check my workspace”, “why did pre-commit block me” |
 
 ### Typical path
 
 ```text
-docs/data-source/  →  analyze  →  validate graph  →  generate SRS  →  index
-                              →  generate basic design
-                              →  prototype setup  →  generate screens (HTML or SPA build)
+docs/data-source/  →  analyze  →  validate
+  →  generate SRS (clarify → plan → waves → specs)  →  index
+  →  basic design  →  prototype  →  review documents
+```
+
+---
+
+## Optional — CocoIndex
+
+Enables semantic search MCP tools (`docs_search`, `graph_query_fuzzy`). Requires Python ≥ 3.11.
+
+```text
+enable CocoIndex for this project
 ```
 
+See [docs/setup-guide.md](docs/setup-guide.md) for Postgres / embedding options.
+
 ---
 
-## CLI (optional)
+## CLI *(scripts & debugging)*
+
+Most users stay in chat. Useful commands:
+
+```bash
+npx ai-spector course serve --open    # interactive course in browser
+npx ai-spector setup --check
+npx ai-spector graph validate
+npx ai-spector graph visualize --open
+npx ai-spector graph impact --git
+npx ai-spector prototype validate --strict
+```
 
-For scripts or debugging only: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. See `npx ai-spector --help`.
+Full list: `npx ai-spector --help`.
 
 ---
 
@@ -172,19 +175,21 @@ For scripts or debugging only: `npx ai-spector index`, `graph validate`, `graph
 | Issue | Fix |
 |-------|-----|
 | MCP tools unavailable | Reload MCP; confirm `.cursor/mcp.json` or `.mcp.json` has `ai-spector` server |
-| Setup incomplete | In chat: **“check ai-spector setup”** |
-| Skills not routing (Cursor) | Re-enable all folders under `.cursor/skills/` in Settings → Rules |
-| Validate errors after edits | In chat: **“re-index the graph”** |
-| Pre-commit hook missing | In chat: **“install ai-spector git hook”** |
+| Setup incomplete | **“check ai-spector setup”** |
+| Skills not routing (Cursor) | Re-enable all folders under `.cursor/skills/` |
+| Validate errors after edits | **“re-index the graph”** |
+| Pre-commit hook missing | **“install ai-spector git hook”** |
 | Agent stuck on CLI error | `.cursor/skills/ai-spector/references/cli-failures.md` |
 
+After upgrading: reload MCP; in chat **“sync ai-spector cursor skills”** if scaffold skills changed.
+
 ---
 
 ## Node SDK
 
-For **scripts, CI, or custom backends** that call the same operations as the CLI and MCP server:
+For scripts, CI, or custom backends:
 
-- **[SDK guide](docs/sdk.md)** — install, entry points, examples, API reference
+- **[SDK guide](docs/plan/sdk.md)** — install, entry points, API reference
 
 ```bash
 npm install ai-spector
@@ -198,10 +203,10 @@ import { runIndex, runGraphImpact, validateGraph } from "ai-spector";
 
 ## Web / graph SDK
 
-For **browser or custom dashboards** (not the Cursor/Claude CLI), use the read-only npm package **`ai-spector-graph`**. Your backend serves repo JSON; the frontend loads it into `ProjectSession`.
+For browser dashboards (read-only graph UI): npm package **`ai-spector-graph`**.
 
-- **[Integration guide](docs/ai-spector-graph-integration-guide.md)** — architecture, API examples, React, recipes
-- **[API reference](docs/ai-spector-graph.md)** — types and exports
+- **[Integration guide](docs/ai-spector-graph-integration-guide.md)**
+- **[API reference](docs/ai-spector-graph.md)**
 
 ```bash
 npm install ai-spector-graph

package/README.vi.md

@@ -4,7 +4,7 @@ Công cụ làm tài liệu phần mềm trên **Cursor** hoặc **Claude Code**
 
 **Cần có:** Node 20+, Git, [Cursor](https://cursor.com) và/hoặc [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(không bắt buộc — dùng cho tìm kiếm thông minh với CocoIndex)*.
 
-Hướng dẫn chi tiết: [docs/setup-guide.md](docs/setup-guide.md)
+Hướng dẫn từng bước: `npx ai-spector course serve --open` · [Khóa học](docs/course/README.md)
 
 **English:** [README.md](README.md)
 
@@ -23,15 +23,25 @@ Hướng dẫn chi tiết: [docs/setup-guide.md](docs/setup-guide.md)
 
 ---
 
-### Bước 1 — Khởi tạo project *(bước duy nhất cần gõ lệnh)*
+### Bước 1 — Cài gói & khởi tạo *(CLI)*
 
-Chạy một lần ở thư mục gốc project. **Lần đầu** cần thêm `--registry` để `npx` tải gói từ registry nội bộ (`http://10.101.0.239:4873`). **Không cần** `npm login`.
+Chạy một lần ở thư mục gốc project. **Cài gói trước**, rồi chạy wizard init.
+
+**Registry nội bộ** (Verdaccio — **không cần** `npm login`):
+
+```bash
+npm install ai-spector --registry http://10.101.0.239:4873
+npx ai-spector init
+```
+
+**npm công khai:**
 
 ```bash
-npx ai-spector@latest init --registry http://10.101.0.239:4873
+npm install ai-spector
+npx ai-spector init
 ```
 
-Lệnh sẽ hỏi: dùng Cursor, Claude Code hay cả hai; ngôn ngữ tài liệu; git hook; và có bật CocoIndex không.
+Wizard init sẽ hỏi: Cursor, Claude Code hay cả hai; ngôn ngữ; git hook; CocoIndex (tùy chọn).
 
 Sau khi chạy xong sẽ có:
 
@@ -145,11 +155,15 @@ Sau đó: **“generate prototype for all screens”**. Với SPA, chạy build
 | Prototype (HTML hoặc SPA) | “generate prototype”, “generate prototype with Vue”, “prototype with stripe theme” |
 | Chọn theme | “help me pick a prototype theme”, “show me theme options” |
 | Vừa sửa tài liệu xong | “re-index the graph” |
-| Đồng bộ đa ngôn ngữ | “add language vi”, “resolve translations”, “translation status” — [Work 10](docs/course/10-multi-language.md) |
-| Template tùy chỉnh | “set up template pack”, “template list”, `generate <pack-name>` — [Work 17](docs/course/17-custom-template-packs.md) |
+| Đồng bộ đa ngôn ngữ | “add language vi”, “resolve translations” — [Translations](docs/course/05-prototype/01-translations.md) |
+| Template tùy chỉnh | “set up template pack”, `generate <pack-name>` — [Custom templates](docs/course/07-advanced/01-custom-templates.md) |
 | Xem phần nào bị ảnh hưởng | “what’s the impact of my changes” |
-| Xử lý comment | “resolve comments” |
-| Xem sơ đồ trực quan | “visualize the graph” |
+| Xử lý comment | “resolve comments”, “show open comments” |
+| Duyệt / phê duyệt tài liệu | “review documents”, “approve srs/01-overview” |
+| Tạm dừng / tiếp tục task | “active tasks”, “resume my SRS” |
+| Thêm / sửa một phần nhỏ | “I want to add login with Google” |
+| Xem sơ đồ trực quan | “show the graph”, `npx ai-spector graph visualize --open` |
+| Kiểm tra workspace | “check my workspace” |
 
 ### Quy trình thường gặp
 
@@ -163,7 +177,16 @@ docs/data-source/  →  analyze  →  validate graph  →  generate SRS  →  in
 
 ## CLI (nếu cần)
 
-Chỉ dùng khi viết script hoặc debug: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. Gõ `npx ai-spector --help` để xem đầy đủ.
+Chủ yếu dùng chat. Một số lệnh hữu ích:
+
+```bash
+npx ai-spector course serve --open
+npx ai-spector setup --check
+npx ai-spector graph validate
+npx ai-spector graph visualize --open
+```
+
+Đầy đủ: `npx ai-spector --help`
 
 ---
 
@@ -184,7 +207,7 @@ Chỉ dùng khi viết script hoặc debug: `npx ai-spector index`, `graph valid
 
 Dùng khi bạn viết **script, CI, hoặc backend tùy chỉnh** — cùng các thao tác typed như CLI và MCP:
 
-- **[Hướng dẫn SDK](docs/sdk.md)** — cài đặt, entry points, ví dụ, tham chiếu API
+- **[Hướng dẫn SDK](docs/plan/sdk.md)** — cài đặt, entry points, ví dụ, tham chiếu API
 
 ```bash
 npm install ai-spector

package/dist/cli.js

@@ -38,13 +38,14 @@ import { runGraphVisualize } from "./core/operations/graph-visualize.js";
 import { runIndex } from "./core/operations/index.js";
 import { runCommentsInbox, runCommentsList, runCommentsPlan, runCommentsResolve, runCommentsShow, } from "./core/operations/comments.js";
 import { runProvenanceLink } from "./core/graph/provenance.js";
-import { runApprove, runReviewStatus, runReviewQueue, runReviewCheck, runReviewReject, runReviewList, runReviewMigrate, } from "./core/operations/review.js";
-import { formatApproveResult, formatReviewStatus, formatReviewQueue, formatReviewCheck, formatReviewReject, formatReviewList, formatReviewMigrate, } from "./interfaces/cli/format/reviews.js";
+import { runApprove, runReviewStatus, runReviewQueue, runReviewCheck, runReviewReject, runReviewList, runReviewMigrate, runReviewSessionStart, runReviewSessionAckReview, } from "./core/operations/review.js";
+import { formatApproveResult, formatReviewStatus, formatReviewQueue, formatReviewCheck, formatReviewReject, formatReviewList, formatReviewMigrate, formatReviewSessionStart, formatReviewSessionAckReview, } from "./interfaces/cli/format/reviews.js";
 import { registerTemplateCommand } from "./core/operations/template.js";
 import { registerReadinessCommand } from "./core/operations/readiness.js";
 import { runCocoindexSetup, runCocoindexSearch, runGraphQueryFuzzy } from "./core/operations/cocoindex.js";
 import { formatCocoindexSetup, formatCocoindexSearch, formatCocoindexStats, formatGraphQueryFuzzy, } from "./interfaces/cli/format/cocoindex.js";
 import { runPrototypeInstallPreviews, runPrototypeManifest, runPrototypePreview, runPrototypeSetup, runPrototypeStack, runPrototypeSync, runPrototypeThemes, runPrototypeValidate, runPrototypeAuth, } from "./core/operations/prototype.js";
+import { runCourseServe, formatCourseServeStarted } from "./core/operations/course.js";
 const program = new Command();
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
@@ -171,7 +172,9 @@ context
     .option("--scope <scope>", "DAG node / section this informs (e.g. srs.use-cases)")
     .option("--source <source>", "user | inferred | data-source", "user")
     .option("--refs <paths>", "Comma-separated source files that make this stale on change")
-    .option("--by <name>", "Who answered")
+    .option("--by <email>", "Answerer email override (default: git user.email)")
+    .option("--username <name>", "Answerer name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--json", "JSON output")
     .action(async (docType, question, opts) => {
     const result = await runContextRecord({
@@ -185,6 +188,8 @@ context
             ? opts.refs.split(",").map((s) => s.trim()).filter(Boolean)
             : undefined,
         answeredBy: opts.by,
+        answeredByUsername: opts.username,
+        role: opts.role,
     });
     if (opts.json)
         console.log(JSON.stringify(result, null, 2));
@@ -195,7 +200,9 @@ context
     .command("resolve <docType> <id> <answer>")
     .description("Answer an open/stale entry by id (e.g. Q-001)")
     .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--by <name>", "Who answered")
+    .option("--by <email>", "Answerer email override (default: git user.email)")
+    .option("--username <name>", "Answerer name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--json", "JSON output")
     .action(async (docType, id, answer, opts) => {
     const result = await runContextResolve({
@@ -204,6 +211,8 @@ context
         id,
         answer,
         answeredBy: opts.by,
+        answeredByUsername: opts.username,
+        role: opts.role,
     });
     if (opts.json)
         console.log(JSON.stringify(result, null, 2));
@@ -235,7 +244,9 @@ spec
     .command("approve <docType> <id>")
     .description("Approve a pending spec; merges its graph patch (if any) into the graph")
     .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--by <name>", "Reviewer name")
+    .option("--by <email>", "Reviewer email override (default: git user.email)")
+    .option("--username <name>", "Reviewer name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--note <note>", "Review note")
     .option("--skip-merge", "Approve without merging the graph patch")
     .option("--json", "JSON output")
@@ -245,6 +256,8 @@ spec
         docType,
         id,
         by: opts.by,
+        username: opts.username,
+        role: opts.role,
         note: opts.note,
         skipMerge: opts.skipMerge,
     });
@@ -257,7 +270,9 @@ spec
     .command("reject <docType> <id>")
     .description("Reject a pending spec (kept for audit, never merged)")
     .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--by <name>", "Reviewer name")
+    .option("--by <email>", "Reviewer email override (default: git user.email)")
+    .option("--username <name>", "Reviewer name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--note <note>", "Why the spec was rejected")
     .option("--json", "JSON output")
     .action(async (docType, id, opts) => {
@@ -266,6 +281,8 @@ spec
         docType,
         id,
         by: opts.by,
+        username: opts.username,
+        role: opts.role,
         note: opts.note,
     });
     if (opts.json)
@@ -395,6 +412,9 @@ task
     .command("approve <taskId>")
     .description("Approve the task plan and advance to the next step")
     .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--by <email>", "Approver email override (default: git user.email)")
+    .option("--username <name>", "Approver name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--plan <json>", "Plan JSON (StoredPlan) if not already set on task")
     .option("--json", "JSON output")
     .action(async (taskId, opts) => {
@@ -402,6 +422,9 @@ task
         root: resolve(opts.cwd ?? process.cwd()),
         taskId,
         plan: opts.plan ? JSON.parse(opts.plan) : undefined,
+        by: opts.by,
+        username: opts.username,
+        role: opts.role,
     });
     if (opts.json)
         console.log(JSON.stringify(result, null, 2));
@@ -898,7 +921,9 @@ comments
     .command("resolve <threadId>")
     .description("Mark thread resolved in meta_data.json and append events.jsonl")
     .requiredOption("--file <path>", "Logical file path (e.g. srs/04-features/auth)")
-    .option("--by <author>", "resolvedBy value recorded in meta_data.json", "local")
+    .option("--by <email>", "Resolver email override (default: git user.email)")
+    .option("--username <name>", "Resolver name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--commit-sha <sha>", "resolvedInCommitSha (defaults to git HEAD)")
     .option("--expected-version <n>", "Optimistic lock on meta_data.json version")
     .option("--dry-run", "Preview resolve without writing files")
@@ -909,6 +934,8 @@ comments
         threadId,
         filePath: opts.file,
         resolvedBy: opts.by,
+        resolvedByUsername: opts.username,
+        role: opts.role,
         commitSha: opts.commitSha,
         expectedVersion: opts.expectedVersion != null ? Number(opts.expectedVersion) : undefined,
         dryRun: opts.dryRun,
@@ -925,10 +952,18 @@ const review = program
 review
     .command("approve <logicalPath>")
     .description("Mark document as internally approved and move to client review queue")
-    .option("--by <reviewer>", "Reviewer name or id (default: local)")
+    .option("--by <email>", "Reviewer email override (default: git user.email)")
+    .option("--username <name>", "Reviewer name override (default: git user.name)")
+    .option("--role <role>", "Actor role: user | client (default: user)")
     .option("--json", "JSON output for agents")
     .action(async (logicalPath, opts, cmd) => {
-    const result = await runApprove({ root: projectRootOpt(cmd), logicalPath, by: opts.by });
+    const result = await runApprove({
+        root: projectRootOpt(cmd),
+        logicalPath,
+        by: opts.by,
+        username: opts.username,
+        role: opts.role,
+    });
     if (opts.json)
         console.log(JSON.stringify(result, null, 2));
     else
@@ -1024,6 +1059,32 @@ review
     else
         console.log(formatReviewMigrate(result));
 });
+const reviewSession = review.command("session").description("Persisted review session gate for sign-off");
+reviewSession
+    .command("start")
+    .description("Start or reset the review session (.session.json)")
+    .option("--json", "JSON output for agents")
+    .action(async (opts, cmd) => {
+    const result = await runReviewSessionStart({ root: projectRootOpt(cmd) });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatReviewSessionStart(result));
+});
+reviewSession
+    .command("ack <logicalPath>")
+    .description("Acknowledge review summary written — unlocks review approve")
+    .option("--json", "JSON output for agents")
+    .action(async (logicalPath, opts, cmd) => {
+    const result = await runReviewSessionAckReview({
+        root: projectRootOpt(cmd),
+        logicalPath,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatReviewSessionAckReview(result));
+});
 const prototype = program
     .command("prototype")
     .description("HTML prototype workspace: themes, manifest, validation (static files under prototype/src/)");
@@ -1065,10 +1126,10 @@ prototype
 });
 prototype
     .command("auth")
-    .description("Configure HTTP basic auth (credentials in prototype.config.json, .htpasswd under prototype/)")
+    .description("Configure HTTP basic auth (credentials in prototype/config.json, .htpasswd under prototype/)")
     .option("--username <name>", "Basic auth username")
     .option("--password <secret>", "Basic auth password")
-    .option("--from-config", "Regenerate .htpasswd from stored prototype.config.json basicAuth")
+    .option("--from-config", "Regenerate .htpasswd from stored prototype/config.json basicAuth")
     .action(async (opts, cmd) => {
     await runPrototypeAuth({
         root: projectRootOpt(cmd),
@@ -1164,6 +1225,27 @@ graph
 });
 registerTemplateCommand(program);
 registerReadinessCommand(program);
+const course = program
+    .command("course")
+    .description("Browse the step-by-step AI Spector course in your browser");
+course
+    .command("serve")
+    .description("Start a local web server for the interactive course")
+    .option("--port <number>", "Port (default: 4177)", (v) => Number(v), 4177)
+    .option("--host <host>", "Host (default: 127.0.0.1)", "127.0.0.1")
+    .option("--open", "Open the course in your default browser")
+    .action(async (opts, cmd) => {
+    const result = await runCourseServe({
+        projectRoot: projectRootOpt(cmd),
+        host: opts.host,
+        port: opts.port,
+        open: opts.open,
+    });
+    console.log(formatCourseServeStarted(result));
+    await new Promise(() => {
+        /* keep process alive until Ctrl+C */
+    });
+});
 // ── CocoIndex ──────────────────────────────────────────────────────────────────
 const cocoindex = program
     .command("cocoindex")