rote-cli 0.16.0__tar.gz → 0.17.0__tar.gz

{rote_cli-0.16.0 → rote_cli-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rote-cli
-Version: 0.16.0
+Version: 0.17.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
@@ -24,10 +24,15 @@ Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: fastmcp-slim[client]<5,>=4.1.3
 Requires-Dist: graphql-core<4,>=3.3
+Requires-Dist: httpx>=0.28
+Requires-Dist: json5<1,>=0.17.3
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pytest<10,>=9.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary<3,>=2.1.1
+Requires-Dist: rich<16,>=15.0.0
 Provides-Extra: api
 Requires-Dist: anthropic>=1.15; extra == 'api'
 Provides-Extra: dbos
@@ -35,12 +40,11 @@ Requires-Dist: dbos<4,>=3.3; extra == 'dbos'
 Provides-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: fastmcp<5,>=4.1.3; extra == 'dev'
 Requires-Dist: google-api-python-client>=2.201.0; extra == 'dev'
 Requires-Dist: google-auth-httplib2>=0.4.4; extra == 'dev'
 Requires-Dist: google-auth>=2.62.0; extra == 'dev'
 Requires-Dist: httplib2>=0.32.0; 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'
@@ -50,13 +54,10 @@ 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<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<5,>=4.1.1; extra == 'serve'
-Requires-Dist: httpx>=0.28; extra == 'serve'
+Requires-Dist: fastmcp<5,>=4.1.3; extra == 'serve'
 Provides-Extra: temporal
 Requires-Dist: temporalio>=1.7; extra == 'temporal'
 Description-Content-Type: text/markdown
@@ -91,7 +92,8 @@ 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]'
+uv tool install rote-cli          # or: python3 -m venv .venv && . .venv/bin/activate && pip install rote-cli
+                                   # (the first dbos run offers to add the dbos extra; you confirm it)
 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)
 
@@ -114,12 +116,12 @@ rote run (python): succeeded
     "status": "draft",
     "reviewer": null,
     "reimbursable_usd": 2395.59,
-    "pending_usd": 844.39,
-    "returned_usd": 64.17,
+    "pending_usd": 18.75,
+    "returned_usd": 889.81,
     "batch_total_usd": 3304.15,
     "auto_approved": ["Dev Patel", "Emi Tanaka"],
-    "review_items": 4,
-    "blocked_items": 2
+    "review_items": 1,
+    "blocked_items": 5
   }
 }
 ```
@@ -134,7 +136,7 @@ runtime:
 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
+# ... "status": "final", "reimbursable_usd": 2414.34, "returned_usd": 889.81
 ```
 
 What compiling it bought, measured: we ran the same batch twice each way
@@ -172,18 +174,49 @@ pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
 # `rote compile` runs an LLM agent, so it needs a driver: Claude Code
 # (`claude`) or Codex (`codex`) installed and authed, or ANTHROPIC_API_KEY
-# for the in-process `api` driver. The BDR run below takes ~13 min and
-# ~$0.70 with Sonnet. (`rote emit` needs no LLM; see below.)
+# for the in-process `api` driver. (`rote emit` needs no LLM; see below.)
+
+# Default target is a compiled skill: the same skill name and trigger,
+# with its fixed steps in code, run by the agent you already use:
+rote compile ./examples/docs-digest/skill --out ./compiled/
+# rote compile: ✓ docs-digest v...
+#   next: rote skill install .../compiled/runtime/skill/docs-digest
+#     then swap it in for the original docs-digest skill (Claude Code:
+#     ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest)
+#     or see it give the original's answer first: rote try ./examples/docs-digest/skill
+```
 
-# Default target is DBOS: durable execution as a plain Python library,
-# no orchestrator to run, SQLite for dev / Postgres for prod:
-rote compile ./examples/bdr-outreach/skill --out ./compiled/
+rote checks `~/.claude/skills/<name>` before it prints the link. When your
+original skill is already there, `ln -s` would nest the link inside it
+(and exit 0), so rote prints the swap with the original moved aside
+instead, plus the undo. Nothing is deleted, and rote runs none of it:
 
-# Or pick another runtime (see the table below):
-rote compile ./examples/bdr-outreach/skill --runtime temporal   --out ./compiled/
+```
+    then, for Claude Code: your original docs-digest skill is at ~/.claude/skills/docs-digest.
+    To use the compiled one instead, move the original out of the skills folder (nothing is
+    deleted): mv ~/.claude/skills/docs-digest ~/docs-digest.original && ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest
+      undo: rm ~/.claude/skills/docs-digest && mv ~/docs-digest.original ~/.claude/skills/docs-digest
+```
+
+```sh
+# Or emit a background workflow instead (see the table below):
+rote compile ./examples/bdr-outreach/skill --runtime dbos       --out ./compiled/
 rote compile ./examples/bdr-outreach/skill --runtime cloudflare --out ./compiled/
 ```
 
+Measured on claude-sonnet-4-6, original skill against its compiled skill,
+with every compared field matching within the original's own run-to-run
+noise:
+
+| Skill | Original | Compiled skill |
+| --- | --- | --- |
+| expense-audit | 154 s, $0.34 | 43 s, $0.13 |
+| ops-report | 55 s, $0.13 | 42 s, $0.12 |
+| docs-digest | 17.9 s, $0.093 | 16.3 s, $0.049 |
+
+`rote try <skill>` runs that comparison on a skill of yours: it compiles,
+installs, and runs both sides on the same input, after showing the cost.
+
 The name comes from *rote learning*: doing something so many times, so
 reliably, that it becomes mechanical. That's what compilation does to a
 skill.
@@ -326,6 +359,12 @@ touching Python tooling:
 /plugin install rote@rote
 ```
 
+New here? Run `/rote:setup`, or `uvx --from rote-cli rote setup` in a
+terminal. It imports the MCP servers you already use, compiles one of your
+skills, and shows that the compiled skill gives the same answer, with time
+and cost on each side. It asks before every step and shows the cost before
+anything is spent.
+
 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
@@ -338,16 +377,17 @@ pipelines up as MCP tools so Claude can trigger the deployed workflows
 Prefer a terminal? The same thing is one `uvx` command:
 
 ```sh
-uvx --from rote-cli rote compile ./my-skill --runtime dbos --out ./compiled
+uvx --from rote-cli rote compile ./my-skill --out ./compiled
 ```
 
 **Hosted platform:** [roteskills.com](https://roteskills.com) is the
 project site (concepts, benchmarks methodology, worked examples).
 [app.roteskills.com](https://app.roteskills.com) is Rote Cloud, a
 managed path for teams that would rather not operate a runtime: run
-`rote login` and `rote compile` then runs server-side, streams progress
-back, auto-deploys, and downloads the artifacts locally. Everything in
-this README still works logged out.
+`rote login`, then `rote compile --cloud` (or set `deploy: rote-cloud`
+with `rote init`) runs server-side, streams progress back, auto-deploys,
+and downloads the artifacts locally. Everything in 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
@@ -440,26 +480,29 @@ through your API credentials.
   (over SSH, `--device` prints the code + URL instead), you click
   Approve, and the CLI stores a tenant API key at
   `~/.local/share/rote/cloud.json` (mode 0600). Once logged in,
-  `rote compile` runs **on rote cloud by default**: the skill bundle
+  `rote compile --cloud` runs **on rote cloud**, and so does a compile
+  whose runtime is `cloudflare` or whose `deploy` is `rote-cloud`
+  (flag, env or config). A flagless compile stays local and emits a
+  compiled skill, logged in or not. On rote cloud the skill bundle
   syncs up (sha-diffed, so unchanged files don't re-upload), the
   platform runs the compilation server-side, live progress streams back
   through the same renderer as a local run, the result auto-deploys,
   and the artifacts download into your `--out` directory in the exact
-  local layout. `--local` keeps the compilation on your machine (then
-  the cloudflare-emit + auto-deploy flow applies), `--no-deploy` or a
-  config opt-out (`runtime:` pinned to a local target, or
-  `deploy: none`) keeps everything local; `--cloud` forces the server
-  even where config says otherwise. Logged out, everything works
-  locally exactly as before. `rote whoami` shows the account (verified
+  local layout. `--local` keeps the compilation on your machine (a
+  cloudflare compile then emits locally and auto-deploys), `--no-deploy`
+  or `deploy: none` keeps everything local; `--cloud` forces the server
+  even where config says otherwise. `rote whoami` shows the account (verified
   live); `rote logout` revokes the key server-side and clears the store.
-- **`rote init`**: one-time interactive onboarding: pick where
-  compiled pipelines run (rote cloud, with login offered inline, or
-  a local runtime, with a one-line pitch for each), which compiler
-  driver does the work (availability probed live), and optionally a
-  model. Answers are saved to `~/.config/rote/config.yaml`
+- **`rote init`**: one-time onboarding: pick where compiled pipelines
+  run (locally, with `skill` first and recommended, or rote cloud, with
+  login offered), which
+  compiler driver and model do the work, and who decides a local
+  compile's structure. It shows what it will write and asks before
+  writing. Answers are saved to `~/.config/rote/config.yaml`
   (`--project` writes a `./rote.yaml` that overrides it per-repo) and
-  every later command reads them. It's the only interactive command
-  besides login; CI never hits a prompt.
+  every later command reads them. Every question has a flag, so CI and
+  agents run it with flags and `--yes`; it never prompts without a
+  person at a terminal.
 - **`rote config`**: print every configurable default with its
   effective value *and the layer that set it*. Resolution everywhere is
   `flag > ROTE_* env (ROTE_RUNTIME, ROTE_DEPLOY, ROTE_AGENT,
@@ -471,7 +514,11 @@ through your API credentials.
   much of the run is still LLM-decided). `rote compile` writes this to
   `compiled/scorecard.md` automatically. Add `--run` to *measure*
   instead of estimate: it executes both sides for real and appends
-  measured cost, turns, and output agreement across trials.
+  measured cost, turns, and output agreement across trials. With
+  `--run --runtime skill` the after side is the compiled skill, run by
+  an agent through `rote skill run`, so both sides are agents and the
+  table compares context, tokens, time, cost and field fidelity
+  (`--budget` is required).
 - **Per-node inference**: emitted judges read `ROTE_MODEL_<ID>` and
   `ROTE_BASE_URL_<ID>` at runtime, so you can swap the model or point at
   any OpenAI-compatible endpoint (Ollama, vLLM, a gateway) without
@@ -515,7 +562,8 @@ see [`docs/mcp-client.md`](docs/mcp-client.md).
 
 | Runtime | `--runtime` | Language | Shape | Notes |
 | --- | --- | --- | --- | --- |
-| **DBOS** (default) | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
+| **Compiled skill** (default) | `skill` | Python driver + SKILL.md | a skill dir: the original's name and description, `scripts/` runs the fixed steps, the agent answers only judges and gates | Install with `rote skill install`; runs in Claude Code, Codex and other skill clients through `rote skill run` |
+| DBOS | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
 | Temporal | `temporal` | Python | `workflow.py` + `activities.py` | Signal handlers for HITL gates |
 | Plain Python | `python` | Python | single `main.py` script | Max legibility, stdlib only; refuses HITL-gate pipelines |
 | Cloudflare Workflows | `cloudflare` | TypeScript | `WorkflowEntrypoint` + `wrangler.jsonc` | `wrangler deploy`-ready |

{rote_cli-0.16.0 → rote_cli-0.17.0}/README.md

@@ -28,7 +28,8 @@ 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]'
+uv tool install rote-cli          # or: python3 -m venv .venv && . .venv/bin/activate && pip install rote-cli
+                                   # (the first dbos run offers to add the dbos extra; you confirm it)
 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)
 
@@ -51,12 +52,12 @@ rote run (python): succeeded
     "status": "draft",
     "reviewer": null,
     "reimbursable_usd": 2395.59,
-    "pending_usd": 844.39,
-    "returned_usd": 64.17,
+    "pending_usd": 18.75,
+    "returned_usd": 889.81,
     "batch_total_usd": 3304.15,
     "auto_approved": ["Dev Patel", "Emi Tanaka"],
-    "review_items": 4,
-    "blocked_items": 2
+    "review_items": 1,
+    "blocked_items": 5
   }
 }
 ```
@@ -71,7 +72,7 @@ runtime:
 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
+# ... "status": "final", "reimbursable_usd": 2414.34, "returned_usd": 889.81
 ```
 
 What compiling it bought, measured: we ran the same batch twice each way
@@ -109,18 +110,49 @@ pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
 
 # `rote compile` runs an LLM agent, so it needs a driver: Claude Code
 # (`claude`) or Codex (`codex`) installed and authed, or ANTHROPIC_API_KEY
-# for the in-process `api` driver. The BDR run below takes ~13 min and
-# ~$0.70 with Sonnet. (`rote emit` needs no LLM; see below.)
+# for the in-process `api` driver. (`rote emit` needs no LLM; see below.)
+
+# Default target is a compiled skill: the same skill name and trigger,
+# with its fixed steps in code, run by the agent you already use:
+rote compile ./examples/docs-digest/skill --out ./compiled/
+# rote compile: ✓ docs-digest v...
+#   next: rote skill install .../compiled/runtime/skill/docs-digest
+#     then swap it in for the original docs-digest skill (Claude Code:
+#     ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest)
+#     or see it give the original's answer first: rote try ./examples/docs-digest/skill
+```
 
-# Default target is DBOS: durable execution as a plain Python library,
-# no orchestrator to run, SQLite for dev / Postgres for prod:
-rote compile ./examples/bdr-outreach/skill --out ./compiled/
+rote checks `~/.claude/skills/<name>` before it prints the link. When your
+original skill is already there, `ln -s` would nest the link inside it
+(and exit 0), so rote prints the swap with the original moved aside
+instead, plus the undo. Nothing is deleted, and rote runs none of it:
 
-# Or pick another runtime (see the table below):
-rote compile ./examples/bdr-outreach/skill --runtime temporal   --out ./compiled/
+```
+    then, for Claude Code: your original docs-digest skill is at ~/.claude/skills/docs-digest.
+    To use the compiled one instead, move the original out of the skills folder (nothing is
+    deleted): mv ~/.claude/skills/docs-digest ~/docs-digest.original && ln -s .../runtime/skill/docs-digest ~/.claude/skills/docs-digest
+      undo: rm ~/.claude/skills/docs-digest && mv ~/docs-digest.original ~/.claude/skills/docs-digest
+```
+
+```sh
+# Or emit a background workflow instead (see the table below):
+rote compile ./examples/bdr-outreach/skill --runtime dbos       --out ./compiled/
 rote compile ./examples/bdr-outreach/skill --runtime cloudflare --out ./compiled/
 ```
 
+Measured on claude-sonnet-4-6, original skill against its compiled skill,
+with every compared field matching within the original's own run-to-run
+noise:
+
+| Skill | Original | Compiled skill |
+| --- | --- | --- |
+| expense-audit | 154 s, $0.34 | 43 s, $0.13 |
+| ops-report | 55 s, $0.13 | 42 s, $0.12 |
+| docs-digest | 17.9 s, $0.093 | 16.3 s, $0.049 |
+
+`rote try <skill>` runs that comparison on a skill of yours: it compiles,
+installs, and runs both sides on the same input, after showing the cost.
+
 The name comes from *rote learning*: doing something so many times, so
 reliably, that it becomes mechanical. That's what compilation does to a
 skill.
@@ -263,6 +295,12 @@ touching Python tooling:
 /plugin install rote@rote
 ```
 
+New here? Run `/rote:setup`, or `uvx --from rote-cli rote setup` in a
+terminal. It imports the MCP servers you already use, compiles one of your
+skills, and shows that the compiled skill gives the same answer, with time
+and cost on each side. It asks before every step and shows the cost before
+anything is spent.
+
 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
@@ -275,16 +313,17 @@ pipelines up as MCP tools so Claude can trigger the deployed workflows
 Prefer a terminal? The same thing is one `uvx` command:
 
 ```sh
-uvx --from rote-cli rote compile ./my-skill --runtime dbos --out ./compiled
+uvx --from rote-cli rote compile ./my-skill --out ./compiled
 ```
 
 **Hosted platform:** [roteskills.com](https://roteskills.com) is the
 project site (concepts, benchmarks methodology, worked examples).
 [app.roteskills.com](https://app.roteskills.com) is Rote Cloud, a
 managed path for teams that would rather not operate a runtime: run
-`rote login` and `rote compile` then runs server-side, streams progress
-back, auto-deploys, and downloads the artifacts locally. Everything in
-this README still works logged out.
+`rote login`, then `rote compile --cloud` (or set `deploy: rote-cloud`
+with `rote init`) runs server-side, streams progress back, auto-deploys,
+and downloads the artifacts locally. Everything in 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
@@ -377,26 +416,29 @@ through your API credentials.
   (over SSH, `--device` prints the code + URL instead), you click
   Approve, and the CLI stores a tenant API key at
   `~/.local/share/rote/cloud.json` (mode 0600). Once logged in,
-  `rote compile` runs **on rote cloud by default**: the skill bundle
+  `rote compile --cloud` runs **on rote cloud**, and so does a compile
+  whose runtime is `cloudflare` or whose `deploy` is `rote-cloud`
+  (flag, env or config). A flagless compile stays local and emits a
+  compiled skill, logged in or not. On rote cloud the skill bundle
   syncs up (sha-diffed, so unchanged files don't re-upload), the
   platform runs the compilation server-side, live progress streams back
   through the same renderer as a local run, the result auto-deploys,
   and the artifacts download into your `--out` directory in the exact
-  local layout. `--local` keeps the compilation on your machine (then
-  the cloudflare-emit + auto-deploy flow applies), `--no-deploy` or a
-  config opt-out (`runtime:` pinned to a local target, or
-  `deploy: none`) keeps everything local; `--cloud` forces the server
-  even where config says otherwise. Logged out, everything works
-  locally exactly as before. `rote whoami` shows the account (verified
+  local layout. `--local` keeps the compilation on your machine (a
+  cloudflare compile then emits locally and auto-deploys), `--no-deploy`
+  or `deploy: none` keeps everything local; `--cloud` forces the server
+  even where config says otherwise. `rote whoami` shows the account (verified
   live); `rote logout` revokes the key server-side and clears the store.
-- **`rote init`**: one-time interactive onboarding: pick where
-  compiled pipelines run (rote cloud, with login offered inline, or
-  a local runtime, with a one-line pitch for each), which compiler
-  driver does the work (availability probed live), and optionally a
-  model. Answers are saved to `~/.config/rote/config.yaml`
+- **`rote init`**: one-time onboarding: pick where compiled pipelines
+  run (locally, with `skill` first and recommended, or rote cloud, with
+  login offered), which
+  compiler driver and model do the work, and who decides a local
+  compile's structure. It shows what it will write and asks before
+  writing. Answers are saved to `~/.config/rote/config.yaml`
   (`--project` writes a `./rote.yaml` that overrides it per-repo) and
-  every later command reads them. It's the only interactive command
-  besides login; CI never hits a prompt.
+  every later command reads them. Every question has a flag, so CI and
+  agents run it with flags and `--yes`; it never prompts without a
+  person at a terminal.
 - **`rote config`**: print every configurable default with its
   effective value *and the layer that set it*. Resolution everywhere is
   `flag > ROTE_* env (ROTE_RUNTIME, ROTE_DEPLOY, ROTE_AGENT,
@@ -408,7 +450,11 @@ through your API credentials.
   much of the run is still LLM-decided). `rote compile` writes this to
   `compiled/scorecard.md` automatically. Add `--run` to *measure*
   instead of estimate: it executes both sides for real and appends
-  measured cost, turns, and output agreement across trials.
+  measured cost, turns, and output agreement across trials. With
+  `--run --runtime skill` the after side is the compiled skill, run by
+  an agent through `rote skill run`, so both sides are agents and the
+  table compares context, tokens, time, cost and field fidelity
+  (`--budget` is required).
 - **Per-node inference**: emitted judges read `ROTE_MODEL_<ID>` and
   `ROTE_BASE_URL_<ID>` at runtime, so you can swap the model or point at
   any OpenAI-compatible endpoint (Ollama, vLLM, a gateway) without
@@ -452,7 +498,8 @@ see [`docs/mcp-client.md`](docs/mcp-client.md).
 
 | Runtime | `--runtime` | Language | Shape | Notes |
 | --- | --- | --- | --- | --- |
-| **DBOS** (default) | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
+| **Compiled skill** (default) | `skill` | Python driver + SKILL.md | a skill dir: the original's name and description, `scripts/` runs the fixed steps, the agent answers only judges and gates | Install with `rote skill install`; runs in Claude Code, Codex and other skill clients through `rote skill run` |
+| DBOS | `dbos` | Python | `main.py` with `@DBOS.workflow` + `@DBOS.step` per node | No orchestrator to deploy; SQLite (dev) / Postgres (prod) |
 | Temporal | `temporal` | Python | `workflow.py` + `activities.py` | Signal handlers for HITL gates |
 | Plain Python | `python` | Python | single `main.py` script | Max legibility, stdlib only; refuses HITL-gate pipelines |
 | Cloudflare Workflows | `cloudflare` | TypeScript | `WorkflowEntrypoint` + `wrangler.jsonc` | `wrangler deploy`-ready |

rote_cli-0.17.0/examples/docs-digest/README.md

@@ -0,0 +1,98 @@
+# Example: Docs Digest
+
+The demo that `rote try` and `rote setup` run. A small skill that builds
+a reading list on a Microsoft technology from Microsoft Learn and adds
+the DeepWiki outline of the matching open-source repo. Both MCP servers
+are public and need no login, so the whole thing runs with two
+`rote mcp add` lines and nothing else:
+
+| Server | URL | Tool |
+| --- | --- | --- |
+| `mslearn` | https://learn.microsoft.com/api/mcp | `microsoft_docs_search` |
+| `deepwiki` | https://mcp.deepwiki.com/mcp | `read_wiki_structure` |
+
+Run as an agent, the skill costs a few cents of model time per run.
+Compiled, it is two MCP calls and two small Python functions, with no
+model call at all.
+
+## What it demonstrates
+
+- **MCP-bound steps.** `search_microsoft_learn` and
+  `read_repo_outline` are bare tool calls through the emitted MCP
+  helper. They run in the same entry wave, concurrently.
+- **Rules lifted out of prose.** "Keep the first 5 results" is the
+  node constant `result_count: 5`, which the code reads, so editing it in
+  `pipeline.yaml` changes the digest. The two section names are code in
+  `compiled/extracted/`.
+- **Live data.** The servers answer from live indexes, so a run today
+  can differ from the recorded one. `reference.json` says which fields
+  are expected to drift and why.
+
+## Run it
+
+From the repo root:
+
+```sh
+rote mcp add mslearn https://learn.microsoft.com/api/mcp --auth none --read-only
+rote mcp add deepwiki https://mcp.deepwiki.com/mcp --auth none --read-only
+
+# The precompiled pipeline (dbos on SQLite: no Node, no Docker; the first run
+# offers to install the dbos extra)
+rote emit examples/docs-digest/compiled/pipeline.yaml --runtime dbos --out /tmp/docs-digest-dbos
+rote run /tmp/docs-digest-dbos --input examples/docs-digest/skill/input.json
+
+# The skill itself, as an agent, read-only (bills your Claude subscription)
+rote run examples/docs-digest/skill --input examples/docs-digest/skill/input.json
+```
+
+The python runtime cannot run this pipeline. It has no MCP backend, so
+it would call the two tool steps' direct-API modules, and those are stubs
+(rote does not write vendor calls from memory). `rote run` refuses it up
+front. dbos is the runtime that speaks MCP and needs no Node and no
+Docker.
+
+## The recorded reference
+
+`reference.json` (format `rote-demo-reference/1`, documented in
+`rote.demo`) holds one real run of each side on `skill/input.json`,
+recorded on 2026-10-22:
+
+| | Skill, as an agent | Compile | Pipeline |
+| --- | --- | --- | --- |
+| Wall time | 14.9 s | 28 s | 6.6 s |
+| Turns or calls | 4 turns | 6 generations + 1 structure call | 0 model calls |
+| Cost | $0.088 | $0.076 | $0 |
+| Model | claude-sonnet-4-6 | claude-sonnet-5-5, claude-haiku-5-5 | none |
+
+The skill's digest and the pipeline's digest were the same text, except
+that the pipeline ends it with a newline. Five runs over 44 minutes (two
+agent runs, three pipeline runs across two compiles) got identical tool
+results. The `drift` section of the reference lists what is still
+expected to change over days: the reading list first, the repo outline
+slowly. The `fields` it compares on are the digest's sections and the
+reading list's length (equal on every run) and the two sections' text
+(expected to drift).
+
+`reference.json` also keeps the pipeline run's two MCP calls
+(`pipeline_run.tool_calls`: the arguments sent and the value received,
+Microsoft Learn's page excerpts dropped, since the pipeline reads only
+titles and links). `tests/test_docs_digest_demo.py` hands them to rote's
+own prefix runner as recorded calls, the interpreter verification uses,
+and requires the recorded digest back.
+
+## Layout
+
+```
+examples/docs-digest/
+├── README.md
+├── reference.json           # the recorded runs, see above
+├── skill/
+│   ├── SKILL.md
+│   ├── input.json           # the sample input; compile picks it up
+│   └── mcp-tools.json       # tools/list snapshot of the two tools
+└── compiled/                # `rote compile --runtime dbos` output
+    ├── pipeline.yaml
+    ├── extracted/
+    ├── tests/
+    └── compile-report.md
+```

rote_cli-0.17.0/examples/docs-digest/compiled/backend.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "external_backend": "mcp"
+}

rote_cli-0.17.0/examples/docs-digest/compiled/compile-metrics.json

@@ -0,0 +1,17 @@
+{
+  "cost_basis": "driver_estimate",
+  "driver": "claude",
+  "metadata": {
+    "cache_read_tokens": 27945,
+    "cache_write_tokens": 14182,
+    "cost_usd": 0.072854,
+    "duration_ms": 14712,
+    "input_tokens": 12,
+    "num_turns": 6,
+    "output_tokens": 3458,
+    "repair_rounds": 0,
+    "usage_complete": true,
+    "usage_source": "generations"
+  },
+  "schema_version": 1
+}

rote_cli-0.17.0/examples/docs-digest/compiled/compile-report.md

@@ -0,0 +1,60 @@
+# Compile report: docs-digest
+
+rote wrote this report from `pipeline.yaml` and the extracted code. Each node's description is the compiler's reason for its kind; each `# skill: "..."` citation is the rule a line of code implements; each `# rote: assumption:` marker is a decision the skill does not state.
+
+Compiled with System-1: rote decided the structure with a structure pass: claude-haiku-5-5 via claude -p (subscription) read the whole skill and proposed every node in 1 round(s), and code checked each one against the skill's text, its tools' schemas and the sample input; no decision model checked it (--decider rules), and the agent wrote the implementations and judge prompts. Every decision, with its confidence and rule, is in `system1/decisions.json`. Its model calls cost $0.0030 (claude-haiku-5-5, structure pass), on top of the agent's run.
+
+## Summary
+
+- 4 node(s): 2 `pure_function`, 2 `external_call`, 0 `llm_judge`, 0 `agent_loop`, 0 `hitl_gate`.
+- Codified (`pure_function` + `external_call`): 4 of 4 non-gate node(s), 100%.
+- Implemented impl node(s): 2 of 4.
+- Entry: `search_microsoft_learn`, `read_repo_outline`.
+- Exit: `write_digest`.
+- Mandatory: `search_microsoft_learn`, `pick_reading_list`, `read_repo_outline`, `write_digest`.
+- MCP servers: `deepwiki` (read_repo_outline), `mslearn` (search_microsoft_learn).
+
+## Nodes
+
+| Node | Kind | Implementation | Skill section | Description |
+|---|---|---|---|---|
+| `search_microsoft_learn` | external_call | `extracted/search_microsoft_learn.py:search_microsoft_learn` (stub) | 1. Search Microsoft Learn | Searches Microsoft Learn with the topic as the search text and returns the tool's decoded result, an object whose results array holds the matching articles with title and contentUrl. |
+| `pick_reading_list` | pure_function | `extracted/pick_reading_list.py:pick_reading_list` (implemented) | 2. Pick the reading list | Keeps the first 5 Microsoft Learn search results, each reduced to its title and link. |
+| `read_repo_outline` | external_call | `extracted/read_repo_outline.py:read_repo_outline` (stub) | 3. Read the repo's wiki outline | Calls the deepwiki read_wiki_structure tool for the repository and returns the wiki outline as text, as a string. |
+| `write_digest` | pure_function | `extracted/write_digest.py:write_digest` (implemented) | 4. Write the digest | Builds the markdown digest with a Reading list section of linked titles and a Repo outline section holding the wiki outline as returned. |
+
+## Crystallization log
+
+- `extracted/pick_reading_list.py` (1 skill citation(s))
+  - line 11: "Keep the first 5 results. For each, keep its title and its link."
+- `extracted/read_repo_outline.py`: 3. Read the repo's wiki outline: direct-API backend stub. (0 skill citation(s))
+- `extracted/search_microsoft_learn.py`: 1. Search Microsoft Learn: direct-API backend stub. (0 skill citation(s))
+- `extracted/write_digest.py` (2 skill citation(s))
+  - line 14: "one bullet per kept result, the title linked to its URL."
+  - line 19: "the wiki outline, as the server returned it."
+
+## Open questions
+
+### Contract: search_microsoft_learn
+
+> result shape of mslearn.microsoft_docs_search is assumed, not recorded; downstream nodes read the whole result. Run `rote baseline` against the real server to record it
+
+### Contract: read_repo_outline
+
+> result shape of deepwiki.read_wiki_structure is assumed, not recorded; downstream nodes read the whole result. Run `rote baseline` against the real server to record it
+
+
+## Suggested next steps
+
+- Review every Open question above; each assumption is a rule the skill does not state, and each low-confidence decision took a conservative default.
+- Run the pipeline once (`rote run`) and compare it with a run of the skill.
+- Recompile with `rote compile` after the skill changes. The skeleton is a model's answer (claude-haiku-5-5's structure pass), checked by code, so two compiles of one skill can differ: compare `system1/skeleton.yaml` between runs before trusting a diff.
+
+## rote verification
+
+- Generated tests: passed (11 passed in 0.01s), run in an OS sandbox.
+- Implemented impl nodes: 2 of 4.
+- Unresolved problems: 0.
+- Assumptions the skill does not state: 0.
+- Deterministic prefix on the sample input: 0 of 4 node(s) ran on the sample input (2 no recording, 2 not reached).
+- Tool schemas: deepwiki from a live tools/list, mslearn from a live tools/list.