specsmith 0.16.0.dev593__tar.gz → 0.16.1__tar.gz

{specsmith-0.16.0.dev593/src/specsmith.egg-info → specsmith-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.16.0.dev593
+Version: 0.16.1
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -110,43 +110,53 @@ flowchart LR
 - **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.
 - **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.
 
-**v0.16.0 — stabilisation milestone:** 20+ new CLI commands (quickstart, expand, verify-integrations, governed-pr, transcript import, policy, recover, dashboard, drift-check, trace score, export/import, approve); new governance modules; ESDB SQLite backend with full test coverage; chronomemory 0.2.0 with all phases complete; Python 3.10–3.13 × Ubuntu + Windows all green; 1 607 tests passing.
-specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)
-and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed,
-every AI-generated output is disclosed, context windows are GPU-aware and protected against
-overflow, and compliance settings are configurable per-session and per-project.
+### Governance efficiency benchmark
+
+We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) comparing specsmith governance against 11 alternatives (ungoverned, BMAD, Cursor rules, Copilot, Aider, Cline, Codex CLI, OpenSpec, Agile BDD/TDD, and context injection) across real coding tasks with gpt-4o-mini and gpt-5.5.
+
+| Condition | Pass Rate | Mean Tokens | Cost/run | Cost-of-Pass |
+|---|---|---|---|---|
+| Ungoverned (raw agent) | 0% on T1 | 44.6k | $0.0079 | ∞ |
+| Context injection (CLAUDE.md) | 100% | 43.7k | $0.0084 | $0.0084 |
+| BMAD-style structured prompting | 50% | 139.1k | $0.0262 | $0.0523 |
+| **specsmith LIGHT (preflight)** | **100%** | **21.1k** | **$0.0032** | **$0.0032** |
+| **specsmith FULL (governed)** | **100%** | **17.1k** | **$0.0026** | **$0.0026** |
+
+**Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179).
+
+See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
+
+**v0.16.1** — governance efficiency benchmark suite (12 conditions, 3 tasks, gpt-4o-mini + gpt-5.5 comparison); cross-model comparison report; real OpenAI agent harness; CI matrix job. Also includes the v0.16.0 stabilisation milestone: 20+ CLI commands, ESDB SQLite backend, chronomemory 0.2.0, Python 3.10–3.13 × Ubuntu + Windows green, 1 607 tests passing.
+
+specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689) and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed, every AI-generated output is disclosed, context windows are GPU-aware, and compliance settings are configurable per-session and per-project.
+
+### Selected v0.16 CLI highlights
 
 ```bash
 specsmith governance-serve --port 7700     # governance REST API
-specsmith sync                              # sync YAML → JSON → MD (YAML-first mode)
-specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md from YAML
-specsmith validate --strict                 # YAML schema checks: dup IDs, orphans, coverage
-specsmith agent permissions-check git_push # check tool permission (REQ-012)
+specsmith sync                              # YAML → JSON → MD (YAML-first mode)
+specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md
+specsmith validate --strict                 # dup IDs, orphans, coverage gaps
+specsmith agent permissions-check git_push  # tool permission gate (REQ-012)
 specsmith ollama gpu                        # detect GPU VRAM, recommend context size
 specsmith export                            # generate full compliance report
 
-# Update channel management (REQ-248)
+# Update channels
 specsmith channel set stable               # pin to stable releases
-specsmith channel set dev                  # opt in to dev/pre-release builds
-specsmith channel get --json               # show current channel + source
+specsmith channel set dev                  # opt in to pre-release builds
 
-# ESDB extended lifecycle (REQ-249..253)
-specsmith esdb export --json               # dump all records to JSON snapshot
-specsmith esdb import backup.json          # validate + stage an import
+# ESDB lifecycle
+specsmith esdb export --json               # dump records to JSON snapshot
 specsmith esdb backup                      # create timestamped snapshot
-specsmith esdb rollback --steps 2          # report WAL rollback (stub)
-specsmith esdb compact                     # request WAL compaction
-
-# Skills lifecycle (REQ-254..255)
-specsmith skills deactivate <skill-id>     # set active=false in skill.json
-specsmith skills delete <skill-id> --yes   # permanently remove skill
+specsmith esdb compact                     # WAL compaction
 
-# MCP config generation (REQ-256)
-specsmith mcp generate "Search USPTO patents" --json  # JSON config stub
+# Skills
+specsmith skills deactivate <skill-id>     # set active=false
+specsmith skills delete <skill-id> --yes   # permanently remove
 
-# Agent ask dispatcher — no LLM required (REQ-257)
+# MCP + agent dispatch
+specsmith mcp generate "Search USPTO patents" --json
 specsmith agent ask "show esdb status" --json-output
-specsmith agent ask "build skill for summarizing"
 ```
 
 It also co-installs the standalone `epistemic` Python library for direct use in any project:
@@ -291,11 +301,11 @@ To obtain a chronomemory ESDB license:
 [licensing@layer1labs.com](mailto:licensing@layer1labs.com) · [layer1labs.com/esdb-licensing](https://layer1labs.com/esdb-licensing)
 See the [full ESDB docs](https://specsmith.readthedocs.io/en/stable/esdb/) for a feature comparison and Python API reference.
 
-**Update:**
+**Upgrading specsmith:**
 
 ```bash
-pipx upgrade specsmith
-specsmith self-update
+pipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI
+specsmith self-update    # alternative: self-update from within specsmith
 ```
 
 ---
@@ -303,36 +313,36 @@ specsmith self-update
 ## Quick Start
 
 ```bash
-# New project (interactive)
-specsmith init
+# 1. Install
+pipx install specsmith
 
-# Adopt an existing project
-specsmith import --project-dir ./my-project
+# 2. Start a new project (or import an existing one)
+specsmith init                           # interactive scaffold wizard
+specsmith import --project-dir ./my-project  # adopt an existing repo
 
-# Check governance health
-specsmith audit --project-dir ./my-project
+# 3. Bootstrap every session (run once at the start of each work session)
+specsmith migrate run                    # apply any pending schema migrations
+specsmith audit                          # verify governance health
+specsmith sync                           # YAML → JSON → MD sync
+specsmith checkpoint                     # emit GOVERNANCE ANCHOR
 
-# Run AEE stress-test on requirements
-specsmith stress-test --project-dir ./my-project
+# 4. Before every code change: preflight
+specsmith preflight "add paginated GET /todos endpoint"  # gate the intent
+# → decision: accepted | needs_clarification  +  work_item_id: WI-XXXXXXXX
 
-# Full epistemic audit (certainty + logic knots + recovery proposals)
-specsmith epistemic-audit --project-dir ./my-project
+# 5. After making changes: verify + save
+specsmith verify                         # check equilibrium
+specsmith save                           # commit governance state + push
 
-# Start the agentic REPL
-specsmith run --project-dir ./my-project
-
-# AG2 agent shell — Planner/Builder/Verifier over Ollama
-specsmith agent status                    # check agent config + Ollama
-specsmith agent plan "add logging"        # plan only (no execution)
-specsmith agent run "fix lint errors"     # full Plan → Build → Verify
-specsmith agent improve "add tests"       # self-improvement with reports
-specsmith agent verify                    # run Verifier on current state
-specsmith agent reports                   # list improvement reports
-
-# Check current AEE workflow phase
-specsmith phase --project-dir ./my-project
+# 6. Check AEE workflow phase and health
+specsmith phase                          # current phase + readiness %
+specsmith audit                          # full governance health check
 ```
 
+> **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.
+> Every utterance is preflighted automatically. Use `/why` to see the governance trace.
+> For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
+
 ---
 
 ## Machine State Sync + YAML Governance
@@ -377,7 +387,7 @@ be overwritten by the next sync.
 `scripts/migrate_governance_to_yaml.py` once to convert an existing project.
 Idempotent — safe to re-run.
 
-## Least-Privilege Agent Permissions (REG-012)
+## Least-Privilege Agent Permissions (REQ-012)
 
 ```bash
 specsmith agent permissions                      # show active permission profile
@@ -465,7 +475,7 @@ Every preflight response includes a mandatory `ai_disclosure` block:
     "governance_gated": true,
     "provider": "ollama",
     "model": "qwen2.5:14b",
-    "spec_version": "0.16.0"
+    "spec_version": "0.16.1"
   }
 }
 ```

{specsmith-0.16.0.dev593 → specsmith-0.16.1}/README.md

@@ -32,43 +32,53 @@ flowchart LR
 - **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.
 - **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.
 
-**v0.16.0 — stabilisation milestone:** 20+ new CLI commands (quickstart, expand, verify-integrations, governed-pr, transcript import, policy, recover, dashboard, drift-check, trace score, export/import, approve); new governance modules; ESDB SQLite backend with full test coverage; chronomemory 0.2.0 with all phases complete; Python 3.10–3.13 × Ubuntu + Windows all green; 1 607 tests passing.
-specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)
-and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed,
-every AI-generated output is disclosed, context windows are GPU-aware and protected against
-overflow, and compliance settings are configurable per-session and per-project.
+### Governance efficiency benchmark
+
+We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) comparing specsmith governance against 11 alternatives (ungoverned, BMAD, Cursor rules, Copilot, Aider, Cline, Codex CLI, OpenSpec, Agile BDD/TDD, and context injection) across real coding tasks with gpt-4o-mini and gpt-5.5.
+
+| Condition | Pass Rate | Mean Tokens | Cost/run | Cost-of-Pass |
+|---|---|---|---|---|
+| Ungoverned (raw agent) | 0% on T1 | 44.6k | $0.0079 | ∞ |
+| Context injection (CLAUDE.md) | 100% | 43.7k | $0.0084 | $0.0084 |
+| BMAD-style structured prompting | 50% | 139.1k | $0.0262 | $0.0523 |
+| **specsmith LIGHT (preflight)** | **100%** | **21.1k** | **$0.0032** | **$0.0032** |
+| **specsmith FULL (governed)** | **100%** | **17.1k** | **$0.0026** | **$0.0026** |
+
+**Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179).
+
+See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
+
+**v0.16.1** — governance efficiency benchmark suite (12 conditions, 3 tasks, gpt-4o-mini + gpt-5.5 comparison); cross-model comparison report; real OpenAI agent harness; CI matrix job. Also includes the v0.16.0 stabilisation milestone: 20+ CLI commands, ESDB SQLite backend, chronomemory 0.2.0, Python 3.10–3.13 × Ubuntu + Windows green, 1 607 tests passing.
+
+specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689) and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed, every AI-generated output is disclosed, context windows are GPU-aware, and compliance settings are configurable per-session and per-project.
+
+### Selected v0.16 CLI highlights
 
 ```bash
 specsmith governance-serve --port 7700     # governance REST API
-specsmith sync                              # sync YAML → JSON → MD (YAML-first mode)
-specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md from YAML
-specsmith validate --strict                 # YAML schema checks: dup IDs, orphans, coverage
-specsmith agent permissions-check git_push # check tool permission (REQ-012)
+specsmith sync                              # YAML → JSON → MD (YAML-first mode)
+specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md
+specsmith validate --strict                 # dup IDs, orphans, coverage gaps
+specsmith agent permissions-check git_push  # tool permission gate (REQ-012)
 specsmith ollama gpu                        # detect GPU VRAM, recommend context size
 specsmith export                            # generate full compliance report
 
-# Update channel management (REQ-248)
+# Update channels
 specsmith channel set stable               # pin to stable releases
-specsmith channel set dev                  # opt in to dev/pre-release builds
-specsmith channel get --json               # show current channel + source
+specsmith channel set dev                  # opt in to pre-release builds
 
-# ESDB extended lifecycle (REQ-249..253)
-specsmith esdb export --json               # dump all records to JSON snapshot
-specsmith esdb import backup.json          # validate + stage an import
+# ESDB lifecycle
+specsmith esdb export --json               # dump records to JSON snapshot
 specsmith esdb backup                      # create timestamped snapshot
-specsmith esdb rollback --steps 2          # report WAL rollback (stub)
-specsmith esdb compact                     # request WAL compaction
-
-# Skills lifecycle (REQ-254..255)
-specsmith skills deactivate <skill-id>     # set active=false in skill.json
-specsmith skills delete <skill-id> --yes   # permanently remove skill
+specsmith esdb compact                     # WAL compaction
 
-# MCP config generation (REQ-256)
-specsmith mcp generate "Search USPTO patents" --json  # JSON config stub
+# Skills
+specsmith skills deactivate <skill-id>     # set active=false
+specsmith skills delete <skill-id> --yes   # permanently remove
 
-# Agent ask dispatcher — no LLM required (REQ-257)
+# MCP + agent dispatch
+specsmith mcp generate "Search USPTO patents" --json
 specsmith agent ask "show esdb status" --json-output
-specsmith agent ask "build skill for summarizing"
 ```
 
 It also co-installs the standalone `epistemic` Python library for direct use in any project:
@@ -213,11 +223,11 @@ To obtain a chronomemory ESDB license:
 [licensing@layer1labs.com](mailto:licensing@layer1labs.com) · [layer1labs.com/esdb-licensing](https://layer1labs.com/esdb-licensing)
 See the [full ESDB docs](https://specsmith.readthedocs.io/en/stable/esdb/) for a feature comparison and Python API reference.
 
-**Update:**
+**Upgrading specsmith:**
 
 ```bash
-pipx upgrade specsmith
-specsmith self-update
+pipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI
+specsmith self-update    # alternative: self-update from within specsmith
 ```
 
 ---
@@ -225,36 +235,36 @@ specsmith self-update
 ## Quick Start
 
 ```bash
-# New project (interactive)
-specsmith init
+# 1. Install
+pipx install specsmith
 
-# Adopt an existing project
-specsmith import --project-dir ./my-project
+# 2. Start a new project (or import an existing one)
+specsmith init                           # interactive scaffold wizard
+specsmith import --project-dir ./my-project  # adopt an existing repo
 
-# Check governance health
-specsmith audit --project-dir ./my-project
+# 3. Bootstrap every session (run once at the start of each work session)
+specsmith migrate run                    # apply any pending schema migrations
+specsmith audit                          # verify governance health
+specsmith sync                           # YAML → JSON → MD sync
+specsmith checkpoint                     # emit GOVERNANCE ANCHOR
 
-# Run AEE stress-test on requirements
-specsmith stress-test --project-dir ./my-project
+# 4. Before every code change: preflight
+specsmith preflight "add paginated GET /todos endpoint"  # gate the intent
+# → decision: accepted | needs_clarification  +  work_item_id: WI-XXXXXXXX
 
-# Full epistemic audit (certainty + logic knots + recovery proposals)
-specsmith epistemic-audit --project-dir ./my-project
+# 5. After making changes: verify + save
+specsmith verify                         # check equilibrium
+specsmith save                           # commit governance state + push
 
-# Start the agentic REPL
-specsmith run --project-dir ./my-project
-
-# AG2 agent shell — Planner/Builder/Verifier over Ollama
-specsmith agent status                    # check agent config + Ollama
-specsmith agent plan "add logging"        # plan only (no execution)
-specsmith agent run "fix lint errors"     # full Plan → Build → Verify
-specsmith agent improve "add tests"       # self-improvement with reports
-specsmith agent verify                    # run Verifier on current state
-specsmith agent reports                   # list improvement reports
-
-# Check current AEE workflow phase
-specsmith phase --project-dir ./my-project
+# 6. Check AEE workflow phase and health
+specsmith phase                          # current phase + readiness %
+specsmith audit                          # full governance health check
 ```
 
+> **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.
+> Every utterance is preflighted automatically. Use `/why` to see the governance trace.
+> For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
+
 ---
 
 ## Machine State Sync + YAML Governance
@@ -299,7 +309,7 @@ be overwritten by the next sync.
 `scripts/migrate_governance_to_yaml.py` once to convert an existing project.
 Idempotent — safe to re-run.
 
-## Least-Privilege Agent Permissions (REG-012)
+## Least-Privilege Agent Permissions (REQ-012)
 
 ```bash
 specsmith agent permissions                      # show active permission profile
@@ -387,7 +397,7 @@ Every preflight response includes a mandatory `ai_disclosure` block:
     "governance_gated": true,
     "provider": "ollama",
     "model": "qwen2.5:14b",
-    "spec_version": "0.16.0"
+    "spec_version": "0.16.1"
   }
 }
 ```

{specsmith-0.16.0.dev593 → specsmith-0.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.16.0.dev593"
+version = "0.16.1"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

{specsmith-0.16.0.dev593 → specsmith-0.16.1}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.16.0"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.16.1"  # fallback: keep in sync with pyproject.toml

{specsmith-0.16.0.dev593 → specsmith-0.16.1/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.16.0.dev593
+Version: 0.16.1
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -110,43 +110,53 @@ flowchart LR
 - **Aider / Claude Code / Cursor:** agentic coding interfaces; SpecSmith is the policy and evidence layer around these clients.
 - **LangGraph / AutoGen:** orchestration frameworks; SpecSmith is a governance-first development layer with compliance-oriented traceability.
 
-**v0.16.0 — stabilisation milestone:** 20+ new CLI commands (quickstart, expand, verify-integrations, governed-pr, transcript import, policy, recover, dashboard, drift-check, trace score, export/import, approve); new governance modules; ESDB SQLite backend with full test coverage; chronomemory 0.2.0 with all phases complete; Python 3.10–3.13 × Ubuntu + Windows all green; 1 607 tests passing.
-specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689)
-and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed,
-every AI-generated output is disclosed, context windows are GPU-aware and protected against
-overflow, and compliance settings are configurable per-session and per-project.
+### Governance efficiency benchmark
+
+We ran a [multi-condition benchmark](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) comparing specsmith governance against 11 alternatives (ungoverned, BMAD, Cursor rules, Copilot, Aider, Cline, Codex CLI, OpenSpec, Agile BDD/TDD, and context injection) across real coding tasks with gpt-4o-mini and gpt-5.5.
+
+| Condition | Pass Rate | Mean Tokens | Cost/run | Cost-of-Pass |
+|---|---|---|---|---|
+| Ungoverned (raw agent) | 0% on T1 | 44.6k | $0.0079 | ∞ |
+| Context injection (CLAUDE.md) | 100% | 43.7k | $0.0084 | $0.0084 |
+| BMAD-style structured prompting | 50% | 139.1k | $0.0262 | $0.0523 |
+| **specsmith LIGHT (preflight)** | **100%** | **21.1k** | **$0.0032** | **$0.0032** |
+| **specsmith FULL (governed)** | **100%** | **17.1k** | **$0.0026** | **$0.0026** |
+
+**Key findings:** specsmith FULL is the only condition to achieve 100% pass rate on the feature-addition task (T1). It uses 2.6× fewer tokens than ungoverned and produces a cost-of-pass 3.2× lower than the next-best alternative. With gpt-5.5, governance reduces cost-of-pass by **6.3×** ($0.028 vs $0.179).
+
+See the [full benchmark report](https://specsmith.readthedocs.io/en/stable/efficiency-benchmark/) and [model comparison (gpt-4o-mini vs gpt-5.5)](https://specsmith.readthedocs.io/en/stable/model-comparison/).
+
+**v0.16.1** — governance efficiency benchmark suite (12 conditions, 3 tasks, gpt-4o-mini + gpt-5.5 comparison); cross-model comparison report; real OpenAI agent harness; CI matrix job. Also includes the v0.16.0 stabilisation milestone: 20+ CLI commands, ESDB SQLite backend, chronomemory 0.2.0, Python 3.10–3.13 × Ubuntu + Windows green, 1 607 tests passing.
+
+specsmith ships a full compliance and auditability layer aligned to the EU AI Act (2024/1689) and the NIST AI Risk Management Framework 1.0. Every agent action is cryptographically sealed, every AI-generated output is disclosed, context windows are GPU-aware, and compliance settings are configurable per-session and per-project.
+
+### Selected v0.16 CLI highlights
 
 ```bash
 specsmith governance-serve --port 7700     # governance REST API
-specsmith sync                              # sync YAML → JSON → MD (YAML-first mode)
-specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md from YAML
-specsmith validate --strict                 # YAML schema checks: dup IDs, orphans, coverage
-specsmith agent permissions-check git_push # check tool permission (REQ-012)
+specsmith sync                              # YAML → JSON → MD (YAML-first mode)
+specsmith generate docs                     # regenerate REQUIREMENTS.md + TESTS.md
+specsmith validate --strict                 # dup IDs, orphans, coverage gaps
+specsmith agent permissions-check git_push  # tool permission gate (REQ-012)
 specsmith ollama gpu                        # detect GPU VRAM, recommend context size
 specsmith export                            # generate full compliance report
 
-# Update channel management (REQ-248)
+# Update channels
 specsmith channel set stable               # pin to stable releases
-specsmith channel set dev                  # opt in to dev/pre-release builds
-specsmith channel get --json               # show current channel + source
+specsmith channel set dev                  # opt in to pre-release builds
 
-# ESDB extended lifecycle (REQ-249..253)
-specsmith esdb export --json               # dump all records to JSON snapshot
-specsmith esdb import backup.json          # validate + stage an import
+# ESDB lifecycle
+specsmith esdb export --json               # dump records to JSON snapshot
 specsmith esdb backup                      # create timestamped snapshot
-specsmith esdb rollback --steps 2          # report WAL rollback (stub)
-specsmith esdb compact                     # request WAL compaction
-
-# Skills lifecycle (REQ-254..255)
-specsmith skills deactivate <skill-id>     # set active=false in skill.json
-specsmith skills delete <skill-id> --yes   # permanently remove skill
+specsmith esdb compact                     # WAL compaction
 
-# MCP config generation (REQ-256)
-specsmith mcp generate "Search USPTO patents" --json  # JSON config stub
+# Skills
+specsmith skills deactivate <skill-id>     # set active=false
+specsmith skills delete <skill-id> --yes   # permanently remove
 
-# Agent ask dispatcher — no LLM required (REQ-257)
+# MCP + agent dispatch
+specsmith mcp generate "Search USPTO patents" --json
 specsmith agent ask "show esdb status" --json-output
-specsmith agent ask "build skill for summarizing"
 ```
 
 It also co-installs the standalone `epistemic` Python library for direct use in any project:
@@ -291,11 +301,11 @@ To obtain a chronomemory ESDB license:
 [licensing@layer1labs.com](mailto:licensing@layer1labs.com) · [layer1labs.com/esdb-licensing](https://layer1labs.com/esdb-licensing)
 See the [full ESDB docs](https://specsmith.readthedocs.io/en/stable/esdb/) for a feature comparison and Python API reference.
 
-**Update:**
+**Upgrading specsmith:**
 
 ```bash
-pipx upgrade specsmith
-specsmith self-update
+pipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI
+specsmith self-update    # alternative: self-update from within specsmith
 ```
 
 ---
@@ -303,36 +313,36 @@ specsmith self-update
 ## Quick Start
 
 ```bash
-# New project (interactive)
-specsmith init
+# 1. Install
+pipx install specsmith
 
-# Adopt an existing project
-specsmith import --project-dir ./my-project
+# 2. Start a new project (or import an existing one)
+specsmith init                           # interactive scaffold wizard
+specsmith import --project-dir ./my-project  # adopt an existing repo
 
-# Check governance health
-specsmith audit --project-dir ./my-project
+# 3. Bootstrap every session (run once at the start of each work session)
+specsmith migrate run                    # apply any pending schema migrations
+specsmith audit                          # verify governance health
+specsmith sync                           # YAML → JSON → MD sync
+specsmith checkpoint                     # emit GOVERNANCE ANCHOR
 
-# Run AEE stress-test on requirements
-specsmith stress-test --project-dir ./my-project
+# 4. Before every code change: preflight
+specsmith preflight "add paginated GET /todos endpoint"  # gate the intent
+# → decision: accepted | needs_clarification  +  work_item_id: WI-XXXXXXXX
 
-# Full epistemic audit (certainty + logic knots + recovery proposals)
-specsmith epistemic-audit --project-dir ./my-project
+# 5. After making changes: verify + save
+specsmith verify                         # check equilibrium
+specsmith save                           # commit governance state + push
 
-# Start the agentic REPL
-specsmith run --project-dir ./my-project
-
-# AG2 agent shell — Planner/Builder/Verifier over Ollama
-specsmith agent status                    # check agent config + Ollama
-specsmith agent plan "add logging"        # plan only (no execution)
-specsmith agent run "fix lint errors"     # full Plan → Build → Verify
-specsmith agent improve "add tests"       # self-improvement with reports
-specsmith agent verify                    # run Verifier on current state
-specsmith agent reports                   # list improvement reports
-
-# Check current AEE workflow phase
-specsmith phase --project-dir ./my-project
+# 6. Check AEE workflow phase and health
+specsmith phase                          # current phase + readiness %
+specsmith audit                          # full governance health check
 ```
 
+> **Agentic REPL:** run `specsmith run` to start the Nexus governance-gated LLM REPL.
+> Every utterance is preflighted automatically. Use `/why` to see the governance trace.
+> For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
+
 ---
 
 ## Machine State Sync + YAML Governance
@@ -377,7 +387,7 @@ be overwritten by the next sync.
 `scripts/migrate_governance_to_yaml.py` once to convert an existing project.
 Idempotent — safe to re-run.
 
-## Least-Privilege Agent Permissions (REG-012)
+## Least-Privilege Agent Permissions (REQ-012)
 
 ```bash
 specsmith agent permissions                      # show active permission profile
@@ -465,7 +475,7 @@ Every preflight response includes a mandatory `ai_disclosure` block:
     "governance_gated": true,
     "provider": "ollama",
     "model": "qwen2.5:14b",
-    "spec_version": "0.16.0"
+    "spec_version": "0.16.1"
   }
 }
 ```