rote-cli 0.13.0__tar.gz → 0.15.0__tar.gz

{rote_cli-0.13.0 → rote_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rote-cli
-Version: 0.13.0
+Version: 0.15.0
 Summary: Compile AI agent skills into cheap, fast, deterministic pipelines that run without an LLM in the loop
 Project-URL: Homepage, https://roteskills.com
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -25,30 +25,31 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: pydantic>=2.7
+Requires-Dist: pytest<10,>=9.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: api
-Requires-Dist: anthropic>=0.89; extra == 'api'
+Requires-Dist: anthropic>=1.15; extra == 'api'
 Provides-Extra: dbos
-Requires-Dist: dbos>=2.26; extra == 'dbos'
+Requires-Dist: dbos<4,>=3.3; extra == 'dbos'
 Provides-Extra: dev
-Requires-Dist: anthropic>=0.89; extra == 'dev'
-Requires-Dist: dbos>=2.26; extra == 'dev'
-Requires-Dist: fastmcp>=3.4.2; extra == 'dev'
+Requires-Dist: anthropic>=1.15; extra == 'dev'
+Requires-Dist: dbos<4,>=3.3; extra == 'dev'
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'dev'
 Requires-Dist: httpx>=0.28; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: openai>=2.45; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: temporalio>=1.7; extra == 'dev'
+Requires-Dist: trustme>=1.2.1; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'mcp'
 Requires-Dist: httpx>=0.28; extra == 'mcp'
 Provides-Extra: openai-api
 Requires-Dist: openai>=2.45; extra == 'openai-api'
 Provides-Extra: serve
-Requires-Dist: fastmcp>=3.4.2; extra == 'serve'
+Requires-Dist: fastmcp<5,>=4.1.1; extra == 'serve'
 Requires-Dist: httpx>=0.28; extra == 'serve'
 Provides-Extra: temporal
 Requires-Dist: temporalio>=1.7; extra == 'temporal'
@@ -75,6 +76,91 @@ genuinely need judgment. A 10 to 20 minute agent loop becomes a
 background workflow that costs a fraction of the tokens and can be
 regression tested.
 
+### Try it free in 60 seconds
+
+No API key, no subscription, no tokens, no clone. The
+[`expense-audit`](examples/expense-audit/) example is a month-end expense
+audit skill whose compiled pipeline ships with working code, and it comes
+inside the package, so you can emit it and run it before you compile
+anything of your own:
+
+```sh
+uv tool install 'rote-cli[dbos]'   # or: python3 -m venv .venv && . .venv/bin/activate && pip install 'rote-cli[dbos]'
+rote example expense-audit         # copies the skill, IR, code and sample input to ./expense-audit
+                                   # (zero-install: uvx --from rote-cli rote example expense-audit)
+
+# IR -> a plain Python script, then run it on the sample batch
+rote emit expense-audit/expected/pipeline-draft.yaml --runtime python --out expense-audit/app-python
+rote run expense-audit/app-python --input expense-audit/input.json
+```
+
+`rote example` prints these commands (and the dbos and eval ones) for
+the copy it made. `rote example` alone lists what is bundled. Prefer the
+repo? `git clone https://github.com/trevhud/rote.git && cd rote`, then
+use `examples/expense-audit/` in place of `expense-audit/`.
+
+```
+rote run (python): succeeded
+  0.1s
+{
+  "file_report": {
+    "report_path": "/home/you/expense-audit/app-python/reports/2026-09-expense-audit.md",
+    "status": "draft",
+    "reviewer": null,
+    "reimbursable_usd": 2395.59,
+    "pending_usd": 844.39,
+    "returned_usd": 64.17,
+    "batch_total_usd": 3304.15,
+    "auto_approved": ["Dev Patel", "Emi Tanaka"],
+    "review_items": 4,
+    "blocked_items": 2
+  }
+}
+```
+
+Sixteen expense lines in five currencies went through a parallel wave of
+three mandatory checks, a per-employee audit fanned out five ways, and a
+report written to disk, with no model anywhere in the loop. The full
+skill also parks for the controller's approval, which needs a durable
+runtime:
+
+```sh
+rote emit expense-audit/expected/pipeline.yaml --runtime dbos --out expense-audit/app-dbos
+rote run expense-audit/app-dbos --input expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+# ... "status": "final", "reimbursable_usd": 2990.98, "returned_usd": 313.17
+```
+
+What compiling it bought, measured: we ran the same batch twice each way
+with `rote eval --run` (the skill as an agent via `claude -p` on Sonnet,
+against the dbos app above):
+
+| | Skill run as an agent | Compiled pipeline |
+| --- | --- | --- |
+| Wall clock per run | 42.9 s | 9.8 s, mostly DBOS startup |
+| Cost per run | $0.22 | $0 |
+| Identical output across runs | 1 of 2 | 2 of 2 |
+
+So it's roughly 4x faster in practice, it drops from $0.22 a run to
+nothing, and it gives the same answer every time. The agent's two runs
+disagreed on where they filed the report. Full results are in
+[`examples/expense-audit/scorecard.md`](examples/expense-audit/scorecard.md).
+
+To get a scorecard for any pipeline without running anything, use
+`rote eval`. It fetches the live price list once and runs no inference.
+Its numbers are an estimate from turn counts, not a measurement:
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+`pip` installs don't include `examples/`, hence the clone. The other
+examples' extracted modules are `NotImplementedError` stubs waiting for
+real vendor API clients, so `expense-audit` is the one that runs end to
+end. Details in [its README](examples/expense-audit/README.md).
+
+### Compile your own skill
+
 ```sh
 pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
@@ -159,6 +245,19 @@ representation (`pipeline.yaml`), extracted Python modules for the
 deterministic parts, typed signature stubs for the LLM-judge parts, and
 runnable code for the durable execution engine of your choice.
 
+The agent implements the deterministic `pure_function` steps the skill
+spells out and writes tests for them. Before the compile reports
+success, rote checks what the agent wrote and runs those tests, and any
+failure goes back to the agent to fix. The tests are code an LLM wrote
+from a skill you may not have written, so rote runs them in an OS
+sandbox (`sandbox-exec` on macOS, bubblewrap on Linux): no network, no
+reads outside the compile's work dir and the Python install, no programs
+other than Python, no API keys in the environment, an empty `HOME`. If
+no sandbox works on your machine, the tests are skipped and the compile
+says the deliverable is unverified. `--trust-skill` runs them without a
+sandbox, and `--no-verify-tests` never runs them; either way, review
+`<out>/compiled/tests/` before running them yourself.
+
 `rote` is a three-layer system; each layer has one job and contracts on
 a small interface.
 
@@ -180,7 +279,7 @@ a small interface.
 ```
 
 1. **The compiler agent** (`skills/rote-compile/`): a regular
-   Anthropic Skill (`SKILL.md` + four reference files). This is the
+   Anthropic Skill (`SKILL.md` + six reference files). This is the
    *brain*; it runs inside any Skills-compatible surface, and you don't
    need `rote` to use it.
 2. **The IR** (`src/rote/ir.py`): Pydantic models for the five node
@@ -210,7 +309,9 @@ touching Python tooling:
 Then say "compile this skill" (or run `/rote:compile`). It confirms the
 source directory, asks which runtime you want, runs the CLI via
 [uv](https://docs.astral.sh/uv/) in the background, and reports the
-emitted pipeline. A second skill, `/rote:serve`, wires compiled
+emitted pipeline. `/rote:implement` then fills in the emitted stub
+modules against each node's IR contract and verifies the result with
+`rote run`. A third skill, `/rote:serve`, wires compiled
 pipelines up as MCP tools so Claude can trigger the deployed workflows
 (see [docs/mcp-trigger.md](docs/mcp-trigger.md)).
 
@@ -230,9 +331,10 @@ this README still works logged out.
 
 > **Naming note:** the `rote` package on PyPI is an unrelated
 > memoization library that also installs `import rote`, so the two can't
-> share an environment. This project's distribution is `rote-cli` while
-> the CLI command and import name stay `rote`, hence
-> `uvx --from rote-cli rote ...`. See [docs/releasing.md](docs/releasing.md).
+> share an environment. This project's distribution is `rote-cli` and the
+> import name stays `rote`. The package installs the same CLI under two
+> commands, `rote` and `rote-cli`, so both `uvx rote-cli ...` and
+> `uvx --from rote-cli rote ...` work. See [docs/releasing.md](docs/releasing.md).
 
 ### Run on the bundled example
 
@@ -246,7 +348,7 @@ rote compile examples/bdr-outreach/skill --out /tmp/bdr-compiled
 
 On that skill the compiler produces a 22-node IR that's **78.9%
 codifiable** (15 of 19 non-gate nodes), extracts 5 Python modules and 2
-typed judge signatures, and flags 4 mandatory nodes and 3 HITL gates,
+typed judge signatures, and flags 3 mandatory nodes and 3 HITL gates,
 all in ~13 minutes for ~$0.70 (Sonnet via Claude Code). Along the way it
 independently lifts the three MANDATORY exclusion checks out of prose,
 pulls four batch-size constants out of prompt text, and models a
@@ -257,6 +359,24 @@ override with `--agent`. The output directory splits into `compiled/`
 (the agent's `pipeline.yaml`, `extracted/`, `signatures/`, eval seeds,
 and a `compile-report.md`) and `runtime/<runtime>/` (the adapter's
 emitted code + a README on how to run, signal gates, and deploy).
+`compiled/compile-metrics.json` preserves final token counts, session ID,
+and the driver's cost estimate before emission starts, so an adapter
+failure does not lose the paid run's metrics. Missing final output stays
+null with `usage_complete: false`; unchanged updates retain prior metrics.
+
+Local `api` and `openai-api` compilation automatically discovers your
+registered, authenticated MCP servers and exposes their read-only tools.
+Pass `--no-mcp` to skip that discovery and compile without live MCP calls:
+
+```sh
+rote compile examples/bdr-outreach/skill --local --agent api --no-mcp --out /tmp/bdr-compiled
+```
+
+This leaves the emitted pipeline's MCP bindings intact. The flag also works
+with `rote analyze` and with an API driver selected through config or
+auto-detection. It rejects cloud compilation, subprocess drivers, and
+`--baseline`, whose raw skill run uses its own MCP tools. API drivers bill
+through your API credentials.
 
 ### Other commands
 
@@ -407,6 +527,8 @@ subscription path.
 
 ## How it differs from other tools
 
+For a side-by-side with calcifier, skill-to-workflow, Claude Code dynamic workflows, and hand-written workflows, see [docs/comparison.md](docs/comparison.md).
+
 - **vs. raw durable engines (Temporal / Cloudflare / Inngest / Restate):**
   they give you the workflow *runtime*; they don't help you decide *what
   should be a workflow*. `rote` is the missing step that turns a working
@@ -425,16 +547,17 @@ subscription path.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example. The
-fast suite (`pytest tests/`) makes no real API calls and is what CI runs
-on every push, alongside a Python e2e (DBOS over SQLite + the MCP server
-over real stdio). Each adapter also has a `slow`-marked e2e that runs its
-emitted code against the real runtime (Temporal's time-skipping server,
-the TypeScript targets via `tsc --noEmit` and live dev servers, the
-plain-Python subprocess); those need a Node toolchain / Docker, so they
-run locally with `pytest tests/ -m slow`, not in CI.
-
-Known gaps: the extracted modules are `NotImplementedError` stubs
-you fill in with real API-client code, and a Restate adapter is planned.
+fast suite (`pytest tests/`) makes no real API calls, spends no tokens,
+and runs on every push. CI also runs every `slow`-marked e2e suite on
+every push: DBOS over SQLite, the MCP server over real stdio, the
+TypeScript targets via `tsc --noEmit` and live dev servers (Cloudflare
+`wrangler dev`, the Inngest dev server), and DBOS TypeScript against a
+Docker Postgres. Locally, `pytest tests/ -m slow` runs them; they need a
+Node toolchain and Docker.
+
+Known gaps: extracted modules that need a vendor API client (HubSpot,
+ZoomInfo, and so on) come out as `NotImplementedError` stubs you fill in,
+and a Restate adapter is planned.
 Published on
 PyPI as [`rote-cli`](https://pypi.org/project/rote-cli/) via tag-driven
 Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
@@ -454,7 +577,7 @@ measure your own workflow instead of reading someone else's, use
 ```
 rote/
 ├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
-├── skills/rote-compile/  the compiler agent (SKILL.md + 4 reference files)
+├── skills/rote-compile/  the compiler agent (SKILL.md + 6 reference files)
 ├── src/rote/
 │   ├── cli.py             rote compile / emit / eval / serve
 │   ├── ir.py              Pydantic IR models + load_pipeline
@@ -462,6 +585,7 @@ rote/
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
 ├── examples/
+│   ├── expense-audit/     free first run: working extracted code · fan-out · HITL gate
 │   ├── bdr-outreach/      canonical: all 5 node kinds · IR baseline · run snapshots
 │   ├── ops-report/        100% roteness: zero LLM nodes + a HITL gate
 │   ├── deal-monitor/      data-heavy: parallel waves · fan-out judges · template render
@@ -483,12 +607,16 @@ rote/
   emitted code uses under `--backend mcp`: endpoint/credential
   resolution and durable park-on-auth across every MCP-capable runtime
 - [`docs/mcp-trigger.md`](docs/mcp-trigger.md): `rote register` +
-  `rote serve`: compiled pipelines as MCP tools (FastMCP 3.x)
+  `rote serve`: compiled pipelines as MCP tools (FastMCP 4.x)
 - [`docs/releasing.md`](docs/releasing.md): tag-driven PyPI Trusted
   Publishing
 - [`skills/rote-compile/`](skills/rote-compile/): the compiler's
-  `SKILL.md` and its four rubric files (node kinds, crystallization
-  heuristics, IR schema, LLM-judge extraction)
+  `SKILL.md` and its six rubric files (node kinds, crystallization
+  heuristics, IR schema, LLM-judge extraction, implementation, eval
+  estimates)
+- [`examples/expense-audit/`](examples/expense-audit/): the free first
+  run: a hand-compiled pipeline with working extracted code that
+  `rote run` completes on python, dbos, and temporal with no credentials
 - [`examples/bdr-outreach/`](examples/bdr-outreach/): the canonical
   skill, its ground-truth IR, and snapshotted real compiler runs
 - [`examples/ops-report/`](examples/ops-report/): the 100%-roteness
@@ -501,6 +629,9 @@ rote/
   archetype: a bounded browser-automation loop stays one agent node
   while the date math, filtering, and reporting around it compile to
   code, plus the measured runs that forced the loop-aware cost model
+- [`examples/rote-compile/`](examples/rote-compile/): the compiler compiling
+  its own core skill, with preserved artifacts and an offline audit of
+  the generated workflow's runtime and data-flow failures
 
 ---
 
@@ -508,17 +639,19 @@ rote/
 
 In rough priority order:
 
-1. **Re-compile BDR end-to-end with `signature_spec`**: the bundled IR
-   was hand-extended with structured schemas; the rubric now teaches the
-   field, but no real run has produced one yet.
-2. **Pre-filter as a `pure_function` node**: today hard thresholds are
-   lifted into a judge's `forward()`, which works for Temporal but not
-   Cloudflare; a separate node makes the short-circuit uniform.
-3. **More example skills**: BDR is one shape; research-heavy,
-   retrieval-heavy, and code-review skills stress the IR differently.
-4. **The compiler compiling itself**: `rote-compile` is a SKILL.md;
-   pointing `rote compile` at it should crystallize its rubric-grade
-   pieces and leave only the genuinely fuzzy judgments in the loop.
+1. **Pre-filter as a `pure_function` node**: today hard thresholds are
+   lifted into a judge's `forward()`, which works for the Python
+   runtimes but not the TypeScript ones; a separate node makes the
+   short-circuit uniform across all six.
+2. **Make self-compilation executable**: the
+   [preserved core-skill run](examples/rote-compile/) produced valid IR,
+   and runtime emission now succeeds. Its offline audit still has
+   data-flow and agent-result contract failures. Close those gaps before
+   treating it as a working replacement compiler.
+3. **More example skills**: four archetypes are covered today (BDR
+   outreach, 100%-roteness, data-heavy, agent-loop). Research-heavy,
+   retrieval-heavy, and code-review skills each stress the IR in ways
+   none of those four do.
 
 ---
 

{rote_cli-0.13.0 → rote_cli-0.15.0}/README.md

@@ -19,6 +19,91 @@ genuinely need judgment. A 10 to 20 minute agent loop becomes a
 background workflow that costs a fraction of the tokens and can be
 regression tested.
 
+### Try it free in 60 seconds
+
+No API key, no subscription, no tokens, no clone. The
+[`expense-audit`](examples/expense-audit/) example is a month-end expense
+audit skill whose compiled pipeline ships with working code, and it comes
+inside the package, so you can emit it and run it before you compile
+anything of your own:
+
+```sh
+uv tool install 'rote-cli[dbos]'   # or: python3 -m venv .venv && . .venv/bin/activate && pip install 'rote-cli[dbos]'
+rote example expense-audit         # copies the skill, IR, code and sample input to ./expense-audit
+                                   # (zero-install: uvx --from rote-cli rote example expense-audit)
+
+# IR -> a plain Python script, then run it on the sample batch
+rote emit expense-audit/expected/pipeline-draft.yaml --runtime python --out expense-audit/app-python
+rote run expense-audit/app-python --input expense-audit/input.json
+```
+
+`rote example` prints these commands (and the dbos and eval ones) for
+the copy it made. `rote example` alone lists what is bundled. Prefer the
+repo? `git clone https://github.com/trevhud/rote.git && cd rote`, then
+use `examples/expense-audit/` in place of `expense-audit/`.
+
+```
+rote run (python): succeeded
+  0.1s
+{
+  "file_report": {
+    "report_path": "/home/you/expense-audit/app-python/reports/2026-09-expense-audit.md",
+    "status": "draft",
+    "reviewer": null,
+    "reimbursable_usd": 2395.59,
+    "pending_usd": 844.39,
+    "returned_usd": 64.17,
+    "batch_total_usd": 3304.15,
+    "auto_approved": ["Dev Patel", "Emi Tanaka"],
+    "review_items": 4,
+    "blocked_items": 2
+  }
+}
+```
+
+Sixteen expense lines in five currencies went through a parallel wave of
+three mandatory checks, a per-employee audit fanned out five ways, and a
+report written to disk, with no model anywhere in the loop. The full
+skill also parks for the controller's approval, which needs a durable
+runtime:
+
+```sh
+rote emit expense-audit/expected/pipeline.yaml --runtime dbos --out expense-audit/app-dbos
+rote run expense-audit/app-dbos --input expense-audit/input.json \
+  --signal controller_review='{"reviewer": "Priya Shah", "approved_ids": ["EXP-2403", "EXP-2413", "EXP-2420"], "rejected_ids": ["EXP-2410"]}'
+# ... "status": "final", "reimbursable_usd": 2990.98, "returned_usd": 313.17
+```
+
+What compiling it bought, measured: we ran the same batch twice each way
+with `rote eval --run` (the skill as an agent via `claude -p` on Sonnet,
+against the dbos app above):
+
+| | Skill run as an agent | Compiled pipeline |
+| --- | --- | --- |
+| Wall clock per run | 42.9 s | 9.8 s, mostly DBOS startup |
+| Cost per run | $0.22 | $0 |
+| Identical output across runs | 1 of 2 | 2 of 2 |
+
+So it's roughly 4x faster in practice, it drops from $0.22 a run to
+nothing, and it gives the same answer every time. The agent's two runs
+disagreed on where they filed the report. Full results are in
+[`examples/expense-audit/scorecard.md`](examples/expense-audit/scorecard.md).
+
+To get a scorecard for any pipeline without running anything, use
+`rote eval`. It fetches the live price list once and runs no inference.
+Its numbers are an estimate from turn counts, not a measurement:
+
+```sh
+rote eval examples/expense-audit/expected/pipeline.yaml
+```
+
+`pip` installs don't include `examples/`, hence the clone. The other
+examples' extracted modules are `NotImplementedError` stubs waiting for
+real vendor API clients, so `expense-audit` is the one that runs end to
+end. Details in [its README](examples/expense-audit/README.md).
+
+### Compile your own skill
+
 ```sh
 pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
@@ -103,6 +188,19 @@ representation (`pipeline.yaml`), extracted Python modules for the
 deterministic parts, typed signature stubs for the LLM-judge parts, and
 runnable code for the durable execution engine of your choice.
 
+The agent implements the deterministic `pure_function` steps the skill
+spells out and writes tests for them. Before the compile reports
+success, rote checks what the agent wrote and runs those tests, and any
+failure goes back to the agent to fix. The tests are code an LLM wrote
+from a skill you may not have written, so rote runs them in an OS
+sandbox (`sandbox-exec` on macOS, bubblewrap on Linux): no network, no
+reads outside the compile's work dir and the Python install, no programs
+other than Python, no API keys in the environment, an empty `HOME`. If
+no sandbox works on your machine, the tests are skipped and the compile
+says the deliverable is unverified. `--trust-skill` runs them without a
+sandbox, and `--no-verify-tests` never runs them; either way, review
+`<out>/compiled/tests/` before running them yourself.
+
 `rote` is a three-layer system; each layer has one job and contracts on
 a small interface.
 
@@ -124,7 +222,7 @@ a small interface.
 ```
 
 1. **The compiler agent** (`skills/rote-compile/`): a regular
-   Anthropic Skill (`SKILL.md` + four reference files). This is the
+   Anthropic Skill (`SKILL.md` + six reference files). This is the
    *brain*; it runs inside any Skills-compatible surface, and you don't
    need `rote` to use it.
 2. **The IR** (`src/rote/ir.py`): Pydantic models for the five node
@@ -154,7 +252,9 @@ touching Python tooling:
 Then say "compile this skill" (or run `/rote:compile`). It confirms the
 source directory, asks which runtime you want, runs the CLI via
 [uv](https://docs.astral.sh/uv/) in the background, and reports the
-emitted pipeline. A second skill, `/rote:serve`, wires compiled
+emitted pipeline. `/rote:implement` then fills in the emitted stub
+modules against each node's IR contract and verifies the result with
+`rote run`. A third skill, `/rote:serve`, wires compiled
 pipelines up as MCP tools so Claude can trigger the deployed workflows
 (see [docs/mcp-trigger.md](docs/mcp-trigger.md)).
 
@@ -174,9 +274,10 @@ this README still works logged out.
 
 > **Naming note:** the `rote` package on PyPI is an unrelated
 > memoization library that also installs `import rote`, so the two can't
-> share an environment. This project's distribution is `rote-cli` while
-> the CLI command and import name stay `rote`, hence
-> `uvx --from rote-cli rote ...`. See [docs/releasing.md](docs/releasing.md).
+> share an environment. This project's distribution is `rote-cli` and the
+> import name stays `rote`. The package installs the same CLI under two
+> commands, `rote` and `rote-cli`, so both `uvx rote-cli ...` and
+> `uvx --from rote-cli rote ...` work. See [docs/releasing.md](docs/releasing.md).
 
 ### Run on the bundled example
 
@@ -190,7 +291,7 @@ rote compile examples/bdr-outreach/skill --out /tmp/bdr-compiled
 
 On that skill the compiler produces a 22-node IR that's **78.9%
 codifiable** (15 of 19 non-gate nodes), extracts 5 Python modules and 2
-typed judge signatures, and flags 4 mandatory nodes and 3 HITL gates,
+typed judge signatures, and flags 3 mandatory nodes and 3 HITL gates,
 all in ~13 minutes for ~$0.70 (Sonnet via Claude Code). Along the way it
 independently lifts the three MANDATORY exclusion checks out of prose,
 pulls four batch-size constants out of prompt text, and models a
@@ -201,6 +302,24 @@ override with `--agent`. The output directory splits into `compiled/`
 (the agent's `pipeline.yaml`, `extracted/`, `signatures/`, eval seeds,
 and a `compile-report.md`) and `runtime/<runtime>/` (the adapter's
 emitted code + a README on how to run, signal gates, and deploy).
+`compiled/compile-metrics.json` preserves final token counts, session ID,
+and the driver's cost estimate before emission starts, so an adapter
+failure does not lose the paid run's metrics. Missing final output stays
+null with `usage_complete: false`; unchanged updates retain prior metrics.
+
+Local `api` and `openai-api` compilation automatically discovers your
+registered, authenticated MCP servers and exposes their read-only tools.
+Pass `--no-mcp` to skip that discovery and compile without live MCP calls:
+
+```sh
+rote compile examples/bdr-outreach/skill --local --agent api --no-mcp --out /tmp/bdr-compiled
+```
+
+This leaves the emitted pipeline's MCP bindings intact. The flag also works
+with `rote analyze` and with an API driver selected through config or
+auto-detection. It rejects cloud compilation, subprocess drivers, and
+`--baseline`, whose raw skill run uses its own MCP tools. API drivers bill
+through your API credentials.
 
 ### Other commands
 
@@ -351,6 +470,8 @@ subscription path.
 
 ## How it differs from other tools
 
+For a side-by-side with calcifier, skill-to-workflow, Claude Code dynamic workflows, and hand-written workflows, see [docs/comparison.md](docs/comparison.md).
+
 - **vs. raw durable engines (Temporal / Cloudflare / Inngest / Restate):**
   they give you the workflow *runtime*; they don't help you decide *what
   should be a workflow*. `rote` is the missing step that turns a working
@@ -369,16 +490,17 @@ subscription path.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example. The
-fast suite (`pytest tests/`) makes no real API calls and is what CI runs
-on every push, alongside a Python e2e (DBOS over SQLite + the MCP server
-over real stdio). Each adapter also has a `slow`-marked e2e that runs its
-emitted code against the real runtime (Temporal's time-skipping server,
-the TypeScript targets via `tsc --noEmit` and live dev servers, the
-plain-Python subprocess); those need a Node toolchain / Docker, so they
-run locally with `pytest tests/ -m slow`, not in CI.
-
-Known gaps: the extracted modules are `NotImplementedError` stubs
-you fill in with real API-client code, and a Restate adapter is planned.
+fast suite (`pytest tests/`) makes no real API calls, spends no tokens,
+and runs on every push. CI also runs every `slow`-marked e2e suite on
+every push: DBOS over SQLite, the MCP server over real stdio, the
+TypeScript targets via `tsc --noEmit` and live dev servers (Cloudflare
+`wrangler dev`, the Inngest dev server), and DBOS TypeScript against a
+Docker Postgres. Locally, `pytest tests/ -m slow` runs them; they need a
+Node toolchain and Docker.
+
+Known gaps: extracted modules that need a vendor API client (HubSpot,
+ZoomInfo, and so on) come out as `NotImplementedError` stubs you fill in,
+and a Restate adapter is planned.
 Published on
 PyPI as [`rote-cli`](https://pypi.org/project/rote-cli/) via tag-driven
 Trusted Publishing ([docs/releasing.md](docs/releasing.md)).
@@ -398,7 +520,7 @@ measure your own workflow instead of reading someone else's, use
 ```
 rote/
 ├── docs/                  agent-runtime · mcp-client · mcp-trigger · releasing
-├── skills/rote-compile/  the compiler agent (SKILL.md + 4 reference files)
+├── skills/rote-compile/  the compiler agent (SKILL.md + 6 reference files)
 ├── src/rote/
 │   ├── cli.py             rote compile / emit / eval / serve
 │   ├── ir.py              Pydantic IR models + load_pipeline
@@ -406,6 +528,7 @@ rote/
 │   └── adapters/          dbos · temporal · python · cloudflare · dbos_ts · inngest
 │                          (+ _common / _py_common / _ts_common emit helpers)
 ├── examples/
+│   ├── expense-audit/     free first run: working extracted code · fan-out · HITL gate
 │   ├── bdr-outreach/      canonical: all 5 node kinds · IR baseline · run snapshots
 │   ├── ops-report/        100% roteness: zero LLM nodes + a HITL gate
 │   ├── deal-monitor/      data-heavy: parallel waves · fan-out judges · template render
@@ -427,12 +550,16 @@ rote/
   emitted code uses under `--backend mcp`: endpoint/credential
   resolution and durable park-on-auth across every MCP-capable runtime
 - [`docs/mcp-trigger.md`](docs/mcp-trigger.md): `rote register` +
-  `rote serve`: compiled pipelines as MCP tools (FastMCP 3.x)
+  `rote serve`: compiled pipelines as MCP tools (FastMCP 4.x)
 - [`docs/releasing.md`](docs/releasing.md): tag-driven PyPI Trusted
   Publishing
 - [`skills/rote-compile/`](skills/rote-compile/): the compiler's
-  `SKILL.md` and its four rubric files (node kinds, crystallization
-  heuristics, IR schema, LLM-judge extraction)
+  `SKILL.md` and its six rubric files (node kinds, crystallization
+  heuristics, IR schema, LLM-judge extraction, implementation, eval
+  estimates)
+- [`examples/expense-audit/`](examples/expense-audit/): the free first
+  run: a hand-compiled pipeline with working extracted code that
+  `rote run` completes on python, dbos, and temporal with no credentials
 - [`examples/bdr-outreach/`](examples/bdr-outreach/): the canonical
   skill, its ground-truth IR, and snapshotted real compiler runs
 - [`examples/ops-report/`](examples/ops-report/): the 100%-roteness
@@ -445,6 +572,9 @@ rote/
   archetype: a bounded browser-automation loop stays one agent node
   while the date math, filtering, and reporting around it compile to
   code, plus the measured runs that forced the loop-aware cost model
+- [`examples/rote-compile/`](examples/rote-compile/): the compiler compiling
+  its own core skill, with preserved artifacts and an offline audit of
+  the generated workflow's runtime and data-flow failures
 
 ---
 
@@ -452,17 +582,19 @@ rote/
 
 In rough priority order:
 
-1. **Re-compile BDR end-to-end with `signature_spec`**: the bundled IR
-   was hand-extended with structured schemas; the rubric now teaches the
-   field, but no real run has produced one yet.
-2. **Pre-filter as a `pure_function` node**: today hard thresholds are
-   lifted into a judge's `forward()`, which works for Temporal but not
-   Cloudflare; a separate node makes the short-circuit uniform.
-3. **More example skills**: BDR is one shape; research-heavy,
-   retrieval-heavy, and code-review skills stress the IR differently.
-4. **The compiler compiling itself**: `rote-compile` is a SKILL.md;
-   pointing `rote compile` at it should crystallize its rubric-grade
-   pieces and leave only the genuinely fuzzy judgments in the loop.
+1. **Pre-filter as a `pure_function` node**: today hard thresholds are
+   lifted into a judge's `forward()`, which works for the Python
+   runtimes but not the TypeScript ones; a separate node makes the
+   short-circuit uniform across all six.
+2. **Make self-compilation executable**: the
+   [preserved core-skill run](examples/rote-compile/) produced valid IR,
+   and runtime emission now succeeds. Its offline audit still has
+   data-flow and agent-result contract failures. Close those gaps before
+   treating it as a working replacement compiler.
+3. **More example skills**: four archetypes are covered today (BDR
+   outreach, 100%-roteness, data-heavy, agent-loop). Research-heavy,
+   retrieval-heavy, and code-review skills each stress the IR in ways
+   none of those four do.
 
 ---