@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/diagram-animation/references/diagram-and-chart-recipes.md

@@ -0,0 +1,218 @@
+# Diagram & Chart Recipes — Cookbook
+
+Runnable recipes for progressive diagram reveals, flowing connectors, and animated charts. Self-contained across SVG/CSS, GSAP, D3, Framer Motion, and Remotion.
+
+## Reveal order & pacing
+
+1. **Containers/regions** first (faint), to establish the frame.
+2. **Nodes** appear (scale 0.8→1 + fade), in reading/logical order.
+3. **Edges** draw between now-visible nodes.
+4. **Labels** fade in last, on the settled nodes.
+5. **Highlight** sweeps the active path; everything else dims to ~0.35 opacity.
+
+Hold each meaningful step 0.5–1.5s. For narrated diagrams, gate each step on the VO line, not a fixed timer.
+
+## 1. Staged node → edge → label reveal (GSAP timeline)
+
+```html
+<svg viewBox="0 0 480 220" id="arch">
+  <g class="region" opacity="0"><rect x="20" y="40" width="180" height="140" rx="12" fill="#11161f"/></g>
+  <g class="node" data-i="0" opacity="0"><rect x="50" y="70" width="120" height="40" rx="8" fill="#0A84FF"/></g>
+  <g class="node" data-i="1" opacity="0"><rect x="50" y="130" width="120" height="40" rx="8" fill="#0A84FF"/></g>
+  <g class="node" data-i="2" opacity="0"><rect x="300" y="100" width="140" height="40" rx="8" fill="#30D158"/></g>
+  <path class="edge" d="M170 90 C240 90 240 120 300 120" fill="none" stroke="#5b6472" stroke-width="3" pathLength="1"/>
+  <path class="edge" d="M170 150 C240 150 240 120 300 120" fill="none" stroke="#5b6472" stroke-width="3" pathLength="1"/>
+  <text class="label" x="110" y="95" fill="#fff" font-size="13" text-anchor="middle" opacity="0">Web</text>
+  <text class="label" x="110" y="155" fill="#fff" font-size="13" text-anchor="middle" opacity="0">Worker</text>
+  <text class="label" x="370" y="125" fill="#000" font-size="13" text-anchor="middle" opacity="0">Queue</text>
+</svg>
+<script type="module">
+  import gsap from "https://cdn.jsdelivr.net/npm/gsap/+esm";
+  gsap.set(".edge", { strokeDasharray: 1, strokeDashoffset: 1 });
+  gsap.set(".node", { transformOrigin: "center", scale: .85 });
+  const tl = gsap.timeline({ defaults: { ease: "power2.out" } });
+  tl.to(".region", { opacity: 1, duration: .4 })
+    .to(".node",  { opacity: 1, scale: 1, duration: .45, stagger: .25, ease: "back.out(1.5)" })
+    .to(".edge",  { strokeDashoffset: 0, duration: .55, stagger: .2 }, "-=0.3")
+    .to(".label", { opacity: 1, duration: .35, stagger: .12 }, "-=0.4");
+</script>
+```
+
+## 2. Sequence diagram (lifelines + activation messages)
+
+Reveal each message arrow in order, marching the dash to imply direction.
+
+```js
+import gsap from "gsap";
+gsap.set(".msg", { strokeDasharray: 1, strokeDashoffset: 1 });
+const tl = gsap.timeline();
+document.querySelectorAll(".msg").forEach((m, i) => {
+  tl.to(m, { strokeDashoffset: 0, duration: .5, ease: "power1.inOut" })
+    .fromTo(m.nextElementSibling, // the message label
+            { opacity: 0, y: -4 }, { opacity: 1, y: 0, duration: .3 }, "-=0.2")
+    .to({}, { duration: .6 }); // hold so it reads
+});
+```
+
+## 3. Flowing connector — marching dash + traveling packet
+
+```html
+<svg viewBox="0 0 400 80">
+  <path id="wire" d="M20 40 H380" stroke="#2b3340" stroke-width="4" fill="none"/>
+  <path class="flow" d="M20 40 H380" stroke="#0A84FF" stroke-width="4" fill="none"
+        stroke-dasharray="10 12"/>
+  <circle class="packet" r="5" fill="#7cc4ff"/>
+</svg>
+<style>
+  .flow   { animation: march .7s linear infinite; }
+  @keyframes march { to { stroke-dashoffset: -22; } } /* = dash(10)+gap(12) */
+  .packet { offset-path: path("M20 40 H380"); animation: travel 1.6s linear infinite; }
+  @keyframes travel { to { offset-distance: 100%; } }
+  @media (prefers-reduced-motion: reduce){
+    .flow, .packet { animation: none; }
+  }
+</style>
+```
+
+Reverse direction (data flowing back): use a positive `stroke-dashoffset` keyframe target and `offset-distance` from 100%→0%.
+
+## 4. Bar chart — grow + stagger
+
+```html
+<div class="chart">
+  <div class="bar" style="--h:60%"></div>
+  <div class="bar" style="--h:85%"></div>
+  <div class="bar" style="--h:40%"></div>
+</div>
+<style>
+  .chart { display:flex; gap:12px; align-items:flex-end; height:200px; }
+  .bar { width:48px; height:var(--h); background:#0A84FF; transform:scaleY(0);
+         transform-origin:bottom; transition:transform .6s cubic-bezier(.22,1,.36,1); }
+  .bar.in { transform:scaleY(1); }
+  .bar:nth-child(1){ transition-delay:.00s } .bar:nth-child(2){ transition-delay:.08s }
+  .bar:nth-child(3){ transition-delay:.16s }
+</style>
+<script>
+  // trigger on view
+  document.querySelectorAll(".bar").forEach(b => b.classList.add("in"));
+</script>
+```
+
+SVG bar version (animate `height` + `y` so it grows from the baseline):
+
+```js
+import gsap from "gsap";
+gsap.from("rect.bar", {
+  attr: { height: 0, y: (i, t) => +t.getAttribute("y") + +t.getAttribute("height") },
+  duration: .6, ease: "power3.out", stagger: .08
+});
+```
+
+## 5. Line chart — draw-on via dashoffset
+
+```js
+const path = document.querySelector("path.series");
+const len = path.getTotalLength();
+Object.assign(path.style, { strokeDasharray: len, strokeDashoffset: len });
+path.getBoundingClientRect();                       // reflow so transition runs
+path.style.transition = "stroke-dashoffset 1.1s ease-in-out";
+path.style.strokeDashoffset = "0";
+// dots pop after the line reaches them:
+gsap?.from("circle.point", { scale: 0, transformOrigin: "center",
+  duration: .3, stagger: .12, delay: .3, ease: "back.out(2)" });
+```
+
+Area-under-line: draw the stroke first, then fade in the filled area path after the stroke completes.
+
+## 6. Count-up number
+
+```js
+function countUp(el, to, { dur = 1200, decimals = 0, prefix = "", suffix = "" } = {}) {
+  const t0 = performance.now();
+  const fmt = new Intl.NumberFormat(undefined, { minimumFractionDigits: decimals,
+                                                 maximumFractionDigits: decimals });
+  (function tick(now){
+    const k = Math.min(1, (now - t0) / dur);
+    const e = 1 - Math.pow(1 - k, 3);               // easeOutCubic
+    el.textContent = prefix + fmt.format(to * e) + suffix;
+    if (k < 1) requestAnimationFrame(tick);
+  })(t0);
+}
+countUp(document.querySelector("#stat"), 1284000, { suffix: "+" });
+```
+
+Respect reduced motion: if reduced, set `el.textContent` to the final value immediately and skip the loop.
+
+## 7. D3 transitions
+
+```js
+const bars = svg.selectAll("rect").data(data).join("rect")
+  .attr("x", d => x(d.label)).attr("width", x.bandwidth())
+  .attr("y", y(0)).attr("height", 0).attr("fill", "#0A84FF");
+bars.transition().duration(600).delay((d, i) => i * 80)
+  .ease(d3.easeCubicOut)
+  .attr("y", d => y(d.value)).attr("height", d => y(0) - y(d.value));
+
+// count-up via attrTween / tween
+d3.select("#stat").transition().duration(1200).ease(d3.easeCubicOut)
+  .tween("text", function () {
+    const i = d3.interpolateNumber(0, 1284000);
+    return t => this.textContent = d3.format(",")(Math.round(i(t)));
+  });
+```
+
+## 8. Framer Motion (React)
+
+```jsx
+import { motion } from "framer-motion";
+const container = { show: { transition: { staggerChildren: 0.12 } } };
+const node = { hidden: { opacity: 0, scale: 0.85 },
+               show:   { opacity: 1, scale: 1, transition: { ease: "backOut" } } };
+
+export function Flow() {
+  return (
+    <motion.svg variants={container} initial="hidden" animate="show" viewBox="0 0 400 200">
+      {nodes.map(n => <motion.circle key={n.id} variants={node} cx={n.x} cy={n.y} r={26} />)}
+      {edges.map(e => (
+        <motion.path key={e.id} d={e.d} fill="none" stroke="#888" strokeWidth={3}
+          initial={{ pathLength: 0 }} animate={{ pathLength: 1 }}
+          transition={{ duration: 0.5, ease: "easeInOut", delay: 0.4 }} />
+      ))}
+    </motion.svg>
+  );
+}
+```
+
+`pathLength` is a first-class animatable prop in Framer Motion — no manual dash math needed.
+
+## 9. Remotion (deterministic video render)
+
+```jsx
+import { useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
+
+export const Bar = ({ value, index }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const delay = index * 4;
+  const grow = spring({ frame: frame - delay, fps, config: { damping: 14 } });
+  return <rect x={index * 60} y={200 - value * grow} width={40} height={value * grow} fill="#0A84FF" />;
+};
+
+export const Count = ({ to }) => {
+  const frame = useCurrentFrame();
+  const e = interpolate(frame, [0, 36], [0, to], { extrapolateRight: "clamp",
+    easing: t => 1 - Math.pow(1 - t, 3) });
+  return <text>{Math.round(e).toLocaleString()}</text>;
+};
+```
+
+Because Remotion renders per-frame deterministically, the same diagram renders identically to PNG sequence/MP4 every time — ideal for repeatable data exports.
+
+## Reduced-motion across all recipes
+
+- Stop `infinite` connector/flow animations (`animation: none`).
+- Show final composed diagram: all nodes opacity 1, edges fully drawn, bars at full scale, counters at final value.
+- Gate any JS timeline on `matchMedia("(prefers-reduced-motion: reduce)").matches` and jump to end state.
+
+---
+Reveal nodes before edges before labels, and a diagram explains itself. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=explainer-video-skills&utm_content=skill_footer&utm_term=diagram-animation)** — the AI motion agent for editable, on-brand motion graphics.

package/skills/diagram-tour/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: diagram-tour
+description: "Generate a narrated architecture-tour video from a codebase. End-to-end: codebase analysis → Graphviz .dot → narration script → narrated MP4. Three confirmation gates between user and final video. Use when the user asks to \"explain this codebase\", \"tour the architecture\", \"make a video about how X works\", or invokes /diagram-tour explicitly. Output: a versioned MP4 at <project>/.diagram-tour/renders/. Expensive — confirm runtime expectations (~15-30 min on modern hardware, longer on lighter machines) before kicking off. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "centraltowerlabs/diagram-tour"
+---
+
+# Diagram Tour Skill
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+You are operating as the diagram-tour skill. Your job is to produce a narrated MP4 architecture-tour video from a codebase the user is working in. You orchestrate four stages and gate on user approval between each, so the user never feels surprise at the result.
+
+## Before anything else: pick a tour stem, confirm scope and cost
+
+### Tour stem
+
+Every tour is keyed by a short kebab-case **stem** that names the focus of the tour. The stem becomes the filename prefix for every artifact: `<stem>.dot`, `<stem>-tour.md`, `<stem>-hires.png`, `<stem>.layout.json`, and the rendered `<stem>-tour-<timestamp>.mp4`. Distinct stems coexist in the same `.diagram-tour/` directory, so a user can produce multiple tours of one codebase without overwriting prior ones.
+
+Derive the stem from what the user asked:
+
+| Prompt | Stem |
+|---|---|
+| `/diagram-tour explain this codebase` (or any whole-codebase ask) | `architecture` |
+| `/diagram-tour explain how the API works` | `api` |
+| `/diagram-tour show the data pipeline` | `data-pipeline` |
+| `/diagram-tour walk through the build system` | `build-system` |
+| `/diagram-tour tour the worker internals` | `worker` |
+
+Rules:
+- Lowercase, kebab-case, 1-3 words, no punctuation.
+- Default to `architecture` only for whole-codebase asks; pick something specific otherwise.
+- If `.diagram-tour/<stem>.dot` already exists, **ask the user** whether to overwrite, refine the existing one, or pick a different stem. Do not silently overwrite.
+
+State the chosen stem in your scope-confirmation message so the user can correct it if the inferred name doesn't fit.
+
+### Scope and cost
+
+Render time is non-trivial — roughly 15-30 min on modern hardware, longer on lighter machines, and proportional to diagram size. The user must opt in *before* you start.
+
+Open with a single message that:
+
+1. Restates what you're about to do, in one sentence.
+2. Names the working directory (or repo root, if detected via `.git`/`pyproject.toml`/`package.json` walk-up from the user's cwd).
+3. Names the **tour stem** you've chosen.
+4. Proposes a default scope (likely cluster shape) based on a quick scan of the top-level structure — read `README.md`, `package.json` or `pyproject.toml`, and `ls` the top-level `src/` directory. **Do not** read source files yet; that comes later.
+5. Names the expected output: `<project>/.diagram-tour/renders/<stem>-tour-<timestamp>.mp4`.
+6. Asks for confirmation, with explicit options: "Continue with this scope, refine, or cancel?"
+
+Example opening (adapt to the codebase):
+
+> I'll analyze this codebase, generate an architecture diagram, write narration, and render a narrated MP4 tour.
+>
+> **Detected**: Next.js + Prisma + BullMQ portal at `/path/to/repo`.
+> **Tour stem**: `architecture` (whole codebase). Will write `.diagram-tour/architecture.dot`.
+> **Best guess at scope**: cluster by top-level `src/` directories — `worker`, `lib`, `app`, `actions`, `components`. Plus a Prisma models cluster. Roughly 12-18 nodes across 5-6 clusters.
+> **Estimated runtime**: 15-30 min on modern hardware, longer on lighter machines.
+> **Output**: `.diagram-tour/renders/architecture-tour-<timestamp>.mp4`.
+>
+> Continue with this scope, refine (e.g. "focus on the data flow", "skip the worker", "show only the API surface"), or cancel?
+
+Wait for confirmation. **Do not proceed until the user explicitly says go.**
+
+## The four stages
+
+Each stage produces an artifact and gates on user approval. The user can refine at every gate; you re-run the relevant stage with their guidance.
+
+### Stage 1 — Scope analysis (no expensive work)
+
+Once the user confirms, scan the codebase:
+- Read `README.md`, `package.json` or `pyproject.toml`, and any obvious docs/architecture pointers.
+- `ls` the top-level structure and key directories.
+- Sample a few entry-point files (e.g. `src/index.ts`, `src/main.py`, the file `package.json` "main" points at).
+- Skim — don't read everything. Goal is to pick the right cluster boundaries, not understand every line.
+
+Then write `<project>/.diagram-tour/<stem>.dot` (using the stem chosen in the scope-confirmation step). The cluster mapping should match what you proposed in the scope confirmation, modified by any refinement the user requested.
+
+Conventions for the `.dot`:
+- One cluster per major architectural concern (worker, lib, UI, DB, etc.).
+- 8-15 nodes per cluster max — denser is unreadable in a tour.
+- Use `rankdir=LR` for typical request-flow diagrams; `rankdir=TB` for layered architectures.
+- Cluster labels follow the form `"Worker process  (src/worker)"` — a natural name plus optional path. Stage 3 narration matches against the natural name part.
+- Node labels: file names verbatim where possible (`triage.ts`, `imap.client.ts`). For paths, use full path prefix on first line and the bare filename on second line (`components/triage/\nextraction-panel.tsx`) — the matcher accepts both forms.
+- Color clusters with light fill colors and slightly darker borders. Node colors should match their cluster fill but a bit darker.
+- Edges should reflect actual code relationships — function calls, data flow, ownership — not file imports unless the codebase has clean modules.
+
+### Stage 2 — `.dot` review gate
+
+Render a preview PNG so the user can see what they'll be touring:
+
+```
+(Or if `analyze` isn't a separate operation yet, render manually with `dot -Tpng -Gdpi=120 .diagram-tour/<stem>.dot -o .diagram-tour/<stem>-preview.png`.)
+
+Then present:
+
+> Here's the diagram I generated. [Show a brief textual summary: N clusters, M nodes, key edges.]
+>
+> Approve and continue to narration, refine, or edit `.diagram-tour/<stem>.dot` directly?
+
+Common refinement requests and how to handle them:
+
+| User says | What to do |
+|---|---|
+| "Make it simpler" | Drop ~30% of nodes (least-essential first), collapse closely-related nodes |
+| "Split the lib cluster" | Split into sub-concerns (e.g. data, parsing, network) |
+| "Show data flow not file dependencies" | Replace edges with read/write/transform relationships |
+| "Focus on X" | Drop unrelated clusters; expand the X area into more nodes |
+| "Show MCP servers" / domain-specific add | Add the cluster they're missing |
+
+Re-render the preview after each refinement. **Don't proceed to narration until they explicitly approve.**
+```
+
+### Stage 3 — Narration generation
+
+Now read the source files referenced by node names. You're writing prose — accuracy matters.
+
+Write `<project>/.diagram-tour/<stem>-tour.md` following `CONVENTIONS.md` strictly:
+
+- **YAML frontmatter** declaring the stop-cluster mapping.
+- **One stop per cluster** plus an Orientation stop (Stop 1, FULL) and a Closing stop (final, FULL).
+- **One paragraph per stop**, ~50-100 words.
+- **Use exact node names verbatim** in narration where natural — these become arrow callouts automatically.
+- **Use exact cluster natural-names** when referring to clusters — these become yellow box callouts.
+- **Closing summary references clusters by name in flow order** so the camera traces the loop.
+
+Example stop:
+
+```markdown
+
+## Stop 3 — Worker process
+
+The worker is the long-running background process. Three files: index.ts
+registers BullMQ Workers; imap.client.ts polls IMAP every 60 seconds and
+saves new messages; extraction.processor.ts handles extract-message jobs
+by calling into triage.ts. The worker runs continuously, separate from
+the Next.js app.
+```
+Notice: `index.ts`, `imap.client.ts`, `extraction.processor.ts`, and `triage.ts` will each get an arrow because they appear in narration.
+
+After writing all stops, present the markdown to the user:
+
+> Here's the narration script. [Brief summary: N stops, ~M words total, ~K min spoken at standard pacing.]
+>
+> Approve and render, refine, or edit `.diagram-tour/<stem>-tour.md` directly?
+
+Common refinements:
+- "Sounds too academic" / "more conversational" — rewrite with shorter sentences and active voice
+- "Add more detail on X" — expand that specific stop
+- "Drop the closing" — keep the orientation but remove the loop summary
+- "Different voice" — note that voice is set at render time via `--voice`; defer to stage 4
+```
+
+### Stage 4 — Render
+
+Invoke the pipeline:
+
+# or with a non-default voice:
+python -m diagram_tour --dot .diagram-tour/<stem>.dot --voice en_US-ryan-high
+```
+Tell the user:
+
+> Rendering. ~15-30 min depending on hardware. I'll notify you when done.
+
+You can run the command in the background and continue handling other user requests. When complete, report:
+
+> ✓ Done: `.diagram-tour/renders/<stem>-tour-<timestamp>.mp4` (Y minutes long)
+>
+> The latest symlink at `.diagram-tour/<stem>-tour-latest.mp4` points at this render. Open it to evaluate.
+```
+
+## Cache behavior
+
+The `.diagram-tour/` workspace at the project root caches expensive intermediates:
+
+- `<stem>.dot` and `<stem>-tour.md` persist between runs — re-runs against the same stem without changes skip stages 1-3.
+- `<stem>-hires.png` and `<stem>.layout.json` are regenerated only when `<stem>.dot` is newer.
+- `voice-cache/<hash>.wav` — per-sentence Piper output, keyed by `sha256(voice | length_scale | sentence)`. Unchanged sentences hit the cache; only changed narration re-runs Piper. Voice cache is shared across all stems in the project.
+
+**Cache scope**: per-project, content-addressable. The cache lives at the project root (located via `.git`/`pyproject.toml`/`package.json` walk-up from the `.dot` file) and is shared across all diagrams in that project. Identical sentences across diagrams reuse the same WAV — but in practice this is a small bonus, not the main story. Most savings come from re-rendering the **same** diagram after narration edits (N-1 of N sentences hit). Different diagrams in one repo (data flow vs. deployment vs. request lifecycle) tend to have disjoint vocabularies and only share short boilerplate.
+
+**Iteration impact**: edit one paragraph in `<stem>-tour.md`, re-run the render, and only the changed sentences re-TTS. ~5-min iteration loop instead of ~30 min for a full rebuild. This is the main efficiency win and the reason the cache layer exists.
+
+When telling the user about cache behavior, lead with the iteration win, not the cross-diagram dedup. The latter is mostly an implementation detail.
+
+## Power-user operations
+
+The skill exposes individual stages so users can re-enter mid-pipeline:
+
+| Operation | What it does |
+|---|---|
+| `/diagram-tour` (no args) | Full pipeline from scratch with confirmation gates (the conversational flow above) |
+| `/diagram-tour analyze` | Stage 1 only — generates the `.dot`, shows preview, stops |
+| `/diagram-tour narrate` | Stage 3 only — rewrites narration against an existing `.dot` |
+| `/diagram-tour render` | Stage 4 only — re-renders from existing `.dot` + `.md` (no LLM, no confirmation gates) |
+| `/diagram-tour preview` | Quick low-DPI render for fast iteration on overlay positions |
+
+When the user invokes a partial operation, skip the confirmation gates that don't apply but **still confirm before stage 4** if it'll trigger a fresh render.
+
+## Refinement patterns
+
+When the user says "regenerate" or "do it again", be explicit about what you're regenerating:
+
+- "Regenerate the diagram" → rerun stage 1 (analyze + write .dot)
+- "Regenerate the narration" → rerun stage 3 (using existing .dot)
+- "Re-render" → rerun stage 4 (using existing .dot + .md)
+
+When the user makes a vague request, infer the intended scope but state it back to them before acting:
+
+> User: "Add MCP servers to this"
+> You: "I'll add an MCP servers cluster to the diagram. That's a stage 1 + stage 3 regeneration (new cluster needs narration too). Proceed?"
+
+## Failure modes and degradation
+
+| Symptom | Cause | Action |
+|---|---|---|
+| `piper: command not found` | Piper not installed | Direct user to `~/.claude/skills/diagram-tour/install.sh` |
+| `[voice] download failed` | Network or invalid voice name | Surface the error; suggest verifying the voice name on rhasspy/piper-voices |
+| `dot: command not found` | Graphviz not installed | Install via `apt install graphviz` / `brew install graphviz` / equivalent |
+| `ffmpeg: command not found` | ffmpeg not installed | Install via OS package manager |
+| Stage 4 takes much longer than estimated | Large diagram or slow hardware | Don't kill it — show progress and wait; users on fast machines should expect 5-10 min |
+| User wants to cancel mid-render | Background process running | Kill the background bash task |
+
+If a user runs the skill but cancels at the scope confirmation, exit cleanly without writing any files.
+
+## Stage-by-stage checklist (for self-verification)
+
+Before declaring "done":
+
+- [ ] Confirmed scope with user before any expensive work
+- [ ] `.dot` written, preview shown, **explicit user approval** received
+- [ ] `.md` written following `CONVENTIONS.md`, shown, **explicit user approval** received
+- [ ] Render kicked off; user notified about runtime expectation
+- [ ] Final MP4 path reported; symlink updated
+- [ ] No partial files left behind from any failed stage
+
+## What this skill is NOT
+
+- Not a code review tool. If the user asks "is this code good?", that's a different request — don't answer with a tour.
+- Not a static-diagram generator. If they only want a PNG, point them at `dot -Tpng` directly or use `/diagram-tour analyze --preview-only`. Tour videos are 15+ min of compute.
+- Not a documentation site. The output is a single MP4 + a `.dot` + a `.md`. If they want a docs site, that's outside scope.
+
+## Reference files
+
+These live in the skill repo and define the operational details:
+
+- `CONVENTIONS.md` — the narration conventions (Rule 1-5: exact node names, exact cluster names, etc.)
+- `lib/voices.py` — voice resolution and auto-download
+- `lib/cache.py` — `.diagram-tour/` workspace, voice cache, staleness detection
+- `render_video.py` — the deterministic pipeline (Stage 4)
+- `examples/` — sample `.dot` + `.md` pairs the user can study
+
+When in doubt about a behavior, the code is the ground truth. When in doubt about narration style, `CONVENTIONS.md` is the ground truth.
+
+## Source
+
+Rewritten for AICUT from [`centraltowerlabs/diagram-tour`](https://github.com/centraltowerlabs/diagram-tour)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/diagram-tour/examples/agent-architecture/agent-architecture-tour.md

@@ -0,0 +1,78 @@
+---
+diagram-tour: 1
+diagram: ./agent-architecture.dot
+stops:
+  1: FULL
+  2: cluster_external
+  3: cluster_core
+  4: cluster_tools
+  5: cluster_memory
+  6: FULL
+---
+
+# AI Agent Architecture — Tour
+
+## Stop 1 — Orientation
+
+This is the architecture of a typical Claude-style AI agent. Four
+clusters in this diagram. External, where the user, the Anthropic
+API, and MCP Servers sit. The Agent Core, where every request gets
+routed. Tools, which the agent can invoke during a turn. And Memory,
+where context across turns and sessions lives. We'll trace what
+happens when a user sends a message and how the agent decides what
+to do.
+
+## Stop 2 — External boundary
+
+The External cluster is the boundary. The User is the chat surface,
+the CLI, or any API caller. The Anthropic API is what the agent
+sends prompts to, and where streaming responses come from with
+optional tool_use blocks. MCP Servers are external processes that
+expose additional tools via the Model Context Protocol — a standard
+way for agents to discover and call capabilities they didn't ship
+with.
+
+## Stop 3 — Agent Core
+
+The Agent Core has four parts. The orchestrator is the agent loop;
+it owns the request lifecycle from input to final output. The
+context builder assembles each prompt: system instructions plus
+conversation history plus retrieved facts from memory. The tool
+router parses tool_use blocks from the model's response and
+dispatches each call, in parallel when possible. The response
+composer streams output tokens back to the user, formats citations,
+and handles the final message.
+
+## Stop 4 — Tools
+
+The agent can call three built-in tool categories. bash runs shell
+commands and manages background processes. file ops handle read,
+write, edit, glob, and grep operations on the local filesystem.
+web fetch retrieves HTTP resources, performs search queries, and
+fetches documentation. Together these cover the everyday
+capabilities a coding agent needs without reaching for any
+external tooling.
+
+## Stop 5 — Memory layers
+
+Three memory layers with different lifetimes. working context is
+turn-scoped and must fit in the model's context window; every
+prompt rebuilds it fresh from the others. session memory holds
+conversation-scoped state: summaries of earlier turns, pinned facts,
+anything that should persist for the duration of one chat.
+persistent memory is file-backed and survives across sessions: a
+user profile, project conventions, long-lived preferences. The
+context builder reads from all three; the orchestrator decides what
+to write back after each turn.
+
+## Stop 6 — The full loop
+
+That's the loop. The User in the External cluster sends a prompt
+to the orchestrator in the Agent Core. The context builder reads
+from Memory and assembles the message. The orchestrator calls the
+Anthropic API. If the response contains tool calls, the tool
+router dispatches them — to built-in Tools or to MCP Servers — and
+feeds the results back. The orchestrator may loop, calling the
+model again with tool results, until the response is final. Then
+the response composer streams the output. State updates land in
+Memory, and the loop is ready for the next turn.