npm - @overdeck/desktop - Versions diffs - 0.49.1 → 0.49.2 - Mend

@overdeck/desktop 0.49.1 → 0.49.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (497) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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-gauntlet-loop/references/lessons.md ADDED Viewed

@@ -0,0 +1,60 @@
+# Gauntlet run-#1 lessons — operational addenda
+Generalized from the first full gauntlet (Lexerra, 2026-08-11). Every line
+exists because its absence cost an iteration. Fold the applicable lines into
+the mission prompt and the per-agent prompts verbatim.
+1. **File-ownership map, enforced in every agent prompt.** Concurrent agents
+   in one worktree WILL clobber shared files. Each area owns exact paths;
+   areas sharing files serialize in one wave, never run in parallel. Agents
+   never commit; the orchestrator reviews and commits per area with
+   path-scoped `git add` — `git add -A` would scoop another in-flight agent's
+   half-done work.
+2. **Evidence at presentation quality.** Screenshots at 1920×1080 — run #1's
+   1440×900 captures failed the critic on storefront parity alone. Capture
+   with realistic data (an in-fiction account name, real content — a test
+   username like `map3d_48100411` visible in the shot is a defect). Keep dev
+   tooling panels out of captures.
+3. **Headless rendering gotchas.** Black frames in headless Chromium are a
+   renderer-context issue, not scene code — try default launch flags before
+   forcing software rasterization flags. React StrictMode double-mounts:
+   canvas/WebGL code must survive a fresh mount. Software-rasterized FPS
+   numbers in headless are CPU rasterization — never treat them as the real
+   60fps verdict.
+4. **Seedable state is load-bearing for critique.** If reaching a state takes
+   hours of wall-clock (filled stockpiles, advanced time, specific data), the
+   loop can't be photographed. Add the test hook / seed path during setup,
+   not mid-loop. Never restart a shared dev server mid-run — hot-reload kills
+   other agents' verification sessions.
+5. **Critic protocol.** The critic is ALWAYS a separate agent from the
+   builder, frontier-tier, sees evidence + refs only (no code access needed).
+   It tags each defect with the owning area so cross-area defects merge into
+   the right queue (run #1's map critic found 5 UI defects). Verdict JSON
+   goes to `gauntlet/notes/critique-<area>-iter<n>.json` and onto the
+   dashboard card verbatim.
+6. **Dashboard contract.** Update `status.json` at EVERY transition (agent
+   launched / landed / awaiting critique / verdict), not just after
+   critiques. The page mutates cards in place — a full-DOM rebuild per poll
+   makes screenshots flash. Regenerated media needs cache-busting or browsers
+   replay stale files.
+7. **Test reconciliation is its own queued item.** Big visual/structural
+   changes break existing test selectors; don't let the builder burn its run
+   fixing them. Wave gates are: build passes, evidence captured, critique
+   filed. Broken-suite repair gets its own area or a follow-up.
+8. **Cadence artifacts.** Commit critique JSONs and status.json to the branch
+   — the pass history is reviewable. Gitignore large third-party reference
+   media and regenerable source assets (keep shipped assets committed).
+## The four ways the loop silently fails
+These are from the pattern's origin notes and every writeup since — restate
+them because they are the whole game:
+1. **Vague bar** → the critic invents a comparison and approves everything.
+   The bar must be named, fetchable, comparable.
+2. **Builder judging its own work** → the critic must be a fresh agent with
+   zero knowledge of the builder's effort or reasoning trail.
+3. **Soft critic** → scores out of 10 drift upward and everything passes.
+   Binary verdict + concrete fixes only.
+4. **Fixed round count** → "do 3 iterations" ships a prototype. The exit
+   condition is WOWED, or the operator stopping the run.

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

@@ -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)."
 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,8 +68,8 @@ 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
@@ -71,7 +78,7 @@ pan handoff source-conv --issue PAN-1234 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 +94,7 @@ 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, and its first ~70 characters become the new conversation's title.
 ## Authoring modes

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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

package/sync-sources/skills/pan-start/SKILL.md CHANGED Viewed

@@ -48,6 +48,7 @@ state it is in to running work.
   from the existing xBRIEF and xBRIEF tasks.
 - **Already running** — `pan start` exits 0 with a no-op message naming `pan tell <id>` for
   messaging and the tmux attach command.
+- **Swarm active** — the bare parent agent is the foreman. `pan start` attaches to or restores that foreman instead of refusing because slot agents exist; it never creates a competing serial parent.
 Planning depth is controlled by `--plan`:
@@ -65,6 +66,8 @@ Start-time policy flags are persisted on the issue before planning or work begin
 sets the durable work-model override used by later respawns, `--swarm` accepts `off`, `auto`,
 or `always`, `--review-mode` accepts `quick`, `full`, or `none`, and `--review-model` pins the
 model used by the review convoy. Omitted flags leave existing and inherited policy untouched.
+Swarm mode controls automatic foreman creation, not Deacon slot dispatch. `off` keeps serial work,
+while `auto` and `always` allow a readiness-eligible foreman loop.
 When this start also kicks off planning (no plan exists yet), `--plan-model <model>` overrides
 the planning agent's model for that session only — it is a one-shot override, not persisted
 policy, and it never changes the work agent's model (`--model`).