@overdeck/desktop 0.49.1 → 0.50.0

package/sync-sources/skills/pan-gauntlet-loop/assets/PROMPT.template.md

@@ -0,0 +1,92 @@
+# The Gauntlet — <THING> at the level of <REFERENCE>
+
+<Fill every <ANGLE> slot from the intake, then delete this line. The three
+paragraphs below ARE the mission — keep them first, keep them plain. Anyone
+(model or human) who reads only them must know exactly what we're doing and
+why. Everything after "The machinery" is supporting detail.>
+
+Build <THING — one sentence naming the subject and where it lives (this repo
+/ this package / this site)> at the level of <REFERENCE — the named quality
+bar>. It should be utterly perfect: <LOOK — 2–4 clauses painting the
+committed direction, concrete enough that "wrong even if it's pretty" is
+checkable>, with every single thing done at <TIER — e.g. shipped-commercial>
+quality, from <AREA_1>, to <AREA_2>, … to anything else you could think of.
+
+Fan out sub-agents and have each one tackle a single area individually so
+that <THING> is utterly perfect. Loop on each area: build it, capture real
+evidence of the result (<CHECK — e.g. screenshots / CLI transcripts /
+benchmarks>), and have a SEPARATE sub-agent check that evidence — a really
+harsh critic, never the agent that built it — to ensure it is <TIER>. If it
+isn't <TIER>, the critic's defect list goes back to the builder and the area
+keeps going.
+
+Don't stop until every area's critic is utterly wowed when the result is
+compared with <REFERENCE>. The critic literally puts our evidence and
+<REFERENCE>'s side by side, blind, and says which one is better — WOWED
+means it picked ours without hesitation. Do this in <STACK — normally "this
+repo, stack unchanged">. Loop until it's utterly perfect.
+
+---
+
+## The machinery (how the loop actually runs)
+
+Everything below exists to serve the three paragraphs above. Where they
+conflict, the paragraphs win.
+
+### Why it works — four rules that are the whole game
+
+1. **The bar is a real named thing** the critic can open — not an adjective.
+2. **The builder never grades its own work** — every critic is a fresh
+   sub-agent with no knowledge of the builder's effort or reasoning.
+3. **The verdict is binary** — WOWED or NOT_YET with concrete fixes. Never
+   a score; scores drift upward and everything passes.
+4. **No fixed round count** — the exit is every critic WOWED, or the
+   operator stopping the run.
+
+### Setup state (the orchestrator has already done this)
+
+- All work on branch `<BRANCH>` in worktree `<WORKTREE PATH>` — never the
+  primary checkout.
+- `refs/STYLE.md` is the committed direction; `refs/REFERENCE-BAR.md` is the
+  critic's judging contract; `refs/press/` holds the fetched reference
+  evidence the blind comparisons run against.
+- `gauntlet/` holds the live progress page: `status.json` (the state of
+  every area), `shots/` (canonical evidence per area), `notes/` (every
+  critique JSON). Served at `<DASHBOARD URL>`.
+- <DESIGN AUTHORITY — e.g. PRD.md / docs/ / this prompt> is the design
+  authority. <List binding sections, if any.>
+
+### Ground rules
+
+- The orchestrator reviews and commits per area with path-scoped `git add`;
+  agents do not commit.
+- Scope: <IN — the only surfaces this pass touches>. Deferred: <OUT —
+  explicit exclusions>.
+- Model routing: design-heavy areas and ALL critics → frontier-tier;
+  mechanical implementation, tests, asset runs → workhorse-tier.
+
+### The loop contract (per area, repeated until WOWED)
+
+1. **Implement** — builder sub-agent with the ownership map below and the
+   current defect list as its work order.
+2. **Capture evidence** — launch and drive the real thing; save the
+   canonical capture to `gauntlet/shots/<area-key>.png` (or transcript /
+   benchmark output to `notes/`).
+3. **Critique** — separate harsh critic, fresh context, evidence + `refs/`
+   only, judges blind per `refs/REFERENCE-BAR.md`; verdict JSON lands in
+   `gauntlet/notes/critique-<area>-iter<n>.json`.
+4. **Report** — update `gauntlet/status.json` at every transition (agent
+   launched / landed / awaiting critique / verdict), not just after
+   critiques. A stale dashboard is a bug.
+5. **NOT_YET** → the defect list becomes the next iteration's work order.
+   **WOWED** → area done.
+
+### Areas
+
+<area-key — one-line charter; one per line; each independently judgeable>
+
+### File ownership
+
+<one line per area: the exact paths it owns. Areas sharing files serialize
+in the same wave, never parallel. This map is repeated verbatim in every
+agent prompt.>

package/sync-sources/skills/pan-gauntlet-loop/assets/REFERENCE-BAR.template.md

@@ -0,0 +1,53 @@
+# The Reference Bar — how critics judge
+
+You are judging against <REFERENCE — the named bar>. Reference evidence (in
+`refs/press/`) is the anchor; this rubric is the contract. You see evidence
+only — not the code, not the builder's effort, not its excuses.
+
+## The verdict question
+
+Put the subject's evidence next to the reference's. Answer honestly:
+
+> "<THE STOREFRONT TEST — one sentence, e.g. 'If these two appeared side by
+> side on a store page, would a buyer believe this is a shipped, commercially
+> published product?' See references/domains.md for per-domain phrasings.>"
+
+- **WOWED** = yes without hesitation. The direction (STYLE.md) is confidently
+  executed; nothing reads as placeholder.
+- **NOT YET** = anything else. List every failing element with a concrete fix.
+
+You are a harsh critic. Your job is to find what's below the bar, not to be
+encouraging. "Pretty good for <an internal tool / a web game / a side
+project>" is a FAIL.
+
+## What the reference does that this must match (adapted, not copied)
+
+<5–7 numbered qualities the reference exhibits that the subject must match in
+its own direction — e.g. legibility hierarchy, material confidence, motion
+everywhere/noise nowhere, typography as craft, celebration engineering.>
+
+## Automatic failures (any one = NOT YET)
+
+<Domain list — see references/domains.md for starter sets. Include
+art-direction/approach incoherence: "two pieces of evidence that read as
+different products.">
+
+## Scoring dimensions (report each: pass / fail + fix)
+
+<5–9 dimensions the critic reports individually, e.g. composition · craft of
+<domain surface> · coherence vs STYLE.md · typography/copy · color/token
+discipline · motion & feedback · celebration quality · legibility-at-a-glance.>
+
+## Verdict format (exact, for status.json)
+
+```json
+{
+  "verdict": "WOWED" | "NOT_YET",
+  "storefront_test": "<one sentence: which side wins and why>",
+  "defects": [ {"element": "...", "why_below_bar": "...", "fix": "...", "owner_area": "<area-key>"} ],
+  "dimensions": {"<dim>": "pass", "<dim>": "fail"}
+}
+```
+
+`owner_area` is required on every defect — cross-area defects route to the
+area that owns the file, not the area being critiqued.

package/sync-sources/skills/pan-gauntlet-loop/assets/STYLE.template.md

@@ -0,0 +1,41 @@
+# <PROJECT> Direction Bible — <BRANCH>
+
+One page. Every builder agent and every critic works from this. If a change
+doesn't serve this direction, it's wrong even if it's pretty.
+
+## The Direction (one sentence)
+
+<One sentence that commits to a direction — name the feeling AND the
+mechanics, e.g. "An illuminated manuscript come to life: stylized low-poly 3D
+world lit like golden hour, unexplored land literally unfinished parchment.">
+
+<One line on what it is never: "Never photoreal, never uncanny-middle, never
+flat-2D." / "Never clever-cute; the prose serves the reader's scan." etc.>
+
+## <Domain section 1 — e.g. World Rendering / Visual System / API Surface>
+
+<Concrete rules with values — hex codes, type scales, timing budgets, naming
+schemes, error shapes. Not adjectives: "painterly flat-shaded gradients, no
+PBR" not "beautiful materials".>
+
+## The Signature Elements (what makes it THIS, not generic)
+
+1. <Signature 1 — the thing a critic can point at in evidence and say
+   "that's <PROJECT>".>
+2. <Signature 2.>
+3. <Signature 3.>
+
+## <Palette / Tokens / Conventions>
+
+<Exact values: colors, fonts, spacing scale, motion durations, naming.>
+
+## <Domain section 2 — e.g. UI Chrome / CLI Output / Docs Voice>
+
+<Rules for the human-facing surface: feedback behavior, motion/easing,
+empty states, copy tone.>
+
+## Hard Bans
+
+<The short list of "any one of these = below the bar by definition": e.g.
+emoji as art · default fonts · unstyled native controls · dead-on-click
+surfaces · modal error dialogs · any element appearing with no transition.>

package/sync-sources/skills/pan-gauntlet-loop/assets/gauntlet-index.html

@@ -0,0 +1,237 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Gauntlet — Live Progress</title>
+<style>
+  :root {
+    --bg: #131417; --panel: #1c1e23; --ink: #e6e4dc; --dim: #8d8f98;
+    --line: #33363e; --gold: #c9a227; --glow: #6fc7bd; --red: #c25b4a;
+    --green: #6fae5c;
+  }
+  * { box-sizing: border-box; margin: 0; }
+  body {
+    background: var(--bg); color: var(--ink);
+    font: 15px/1.45 Georgia, 'Times New Roman', serif;
+    padding: 28px clamp(16px, 4vw, 48px);
+  }
+  header { display: flex; align-items: baseline; gap: 16px; flex-wrap: wrap; margin-bottom: 6px; }
+  h1 { font-size: 26px; letter-spacing: 0.06em; font-variant: small-caps; }
+  h1 .accent { color: var(--gold); }
+  #meta { color: var(--dim); font-size: 13px; }
+  #tagline { color: var(--dim); font-style: italic; margin-bottom: 22px; font-size: 13px; }
+  .grid {
+    display: grid; gap: 18px;
+    grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
+  }
+  .card {
+    background: var(--panel); border: 1px solid var(--line); border-radius: 8px;
+    overflow: hidden; display: flex; flex-direction: column;
+  }
+  .shot {
+    aspect-ratio: 16/9; background: #0c0d10; display: flex;
+    align-items: center; justify-content: center; overflow: hidden; position: relative;
+  }
+  .shot img { width: 100%; height: 100%; object-fit: cover; display: block; }
+  .shot .none { color: #45484f; font-size: 13px; letter-spacing: 0.08em; }
+  .body { padding: 12px 14px 14px; display: flex; flex-direction: column; gap: 8px; flex: 1; }
+  .titlerow { display: flex; justify-content: space-between; align-items: center; gap: 8px; }
+  .title { font-size: 16px; font-variant: small-caps; letter-spacing: 0.04em; }
+  .badge {
+    font: 700 11px/1 system-ui, sans-serif; letter-spacing: 0.08em;
+    padding: 4px 9px; border-radius: 3px; white-space: nowrap;
+  }
+  .b-notstarted { color: var(--dim); border: 1px solid var(--line); }
+  .b-inprogress { color: #0c0d10; background: var(--gold); }
+  .b-critique   { color: #0c0d10; background: var(--glow); }
+  .b-wowed      { color: #0c0d10; background: var(--green); }
+  .b-notyet     { color: #fff; background: var(--red); }
+  .b-delivered  { color: #0c0d10; background: var(--glow); }
+  .note { color: var(--dim); font-size: 13px; }
+  .defects { list-style: none; display: flex; flex-direction: column; gap: 4px; }
+  .defects li {
+    font-size: 12.5px; color: var(--ink); padding-left: 14px; position: relative;
+  }
+  .defects li::before { content: '✕'; color: var(--red); position: absolute; left: 0; font-size: 10px; top: 2px; }
+  .foot { margin-top: auto; display: flex; justify-content: space-between; color: var(--dim); font-size: 12px; }
+  #err { color: var(--red); margin-top: 20px; display: none; }
+  #media-section { margin-top: 30px; }
+  #media-section h2 {
+    font-size: 18px; font-variant: small-caps; letter-spacing: 0.06em;
+    margin-bottom: 10px; color: var(--gold);
+  }
+  .tracks { display: flex; flex-direction: column; gap: 6px; max-width: 720px; }
+  .track {
+    display: flex; align-items: center; gap: 12px;
+    background: var(--panel); border: 1px solid var(--line); border-radius: 6px;
+    padding: 8px 12px;
+  }
+  .play {
+    width: 34px; height: 34px; border-radius: 50%; border: 1px solid var(--gold);
+    background: none; color: var(--gold); font-size: 13px; cursor: pointer;
+    display: flex; align-items: center; justify-content: center; flex: none;
+  }
+  .play:hover, .play.playing { background: var(--gold); color: #0c0d10; }
+  .t-title { font-size: 14.5px; }
+  .t-meta { color: var(--dim); font-size: 12px; }
+  .t-kind {
+    font: 700 10px/1 system-ui, sans-serif; letter-spacing: 0.08em;
+    padding: 3px 7px; border-radius: 3px; border: 1px solid var(--line);
+    color: var(--dim); flex: none;
+  }
+  .t-right { margin-left: auto; color: var(--dim); font-size: 12px; flex: none; }
+</style>
+</head>
+<body>
+<header>
+  <h1>The <span class="accent">Gauntlet</span> — <span id="project">loading…</span></h1>
+  <span id="meta"></span>
+</header>
+<p id="tagline"></p>
+<div class="grid" id="grid"></div>
+<section id="media-section" style="display:none">
+  <h2>Generated Media</h2>
+  <div class="tracks" id="tracks"></div>
+</section>
+<p id="err"></p>
+<audio id="player"></audio>
+<script>
+// Live gauntlet progress page. Renders entirely from status.json (+ optional
+// media-manifest.json); copied verbatim into each project's gauntlet/ dir.
+const badge = (a) => {
+  if (a.verdict === 'WOWED')  return ['b-wowed', 'WOWED'];
+  if (a.verdict === 'NOT_YET') return ['b-notyet', 'NOT YET · iter ' + a.iteration];
+  if (a.status === 'IN PROGRESS' || /ITER \d+ IN PROGRESS/.test(a.status || '')) return ['b-inprogress', a.status];
+  if (a.status === 'AWAITING CRITIQUE') return ['b-critique', 'AWAITING CRITIQUE'];
+  if ((a.status || '').match(/DELIVERED|SHIPPED|WIRED/)) return ['b-delivered', a.status];
+  return ['b-notstarted', a.status || 'NOT STARTED'];
+};
+
+// Per-area card registry: create once, then mutate in place — no flashing.
+const cards = {}; // key -> {el, img, lastUpdated}
+
+function ensureCard(key) {
+  if (cards[key]) return cards[key];
+  const el = document.createElement('div');
+  el.className = 'card';
+  el.innerHTML =
+    '<div class="shot"><span class="none">NO CAPTURE YET</span></div>' +
+    '<div class="body">' +
+      '<div class="titlerow"><span class="title"></span><span class="badge"></span></div>' +
+      '<div class="note"></div>' +
+      '<ul class="defects"></ul>' +
+      '<div class="foot"><span class="f-iter"></span><span class="f-time"></span></div>' +
+    '</div>';
+  document.getElementById('grid').appendChild(el);
+  cards[key] = { el, img: null, lastUpdated: null };
+  return cards[key];
+}
+
+function setText(el, sel, text) {
+  const n = el.querySelector(sel);
+  if (n.textContent !== text) n.textContent = text;
+}
+
+function updateCard(key, a) {
+  const c = ensureCard(key);
+  const [cls, label] = badge(a);
+  setText(c.el, '.title', a.title || key);
+  const b = c.el.querySelector('.badge');
+  if (b.className !== 'badge ' + cls) b.className = 'badge ' + cls;
+  if (b.textContent !== label) b.textContent = label;
+  setText(c.el, '.note', a.note || '');
+  const defects = (a.defects || []).slice(0, 5).map(d =>
+    typeof d === 'string' ? d : (d.element + ' — ' + d.fix));
+  const ul = c.el.querySelector('.defects');
+  const want = defects.map(d => '<li>' + d + '</li>').join('');
+  if (ul.innerHTML !== want) ul.innerHTML = want;
+  setText(c.el, '.f-iter', 'iteration ' + (a.iteration || 0));
+  setText(c.el, '.f-time', a.updated ? new Date(a.updated).toLocaleTimeString() : '');
+
+  // Screenshot: reload only when the area's timestamp changes (or first pass).
+  if (c.lastUpdated !== a.updated || !c.img) {
+    const probe = new Image();
+    probe.onload = () => {
+      const holder = c.el.querySelector('.shot');
+      if (!c.img) { holder.innerHTML = ''; c.img = probe; holder.appendChild(probe); }
+      else c.img.src = probe.src; // swap after load — old frame stays until ready
+    };
+    probe.onerror = () => { c.lastUpdated = a.updated; }; // no shot yet; stop retrying this stamp
+    probe.src = 'shots/' + key + '.png?t=' + Date.now();
+    c.lastUpdated = a.updated;
+  }
+}
+
+async function refresh() {
+  try {
+    const r = await fetch('status.json?t=' + Date.now());
+    const s = await r.json();
+    if (s.project) document.getElementById('project').textContent = s.project;
+    if (s.tagline) document.getElementById('tagline').textContent = s.tagline;
+    document.getElementById('meta').textContent =
+      (s.pass || '') + ' · updated ' + new Date(s.updated).toLocaleTimeString();
+    for (const [key, a] of Object.entries(s.areas || {})) updateCard(key, a);
+    document.getElementById('err').style.display = 'none';
+  } catch (e) {
+    const el = document.getElementById('err');
+    el.textContent = 'status.json unreadable: ' + e.message;
+    el.style.display = 'block';
+  }
+}
+
+// Optional media list (audio/video generated during the pass) — built once
+// per manifest version, keyed by updated stamp.
+const player = document.getElementById('player');
+let currentFile = null;
+let mediaVersion = null;
+player.addEventListener('ended', () => { currentFile = null; markPlaying(); });
+player.addEventListener('pause', markPlaying);
+player.addEventListener('play', markPlaying);
+function markPlaying() {
+  document.querySelectorAll('.play').forEach(b => {
+    const active = b.dataset.file === currentFile && !player.paused;
+    b.classList.toggle('playing', active);
+    b.textContent = active ? '❚❚' : '▶';
+  });
+}
+function togglePlay(file) {
+  if (currentFile === file && !player.paused) { player.pause(); }
+  else {
+    if (currentFile !== file) { player.src = file; currentFile = file; }
+    player.play();
+  }
+  markPlaying();
+}
+async function refreshMedia() {
+  try {
+    const r = await fetch('media-manifest.json?t=' + Date.now());
+    if (!r.ok) return;
+    const m = await r.json();
+    if (!m.tracks || !m.tracks.length || m.updated === mediaVersion) return;
+    mediaVersion = m.updated;
+    document.getElementById('media-section').style.display = 'block';
+    const list = document.getElementById('tracks');
+    list.innerHTML = '';
+    for (const t of m.tracks) {
+      const row = document.createElement('div');
+      row.className = 'track';
+      row.innerHTML =
+        '<button class="play" data-file="' + t.file + '">▶</button>' +
+        '<div><div class="t-title">' + t.title + '</div>' +
+        '<div class="t-meta">' + (t.placement || '') + '</div></div>' +
+        '<span class="t-kind">' + (t.kind || '').toUpperCase() + '</span>' +
+        '<span class="t-right">' + (t.duration || '') + '</span>';
+      row.querySelector('.play').addEventListener('click', () => togglePlay(t.file));
+      list.appendChild(row);
+    }
+    markPlaying();
+  } catch (e) { /* manifest optional */ }
+}
+refresh();
+refreshMedia();
+setInterval(refresh, 5000);
+setInterval(refreshMedia, 15000);
+</script>
+</body>
+</html>

package/sync-sources/skills/pan-gauntlet-loop/references/domains.md

@@ -0,0 +1,106 @@
+# Gauntlet domains — evidence, areas, automatic failures
+
+Pick the row matching THING, adapt freely. The point of this file: every
+domain has a CHECK (how the critic inspects the work), a starter area split,
+an automatic-failure list, and a storefront-test phrasing. Non-visual domains
+replace "screenshot" with the domain's capturable evidence.
+
+## Game / rich visual UI
+
+- **CHECK:** Playwright screenshots at 1920×1080 across the key states
+  (spawn, mid-action, celebration, error), on an account with realistic data.
+- **Areas:** world/rendering · game-feel animation · UI system & motion ·
+  onboarding · presentation of the core loop · sound design · music ·
+  performance.
+- **Auto-fails:** emoji as art · default/system fonts · unstyled native
+  controls · flat untextured surfaces with no lighting response · dead-on-
+  click surfaces · error-after-the-fact UX (offer then reject) · uncanny-
+  middle photorealism · two shots that read as different games.
+- **Storefront test:** "If this appeared on the same store page as the
+  reference, would a player believe it is a shipped, commercially published
+  game?"
+
+## Web app / product UI
+
+- **CHECK:** Playwright screenshots at 1920×1080 + mobile width, across real
+  user flows (empty state, populated, error, loading, success).
+- **Areas:** design system & tokens · core flow A · core flow B · empty/error/
+  loading states · motion & micro-interactions · accessibility · performance.
+- **Auto-fails:** default browser styling anywhere · unstyled focus rings ·
+  layout shift on load · dead-end states with no next action · stock toasts
+  for moments that deserve staging · inconsistent spacing rhythm.
+- **Storefront test:** "Next to the reference's marketing screenshots, would
+  a buyer believe this is the same tier of product?"
+
+## CLI / developer tool
+
+- **CHECK:** Captured terminal sessions (real invocations, real output,
+  success + error + `--help`), asciinema or scripted transcript + screenshot.
+- **Areas:** command surface & help text · output design (color, tables,
+  spinners) · error messages & recovery hints · exit codes & pipe behavior ·
+  docs/README · performance (startup, large input).
+- **Auto-fails:** stack traces leaked to users · wall-of-text help · no
+  `--help` for any verb · colors that break on light terminals · silent
+  failure (exit 0, nothing happened) · inconsistent flag naming.
+- **Storefront test:** "Shown both tools' real transcripts, would a developer
+  pick this one as the professionally maintained tool?"
+
+## API / backend service
+
+- **CHECK:** Real request/response transcripts (curl -v or HTTPie), OpenAPI
+  render, error catalog exercised live, latency numbers under stated load.
+- **Areas:** resource model & naming · error design · docs & examples ·
+  authn/authz behavior · observability · performance & limits.
+- **Auto-fails:** inconsistent naming across resources · 500s for user error
+  · errors without actionable messages · undocumented behavior the client
+  must guess · missing pagination on list endpoints.
+- **Storefront test:** "Given both APIs' docs and live responses, would an
+  integrating engineer call this one a commercial-grade API?"
+
+## Library / SDK
+
+- **CHECK:** A consumer test app's real usage, rendered API docs, README
+  quickstart timed end-to-end, type/error behavior at the boundaries.
+- **Areas:** API surface & naming · docs & quickstart · error taxonomy ·
+  types & ergonomics · test coverage of the contract · bundle/perf cost.
+- **Auto-fails:** quickstart that doesn't run as written · leaked internal
+  types · error classes users can't catch selectively · breaking the stated
+  semver contract.
+- **Storefront test:** "Would an engineer skimming both READMEs believe this
+  one is the safe dependency to bet on?"
+
+## Performance pass
+
+- **CHECK:** Benchmark output (cold + warm, p50/p95/p99), flamegraphs,
+  before/after on the same machine, under stated load. Numbers, not vibes.
+- **Areas:** the hot path · memory footprint · startup · I/O & caching ·
+  regression guard (the benchmark becomes CI).
+- **Auto-fails:** benchmark that doesn't isolate the change · claimed wins
+  without reproducible numbers · a win on one path that regresses another
+  unmeasured · micro-benchmarks that don't reflect real load.
+- **Storefront test:** "Presented with both benchmark suites, would an
+  engineer believe this result and reproduce it?"
+
+## Writing / docs / content
+
+- **CHECK:** The rendered pieces side by side with the reference's, read by
+  the critic with labels stripped; timed comprehension check ("which one do
+  you understand faster?").
+- **Areas:** structure & information architecture · voice & register ·
+  examples & code samples · visuals/diagrams · navigation & discoverability.
+- **Auto-fails:** jargon the target reader can't define · examples that
+  don't run · a wall of text where a table/diagram carries the point ·
+  inconsistent terminology for the same concept.
+- **Storefront test:** "Stripped of branding, which piece would the target
+  reader finish and act on?"
+
+## Asset-heavy passes (audio, video, 3D, images)
+
+- **CHECK:** The generated assets played/viewed in situ (wired into the
+  product), plus a media-manifest.json so the progress page can play them.
+- **Rules worth restating** (from run #1): generation prompts must describe
+  audible/visible results, not mood adjectives ("soft/tiny" yields near-
+  silence — put gentleness in the engine's gain, not the prompt); strip
+  leading silence before trimming to a duration budget; never hard-trim a
+  musical phrase; peak-normalize audio to −3 dBFS; verify the license clause
+  of every purchased/stock asset for the distribution form.

package/sync-sources/skills/pan-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pan-handoff
-description: "pan handoff <conv> — agent-authored conversation handoff that spawns a new conversation. The focus text MUST be ≤500 characters or the fork is rejected."
+description: "pan handoff <conv> — agent-authored conversation handoff that spawns a new conversation. Keep the focus short and steering; the hard cap is 10000 characters (PAN-3737). Pass --title to name the successor."
 triggers:
   - pan handoff
   - hand off conversation
@@ -24,7 +24,14 @@ pan handoff [conv] [focus text...]
 
 The trailing text after the conversation reference becomes the focus — no flag required.
 
-> ⚠️ **The focus MUST be ≤ 500 characters.** A longer focus is rejected outright with `Fork request rejected: focus must be 500 characters or fewer` and **no conversation is created** — so count it and keep it under 500 on the first try. Keep the focus short and steering; do NOT pack backstory/context into it — the author reads the full source transcript for that. This is the single most common handoff mistake.
+> Keep the focus short and steering; do NOT pack backstory/context into it — the author reads the full source transcript for that, and long briefs belong in a file the focus points at. The hard cap is 10,000 characters (multi-line is fine; PAN-3737) — a longer focus is rejected with `Fork request rejected: focus must be 10000 characters or fewer` and no conversation is created.
+
+## Where to run it, and where the successor lives
+
+Two separate directories are involved, and each has its own rule:
+
+- **Run the command from your project directory** (the directory your session was launched in). Do NOT `cd` into the `--cwd` target, a `/tmp` brief directory, or any other path first — `--cwd` is where the *successor* will live; you never need to stand there. Sandboxed harnesses (e.g. codex `workspace-write`) block network and non-workspace writes for commands run from untrusted directories. The failure signature is `attempt to write a readonly database` followed by `Could not reach the Overdeck dashboard at http://127.0.0.1:3011 … (fetch failed)` **while the dashboard is actually up** — if you see that pair, re-run from your project directory (PAN-3735).
+- **`--cwd` must be an absolute path to an existing directory under your home directory, inside a git working tree.** The server rejects violations and creates no conversation: `/tmp/...` fails the home-containment check (`Invalid cwd`), a relative path like `../worktree` fails the absolute-path check (the CLI does not resolve it for you), a not-yet-created directory fails the existence check, and a plain non-git directory fails with `Handoff cwd is not inside a git repository`. The reliable recipe is an isolated worktree: `git -C <repo> worktree add -b hoff/<slug> "$HOME/hoff-<slug>-wt" main`, put any brief files in it, then pass it as `--cwd`. In a polyrepo project whose parent directory is not itself a git repo, point `--cwd` at (a worktree of) the relevant sub-repo — the parent fails the git check.
 
 ## Handing off the conversation you are in (the common case)
 
@@ -61,17 +68,18 @@ pan handoff 42
 pan handoff source-conv continue the API wiring
 pan handoff source-conv --model claude-sonnet-4-6
 pan handoff source-conv --harness pi
-pan handoff source-conv --cwd /path/to/project
-pan handoff source-conv --cwd ../isolated-worktree --project mind-your-now
+pan handoff source-conv --cwd /home/you/Projects/project
+pan handoff source-conv --cwd /home/you/Projects/isolated-worktree --project mind-your-now
 pan handoff source-conv --model claude-opus-4-7 wire the Stripe webhook into checkout
 pan handoff source-conv --author external --author-model claude-haiku-4-5 cheap clean handoff
 pan handoff source-conv --author source uses-source-agent-and-pollutes-its-context
 pan handoff source-conv --issue PAN-1234 continue the API wiring
+pan handoff source-conv --title "Checkout webhook repair" continue the API wiring
 ```
 
 ## Project and issue association
 
-Use `--project <key-or-name>` when the successor runs from a `--cwd` outside the registered project's directory, such as an isolated worktree. The explicit project wins over the source association; without the flag, the successor inherits the source conversation's project. Unknown projects reject the request and create no conversation.
+Use `--project <key-or-name>` when the successor runs from a `--cwd` outside the registered project's directory, such as an isolated worktree. The `--cwd` value must be an absolute path to an existing directory under your home directory (see "Where to run it, and where the successor lives" above). The explicit project wins over the source association; without the flag, the successor inherits the source conversation's project. Unknown projects reject the request and create no conversation.
 
 Use `--issue <id>` to attach the new conversation to a specific issue (e.g. `PAN-1234`). The flag is validated; an invalid ID rejects the request and creates no conversation. When `--issue` is omitted, the new conversation inherits the source conversation's issue association, if any.
 
@@ -87,7 +95,17 @@ Use a normal summary fork when a quick passive summary is enough. Use a plain fo
 
 The positional text after `<conv>` is the focus — a short statement of what the successor should concentrate on. Quotes are optional; everything after the conversation reference (excluding flags) is joined with spaces. Keep it short and task-oriented; the focus is injected into the handoff-authoring prompt, not used as the new conversation's user request.
 
-**Hard limit: the focus must be ≤ 500 characters.** A longer focus is rejected outright with `Fork request rejected: focus must be 500 characters or fewer` and no conversation is created — so write it under 500 chars on the first try. Don't pack the backstory into the focus; the detail belongs in the transcript the author reads. The focus only steers what the author emphasizes.
+**Hard ceiling: 10,000 characters** (PAN-3737; multi-line focus is allowed). Don't pack the backstory into the focus even so; the detail belongs in the transcript the author reads or in a brief file in the successor cwd. The focus only steers what the author emphasizes.
+
+## Title
+
+Without `--title`, the new conversation is titled `Handoff: <first ~70 chars of focus>` (or `Handoff: <source title>` when there is no focus). Pass `--title "<title>"` to name it explicitly — useful when the focus is a file pointer like "Read .pan/handoff-brief.md FIRST" and would otherwise become the title verbatim:
+
+```bash
+pan handoff self --title "Checkout webhook repair" Read .pan/handoff-brief.md FIRST and follow it exactly.
+```
+
+A blank `--title` falls back to the default naming above.
 
 ## Authoring modes
 

package/sync-sources/skills/pan-help/SKILL.md

@@ -126,7 +126,7 @@ Overdeck comes with a suite of skills to guide AI assistants:
 
 ### Utilities
 - `/session-health` - Detect and clean up stuck sessions
-- `/skill-creator` - Guide for creating new skills
+- `/claude-skill-creator` - Guide for creating Claude Code skills
 - `/web-design-guidelines` - UI/UX best practices
 - `/work-complete` - Checklist for completing work
 

package/sync-sources/skills/pan-peer-review/SKILL.md

@@ -62,9 +62,9 @@ never raise it to `xhigh`/`max` for a review.
 
 ### 1. Write the brief to a file — never into the focus
 
-The `pan handoff` focus is hard-capped at 500 characters. A real review brief is
-thousands. Write it to a file in the reviewer's future cwd and let the focus
-point at it.
+The `pan handoff` focus is for steering, not content (hard ceiling 10,000 chars
+since PAN-3737). A real review brief is thousands of characters of structure —
+write it to a file in the reviewer's future cwd and let the focus point at it.
 
 A brief that produces a useful review has these parts:
 

package/sync-sources/skills/pan-restart/SKILL.md

@@ -31,11 +31,14 @@ pan restart
 # Scoped alternatives
 pan restart --cliproxy
 pan restart --traefik
-pan restart --full       # nuclear — stops & restarts everything
+# --full is nuclear — stops & restarts everything
+pan restart --full
 
 # Explicit force cases
-pan restart --force              # explicit operator bypass of the deploy-window gate
-pan restart --cliproxy --force   # redownload the pinned CLIProxy binary
+# --force is an explicit operator bypass of the deploy-window gate
+pan restart --force
+# --cliproxy --force redownloads the pinned CLIProxy binary
+pan restart --cliproxy --force
 ```
 
 Each stage is health-gated: the command waits for `GET /api/health` from the