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

{rhylthyme_cli_runner-0.2.2a0/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.2a0
+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
@@ -257,6 +357,16 @@ 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
@@ -421,13 +531,15 @@ and tracks that finish early. No sign-in; nothing is published.
 
 ### `rhylthyme publish`
 
-Publishes a program file as a live timeline and prints its URL. No sign-in.
+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`

{rhylthyme_cli_runner-0.2.2a0 → 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
@@ -197,6 +297,16 @@ 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
@@ -361,13 +471,15 @@ and tracks that finish early. No sign-in; nothing is published.
 
 ### `rhylthyme publish`
 
-Publishes a program file as a live timeline and prints its URL. No sign-in.
+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`

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

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="rhylthyme-cli-runner",
-    version="0.2.2a0",
+    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.2a0 → 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.2a0"
+__version__ = "0.2.3a0"
 __author__ = "Rhylthyme Team"
 __description__ = "CLI runner for Rhylthyme real-time program schedules"
 

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.3a0}/src/rhylthyme_cli_runner/remote/cli.py

@@ -386,16 +386,47 @@ def mcp_test(
         ctx.exit(1)
 
 
+MAX_PROGRAM_BYTES = 2 * 1024 * 1024
+
+
+def _fetch_bytes(url: str, limit: int = 8 * 1024 * 1024) -> bytes:
+    import urllib.request
+
+    if not url.startswith(("http://", "https://")):
+        raise ValueError("not an http(s) URL")
+    request = urllib.request.Request(url, headers={"User-Agent": "rhylthyme-cli"})
+    with urllib.request.urlopen(
+        request, timeout=60
+    ) as response:  # nosec B310 - scheme checked above
+        data = response.read(limit + 1)
+    if len(data) > limit:
+        raise ValueError(f"larger than {limit // (1024 * 1024)} MB")
+    return data
+
+
+def _read_source(source: str) -> str:
+    """The text of a program given as a file path, an http(s) URL, or `-`
+    for standard input."""
+    if source == "-":
+        return sys.stdin.read()
+    if source.startswith(("http://", "https://")):
+        return _fetch_bytes(source, MAX_PROGRAM_BYTES).decode("utf-8")
+    path = Path(source)
+    if not path.is_file():
+        raise FileNotFoundError("no such file")
+    return path.read_text()
+
+
 def _load_program(program_file: str) -> dict:
-    path = Path(program_file)
     program = None
     try:
-        if path.suffix.lower() in (".yaml", ".yml"):
+        text = _read_source(program_file)
+        if program_file.lower().split("?")[0].endswith((".yaml", ".yml")):
             import yaml
 
-            program = yaml.safe_load(path.read_text())
+            program = yaml.safe_load(text)
         else:
-            program = json.loads(path.read_text())
+            program = json.loads(text)
     except Exception as e:  # noqa: BLE001
         _fail(f"Could not read {program_file}: {e}")
     if not isinstance(program, dict) or not isinstance(program.get("tracks"), list):
@@ -439,7 +470,7 @@ def _local(iso: Optional[str]) -> str:
 
 
 @click.command("analyze")
-@click.argument("program_file", type=click.Path(exists=True, dir_okay=False))
+@click.argument("program_file", metavar="PROGRAM")
 @click.option(
     "--finish-at",
     "finish_at",
@@ -461,6 +492,8 @@ def _local(iso: Optional[str]) -> str:
 def analyze(program_file, finish_at, start_at, json_output, strict):
     """Total length, critical path, resource conflicts and clock times. No sign-in needed.
 
+    PROGRAM is a JSON or YAML file, an http(s) URL, or - for standard input.
+
     \b
     Computed by the hosted MCP server (analyze_schedule); nothing is published.
       rhylthyme analyze dinner.json --finish-at 19:00
@@ -520,7 +553,7 @@ ENV_BY_TYPE = {
 
 
 @click.command("publish")
-@click.argument("program_file", type=click.Path(exists=True, dir_okay=False))
+@click.argument("program_file", metavar="PROGRAM")
 @click.option(
     "-e",
     "--env",
@@ -539,14 +572,24 @@ ENV_BY_TYPE = {
     help="Print {url, imageUrl, makespanSeconds, warnings} as JSON.",
 )
 @click.option("-q", "--quiet", is_flag=True, help="Print only the live-timeline URL.")
-def publish(program_file, environment, open_url, json_output, quiet):
-    """Publish a program file as a live, shareable timeline. No sign-in needed.
+@click.option(
+    "--image",
+    "image_path",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Also save a PNG of the timeline here.",
+)
+def publish(program_file, environment, open_url, json_output, quiet, image_path):
+    """Publish a program as a live, shareable timeline. No sign-in needed.
+
+    PROGRAM is a JSON or YAML file, an http(s) URL, or - for standard input.
 
     \b
     The hosted MCP server validates the program first and refuses an invalid
     one, so run `rhylthyme validate` locally and fix what it reports.
       rhylthyme publish dinner.json
       rhylthyme publish blot.json -e lab -q
+      rhylthyme publish https://example.org/party.json --image party.png --open
     """
     program = _load_program(program_file)
     env = environment or ENV_BY_TYPE.get(
@@ -585,6 +628,13 @@ def publish(program_file, environment, open_url, json_output, quiet):
         click.echo(published.text.strip())
         if url:
             click.echo(f"\nLive timeline: {url}")
+    if image_path and info.get("imageUrl"):
+        try:
+            Path(image_path).write_bytes(_fetch_bytes(info["imageUrl"]))
+            if not json_output and not quiet:
+                click.echo(f"Picture: {image_path}")
+        except Exception as e:  # noqa: BLE001
+            click.echo(f"Could not save the picture: {e}", err=True)
     if open_url and url:
         webbrowser.open(url)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhylthyme-cli-runner
-Version: 0.2.2a0
+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
@@ -257,6 +357,16 @@ 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
@@ -421,13 +531,15 @@ and tracks that finish early. No sign-in; nothing is published.
 
 ### `rhylthyme publish`
 
-Publishes a program file as a live timeline and prints its URL. No sign-in.
+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`

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.3a0}/tests/test_remote.py

@@ -511,3 +511,58 @@ def test_clock_to_iso():
     assert _clock_to_iso(iso, now) == iso
     assert _clock_to_iso("25:00", now) == "25:00", "left for the server to reject"
     assert _clock_to_iso("7", now) == "7", "a bare number is not a time"
+
+
+def test_publish_and_analyze_read_a_url_or_stdin(
+    fake_mcp, config_home, tmp_path, monkeypatch
+):
+    import threading
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    class Files(BaseHTTPRequestHandler):
+        def log_message(self, *a):
+            pass
+
+        def do_GET(self):
+            if self.path == "/dinner.json":
+                body, status = json.dumps(PROGRAM).encode(), 200
+            elif self.path == "/timeline.png":
+                body, status = b"\x89PNG fake", 200
+            else:
+                body, status = b"nope", 404
+            self.send_response(status)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+    server = HTTPServer(("127.0.0.1", 0), Files)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    base = f"http://127.0.0.1:{server.server_address[1]}"
+    try:
+        from_url = CliRunner().invoke(cli, ["publish", f"{base}/dinner.json", "-q"])
+        assert from_url.exit_code == 0, from_url.output
+        assert from_url.output.strip() == "https://kitchen.rhylthyme.com?share=abc"
+        assert fake_mcp.tool_calls()[-1][2]["program"]["programId"] == "dinner"
+
+        piped = CliRunner().invoke(cli, ["analyze", "-"], input=json.dumps(PROGRAM))
+        assert piped.exit_code == 0, piped.output
+        assert fake_mcp.tool_calls()[-1][1] == "analyze_schedule"
+
+        missing = CliRunner().invoke(cli, ["publish", f"{base}/nope.json"])
+        assert missing.exit_code != 0 and "404" in missing.output
+        assert (
+            CliRunner()
+            .invoke(cli, ["publish", str(tmp_path / "absent.json")])
+            .exit_code
+            != 0
+        )
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+def test_clock_and_sources_reject_other_schemes():
+    from rhylthyme_cli_runner.remote.cli import _fetch_bytes
+
+    with pytest.raises(ValueError):
+        _fetch_bytes("file:///etc/passwd")

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.3a0}/tests/test_skill.py

@@ -69,3 +69,14 @@ def test_every_command_the_skill_names_exists():
     assert {"validate", "analyze", "publish", "run", "calibrate", "generate"} <= named
     missing = named - set(cli.commands)
     assert not missing, missing
+
+
+def test_the_readme_recipe_program_is_valid_and_is_what_the_readme_shows():
+    root = SKILL.parent.parent
+    recipe = root / "examples" / "recipe" / "birthday-party.json"
+    result = CliRunner().invoke(cli, ["validate", str(recipe), "--strict"])
+    assert result.exit_code == 0, result.output
+    readme = (root / "README.md").read_text()
+    assert "examples/recipe/birthday-party.json" in readme
+    for step in json.loads(recipe.read_text())["tracks"][0]["steps"]:
+        assert step["name"] in readme, f"README itinerary is missing {step['name']!r}"