stream_weaver 0.3.0

data/docs/university/capability-inventory.md

@@ -0,0 +1,137 @@
+# StreamWeaver Capability Inventory
+
+Read-only inventory of what StreamWeaver (the Ruby gem at the root of this repo) can do, compiled to design a "getting started" tutorial for a newcomer. Sourced from `README.md`, `docs/for_llms.md`, `exe/streamweaver`, `lib/stream_weaver/cli.rb`, `docs/*.md`, `lib/stream_weaver/skills/*/SKILL.md`, `.claude/skills/`, and `examples/`.
+
+## 1. CLI Subcommands
+
+All subcommands dispatch through `StreamWeaver::CLI.run` in `lib/stream_weaver/cli.rb`. `streamweaver <file.rb>` (bare path) is shorthand for `run`.
+
+| Command | Purpose | Tutorial-worthy? |
+|---|---|---|
+| `streamweaver <file.rb>` / `run` | Run an app file (standalone, auto-port, auto-browser) | Y — the entry point everyone needs first |
+| `ruby app.rb` | Same DSL, but you own the process (no service) | Y — the "vs `streamweaver app.rb`" distinction is a common first confusion |
+| `eval` | Evaluate DSL from stdin, print result as JSON | N for a first pass — power-user/scripting path |
+| `prompt` | One-shot flag-driven UI (`--radio`, `--select`, etc.), returns JSON | N — niche flag-based alternative to writing DSL |
+| `list` | List all apps loaded into the background service | N — housekeeping |
+| `remove <app_id>` | Remove one app from the service | N — housekeeping |
+| `clear` | Remove all apps from the service | N — housekeeping |
+| `admin` | Open the admin dashboard for the running service | N — operational, not a first-day need |
+| `tutorial` | Launches the built-in interactive tutorial app (`examples/advanced/tutorial.rb`) | Y — literally the guided onboarding path, mention immediately |
+| `showcase` | Browse all bundled examples in a live examples browser | Y — best "see what's possible" discovery step |
+| `serve` | Start the background service in the foreground (dev mode) | N — internals |
+| `stop` | Stop the background service | N — housekeeping, but worth one line |
+| `status` | Show service status (port, pid) | N — troubleshooting reference |
+| `llm` | Print `docs/for_llms.md` to stdout (LLM quick reference) | Y — the one-liner every AI-agent user needs on day one |
+| `opal-build <app.rb>` | Compile an app to a static Opal (client-side Ruby→JS) bundle in `dist/` | N — advanced/deployment topic |
+| `live <name>` | Open a persistent one-way live session (SSE push, no round-trip IPC) | N — superseded by `canvas` for most agent use, but worth a mention as the simpler ancestor |
+| `push <name>` | Push content into a `live` session | N — pairs with `live` |
+| `live-list` / `live-close <name>` | List / close live sessions | N — housekeeping |
+| `template <name>` | Run one of the bundled templates | N — not explored in depth this pass; see Gaps |
+| `canvas <name>` | Create/connect to a two-way canvas session (opens browser) | Y — the flagship "Claude Code talks to a UI" capability |
+| `canvas-push <name>` | Push DSL content (from stdin) into a canvas session | Y — paired with `canvas`, this is the core loop |
+| `canvas-wait <name>` | Block until the user interacts, return form state as JSON | Y — completes the two-way loop |
+| `canvas-toast <name> <msg>` | Show a toast overlay without replacing page content | N — nice-to-know, not core |
+| `canvas-close <name>` | Close a canvas session | N — one line in passing |
+| `canvas-reset <name>` / `--all` | Reset session state, keep the connection/pane open | N — troubleshooting reference |
+| `canvas-list` | List active canvas sessions | N — housekeeping |
+| `canvas-stop` | Stop the canvas bridge server entirely | N — troubleshooting reference |
+| `canvas-read <file\|dir>` | Browse canvas DSL docs (and history) in a read-only local viewer, no app session needed | Y — how you view a doc after the fact / share it |
+| `export <file.rb>` | Write a canvas DSL doc out as standalone static HTML | Y — the "hand this to someone with no StreamWeaver installed" capability |
+| `org-export <file.rb>` | Convert a saved DSL doc to a human-readable `.org` sibling file | N for first tutorial — but core to the org-mode story, see section 3 |
+| `org-render <file.org>` | Convert an `.org` doc back into DSL body text (stdout) | N for first tutorial — round-trip companion to `org-export` |
+| `pick` | High-level canvas helper wrapping a common choice pattern | N — not explored deeply this pass |
+| `confirm` | High-level canvas helper wrapping a common confirm-dialog pattern | N — not explored deeply this pass |
+| `panel [name]` | Split the current iTerm2 pane and open a canvas session in the new pane | Y — the single best "wow" demo for a terminal-based coworker |
+| `install-skill [--global]` | Install StreamWeaver's Claude Code / cross-tool skills | Y — a one-time setup step worth doing in the first session |
+| `setup` | One-command setup: bash permissions + globally install the panel skill for Claude Code | Y — alternative/superset of `install-skill`, good "step 0" |
+| `--help` / `-h` / `help` | Show usage | N |
+| `--version` / `-v` | Show gem version | N |
+
+## 2. Canvas Capabilities
+
+The canvas bridge is a persistent background server (separate from the app service) that gives Claude Code a two-way, addressable, named UI surface.
+
+| Capability | Exact command |
+|---|---|
+| Create/open a session | `streamweaver canvas <name>` |
+| Push DSL content into it | `streamweaver canvas-push <name> <<'RUBY' ... RUBY` (stdin) |
+| Block for user interaction, get JSON back | `streamweaver canvas-wait <name>` |
+| Multi-step flow without a final "close" message | end a pushed page with `canvas_continue message: "..."` DSL call instead of nothing |
+| Show a non-destructive toast | `streamweaver canvas-toast <name> "message"` |
+| Reset session state (keep the pane/connection) | `streamweaver canvas-reset <name>` (or `--all` for every session) |
+| Close a session (and its iTerm pane, if any) | `streamweaver canvas-close <name>` |
+| List all sessions | `streamweaver canvas-list` |
+| Stop the whole bridge | `streamweaver canvas-stop` |
+| Browse a saved/pushed DSL doc read-only (no live app) | `streamweaver canvas-read <file\|dir> [--theme=NAME] [--layout=NAME]` |
+| Read history of everything pushed to a session | Tier-1 (off-repo) snapshots at `~/.streamweaver/history/<session>/<timestamp>.rb`, written automatically on every `canvas-push`, pruned after 7 days (`lib/stream_weaver/canvas/history.rb`). `canvas-read` with no args discovers these automatically. |
+| Save the current canvas content as a permanent doc | In-browser: click the floating **💾 Save as doc** button rendered by `lib/stream_weaver/canvas/save_doc_widget.rb` (posts to the bridge; `scope: :repo` default writes near the project, `scope: :global` writes to `~/.streamweaver/canvas`) |
+| Session naming | Free-form string arg to `canvas`/`canvas-push`/etc.; sanitized to `[A-Za-z0-9._-]` for on-disk paths; `panel` auto-generates `panel-<hex>` if omitted |
+| Port / PID discovery | Canvas bridge finds its own free port (same auto-scan behavior as app service); the **app service** (separate from canvas) writes `~/.streamweaver/server.pid` (`port=`, `pid=`) via `lib/stream_weaver/service.rb`; individual apps write portfiles to `~/.streamweaver/apps/<sanitized_name>.port` (`url=`, `pid=`, `name=`) via `lib/stream_weaver/portfile.rb` |
+| iTerm split-pane helper | `streamweaver panel [name]` — implemented in `lib/stream_weaver/iterm.rb` via the optional `iterm2_ruby` gem, **not** a standalone `bin/` script (see Gaps §7) |
+
+## 3. Docs Capabilities
+
+| Capability | Exact command |
+|---|---|
+| Render org-mode or DSL docs live in a viewer | `streamweaver canvas-read <path>` (accepts a file or directory; also auto-discovers Tier-1 history + registered doc roots when called with no args) |
+| Force a fallback theme/layout for docs with no `use_theme`/`use_layout` declared | `streamweaver canvas-read <path> --theme=NAME --layout=NAME` |
+| Apply the `:doc` theme in code (artifact-parity editorial styling, dark mode via `data-sw-theme="dark"`) | `theme: :doc` option to `app`, or `--theme=doc` flag to `streamweaver panel` |
+| Export a live/saved DSL doc to standalone static HTML (no server, no Ruby needed to view) | `streamweaver export <file.rb> [-o out.html] [--inline-images] [--offline]` |
+| Convert a saved DSL doc to human-readable `.org` | `streamweaver org-export <file.rb>` (writes `<name>.org` next to the source) |
+| Convert an `.org` doc back into DSL body text | `streamweaver org-render <file.org>` (prints to stdout) |
+| Render a StreamWeaver doc on GitHub/Gist as it would look running, client-side | Chrome extension at `extension/` (`StreamWeaver Doc Viewer`) — content script matches `github.com/*` and `gist.github.com/*`, adds a "View rendered" button. Build: `bin/vendor_browser_assets` then `bin/build_extension`, then load unpacked in `chrome://extensions`. **Shipped and verified** (status per `docs/plans/org-doc-preview-surfaces.md`: S1–S3 shipped, S4–S6 not started). |
+| Save the currently-displayed canvas content permanently as a doc | Floating "Save as doc" button in the browser (see §2) |
+| Doc history (append-only local snapshots) | `~/.streamweaver/history/<session>/` for canvas pushes; separate doc store at `~/.streamweaver/canvas` (`scope: :global`) or repo-local (`scope: :repo`, default) for explicit saves — `lib/stream_weaver/canvas/doc_store.rb` |
+
+## 4. Interaction Modes Worth Demonstrating
+
+| Mode | What it does | Example file |
+|---|---|---|
+| **Standalone / stateful app** | `app { ... }.run!` — persistent server, DSL block re-executes on every interaction, state persists across the session | `examples/basic/hello_world.rb`, `examples/basic/todo_list.rb` |
+| **Agentic / blocking form** | `app { ... }.run_once!` — opens a popup UI, blocks the calling Ruby process until Submit, returns collected state as JSON, then exits | `examples/agentic/agentic_form.rb` |
+| **Agentic with auto-close** | Same as above, plus the browser window auto-closes ~1s after submit | `examples/agentic/agentic_form_autoclose.rb` |
+| **Canvas two-way IPC** | Claude Code pushes DSL, blocks on `canvas-wait`, reacts, pushes again — the terminal-agent-drives-a-UI loop | `docs/canvas-panel-workflow.md` walkthrough; `examples/claude_code/` |
+| **Multi-step canvas flow** | `canvas_continue message: "..."` keeps a "processing" spinner between pushes instead of ending the session | documented in `docs/canvas-panel-workflow.md`; no single dedicated example file found (see Gaps) |
+| **Traditional form block** | `form :name do ... submit "Save" { ... }; cancel "Cancel" end` — deferred submission, all fields collected together | `docs/form-patterns.md` (canonical pattern reference with all four form patterns side by side) |
+| **Reactive auto-submit inputs** | Default behavior: every input triggers a server round-trip + re-render immediately (filters, toggles) | `docs/form-patterns.md`, `examples/basic/todo_list.rb` |
+| **Editorial long-form doc (`:doc` theme)** | `doc_header`, `doc_section_header`, `sidebar_toc` — PRDs/reports delivered as standalone app or canvas from one shared DSL body | `examples/tutorials/streamweaver_way_tutorial.rb` (`SW_NO_OPEN=1 ruby examples/tutorials/streamweaver_way_tutorial.rb`); pattern documented in `lib/stream_weaver/skills/streamweaver-doc-builder/SKILL.md` |
+| **Live one-way SSE session** | `streamweaver live <name>` + `streamweaver push <name>` — simpler ancestor of canvas, push-only, no wait/reply loop | referenced in CLI help; no dedicated `examples/` file found for `live`/`push` specifically (`examples/canvas/` only has a mermaid demo script) |
+
+Note: the task brief's phrase "growing document" does not appear anywhere in the docs or code searched — likely means the multi-step canvas flow (`canvas_continue`) or the doc-builder pattern above; flagged rather than guessed at further.
+
+## 5. Skills Shipped in This Repo
+
+Two install paths exist, both driven by the CLI:
+
+- **`streamweaver install-skill [--global]`** — installs the panel skill (inline, Claude-Code-only, not spec-compliant `SKILL.md`) plus four gem-sourced skills, symlinked (not copied) so gem updates propagate. Installs to `.claude/skills/` (Claude Code) **and** `.agents/skills/` (the cross-tool alias Codex CLI, Gemini CLI, and GitHub Copilot all discover natively) — `--global` targets `~/.claude/skills/` / `~/.agents/skills/` instead of the project-local paths.
+- **`streamweaver setup`** — one-command setup: adds bash permissions for Claude Code and installs the panel skill globally.
+
+| Skill | Source | Installed by `install-skill`? | Triggers on |
+|---|---|---|---|
+| `streamweaver-panel` | `.claude/skills/streamweaver-panel.md` (repo-committed, loose-file legacy format) | Y | Presenting results/status/rich choices visually via `streamweaver panel` |
+| `streamweaver-visual-companion` | `lib/stream_weaver/skills/streamweaver-visual-companion/` | Y | Any "show me / mock it up / push to canvas" moment — replaces Artifact tool and Chrome-screenshot workflows |
+| `streamweaver-doc-builder` | `lib/stream_weaver/skills/streamweaver-doc-builder/` | Y | Building editorial long-form docs with the `:doc` theme |
+| `streamweaver-way` | `lib/stream_weaver/skills/streamweaver-way/` | Y | Building/changing interactive app features (fragments, defer/lazy, keying, dev-loud/prod-self-heal conventions) |
+| `streamweaver-canvas-safe` | `lib/stream_weaver/skills/streamweaver-canvas-safe/` | Y | Before building a canvas doc / running `export` — which components need a live backend vs. render standalone |
+| `visual-plan` | `lib/stream_weaver/skills/visual-plan/` | **N — not in the `gem_skills` install list** (see Gaps) | Pre-flight implementation planning via canvas, before code is written |
+| `visual-recap` | `lib/stream_weaver/skills/visual-recap/` | **N — not in the `gem_skills` install list** (see Gaps) | Post-implementation visual summary of what changed |
+
+## 6. The Representative 5 (first 20-minute tutorial)
+
+1. **`streamweaver tutorial`** — the built-in guided app. Zero-setup, self-teaching first move; sets the "this is real code, not slides" tone immediately.
+2. **`ruby app.rb` on the minimal example from `docs/for_llms.md`** (a 6-line `text_field` + reactive `text` app) — proves the "your DSL block re-executes on every interaction" mental model in under a minute, which is the single idea everything else builds on.
+3. **`streamweaver panel demo`** + `canvas-push` from another terminal — the "wow" moment: an agent (or the coworker's own hand-typed command) drives a live split-pane UI with no HTML/JS. This is StreamWeaver's actual differentiator versus every other quick-UI tool, and it's the one capability a coworker cannot get anywhere else.
+4. **`streamweaver showcase`** — self-serve exploration of the example library once the core loop clicks, so the tutorial doesn't have to enumerate every component; Matt's Law (find it, digest it) via a browsable index instead of a wall of text.
+5. **`streamweaver export`** on a pushed canvas doc — closes the loop by showing the output is a real, shareable artifact (static HTML, no server needed), which matters for a coworker evaluating whether this is a toy or something they can actually hand to someone else.
+
+Rationale: this set covers all four modes (standalone, agentic-adjacent via canvas-wait, canvas two-way, static export) with the minimum number of new concepts, and front-loads the one feature (`panel`) that no generic "Streamlit for Ruby" pitch conveys in words alone — it has to be seen running.
+
+## 7. Gaps (things a newcomer would trip on)
+
+1. **`visual-plan` and `visual-recap` skills exist in `lib/stream_weaver/skills/` but are absent from the `gem_skills` hash in `CLI.install_skill`** (`lib/stream_weaver/cli.rb:2056-2061`) — running `streamweaver install-skill` does not install them, and the command's own printed summary doesn't mention them either. A newcomer who reads the skill source directly and expects `install-skill` to wire it up will be quietly wrong.
+2. **No `bin/iterm_split_browser.py` in this repo.** The iTerm split-pane behavior referenced by that name (from prior session memory) doesn't exist here — the actual mechanism is `lib/stream_weaver/iterm.rb`, a Ruby wrapper around the optional `iterm2_ruby` gem, invoked via `streamweaver panel`. Worth correcting in any tutorial material that inherited the old filename.
+3. **`streamweaver template <name>`** is a documented top-level command (`lib/stream_weaver/cli.rb:916`) but this pass didn't find example template names or a `docs/` page describing what templates ship or how to list them — a newcomer typing `streamweaver template` with no args has no discoverable next step from the CLI help text alone (the main `help` output doesn't mention `template` at all, only `live`/`push`/canvas commands are documented there).
+4. **`streamweaver pick` and `streamweaver confirm`** are listed in the dispatch table and called "high-level canvas helpers" in the main help text's Panel section, but neither appears in the `help` command's own examples, and this pass didn't trace their DSL surface — a newcomer has no worked example to copy.
+5. **`examples/canvas/`** contains only `mermaid_canvas_demo.sh` — there's no example file demonstrating the basic `live`/`push` one-way session commands that the CLI help documents at length, so a newcomer following the help text's "Live Session Examples" has to hand-type them from scratch rather than running something first.
+
+These are reported, not fixed — this was a read-only inventory pass.

data/docs/university/dependency-survey.md

@@ -0,0 +1,114 @@
+# Dependency & Setup Surface Survey
+
+Read-only survey for a future `streamweaver get-started` command that verifies/installs
+dependencies for a newcomer on a fresh Mac, and degrades gracefully on Linux/Windows.
+Companion to `docs/university/roadmap.md` and `docs/university/capability-inventory.md`.
+
+## 1. Dependency summary table
+
+| Dependency | Required / Optional | Platform | Where declared / used | Notes |
+|---|---|---|---|---|
+| sinatra, sinatra-contrib | required | any | `stream_weaver.gemspec:38-39` | web framework |
+| phlex | required | any | `stream_weaver.gemspec:40` | view layer |
+| puma | required | any | `stream_weaver.gemspec:41` | server |
+| rackup | required | any | `stream_weaver.gemspec:42` | server |
+| kramdown, kramdown-parser-gfm | required | any | `stream_weaver.gemspec:43-44` | markdown |
+| ostruct | required | any | `stream_weaver.gemspec:45` | Ruby 3.5+ compat |
+| diffy | required | any | `stream_weaver.gemspec:52` | DiffBlock |
+| **iterm2_ruby** | **optional** | **macOS only** | not in gemspec (deliberately) | see [1] below |
+| `open` (BSD) | required for browser auto-launch | macOS | `iterm.rb:39`, `service_client.rb:35`, `cli.rb:1060`, `server.rb:1064` | |
+| `xdg-open` | required for browser auto-launch | Linux | `service_client.rb:37`, `cli.rb:1062`, `server.rb:1066` | |
+| `start` | required for browser auto-launch | Windows | `service_client.rb:39`, `cli.rb:1064`, `server.rb:1068` | via `system('start', url)` |
+| `osascript` | optional (terminal-focus convenience) | macOS only | `cli.rb:2159` | see [2] below |
+| `iterm2ctl` (bin from iterm2_ruby gem) | optional | macOS only | not called from this repo's `lib/`; only from `~/work/claude_code_history` worker-session tooling | see [4] below — outside this gem |
+| `herdr` socket/CLI | optional | any (Forrest's personal tool) | not in this repo; used by `/worker-session` | see [4] below |
+
+**[1] `iterm2_ruby`** — Not a gemspec runtime dependency by design (`stream_weaver.gemspec:46-50`, comment explicitly states it is optional so `StreamWeaver::ITerm` degrades gracefully). Required by `lib/stream_weaver/iterm.rb:85` (`require "iterm2"` inside `check_availability`, rescued as `LoadError` → `false`). Availability gating in `iterm.rb:78-89`: only even attempts the require when host OS matches `darwin` (`iterm.rb:79`) and `ENV['ITERM_SESSION_ID']` is set (`iterm.rb:83`), i.e. only inside a live iTerm2 session on macOS — this also avoids spawning the gem's Python-API subprocess unnecessarily. Setup needed for `iterm2_ruby` itself (per `~/work/iterm2_ruby/README.md:67-69`): macOS + iTerm2 installed, Ruby >= 3.1, and iTerm2's own **Preferences > General > Magic > Enable Python API** toggle switched on — no separate Python venv needed (the gem's own README says "No external WebSocket gems required" and does not mention a Python dependency for the Ruby side; iTerm2's built-in Python API server is what it talks to over its own socket). No install script/launcher is provided by this repo; the only guidance is `gem install iterm2_ruby`.
+
+**[2] `osascript`** — `lib/stream_weaver/cli.rb:2159`, inside `self.focus_terminal`, used to bring the terminal back to front after the browser auto-closes; runs an AppleScript block checking `System Events`/iTerm2/Terminal.app. Gated behind `RbConfig::CONFIG['host_os']` matching `/darwin|mac os/` (`cli.rb` case statement just above `2148`, see `2143-2165` range) — no-ops elsewhere.
+
+## 2. `iterm2_ruby` — error handling / messaging when missing
+
+- `ITerm.available?` (`iterm.rb:11-14`) memoizes `check_availability`, which returns `false` on `LoadError` (`iterm.rb:87-88`) — every downstream `ITerm` call (`split_vertical_with_url`, `close_pane`, `split_vertical_with_command`, `navigate_browser`) short-circuits to a `false`/`nil`/no-op return, so nothing raises.
+- `split_vertical_with_url` (`iterm.rb:31-44`) falls back to `system("open", url)` (the plain macOS opener) when the pane split isn't available and `open_browser: true` — this is the "degrade to system browser" path referenced in the gemspec comment.
+- The one place StreamWeaver actively *tells the user* the gem would help: `ITerm.gem_missing?` (`iterm.rb:20-27`) is true only when **not** available, **is** macOS, and **is** inside an iTerm2 session (`ENV["ITERM_SESSION_ID"]` present) — i.e. the one case where installing the gem is actually actionable. Consumed at `lib/stream_weaver/cli.rb:1921-1922`:
+  ```
+  if ITerm.gem_missing?
+    puts "(Tip: `gem install iterm2_ruby` to open canvases in an iTerm split pane)"
+  end
+  ```
+  This hint was added in commit `a5c5571` ("feat(cli): hint 'gem install iterm2_ruby' when split-pane would help"); the gem was made optional (not a runtime dep) in `12d76b5` ("fix(gem): make iterm2_ruby an optional enhancement, not a runtime dep"), then pinned to the published RubyGems version in `c3dfaf7`. Full history: `git log -S 'iterm2_ruby' --oneline` shows 12 touching commits from the original hand-rolled-AppleScript replacement (`58866e3`) through the current optional-gem state.
+- Docs mentioning setup gotchas: `docs/claude-code-companion-skill-spec.md:24` ("StreamWeaver's `iterm.rb` uses the `iterm2_ruby` gem to: split pane, open browser pane, keep it persistent"); `docs/university/capability-inventory.md:70` and `:132` (corrects stale session-memory that referenced a nonexistent `bin/iterm_split_browser.py` — the real mechanism is `lib/stream_weaver/iterm.rb` + the optional gem, invoked via `streamweaver panel`); `docs/university/roadmap.md:36` proposes (not yet built — status `[loose]`) a future `streamweaver university` command that "checks `iterm2_ruby` gem (prompts if absent)."
+
+## 3. `streamweaver setup` subcommand (`lib/stream_weaver/cli.rb:2095-2133`, `self.setup`)
+
+Currently a two-step, Claude-Code-specific bootstrap — **it does not touch `iterm2_ruby` at all**:
+
+1. **Bash permission**: reads (or creates) `~/.claude/settings.json`, ensures `permissions.allow` contains `'Bash(streamweaver *)'`, writes it back pretty-printed (`cli.rb:2098-2118`).
+2. **Skill install**: calls `install_skill(['--global'])` (`cli.rb:2121`) — see §3 below for what that installs and where.
+
+No dependency checks (no Ruby version check, no `iterm2_ruby` check, no browser-opener check) and no cross-platform branching — it unconditionally writes to `~/.claude/settings.json`, which only makes sense for a Claude Code user. This is the gap a `get-started`/`streamweaver university` command would need to fill; `docs/university/roadmap.md:36` sketches exactly that (story `university-door-command`).
+
+**Update (get-started-door-command, shipped):** the gap above is now closed — `streamweaver get-started` (`CLI.get_started` in `cli.rb`) wraps `setup`, adds the Ruby-version/canvas-bridge/agent-skill/premier-iTerm2 dependency report this section describes, and pushes the `university` canvas session.
+
+## 4. `streamweaver install-skill` (`lib/stream_weaver/cli.rb:2039-2091`, `self.install_skill`)
+
+Yes — **Codex is supported today**, alongside Claude Code and (per the printed help text) Gemini CLI and GitHub Copilot, via a single cross-tool alias directory. Two target roots, chosen by `--global`/`-g`:
+
+| Tool | Global path | Project path |
+|---|---|---|
+| Claude Code | `~/.claude/skills` (`cli.rb:2043`) | `.claude/skills` (cwd) |
+| Codex / Gemini CLI / Copilot alias | `~/.agents/skills` (`cli.rb:2044`) | `.agents/skills` (cwd) |
+
+Behavior:
+- `streamweaver-panel.md` (inline `SKILL_CONTENT`, a flat `.md` with no frontmatter) is written **only** to the Claude-Code path (`cli.rb:2049-2052`) — explicitly noted as "not SKILL.md-spec-compliant, so Claude Code only."
+- Four gem-sourced, spec-compliant skills (`streamweaver-visual-companion`, `streamweaver-doc-builder`, `streamweaver-way`, `streamweaver-canvas-safe`; `cli.rb:2057-2062`) are symlinked — **whole directory, not just SKILL.md** (fixed in the commit tagged `stream_weaver-5fyf` per the comment at `cli.rb:2064-2067`, so sibling `examples/`/`references/` content stays reachable) — into **both** `claude_dir` and `agents_dir` (`cli.rb:2069-2076`).
+- Printed summary explicitly documents the Codex path (`cli.rb:2088-2090`): "Also installed to `#{agents_location}` — the cross-tool alias Codex CLI, Gemini CLI, and GitHub Copilot all discover natively (Claude Code uses its own path above instead)."
+
+**Tested?** Yes, partially — `spec/cli_install_skill_spec.rb:38-39` has a test asserting the `.agents/skills` symlink is created for `streamweaver-canvas-safe`. No test found asserting Codex itself discovers/loads from that path (that would require a real Codex CLI invocation, out of scope for this repo's spec suite).
+
+**Caveat vs. Codex's own conventions**: `docs/reference/agent-skills-comparison.md:16` documents that Codex actually looks in `~/.agents/skills/` (user), `$REPO_ROOT/.agents/skills/` (repo-root), `$CWD/.agents/skills/` (working dir), **and** historically `~/.codex/skills/`, plus an admin-level `/etc/codex/skills/`. StreamWeaver's installer only ever writes to `~/.agents/skills` or `<cwd>/.agents/skills` — it does not also mirror into the legacy `~/.codex/skills/` path, so a Codex install expecting the legacy path specifically would miss it (the modern `.agents/skills` convention is covered).
+
+## 5. `/worker-session` skill — dependency chain
+
+Location: `~/.claude/skills/worker-session/SKILL.md` (single file, no sibling `references/`/`examples/`).
+
+The skill itself is a thin dispatcher: it resolves `--dir`/`--task`/`--model`/`--session-name`/`--mode` and shells out to:
+
+```
+~/work/claude_code_history/bin/worker-session --dir <dir> --task-file <path> [--model][--name][--mode]
+```
+
+That script (`bin/worker-session`) requires `../lib/worker_session_launcher` (`ClaudeCodeAnalyzer::WorkerSessionLauncher`), which chains to:
+
+| Dependency | Type | Used for |
+|---|---|---|
+| `ENV['HERDR_PANE_ID']` / `ENV['TERM_PROGRAM']` | env inspection | detects calling terminal (`:herdr` vs `:iterm` vs `:unknown`) — `worker_session_launcher.rb caller_terminal` |
+| `TerminalAdapter::HerdrAdapter` (`herdr_adapter.rb`) | Ruby class, shells to `herdr` CLI | when caller is inside a herdr pane: `herdr api snapshot`, `herdr tab create --cwd ... --label ... --focus`, `herdr pane run <pane_id> <command>`, `herdr tab focus <tab_id>` — all via `IO.popen(['herdr', *args], ...)` |
+| `herdr` socket | file existence check | `HerdrAdapter.detected?` checks `~/.config/herdr/herdr.sock` exists before considering herdr "running" |
+| `iterm2ctl` (from the `iterm2_ruby` gem's `bin/`) | external binary, `IO.popen` | when caller is plain iTerm (not herdr): `iterm2ctl create tab`, `iterm2ctl send-text <session_id> <text>` — `worker_session_launcher.rb run_iterm2ctl` |
+| `claude` CLI | shelled-out command | the actual command sent into the new pane/tab (`build_command`, prefixes with `--model`/`-n`/`--permission-mode` as given) |
+
+So the full external chain for `/worker-session` is: **herdr** (socket + CLI, optional — only when inside a herdr pane) **or** **iterm2ctl** (binary shipped by the `iterm2_ruby` gem, optional — only when inside plain iTerm and not herdr) → **claude** CLI itself. None of this lives in the `stream_weaver` repo — it's entirely in `~/work/claude_code_history` (personal tooling), invoked by a global skill, not a repo-local one. Not a dependency of the `stream_weaver` gem or its `get-started` surface, but flagged since it was in scope of the ask.
+
+## 6. Platform-specific shell-outs in `lib/` and `exe/`
+
+All `osascript` / `system(...)` / backtick invocations found (excludes comments and non-shell backtick usage in prose, e.g. inline-code markdown in comments):
+
+| Call | File:line | Platform gate | Purpose |
+|---|---|---|---|
+| `system("open", url)` | `lib/stream_weaver/iterm.rb:39` | none explicit (only reached after `available?` macOS/iTerm gate upstream) | fallback browser open when pane split unavailable |
+| `system('open', url)` | `lib/stream_weaver/service_client.rb:35` | `when /darwin/` | browser open |
+| `system('xdg-open', url)` | `lib/stream_weaver/service_client.rb:37` | `when /linux/` | browser open |
+| `system('start', url)` | `lib/stream_weaver/service_client.rb:39` | `when /mswin\|mingw\|cygwin/` (Windows) | browser open |
+| `system('open', url)` | `lib/stream_weaver/cli.rb:1060` | `when /darwin\|mac os/` | browser open |
+| `system('xdg-open', url)` | `lib/stream_weaver/cli.rb:1062` | `when /linux/` | browser open |
+| `system('start', url)` | `lib/stream_weaver/cli.rb:1064` | `when /mswin\|mingw\|cygwin/` | browser open |
+| `system('osascript', '-e', script)` | `lib/stream_weaver/cli.rb:2159` | `when /darwin\|mac os/` (`self.focus_terminal`) | refocus terminal after browser auto-close |
+| `system("open", url)` / `system("xdg-open", url)` / `system("start", url)` | `lib/stream_weaver/server.rb:1064,1066,1068` | same three-way OS case | browser open (server-side variant) |
+
+All three OS-specific browser-open call sites (`service_client.rb`, `cli.rb`, `server.rb`) implement the same `open`/`xdg-open`/`start` fallback triad independently — i.e. this logic is duplicated three times rather than factored into one shared helper. No `Process.spawn`/`Open3`/other shell-out patterns found for anything beyond these two purposes (browser-open, terminal-refocus) and the `iterm2ctl`/`herdr` calls covered in §5 (which live outside this repo).
+
+## 7. Skill packaging levels (private/team/world) — not found
+
+Grepped `docs/` and `~/work/cultiv-ai/wiki` for "world" near "skill"/"packag": no hits describing a private/team/world skill-packaging tier scheme. The only adjacent material is `docs/reference/agent-skills-comparison.md:112`, which notes Claude Code has no equivalent to Codex's "plugin packaging layer (distributable bundles of multiple skills + MCP config)" — a different axis (bundling, not visibility/audience tiers). If a private/team/world scheme exists, it isn't documented in this repo or in the cultiv-ai wiki index as of this survey.

data/docs/university/design-spec.md

@@ -0,0 +1,217 @@
+# StreamWeaver University — course canvas design spec
+
+Story: `course-canvas-design` (epic `university-getting-started`). Binding input for `course-list-canvas`, `progress-ledger`, `driver-worker-runner`, and every `step-N-*` story.
+
+Mockup: `docs/university/mockups/course_canvas_mockup.rb` (runs standalone with `ruby`, and pushes to a canvas with `canvas-push`).
+Screenshots: `course-list-light.png`, `course-list-dark.png`, `step-screen-light.png`, `step-screen-dark.png` in the same directory.
+
+**Revision note (v2).** v1 was reviewed and rejected as "a decent first start" that read as a *document* rather than an app: the course state sat at page level above everything, sections were divided by hairlines and 11px small-caps labels that reviewers missed entirely, and the single-blue palette left every state looking alike. v2 rebuilds the information architecture around course panels, replaces hairlines with real surfaces, raises the type scale, and introduces a three-colour state language. Sections 1–4 describe v2; §5 records what v1 taught us that still binds the build.
+
+**Revision note (single-mode, 2026-09-03).** Live UAT (round 5) cut the separate "step screen" this doc's §2/§6 describe: "Details" on a course-list row now expands that row's content inline on the SAME course-list render (why it matters, prompt + Run/Copy, payoffs, Mark done + a next-step hint) instead of navigating to a second screen. Expanding one row collapses any other, and there is nothing to get "back" from — no `← All steps`, no `Next: step N+1` link. The content and CSS classes §2's "Step screen" table describes (`.uni-label`, `.uni-prose`, `.uni-promptbox`, `.uni-payoff`, the footer) carry over unchanged as the expansion body; only the App band / Context row (wordmark+breadcrumbs, `← All steps`, `Step N of 5`) are gone, since there is no second screen to orient within. See `lib/stream_weaver/university/canvas.rb` (`.uni-step__expansion`) and `Progress#expanded_step`/`#expand_step!`/`#collapse!`.
+
+---
+
+## 1. Visual direction
+
+**A warm workbench.** The `:doc` theme's warm paper stays, but it is now the *room*, not the object. Courses sit on it as raised instrument panels — near-white in light, warm charcoal in dark — each with a title bar, a body, and its own state. The reader is someone with a terminal open beside this pane, at roughly 500–900px wide, whose attention is already spent. They must be able to tell in under a second: what is this, which course am I in, and what do I do next.
+
+Five decisions carry the design:
+
+**a. The course owns its state; the page owns nothing.** Nothing course-specific appears above the course list. The resume line ("Pick up at step 3."), the primary Run button, and the 5-segment rail all live *inside* the Getting Started panel, under its own title bar. This is what makes a second course additive rather than a rewrite: a course is a self-contained unit with a header, a state, and a list. The page above it carries only identity — the app name and one line saying what the app is for.
+
+**b. Courses are accordion panels, open or dormant.** Getting Started renders open (`card depth: :elevated`) with a filled title bar, a status chip, and its full body. Future courses render closed (`card depth: :recessed`): transparent ground, quiet border, hollow dot, name and one-line blurb, a `Soon` chip with a drawn lock — and no controls at all. A dormant course is a promise on a shelf, not a wall of dead buttons.
+
+**c. Surfaces, not hairlines.** v1 separated everything with 1px rules, and reviewers scrolled straight past the boundaries. v2 gives every region a real ground: page `#E7E4D9`, panel `#FDFCF9`, title bar `#F3F1E8`, recessed regions (resume band, prompt block, footer) `#F1EFE6`, plus a two-layer neutral shadow on the open panel. The panel edge is now the loudest line on the page, which is correct — it is the strongest structural fact.
+
+**d. A three-colour state language, used identically everywhere.** One triad, no confetti:
+
+| State | Light | Dark | Where it appears |
+|---|---|---|---|
+| Done | `#17754A` green | `#57C98A` | step mark (filled disc + check), rail segment, "What you should see" checks |
+| Now | `#1E4ED8` blue (`--sw-color-accent`) | `#6699FF` | step mark (filled disc + number + ring), current-row band, rail segment, every primary button, course status dot |
+| Not yet | `#6E6959` stone | `#9A9285` | step mark (hollow ring + number), `Soon` chip |
+
+The rail's empty segments use a separate `--uni-rail-track` value rather than the stone. They are a *track*, not a state marker: the rail's meaning is carried by the filled done/now segments and by the always-present `N of 5 done` label beside it, so the track is not required to clear 3:1 and darkening it to that level would read as "filled."
+
+Because the same three colours drive the mark, the rail, and the checks, the rail becomes readable without its label and the current step is findable at a glance from anywhere on the page. Colour is never the *only* signal: done also carries a check glyph, current also carries a filled disc and a tinted row band, dormant also carries a lock glyph and the word `Soon`.
+
+**e. One primary action, three button weights.** Every step keeps a working Run/Repeat control — locking steps would be pure friction — but hierarchy carries the guidance: filled accent (the one thing to do now) → outlined (the current step's own Run, and Copy prompt) → quiet borderless (repeat a done step, jump ahead). Exactly one filled button exists per screen.
+
+**Type.** Base is 16px, up from 15px. The serif display face (`--sw-font-display`, Charter) is used exactly twice per screen and only for voice, never for structure: the app name (27px) and the resume line / step title (~1.55rem / ~1.95rem). Everything structural is the body sans, at sizes that survive a skim: course name 20px/700, step title 17px/650, step payoff 14.5px, section labels 15px/650, prose 16px. **v1's 11px uppercase micro-labels are gone from the content flow.** Small caps survive only as *chrome* — the `IN PROGRESS` / `SOON` chips and the prompt block's title bar — where the enclosing shape, not the type size, does the work of being noticed.
+
+**Motion.** Deliberately none on load. The canvas is re-pushed by an agent many times per session; a re-entrance animation on every push is an attention tax, not a delight. The budget is spent on 130ms state transitions (hover, focus) behind a `prefers-reduced-motion` guard.
+
+**Light and dark.** v1 rode `--sw-*` tokens exclusively and claimed zero dark-mode rules as a win. That constraint is what produced the blandness: a control panel needs the page and the panel to be *different grounds*, and that is a two-value decision per theme, not one token. v2 therefore carries one explicit dark block, hung off the same selector the `:doc` theme uses for its own dark palette (`html[data-sw-theme="dark"] body`), so the two flip on exactly the same signal and can never disagree. Semantic tokens (`--sw-color-text`, `--sw-color-accent`, `--sw-font-*`) are still consumed directly.
+
+---
+
+## 2. What each screen must assert
+
+### Course list
+
+| Region | Content | Why it's there |
+|---|---|---|
+| App band | `StreamWeaver University` (serif, 27px), one-line tagline, theme toggle | Says what this is in under a second — the fix for "I thought it was a document" |
+| Course panel — title bar | status dot, `Getting Started` (20px/700), `IN PROGRESS` chip | The course names itself at a size nobody scrolls past |
+| Course panel — resume band | "Pick up at step N." + step title + `Run step N` (primary) + `Repeat step N-1` (quiet) + 5-segment rail + "N of 5 done" | The single answer to "what do I do now" — scoped to this course |
+| Course panel — run report band | Only after a Run/Repeat click: one line saying what the driver did. On a clean send, green and nothing else. On a refusal (worker session closed, none recorded) or in degraded mode, stone, plus the step's prompt in a code block with a Copy button and a paste instruction | The click has to say what it did — a silent Run is indistinguishable from a broken one, and a refusal must hand back the prompt rather than strand the user (`driver-worker-runner` criteria 4-5). Superseded by the next click and cleared by Mark done, so it never goes stale |
+| Course panel — step rows | 5 rows: state mark, title, one-line payoff, Run/Repeat | The map; every step re-runnable |
+| Divider | `In the works` (15px/650) + rule to the right edge | A section label at reading size, not a micro-label |
+| Dormant panels | 3 closed cards: hollow dot, name, blurb, `Soon` chip. **No controls.** | Promise, not denial |
+| Footer note | `streamweaver tutorial` in a code chip, on its own recessed panel | The escape hatch to the old tour |
+
+### Step screen
+
+| Region | Content | Why it's there |
+|---|---|---|
+| App band | wordmark + breadcrumbs `Getting Started · Step 3` + theme toggle | Where am I |
+| Context row | `← All steps` button, the same 5-segment rail, `Step 3 of 5` | Back out, and position — the rail is the same instrument as on the list |
+| Panel title bar | blue step-number badge + serif h1 title | The step, marked with the same "now" badge the list used |
+| Why this matters | 2 short paragraphs, ≤66ch | Motivation before mechanics |
+| Prompt block | labelled title bar + verbatim monospace body on a sunk ground | **Transparency.** No hidden prompt, no paraphrase — the user sees exactly what gets sent |
+| Actions | `Run in worker session` (primary) + `Copy prompt` (outlined) | Premier path and degraded path, side by side |
+| What you should see | 3 lines with green done-checks | The payoff, stated before they run it |
+| Footer band | `Mark step N done` (outlined) + "Unlocks step 4." | The exit, on its own ground, not competing with Run |
+
+Monospace appears exactly once per screen, on the prompt block, where it is doing its real job: showing a verbatim payload character-for-character.
+
+---
+
+## 3. Component and token inventory
+
+Existing components used as-is (prefer these in the build; do not hand-roll replacements):
+
+| Component | Used for | Hook restyled |
+|---|---|---|
+| `card(depth:, class:)` | every course panel — `:elevated` open, `:recessed` dormant | `.sw-card` |
+| `card_header(class:)` | course title bar, step title bar | `.sw-card-header` |
+| `card_body(class:)` | course body | `.sw-card-body` |
+| `topbar(wordmark:, breadcrumbs:)` | app band on both screens | `.sw-topbar`, `.sw-topbar-wordmark`, `.sw-topbar-crumb`, `.sw-topbar-crumb--active` |
+| `theme_toggle mode: :auto` | light/dark control | `.sw-theme-toggle__btn`, `.sw-theme-toggle__icon`, `.sw-theme-toggle__label` |
+| `button(label, submit: false, key:, class:)` | every Run / Repeat / Mark done | `.sw-button` |
+| `copy_button(label, text:, copied_label:)` | Copy prompt (degraded path) | `.sw-button` (it emits the same hook) |
+| `header1` / `header2` / `header3` | step-screen title, course names, step-row titles | none — styled via own class |
+| `phrase` / `div` / `md` | rows, chips, labels, prose, the prompt block | `.markdown-content` for `md` bodies |
+| `tabs :screen, variant: :line` | **review chrome only** — see §6 | none |
+| `use_theme` / `use_layout` / `use_stylesheet` | in-DSL theme + stylesheet, so one file serves standalone and canvas | — |
+
+Theme tokens consumed directly:
+
+| Token | Used for |
+|---|---|
+| `--sw-color-text` | all primary text |
+| `--sw-color-text-muted` | payoffs, blurbs, quiet buttons, hints |
+| `--sw-color-accent` | the "now" colour, in every state surface and primary button |
+| `--sw-color-primary-hover` | primary button hover |
+| `--sw-font-display` / `--sw-font-body` / `--sw-font-mono` | the three voices |
+
+Values defined per-theme by this design rather than taken from a token, because no token expresses them: the four grounds (page / panel / bar / sunk), the two line weights, and the done / now-tint / not-yet triad. All are declared once on `body` and once on `html[data-sw-theme="dark"] body`.
+
+`--sw-color-text-light` is deliberately **not** used for any text: at `#A09D96` on paper it is 2.4:1 and fails WCAG AA. Anything that needs to recede drops *weight* rather than contrast.
+
+`--sw-color-text-muted` is also **overridden in light mode** (`#5F5C54` instead of `#6B6860`). The theme value measures 4.37:1 on this design's page ground, and the tagline and the dormant-course blurbs sit exactly there. The override clears 4.5:1 on all four grounds. Dark mode keeps the theme value (6.5:1+ everywhere).
+
+---
+
+## 4. Bespoke CSS
+
+One stylesheet, carried inline via `use_stylesheet` (see §5 for why inline rather than a sibling `.css`). All of it lives in the `uni-` namespace except the `sw-` hook overrides listed in §3.
+
+| Class | What it is |
+|---|---|
+| `.uni-i`, `--check/play/repeat/back/lock` | the drawn icon set — masked inline SVG at one stroke weight, `background-color: currentColor` so icons inherit text colour and theme automatically. No emoji, no icon library. |
+| `.uni-course`, `--dormant`, `__bar`, `__dot`, `__name`, `__blurb`, `__body` | the course panel: open and dormant variants, title bar, status dot |
+| `.uni-chip`, `--soon` | the `IN PROGRESS` and `Soon` status chips |
+| `.uni-resume`, `__lead`, `__sub` | the resume band inside a course panel |
+| `.uni-actions` | the primary/secondary button row |
+| `.uni-btn`, `--run`, `--outline`, `--quiet` | the three-weight button ladder, applied via `class:` on `button`/`copy_button` |
+| `.uni-rail`, `__track`, `__seg`, `--done`, `--current`, `__label` | the five-segment progress rail |
+| `.uni-step`, `--done/--current/--todo`, `__mark`, `--hero`, `__title`, `__payoff` | the step rows and their state marks |
+| `.uni-divider`, `__label`, `__rule` | the `In the works` section divider |
+| `.uni-note` | the `streamweaver tutorial` footer panel |
+| `.uni-context`, `.uni-back`, `.uni-count`, `.uni-title`, `.uni-section`, `.uni-label`, `.uni-prose`, `.uni-promptbox`, `.uni-prompt`, `.uni-payoff`, `.uni-foot` | the step screen |
+| chrome neutralization on `body[class*="sw-layout-"]` + `#app-container` | holds one 860px column whether the host set `sw-layout-fluid` (canvas) or `sw-layout-default` (standalone) |
+| `::selection`, `:focus-visible`, scrollbar rules | browser surfaces themed from the palette instead of left at browser defaults |
+
+Four structural notes for the build:
+
+- The icon set is data-URI masks, so it costs no network request and needs no asset route.
+- Step titles are `h3` under the course's `h2` name, and the `:doc` theme's own `h2`/`h3` treatment is explicitly reset, so the outline nests correctly instead of running flat.
+- Selectors that fight a theme rule are written `body.sw-theme-doc h2.uni-…` to win specificity outright rather than relying on source order.
+- The card component's own `--elevated` / `--recessed` backgrounds are overridden by `body .sw-card.uni-course`; the depth argument is kept because it carries the semantic and any future theme work should key off it.
+
+---
+
+## 5. Gaps found
+
+| Gap | Impact on the build | Suggested fix |
+|---|---|---|
+| **`use_theme` in a pushed DSL body does not reach the live canvas page.** `Canvas::Session` fixes `theme`/`layout` at create time (`bridge.rb` `handle_create`); `render_canvas_page` emits `sw-theme-#{session.theme}`. A body declaring `use_theme :doc` still renders under `sw-theme-default`. | `course-list-canvas` **must** create its session with the doc theme — the canvas will silently look wrong otherwise. | Have the push path adopt the body's `use_theme`/`use_layout` (canvas-read already does), or at minimum let `streamweaver canvas` accept `--theme=`. |
+| **`streamweaver canvas <name>` has no `--theme=` flag** (only `panel` does). | Any headless canvas setup for the course app needs `panel`, which also opens a pane. | Add `--theme=` to `canvas_session`, matching `panel`. |
+| **`use_stylesheet` must be handed literal CSS, not a path, for canvas.** Path resolution is relative to the *evaluating* script dir, which canvas-push does not set. | The mockup inlines its CSS in a heredoc. Same constraint applies to the built app. | Either keep CSS inline in the body, or teach `canvas-push` to resolve `use_stylesheet` paths against the pushed file's directory. |
+| **`topbar`'s wordmark renders as a `div`, so a page whose title is the wordmark has no `h1`.** | The course list has no `h1` — its outline starts at the `h2` course name. Harmless visually, wrong for screen readers and for `export`. | Give `topbar` a `wordmark_level:` option (default `div`, opt into `h1`), or let the app pass its own heading into the wordmark slot. |
+| **`card_header(content)` renders the title as `h4`,** which cannot sit under an `h2`/`h1` without skipping levels. | The mockup passes no content string and nests its own `header2`/`header1` as a child instead. | Add a `level:` option to `card_header`. |
+| **`theme_toggle` ships an emoji icon plus a `System/Dark/Light` word label** with no option to suppress either. | The mockup overrides both in CSS (hides the label, re-masks the two icon spans by `:nth-of-type`). Brittle if the component's markup order changes. | Add `compact: true` (icon only) and/or an `icon:` option. Worth an `sw-` hook per icon variant so `nth-of-type` isn't the selector. |
+| **`Header` drops unknown options.** `header2 "x", "data-foo": 1` silently loses the attribute (only `:class`/`:style` forward). | Step numbers live inside the mark element rather than as a `data-*` on the title. Fine, but worth knowing. | Forward arbitrary `data-*` through `render_header`. |
+| **No component for a "list row with state mark + title + detail + action".** This is the step row, and it will recur (course lists, checklists, run logs). | Built from `div` + grid CSS here. | Candidate component after `course-list-canvas` proves the shape: `step_row(number:, title:, detail:, state:, &action)` emitting `.sw-step-row`, `__mark/__title/__detail`, `--done/--current/--todo`. |
+| **No progress-rail component.** `progress_bar` is a percentage bar, which is the wrong instrument. | Built from five `div`s, and now used on *both* screens. | Candidate: `step_rail(total:, done:, current:)` emitting `.sw-step-rail`, `__seg`, `--done`, `--current`. |
+| **No status-chip component.** `badge` exists but carries its own colour vocabulary. | `IN PROGRESS` / `Soon` are hand-rolled `.uni-chip`. | Either widen `badge` to accept a semantic state, or leave chips bespoke. |
+| Canvas WebSocket handshake 404s and falls back to polling (`ws://…/canvas/<name>/ws` → 404 in the console). | Pre-existing; not caused by this design. Content still updates. | Out of scope here — worth a separate mark if it isn't already tracked. |
+
+---
+
+## 6. How to build `course-list-canvas` from this
+
+1. **Start from the mockup file, not from scratch.** `docs/university/mockups/course_canvas_mockup.rb` already holds the finished stylesheet and both screens' markup. Lift the `_css` heredoc verbatim into the real app; it is the design.
+2. **Drop the tabs.** `tabs :screen` in the mockup is review chrome so both screens are visible in one push. The real app has no tabs: the course list and the step screen are two renders of the same app, chosen by state (`state[:step]`, nil = list).
+3. **Model a course, not a page.** The course panel is the unit of composition: `card(depth:) > card_header(title bar) > card_body(resume band + step rows)`. Adding a second live course means appending another panel with its own state — no page-level change. Keep the rule that **nothing course-specific renders above the course list.**
+4. **Replace the literal arrays with the curriculum.** The `steps` array (number, title, payoff, state) is the shape the curriculum layer must supply. `state` comes from the progress ledger (`progress-ledger`), so it is `:done` / `:current` / `:todo` — the CSS keys off exactly those three, as do the rail segments.
+5. **Wire the buttons.** Every `button` in the mockup is `submit: false` and inert. In the build: the resume-band Run and each row's Run/Repeat call the driver (`driver-worker-runner`); `Mark step N done` writes the ledger; `← All steps` clears `state[:step]`. Keep `key:` on every button in the loop — without it, loop-derived ids collide.
+
+   Two non-obvious requirements, both found the hard way in the 2026-08-29 UAT, where every button blanked the canvas to "✓ Submitted — You can close this window" and nothing happened:
+
+   - **The DSL must emit `canvas_continue`.** Buttons already dispatch non-terminal `action` events; the blanking comes from the adapter's `showFeedback()`, which falls back to that terminal screen when the pushed page carries no `#sw-canvas-continue` marker. Right for a one-shot form, fatal for a control panel. With the marker a click shows a brief spinner instead.
+   - **Something has to be listening.** A click only reaches the ledger if `University::Listener` is running, and only returns to a real page because the listener re-pushes. `get-started` starts it as a detached background process (pid and log under `~/.streamweaver/university/`); `streamweaver university-listener [start|stop|status]` is the manual control. Without it the canvas is a screen of buttons that silently do nothing — and, with the marker in place, one that sits on "Working…" forever.
+6. **Keep `use_theme :doc` + `use_stylesheet` in the DSL body** so the app renders identically standalone, on a canvas, through `canvas-read`, and through `export`. And per §5, create the canvas session itself with the doc theme — `use_theme` alone will not colour the live page.
+7. **Degraded mode is a hierarchy swap, not a different screen.** With no worker session, drop the Run buttons and promote `Copy prompt` from `.uni-btn--outline` to `.uni-btn--run`. The resume band's `Run step N` becomes `Copy step N prompt`. Nothing else changes.
+8. **States the mockup does not show, which the build owes:**
+   - *First run* (0 of 5): resume line reads "Start with step 1.", rail all not-yet, no Repeat button, and the course chip reads `NOT STARTED` rather than `IN PROGRESS`.
+   - *All done* (5 of 5): the chip reads `COMPLETE` in the done green, the resume band congratulates and points at the shelf / `streamweaver tutorial`, every row shows Repeat, and there is no primary button (the course has no "next").
+   - *Running*: the row whose step was just dispatched needs a "sent to your worker session" acknowledgement — the canvas cannot see the worker's progress, so say only what is true.
+9. **Do not add:** a percentage progress bar, per-step time estimates, step locking, a fourth accent colour, a nested card inside a course panel, or an entrance animation. Each was considered and rejected above.
+
+---
+
+## 7. Verification done
+
+- Rendered on the live canvas bridge (session `university-design`, doc theme) and screenshotted full-page at 1000px, light and dark, both screens. Also checked at 620px — the real narrow iTerm pane — where step rows reflow to put the action under the text.
+- Booted standalone (`SW_NO_OPEN=1 STREAMWEAVER_PORT=… ruby docs/university/mockups/course_canvas_mockup.rb`) and confirmed HTTP 200 with `<body class="sw-layout-default sw-theme-doc">` — the same file drives both delivery modes.
+- Ran the Impeccable mechanical detector over the rendered page, then ran a two-assessment critique (independent design review + independent detector/contrast evidence) over the result. Findings and their attribution are in §8.
+
+---
+
+## 8. Critique findings (v2)
+
+Recorded so the build inherits them rather than rediscovering them.
+
+**Attribution rule.** The canvas bridge injects its own framework CSS and its own "Save canvas as doc" control into every page it serves. A detector finding belongs to this design only if it traces to markup or CSS authored in the mockup file.
+
+| Finding | Attribution | Disposition |
+|---|---|---|
+| `skipped-heading`: `h1` "One form, two modes" followed by `h3` "Save canvas as doc" | Host — the Save-as-doc control is bridge chrome appended after page content | Not fixable from the DSL; ignore |
+| `pulsing-dot`: `.sw-pulse-dot` with an infinite `sw-pulse` animation | Framework CSS — this page has no pulsing element (`.uni-course__dot` is static) | Ignore |
+| `dark-glow`: zero-offset `#ef4444` box-shadow | Framework CSS — not a colour this design uses | Ignore |
+| Course list has no `h1` | Ours, but caused by `topbar`'s wordmark rendering as a `div` | Recorded as a component gap in §5; the build should fix it there, not with a stray heading |
+| Step titles were `h2` under an `h2` course name (flat outline) | Ours | **Fixed** — step titles are now `h3` |
+
+Contrast was computed, not estimated, for every state colour against every ground it lands on in both themes. The first pass had three genuine failures, all now fixed:
+
+| Pair | Was | Now | Fix |
+|---|---|---|---|
+| `not yet` stone on panel (todo step numerals) | 3.53 light / 4.43 dark | 5.35 / 5.34 | darkened light stone to `#6E6959`, lightened dark stone to `#9A9285` |
+| `not yet` stone on the `Soon` chip ground | 2.49 light / 3.95 dark | 4.64 / 4.76 | chip ground split off from the rail track and lightened to `#EFECE1` — no stone value could pass against the old ground |
+| muted text on the page ground (tagline, dormant blurbs) | 4.37 light | 5.24 | light-mode `--uni-muted` override, §3 |
+
+Also fixed from the design review: the todo mark's ring was a 50% tint (2.07:1 as a boundary) and is now solid stone; the done mark, which replaces its number with a glyph, now carries visually-hidden state text (`.uni-sr`) so a screen reader gets "Step 1, done" rather than silence; body bottom padding became a real safe area (120px, 150px under 700px) because the host's floating "Save as doc" control was landing on the last payoff line in a narrow pane; the step screen's rail gained the same `N of 5 done` label the course list uses.
+
+One review suggestion was implemented with a deliberate change: it asked for a `Next: step N →` **action** in the footer. Two equally-weighted exits there would have been ambiguous — only one of them writes the ledger — so `Mark step N done` keeps the outlined weight and `Next: step 4` sits at the quiet weight on the far side of the footer. The one-primary-action rule still holds; the screen's primary remains `Run in worker session`.