@justjoshn/pi-pstack 0.15.36-pi.1 → 0.15.36-pi.8

package/skills/ketchup-video/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Ketchup video
 
-Follow [`/ketchup`](../ketchup/SKILL.md), but show what happened in a short subtitled video instead of its summary and visuals. Its window starts at the last message the user wrote before `/ketchup-video`, not before any earlier `/ketchup`. Writing and rendering the video, outside the repo, is the one exception to its read-only rule. The reply is ketchup's opening sentence, the embedded video, one line naming any work left that you can do yourself, and the action items. When the video shows a call's options, call each option by the name the video gives it. If the render fails, say so in one line and give only the calls.
+Follow [`/ketchup`](../ketchup/SKILL.md), but show what happened in a short subtitled video instead of its summary and visuals. Its window starts at the last message the user wrote before `/ketchup-video`, not before any earlier `/ketchup`. Writing and rendering the video, outside the repo, is the one exception to its read-only rule. After render and frame QC, open the mp4 with the OS player (`open` on macOS, `xdg-open` on Linux), read one frame per slide with the read tool for terminals that support images, and name the video path in the reply. Pi chat does not play video inside a reply, so do not assume Markdown embedding plays it. The reply is ketchup's opening sentence, that video delivery (open, path, and frames), one line naming any work left that you can do yourself, and the action items. When the video shows a call's options, call each option by the name the video gives it. If the render fails, say so in one line and give only the calls.
 
 ## Slides
 
@@ -26,4 +26,4 @@ Give each slide one short subtitle line, about ten words, that says its point th
 
 Render one silent landscape video, such as an mp4, with motion between slides. Every frame is the slide itself, edge to edge, above its subtitle strip. Make the frames from the slides, never by recording a screen, and burn each subtitle into its slide's frames so it stays on screen for the slide's whole hold. The hold is the time a slide is fully on screen, not counting the motion into or out of it. Hold each slide long enough to read the words it adds, at least one second for each three words. A slide adds its subtitle and each word that was not on the slide before it, including a label it changes. The first slide adds all its words. Words inside a screenshot do not count.
 
-Before you embed the video, check the rendered file. Look at one frame from each slide at chat size, and check that its subtitle is readable and covers nothing. Measure each hold by matching the file's frames to the slide, not with a still-frame detector, which counts the faint ends of a fade as still. Count the words each slide adds against its measured hold. Fix any slide you cannot read in that time, render again, and check again.
+Before you deliver the video, check the rendered file. Look at one frame from each slide at chat size, and check that its subtitle is readable and covers nothing. Measure each hold by matching the file's frames to the slide, not with a still-frame detector, which counts the faint ends of a fade as still. Count the words each slide adds against its measured hold. Fix any slide you cannot read in that time, render again, and check again. Then open the file in the system player, read one frame per slide into the reply, and name the path.

package/skills/loop-on-ci/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: loop-on-ci
+description: Monitor PR checks and fix failures until green. Uses gh pr checks as the source of truth for PR-attached checks.
+---
+
+# Loop on CI
+
+## Trigger
+
+Need to watch a branch or pull request and iterate on CI failures until all required checks are green.
+
+Use `gh pr checks` as the source of truth. It includes all PR-attached checks, while `gh run list` only covers GitHub Actions.
+
+## Workflow
+
+1. Resolve the PR for the current branch.
+2. Inspect current PR checks before waiting.
+3. If checks already failed, diagnose those failures first.
+4. If checks are pending, watch with `gh pr checks --watch --fail-fast`.
+5. After each push, re-check the full PR check set and repeat until green.
+
+## Commands
+
+```bash
+# Resolve the active PR
+gh pr view --json number,url,headRefName
+
+# Inspect all attached checks
+gh pr checks --json name,bucket,state,workflow,link
+
+# Watch pending checks and fail fast
+gh pr checks --watch --fail-fast
+
+# GitHub Actions logs, when the failing check links to a GHA run
+gh run view <run-id> --log-failed
+```
+
+## Guardrails
+
+- Keep each fix scoped to a single failure cause when possible.
+- Do not bypass hooks (`--no-verify`) to force progress.
+- If the failure is clearly unrelated to the PR and appears fixed on main, merge latest main instead of bloating the PR with unrelated fixes.
+- If failures are flaky, retry once and report flake evidence.
+- Re-run `gh pr checks --json name,bucket,state,workflow,link` after every push; the check set can change.
+
+## Output
+
+- Current CI status
+- Failure summary and fixes applied
+- PR URL once checks are green

package/skills/make-bot-ui/SKILL.md

@@ -20,7 +20,7 @@ Call `subscribe_webhook`. Set these fields:
 The routine slug is the kebab-case form of the name.
 The result gives the routine URL, `http://127.0.0.1:<port>/routines/<slug>`, and the credential file path. Use the path the result names, such as `~/.pi/agent/pstack/routines/<slug>/credentials.json` (`PI_CODING_AGENT_DIR` moves it).
 The result does not include the sender key.
-The routine lives in this Pi process: it stops when Pi exits and expires at the `expiresAt` the result names. Keep this Pi session running while the UI is in use, and check it with `list_subscriptions`.
+The routine targets the owning Pi session and expires at the `expiresAt` the result names. The durable supervisor keeps the listener available after the chat exits. Wakes received while the owner is offline park until that session is restored. Keep the owner running for immediate UI actions, and check the routine with `list_subscriptions`. A timer with `sessionStrategy: "new_session"` can start detached work while the owner is offline. A webhook does not use that strategy.
 
 ## Copy the URL and the sender key
 
@@ -55,7 +55,7 @@ The server POSTs to the routine URL with:
 - timeout: 8 seconds
 - one try, no retry
 
-The POST returns HTTP 200 when the routine wakes.
+The POST returns HTTP 200 when the routine accepts the event. This does not prove that the owning session has handled it.
 Before you tell the user that the UI is live, probe once with a harmless payload.
 Use an action that the prompt ignores.
 

package/skills/make-pr-easy-to-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: make-pr-easy-to-review
+description: Prepare PRs for review by cleaning noisy history, improving PR descriptions, and adding reviewer guidance without changing code behavior. Use for "make this easy to review", "tidy this PR", "clean up commits", or "annotate the diff".
+---
+
+# Make PR Easy to Review
+
+Prepare a PR so a reviewer can quickly understand the intent, important files, and risk. The default goal is reviewability without behavior changes.
+
+## Workflow
+
+1. Resolve the target PR from the user-provided URL or current branch.
+2. Inspect commits, diff size, changed paths, generated files, and PR description.
+3. Identify reviewability issues: noisy commits, stale description, unrelated changes, mixed mechanical and logic changes, missing tests, or unclear reviewer entry points.
+4. Propose a plan before rewriting history or force-pushing.
+5. Apply safe improvements, then verify the tree or diff still matches the intended code.
+
+## History Cleanup
+
+Only rewrite history when the user asks for it or agrees to the plan. Before rewriting:
+
+```bash
+gh pr view <PR> --json title,headRefName,baseRefName,state,commits
+git fetch origin <headRefName> <baseRefName>
+ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})
+```
+
+Good commit groupings usually follow dependency order:
+
+1. Schema/storage or generated API definitions.
+2. Core logic.
+3. Wiring and integration.
+4. UI or surface behavior.
+5. Tests.
+
+After rewriting, verify content identity:
+
+```bash
+echo "Original tree: $ORIGINAL_TREE"
+echo "Current tree:  $(git rev-parse HEAD^{tree})"
+git diff origin/<headRefName> --stat
+```
+
+Do not push if the tree changed unintentionally.
+
+## Reviewer Guidance
+
+When code behavior should stay untouched, prefer PR description and review notes:
+
+- Add a TL;DR that matches the actual diff.
+- Separate core files from generated or mechanical files.
+- Call out risky behavior changes, migration order, rollout plan, and test coverage.
+- Link issue trackers, dashboards, or design docs when they explain intent.
+
+## Guardrails
+
+- Never hide meaningful behavior changes inside "cleanup".
+- Do not bypass hooks unless the user explicitly asks.
+- If the PR is too large to make reviewable with notes, recommend splitting instead of polishing around the problem.

package/skills/new-branch-and-pr/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: new-branch-and-pr
+description: Create a fresh branch, complete work, and open a pull request
+---
+
+# New branch and PR
+
+## Trigger
+
+Starting work that should be shipped through a clean branch and pull request workflow.
+
+## Workflow
+
+1. Ensure the working tree is clean or explicitly handled.
+2. Create a descriptive branch from the latest main.
+3. Complete implementation and tests.
+4. Commit focused changes and push.
+5. Create a concise PR with summary and test notes.
+
+## Guardrails
+
+- Keep branch scope focused on one change set.
+- Include verification notes before requesting review.
+
+## Output
+
+- New branch name
+- PR summary and test notes
+- PR URL

package/skills/no-inline-imports/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: no-inline-imports
+description: Keep imports at top of file and avoid inline imports
+disable-model-invocation: true
+---
+
+# No Inline Imports
+
+# No inline imports
+
+Always place imports at the top of the module. Avoid inline imports in function bodies, type annotations, or interface fields unless there is a strict circular-dependency reason and it is documented.
+

package/skills/poteto-help/SKILL.md

@@ -24,7 +24,7 @@ Infer the need from the message and the conversation. A named situation, such as
 
 Check the state that changes the answer, and mention it only when it does:
 
-- No `~/.pi/agent/pstack/pstack-models.md` means `/setup-pstack` hasn't run for this user, so every role uses its default model.
+- If the model rule is absent at the path the system prompt names, every role uses its default model. Do not infer absence from the default path when `PI_CODING_AGENT_DIR` relocates it.
 - No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works.
 - No formal verification skill in the project means no property is checked past what tests reach. Mention `/create-formal-verification-skill` when the question is about a race, an invariant, or another case tests rarely hit. When one exists and the code it covers changed after the commit it records as last in sync, mention `/maintain-formal-verification-skill` if the question touches that code.
 
@@ -39,7 +39,7 @@ When the model rule is missing and it matters, ask whether the user wants to pic
 2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes the model rule. The rule applies from the next request. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one.
 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail.
 
-Installing adds pi-pstack's tools and system-prompt sections, and no skill runs until the user invokes one. Only `/setup-pstack`, and the `/create-skill`, `/deslop`, `control-cli`, and `control-ui` skills pi-pstack ships outside pstack, load from the user's words. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md).
+Installing adds pi-pstack's tools and system-prompt sections. Pi advertises `/setup-pstack` and bundled skills whose frontmatter does not set `disable-model-invocation: true`. The model may read those skills when the user's request matches. Most pstack workflow skills stay hidden from automatic selection and load through an explicit command or another skill's instructions. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md).
 
 If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor.
 
@@ -140,8 +140,8 @@ Principles are one-rule skills that `/poteto-mode` reads and cites in its replie
 | A question got treated as the next step of the last task | Say "new task", or say the turn doesn't need the mode. |
 | A new model choice had no effect | The rule from `/setup-pstack` applies from the next request. Send one. |
 | Runs cost more than expected | See the cost paragraph under Get set up. |
-| A skill didn't load on its own | Only `/setup-pstack`, and the `/create-skill`, `/deslop`, `control-cli`, and `control-ui` skills pi-pstack ships outside pstack, load from the user's words. The others load when the user types them or when `/poteto-mode` runs them, and it doesn't run every skill. |
-| Parallel agents overwrote each other | Give each agent its own worktree, or run them as isolated workers (`environment: "cloud"`), which each get their own git worktree. |
+| A skill didn't load on its own | Check its `disable-model-invocation` frontmatter. Hidden skills load when the user types their command or another skill tells the model to read them. `/poteto-mode` does not run every skill. |
+| Parallel agents overwrote each other | Give each agent its own git worktree with `environment: "cloud"`. They still share this machine. Assign distinct ports, output directories, and writable cache paths to concurrent runtime lanes. Stronger machine isolation is not provided. |
 | An overnight run moved but finished nothing | `/loop` needs a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). |
 | The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. |
 

package/skills/poteto-mode/playbooks/multi-phase-plan.md

@@ -68,7 +68,7 @@ Tests alone are not sufficient verification. A PR is verified only when its unit
 
 ### Boot recipe, for every live lane
 
-Each live lane runs as its own isolated worker (`environment: "cloud"`) at the PR head. Drive through `control-ui` or `control-cli`, shipped with pi-pstack.
+Each live lane runs in its own git worktree (`environment: "cloud"`) at the PR head on this machine. Assign each concurrent lane distinct ports, output directories, and writable cache paths. A worktree does not provide VM or credential isolation. If the lane needs stronger machine isolation, mark it blocked until that isolation is available. Drive through `control-ui` or `control-cli`, shipped with pi-pstack.
 
 - [ ] `git fetch origin <head-branch> && git checkout <head SHA>`.
 - [ ] <Start the backend and the surface. Wait for ready.>

package/skills/poteto-mode/playbooks/orchestrate.md

@@ -7,7 +7,7 @@ Run it with your own tools. Spawn workers with `Task`. Keep the program's state
 #### Topology
 
 - **One owner per PR.** The owner is the only writer of its branch and carries the PR from build to merge. Only the owner pushes, rebases, or retargets it. Closing or retargeting a base PR orphans every PR above it, so the owner does that only on your call. You never author or edit code. Conflicted merges, chain rebases, and fixes go to owners.
-- **A fresh worker for each independent task.** Its kickoff carries everything it needs, including each upstream report it depends on, pasted in full. Workers can't see their siblings. Run workers as a new isolated worktree worker (`environment: "cloud"`) unless the work needs this machine: a `control-ui` or `control-cli` runtime check (shipped with pi-pstack), local transcripts, a simulator, or auth that exists only here. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section.
+- **A fresh worker for each independent task.** Its kickoff carries everything it needs, including each upstream report it depends on, pasted in full. Workers can't see their siblings. Run workers in a new git worktree (`environment: "cloud"`) unless the work needs the existing checkout or its uncommitted state. Both environments run on this machine and can access its local transcripts, simulators, and auth. Assign distinct ports, output directories, and writable cache paths to concurrent runtime workers, including `control-ui` and `control-cli` checks. A worktree is not a machine or credential boundary. Report stronger isolation as unavailable when the task requires it. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section.
 - **A sub-coordinator only when one area has many parallel workers.** It owns that area's workers and kickoffs and sends you one rollup, never raw worker reports. Stop at three levels: you, sub-coordinators, and workers. Keep about ten workers in flight per coordinator, and start the next one as each finishes instead of waiting on a whole batch.
 - **Fork with Task `fork` when new work needs a worker's built state,** such as its checkout, uncommitted changes, or a running process. Message a worker with Task `resume` only for a follow-up on the same work. Never message one to check on it, because a message restarts an idle agent.
 - **Each PR gets a verifier that isn't its author,** on a different model family. The owner merges only on that verifier's pass at the current head.

package/skills/pr-review-canvas/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: pr-review-canvas
+disable-model-invocation: true
+description: Generate an interactive PR review walkthrough as an HTML page. Fetches PR data via gh API, categorizes files into core vs mechanical changes, adds reviewer annotations, and renders diffs with moved-code detection. Use when the user pastes a GitHub PR URL and asks for a review, walkthrough, or summary, or says "review this PR".
+---
+
+# PR Review Canvas
+
+Generate an interactive HTML review of a GitHub PR that reads like a peer walking you through what matters.
+
+## Workflow
+
+### 1. Fetch PR data
+
+Run these `gh api` calls in parallel:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{number} --jq '{title, body, user: .user.login, state, additions, deletions, changed_files, base: .base.ref, head: .head.ref}'
+gh api repos/{owner}/{repo}/pulls/{number}/files --paginate --jq '.[] | {filename, status, additions, deletions, patch}'
+gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {user: .user.login, body, path, line}'
+```
+
+### 2. Analyze the PR and write the body HTML
+
+Read the diffs, understand the PR, and write the `<body>` content directly as HTML. You have full creative freedom -- the goal is to explain the PR clearly to a reviewer. Use whatever structure best fits the PR.
+
+**Typical structure** (adapt as needed):
+- Header with title, PR number, author, stats
+- Summary box explaining what the PR does in plain English
+- Core file sections with annotations and diffs
+- Mechanical/boilerplate files collapsed by default
+- Review checklist at the bottom
+
+**But you can also add:**
+- **Pseudocode summaries** for verbose code -- show the algorithm in plain English or short pseudocode, with the real diff collapsed below (use a `.bp-section` card labeled "Show full implementation"). Great when 150 lines of retry/backoff/error-handling code is really just "fetch with exponential backoff and circuit breaker."
+- Diagrams (inline SVG, mermaid via CDN, ASCII art in `<pre>`)
+- Flowcharts showing before/after control flow
+- Tables comparing old vs new behavior
+- Callout boxes for warnings, questions, or gotchas
+- Interactive widgets if they help
+- Anything else that makes the review clearer
+
+**Pseudocode pattern example:**
+```html
+<div class="file-card">
+  <div class="file-hdr" onclick="toggle(this)">
+    <span class="fname">retryClient.ts</span>
+    <div class="fstats"><span class="pill add">+173</span><span class="pill del">&minus;11</span><span class="chev open">&#9654;</span></div>
+  </div>
+  <div class="file-body open">
+    <div class="file-note">
+      <strong>What this does in plain English:</strong>
+      <pre style="margin-top:8px;color:var(--text);font-size:12px;line-height:1.6;">
+fetch(url):
+  if circuit breaker is open → fail fast
+  retry up to N times:
+    try fetch with timeout
+    on success → close circuit breaker, return
+    on retryable error → wait (exponential backoff + jitter)
+    on non-retryable error → throw
+  circuit breaker records failure</pre>
+    </div>
+    <div class="bp-section" style="margin:0;border:0;border-radius:0;">
+      <div class="bp-hdr" onclick="toggleBP(this)">
+        <span>Show full implementation (+173 lines)</span><span class="chev">&#9654;</span>
+      </div>
+      <div class="bp-body"><div data-diff="retryClient"></div></div>
+    </div>
+  </div>
+</div>
+```
+
+### 3. Available CSS classes and JS utilities
+
+Read [styles.css](styles.css) and [renderer.js](renderer.js) from this skill directory. These give you a prebuilt dark-themed toolkit. Inject them into [template.html](template.html) verbatim.
+
+**CSS classes you can use:**
+
+| Class | Purpose |
+|-------|---------|
+| `.header`, `.header h1`, `.header-meta` | Page header |
+| `.pill.add`, `.pill.del`, `.pill.files` | Stat badges (+N, -N, N files) |
+| `.content` | Centered content wrapper (max 900px) |
+| `.summary` | Summary/TL;DR box |
+| `.section-title` | Section heading with bottom border |
+| `.ic` | Inline code reference (mono, blue, dark bg) |
+| `.file-card`, `.file-hdr`, `.file-body` | Collapsible file card (use `onclick="toggle(this)"` on `.file-hdr`) |
+| `.file-note` | Sticky reviewer annotation inside a file card |
+| `.bp-section`, `.bp-hdr`, `.bp-body` | Collapsed boilerplate card (use `onclick="toggleBP(this)"`) |
+| `.bp-note` | Note inside a boilerplate card |
+| `.verdict` | Review checklist box |
+
+**JS functions available:**
+
+| Function | Usage |
+|----------|-------|
+| `toggle(hdrElement)` | Toggle a `.file-body` open/closed |
+| `toggleBP(hdrElement)` | Toggle a `.bp-body` open/closed |
+| `renderDiff(target, diffInput)` | Render a unified diff. `target` can be a DOM element, string ID, or CSS selector. `diffInput` can be a raw patch string OR an array of lines -- both work. Automatically filters imports, collapses whitespace-only changes, detects moved code (blue/purple tint). |
+| `esc(string)` | HTML-escape a string |
+
+**Rendering diffs -- use `data-diff` attributes with auto-discovery.**
+Put `<div data-diff="KEY"></div>` placeholders in your body HTML wherever you want a diff rendered. The renderer finds them automatically after DOM load and fills them from the `<script id="pr-diffs-json" type="application/json">` element in `template.html`.
+
+**CRITICAL: Patch strings can contain `</script>` in addition to newlines, backslashes, and quotes.** Even `json.dumps(...)` is not enough if you paste raw output into executable `<script>` because HTML parsing can terminate the tag early. Never manually embed patch strings in JS/JSON. Instead, use this safe approach:
+
+1. During the fetch step, save patches to a JSON file using `jq` (which handles escaping correctly):
+```bash
+gh api repos/{owner}/{repo}/pulls/{number}/files --paginate \
+  --jq '[.[] | {key: (.filename | gsub("[^a-zA-Z0-9]"; "_")), value: (.patch // "")}] | from_entries' \
+  > /tmp/pr-patches-{number}.json
+```
+
+2. During assembly, use Python to safely inject the JSON into `template.html`:
+```bash
+python3 <<'PY'
+import json
+from pathlib import Path
+
+patches = json.loads(Path('/tmp/pr-patches-{number}.json').read_text())
+html = Path('/tmp/pr-review-{number}-body.html').read_text()
+css = Path('styles.css').read_text()
+js = Path('renderer.js').read_text()
+tmpl = Path('template.html').read_text()
+
+# Prevent literal </script> from terminating HTML script tags early.
+safe_json = json.dumps(patches).replace('<', '\\u003c').replace('>', '\\u003e').replace('&', '\\u0026')
+
+out = (
+  tmpl.replace('/* INJECT_CSS */', css)
+      .replace('/* INJECT_JS */', js)
+      .replace('<!-- INJECT_BODY -->', html)
+      .replace('{"__PR_DIFFS_PLACEHOLDER__":true}', safe_json)
+)
+
+Path('/tmp/pr-review-{number}.html').write_text(out)
+PY
+```
+
+This guarantees valid JSON and script-safe HTML embedding. The agent writes body HTML to a temp file, then Python assembles everything safely.
+
+The diff data keys should match the `data-diff` attribute values in the HTML:
+```html
+<div data-diff="path_to_file_ts"></div>
+```
+
+Since renderer.js loads in `<head>`, you can also call `renderDiff(target, lines)` directly from inline `<script>` tags if needed for custom use cases. The function accepts a DOM element, ID string, or CSS selector as `target`, and a string or array as `lines`.
+
+**You're not limited to these.** Add your own inline `<style>` blocks, `<script>` blocks, SVGs, diagrams, or anything else. The prebuilt pieces save time but don't constrain you.
+
+### 4. Assemble and serve
+
+1. Write your body HTML (everything that goes inside `<body>`) to `/tmp/pr-review-{number}-body.html`
+2. Save patches to `/tmp/pr-patches-{number}.json` using the `jq` command from step 3 above
+3. Run the Python assembly script from step 3 above (reads styles.css, renderer.js, template.html from this skill directory, injects body + patches safely, writes final HTML)
+4. Start a local server on a fixed port:
+   ```bash
+   cd /tmp && python3 -m http.server 8432 --bind 127.0.0.1
+   ```
+   Run this backgrounded, then navigate the in-app browser to `http://127.0.0.1:8432/pr-review-{number}.html`.
+
+   **Why a fixed port and `cd /tmp`:** Background shells have no TTY, so Python buffers its startup message ("Serving HTTP on...") indefinitely — using port 0 means you can never read which port was chosen. And `--directory /tmp` works but `cd /tmp` is more robust across Python versions. If port 8432 is taken, try 8433, 8434, etc.
+
+### Diff features (handled automatically by renderer.js)
+
+- Filters out import-only lines
+- Collapses whitespace-only changes into context lines
+- Detects moved code blocks (3+ consecutive lines deleted in one place and added identically elsewhere) -- renders in blue/purple instead of red/green
+- Near-matches (moved + small edit) get a different purple tint
+
+### Style notes
+
+- Dark theme: `#1a1a1a` background, Inter body font, IBM Plex Mono for code
+- Use `var(--warning)` for orange, `var(--success)` for green, `var(--danger)` for red, `var(--accent)` for blue
+- Sticky file headers (`position: sticky; top: 0`) and notes (`top: 35px`) pin while scrolling
+- Core files expanded by default (`.file-body.open`), mechanical files collapsed

package/skills/pr-review-canvas/renderer.js

@@ -0,0 +1,170 @@
+function toggle(hdr) {
+  var b = hdr.nextElementSibling, c = hdr.querySelector('.chev');
+  b.classList.toggle('open'); c.classList.toggle('open');
+}
+function toggleBP(hdr) {
+  var b = hdr.nextElementSibling, c = hdr.querySelector('.chev');
+  b.classList.toggle('open'); c.classList.toggle('open');
+}
+
+function isImport(line) {
+  var s = line.replace(/^[+ -]/, '').trim();
+  return s.startsWith('import ') || s.startsWith('import{') || s.startsWith('} from ');
+}
+
+function isWhitespaceOnly(del, add) {
+  return del.replace(/^-/, '').replace(/\s/g, '') === add.replace(/^\+/, '').replace(/\s/g, '');
+}
+
+function esc(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function normWs(s) {
+  return s.replace(/\s+/g, ' ').trim();
+}
+
+function toLines(input) {
+  if (!input) return [];
+  if (Array.isArray(input)) return input;
+  if (typeof input === 'string') return input.split('\n');
+  return [];
+}
+
+function loadPrDiffs() {
+  var el = document.getElementById('pr-diffs-json');
+  if (!el) return null;
+  try {
+    return JSON.parse(el.textContent || '');
+  } catch (err) {
+    console.error('Failed to parse PR diff JSON payload', err);
+    return null;
+  }
+}
+
+function detectMoves(dels, adds) {
+  var TH = 3;
+  var md = {}, ma = {};
+  for (var di = 0; di < dels.length; di++) {
+    if (md[di]) continue;
+    var db = [di];
+    for (var d2 = di+1; d2 < dels.length && d2-di < 40; d2++) {
+      if (dels[d2].consecutive && !md[d2]) db.push(d2); else break;
+    }
+    if (db.length < TH) continue;
+    var dn = db.map(function(i){ return normWs(dels[i].code); });
+    for (var ai = 0; ai < adds.length; ai++) {
+      if (ma[ai]) continue;
+      var ab = [ai];
+      for (var a2 = ai+1; a2 < adds.length && a2-ai < 40; a2++) {
+        if (adds[a2].consecutive && !ma[a2]) ab.push(a2); else break;
+      }
+      if (ab.length < TH) continue;
+      var an = ab.map(function(i){ return normWs(adds[i].code); });
+      var ml = Math.min(dn.length, an.length), mc = 0;
+      for (var m = 0; m < ml; m++) { if (dn[m] === an[m]) mc++; }
+      if (mc >= TH && mc >= ml * 0.7) {
+        for (var k = 0; k < ml; k++) {
+          md[db[k]] = { exact: dn[k] === an[k] };
+          ma[ab[k]] = { exact: dn[k] === an[k] };
+        }
+        break;
+      }
+    }
+  }
+  return { movedDels: md, movedAdds: ma };
+}
+
+/**
+ * renderDiff(target, diffInput)
+ *   target: DOM element, string ID, or CSS selector
+ *   diffInput: array of diff lines, OR a single string (will be split on \n)
+ */
+function renderDiff(target, diffInput) {
+  var el;
+  if (typeof target === 'string') {
+    el = document.getElementById(target) || document.querySelector(target);
+  } else {
+    el = target;
+  }
+  if (!el) return;
+
+  var lines = toLines(diffInput);
+  if (!lines.length) { el.innerHTML = '<div style="padding:12px;color:#777;font-size:12px;">No diff data</div>'; return; }
+
+  var filtered = lines.filter(function(l) {
+    if (l.startsWith('--- ') || l.startsWith('+++ ') || l.startsWith('@@') || l.startsWith('diff ')) return true;
+    return !isImport(l);
+  });
+
+  var wsOut = [];
+  for (var wi = 0; wi < filtered.length; wi++) {
+    if (filtered[wi].startsWith('-')) {
+      var dr = [filtered[wi]], wj = wi+1;
+      while (wj < filtered.length && filtered[wj].startsWith('-')) { dr.push(filtered[wj]); wj++; }
+      var ar = [], wk = wj;
+      while (wk < filtered.length && filtered[wk].startsWith('+')) { ar.push(filtered[wk]); wk++; }
+      if (dr.length === ar.length && dr.length > 0) {
+        var allWs = true;
+        for (var wc = 0; wc < dr.length; wc++) { if (!isWhitespaceOnly(dr[wc], ar[wc])) { allWs = false; break; } }
+        if (allWs) { for (var wx = 0; wx < ar.length; wx++) wsOut.push(' ' + ar[wx].slice(1)); wi = wk-1; continue; }
+      }
+    }
+    wsOut.push(filtered[wi]);
+  }
+
+  var dels = [], adds = [], parsed = [];
+  var oL = 0, nL = 0, pD = false, pA = false;
+  for (var pi = 0; pi < wsOut.length; pi++) {
+    var line = wsOut[pi];
+    if (line.startsWith('--- ') || line.startsWith('+++ ') || line.startsWith('diff ')) continue;
+    if (line.startsWith('@@')) {
+      var hm = line.match(/@@ -(\d+)(?:,\d+)? \+(\d+)/);
+      if (hm) { oL = parseInt(hm[1]); nL = parseInt(hm[2]); }
+      parsed.push({ type: 'hunk', text: line }); pD = false; pA = false; continue;
+    }
+    if (line.startsWith('+')) {
+      var ae = { type:'add', code:line.slice(1), newLine:nL, consecutive:pA, idx:parsed.length };
+      adds.push(ae); parsed.push(ae); nL++; pA = true; pD = false;
+    } else if (line.startsWith('-')) {
+      var de = { type:'del', code:line.slice(1), oldLine:oL, consecutive:pD, idx:parsed.length };
+      dels.push(de); parsed.push(de); oL++; pD = true; pA = false;
+    } else {
+      var c = line.startsWith(' ') ? line.slice(1) : line;
+      parsed.push({ type:'ctx', code:c, oldLine:oL, newLine:nL }); oL++; nL++; pD = false; pA = false;
+    }
+  }
+
+  var mv = detectMoves(dels, adds);
+  var rows = [];
+  for (var ri = 0; ri < parsed.length; ri++) {
+    var p = parsed[ri];
+    if (p.type === 'hunk') {
+      rows.push('<tr class="diff-hunk"><td class="diff-ln"></td><td class="diff-ln"></td><td class="diff-code">' + esc(p.text) + '</td></tr>');
+    } else if (p.type === 'add') {
+      var ai2 = -1; for (var fa=0;fa<adds.length;fa++) if(adds[fa].idx===p.idx){ai2=fa;break;}
+      var cls = (mv.movedAdds[ai2]) ? (mv.movedAdds[ai2].exact ? 'diff-moved-add' : 'diff-moved-add-edited') : 'diff-add';
+      rows.push('<tr class="'+cls+'"><td class="diff-ln"></td><td class="diff-ln">'+p.newLine+'</td><td class="diff-code">'+esc(p.code)+'</td></tr>');
+    } else if (p.type === 'del') {
+      var di2 = -1; for(var fd=0;fd<dels.length;fd++) if(dels[fd].idx===p.idx){di2=fd;break;}
+      var cls2 = (mv.movedDels[di2]) ? (mv.movedDels[di2].exact ? 'diff-moved-del' : 'diff-moved-del-edited') : 'diff-del';
+      rows.push('<tr class="'+cls2+'"><td class="diff-ln">'+p.oldLine+'</td><td class="diff-ln"></td><td class="diff-code">'+esc(p.code)+'</td></tr>');
+    } else {
+      rows.push('<tr class="diff-ctx"><td class="diff-ln">'+p.oldLine+'</td><td class="diff-ln">'+p.newLine+'</td><td class="diff-code">'+esc(p.code)+'</td></tr>');
+    }
+  }
+  el.innerHTML = '<table class="diff-table"><tbody>' + rows.join('') + '</tbody></table>';
+}
+
+/* Auto-discovery: after DOM loads, find all [data-diff] elements and render diffs from pr-diffs-json. */
+document.addEventListener('DOMContentLoaded', function() {
+  var prDiffs = loadPrDiffs();
+  if (!prDiffs) return;
+  var els = document.querySelectorAll('[data-diff]');
+  for (var i = 0; i < els.length; i++) {
+    var key = els[i].getAttribute('data-diff');
+    if (key && Object.prototype.hasOwnProperty.call(prDiffs, key)) {
+      renderDiff(els[i], prDiffs[key]);
+    }
+  }
+});