walkthru 0.0.2__tar.gz

walkthru-0.0.2/.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,toml,yml,yaml}]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

walkthru-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

walkthru-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@v0.1.81`).
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`) because `inherit` does
+    # not reliably propagate caller-repo secrets to a reusable workflow
+    # owned by a different account (verified empirically: caller in a
+    # personal account, called in i2mint org → `${{ secrets.PYPI_PASSWORD }}`
+    # resolved to empty inside the reusable workflow despite the secret
+    # being set on the caller repo). Listing each secret here makes the
+    # propagation unambiguous regardless of caller-vs-called ownership.
+    # Missing secrets on the caller resolve to empty strings, harmless for
+    # the optional ones; PYPI_PASSWORD must be set for the publish job.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      HUGGINGFACE_TOKEN: ${{ secrets.HUGGINGFACE_TOKEN }}
+      KAGGLE_USERNAME: ${{ secrets.KAGGLE_USERNAME }}
+      KAGGLE_KEY: ${{ secrets.KAGGLE_KEY }}

walkthru-0.0.2/.github/workflows/npm-ci-ts.yml

@@ -0,0 +1,30 @@
+# wads NPM CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration lives in ts/package.json under the "wads"
+# key (wads.ci.*). This workflow only runs when the JS subdirectory changes,
+# so it never collides with the Python ci.yml.
+#
+# Publishing to npm is OPT-IN: set wads.ci.publish.enabled=true in package.json
+# and include the marker (default "[publish-npm]") in your commit message.
+# Publishing uses OIDC trusted publishing by default (configure the trusted
+# publisher for this repo + workflow filename on npmjs.com). NPM_TOKEN is only
+# needed as a fallback (e.g. the very first publish of a new package name).
+name: NPM CI (ts)
+on:
+  push:
+    paths:
+      - "ts/**"
+      - ".github/workflows/npm-ci-ts.yml"
+  pull_request:
+    paths:
+      - "ts/**"
+jobs:
+  npm-ci:
+    uses: i2mint/wads/.github/workflows/npm-ci.yml@master
+    permissions:
+      contents: read
+      id-token: write # npm provenance / OIDC trusted publishing
+    with:
+      package-dir: ts
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

walkthru-0.0.2/.gitignore

@@ -0,0 +1,124 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Node / TypeScript (ts/ frontend, generated by `wads --frontend ts`)
+node_modules/
+*.tsbuildinfo
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

walkthru-0.0.2/DECISIONS.md

@@ -0,0 +1,255 @@
+# walkthru — Decisions & Deviations
+
+> Deliverable 2 of the build brief. Every place this project deviates from
+> `misc/docs/WALKTHRU-AGENT-BRIEF.md` or either report, plus every genuinely open judgment
+> call — with the reasoning and what in the code justified it. Candid, not deferential, per
+> the brief's instruction. Granular follow-up lives in the repo's enhancement issues.
+
+Legend: **[deviation]** departs from a stated brief/report conclusion · **[call]** an open
+judgment the brief left to us · **[confirm]** inspection confirmed a brief assumption.
+
+---
+
+## D1. SSOT authored in Python (Pydantic), not Zod-first — **[deviation]**
+
+**Brief said:** Zod is the presumptive SSOT; `zodal` is the presumptive schema layer; author
+the Demo Document in TS-Zod / `zodal` and emit JSON Schema for the renderer.
+
+**Decision:** Author the SSOT **once in Python Pydantic v2**; emit JSON Schema; **codegen Zod
+v4** for the TS side.
+
+**What justified it:**
+
+- `reelee` defines its content schemas as **Pydantic** `BaseModel`s registered via
+  `lacing.register_body_schema`, exports JSON Schema (`reelee export-schemas`), and
+  **`reelee-web` codegens its Zod types from that export** (`schemas/` → `src/types/generated/`,
+  never hand-written). The federation's SSOT direction is **Python → JSON Schema → Zod**, the
+  opposite of the brief's bias.
+- Matching this lets the Demo Document register as a `lacing` body schema and round-trip
+  losslessly with the renderer side, instead of fighting the grain of the ecosystem.
+- `zodal` turned out to be **collection-centric** (`defineCollection`, `DataProvider`,
+  list/filter/sort) and TS-only — a poor fit for authoring a single nested document schema. It
+  is the right tool for *presenting a library of* Demo Documents/Steps as a collection, not for
+  defining the document itself.
+
+**Cost / risk:** the *live* engine runs TS-side (capture taps acture in the browser), so TS
+consumes codegened types rather than authoring them. This is exactly how `reelee-web` already
+operates, so the toolchain exists. Ecosystem-independence is preserved: Pydantic is a
+permissive third-party dep, not an ecosystem package; the `lacing` hook is an optional
+`ecosystem/` adapter.
+
+---
+
+## D2. First `RenderTarget` is reelee's Ken Burns contract, not Remotion — **[deviation]**
+
+**Brief/report said:** treat the hand-off as Remotion-style "input props"; Report 02 used
+Remotion as a proxy because "Reelee could not be identified from public sources."
+
+**Decision:** The first `RenderTarget` adapter targets **`reelee`'s actual contract** — a
+`reelee.Project` graph projected to an ordered `list[PanelView]`, rendered by
+`render_kenburns_video(project, out, ...)` (MoviePy/ffmpeg). Remotion becomes a *secondary,
+external* adapter built only if a real need appears.
+
+**What justified it:** `reelee` is a real, inspectable ecosystem package and is **not** a
+React/props renderer. Its render input is `PanelView` records (`reelee/storyboard_export.py`) +
+`render_kenburns_video` kwargs (`reelee/kenburns_video.py`). The brief itself instructed:
+"inspect `reelee`'s actual input contract and write the first `RenderTarget` adapter against
+it — the real contract supersedes the Remotion proxy; only the field-mapping adapter changes."
+This decision follows that instruction.
+
+**Unchanged:** the boundary principle (we own representation, the renderer owns pixels; hand off
+validated JSON; the renderer may ignore what it doesn't understand) holds exactly as written.
+
+**Resolved (was an open question): feed `PanelView`s, don't rebuild a `reelee.Project`.** Issue #3
+left open whether the adapter constructs a `reelee.Project` graph or feeds panels directly.
+`render_kenburns_video(project, …)` immediately calls `collect_panel_views(project)` — it
+re-derives panels from an `nw`/`lacing`/falaw annotation + content-addressed-artifact graph.
+Reconstructing that graph from a `DemoDocument` would bleed reelee's whole internal model across
+the firewall, only for reelee to throw our panels away and rebuild its own. So
+`walkthru.ecosystem.reelee` maps the resolved `Timeline` **directly** to `list[PanelView]` and
+drives the film with the *same lower-level primitives* `render_kenburns_video` uses internally
+(`burns.ken_burns_path` + an injectable `film_renderer`, default
+`reelee.kenburns_video.default_film_renderer`). Per-panel screen time comes from the **walkthru
+timeline** (the SSOT already composes it), not reelee's shot-timing strategies. The step-level
+`poster` (AssetRef) added in this work is the panel image (`PanelView.image_path`).
+
+---
+
+## D3. The command layer is `acture`; reuse its record/replay primitives — **[confirm + call]**
+
+**Brief said:** reuse the command layer's registry + middleware; find the cleanest capture
+interception point.
+
+**Finding:** the layer is **`acture`** (TS/React, Apache-2.0). It already ships, in
+`acture/packages/e2e-playwright/src/sequence.ts`:
+
+- `replaySequence(registry, sequence, {ctx, onStep, stopOnError})` — generative replay.
+- `recordSequence(registry) → {steps, stop()}` — capture, by wrapping `registry.dispatch`.
+
+**Decision/call:** `walkthru`'s `play()` is a cue/narration/camera-aware **superset of
+`replaySequence`**, and its `ActionRecorder` is a Demo-Document-emitting **superset of
+`recordSequence`**. We do **not** invent a new engine or a new extension paradigm — observers
+wrap `registry.dispatch` exactly as `acture-telemetry`/`acture-devtools` already do. acture has
+**no core middleware chain by design** (dispatch interception is an opt-in adapter concern);
+`acture-walkthru` slots in as one more opt-in dispatch-observer package beside
+`acture-e2e-playwright` and `acture-telemetry`.
+
+**Implication:** much of the TS engine is *composition over acture*, not new code. This is the
+single biggest scope reduction inspection produced.
+
+---
+
+## D4. Command atom mirrors acture's `SequenceStep {commandId, params}` — **[confirm]**
+
+The brief's `command:{id, params}` maps to acture's macro step shape exactly:
+`SequenceStep { commandId: string, params?: unknown }` (`sequence.ts`). The full command
+*definition* is a richer `CommandRecord {id, title, params: ZodType, when, execute, …}`, but
+the *serializable macro step* — what a Demo Document stores — is `{commandId, params}`. We adopt
+`{ command: { id, params } }` in the Demo Document and bridge `id ↔ commandId` in the acture
+adapter. acture constrains `params` to the JSON-Schema-representable Zod subset; our Pydantic
+models honor the same subset so codegen stays faithful.
+
+---
+
+## D5. License = MIT — **[call]**
+
+**Brief said:** pick a permissive license consistent with the ecosystem.
+
+**Decision:** **MIT.** The Python house default across `dol`, `nw`, `lacing`, `reelee`, and
+`zodal` is MIT. `acture` is the lone **Apache-2.0** package; since `acture-walkthru` builds on
+acture, Apache-2.0 is the relevant *inbound* license, and MIT is outbound-compatible with it
+(MIT code may depend on Apache-2.0). MIT keeps walkthru aligned with the Python orbit it
+publishes into while remaining compatible with the acture tie.
+
+---
+
+## D6. Layout = wads current defaults (Python `name/name/` at root); frontend CI deferred — **[call]**
+
+**Brief proposed:** `py/src/walkthru/…`. An earlier draft of this doc used a `py/` + `ts/`
+split. Both are superseded.
+
+**Decision:** Use **wads current defaults**. The Python package sits at the **repo root** in the
+`name/name/` form — `walkthru/walkthru/` — exactly what `wads populate` produces (hatchling,
+`requires-python >= 3.10`, MIT, ruff `D100`, `tests/`, `[tool.wads.ci.*]` SSOT, the 5-line
+`.github/workflows/ci.yml` uv stub, plus the wads `.gitignore`/`.gitattributes`/`.editorconfig`).
+The TypeScript side lives in a sibling **`ts/`** subdir as a **single** npm package
+(`acture-walkthru`).
+
+**What justified it (and the constraint):** the user maintains ~200 repos in the `name/name`
+form and wants the Python convention left untouched. wads already models the frontend as a
+*separate, additive* overlay (`profiles.py` / `npm_config.py` + a path-filtered workflow), so
+supporting a TS frontend alongside the unchanged Python layout costs nothing. Confirmed by
+reading wads: `populate` (Python) and `apply_npm_overlay` (frontend) are independent code paths.
+
+**Frontend CI deferred — coordination, not indecision.** wads' frontend overlay is brand-new and
+unused (zodal was set up independently/earlier), so its defaults can change freely. We filed
+**i2mint/wads#39** to generalize the single npm overlay into a **js/ts language-profile
+registry** (extensible, with a monorepo seam), to be built in a separate session. To avoid the
+two sessions colliding, walkthru:
+
+- ships the **Python side on wads current defaults now** (this commit), with a **Python-only**
+  `ci.yml`; and
+- **defers `ts/` scaffolding + `npm-ci.yml`** until the wads `ts` profile lands, then generates
+  them via `wads --frontend ts`.
+
+**Single TS package, not a monorepo (for MVP).** `acture`/`zodal` are pnpm+turbo monorepos, but
+walkthru's MVP needs only one publishable package. The core/adapter firewall is enforced
+*within* one package (subpath exports + an import-boundary lint such as dependency-cruiser +
+optional peer deps) — separate packages would be premature. The wads single-package overlay
+fits; we graduate to the `ts-monorepo` profile (reserved in #39) only if adapters ever need
+independent versioning.
+
+**Pre-release CI toggles.** Because there is no release artifact, generated docs, or metrics
+history yet, `[tool.wads.ci].publish/docs/metrics` are set to `enabled = false` (testing +
+ruff stay on so CI gives real signal). Flip `publish` on at the first release; `docs` on once
+docs exist. This is a phase toggle, not a convention change.
+
+---
+
+## D7. Pydantic v2 over plain dataclasses for the Python SSOT — **[call]**
+
+The brief left the Python mirror open (dataclasses / pydantic / generated). Chose **Pydantic
+v2**: it gives validation *and* JSON-Schema emission in one step (the whole point of the SSOT),
+and it is what the federation already uses, so `lacing` schema registration and the reelee
+round-trip come for free. The `core` remains pure — schema validation is side-effect-free; only
+`play()`'s injected observers/ports perform effects.
+
+---
+
+## D8. Anchor is the single SSOT for cue/narration → step association — **[call]**
+
+**Brief listed** `cueRefs?` and `narrationRef?` on `CommandStep`, *and* anchors on the cue and
+narration tracks — i.e. the association stored in two places.
+
+**Decision:** Drop the step-side `cueRefs`/`narrationRef`. The **track item's `anchor`**
+(`{stepId, localOffsetMs[, durationMs]}`) is the *only* place a cue/narration is tied to a step.
+The engine resolves "what fires at this step" by filtering the tracks on `anchor.stepId`
+(`_cues_for` / `_narration_for`).
+
+**Why:** storing the same association on both the step and the track item is a dual-source-of-truth
+that drifts on every edit (the user's SSOT principle, and Report 02's "wrong abstraction"
+warning). The anchor is also strictly richer — it carries `localOffset` (and `duration` for
+narration) that a bare id reference cannot — so it must exist regardless; the step-side ref is pure
+redundancy. Finding a step's cues is an O(n) track scan, which is irrelevant at demo sizes. If a
+real need for fast reverse lookup ever appears, it is a derived index, not new SSOT.
+
+---
+
+## D9. Lifecycle protocol realized as a typed event stream, not named hooks — **[deviation]**
+
+**Brief/Report 02 §B.1** describe the lifecycle as an `Observer` object with named methods
+(`onStepEnter`, `beforeCommand`, `onCueBegin`, …).
+
+**Decision:** Realize it as a stream of **typed event dataclasses** (`StepEnter`, `BeforeCommand`,
+`CueBegin`, …) consumed by observer **callables** (`Observer = Callable[[Event], Awaitable|None]`).
+Each event type maps 1:1 to a brief hook name, so nothing is lost; the canonical walk is the async
+generator `iter_events(document, executor)`, and `play()` is a thin driver that fans events to
+observers.
+
+**Why:** it matches Thor's functional-over-OOP convention and the iterables guidance (a lazy
+`yield`-based stream rather than an object with 13 optional override points). Composition is
+trivial (an observer is just a function; filtering by `isinstance` selects the events you care
+about), and the same event vocabulary serves both `play` (generative) and `record` (capture) —
+the "one lifecycle protocol, driver inverted" the brief wants. A named-hook adapter can be layered
+on later for anyone who prefers it (progressive disclosure), but it is not the core mechanism.
+
+**Async core — [call].** The engine and ports are `async` because the real executors (acture
+dispatch, Playwright) and recorders do I/O. The pure-core tests need no async plugin — they use
+`asyncio.run` over fakes. `executor` and observers may be sync *or* async; the engine awaits
+whatever is awaitable (`_maybe_await`).
+
+---
+
+## D10. Zod codegen is a self-contained `ts/` build script, not reelee-web's toolchain — **[call]**
+
+**Open question (was PLAN §9):** where the Zod codegen lives — a `schema/` build script vs.
+reusing reelee-web's codegen toolchain.
+
+**Decision:** a self-contained `ts/scripts/codegen.mjs` that consumes the committed
+`schema/demo-document.schema.json` (the Pydantic-emitted artifact) and writes
+`ts/src/schema.generated.ts`. It uses the **same tools** reelee-web uses — `json-schema-to-zod` +
+zod v4 — but **not** reelee's `export-schemas` CLI or `lacing` body-schema registry.
+
+**Why:** reelee-web's `scripts/codegen.mjs` is coupled to `python -m reelee export-schemas` and a
+`lacing` `index.json` registry — machinery walkthru does not have, and whose adoption PLAN §9 still
+defers (the `lacing` body-schema question). Reusing the *technique* without the *coupling* keeps
+the TS side runnable with no Python toolchain and preserves the core/adapter firewall: TS depends
+only on the JSON contract, never on `walkthru`/`reelee`/`lacing`.
+
+**Two gotchas handled:** (1) `json-schema-to-zod` does **not** dereference `$ref` (CLI *or* API) —
+it renders Pydantic's `$defs` refs as `z.any()`; we inline them first with
+`@apidevtools/json-schema-ref-parser` (the Demo Document schema is a DAG, so full dereference is
+safe). (2) Drift is guarded both sides: Python pins JSON Schema ↔ Pydantic
+(`test_committed_json_schema_is_up_to_date`); TS pins the committed Zod ↔ JSON Schema via
+`codegen.mjs --check` (run by `ts/src/schema.codegen.test.ts`). Discriminated unions arrive as
+`oneOf` → json-schema-to-zod's "exactly one variant passes" `superRefine`, which is faithful
+(closed union; unknown `type`/`kind` rejected — covered by the round-trip negatives).
+
+---
+
+## Open judgment calls deferred to issues (not yet decided)
+
+- Whether `play()` needs a **Python mirror** for MVP or whether TS-only suffices until render.
+- Whether to register the Demo Document as a **`lacing` body schema** in MVP or defer.
+
+These are tracked as enhancement issues — the project's permanent development memory.

walkthru-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

walkthru-0.0.2/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: walkthru
+Version: 0.0.2
+Summary: Turn a sequence of app commands into an editable, re-renderable demo/tour artifact.
+Project-URL: Homepage, https://github.com/thorwhalen/walkthru
+License: MIT
+License-File: LICENSE
+Keywords: annotation,automation,demo,screencast,tour,walkthrough
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2
+Provides-Extra: reelee
+Requires-Dist: burns; extra == 'reelee'
+Requires-Dist: mixing; extra == 'reelee'
+Requires-Dist: reelee; extra == 'reelee'
+Provides-Extra: testing
+Description-Content-Type: text/markdown
+
+# walkthru
+
+Turn a sequence of application **commands** into an **editable, re-renderable demo/tour
+artifact** — and play that sequence while observers record video, draw visual cues, and
+narrate.
+
+`walkthru` owns the **representation** (the *Demo Document*) and the **playback/capture
+engine**. It does **not** render the final video — it hands a validated artifact off to a
+renderer (the `reelee` ecosystem, Remotion, moviepy/ffmpeg, …). *Owning representation, not
+pixels, is the load-bearing boundary of the whole design.*
+
+## Two modes, one data model, one engine
+
+- **Generative** — an author supplies a Demo Document (commands + annotations); `walkthru`
+  plays it while recording, with optional cues (highlight, spotlight, hotspot, callout,
+  synthetic cursor), pauses, and narration.
+- **Capture** — a human operates the app manually; `walkthru` records the video **and** the
+  underlying command stream **and** annotations, producing the *same* Demo Document.
+
+The only difference between the modes is *who fills in the document*.
+
+## The core
+
+```
+play(demoDoc, executor, observers) -> Outcome
+```
+
+A pure higher-order function that walks the document and emits lifecycle events
+(`onStepEnter` → `beforeCommand` → `afterCommand` → `onStepExit`, `onCueBegin/End`,
+`onNarration`, …). It never records, renders, or speaks — every effect is an injected
+observer or port.
+
+## Ecosystem-biased, ecosystem-independent
+
+The core and ports depend on **nothing** from our ecosystem. Integration with
+[`acture`](https://github.com/thorwhalen/acture) (the command layer),
+[`reelee`](https://github.com/thorwhalen/reelee) (the renderer), and `zodal` ships as
+**optional adapters**. You can `pip install walkthru` / `npm i acture-walkthru` and use the
+core with your own adapters.
+
+## Packages
+
+| Package | Registry | Role |
+|---|---|---|
+| `walkthru` | PyPI | Python core + schema SSOT + render hand-off |
+| `acture-walkthru` | npm | TS core + the live capture/play engine over `acture` |
+
+## Status
+
+🚧 **Planning.** See [`PLAN.md`](./PLAN.md) for the implementation plan,
+[`DECISIONS.md`](./DECISIONS.md) for design decisions and deviations from the brief, and the
+repo's **enhancement issues** for the running development journal. Source documents live in
+[`misc/docs/`](./misc/docs/).
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).