pan-wizard 3.36.0 → 3.37.0

package/docs/branding/README-brand-draft.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+<!-- Replace with the generated banner (Nano Banana prompt #1) or a 2x screenshot
+     of the README hero card in PanWizard Brand.dc.html -->
+<img src="assets/pan-readme-hero.png" alt="PanWizard — Context engineering that makes AI coding reliable" width="820" />
+
+# PanWizard
+
+**Project Automation Navigator** — a lightweight workflow-automation and
+context-engineering system for Claude Code, OpenCode, Gemini CLI, Codex and
+Copilot CLI.
+
+*Solves context rot — the quality degradation that happens as the model fills its
+context window.*
+
+[![npm version](https://img.shields.io/npm/v/pan-wizard?style=for-the-badge&color=FF5A3C&labelColor=211E18)](https://www.npmjs.com/package/pan-wizard)
+[![downloads](https://img.shields.io/npm/dm/pan-wizard?style=for-the-badge&color=5B4BE6&labelColor=211E18)](https://www.npmjs.com/package/pan-wizard)
+[![license](https://img.shields.io/badge/license-MIT-1E8E5A?style=for-the-badge&labelColor=211E18)](LICENSE)
+
+```bash
+npx pan-wizard@latest
+```
+
+**Works on Mac, Windows, and Linux.**
+
+</div>
+
+---
+
+## What is PanWizard?
+
+PanWizard is the context-engineering layer that makes AI coding assistants
+reliable. It breaks work into phases that fit inside the context window, hands
+each phase to a specialist agent with exactly the context it needs, and keeps
+durable state that survives every reset.
+
+The complexity lives in the system, not in your workflow. Behind the scenes:
+context engineering, XML prompt formatting, subagent orchestration, state
+management. What you see — a few commands that just work.
+
+```
+planner ──▶ executor ──▶ verifier      each in a fresh 200K context window
+   │            │            │
+   └────────────┴────────────┘
+              .planning/   ← persistent state: project.md · roadmap.md · state.md
+```
+
+## Why it works
+
+- **Thin commands.** A handful of `/pan:` commands orchestrate everything. You
+  describe; it builds.
+- **Specialist agents.** Planner, executor, verifier, researcher, debugger — each
+  spawned in a fresh 200K window so quality never degrades mid-task.
+- **Durable state.** Plans, roadmap and progress live in `.planning/` and survive
+  context resets, restarts and new sessions.
+- **Zero runtime dependencies.** Cross-platform CLI core. MIT licensed.
+
+## Bot army — `/pan:army`
+
+One phase is `/pan:exec-phase`. A whole goal is a **campaign**: a
+**Mission Control** agent (`pan-conductor`) — running on the model you launched
+with — plans the mission and delegates to specialist **squads** rather than
+implementing anything itself.
+
+| Tier | Squad | Role | Access |
+| --- | --- | --- | --- |
+| 0 | Mission Control | plan + delegate | delegation-first (instructed, not tool-enforced) |
+| 1 | Architecture | roadmap · plan · research | read-only · parallel |
+| 1 | Build | `pan-executor` | write · one worktree per agent |
+| 1 | Quality | review · harden · verify | adversarial · read-only |
+| 1 | Release | `pan-release` | always-ask · human gate |
+| 2 | Workers | document_code · distiller | narrow, high-volume |
+
+Six-phase loop: **Muster → Plan → Delegate → Execute → Review → Integrate → Learn** ↺
+
+- **Concurrency:** research parallel · builds parallel but isolated in per-agent
+  worktrees · integrate serial and human-gated.
+- **Safety harness:** nesting depth 2 · spawn + budget caps · abort kill-switch ·
+  protected main · revert never rewrite.
+- **Scheduled campaigns:** arm a self-resuming run with a per-day budget — a human
+  still approves every merge.
+
+```bash
+/pan:army "ship the v1 reporting module" --source backlog --max-cycles 5
+/pan:army --status        # campaign progress
+/pan:army --stop          # graceful halt, state preserved
+```
+
+## Quick start
+
+```bash
+npx pan-wizard@latest          # choose runtime + global/local
+/pan:new-project               # questions → research → requirements → roadmap
+/pan:plan-phase 1              # research → atomic plans → verify
+/pan:exec-phase 1              # planner → executor → verifier
+/pan:hud                       # context budget · progress · cost
+```
+
+## Brand
+
+| Token | Hex | Use |
+| --- | --- | --- |
+| Ember | `#FF5A3C` | Primary / CTAs |
+| Conduit | `#5B4BE6` | Links, agent connectors |
+| Verify | `#1E8E5A` | Success / verified |
+| Butter | `#FFCE4A` | Highlights |
+| Ink | `#211E18` | Dark surfaces, terminals |
+| Paper | `#F3ECDD` | Light surfaces |
+
+Type: **Gabarito** (display) + **JetBrains Mono** (code & labels).
+Logo: node-graph mark (coral → butter + green, indigo links) + `PanWizard` wordmark.
+
+> Banner, avatar and illustration art: generate with `nano-banana-prompts.txt`.
+
+---
+
+<div align="center">
+<sub>PanWizard · Project Automation Navigator · MIT</sub>
+</div>

package/docs/branding/handoff/IMPLEMENTATION.md

@@ -0,0 +1,205 @@
+# PanWizard Rebrand — Implementation Guide (Claude Code)
+
+This ports the new brand system into the **PanWizard repo**. Each step below is a
+copy-paste prompt for Claude Code, run from the repo root. Do them in order; each is
+self-contained and safe to commit on its own.
+
+> Design source of truth lives in this design project:
+> `PanWizard Brand.dc.html` · `PanWizard UI Kit.dc.html` · `PanWizard HUD.dc.html`
+> Generated art + SVGs are in `assets/`. Drop those files into the repo's `assets/`
+> before running Step 2.
+
+---
+
+## Brand tokens (reference — paste into any prompt if drift appears)
+
+| Token | Hex | Role |
+| --- | --- | --- |
+| Ember | `#FF5A3C` | Primary / brand / active |
+| Conduit | `#5B4BE6` | Links, agent connectors, focus |
+| Verify | `#1E8E5A` | Success / done / healthy |
+| Butter | `#FFCE4A` | Pending / highlights |
+| Ink | `#211E18` | Text, dark surfaces |
+| Paper | `#F3ECDD` | Cards / light surfaces |
+| Sand | `#E7DBC2` | Canvas / page background |
+
+Type: **Gabarito** (display) + **JetBrains Mono** (code/labels).
+Logo: node-graph mark — coral parent → indigo links → butter + green children.
+
+---
+
+## Step 1 — Drop in the new assets
+
+Copy these files from the design project's `assets/` into the repo's `assets/`:
+
+- `pan-mark.svg` — primary node-graph mark (transparent)
+- `pan-logo-lockup.svg` — mark + wordmark on ink
+- `pan-hero.png` — README / npm hero banner (1024²)
+- `pan-avatar.png` — npm / CLI / favicon icon (rounded square)
+- `pan-orchestration.png` — orchestration illustration
+- `pan-docs-header.png` — soft docs-header background
+
+```
+Update assets/pan-logo-2000.svg and assets/pan-logo-2000-transparent.svg to the new
+PanWizard mark: a node-graph glyph — a coral (#FF5A3C) parent node at top, two indigo
+(#5B4BE6) connector lines fanning down to a butter (#FFCE4A) node on the lower-left and
+a green (#1E8E5A) node on the lower-right — beside a bold rounded-sans wordmark
+"PanWizard" ("Pan" in #FF5A3C, "Wizard" in #FBF7EE on dark / #211E18 on light). Use
+assets/pan-logo-lockup.svg as the reference. Keep the same viewBox/dimensions the old
+files used so every <img> reference still renders.
+```
+
+---
+
+## Step 2 — README hero + brand
+
+```
+Replace the README.md header so the hero image is assets/pan-hero.png (the new banner).
+Apply the PanWizard brand: keep the centered layout, swap the npm/license badge colors
+to brand hex (version #FF5A3C, downloads #5B4BE6, license #1E8E5A, all labelColor
+#211E18), and add a short "Brand" section near the bottom with the token table and the
+note that banner/avatar/illustration art is generated from image-prompts.md. Use the
+content of README-brand-draft.md from the design project as the source — do not change
+any factual/usage copy, commands, or install instructions.
+```
+
+---
+
+## Step 3 — Re-theme the HUD (light, on-brand)
+
+File: `pan-wizard-core/bin/lib/hud.cjs`.
+
+```
+In pan-wizard-core/bin/lib/hud.cjs, re-theme the HUD from the current dark palette to
+the light PanWizard brand. Make ONLY visual changes — do not touch collectHudData(),
+the render*() data wiring, or any data shape/test.
+
+1. Replace the :root block at the top of HUD_CSS with:
+
+:root{
+  --bg:#E7DBC2;--panel:#FBF7EE;--panel2:#F3ECDD;--border:#E4D8C0;
+  --text:#211E18;--text2:#5C5446;--muted:#9A9180;
+  --coral:#FF5A3C;--amber:#C9A227;--cyan:#5B4BE6;--green:#1E8E5A;
+  --violet:#5B4BE6;--red:#D2431F;
+  --font:"Gabarito","Segoe UI",system-ui,sans-serif;
+  --mono:"JetBrains Mono","SFMono-Regular",Consolas,monospace;
+}
+
+2. Replace the .pill.* rules with light-theme equivalents:
+
+.pill.ok{background:#E4F3EB;color:#1E8E5A;}
+.pill.info{background:#E9E6FB;color:#5B4BE6;}
+.pill.warn{background:#FFF3D4;color:#9A7A12;}
+.pill.danger{background:#FBE2DB;color:#D2431F;}
+.pill.muted{background:#EDE8DC;color:#8C8475;}
+
+3. Add a subtle card lift: on .panel and .metric add
+   box-shadow:0 1px 3px rgba(33,30,24,0.05);
+4. In the TIER_COLOR map, change reasoning to 'var(--coral)' so Mission Control /
+   reasoning agents read coral instead of amber.
+5. Bump the header: in renderMission, render the node-graph mark (inline SVG from
+   assets/pan-mark.svg) to the left of the project title.
+
+Keep all class names, structure, and the self-contained (no-network) output intact.
+Run `node pan-wizard-core/bin/lib/... hud --stdout` mentally / `npm test` to confirm
+renderHud still produces the same sections.
+```
+
+---
+
+## Step 4 — Add the "Now building" panel (what + where)
+
+This is the new panel that answers *what is it building* and *where in the project*.
+
+```
+In pan-wizard-core/bin/lib/hud.cjs, add a new "Now building" panel that renders BETWEEN
+the mission panel and the command stack. It must show (a) WHERE — a horizontal phase
+stepper across all roadmap phases with the current phase highlighted — and (b) WHAT —
+the current phase name, the pan pipeline stage (research → plan → execute → verify),
+and the in-flight build tasks (one row per active army worktree with a progress bar).
+
+Use only data already on the object returned by collectHudData():
+  d.roadmap            // [{number,name,status,plans,summaries}]
+  d.state.current_phase, d.state.current_phase_name
+  d.worktrees          // [{branch,worktree}]
+  d.progress           // {percent,completed,total,...}
+
+Add this helper + renderer (mirror the existing esc()/pill()/bar() style):
+
+function pipelineStage(p){
+  if(!p) return 'queued';
+  if(p.status==='complete') return 'verify';
+  if(p.status==='partial')  return 'execute';
+  if(p.status==='researched') return 'plan';
+  if(p.status==='discussed')  return 'research';
+  return 'queued';
+}
+
+function renderNowBuilding(d){
+  if(!d.roadmap.length) return '';
+  const curNum = d.state.current_phase
+    || (d.roadmap.find(p=>p.status!=='complete')||{}).number;
+  const cur = d.roadmap.find(p=>String(p.number)===String(curNum)) || d.roadmap[0];
+  const stage = pipelineStage(cur);
+  const stages = ['research','plan','execute','verify'];
+
+  // WHERE — stepper
+  const steps = d.roadmap.map(p=>{
+    const done = p.status==='complete';
+    const active = String(p.number)===String(cur.number);
+    const cls = done?'ok':active?'now':'todo';
+    return `<div class="step ${cls}"><span class="sdot">${done?'✓':esc(p.number)}</span>`
+      + `<span class="slabel">${esc((p.name||'').split(' ')[0]||p.number)}</span></div>`;
+  }).join('<span class="sline"></span>');
+
+  // WHAT — pipeline + in-flight worktrees
+  const pipe = stages.map(s=>{
+    const i = stages.indexOf(s), ci = stages.indexOf(stage);
+    const k = i<ci?'done':i===ci?'on':'off';
+    return `<span class="pstep ${k}">${esc(s)}${i<ci?' ✓':i===ci?' ●':''}</span>`;
+  }).join('<span class="pgt">›</span>');
+
+  const tasks = d.worktrees.length
+    ? d.worktrees.map(t=>`<div class="task"><span class="tname">${esc(t.branch.replace(/^army\//,''))}</span>`
+        + `<span class="amono dim">${esc(t.worktree)}</span></div>`).join('')
+    : `<div class="task dim amono">${cur.plans||0} plan(s) · ${cur.summaries||0} done</div>`;
+
+  return `
+  <section class="panel nowbuilding">
+    <div class="ph">now building — phase ${esc(cur.number)} of ${esc(d.progress.total)}</div>
+    <div class="stepper">${steps}</div>
+    <div class="nbcard">
+      <div class="nbhead"><div class="nbtitle">Phase ${esc(cur.number)} — ${esc(cur.name||'')}</div>
+        <div class="pipeline">${pipe}</div></div>
+      <div class="tasks">${tasks}</div>
+    </div>
+  </section>`;
+}
+
+Wire it into renderHud()'s body array, right after renderMission(d). Add matching CSS to
+HUD_CSS using existing tokens (.stepper as a flex row; .step.now .sdot uses --coral with
+a soft ring; .step.ok .sdot uses --green; .pstep.on uses --coral). Then add
+'now-building' to the sections list in cmdHud() so the JSON result reports it.
+Add a unit test in tests/hud.test.cjs asserting renderHud output contains "now building"
+when a roadmap exists.
+```
+
+---
+
+## Step 5 — Verify
+
+```
+Run npm test and npm run test:scenarios. Then generate a sample HUD with
+`node bin/install.js` env or the pan-tools dispatcher: `pan-tools hud --out /tmp/hud.html`
+and open it to confirm the light theme + the "now building" panel render correctly with
+real project data. Fix any failing hud tests caused by the new section.
+```
+
+---
+
+## Notes
+- The HUD stays a single self-contained file — no external CSS/JS/fonts fetched. Gabarito
+  / JetBrains Mono are named with system fallbacks; if you want them embedded, base64 a
+  woff2 into an `@font-face` inside HUD_CSS (optional).
+- Nothing here changes planning/state semantics — the HUD remains a pure view.
+- Re-generate any new art with the prompts in `image-prompts.md`.

package/docs/branding/handoff/README-brand-draft.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+<!-- Replace with the generated banner (Nano Banana prompt #1) or a 2x screenshot
+     of the README hero card in PanWizard Brand.dc.html -->
+<img src="assets/pan-readme-hero.png" alt="PanWizard — Context engineering that makes AI coding reliable" width="820" />
+
+# PanWizard
+
+**Project Automation Navigator** — a lightweight workflow-automation and
+context-engineering system for Claude Code, OpenCode, Gemini CLI, Codex and
+Copilot CLI.
+
+*Solves context rot — the quality degradation that happens as the model fills its
+context window.*
+
+[![npm version](https://img.shields.io/npm/v/pan-wizard?style=for-the-badge&color=FF5A3C&labelColor=211E18)](https://www.npmjs.com/package/pan-wizard)
+[![downloads](https://img.shields.io/npm/dm/pan-wizard?style=for-the-badge&color=5B4BE6&labelColor=211E18)](https://www.npmjs.com/package/pan-wizard)
+[![license](https://img.shields.io/badge/license-MIT-1E8E5A?style=for-the-badge&labelColor=211E18)](LICENSE)
+
+```bash
+npx pan-wizard@latest
+```
+
+**Works on Mac, Windows, and Linux.**
+
+</div>
+
+---
+
+## What is PanWizard?
+
+PanWizard is the context-engineering layer that makes AI coding assistants
+reliable. It breaks work into phases that fit inside the context window, hands
+each phase to a specialist agent with exactly the context it needs, and keeps
+durable state that survives every reset.
+
+The complexity lives in the system, not in your workflow. Behind the scenes:
+context engineering, XML prompt formatting, subagent orchestration, state
+management. What you see — a few commands that just work.
+
+```
+planner ──▶ executor ──▶ verifier      each in a fresh 200K context window
+   │            │            │
+   └────────────┴────────────┘
+              .planning/   ← persistent state: project.md · roadmap.md · state.md
+```
+
+## Why it works
+
+- **Thin commands.** A handful of `/pan:` commands orchestrate everything. You
+  describe; it builds.
+- **Specialist agents.** Planner, executor, verifier, researcher, debugger — each
+  spawned in a fresh 200K window so quality never degrades mid-task.
+- **Durable state.** Plans, roadmap and progress live in `.planning/` and survive
+  context resets, restarts and new sessions.
+- **Zero runtime dependencies.** Cross-platform CLI core. MIT licensed.
+
+## Bot army — `/pan:army`
+
+One phase is `/pan:exec-phase`. A whole goal is a **campaign**: a
+**Mission Control** agent (`pan-conductor`) — running on the model you launched
+with — plans the mission and delegates to specialist **squads** rather than
+implementing anything itself.
+
+| Tier | Squad | Role | Access |
+| --- | --- | --- | --- |
+| 0 | Mission Control | plan + delegate | delegation-first (instructed, not tool-enforced) |
+| 1 | Architecture | roadmap · plan · research | read-only · parallel |
+| 1 | Build | `pan-executor` | write · one worktree per agent |
+| 1 | Quality | review · harden · verify | adversarial · read-only |
+| 1 | Release | `pan-release` | always-ask · human gate |
+| 2 | Workers | document_code · distiller | narrow, high-volume |
+
+Six-phase loop: **Muster → Plan → Delegate → Execute → Review → Integrate → Learn** ↺
+
+- **Concurrency:** research parallel · builds parallel but isolated in per-agent
+  worktrees · integrate serial and human-gated.
+- **Safety harness:** nesting depth 2 · spawn + budget caps · abort kill-switch ·
+  protected main · revert never rewrite.
+- **Scheduled campaigns:** arm a self-resuming run with a per-day budget — a human
+  still approves every merge.
+
+```bash
+/pan:army "ship the v1 reporting module" --source backlog --max-cycles 5
+/pan:army --status        # campaign progress
+/pan:army --stop          # graceful halt, state preserved
+```
+
+## Quick start
+
+```bash
+npx pan-wizard@latest          # choose runtime + global/local
+/pan:new-project               # questions → research → requirements → roadmap
+/pan:plan-phase 1              # research → atomic plans → verify
+/pan:exec-phase 1              # planner → executor → verifier
+/pan:hud                       # context budget · progress · cost
+```
+
+## Brand
+
+| Token | Hex | Use |
+| --- | --- | --- |
+| Ember | `#FF5A3C` | Primary / CTAs |
+| Conduit | `#5B4BE6` | Links, agent connectors |
+| Verify | `#1E8E5A` | Success / verified |
+| Butter | `#FFCE4A` | Highlights |
+| Ink | `#211E18` | Dark surfaces, terminals |
+| Paper | `#F3ECDD` | Light surfaces |
+
+Type: **Gabarito** (display) + **JetBrains Mono** (code & labels).
+Logo: node-graph mark (coral → butter + green, indigo links) + `PanWizard` wordmark.
+
+> Banner, avatar and illustration art: generate with `nano-banana-prompts.txt`.
+
+---
+
+<div align="center">
+<sub>PanWizard · Project Automation Navigator · MIT</sub>
+</div>

package/docs/branding/handoff/image-prompts.md

@@ -0,0 +1,46 @@
+# PanWizard — Image Prompts for Nano Banana (Gemini)
+
+Hand any of these to Nano Banana. Every prompt locks the brand palette so output stays on-system.
+
+## Brand constraints (paste with any prompt if drift appears)
+- **Palette only:** Ember coral `#FF5A3C` · Conduit indigo `#5B4BE6` · Verify green `#1E8E5A` · Butter yellow `#FFCE4A` · Ink `#211E18` · Paper cream `#F3ECDD` / `#FBF7EE`
+- **Logo motif:** a node-graph — one coral dot branching *down* to a butter dot and a green dot, joined by indigo connector lines (planner → executor → verifier)
+- **Type vibe:** bold rounded geometric sans (Gabarito) + JetBrains Mono
+- **Style:** flat vector, rounded corners (8 / 16 / 32px), soft shadows, soft grain, generous negative space
+- **Avoid:** neon, heavy gradients, 3D (unless asked), stock-photo people (unless asked), busy backgrounds
+
+---
+
+## 1 · GitHub social preview / npm hero — `1280 × 640`
+> Wide developer-brand banner on a deep charcoal-brown background `#211E18`. A clean geometric node-graph logo: one coral `#FF5A3C` dot branching down to a butter `#FFCE4A` dot and a green `#1E8E5A` dot, connected by indigo `#5B4BE6` lines. To its right, a bold rounded sans wordmark "PanWizard" with "Pan" in coral and "Wizard" in cream. Subhead: "Context engineering that makes AI coding reliable." A small cream pill reading `npx pan-wizard@latest` in monospace. Flat vector, soft grain, generous negative space, no photo, no 3D. Friendly, premium dev-tool aesthetic.
+
+## 2 · Hero illustration — orchestration
+> Isometric flat illustration of three friendly rounded robot agents labelled planner, executor and verifier, passing a small glowing token along a connected track. Warm cream `#F3ECDD` background. Strict palette: coral `#FF5A3C`, indigo `#5B4BE6`, green `#1E8E5A`, butter `#FFCE4A`, ink `#211E18`. Rounded shapes, 16–32px corner radii, soft shadows, no heavy gradients, no neon. Calm, approachable, editorial vector style with lots of breathing room.
+
+## 3 · App / CLI avatar — square `1024 × 1024`
+> Square app icon, rounded-square tile filled coral `#FF5A3C`, a centered minimal node-graph glyph in cream `#FBF7EE` (one dot branching to two dots with thin connector lines), subtle inner shadow, flat and crisp, no text. iOS-style icon grid with safe-area padding.
+
+## 4 · Docs section header — wide, soft background
+> Abstract soft background for documentation headers: a warm cream `#F3ECDD` field with a few large, out-of-focus rounded shapes in coral, indigo, green and butter drifting near the edges. Large empty center for a text overlay. Flat, gentle grain, no objects, no people.
+
+## 5 · Feature spot illustrations (set of 3, square)
+> Three matching minimal spot illustrations on cream `#F3ECDD`, one per feature, same line-weight and palette (`#FF5A3C` `#5B4BE6` `#1E8E5A` `#FFCE4A` `#211E18`):
+> 1. **Thin commands** — a terminal window with a single glowing prompt line.
+> 2. **Specialist agents** — three rounded robot heads connected by indigo lines.
+> 3. **Durable state** — a stack of document cards with a small save/checkpoint badge.
+> Flat vector, rounded corners, soft shadow, generous negative space, no text.
+
+## 6 · OG / Twitter card — `1200 × 630`
+> Social share card, ink `#211E18` background, node-graph logo top-left, big rounded-sans headline "Stop fighting context rot." in cream, a coral `#FF5A3C` accent underline, and a monospace `npx pan-wizard@latest` chip bottom-left. Flat, grainy, minimal.
+
+## 7 · (Optional) friendly developer photo — brand-tinted
+> Natural candid photo of a relaxed developer at a desk, warm daylight, shallow depth of field. Color-grade toward the brand: warm cream tones with a coral `#FF5A3C` accent object in frame (mug or sticky note) and an indigo `#5B4BE6` element. Soft, friendly, editorial. Leave clean negative space on one side for text overlay.
+
+---
+
+### Where each image goes
+- **#1** → repo `assets/pan-readme-hero.png`, referenced at the top of `README.md`
+- **#3** → npm/GitHub avatar, CLI icon, favicon
+- **#6** → `og:image` / Twitter card meta
+- **#2, #4, #5** → landing page + docs site
+- **#7** → optional landing-page section (only if you want a human touch)

package/docs/branding/image-prompts.md

@@ -0,0 +1,46 @@
+# PanWizard — Image Prompts for Nano Banana (Gemini)
+
+Hand any of these to Nano Banana. Every prompt locks the brand palette so output stays on-system.
+
+## Brand constraints (paste with any prompt if drift appears)
+- **Palette only:** Ember coral `#FF5A3C` · Conduit indigo `#5B4BE6` · Verify green `#1E8E5A` · Butter yellow `#FFCE4A` · Ink `#211E18` · Paper cream `#F3ECDD` / `#FBF7EE`
+- **Logo motif:** a node-graph — one coral dot branching *down* to a butter dot and a green dot, joined by indigo connector lines (planner → executor → verifier)
+- **Type vibe:** bold rounded geometric sans (Gabarito) + JetBrains Mono
+- **Style:** flat vector, rounded corners (8 / 16 / 32px), soft shadows, soft grain, generous negative space
+- **Avoid:** neon, heavy gradients, 3D (unless asked), stock-photo people (unless asked), busy backgrounds
+
+---
+
+## 1 · GitHub social preview / npm hero — `1280 × 640`
+> Wide developer-brand banner on a deep charcoal-brown background `#211E18`. A clean geometric node-graph logo: one coral `#FF5A3C` dot branching down to a butter `#FFCE4A` dot and a green `#1E8E5A` dot, connected by indigo `#5B4BE6` lines. To its right, a bold rounded sans wordmark "PanWizard" with "Pan" in coral and "Wizard" in cream. Subhead: "Context engineering that makes AI coding reliable." A small cream pill reading `npx pan-wizard@latest` in monospace. Flat vector, soft grain, generous negative space, no photo, no 3D. Friendly, premium dev-tool aesthetic.
+
+## 2 · Hero illustration — orchestration
+> Isometric flat illustration of three friendly rounded robot agents labelled planner, executor and verifier, passing a small glowing token along a connected track. Warm cream `#F3ECDD` background. Strict palette: coral `#FF5A3C`, indigo `#5B4BE6`, green `#1E8E5A`, butter `#FFCE4A`, ink `#211E18`. Rounded shapes, 16–32px corner radii, soft shadows, no heavy gradients, no neon. Calm, approachable, editorial vector style with lots of breathing room.
+
+## 3 · App / CLI avatar — square `1024 × 1024`
+> Square app icon, rounded-square tile filled coral `#FF5A3C`, a centered minimal node-graph glyph in cream `#FBF7EE` (one dot branching to two dots with thin connector lines), subtle inner shadow, flat and crisp, no text. iOS-style icon grid with safe-area padding.
+
+## 4 · Docs section header — wide, soft background
+> Abstract soft background for documentation headers: a warm cream `#F3ECDD` field with a few large, out-of-focus rounded shapes in coral, indigo, green and butter drifting near the edges. Large empty center for a text overlay. Flat, gentle grain, no objects, no people.
+
+## 5 · Feature spot illustrations (set of 3, square)
+> Three matching minimal spot illustrations on cream `#F3ECDD`, one per feature, same line-weight and palette (`#FF5A3C` `#5B4BE6` `#1E8E5A` `#FFCE4A` `#211E18`):
+> 1. **Thin commands** — a terminal window with a single glowing prompt line.
+> 2. **Specialist agents** — three rounded robot heads connected by indigo lines.
+> 3. **Durable state** — a stack of document cards with a small save/checkpoint badge.
+> Flat vector, rounded corners, soft shadow, generous negative space, no text.
+
+## 6 · OG / Twitter card — `1200 × 630`
+> Social share card, ink `#211E18` background, node-graph logo top-left, big rounded-sans headline "Stop fighting context rot." in cream, a coral `#FF5A3C` accent underline, and a monospace `npx pan-wizard@latest` chip bottom-left. Flat, grainy, minimal.
+
+## 7 · (Optional) friendly developer photo — brand-tinted
+> Natural candid photo of a relaxed developer at a desk, warm daylight, shallow depth of field. Color-grade toward the brand: warm cream tones with a coral `#FF5A3C` accent object in frame (mug or sticky note) and an indigo `#5B4BE6` element. Soft, friendly, editorial. Leave clean negative space on one side for text overlay.
+
+---
+
+### Where each image goes
+- **#1** → repo `assets/pan-readme-hero.png`, referenced at the top of `README.md`
+- **#3** → npm/GitHub avatar, CLI icon, favicon
+- **#6** → `og:image` / Twitter card meta
+- **#2, #4, #5** → landing page + docs site
+- **#7** → optional landing-page section (only if you want a human touch)

package/docs/branding/nano-banana-prompts.txt

@@ -0,0 +1,60 @@
+PANWIZARD — NANO BANANA (GEMINI) IMAGE PROMPTS
+================================================
+Brand palette (keep locked in every prompt):
+  Ember coral   #FF5A3C   (primary)
+  Conduit indigo #5B4BE6  (links / secondary)
+  Verify green  #1E8E5A
+  Butter yellow #FFCE4A
+  Ink           #211E18   (dark backgrounds)
+  Paper cream   #F3ECDD / #FBF7EE
+Logo motif: a node-graph — one coral dot branching DOWN to a yellow dot and a
+green dot, joined by indigo connector lines (planner -> executor -> verifier).
+Type vibe: bold rounded geometric sans (Gabarito) + JetBrains Mono.
+Style rules: flat vector, rounded corners (8/16/32px), soft shadows, soft grain,
+generous negative space. NO neon, NO heavy gradients, NO 3D unless asked,
+NO stock-photo people unless asked.
+
+
+1) GITHUB SOCIAL PREVIEW / NPM HERO  (1280 x 640)
+-------------------------------------------------
+Wide developer-brand banner on a deep charcoal-brown background #211E18. A clean
+geometric node-graph logo: one coral #FF5A3C dot branching down to a butter
+#FFCE4A dot and a green #1E8E5A dot, connected by indigo #5B4BE6 lines. To its
+right, a bold rounded sans wordmark "PanWizard" with "Pan" in coral and "Wizard"
+in cream. Subhead "Context engineering that makes AI coding reliable." A small
+cream pill reading "npx pan-wizard@latest" in monospace. Flat vector, soft grain,
+generous negative space, no photo, no 3D. Friendly, premium dev-tool aesthetic.
+
+
+2) HERO ILLUSTRATION — ORCHESTRATION
+------------------------------------
+Isometric flat illustration of three friendly rounded robot agents labelled
+planner, executor and verifier, passing a small glowing token along a connected
+track. Warm cream #F3ECDD background. Strict palette: coral #FF5A3C, indigo
+#5B4BE6, green #1E8E5A, butter #FFCE4A, ink #211E18. Rounded shapes, 16-32px
+corner radii, soft shadows, no heavy gradients, no neon. Calm, approachable,
+editorial vector style. Lots of breathing room.
+
+
+3) APP / CLI AVATAR  (square, 1024 x 1024)
+------------------------------------------
+Square app icon, rounded-square tile filled coral #FF5A3C, a centered minimal
+node-graph glyph in cream #FBF7EE (one dot branching to two dots with thin
+connector lines), subtle inner shadow, flat and crisp, no text. iOS-style icon
+grid with safe-area padding.
+
+
+4) DOCS SECTION HEADER  (wide, soft background)
+-----------------------------------------------
+Abstract soft background for documentation headers: a warm cream #F3ECDD field
+with a few large, out-of-focus rounded shapes in coral, indigo, green and butter
+drifting near the edges. Large empty center for a text overlay. Flat, gentle
+grain, no objects, no people.
+
+
+5) OPTIONAL — FRIENDLY DEVELOPER PHOTO (brand-tinted)
+-----------------------------------------------------
+Natural candid photo of a relaxed developer at a desk, warm daylight, shallow
+depth of field. Color-grade toward the brand: warm cream tones, with a coral
+#FF5A3C accent object in frame (mug, sticky note) and an indigo #5B4BE6 element.
+Soft, friendly, editorial. Leave clean negative space on one side for text.

package/docs/context-monitor.md

@@ -0,0 +1,13 @@
+# Context Window Monitor
+
+> **Note:** This page is a short summary. [HOOKS.md](HOOKS.md#pan-context-monitorjs) is the full, maintained description of the context monitor and of every other built-in hook.
+
+`pan-context-monitor.js` is a `PostToolUse` hook. It tells the agent when the host will compact its context soon, so the agent can make sure `.planning/state.md` records where it is first.
+
+- **What it measures:** the room left before the host compacts. The host compacts about 33K tokens short of its auto-compact window: `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, then `autoCompactWindow` in settings, else the model window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` lowers that point when its share of the window is lower. With auto-compact off (`DISABLE_AUTO_COMPACT=1`, or `autoCompactEnabled: false` in settings) it measures the room left in the model window instead.
+- **Where it reads it:** PAN's status line writes a bridge file, `<os-tmpdir>/pan-hooks-{uid}/claude-ctx-{session_id}.json`, and a main-thread call reads it while it is fresh. Without one (headless `claude -p`, or a status line that is not PAN's), the hook reads the session transcript the payload names. A call inside a subagent is measured on the subagent's own transcript.
+- **What it says:** at 35% or less of that room left, a note asking for a checkpoint in `.planning/state.md` (or, in a project without one, wherever it records its progress) at the next natural stopping point; at 25% or less, a checkpoint before the next step (`/pan:pause` writes it). The note carries no countdown and asks the agent to keep working at full quality, because PAN restores the planning state after the compaction.
+- **Where it runs:** Claude Code only. PAN registers it on no other runtime: Codex has no status-line bridge and its transcript is not Claude-shaped, Copilot's payload is camelCase, Gemini CLI exposes no context usage, and OpenCode runs no hooks (see [HOOKS.md](HOOKS.md#hook-runtime-support)).
+- **Safety:** it fails open. Any error, a missing transcript or an unknown model window means no note, and it never blocks a tool call.
+
+The installer registers it; [HOOKS.md](HOOKS.md#installation) shows the `settings.json` entries it writes.