rhylthyme-cli-runner 0.2.0a0__tar.gz → 0.2.3a0__tar.gz

{rhylthyme_cli_runner-0.2.0a0/src/rhylthyme_cli_runner.egg-info → rhylthyme_cli_runner-0.2.3a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhylthyme-cli-runner
-Version: 0.2.0a0
+Version: 0.2.3a0
 Summary: CLI runner for Rhylthyme real-time program schedules
 Home-page: https://github.com/rhylthyme/rhylthyme-cli-runner
 Author: Rhylthyme Team
@@ -69,6 +69,106 @@ rhylthyme login
 rhylthyme generate "roast chicken, potatoes and green beans for 6" -e kitchen --by 19:00 --with "one oven"
 ```
 
+## A timeline in five commands: a birthday party
+
+Parents collect at 4:00. Working backwards from that: when does the cake go in
+the oven, when do the balloons go up, and do the pizzas and the cake ever want
+the oven at the same time?
+
+```bash
+pip install rhylthyme-cli-runner
+
+# 1. a program: the party, the kitchen and the setup crew, 13 steps
+curl -sO https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.json
+
+# 2. is it well formed?
+rhylthyme validate birthday-party.json --strict
+
+# 3. any clashes, and what time does everything start if we finish at 4?
+rhylthyme analyze birthday-party.json --finish-at 16:00
+```
+
+```
+**Makespan:** 3h 10m across 3 tracks, 13 steps.
+**Critical path:** Guests arrive → Party games → Pizza → Candles and cake → Piñata, until it breaks → Party bags and goodbyes
+**Binding constraints:** step dependencies only — no resource or in-flight limit gates the critical path.
+**Peak concurrency:** 2 steps at 10:00.
+**Resource conflicts:** none.
+
+**Tracks that finish early:** Kitchen (1h 10m early), Setup crew (50m early)
+
+Start Sat 12:50, finish Sat 16:00 (local time)
+  Sat 12:50  Bake the cake
+  Sat 13:00  Balloons and banner
+  Sat 13:25  Cake cools
+  Sat 13:30  Hang the piñata
+  Sat 13:50  Guests arrive
+  Sat 14:05  Frost and decorate
+  Sat 14:20  Party games
+  Sat 14:35  Pizzas in the oven
+  Sat 14:50  Fill party bags
+  Sat 14:50  Pizza
+  Sat 15:15  Candles and cake
+  Sat 15:30  Piñata, until it breaks
+  Sat 15:45  Party bags and goodbyes
+```
+
+```bash
+# 4. a live timeline for the fridge door (or a phone): timers, cues, and you end the piñata when it breaks
+rhylthyme publish birthday-party.json --open --image party-preview.png
+
+# 5. a picture for the group chat, on the wall clock (needs Node; nothing to install)
+npx -y github:rhylthyme/rhylthyme-timeline birthday-party.json -o birthday-party.png \
+  --style web --palette vivid --label-overflow outside --start-at "$(date +%F)T12:50:00"
+```
+
+![Eighth birthday party: the party, the kitchen and the setup crew on a wall-clock axis](https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.png)
+
+The pizzas go in 15 minutes after the games *start*, so they come out as the
+games end; the party bags get filled while everyone is eating. Try
+`--finish-at 17:30`, or turn the cake into a two-hour fruitcake (`"seconds": "2h"`
+on `bake`) and `analyze` reports the clash: `oven needs 2 but max is 1 from
+1:45:00 to 2:00:00 (bake, heat-pizza)`. `rhylthyme run birthday-party.json --time-scale 60` rehearses
+the whole afternoon in the terminal at a minute per second.
+
+## This repository and rhylthyme-mcp
+
+Two repositories do related things and are easy to confuse. This one is the
+**command a person types**. [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp)
+is the **server an AI assistant talks to**.
+
+| | [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp) | [rhylthyme-cli-runner](https://github.com/rhylthyme/rhylthyme-cli-runner) |
+|---|---|---|
+| What it is | The MCP **server**: the tools an AI assistant calls | A command-line **program**: the `rhylthyme` command |
+| Who uses it | Claude, ChatGPT, Cursor or any MCP client, on a person's behalf | A person at a terminal, a script, or CI |
+| Where it runs | Hosted at `mcp.rhylthyme.com`; nothing to install | On your machine: `pip install rhylthyme-cli-runner` |
+| Language | JavaScript (Node 20+) | Python 3.12+ |
+| Input | A program the assistant builds in conversation | A program file on disk (JSON or YAML) |
+| Validate a program | `validate_program` | `rhylthyme validate` (works offline) |
+| Timing, conflicts, deadlines | `analyze_schedule` | `rhylthyme analyze` (asks the server) |
+| Publish a live timeline | `visualize_schedule` | `rhylthyme publish` (asks the server) |
+| Run a schedule with timers | no: it hands back a link to the web timeline | `rhylthyme run`, an interactive terminal runner |
+| Recorded runs, calibration | reads runs saved to an account | records runs locally; `rhylthyme runs`, `rhylthyme calibrate` |
+| Catalog search, imports, account library | yes | no |
+| Also in the repository | the `rhylthyme-mcp` PyPI package (a stdio bridge to the hosted server), the Claude plugin marketplace | the Claude skill's source, the prompt-evaluation harness and its results, `rhylthyme mcp-test` |
+
+How they fit together: this tool is one of the MCP server's clients.
+`rhylthyme analyze`, `publish`, `generate` and `mcp-test` are MCP calls to
+`mcp.rhylthyme.com`; `rhylthyme validate`, `run`, `runs` and `calibrate` never
+touch the network. Each has its own validator for the same program schema
+(Python here, JavaScript there), so a program is checked again when it is
+published.
+
+Use this repository if you have a program file and a terminal, want timers in
+the terminal, or keep run records. Use rhylthyme-mcp to connect Claude, ChatGPT
+or another assistant, or to read or self-host the server.
+
+Two names to keep apart: `rhylthyme-cli-runner` on PyPI is this tool (command
+`rhylthyme`); `rhylthyme-mcp` on PyPI is the server's stdio bridge (command
+`rhylthyme-mcp`). The program format itself is defined in
+[rhylthyme-spec](https://github.com/rhylthyme/rhylthyme-spec), with examples in
+[rhylthyme-examples](https://github.com/rhylthyme/rhylthyme-examples).
+
 ## Installation
 
 ### From Source
@@ -197,9 +297,30 @@ rhylthyme run examples/programs/breakfast_schedule.json --environment kitchen
 rhylthyme run examples/programs/breakfast_schedule.json --no-validate
 ```
 
+### Analyze and Publish a Program
+
+Neither needs an account; both are computed by the hosted MCP server.
+
+```bash
+# Total length, critical path, resource conflicts
+rhylthyme analyze examples/programs/breakfast_schedule.json
+
+# When does each step start if breakfast is at 8:30?
+rhylthyme analyze examples/programs/breakfast_schedule.json --finish-at 8:30am
+
+# A live, shareable timeline with timers; prints the URL
+rhylthyme publish examples/programs/breakfast_schedule.json
+```
+
+`validate` checks structure only. Two steps that want the only oven at the
+same time pass validation; `analyze` reports them, and `--strict` makes that
+a non-zero exit.
+
 ### Optimize a Program
 
-Create an optimized version of a program to reduce resource contention:
+`plan` is an older stagger heuristic that reads the pre-0.2 program format; on
+programs written with `stepId` and `task` (all current examples) it writes the
+program back unchanged. Use `analyze` to find contention.
 
 ```bash
 # Optimize a program and save to new file
@@ -227,6 +348,39 @@ rhylthyme validate-environments
 rhylthyme environment-info kitchen
 ```
 
+## Claude Skill
+
+[`skills/rhylthyme`](skills/rhylthyme) is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude (Claude Code, the Claude apps, the Agent SDK) to turn a
+protocol, recipe or run sheet into a validated program with this CLI, check
+it for conflicts, and hand back a live timeline. It follows the layout of
+[K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
+a `SKILL.md` plus `references/`.
+
+The easiest install is the Claude Code plugin, which also connects the hosted
+MCP server:
+
+```
+/plugin marketplace add rhylthyme/rhylthyme-mcp
+/plugin install rhylthyme@rhylthyme
+```
+
+Or copy the skill by hand:
+
+```bash
+# Claude Code, for one user
+mkdir -p ~/.claude/skills
+cp -r skills/rhylthyme ~/.claude/skills/
+
+# or for one project
+mkdir -p .claude/skills && cp -r skills/rhylthyme .claude/skills/
+```
+
+Then ask, for example, "time a Western blot so imaging is at 4 pm" or "two PCR
+protocols, one thermocycler: when do I start each?". `tests/test_skill.py`
+validates every program in the skill and checks that every command it names
+exists.
+
 ## Program File Examples
 
 ### Simple Breakfast Schedule
@@ -305,6 +459,39 @@ Environment: `RHYLTHYME_TOKEN` (access token, overrides the stored session),
 `RHYLTHYME_MCP_URL` (default `https://mcp.rhylthyme.com/mcp`),
 `RHYLTHYME_SITE_URL` (default `https://www.rhylthyme.com`).
 
+### `rhylthyme mcp-test`
+
+Smoke-tests a Rhylthyme MCP server and exits 1 if any check fails. By
+default it runs the read-only checks against all five hosted endpoints
+(`/mcp`, `/kitchen/mcp`, `/lab/mcp`, `/events/mcp`, `/gym/mcp`):
+
+| Check | What it proves |
+|---|---|
+| `initialize` | server name, protocol version, tools/resources/prompts capabilities, instructions |
+| `tools` | core tools and the endpoint's one-shot tools are listed, each with a description and schema |
+| `validate-good` / `validate-bad` | a valid program passes (including a `type: "compound"` trigger); a dangling step reference is rejected with a fix hint |
+| `analyze` | makespan, critical path and wall-clock itinerary for a known program |
+| `resources` / `prompts` | schema and guides are readable, a bundled example validates, `plan_schedule` substitutes its arguments |
+| `json-accept` | clients that do not accept SSE (`*/*`, `application/json`) get JSON, not 406 |
+| `bad-requests` | unknown method gives -32601, unknown tool gives an error, never a 5xx |
+| `login-gate` | account tools refuse without a token and point at `login` |
+| `catalog` | public search returns entries that load with a URL (empty catalog = warning) |
+| `publish` (`--publish`) | `visualize_schedule` returns a URL on the right site; the page and PNG load |
+| `generate` (`--generate`) | the model-backed `import_text` returns a program that validates (needs `login`) |
+
+```bash
+rhylthyme mcp-test                         # everything read-only
+rhylthyme mcp-test -e lab --publish        # one endpoint, plus a real share
+rhylthyme mcp-test -k catalog -k tools     # only some checks
+rhylthyme mcp-test --url http://localhost:3000/mcp -e generic
+rhylthyme mcp-test --json --strict         # cron / CI: warnings fail too
+```
+
+Requests carry `mcp-test` in the User-Agent so the hosted server logs the
+errors these checks provoke without alerting anyone. The same suite is
+importable (`rhylthyme_cli_runner.remote.checks.run_suite`), and
+`RHYLTHYME_MCP_LIVE=1 pytest tests/test_mcp_checks.py` runs it live.
+
 ### `rhylthyme login` / `logout` / `whoami`
 
 `login` opens the rhylthyme.com sign-in page and receives the session on a
@@ -331,9 +518,35 @@ Runs programs with interactive terminal UI.
 - `--validate / --no-validate`: Validate before running (default: True)
 - `--auto-start`: Automatically start without manual trigger
 
+### `rhylthyme analyze`
+
+Total length, critical path, what gates each link of it, resource conflicts
+and tracks that finish early. No sign-in; nothing is published.
+
+**Options:**
+- `--finish-at TEXT`: when everything must be finished (`19:00`, `7:30pm` or ISO 8601); prints local clock times per step
+- `--start-at TEXT`: when the program starts; ignored with `--finish-at`
+- `--strict`: exit non-zero when there are resource conflicts
+- `--json`: the full analysis
+
+### `rhylthyme publish`
+
+Publishes a program (a file, an http(s) URL, or `-` for standard input) as a
+live timeline and prints its URL. No sign-in.
+A published timeline is reachable by anyone who has the link.
+
+**Options:**
+- `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
+- `-q, --quiet`: print only the URL
+- `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--image PATH`: also save a PNG of the timeline
+- `--open`: open it in a browser
+
 ### `rhylthyme plan`
 
-Optimizes program schedules to reduce resource contention.
+An older stagger heuristic. It reads the pre-0.2 program format and leaves
+programs written with `stepId` and `task` unchanged; use `analyze` to find
+contention and edit the triggers.
 
 **Options:**
 - `--verbose, -v`: Show detailed planning information
@@ -614,6 +827,56 @@ make test-unit                 # excludes llm
 RHYLTHYME_EVAL_LIVE=1 pytest -m llm      # one real call, opt in
 ```
 
+
+### Other models and a spending cap
+
+`--model` also accepts models served through an OpenAI-compatible API. The
+provider is picked from the model id and the key is read from the
+environment:
+
+| Model id | Provider | Key |
+|---|---|---|
+| `claude-*` | Anthropic | `ANTHROPIC_API_KEY` |
+| `deepseek-*` (e.g. `deepseek-flash`, `deepseek-v4-pro`) | api.deepseek.com | `DEEPSEEK_API_KEY` |
+| `qwen*` | Alibaba DashScope (international) | `DASHSCOPE_API_KEY` |
+| `kimi-*`, `moonshot-*` | Moonshot | `MOONSHOT_API_KEY` |
+| `glm-*` | Z.ai | `ZAI_API_KEY` |
+| anything with a slash, e.g. `deepseek/deepseek-flash` | OpenRouter | `OPENROUTER_API_KEY` |
+| any id, with `RHYLTHYME_EVAL_BASE_URL` set | that endpoint (vLLM, Ollama, ...) | `RHYLTHYME_EVAL_API_KEY`, optional for localhost |
+
+Costs come from the price table in `eval/llm.py` (DeepSeek at its peak
+rates, so estimates are upper bounds). For a model the table does not know,
+set `RHYLTHYME_EVAL_PRICE_IN` and `RHYLTHYME_EVAL_PRICE_OUT` in USD per
+million tokens.
+
+`eval/run_model_comparison.py` runs a model under a hard budget. It runs one
+gold program at a time, both prompts per program, records each program's
+cost in `eval/models/spend-ledger.json`, and stops before the next program
+could cross `--cap`. The ledger is cumulative across models and
+invocations, and the script refuses a model with no known price (it would
+be recorded as $0 and the cap would never trip).
+
+One OpenRouter key reaches OpenAI, Qwen and Meta models (ids with a vendor
+prefix). Run the cheapest first and raise the cumulative cap as you go, so
+no single model can spend the whole allowance. Reasoning models need a
+higher per-call output ceiling than the default 16,000 tokens:
+
+```bash
+export OPENROUTER_API_KEY=...
+L=eval/models/spend-ledger-openrouter.json
+python eval/run_model_comparison.py --ledger $L --model meta-llama/llama-4-maverick --cap 0.80 --first-guess 0.05
+python eval/run_model_comparison.py --ledger $L --model qwen/qwen3.8-flash --cap 2.00 --first-guess 0.08 --max-tokens 64000
+python eval/run_model_comparison.py --ledger $L --model openai/gpt-5.6-luna --cap 4.50 --first-guess 0.15 --max-tokens 64000
+python eval/compare_models.py
+```
+
+```bash
+export DEEPSEEK_API_KEY=...
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70 --dry-run
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70
+python eval/compare_models.py        # like-for-like table across every model run so far
+```
+
 ## Development
 
 1. Clone the repository

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.3a0}/README.md

@@ -9,6 +9,106 @@ rhylthyme login
 rhylthyme generate "roast chicken, potatoes and green beans for 6" -e kitchen --by 19:00 --with "one oven"
 ```
 
+## A timeline in five commands: a birthday party
+
+Parents collect at 4:00. Working backwards from that: when does the cake go in
+the oven, when do the balloons go up, and do the pizzas and the cake ever want
+the oven at the same time?
+
+```bash
+pip install rhylthyme-cli-runner
+
+# 1. a program: the party, the kitchen and the setup crew, 13 steps
+curl -sO https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.json
+
+# 2. is it well formed?
+rhylthyme validate birthday-party.json --strict
+
+# 3. any clashes, and what time does everything start if we finish at 4?
+rhylthyme analyze birthday-party.json --finish-at 16:00
+```
+
+```
+**Makespan:** 3h 10m across 3 tracks, 13 steps.
+**Critical path:** Guests arrive → Party games → Pizza → Candles and cake → Piñata, until it breaks → Party bags and goodbyes
+**Binding constraints:** step dependencies only — no resource or in-flight limit gates the critical path.
+**Peak concurrency:** 2 steps at 10:00.
+**Resource conflicts:** none.
+
+**Tracks that finish early:** Kitchen (1h 10m early), Setup crew (50m early)
+
+Start Sat 12:50, finish Sat 16:00 (local time)
+  Sat 12:50  Bake the cake
+  Sat 13:00  Balloons and banner
+  Sat 13:25  Cake cools
+  Sat 13:30  Hang the piñata
+  Sat 13:50  Guests arrive
+  Sat 14:05  Frost and decorate
+  Sat 14:20  Party games
+  Sat 14:35  Pizzas in the oven
+  Sat 14:50  Fill party bags
+  Sat 14:50  Pizza
+  Sat 15:15  Candles and cake
+  Sat 15:30  Piñata, until it breaks
+  Sat 15:45  Party bags and goodbyes
+```
+
+```bash
+# 4. a live timeline for the fridge door (or a phone): timers, cues, and you end the piñata when it breaks
+rhylthyme publish birthday-party.json --open --image party-preview.png
+
+# 5. a picture for the group chat, on the wall clock (needs Node; nothing to install)
+npx -y github:rhylthyme/rhylthyme-timeline birthday-party.json -o birthday-party.png \
+  --style web --palette vivid --label-overflow outside --start-at "$(date +%F)T12:50:00"
+```
+
+![Eighth birthday party: the party, the kitchen and the setup crew on a wall-clock axis](https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.png)
+
+The pizzas go in 15 minutes after the games *start*, so they come out as the
+games end; the party bags get filled while everyone is eating. Try
+`--finish-at 17:30`, or turn the cake into a two-hour fruitcake (`"seconds": "2h"`
+on `bake`) and `analyze` reports the clash: `oven needs 2 but max is 1 from
+1:45:00 to 2:00:00 (bake, heat-pizza)`. `rhylthyme run birthday-party.json --time-scale 60` rehearses
+the whole afternoon in the terminal at a minute per second.
+
+## This repository and rhylthyme-mcp
+
+Two repositories do related things and are easy to confuse. This one is the
+**command a person types**. [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp)
+is the **server an AI assistant talks to**.
+
+| | [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp) | [rhylthyme-cli-runner](https://github.com/rhylthyme/rhylthyme-cli-runner) |
+|---|---|---|
+| What it is | The MCP **server**: the tools an AI assistant calls | A command-line **program**: the `rhylthyme` command |
+| Who uses it | Claude, ChatGPT, Cursor or any MCP client, on a person's behalf | A person at a terminal, a script, or CI |
+| Where it runs | Hosted at `mcp.rhylthyme.com`; nothing to install | On your machine: `pip install rhylthyme-cli-runner` |
+| Language | JavaScript (Node 20+) | Python 3.12+ |
+| Input | A program the assistant builds in conversation | A program file on disk (JSON or YAML) |
+| Validate a program | `validate_program` | `rhylthyme validate` (works offline) |
+| Timing, conflicts, deadlines | `analyze_schedule` | `rhylthyme analyze` (asks the server) |
+| Publish a live timeline | `visualize_schedule` | `rhylthyme publish` (asks the server) |
+| Run a schedule with timers | no: it hands back a link to the web timeline | `rhylthyme run`, an interactive terminal runner |
+| Recorded runs, calibration | reads runs saved to an account | records runs locally; `rhylthyme runs`, `rhylthyme calibrate` |
+| Catalog search, imports, account library | yes | no |
+| Also in the repository | the `rhylthyme-mcp` PyPI package (a stdio bridge to the hosted server), the Claude plugin marketplace | the Claude skill's source, the prompt-evaluation harness and its results, `rhylthyme mcp-test` |
+
+How they fit together: this tool is one of the MCP server's clients.
+`rhylthyme analyze`, `publish`, `generate` and `mcp-test` are MCP calls to
+`mcp.rhylthyme.com`; `rhylthyme validate`, `run`, `runs` and `calibrate` never
+touch the network. Each has its own validator for the same program schema
+(Python here, JavaScript there), so a program is checked again when it is
+published.
+
+Use this repository if you have a program file and a terminal, want timers in
+the terminal, or keep run records. Use rhylthyme-mcp to connect Claude, ChatGPT
+or another assistant, or to read or self-host the server.
+
+Two names to keep apart: `rhylthyme-cli-runner` on PyPI is this tool (command
+`rhylthyme`); `rhylthyme-mcp` on PyPI is the server's stdio bridge (command
+`rhylthyme-mcp`). The program format itself is defined in
+[rhylthyme-spec](https://github.com/rhylthyme/rhylthyme-spec), with examples in
+[rhylthyme-examples](https://github.com/rhylthyme/rhylthyme-examples).
+
 ## Installation
 
 ### From Source
@@ -137,9 +237,30 @@ rhylthyme run examples/programs/breakfast_schedule.json --environment kitchen
 rhylthyme run examples/programs/breakfast_schedule.json --no-validate
 ```
 
+### Analyze and Publish a Program
+
+Neither needs an account; both are computed by the hosted MCP server.
+
+```bash
+# Total length, critical path, resource conflicts
+rhylthyme analyze examples/programs/breakfast_schedule.json
+
+# When does each step start if breakfast is at 8:30?
+rhylthyme analyze examples/programs/breakfast_schedule.json --finish-at 8:30am
+
+# A live, shareable timeline with timers; prints the URL
+rhylthyme publish examples/programs/breakfast_schedule.json
+```
+
+`validate` checks structure only. Two steps that want the only oven at the
+same time pass validation; `analyze` reports them, and `--strict` makes that
+a non-zero exit.
+
 ### Optimize a Program
 
-Create an optimized version of a program to reduce resource contention:
+`plan` is an older stagger heuristic that reads the pre-0.2 program format; on
+programs written with `stepId` and `task` (all current examples) it writes the
+program back unchanged. Use `analyze` to find contention.
 
 ```bash
 # Optimize a program and save to new file
@@ -167,6 +288,39 @@ rhylthyme validate-environments
 rhylthyme environment-info kitchen
 ```
 
+## Claude Skill
+
+[`skills/rhylthyme`](skills/rhylthyme) is an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude (Claude Code, the Claude apps, the Agent SDK) to turn a
+protocol, recipe or run sheet into a validated program with this CLI, check
+it for conflicts, and hand back a live timeline. It follows the layout of
+[K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
+a `SKILL.md` plus `references/`.
+
+The easiest install is the Claude Code plugin, which also connects the hosted
+MCP server:
+
+```
+/plugin marketplace add rhylthyme/rhylthyme-mcp
+/plugin install rhylthyme@rhylthyme
+```
+
+Or copy the skill by hand:
+
+```bash
+# Claude Code, for one user
+mkdir -p ~/.claude/skills
+cp -r skills/rhylthyme ~/.claude/skills/
+
+# or for one project
+mkdir -p .claude/skills && cp -r skills/rhylthyme .claude/skills/
+```
+
+Then ask, for example, "time a Western blot so imaging is at 4 pm" or "two PCR
+protocols, one thermocycler: when do I start each?". `tests/test_skill.py`
+validates every program in the skill and checks that every command it names
+exists.
+
 ## Program File Examples
 
 ### Simple Breakfast Schedule
@@ -245,6 +399,39 @@ Environment: `RHYLTHYME_TOKEN` (access token, overrides the stored session),
 `RHYLTHYME_MCP_URL` (default `https://mcp.rhylthyme.com/mcp`),
 `RHYLTHYME_SITE_URL` (default `https://www.rhylthyme.com`).
 
+### `rhylthyme mcp-test`
+
+Smoke-tests a Rhylthyme MCP server and exits 1 if any check fails. By
+default it runs the read-only checks against all five hosted endpoints
+(`/mcp`, `/kitchen/mcp`, `/lab/mcp`, `/events/mcp`, `/gym/mcp`):
+
+| Check | What it proves |
+|---|---|
+| `initialize` | server name, protocol version, tools/resources/prompts capabilities, instructions |
+| `tools` | core tools and the endpoint's one-shot tools are listed, each with a description and schema |
+| `validate-good` / `validate-bad` | a valid program passes (including a `type: "compound"` trigger); a dangling step reference is rejected with a fix hint |
+| `analyze` | makespan, critical path and wall-clock itinerary for a known program |
+| `resources` / `prompts` | schema and guides are readable, a bundled example validates, `plan_schedule` substitutes its arguments |
+| `json-accept` | clients that do not accept SSE (`*/*`, `application/json`) get JSON, not 406 |
+| `bad-requests` | unknown method gives -32601, unknown tool gives an error, never a 5xx |
+| `login-gate` | account tools refuse without a token and point at `login` |
+| `catalog` | public search returns entries that load with a URL (empty catalog = warning) |
+| `publish` (`--publish`) | `visualize_schedule` returns a URL on the right site; the page and PNG load |
+| `generate` (`--generate`) | the model-backed `import_text` returns a program that validates (needs `login`) |
+
+```bash
+rhylthyme mcp-test                         # everything read-only
+rhylthyme mcp-test -e lab --publish        # one endpoint, plus a real share
+rhylthyme mcp-test -k catalog -k tools     # only some checks
+rhylthyme mcp-test --url http://localhost:3000/mcp -e generic
+rhylthyme mcp-test --json --strict         # cron / CI: warnings fail too
+```
+
+Requests carry `mcp-test` in the User-Agent so the hosted server logs the
+errors these checks provoke without alerting anyone. The same suite is
+importable (`rhylthyme_cli_runner.remote.checks.run_suite`), and
+`RHYLTHYME_MCP_LIVE=1 pytest tests/test_mcp_checks.py` runs it live.
+
 ### `rhylthyme login` / `logout` / `whoami`
 
 `login` opens the rhylthyme.com sign-in page and receives the session on a
@@ -271,9 +458,35 @@ Runs programs with interactive terminal UI.
 - `--validate / --no-validate`: Validate before running (default: True)
 - `--auto-start`: Automatically start without manual trigger
 
+### `rhylthyme analyze`
+
+Total length, critical path, what gates each link of it, resource conflicts
+and tracks that finish early. No sign-in; nothing is published.
+
+**Options:**
+- `--finish-at TEXT`: when everything must be finished (`19:00`, `7:30pm` or ISO 8601); prints local clock times per step
+- `--start-at TEXT`: when the program starts; ignored with `--finish-at`
+- `--strict`: exit non-zero when there are resource conflicts
+- `--json`: the full analysis
+
+### `rhylthyme publish`
+
+Publishes a program (a file, an http(s) URL, or `-` for standard input) as a
+live timeline and prints its URL. No sign-in.
+A published timeline is reachable by anyone who has the link.
+
+**Options:**
+- `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
+- `-q, --quiet`: print only the URL
+- `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--image PATH`: also save a PNG of the timeline
+- `--open`: open it in a browser
+
 ### `rhylthyme plan`
 
-Optimizes program schedules to reduce resource contention.
+An older stagger heuristic. It reads the pre-0.2 program format and leaves
+programs written with `stepId` and `task` unchanged; use `analyze` to find
+contention and edit the triggers.
 
 **Options:**
 - `--verbose, -v`: Show detailed planning information
@@ -554,6 +767,56 @@ make test-unit                 # excludes llm
 RHYLTHYME_EVAL_LIVE=1 pytest -m llm      # one real call, opt in
 ```
 
+
+### Other models and a spending cap
+
+`--model` also accepts models served through an OpenAI-compatible API. The
+provider is picked from the model id and the key is read from the
+environment:
+
+| Model id | Provider | Key |
+|---|---|---|
+| `claude-*` | Anthropic | `ANTHROPIC_API_KEY` |
+| `deepseek-*` (e.g. `deepseek-flash`, `deepseek-v4-pro`) | api.deepseek.com | `DEEPSEEK_API_KEY` |
+| `qwen*` | Alibaba DashScope (international) | `DASHSCOPE_API_KEY` |
+| `kimi-*`, `moonshot-*` | Moonshot | `MOONSHOT_API_KEY` |
+| `glm-*` | Z.ai | `ZAI_API_KEY` |
+| anything with a slash, e.g. `deepseek/deepseek-flash` | OpenRouter | `OPENROUTER_API_KEY` |
+| any id, with `RHYLTHYME_EVAL_BASE_URL` set | that endpoint (vLLM, Ollama, ...) | `RHYLTHYME_EVAL_API_KEY`, optional for localhost |
+
+Costs come from the price table in `eval/llm.py` (DeepSeek at its peak
+rates, so estimates are upper bounds). For a model the table does not know,
+set `RHYLTHYME_EVAL_PRICE_IN` and `RHYLTHYME_EVAL_PRICE_OUT` in USD per
+million tokens.
+
+`eval/run_model_comparison.py` runs a model under a hard budget. It runs one
+gold program at a time, both prompts per program, records each program's
+cost in `eval/models/spend-ledger.json`, and stops before the next program
+could cross `--cap`. The ledger is cumulative across models and
+invocations, and the script refuses a model with no known price (it would
+be recorded as $0 and the cap would never trip).
+
+One OpenRouter key reaches OpenAI, Qwen and Meta models (ids with a vendor
+prefix). Run the cheapest first and raise the cumulative cap as you go, so
+no single model can spend the whole allowance. Reasoning models need a
+higher per-call output ceiling than the default 16,000 tokens:
+
+```bash
+export OPENROUTER_API_KEY=...
+L=eval/models/spend-ledger-openrouter.json
+python eval/run_model_comparison.py --ledger $L --model meta-llama/llama-4-maverick --cap 0.80 --first-guess 0.05
+python eval/run_model_comparison.py --ledger $L --model qwen/qwen3.8-flash --cap 2.00 --first-guess 0.08 --max-tokens 64000
+python eval/run_model_comparison.py --ledger $L --model openai/gpt-5.6-luna --cap 4.50 --first-guess 0.15 --max-tokens 64000
+python eval/compare_models.py
+```
+
+```bash
+export DEEPSEEK_API_KEY=...
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70 --dry-run
+python eval/run_model_comparison.py --model deepseek-flash --cap 6.70
+python eval/compare_models.py        # like-for-like table across every model run so far
+```
+
 ## Development
 
 1. Clone the repository

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.3a0}/setup.py

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="rhylthyme-cli-runner",
-    version="0.2.0a0",
+    version="0.2.3a0",
     description="CLI runner for Rhylthyme real-time program schedules",
     long_description=read_readme(),
     long_description_content_type="text/markdown",

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.3a0}/src/rhylthyme_cli_runner/__init__.py

@@ -6,7 +6,7 @@ This package provides the command-line interface for running and validating
 Rhylthyme real-time program schedules.
 """
 
-__version__ = "0.2.0a0"
+__version__ = "0.2.3a0"
 __author__ = "Rhylthyme Team"
 __description__ = "CLI runner for Rhylthyme real-time program schedules"
 

{rhylthyme_cli_runner-0.2.0a0 → rhylthyme_cli_runner-0.2.3a0}/src/rhylthyme_cli_runner/eval/cli.py

@@ -321,7 +321,10 @@ def _live(
     if fake_client_path:
         with open(fake_client_path, "r", encoding="utf-8") as handle:
             fake_responses = json.load(handle)
-    client = make_client(fake_responses)
+    try:
+        client = make_client(fake_responses, model=model)
+    except RuntimeError as exc:
+        raise click.UsageError(str(exc))
 
     gold_set = _load_gold(gold_dir)
     out_root = Path(out_dir)