codeframe-ai 0.9.3__tar.gz → 0.9.5__tar.gz

{codeframe_ai-0.9.3/codeframe_ai.egg-info → codeframe_ai-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeframe-ai
-Version: 0.9.3
+Version: 0.9.5
 Summary: A project delivery system that orchestrates frontier coding agents: Think, Build, Prove, Ship.
 Author-email: Frank Bria <hello@codeframe.sh>
 License: AGPL-3.0-or-later
@@ -17,10 +17,10 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: anthropic<1.0,>=0.18.0
+Requires-Dist: anthropic<2,>=1.0
 Requires-Dist: bandit>=1.8.6
 Requires-Dist: tenacity>=8.2.0
-Requires-Dist: openai>=1.12.0
+Requires-Dist: openai<3,>=1.12.0
 Requires-Dist: fastapi>=0.109.0
 Requires-Dist: uvicorn[standard]>=0.27.0
 Requires-Dist: websockets>=12.0
@@ -30,12 +30,13 @@ Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: aiosqlite>=0.19.0
 Requires-Dist: aiohttp>=3.14.0
+Requires-Dist: yarl<2,>=1.22
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: typer>=0.9.0
+Requires-Dist: typer<0.28,>=0.27
 Requires-Dist: rich>=13.7.0
 Requires-Dist: textual>=0.86.0
 Requires-Dist: requests>=2.33.0
-Requires-Dist: gitpython>=3.1.50
+Requires-Dist: gitpython<4,>=3.1.60
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: tree-sitter>=0.20.4
 Requires-Dist: tree-sitter-python>=0.20.4
@@ -43,9 +44,9 @@ Requires-Dist: tree-sitter-javascript>=0.20.3
 Requires-Dist: tree-sitter-typescript>=0.20.3
 Requires-Dist: tiktoken>=0.12.0
 Requires-Dist: radon>=6.0.1
-Requires-Dist: pytest>=8.4.2
+Requires-Dist: pytest<10,>=9.0.3
 Requires-Dist: ruff>=0.14.0
-Requires-Dist: pytest-asyncio>=1.2.0
+Requires-Dist: pytest-asyncio>=1.4.0
 Requires-Dist: pytest-json-report>=1.5.0
 Requires-Dist: hypothesis>=6.148.0
 Requires-Dist: fastapi-users[sqlalchemy]>=15.0.2
@@ -57,16 +58,18 @@ Requires-Dist: slowapi>=0.1.9
 Requires-Dist: rapidfuzz>=3.0.0
 Requires-Dist: starlette>=1.0.1
 Requires-Dist: python-multipart>=0.0.27
-Requires-Dist: pyjwt>=2.12.0
+Requires-Dist: pyjwt>=2.15.0
 Requires-Dist: cryptography>=46.0.7
-Requires-Dist: urllib3>=2.7.0
+Requires-Dist: urllib3>=2.8.0
 Requires-Dist: mcp>=1.23.0
 Requires-Dist: idna>=3.15
 Provides-Extra: cloud
 Requires-Dist: e2b>=2.0.0; extra == "cloud"
+Provides-Extra: redis
+Requires-Dist: limits[redis]; extra == "redis"
 Provides-Extra: dev
-Requires-Dist: pytest>=8.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: pytest-json-report>=1.5.0; extra == "dev"
 Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
@@ -77,6 +80,7 @@ Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: e2b>=2.0.0; extra == "dev"
 Requires-Dist: jsonschema>=4.0.0; extra == "dev"
+Requires-Dist: limits[redis]; extra == "dev"
 Dynamic: license-file
 
 ![CodeFRAME Header](./codeframe_github_header_1600x500.png)
@@ -117,7 +121,7 @@ THINK    What are you building? How should it be broken down?
            cf tasks generate       Atomic tasks with dependency graphs
 
 BUILD    Delegate to the best coding agent for the job
-           cf work start --engine  Claude Code, Codex, OpenCode, Kilocode, or built-in
+           cf work start <task> --engine  Claude Code, Codex, OpenCode, Kilocode, or built-in
            CodeFRAME owns: verification gates, self-correction, stall detection
 
 PROVE    Is the output any good?
@@ -130,7 +134,7 @@ PROVE    Is the output any good?
 
 SHIP     Deploy with confidence
            cf pr create            PR with proof report attached
-           cf pr merge             Only merges if proof passes
+           cf pr merge <number>    Only merges if proof passes
 
 THE CLOSED LOOP
   Glitch in production
@@ -155,7 +159,7 @@ THE CLOSED LOOP
 ---
 
 > [!NOTE]
-> **CodeFRAME is in public beta (`0.9.3`).** The vision and the Golden Path CLI
+> **CodeFRAME is in public beta (`0.9.5`).** The vision and the Golden Path CLI
 > (`cf init/prd/tasks/work/proof/pr`) and v2 API are stable enough to build on;
 > the web UI and anything marked "in progress" in
 > [`docs/PRODUCT_ROADMAP.md`](docs/PRODUCT_ROADMAP.md) are still moving, and
@@ -191,6 +195,7 @@ When working from source, prefix the commands below with `uv run`.
 
 ```bash
 export ANTHROPIC_API_KEY="sk-ant-..."   # get yours at https://console.anthropic.com/
+# or store it once instead: cf auth setup --provider anthropic
 ```
 
 **Step 3 — Initialize your project**
@@ -207,28 +212,111 @@ cf tasks generate        # Decompose PRD into atomic tasks with dependencies
 cf tasks list            # Review what was generated
 ```
 
-**Step 5 — Promote the tasks you want to run**
+**Step 5 — Promote one task**
 
 `cf tasks generate` creates tasks in `BACKLOG` so you can review them before an
-agent touches your code. Move the ones you approve to `READY`:
+agent touches your code. Pick one and move it to `READY` — `cf tasks list` prints
+an 8-character ID for each task, and that prefix is all you need:
 
 ```bash
-cf tasks set status READY --all --from BACKLOG   # every BACKLOG task
-cf tasks set status <task-id> READY              # one task (note: id before status)
+cf tasks list                            # copy the ID of the task you want
+cf tasks set status <task-id> READY      # note: id before status
+```
+
+Start with one. A generated backlog is typically 20+ tasks, and your first run
+should show you the loop, not build the whole project in one sitting.
+
+**Step 6 — Build: hand the task to an agent**
+
+```bash
+cf work start <task-id> --execute
+```
+
+**Step 7 — Prove: capture a requirement, then verify it**
+
+PROOF9 verifies *obligations*, and a new workspace has none — so verifying it
+first would report that nothing was checked and exit `2`. That is deliberate: a
+run that checked nothing is not a pass. Give it something to check.
+
+```bash
+cf proof capture \
+  --title "add() returns the wrong sum for negative numbers" \
+  --description "Calculation is wrong: add(-1, -1) returned 0 instead of -2" \
+  --where src/calc.py --severity high --source qa
+```
+
+That creates a requirement, picks the gates that would have caught it, and
+writes a **draft** test stub per gate under `tests/proof/<REQ-ID>/`. The stubs
+are named `draft_*.py` so pytest does not collect them yet, and each one is a
+placeholder `assert False`. Turn them into real tests — drop the `draft_`
+prefix from each filename, and replace the placeholder with an assertion that
+actually proves the bug is fixed:
+
+```bash
+ls tests/proof/REQ-0001/          # draft_test_..._unit.py, draft_test_..._contract.py
+# rename each to test_*.py and write the real assertion
+```
+
+Now the gates have evidence to collect:
+
+```bash
+cf proof run --full               # -> All obligations satisfied. (exit 0)
 ```
 
-Skipping this step is why `--all-ready` below would otherwise report
-`No READY tasks found` and do nothing.
+`--full` checks every open requirement; plain `cf proof run` checks only the
+ones your current diff touches. The `unit` and `contract` gates run **your
+project's** pytest, so the project needs pytest available (`uv add --dev
+pytest`) — a gate with no way to run is reported as unverified, never as a pass.
+
+This is the loop that compounds: every glitch you capture stays a permanent
+check, and `cf pr merge` refuses to merge while any of them is open.
+
+**Step 8 — Ship**
+
+`cf pr` talks to GitHub, so it needs a token and the repository: connect them in
+the web UI (Settings → Integrations), or export `GITHUB_TOKEN` (a PAT with
+`repo` scope) and `GITHUB_REPO=owner/repo`.
+
+```bash
+cf pr create                        # Open a PR with proof report attached
+```
+
+The title defaults to the branch's newest commit (`--title` overrides it), and
+the body ends with the workspace's PROOF9 status: requirement counts, the open
+ones by name, and the latest `cf proof run` verdict.
+
+That is the entire workflow. An empty directory through a green `cf proof run`
+is **5m59s** of wall clock on a clean machine — measured, not estimated, in
+[this walkthrough](docs/demos/quickstart-cleanroom.md) — most of it in
+`cf prd generate` and the agent run; Step 7 costs 7 seconds of it. `cf pr create`
+needs a GitHub remote, so it is outside that measurement.
 
-**Step 6 — Build, Prove, and Ship**
+If the agent needs a decision it cannot make, it stops and files a blocker
+rather than guessing — `cf blocker list` shows it and `cf blocker answer <id>
+"..."` unblocks the task.
+
+<details>
+<summary>Running the whole backlog</summary>
+
+Once you trust the loop, promote everything and let it run:
 
 ```bash
-cf work batch run --all-ready   # Execute all READY tasks (delegates to agent)
-cf proof run                    # Run PROOF9 quality gates
-cf pr create                    # Open a PR with proof report attached
+cf tasks set status READY --all --from BACKLOG   # every BACKLOG task
+cf work batch run --all-ready                    # execute them
 ```
 
-That is the entire workflow. Everything else is optional.
+This is **long-running** — each task is a full agent run, and serial is the
+default strategy — so start it and watch it from another terminal rather than
+waiting on the prompt:
+
+```bash
+cf work batch status              # lists recent batches and their IDs
+cf work batch follow <batch-id>   # live progress for one of them
+```
+
+`--strategy parallel --max-parallel 4` and `--retry 2` are worth knowing about
+before you kick off a large batch; see [`docs/QUICKSTART.md`](docs/QUICKSTART.md).
+</details>
 
 > **See it run from scratch.** [Cold start on a clean machine](docs/demos/quickstart-cleanroom.md)
 > is a narrated walkthrough of exactly these steps in a throwaway container —
@@ -250,7 +338,7 @@ That is the entire workflow. Everything else is optional.
                                |
                                v
   +-BUILD---------------------------------------------+
-  |  cf work start --engine <agent>                    |
+  |  cf work start <task> --engine <agent>             |
   |                                                    |
   |  +-- Claude Code / Codex / OpenCode / Kilocode / ReAct        |
   |  |                                                 |
@@ -268,7 +356,7 @@ That is the entire workflow. Everything else is optional.
                                v
   +-SHIP----------------------------------------------+
   |  cf pr create       PR with proof report           |
-  |  cf pr merge        Merge if proof passes          |
+  |  cf pr merge <n>    Merge if proof passes          |
   +---------------------------------------------------+
                                |
             Glitch in production?
@@ -297,6 +385,7 @@ cf status                             # Workspace status
 # Requirements
 cf prd generate                       # AI-guided Socratic PRD creation
 cf prd generate --template lean       # Use a specific template
+cf prd generate --max-questions 6     # Cap discovery (default 10; /done finishes early)
 cf prd add <file.md>                  # Import existing PRD
 cf prd show                           # Display current PRD
 
@@ -347,7 +436,7 @@ cf blocker show <id>                  # Blocker details
 cf blocker answer <id> "answer"       # Unblock the agent
 
 # Diagnostics
-cf work diagnose <id>                 # AI-powered failure analysis
+cf work diagnose <id>                 # Pattern-based failure analysis
 cf env check                          # Validate environment
 cf env doctor                         # Comprehensive health check
 ```
@@ -382,23 +471,23 @@ resolved by waiving it with a justification.
 cf review                             # Run verification gates
 cf checkpoint create "milestone"      # Snapshot project state
 cf checkpoint list                    # List checkpoints
-cf checkpoint restore <id>            # Roll back to checkpoint
+cf checkpoint restore <id>            # Restore task statuses (files untouched)
 
 # Debugging
-cf work replay <id>                   # Replay and debug a past execution
+cf work replay <run-id>               # Replay and debug a past run (built-in react engine)
 cf dashboard                          # Launch TUI dashboard
 ```
 
 ### SHIP -- Delivery
 
 ```bash
-cf pr create                          # Create PR from current branch
+cf pr create --title "Add search"     # PR from the current branch, PROOF9 report appended
 cf pr list                            # List open PRs
 cf pr status                          # PR status, review state and CI checks
 cf pr get <number>                    # Details for one PR
-cf pr merge                           # Merge approved PR
+cf pr merge <number>                  # Merge it (refused while a requirement is open)
 cf pr close <number>                  # Close a PR without merging
-cf commit                             # Commit verified changes
+cf commit create -m "feat: search"    # Commit verified changes
 cf patch export                       # Export changes as patch
 ```
 
@@ -409,7 +498,7 @@ cf patch export                       # Export changes as patch
 CodeFRAME delivers the full Think-Build-Prove-Ship loop from the CLI and browser:
 
 - **THINK**: Socratic PRD generation with recursive stress-testing, LLM-powered task decomposition with dependency graphs, 5 PRD templates, 7 task templates, CPM-based scheduling
-- **BUILD**: ReAct agent with 7 tools, self-correction with loop prevention, verification gates (ruff/pytest/BUILD), stall detection with configurable recovery (retry/blocker/fail), batch execution (serial/parallel/auto), human-in-the-loop blockers, checkpointing, state persistence, replay/debug mode (`cf work replay`), dynamic config reload, TUI dashboard (`cf dashboard`)
+- **BUILD**: ReAct agent with 7 tools, self-correction with loop prevention, verification gates (ruff/pytest/BUILD), stall detection with configurable recovery (retry/blocker/fail), batch execution (serial/parallel/auto), human-in-the-loop blockers, checkpointing, state persistence, replay/debug mode for built-in react runs (`cf work replay`), dynamic config reload, TUI dashboard (`cf dashboard`)
 - **PROVE**: PROOF9 quality memory system — 9-gate evidence-based verification (`cf proof run/capture/list/status/show/waive`), every glitch becomes a permanent proof obligation
 - **SHIP**: GitHub PR workflow, environment validation, task self-diagnosis
 - **Engine adapters**: Claude Code, Codex, OpenCode, Kilocode, and built-in ReAct — all via `--engine` flag
@@ -431,7 +520,7 @@ CodeFRAME delivers the full Think-Build-Prove-Ship loop from the CLI and browser
 - [x] Agent adapter architecture -- delegate to Claude Code, Codex, OpenCode, Kilocode via workspace hooks
 - [x] Worktree isolation for parallel agent execution
 - [x] Reconciliation layer for multi-agent output
-- [x] Replay/debug mode (`cf work replay`)
+- [x] Replay/debug mode (`cf work replay`, built-in react engine)
 - [x] TUI dashboard (`cf dashboard`)
 - [x] Dynamic config reload during batch execution
 - [x] Multi-provider LLM -- Anthropic, OpenAI, or any OpenAI-compatible endpoint
@@ -477,7 +566,7 @@ export OPENAI_BASE_URL=http://localhost:11434/v1  # for Ollama, vLLM, LM Studio,
 # Per-workspace: .codeframe/config.yaml supports an `llm:` block for the same options
 
 # Optional
-export DATABASE_PATH=./codeframe.db         # Default: ./.codeframe/state.db
+export DATABASE_PATH=./codeframe.db         # Server accounts/keys; default ./.codeframe/platform.db
 export RATE_LIMIT_ENABLED=true              # API rate limiting
 export RATE_LIMIT_DEFAULT=100/minute        # Default limit
 ```
@@ -545,7 +634,7 @@ CodeFRAME is in **public beta**.
 - **Security:** found a vulnerability? Report it privately via [GitHub private vulnerability reporting](https://github.com/frankbria/codeframe/security/advisories/new) (or `security@codeframe.sh`) -- never a public issue. See [SECURITY.md](SECURITY.md) for scope and response expectations.
 - **Licensing:** CodeFRAME is [AGPL-3.0](LICENSE), an open-core stance. [LICENSING.md](LICENSING.md) explains what that means for individuals, internal company use, and embedding -- and how to reach us about **commercial licensing or a hosted offering** (both planned). Commercial inquiries: `licensing@codeframe.sh`.
 - **Trademark:** the code is AGPL-3.0, but the **CodeFRAME name and logo are trademarks** and are *not* covered by the code license. See [TRADEMARKS.md](TRADEMARKS.md) before using the name for a fork or product.
-- **Early access / design partners:** email `hello@codeframe.sh` or reply to the pinned [Discussion](https://github.com/frankbria/codeframe/discussions) to be included.
+- **Early access / design partners:** we are recruiting 5-10 teams for the beta design-partner cohort -- see [DESIGN_PARTNERS.md](DESIGN_PARTNERS.md) for what partners get and commit. To be included, email `hello@codeframe.sh` or reply to the pinned [Discussion](https://github.com/frankbria/codeframe/discussions).
 - **Help & community:** [Discussions -> Q&A](https://github.com/frankbria/codeframe/discussions/categories/q-a) for questions, [Ideas](https://github.com/frankbria/codeframe/discussions/categories/ideas) for feature requests, and [bug reports](https://github.com/frankbria/codeframe/issues/new/choose) for confirmed bugs.
 
 ---

{codeframe_ai-0.9.3 → codeframe_ai-0.9.5}/README.md

@@ -36,7 +36,7 @@ THINK    What are you building? How should it be broken down?
            cf tasks generate       Atomic tasks with dependency graphs
 
 BUILD    Delegate to the best coding agent for the job
-           cf work start --engine  Claude Code, Codex, OpenCode, Kilocode, or built-in
+           cf work start <task> --engine  Claude Code, Codex, OpenCode, Kilocode, or built-in
            CodeFRAME owns: verification gates, self-correction, stall detection
 
 PROVE    Is the output any good?
@@ -49,7 +49,7 @@ PROVE    Is the output any good?
 
 SHIP     Deploy with confidence
            cf pr create            PR with proof report attached
-           cf pr merge             Only merges if proof passes
+           cf pr merge <number>    Only merges if proof passes
 
 THE CLOSED LOOP
   Glitch in production
@@ -74,7 +74,7 @@ THE CLOSED LOOP
 ---
 
 > [!NOTE]
-> **CodeFRAME is in public beta (`0.9.3`).** The vision and the Golden Path CLI
+> **CodeFRAME is in public beta (`0.9.5`).** The vision and the Golden Path CLI
 > (`cf init/prd/tasks/work/proof/pr`) and v2 API are stable enough to build on;
 > the web UI and anything marked "in progress" in
 > [`docs/PRODUCT_ROADMAP.md`](docs/PRODUCT_ROADMAP.md) are still moving, and
@@ -110,6 +110,7 @@ When working from source, prefix the commands below with `uv run`.
 
 ```bash
 export ANTHROPIC_API_KEY="sk-ant-..."   # get yours at https://console.anthropic.com/
+# or store it once instead: cf auth setup --provider anthropic
 ```
 
 **Step 3 — Initialize your project**
@@ -126,28 +127,111 @@ cf tasks generate        # Decompose PRD into atomic tasks with dependencies
 cf tasks list            # Review what was generated
 ```
 
-**Step 5 — Promote the tasks you want to run**
+**Step 5 — Promote one task**
 
 `cf tasks generate` creates tasks in `BACKLOG` so you can review them before an
-agent touches your code. Move the ones you approve to `READY`:
+agent touches your code. Pick one and move it to `READY` — `cf tasks list` prints
+an 8-character ID for each task, and that prefix is all you need:
 
 ```bash
-cf tasks set status READY --all --from BACKLOG   # every BACKLOG task
-cf tasks set status <task-id> READY              # one task (note: id before status)
+cf tasks list                            # copy the ID of the task you want
+cf tasks set status <task-id> READY      # note: id before status
+```
+
+Start with one. A generated backlog is typically 20+ tasks, and your first run
+should show you the loop, not build the whole project in one sitting.
+
+**Step 6 — Build: hand the task to an agent**
+
+```bash
+cf work start <task-id> --execute
+```
+
+**Step 7 — Prove: capture a requirement, then verify it**
+
+PROOF9 verifies *obligations*, and a new workspace has none — so verifying it
+first would report that nothing was checked and exit `2`. That is deliberate: a
+run that checked nothing is not a pass. Give it something to check.
+
+```bash
+cf proof capture \
+  --title "add() returns the wrong sum for negative numbers" \
+  --description "Calculation is wrong: add(-1, -1) returned 0 instead of -2" \
+  --where src/calc.py --severity high --source qa
+```
+
+That creates a requirement, picks the gates that would have caught it, and
+writes a **draft** test stub per gate under `tests/proof/<REQ-ID>/`. The stubs
+are named `draft_*.py` so pytest does not collect them yet, and each one is a
+placeholder `assert False`. Turn them into real tests — drop the `draft_`
+prefix from each filename, and replace the placeholder with an assertion that
+actually proves the bug is fixed:
+
+```bash
+ls tests/proof/REQ-0001/          # draft_test_..._unit.py, draft_test_..._contract.py
+# rename each to test_*.py and write the real assertion
+```
+
+Now the gates have evidence to collect:
+
+```bash
+cf proof run --full               # -> All obligations satisfied. (exit 0)
 ```
 
-Skipping this step is why `--all-ready` below would otherwise report
-`No READY tasks found` and do nothing.
+`--full` checks every open requirement; plain `cf proof run` checks only the
+ones your current diff touches. The `unit` and `contract` gates run **your
+project's** pytest, so the project needs pytest available (`uv add --dev
+pytest`) — a gate with no way to run is reported as unverified, never as a pass.
+
+This is the loop that compounds: every glitch you capture stays a permanent
+check, and `cf pr merge` refuses to merge while any of them is open.
+
+**Step 8 — Ship**
+
+`cf pr` talks to GitHub, so it needs a token and the repository: connect them in
+the web UI (Settings → Integrations), or export `GITHUB_TOKEN` (a PAT with
+`repo` scope) and `GITHUB_REPO=owner/repo`.
+
+```bash
+cf pr create                        # Open a PR with proof report attached
+```
+
+The title defaults to the branch's newest commit (`--title` overrides it), and
+the body ends with the workspace's PROOF9 status: requirement counts, the open
+ones by name, and the latest `cf proof run` verdict.
+
+That is the entire workflow. An empty directory through a green `cf proof run`
+is **5m59s** of wall clock on a clean machine — measured, not estimated, in
+[this walkthrough](docs/demos/quickstart-cleanroom.md) — most of it in
+`cf prd generate` and the agent run; Step 7 costs 7 seconds of it. `cf pr create`
+needs a GitHub remote, so it is outside that measurement.
 
-**Step 6 — Build, Prove, and Ship**
+If the agent needs a decision it cannot make, it stops and files a blocker
+rather than guessing — `cf blocker list` shows it and `cf blocker answer <id>
+"..."` unblocks the task.
+
+<details>
+<summary>Running the whole backlog</summary>
+
+Once you trust the loop, promote everything and let it run:
 
 ```bash
-cf work batch run --all-ready   # Execute all READY tasks (delegates to agent)
-cf proof run                    # Run PROOF9 quality gates
-cf pr create                    # Open a PR with proof report attached
+cf tasks set status READY --all --from BACKLOG   # every BACKLOG task
+cf work batch run --all-ready                    # execute them
 ```
 
-That is the entire workflow. Everything else is optional.
+This is **long-running** — each task is a full agent run, and serial is the
+default strategy — so start it and watch it from another terminal rather than
+waiting on the prompt:
+
+```bash
+cf work batch status              # lists recent batches and their IDs
+cf work batch follow <batch-id>   # live progress for one of them
+```
+
+`--strategy parallel --max-parallel 4` and `--retry 2` are worth knowing about
+before you kick off a large batch; see [`docs/QUICKSTART.md`](docs/QUICKSTART.md).
+</details>
 
 > **See it run from scratch.** [Cold start on a clean machine](docs/demos/quickstart-cleanroom.md)
 > is a narrated walkthrough of exactly these steps in a throwaway container —
@@ -169,7 +253,7 @@ That is the entire workflow. Everything else is optional.
                                |
                                v
   +-BUILD---------------------------------------------+
-  |  cf work start --engine <agent>                    |
+  |  cf work start <task> --engine <agent>             |
   |                                                    |
   |  +-- Claude Code / Codex / OpenCode / Kilocode / ReAct        |
   |  |                                                 |
@@ -187,7 +271,7 @@ That is the entire workflow. Everything else is optional.
                                v
   +-SHIP----------------------------------------------+
   |  cf pr create       PR with proof report           |
-  |  cf pr merge        Merge if proof passes          |
+  |  cf pr merge <n>    Merge if proof passes          |
   +---------------------------------------------------+
                                |
             Glitch in production?
@@ -216,6 +300,7 @@ cf status                             # Workspace status
 # Requirements
 cf prd generate                       # AI-guided Socratic PRD creation
 cf prd generate --template lean       # Use a specific template
+cf prd generate --max-questions 6     # Cap discovery (default 10; /done finishes early)
 cf prd add <file.md>                  # Import existing PRD
 cf prd show                           # Display current PRD
 
@@ -266,7 +351,7 @@ cf blocker show <id>                  # Blocker details
 cf blocker answer <id> "answer"       # Unblock the agent
 
 # Diagnostics
-cf work diagnose <id>                 # AI-powered failure analysis
+cf work diagnose <id>                 # Pattern-based failure analysis
 cf env check                          # Validate environment
 cf env doctor                         # Comprehensive health check
 ```
@@ -301,23 +386,23 @@ resolved by waiving it with a justification.
 cf review                             # Run verification gates
 cf checkpoint create "milestone"      # Snapshot project state
 cf checkpoint list                    # List checkpoints
-cf checkpoint restore <id>            # Roll back to checkpoint
+cf checkpoint restore <id>            # Restore task statuses (files untouched)
 
 # Debugging
-cf work replay <id>                   # Replay and debug a past execution
+cf work replay <run-id>               # Replay and debug a past run (built-in react engine)
 cf dashboard                          # Launch TUI dashboard
 ```
 
 ### SHIP -- Delivery
 
 ```bash
-cf pr create                          # Create PR from current branch
+cf pr create --title "Add search"     # PR from the current branch, PROOF9 report appended
 cf pr list                            # List open PRs
 cf pr status                          # PR status, review state and CI checks
 cf pr get <number>                    # Details for one PR
-cf pr merge                           # Merge approved PR
+cf pr merge <number>                  # Merge it (refused while a requirement is open)
 cf pr close <number>                  # Close a PR without merging
-cf commit                             # Commit verified changes
+cf commit create -m "feat: search"    # Commit verified changes
 cf patch export                       # Export changes as patch
 ```
 
@@ -328,7 +413,7 @@ cf patch export                       # Export changes as patch
 CodeFRAME delivers the full Think-Build-Prove-Ship loop from the CLI and browser:
 
 - **THINK**: Socratic PRD generation with recursive stress-testing, LLM-powered task decomposition with dependency graphs, 5 PRD templates, 7 task templates, CPM-based scheduling
-- **BUILD**: ReAct agent with 7 tools, self-correction with loop prevention, verification gates (ruff/pytest/BUILD), stall detection with configurable recovery (retry/blocker/fail), batch execution (serial/parallel/auto), human-in-the-loop blockers, checkpointing, state persistence, replay/debug mode (`cf work replay`), dynamic config reload, TUI dashboard (`cf dashboard`)
+- **BUILD**: ReAct agent with 7 tools, self-correction with loop prevention, verification gates (ruff/pytest/BUILD), stall detection with configurable recovery (retry/blocker/fail), batch execution (serial/parallel/auto), human-in-the-loop blockers, checkpointing, state persistence, replay/debug mode for built-in react runs (`cf work replay`), dynamic config reload, TUI dashboard (`cf dashboard`)
 - **PROVE**: PROOF9 quality memory system — 9-gate evidence-based verification (`cf proof run/capture/list/status/show/waive`), every glitch becomes a permanent proof obligation
 - **SHIP**: GitHub PR workflow, environment validation, task self-diagnosis
 - **Engine adapters**: Claude Code, Codex, OpenCode, Kilocode, and built-in ReAct — all via `--engine` flag
@@ -350,7 +435,7 @@ CodeFRAME delivers the full Think-Build-Prove-Ship loop from the CLI and browser
 - [x] Agent adapter architecture -- delegate to Claude Code, Codex, OpenCode, Kilocode via workspace hooks
 - [x] Worktree isolation for parallel agent execution
 - [x] Reconciliation layer for multi-agent output
-- [x] Replay/debug mode (`cf work replay`)
+- [x] Replay/debug mode (`cf work replay`, built-in react engine)
 - [x] TUI dashboard (`cf dashboard`)
 - [x] Dynamic config reload during batch execution
 - [x] Multi-provider LLM -- Anthropic, OpenAI, or any OpenAI-compatible endpoint
@@ -396,7 +481,7 @@ export OPENAI_BASE_URL=http://localhost:11434/v1  # for Ollama, vLLM, LM Studio,
 # Per-workspace: .codeframe/config.yaml supports an `llm:` block for the same options
 
 # Optional
-export DATABASE_PATH=./codeframe.db         # Default: ./.codeframe/state.db
+export DATABASE_PATH=./codeframe.db         # Server accounts/keys; default ./.codeframe/platform.db
 export RATE_LIMIT_ENABLED=true              # API rate limiting
 export RATE_LIMIT_DEFAULT=100/minute        # Default limit
 ```
@@ -464,7 +549,7 @@ CodeFRAME is in **public beta**.
 - **Security:** found a vulnerability? Report it privately via [GitHub private vulnerability reporting](https://github.com/frankbria/codeframe/security/advisories/new) (or `security@codeframe.sh`) -- never a public issue. See [SECURITY.md](SECURITY.md) for scope and response expectations.
 - **Licensing:** CodeFRAME is [AGPL-3.0](LICENSE), an open-core stance. [LICENSING.md](LICENSING.md) explains what that means for individuals, internal company use, and embedding -- and how to reach us about **commercial licensing or a hosted offering** (both planned). Commercial inquiries: `licensing@codeframe.sh`.
 - **Trademark:** the code is AGPL-3.0, but the **CodeFRAME name and logo are trademarks** and are *not* covered by the code license. See [TRADEMARKS.md](TRADEMARKS.md) before using the name for a fork or product.
-- **Early access / design partners:** email `hello@codeframe.sh` or reply to the pinned [Discussion](https://github.com/frankbria/codeframe/discussions) to be included.
+- **Early access / design partners:** we are recruiting 5-10 teams for the beta design-partner cohort -- see [DESIGN_PARTNERS.md](DESIGN_PARTNERS.md) for what partners get and commit. To be included, email `hello@codeframe.sh` or reply to the pinned [Discussion](https://github.com/frankbria/codeframe/discussions).
 - **Help & community:** [Discussions -> Q&A](https://github.com/frankbria/codeframe/discussions/categories/q-a) for questions, [Ideas](https://github.com/frankbria/codeframe/discussions/categories/ideas) for feature requests, and [bug reports](https://github.com/frankbria/codeframe/issues/new/choose) for confirmed bugs.
 
 ---