readme2demo 0.7.1__tar.gz

readme2demo-0.7.1/.claude/agents/grounding-auditor.md

@@ -0,0 +1,43 @@
+---
+name: grounding-auditor
+description: Audit code or prompt changes against readme2demo's grounding invariant before commit. Use PROACTIVELY after any change touching distill.py, tutorial.py, normalize.py, engines/, prompts/, or templates/ — anything on the path between the LLM and the published artifacts.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the guardian of readme2demo's core invariant:
+
+> The LLM never publishes anything a fresh container didn't independently
+> execute. Grounding is enforced in code, not prompts.
+
+Given a diff or a set of changed files, answer ONE question: can any command
+or output now reach a published artifact (tutorial.md, step_by_step.md,
+commands.sh, demo.tape, howto.jsonld) without being backed by the agent log
+or the verify replay?
+
+## Checklist
+
+1. `distill.py`: every path into `commands.sh`/`demo.tape` still passes
+   through `is_grounded`/`validate_grounding` or an explicitly documented
+   exception (`cd`, comments, harness clone, pipe variants, heredoc prefixes,
+   findings_success entries). New equivalences must be SYMMETRIC in
+   `normalize_cmd`/`_grounded_candidates` and regression-tested both ways
+   (grounded variant accepted, unproven command still rejected).
+2. `tutorial.py`: `enforce_commands` still restores every command AND
+   expected_output from the grounded outline after the LLM polish pass;
+   expected outputs come from verify.log or the agent log, never the model.
+3. `normalize.py` + `engines/*`: parsing stays pure/deterministic (no LLM
+   calls); `mark_findings_success` only marks entries matching BOTH the
+   success command and the expected pattern.
+4. Prompt-only fixes: reject them. A prompt change without a corresponding
+   code-level check or test is not a defense (search the diff for prompt
+   edits lacking sibling code/test changes).
+5. `sandbox.py`: hardening flags intact (--cap-drop ALL, no-new-privileges,
+   limits, non-root); docker-socket mounting stays opt-in.
+6. Run `python -m pytest tests/ -q` and report the count.
+
+## Report format
+
+- **Verdict**: PASS / FAIL (+ the specific leak path if FAIL).
+- **Weakened checks**: any check made more permissive, with justification
+  status (documented + tested, or not).
+- **Missing regression tests**: for each behavior change.

readme2demo-0.7.1/.claude/agents/run-debugger.md

@@ -0,0 +1,46 @@
+---
+name: run-debugger
+description: Diagnose a failed or unverified readme2demo run directory. Use PROACTIVELY whenever a pipeline run fails, verify doesn't pass, a video comes out short/incomplete, or generated docs are missing steps. Input should include the runs/<run-id> path.
+tools: Read, Grep, Glob, Bash
+---
+
+You diagnose failed readme2demo runs. You are read-mostly: produce a precise
+diagnosis and a repair plan; only write files when explicitly asked to repair.
+
+## Procedure
+
+1. Read `manifest.json` in the run dir: which stage failed/skipped, stage
+   `meta` (outcome, adjusted_success, source_modified,
+   guide_steps_unattempted, tape_coverage), `verified`, total cost.
+2. Read the failing stage's evidence:
+   - verify failures → `verify.log` (find `===== ATTEMPT n =====` markers,
+     read the tail of the LAST attempt; the line after the final `+ cmd`
+     trace is where it died) and `commands.sh`.
+   - agent failures → `command_log.json`: filter entries by exit_code,
+     read outputs of the failures; check `fixes`, `adjusted_success_command`,
+     `file_edits`.
+   - render failures → the RenderError text, `demo.tape`, tape vs
+     `expected_min_duration_s`.
+   - doc-quality complaints → `step_by_step.md` / `tutorial.md` vs
+     `command_log.json`: which proven commands are missing from the docs?
+3. Match against the "Known failure classes" table in CLAUDE.md — most
+   failures are a recurrence or a sibling of a known class. Name the class.
+4. If it is genuinely new: state the mechanism (what state/assumption
+   diverged between the agent container and the verify/render container),
+   which module owns it, and what code-level defense would have caught it.
+
+## Report format
+
+- **Verdict**: one sentence — what failed and why.
+- **Class**: known-class number from CLAUDE.md, or "NEW".
+- **Evidence**: 2-4 quoted lines from logs.
+- **Systemic fix**: file + function to change (code first; prompt second).
+- **Run repair**: the cheapest way to salvage THIS run (patch commands.sh /
+  plan.json / regenerate guide+tape via the pure functions in distill.py and
+  tutorial.py) and the exact `readme2demo resume <run> --from-stage <s>`
+  command. Never suggest re-running the agent when a downstream repair works.
+
+Key fact for repairs: distill/tutorial artifact writers
+(`write_step_by_step`, `tape_from_guide`, `write_tape`) are pure functions —
+they can regenerate a run's guide and tape from `command_log.json` +
+`plan.json` without any LLM cost.

readme2demo-0.7.1/.claude/commands/ship-check.md

@@ -0,0 +1,22 @@
+---
+description: Pre-commit gauntlet for readme2demo — invariant audit, tests, hygiene
+---
+
+Run the pre-commit gauntlet on the current working tree:
+
+1. Run `python -m pytest tests/ -q` — must be fully green.
+2. `python -m compileall -q src/` — must be clean.
+3. Use the grounding-auditor agent on the staged/changed files if anything
+   under src/readme2demo/{distill,tutorial,normalize,engines,prompts,templates}
+   changed.
+4. Hygiene greps: no `runs/` paths staged (`git status --short | grep runs/`
+   must be empty), no credentials
+   (`git diff --cached | grep -iE 'sk-ant-[a-z0-9]{8}'` empty).
+5. If prompts/*.md changed: confirm the change has a sibling code check or
+   test, and note which real run motivated it.
+6. If images/base/Dockerfile changed: remind that users must rebuild
+   (`docker build --no-cache -t readme2demo/base:latest images/base/`) and
+   check the Claude Code pin ↔ stream-json parser coupling.
+7. Report: test count, files changed by area, any CLAUDE.md failure-class
+   entries that should be added for this change, and a suggested
+   conventional commit message.

readme2demo-0.7.1/.claude/skills/add-engine/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: add-engine
+description: Add a new AI agent backend (engine) to readme2demo, or fix parsing for an existing one (claude-code stream-json drift, openhands trajectory changes). Use when adding support for a new coding agent or when transcripts stop parsing after an agent CLI upgrade.
+---
+
+# Adding or fixing an agent engine
+
+Engines are the ONLY place that knows which AI agent ran. Everything
+downstream consumes `command_log.json`.
+
+## The contract (`engines/base.py`)
+
+Implement `AgentEngine` and decorate with `@register`:
+
+- `name`: CLI value for `--engine`.
+- `required_env()` / `resolve_env()`: host env vars forwarded into the
+  sandbox at exec time (never baked into images). Support alternative auth
+  by overriding `resolve_env` (see ClaudeCodeEngine's key-OR-oauth-token,
+  including the credential-format validation — copy it).
+- `build_command(limits)`: one shell string run via `bash -lc` inside the
+  container; reads the prompt from `PROMPT_CONTAINER_PATH`, writes the raw
+  transcript to `TRANSCRIPT_CONTAINER_PATH`, stderr next to it.
+- `parse_transcript(path) -> CommandLog`: PURE, deterministic, no LLM calls,
+  tolerant of malformed lines and schema drift. Reuse `truncate_output`,
+  `scan_markers`, `scan_adjusted` from `claude_code.py` so markers and
+  truncation behave identically across engines.
+
+## Parsing requirements
+
+- Pair command events with their results; unpaired commands get
+  `exit_code=None` (never fabricate 0).
+- Extract: Bash-equivalent commands + outputs (head 3KB + tail 1KB
+  truncation), file edits, FIX/BLOCKED/ADJUSTED_SUCCESS markers, outcome
+  (blocked > success-marker > failed), cost/turns/duration when available
+  (None when not — budget logic treats None as unknown, not zero).
+
+## Checklist
+
+1. `engines/<name>.py` with the above; module docstring stating the
+   transcript format assumptions and its drift-tolerance strategy.
+2. Fixture transcript in `tests/fixtures/` exercising: success + failure
+   pairs, a marker, a malformed line, string-vs-list content shapes.
+3. Tests: parse the fixture, verify counts/exit codes/markers/outcome;
+   missing-env EngineError; build_command shape (uses the canonical
+   container paths, not hardcoded strings).
+4. If the format VERSION is coupled to a pinned CLI in
+   `images/base/Dockerfile`, bump pin and parser together and say so in the
+   commit message.
+5. README: add the engine to the auth/requirements section.
+
+## Known drift landmines
+
+- claude-code stream-json: `tool_result.content` is a string OR a list of
+  text blocks; the final `result` event can be absent when the agent is
+  killed (marker alone then decides success).
+- openhands trajectories: JSON array, `{"events": [...]}` wrapper, or JSONL
+  — detect all three.

readme2demo-0.7.1/.claude/skills/add-failure-class/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: add-failure-class
+description: The workflow for turning a newly diagnosed readme2demo run failure into a permanent, tested defense. Use after debug-run identifies a failure mechanism that is not yet in CLAUDE.md's known-failure-classes table.
+---
+
+# Adding a failure class (the maintenance meta-workflow)
+
+Every robustness feature in this repo came from a real failed run processed
+through exactly these steps. Do them in order; skipping the test or the
+CLAUDE.md entry is how knowledge evaporates.
+
+## Steps
+
+1. **Name the mechanism, not the symptom.** "verify exit 1" is a symptom;
+   "findings tools exit nonzero on success and set -e kills the assertion"
+   is a mechanism. You must be able to say which two components disagreed
+   about an assumption.
+
+2. **Pick the owning module** (one, occasionally two):
+   - agent behavior → `prompts/agent.md` rule AND a detector in
+     `normalize.py` (rule 6 + repo_files_edited is the template)
+   - command equivalence → `distill.normalize_cmd` / `_grounded_candidates`
+     (always symmetric, both directions tested)
+   - replay semantics → `distill._render_commands_sh` (assertion block) or
+     `verify.py`
+   - video → `templates/demo.tape.j2` / `render.py` gates
+   - parsing → the engine adapter, kept pure and tolerant
+
+3. **Code first, prompt second.** If the fix involves an LLM behaving
+   differently, the prompt edit gets a sibling code-level check or
+   validation — prompts alone are not defenses.
+
+4. **Regression test named for the run.** Docstring starts with
+   `"""Regression (<repo> run): ..."""` describing the real failure. Must
+   fail on the old code. Tests stay free of docker/network/API.
+
+5. **Repair the triggering run cheaply** (see debug-run skill) and give the
+   exact resume command.
+
+6. **Document**: add a numbered entry to CLAUDE.md "Known failure classes"
+   (symptom → mechanism → defense location). If the class is user-visible,
+   consider a line in README or the troubleshooting-relevant prompt.
+
+7. **Full suite green** (`python -m pytest tests/ -q`) before claiming done.
+
+## Quality bar for grounding changes
+
+New equivalences (like the 2>&1 or pipe-variant rules) must:
+- apply to BOTH the candidate set and the queried command (symmetry),
+- never make an unproven command grounded (add a negative test: the evil
+  variant is still rejected),
+- be documented in the `is_grounded` docstring's accepted-forms list.

readme2demo-0.7.1/.claude/skills/debug-run/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: debug-run
+description: Debug a failed, unverified, or low-quality readme2demo pipeline run. Use when a run fails at any stage, verify won't pass, the demo video is short or missing steps, generated docs lack detail, or the user pastes readme2demo CLI output showing a failure.
+---
+
+# Debugging a readme2demo run
+
+Every run leaves complete evidence in `runs/<run-id>/`. Read evidence before
+theorizing — the answer is almost always in three files.
+
+## Evidence map
+
+| File | Tells you |
+|---|---|
+| `manifest.json` | which stage failed, stage meta (outcome, adjusted_success, source_modified, guide_steps_unattempted, tape_coverage), verified flag, cost |
+| `command_log.json` | every command the agent ran, exit codes, outputs, FIX markers, findings_success flags |
+| `verify.log` | the clean-container replay, bash -x traced; last `+ cmd` before silence = point of death; `===== ATTEMPT n =====` separates tries |
+| `commands.sh` | what verify executed — preamble (harness clone), steps, assertion block |
+| `step_by_step.md` + `tape_coverage.json` | what made the docs/video and what was dropped (with reasons) |
+| `transcript.ndjson` | raw agent stream (only needed for parser bugs) |
+
+## Decision tree
+
+1. **ingest failed** → planner/LLM issue or infeasible repo (read plan.json
+   blockers). Infeasible is often CORRECT behavior.
+2. **agent failed/blocked** → read final assistant text in command_log
+   result + failed entries. Check for the cutoff-denial pattern ("X isn't
+   released yet") and infrastructure rabbit holes (fake sockets). Blocked
+   for credentials/GPU is correct behavior.
+3. **distill failed (ungrounded)** → compare the rejected command against
+   the log: usually a syntax-equivalence gap (whitespace, 2>&1, env prefix,
+   chain, pipe-cap, heredoc body). Fix in `normalize_cmd` /
+   `_grounded_candidates` symmetrically, never by weakening validation.
+4. **verify failed** → tail the last attempt in verify.log. Common causes in
+   order: missing setup step, cwd drift (run `verify.cwd_hints` on the
+   script), findings-tool nonzero exit reaching `set -e`, wrong
+   expected_pattern, agent had patched source (manifest source_modified).
+5. **render failed** → duration gate (steps didn't play → stale image or
+   tape bug), VHS parse error (quoting), disk exhaustion (docker system
+   prune), socket permissions if the tape manages containers.
+6. **docs/video missing steps** → `tape_coverage.json` dropped list +
+   normalize's guide_steps_unattempted meta. Unattempted = agent never ran
+   it (needs fresh agent run); dropped = grounding gap (fixable + tape
+   regenerable without LLM).
+
+## Cheap repairs (no agent re-run)
+
+The artifact writers are pure functions. From the repo root:
+
+```python
+# regenerate guide + tape for an existing run after a code fix
+PYTHONPATH=src python3 - <<'EOF'
+from pathlib import Path
+from readme2demo.distill import tape_from_guide, write_tape
+from readme2demo.tutorial import write_step_by_step
+from readme2demo.types import CommandLog, Plan, TutorialOutline
+rd = Path("runs/<run-id>")
+plan = Plan.model_validate_json((rd/"plan.json").read_text())
+log = CommandLog.model_validate_json((rd/"command_log.json").read_text())
+outline = TutorialOutline.model_validate_json((rd/"tutorial_outline.json").read_text())
+write_step_by_step(rd, plan, outline, log, verified=False, repo_url="<url>")
+write_tape(tape_from_guide((rd/"step_by_step.md").read_text(), log, [], "<url>"), rd)
+EOF
+```
+
+`commands.sh` and `plan.json` can be patched by hand for one run; then
+`readme2demo resume runs/<run-id> --from-stage <verify|render|tutorial>`.
+Resume from the EARLIEST stage whose inputs changed, never earlier.
+
+## After the diagnosis
+
+If the cause is new, follow the add-failure-class skill: systemic code fix +
+regression test + CLAUDE.md failure-class entry. A run-specific patch without
+a systemic fix just schedules the same debugging session for the next repo.

readme2demo-0.7.1/.claude/skills/docker-sandbox/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: docker-sandbox
+description: Docker usage in readme2demo — the base image, hardened sandbox lifecycle, the Docker-socket opt-in, and diagnosing container/daemon failures. Use when touching sandbox.py, images/base/Dockerfile, render.py, verify.py, or when a run fails with a docker/daemon/permission/disk error.
+---
+
+# Docker & the sandbox
+
+The container IS the security boundary. READMEs are untrusted code; the agent
+runs INSIDE the container so `--dangerously-skip-permissions` is safe.
+
+## The base image (`images/base/Dockerfile`)
+
+- Built FROM `ghcr.io/charmbracelet/vhs:latest` so ONE image serves the agent
+  run, the verify replay, AND the video render (vhs + ttyd + ffmpeg from the
+  base; git/Go/Python/Node + Claude Code added on top). This is why the video
+  can execute real toolchain steps on camera.
+- `ENTRYPOINT []` + `CMD ["bash"]`: the VHS image ships `ENTRYPOINT ["vhs"]`;
+  reset it so `sandbox.py` can run arbitrary commands. The renderer re-invokes
+  vhs via `--entrypoint vhs`.
+- Go comes from the official tarball at build time (distro packages lag and
+  strand agents on "go >= 1.2x required"). Rebuild periodically to stay current.
+- The Claude Code npm pin is COUPLED to the stream-json parser
+  (`engines/claude_code.py`) — bump them together.
+- Rebuild after ANY Dockerfile change:
+  `docker build --no-cache -t readme2demo/base:latest images/base/`. The render
+  stage preflights the image (`render.check_render_image`) and errors clearly
+  if it's stale (missing vhs/ffmpeg/git).
+
+## Hardening (`sandbox.py` — never weaken without discussion)
+
+Every container: `--cap-drop ALL`, `--security-opt no-new-privileges`,
+`--memory/--cpus/--pids-limit`, non-root user `demo` (uid 1000), wall-clock
+timeout, destroyed after the stage. Run dirs are mounted with ABSOLUTE paths
+(docker -v treats relative as a volume name).
+
+## Docker-socket opt-in (`--allow-docker-socket`)
+
+For tools that manage containers themselves (toolhive `thv run`,
+testcontainers, compose repos). Mounts `/var/run/docker.sock` into agent +
+verify + render. The non-root user needs `--group-add $(socket gid)` —
+`sandbox.docker_socket_gid` probes it (`stat -c %g`) or every socket call is
+EACCES and the tool reports "no container runtime available" despite the mount.
+Pierces isolation: trusted repos only; the CLI prints the warning in red.
+
+## Diagnosing docker failures
+
+- `input/output error` / `containerd meta.db` → Docker VM disk full (VHS writes
+  a PNG per frame). `docker system prune -af --volumes`; restart Docker
+  Desktop; raise the VM disk. The render mitigations (24fps, mp4-only, short
+  ffmpeg gif preview) exist because full-length GIFs once filled the disk.
+- exit 125 from `docker run` → bad flags / relative mount path — check the
+  Sandbox args.
+- "no container runtime available" WITH `--allow-docker-socket` → group-add gid
+  problem (above).
+- verify passes but render image errors → stale base image; rebuild.

readme2demo-0.7.1/.claude/skills/git-github-operator/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: git-github-operator
+description: Git and GitHub operations for maintaining the readme2demo repo — branching, conventional commits, PRs, releases, and the never-commit rules. Use when committing, opening a PR, tagging a release, or doing any git/gh operation on this repo.
+---
+
+# Git & GitHub operator for readme2demo
+
+Remote: `https://github.com/alphacrack/readme2demo` (origin). Default branch:
+`main`. In non-interactive sessions you can stage/commit locally but the human
+runs `git push` (auth lives on their machine).
+
+## Never commit
+
+- `runs/` — every pipeline run (transcripts, videos, cloned repos, and
+  potentially the target repo's content). Gitignored; keep it that way.
+  Publishable examples are HAND-COPIED into `examples/` after review.
+- `.env`, `readme2demo.toml`, any credential. Before every commit:
+  `git diff --cached | grep -iE 'sk-ant-[a-z0-9]{8}'` must be empty, and
+  `git status --short | grep runs/` must be empty.
+
+## Commit style
+
+Conventional-ish, imperative subject, then a body that lists WHAT changed and
+WHY — this repo's history is a design log (read `git log` to see the bar).
+When a commit fixes a failure class, name the run that found it and note the
+regression test. One concern per commit where practical; batch tightly-coupled
+changes (code + test + CLAUDE.md entry) together.
+
+## Pre-push gate
+
+Run the `/ship-check` command (or the ship-check flow): tests green, compile
+clean, grounding-auditor on any src change touching the LLM→artifact path,
+hygiene greps. If `images/base/Dockerfile` changed, the commit body must tell
+users to rebuild (`docker build --no-cache -t readme2demo/base:latest images/base/`).
+
+## Branches & PRs
+
+- Feature work on a branch; PR into main. PR description states the failure
+  class or feature, the systemic fix (code first), and the regression test.
+- CI (`.github/workflows/ci.yml`) runs the suite on 3.10 and 3.12 — a red CI
+  blocks merge. Keep the suite docker/network/API-free so CI stays fast.
+- `good first issue` / `help wanted` labels are seeded for contributors (see
+  launch/LAUNCH_CHECKLIST.md).
+
+## Releases
+
+- Tag `vX.Y.Z` with honest notes (state the MVP tradeoffs — Docker required,
+  README treated as untrusted code, API key enters sandbox until the egress
+  proxy lands). The pinned Claude Code version in the base image is coupled to
+  the stream-json parser — call out a bump in the release notes.
+
+## Repairing a user's run without git
+
+Run dirs are disposable and gitignored. To salvage a failed run, patch its
+`commands.sh`/`plan.json` or regenerate its guide+tape with the pure functions
+(see the debug-run skill) and give the `resume --from-stage` command — no
+commit involved.

readme2demo-0.7.1/.claude/skills/python-standards/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: python-standards
+description: Python coding standards, testing patterns, and pydantic/typing conventions for the readme2demo codebase. Use when writing or reviewing any Python in src/readme2demo/ or tests/, adding a module, or before committing code changes.
+---
+
+# Python standards for readme2demo
+
+Python ≥3.10. Match the surrounding code; these are the invariants.
+
+## Types & models
+
+- Type hints on every public function signature; return types included.
+- Data contracts are pydantic v2 models in `types.py` — the single source of
+  truth every stage serializes through. Add a field THERE first, never invent
+  an ad-hoc dict that crosses a stage boundary. Use `model_dump_json(indent=2)`
+  / `model_validate_json` for run-dir I/O.
+- `Optional[X]` for nullable; default containers via `Field(default_factory=...)`.
+- New fields must be backward-compatible (defaulted) — old run dirs on disk
+  must still load.
+
+## Purity boundary (enforced, not stylistic)
+
+- `normalize.py` and every engine `parse_transcript` are PURE and
+  deterministic: no LLM calls, no network, no docker, no clock/random that
+  changes output. They are tested against fixtures. If you need an LLM, you
+  are in the wrong module.
+- LLM calls live only in ingest (planner), distill, tutorial — via `llm.py`.
+
+## Docstrings
+
+- One-line summary; then WHY when non-obvious. Regression-critical functions
+  carry the failure they defend against (search for "Regression (" in tests).
+- Public functions in the pipeline path get a docstring naming their invariant.
+
+## Testing (this is where the repo's value lives)
+
+- `python -m pytest tests/ -q` runs in <1s with NO docker/network/API. Keep it
+  that way: mock `llm.complete_json`, feed fixture transcripts, build models
+  inline. Anything needing real infra is marked `@pytest.mark.integration`.
+- EVERY bug fix carries a regression test whose docstring starts
+  `"""Regression (<repo> run): ..."""` and describes the real failure. It must
+  fail on the old code.
+- For grounding/equivalence changes: test BOTH directions — the new-variant is
+  accepted AND an unproven/evil command is still rejected.
+- Prefer table-style asserts on the actual artifact (the rendered commands.sh,
+  the tape text, the guide markdown), not on internal state.
+
+## Style
+
+- stdlib > third-party; the runtime deps are deliberately few (typer, rich,
+  pydantic, jinja2, anthropic). Don't add a dependency for something stdlib
+  does.
+- `subprocess.run(..., capture_output=True, text=True, timeout=..., errors="replace")`
+  is the house pattern for shelling out; always set a timeout.
+- Fail with a specific, actionable message (name the env var, the file, the
+  fix command) — see the preflight and EngineError messages for the tone.
+
+## Before you commit
+
+Run `/ship-check`. Minimum: full suite green, `python -m compileall -q src/`
+clean, no `runs/` or secrets staged.

readme2demo-0.7.1/.claude/skills/sandbox-toolchains/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sandbox-toolchains
+description: How readme2demo handles TARGET-repo languages and toolchains (Go, Node, Python, Rust, Terraform, etc.) inside the sandbox — version currency, install patterns, and the agent rules that keep runs honest. Use when a run fails on a toolchain install/version, or when extending language support in the base image or agent prompt.
+---
+
+# Target-repo toolchains in the sandbox
+
+readme2demo runs OTHER projects' quickstarts. The base image ships common
+toolchains; the agent installs anything else. Two recurring hazards, both with
+agent-prompt rules AND code defenses.
+
+## Version currency (failure class 2)
+
+The agent's training data is STALE — languages/tools newer than it remembers
+almost certainly exist. `prompts/agent.md` rule 4: never declare a version
+"unreleased"; CHECK the official source
+(`curl -sL 'https://go.dev/VERSION?m=text'`, `pyenv install --list`,
+`npm view <pkg> version`) then download it. Keep the base image's Go current
+(built from the official tarball) so the common case needs no download.
+
+## Install patterns the agent uses (and that must survive verify)
+
+- Python externally-managed sandbox → `pip install --break-system-packages`
+  (and `--no-input`). Editable installs (`pip install -e .`) are cwd-sensitive
+  — see below.
+- Go: `go build` with a current toolchain; GOTOOLCHAIN pitfalls handled by
+  shipping a new-enough Go.
+- Binaries fetched by curl+unzip go to `~/.local/bin` or `~/bin` on PATH.
+
+## cwd drift (failure class 6)
+
+`cd` persists across script lines. The classic bug: `cd /tmp` to unpack a
+binary, then `pip install -e .` editable-installs /tmp instead of the repo.
+`prompts/distill.md` rule 5b requires a `cd` on/before any relative-path line;
+`verify.cwd_hints` runs a static cwd simulation of a failing script and injects
+precise hints into the distiller retry. The repo is always at `/work`.
+
+## Findings tools (failure class 4)
+
+Linters, drift detectors, scanners (tfdrift, etc.) exit NONZERO when they find
+what the demo exists to show. The assertion block uses `set +e` +
+pattern-as-criterion; `normalize.mark_findings_success` reclassifies such
+entries as successful so they count for grounding, the tape, and the payoff
+step. When adding language support, remember success ≠ exit 0 for this class.
+
+## Extending support
+
+Add a toolchain to `images/base/Dockerfile` only if it's common across target
+repos (keep the image lean; the agent can install niche tools). Per-ecosystem
+slim images are a known future optimization, not the MVP.

readme2demo-0.7.1/.claude/skills/vhs-video/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: vhs-video
+description: VHS tape syntax and ffmpeg video handling in readme2demo — how the demo video is generated, the hard-won gotchas, and the duration gate. Use when touching templates/demo.tape.j2, render.py, distill.tape_from_guide, or when a video is short, blank, mis-paced, or fails to render.
+---
+
+# VHS tapes & video
+
+The demo video is built from the FINAL `step_by_step.md` (render stage, after
+tutorial finalizes the guide) so the video follows the published guide
+step-for-step. `distill.tape_from_guide` parses the guide's fenced bash blocks
+into `TapeCommand`s; `templates/demo.tape.j2` renders the tape; `render.py`
+runs VHS in the base image.
+
+## Non-negotiable tape rules (each is a scar)
+
+- **Never use `Wait+Screen` on output text.** It matches only the VISIBLE
+  buffer; any pattern in longer-than-one-screen output scrolls off and times
+  the render out. Pace with `Wait` (blocks until the shell prompt returns, so
+  the command — build included — has finished) then a short `Sleep` to read.
+- **VHS string literals have NO backslash escapes.** `vhs_quote` picks a
+  delimiter the text doesn't contain: `"` → `` ` `` → `'`. A string with all
+  three can't be typed (rare; that step is skipped).
+- **`Type` is single-line.** Multi-line commands (heredocs) are typed
+  LINE-BY-LINE via `TapeCommand.lines` (Type/Enter per line) so file creation
+  plays on camera — a real shell reads a heredoc until its terminator.
+- **Framerate 24, `Output demo.mp4` only.** A GIF per-frame render of a
+  multi-minute tape once filled the Docker VM disk. `demo.gif` is a short
+  downscaled ffmpeg preview cut from the mp4 afterwards (best-effort, never
+  gates the stage).
+- Hidden preamble `cd /work && clear` so the guide's own `git clone ... .`
+  starts from the empty workspace.
+
+## Duration gate (`render.validate_outputs`)
+
+`expected_min_duration_s` sums the tape's Sleeps + typing time; real command
+execution (the Waits) only adds on top. A video shorter than ~0.8× that bound
+means steps didn't play (stale image, aborted tape) → HARD error, never a
+silently short clip. Bounds: 5s..1500s.
+
+## Coverage
+
+`render` writes `tape_coverage.json` (guide_steps / tape_steps / dropped) and
+prints any dropped step. With heredocs now on camera, a dropped step means a
+genuinely ungrounded guide command — investigate, don't ignore.
+
+## ffmpeg
+
+Used for the gif preview (`fps=10,scale=800`) and, on the host, `ffprobe` for
+the duration check. Both run inside the base image for the preview; the host
+ffprobe check is skipped when ffprobe isn't on PATH.

readme2demo-0.7.1/.env.example

@@ -0,0 +1,36 @@
+# Copy to `.env` (gitignored) and fill in the auth you use. You need ONE of the
+# options below. Do NOT commit real secrets.
+
+# Option A — run on your Claude subscription (no API key), self-hosted single
+# operator. This is the default when no provider flag is given. Create the
+# token with `claude setup-token` and paste it here.
+# (Copy the printed sk-ant-oat01-... value; do not use $(claude setup-token).)
+CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
+
+# Option B — Anthropic metered API billing (scale, concurrency, or hosting for
+# others). Also powers `--anthropic`, which runs the sandboxed agent on the
+# OpenHands engine with a Claude model.
+# ANTHROPIC_API_KEY=sk-ant-...
+# Optional model override for `--anthropic` (default: the config model):
+# ANTHROPIC_MODEL=claude-sonnet-5
+
+# Option C — run the whole session on Google Gemini with `--gemini`. This one
+# key powers both the planner/distiller/tutorial passes and the sandboxed agent
+# (via the OpenHands engine). Install the extra: pip install 'readme2demo[gemini]'.
+# GEMINI_API_KEY=...
+# No Gemini model name is built into readme2demo (Google retires old ones with
+# a hard 404). Name it per run (`--gemini <model>`) or set it once here:
+# GEMINI_MODEL=gemini-3.5-flash
+
+# Option D — run the whole session on OpenAI with `--openai`. Same shape as
+# Gemini: one key for the passes and the OpenHands agent, no built-in model
+# name. Install the extra: pip install 'readme2demo[openai]'.
+# OPENAI_API_KEY=sk-...
+# OPENAI_MODEL=gpt-5.1
+
+# Optional — only for the experimental OpenHands engine (--engine openhands).
+# The provider presets (--gemini / --openai / --anthropic) fill these in from
+# the provider's key automatically; set them by hand only to point OpenHands
+# at a different litellm model/provider.
+# LLM_API_KEY=...
+# LLM_MODEL=...

readme2demo-0.7.1/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Default review owner for everything in the repo.
+# Replace @alphacrack with the GitHub handle(s) or team that should be
+# auto-requested for review on every pull request.
+*       @alphacrack
+
+# The grounding invariant lives in these files — guard them closely.
+/src/readme2demo/distill.py      @alphacrack
+/src/readme2demo/verify.py       @alphacrack
+/src/readme2demo/normalize.py    @alphacrack
+/src/readme2demo/sandbox.py      @alphacrack

readme2demo-0.7.1/.github/FUNDING.yml

@@ -0,0 +1,6 @@
+# Adds a "Sponsor" button to the repo. Uncomment and fill in the ones you use.
+# GitHub Sponsors must be enabled for your account first:
+# https://github.com/sponsors
+# github: [alphacrack]
+# ko_fi: your_handle
+# custom: ["https://readme2demo.dev/sponsor"]