@groeponline/pi-wishcraft 1.1.0 → 1.3.0

package/ROADMAP.md

@@ -1,427 +1,146 @@
 # Roadmap — pi-wishcraft
 
-Herschreven 2026-08-18. Vijfde pass 2026-08-20: 0.19.0–0.19.2 staan
-op npm. CHE-40 (`/powerline` tab) is Done via #18. Overlay-submenus
-(CHE-42 / #19) starten 0.20. ROADMAP was achter op de code: hooks,
-repairs-subset en skills-manager v2 UI zitten al op `main`.
-
-Pi core is de engine. Wishcraft is de cockpit. Elke feature dient één van
-drie doelen: **grip** (skills, tokens, config), **prestatie** (repairs,
-hooks, read-hints), of **leven** (overlays, vibes, detail views).
-
-Elke release is één campagne met een done-criterium. P1 = deze release,
-P2 = volgende, P3 = richting 1.0. Wat in 0.19 staat, shipt. Wat later
-staat, start niet eerder.
-
----
-
-## Waarom wij bestaan
-
-De pi-extensiewereld heeft statusbalken. Ze heeft geen cockpit.
-
-**Upstream `nicobailon/pi-powerline-footer`** is een goede balk: git,
-context, stash, compaction-queue, vibes, welcome, bash-mode. Wij zijn
-daaruit gegroeid. Wat zij niet hebben, en wat onze publieke identiteit
-is:
-
-| Wij | Zij / de rest |
-|---|---|
-| Skills als OS: `/skills`, inline `/$`, usage, later doctor | Geen skill-manager |
-| Idee → actie: `#`, `/idea`, `/ideas`, `/ideas issue` | Alleen compaction-hold queue |
-| Eerlijke TPS: 1s-venster over 5s-ring, in/out gescheiden | Session-average of helemaal niks |
-| Tab-token completion + git ahead/behind | Niet of later |
-| Harness-laag (0.20): hooks + tool-input repairs op stock pi | Nergens in het extensie-ecosysteem |
-
-**oh-my-pi** is een hele agent-fork (~80k regels Rust-core, eigen tools,
-LSP, DAP). Dat is een ander product. Wij forken Mario's pi niet. Alles
-wat we willen van oh-my-pi vertalen we naar een extensie of we laten het
-liggen. De weddenschap: de beste cockpit op stock pi wint van een
-tweede engine.
-
-**Command Code** is een commerciële harness (hooks, tool-call repairs,
-read-tool engineering). Hun inzicht klopt: open modellen falen op het
-contract, niet op "slimheid". Wij kopiëren hun product niet. We gieten
-dezelfde principes in wat Pi al native biedt:
-
-- `pi.on("tool_call")` — `event.input` is mutable; `block` + `reason` +
-  `terminate` bestaan (`pi-coding-agent` 0.84.x
-  `dist/core/extensions/types.d.ts`).
-- `pi.on("tool_result")` — resultaat muteren.
-- `pi.on("session_start" | "input" | "turn_end")`.
-
-Geen core-patch. Geen tweede agent. Iedereen die `pi` draait kan de
-cockpit + harness installeren.
-
-**ChefGroep** (ChefBar-statuskeys, fleet-ports) is een privé-bonus, niet
-de publieke pitch. De npm-pagina moet leesbaar zijn voor iemand die pi
-gisteren installeerde.
-
-Kort: **wij zijn de cockpit + harness voor stock pi.** Niet de balk.
-Niet de fork. Niet de SaaS-agent.
-
----
-
-## Wat wij niet worden
-
-- Geen agent-fork. Geen oh-my-pi-lite.
-- Geen derde control surface naast ChefBar / Kater. Overlays blijven in
-  deze extensie.
-- Geen muis op de live footer. Pi core bezit die; overlay-navigatie is
-  het pad.
-- Geen eigen bulk-read tool. Core's verantwoordelijkheid; wij leveren
-  repairs + hints eromheen.
-- Geen PostHog in de balk. Events alleen op expliciete Joep-opt-in.
-- Geen custom embed/component-registratie voor footer-segments.
-  Segments zijn data; `customItems` + `command/env/static` dekken
-  gebruikerscontent.
-- Geen skills-markt als identiteit vóór 1.0. Eerst discovery die klopt
-  en een manager die zoekt.
-- Geen fleet-SSH `open_ports` zonder expliciete opt-in (`segmentOptions.openPorts.host`; sanitized, geen shell-injectie).
-- Geen versie-reset naar 1.0.0. We blijven op 0.19 → 0.20 → 1.0 wanneer
-  de cockpit stabiel is.
-
----
-
-## Mijlpalen
-
-- **0.19.0–0.19.2 — "Correctheid"** (geland). Bugs, hygiëne, catalogus,
-  auto-release, `/powerline` tab. Hooks, repairs-subset en skills
-  manager v2 UI gingen mee in #12, eerder dan deze sectie beloofde.
-  Done = npm 0.19.2 live, `/skills` filtert, `$test` expandeert geen
-  debris, verify-trio groen op de tag.
-- **0.20.0–0.22 — "Harness"** (0.20.0 + 0.21.0 op npm; leftovers in GRO-1414).
-  Overlay-chrome + CHE-42 drill-down, Configure als SelectList, token-overlays,
-  rest-repairs, README-hooks. Done = drie README-hookvoorbeelden, repair-teller,
-  `alt+p` overlay-boom, `/tps` deelt de ring met het segment.
-- **1.0 — "Cockpit"**. Skills-doctor/install, declaratieve policy,
-  preset-editor, idee-review, stabiele ChefGroep-statuskeys,
-  documentatie die waar is. Done = README dekt alles wat we shipten,
-  geen kapotte footer-belofte.
-
-## Top-15 track: remaining maturity gaps
-
-Written 2026-08-20, rebaselined on 0.27.1 (code review, not this ROADMAP
-alone). Feature density is high; several original gaps closed in
-0.23–0.27. What remains is the maturity layer that separates a top-15 pi
-extension from a feature-rich prototype.
-
-### Already shipped (0.22.x–0.27.x)
-- **CHE-41 per-segment detail** — `→` in Navigate, snapshot on open (0.22.1).
-- **CHE-42 drill-down** — #19 + Configure in #13.
-- **Changelog roll** — version headers drive the what's-new panel.
-- **Per-segment fault isolation** — throwing custom segments show `!id`
-  instead of blanking the footer (#34, 0.23.1).
-- **macOS open_ports** — netstat dot-address parsing (#34, 0.23.1).
-- **GitHub Release per npm tag** (#25, 0.23.2).
-- **CodeQL proto-pollution hardening** (#27, 0.23.3).
-- **setupHooks wired** (#26, 0.23.4).
-- **Policy engine** — declarative deny/inject, no spawn (GRO-1418, #29,
-  0.24.0).
-- **`/skills doctor`** — broken frontmatter, dupes, unused, budget
-  (GRO-1416, #28, 0.24.0 / 0.25.0 tag).
-- **`/skills new` templates** — no marketplace (GRO-1417, #32, 0.26.0).
-- **`/ideas` review overlay** — status, tags, skill insert (GRO-1419, #31,
-  0.27.0).
-- **English operator UI** — overlays, skill manager, `/wishcraft` TUI
-  (GRO-1422, #24, 0.27.1).
-- **`powerline.skills.count` + read hints + Status trim** (GRO-1420, 0.23.0).
-- **1.0.0 cockpit cut** — README lists doctor, templates, policy, and
-  idea-review (GRO-1421). Semver leaves 0.x.
-
-### Remaining open gaps (maturity)
-P1 — differentiation and quality:
-1. **Settings contract to pi core.** No `contributes.settings`/schema;
-   users hand-edit JSON. *Fix: typed settings schema + contributions.*
-2. **Zero-config first run.** Install still expects JSON edits for the most
-   useful features. *Fix: sensible defaults + first-run setup overlay.*
-3. **Perf budget / low-power mode.** Status renders every ~33ms; heavy
-   segments (bash-history, git) can hit the hot path. *Fix: configurable
-   refresh + lite mode.*
-4. **Accessibility (no-color / reduced-motion).** Truecolor + animations
-   (vibes, rainbow think) break on terminals without truecolor. *Fix:
-   `NO_COLOR`/8-color + reduced-motion respect.*
-
-P2 — full product, post-1.0:
-5. **Preset editor in-menu** — custom JSON-only today.
-6. **Skill install from repo/npm** — discovery + doctor exist; install and
-   curate missing.
-7. **Host-status integration** — `ctx.ui.setStatus` beside the footer so
-   status also shows in host UI (`skills.count` is a start; full coverage
-   remains).
-
-Linear tickets for open gaps are still to be filed (not invented in this
-ROADMAP).
-
----
-
-## 0.19.0 — Correctheid
-
-Eén campagne, drie stacked PRs. Volgorde vast. Elke PR: `npm run
-typecheck && npm test && npx madge --circular src index.ts bash-mode
-queue` groen vóór review. Overlay-submenus (CHE-42) zitten in 0.20.
-
-### PR A — runtime-bugs — ✅ geland in `feat/wishcraft-0.19` (samen met skills v2, hooks, lantern-welcome, `/wishcraft` config-TUI; supersedeert #10)
-
-Alle zes punten uit het oorspronkelijke plan zitten in de ene 0.19-branch:
-debris weg, filter werkend (v2: substring i.p.v. prefix), cache-invalide op
-`session_start` + TTL, woordgrens op inline-triggers, unclosed-fence EOF,
-bash-session tempdir + sentinel-colon, `permissions: contents: read`.
-`npm pack --dry-run` bevat geen debris (113 files, geen `ook.md`/`test.md`).
-
-### PR B — config-afmakers — ✅ geland in `feat/wishcraft-0.19` / #12
-
-Bestanden: `src/config/`, `src/segments/`, `src/extension/ui/`.
-
-1. `segmentLabels` toepassen in `renderSegment` voor **alle** segments
-   (nu alleen tps/open_ports/subagents).
-2. `segmentOptions.<seg>.template` wint van label
-   (`"{value} tok/s"`).
-3. `segmentOptions.tps.windowMs` (default 1000), `.mode`
-   (`both | out | in | total`), `.hideIdle` (default true).
-4. Visibility-toggle in het `alt+p`-menu schrijft live
-   `powerline.disabledSegments`.
-
-Done: unit tests op label/template/windowMs-resolutie; handmatige
-check: label op `git` + `cost` zichtbaar, TPS hidden bij 0 wanneer
-`hideIdle`.
-
-### PR C — release 0.19.0
-
-1. Merge naar `main` triggert `release.yml`: `node scripts/release.mjs auto --push`.
-   Commits sinds `v0.18.0` bevatten `feat:` → **0.19.0**. Handmatig blijft
-   `npm run release minor` + tag-push mogelijk.
-2. Tag-job publiceert met org-secret `NPM_TOKEN` (geen repo-override).
-3. Verify: tag op origin, publish-job groen, `npm view @groeponline/pi-wishcraft version` = 0.19.0.
-   Catalogus (hard): `npm run verify:package` groen in de release-job;
-   `npm view @groeponline/pi-wishcraft keywords` bevat `pi-package`,
-   `pi-extension`, `wishcraft`; `pi.image` is de banner-URL.
-   Daarna:
-   - https://pi.dev/packages/@groeponline/pi-wishcraft toont 0.19.0
-   - https://pi.dev/packages?name=wishcraft toont de card
-   - https://pi.dev/packages?name=groeponline toont wishcraft naast
-     fff en orchestrator
-   Detailpagina bestaat al voor 0.18.0; de zoekindex niet. Nieuwe
-   publish + discovery-keywords is de refresh. Catalogus-lag tot
-   een paar uur is oké; ontbreken na 24u = 0.19.1 met dezelfde
-   metadata, geen stille "later wel".
-4. README: skills-sectie zegt dat filter werkt; geen `ook`/`test`
-   debris. ROADMAP sync (deze file).
-5. `npm deprecate @groeponline/pi-powerline-footer` blijft een
-   scope-owner actie buiten deze PR (`deprecate-old-name.yml`,
-   workflow_dispatch). Blokkeert 0.19 niet.
-
-Hygiëne die al klaar is en niet opnieuw gepland wordt:
-
-- Fork-tags weg (51 upstream-tags, 2026-08-18). Eigen reeks vanaf
-  `v0.10.0`.
-- `banner.png` blijft (README). `wishcraft-concept.png` gaat weg in
-  PR A of een docs-PR, niet in de balk-runtime.
-- CHANGELOG inkorten (GRO-1060) doen we **niet** in 0.19. Erfgoed
-  is history, geen cruft.
-- Versie blijft 0.19, geen reset naar 1.0.0.
-
-GRO-1061 (runner-queue) is ops, geen product-slice.
-
----
-
-## 0.20.0 — Harness
-
-Vier stacked PRs. 0.20.0 (#19) en 0.21.0 (#13) staan op npm. CHE-42
-Configure-overlay, doctor/export, queue-archive en `docs/` zijn geland.
-GRO-1414 sluit README-hooks, rest-repairs, `/tps`+`/usage`, substring-filter.
-
-Overlay-chrome kit, één keer, daarna hergebruiken: box + ronde hoeken,
-accent-kop, dim metadata, rechts uitgelijnde counts, `→` detail /
-`←` terug / `esc` weg, consistente footer-hints. Eerste consument =
-skills v2; tweede = `/usage`; derde = queue/idea. Pure render-
-functies, geen `ctx.ui`-mock.
-
-### PR E — hooks — ✅ geland in `feat/wishcraft-0.19`; README-voorbeelden in GRO-1414
-
-Settings: `wishcraft.hooks` met events
-`preToolUse | postToolUse | sessionStart | turnEnd`. Per hook
-`matcher` (toolName-regex) en `command` (JSON stdin/stdout, timeout
-30s, max 600s). PreToolUse: `allow | deny` + reason die het model
-ziet. Exit 2 = deny, stderr-eerste-regel = reason. PostToolUse /
-SessionStart: `additionalContext`. Kill-switch
-`wishcraft.hooksEnabled: false`. PreToolUse sequentieel (eerste deny
-stopt); PostToolUse/turnEnd parallel.
-
-Done: `parseHookOutput` unit-testen. README met drie werkende
-voorbeelden: bash-guard (`rm -rf /` blokkeren), write-audit
-(append-only log), SessionStart git-status injectie.
-
-### PR F — tool-input repairs — ✅ schema-loze subset in 0.19; rest (JSON-array, `{}`, bare-wrap, path aliases) in GRO-1414. Core tools blijven met rust.
-
-`tool_call`-handler repareert bekende malformaties vóór executie
-(mutable input). Volgorde vast: json-parse vóór bare-wrap.
-
-1. `null` voor optioneel weglaten.
-2. JSON-string-array → array.
-3. `{}`-placeholder → array.
-4. bare-string → array-wrap.
-5. markdown-auto-link pads (`[x.md](http://x.md)` → `x.md`).
-6. pad-alias `filePath` / `absolutePath` / `target_file` → `path`.
-
-Repair-teller per `(tool, repair)` als extension status.
-`wishcraft.repairsEnabled` default true. Scope: custom tools +
-extensie-tools. Pi core-tools laten we met rust — core valideert
-zijn eigen schema's.
-
-Done: pure `repairToolInput(tool, input)` + table-driven tests voor
-de zes gevallen + de parse-vóór-wrap invariant.
-
-### PR G — overlay-submenus (CHE-42) — ✅ #19 + expansion (#13 reopen)
-
-The `alt+p` menu gets stacked `SelectList` overlays (arrows +
-descriptions) instead of flat `ctx.ui.select`. Maximum three top-level
-entries. #19 lands the top-level tree (Navigate / Configure /
-Status). Configure now uses `showSelectOverlay` (CHE-42 remainder). CHE-40
-is Done (#18). CHE-41 is Done: `→` in Navigate, snapshot on open, no second `alt+i` path.
-
-### PR H — skills manager v2 UI + token-overlays
-
-Replaces `skill-manager.ts` (242 lines). The data layer builds on Pi
-core `loadSkills` / `loadSkillsFromDir` / `Skill` /
-`SkillFrontmatter` (publicly exported in
-`@earendil-works/pi-coding-agent`).
-
-UI, non-negotiable:
-
-- Working search: substring on name + description + path,
-  case-insensitive; `ctrl+u` clears; empty match = row
-  `no skills for '<q>'`.
-- Categories with headings (bundled / global / project / prompts);
-  `tab` switches the filter; `s` sorts name ↔ usage.
-- `→` detail (frontmatter table, usage, path, body + scroll);
-  `enter` inserts; `e` opens `$EDITOR` (default nvim) via external
-  spawn like pi's `!`; `n` creates a new skill in
-  `~/.pi/agent/skills/<name>/SKILL.md`; `d` delete + confirm.
-- Usage-ledger `~/.pi/agent/skill-usage.json` (name, timestamp,
-  trigger type). Best-effort, never blocking on the input hot path.
-- Skill health: core-diagnostics as a warning icon; `?` explains it.
-
-Same chrome as the segment navigator. English, direct.
-
-At the same time, small additions:
-
-- `/tps` overlay: in/out, peak + average over the existing ring.
-  No new sampler.
-- `/usage` overlay: today / this week / this session; per model;
-  cache-hit %; ASCII sparkline. File
-  `~/.pi/agent/wishcraft-usage.json` (append-only, compaction at
-  threshold).
-- `wishcraft.tokenBudget.daily` colors the segment red and warns
-  in the welcome at 80% / 100%. Never blocking.
-
-Done: substring filter tests; usage-ledger tests; `/tps` reads
-the same ring as the segment (no second source of truth).
-
----
-
-## 1.0 — Cockpit
-
-Shipped. The 0.x train ends at this cut. Preset editor and skill
-install-from-repo stay post-1.0 (top-15 P2).
-
-- [x] `/skills doctor` — broken frontmatter, long descriptions, global/project
-      duplicates, unused skills. Table, not an essay. (GRO-1416, #28)
-- [x] `/skills new` templates — standard, browser-workflow, CLI-workflow,
-      review-checklist. No marketplace. (GRO-1417, #32)
-- [x] Policy engine — in-process deny/inject, no spawn. Command hooks remain
-      for anything that needs a process. (GRO-1418, #29)
-- [x] Per-segment detail (CHE-41) — `→` in Navigate, snapshot on open.
-- [x] Idea review — `/ideas` overlay: idea / in-progress / done, tags,
-      Run with skill X. Welcome widget shows next idea + `/ideas next`.
-      (GRO-1419, #31)
-- [x] Status keys — `powerline.tps`, `powerline.ports`, `powerline.preset`,
-      `powerline.skills.count` via `ctx.ui.setStatus`. Not the public pitch.
-      (GRO-1420)
-- [x] Read-tool hints — continuation hint when core omits a range/offset
-      summary. (GRO-1420)
-- [x] English operator UI. (GRO-1422, #24)
-- [x] README lists doctor, new, policy, and idea-review. `banner.png` only.
-
----
-
-## Linear
-
-| Ticket | Actie |
-|---|---|
-| GRO-1060 fork cleanup | Done. Release-pad bewezen. CHANGELOG niet inkorten. Versie niet resetten. `banner.png` blijft. |
-| GRO-1061 CI queue | Ops, niet deze roadmap. |
-| CHE-40 `/powerline` tab | Done (#18 / 0.19.2). |
-| CHE-41 per-segment detail | Done. `→` in Navigate; snapshot on open; `alt+i` stays ports. |
-| CHE-42 drill-down | Done (#19 + Configure in #13). |
-| GRO-1414 0.20 leftovers | Done (#20 / 0.22.0). |
-
-Oude `pi-powerline-footer`-projecttickets niet laten staan alsof
-die package nog leeft.
-
----
-
-## Kwaliteit (altijd)
-
-- Overlay logic is testable via pure functions. No headless `ctx.ui`.
-- **English UI:** operator overlays, notify strings, and `/wishcraft` copy are
-  English. Do not add Dutch UI strings.
-- `prepublishOnly` = `tsc --noEmit`. Een slecht type ship't niet.
-- `madge --circular` blijft CI. Nieuwe map in `src/` → check mee.
-- Dependabot-vulns (devDep-transitief): waiven, track op GRO-603.
-  Niet required in CI. Geen stille bump van TypeScript 7 of
-  `@types/node` 26 in een bug-PR.
-- TPS-core blijft 1s sliding window over 5s-ring. Geen regressie
-  naar session-average of per-render EMA (beide spikten:
-  `tps:12775`).
-
----
-
-## Residual risks
-
-- `SelectList.setFilter` matcht alleen prefix op `value`. Overlay-chrome
-  filtert zelf op substring (GRO-1414). Skills-manager had dat al.
-- `npm deprecate` van de oude naam faalt tot de scope-owner het
-  token verruimt. Gebruikers die `pi-powerline-footer` installeren
-  blijven op 0.17.2.
-- Hooks spawnen processen. Default timeout 30s; kill-switch
-  `wishcraft.hooksEnabled` bestaat al op `main`.
-- Repairs op core-tools raken we niet aan. Als DeepSeek-achtige
-  modellen daar alsnog op stuklopen, is dat een gesprek met pi
-  core, geen stille override.
-- `loadSkills` API-drift: we pinnen `@earendil-works/pi-coding-agent`
-  `>=0.81.0 <0.85.0`. 0.20 neemt de publieke export over; bij
-  breaking change blijven we op eigen scan tot de pin omhoog kan.
-- Usage-ledger corruptie: best-effort write, kapot JSON → leeg
-  object, nooit throw op de input-path.
-- ChefGroep-keys in 1.0 mogen de publieke README niet gijzelen.
-
----
-
-## Rollback
-
-- PR A–H: revert-commit op `main`. Geen force-push.
-- 0.19-tag te vroeg: laat de tag staan, ship `0.19.1` met de fix.
-  Tags niet herschrijven.
-- Fork-tags (51 stuks) zijn weg. Recovery = upstream remote
-  `nicobailon/pi-powerline-footer` opnieuw fetchen, niet onze
-  `v0.10.0+` overschrijven.
-- DevDep-bumps (pi-* 0.84.2, TS 7) horen in een eigen PR met
-  `npm ci` + de verify-trio. Revert = die PR revert + `npm ci`.
-
----
-
-## Checklist (1:1 met 0.19)
-
-- [x] PR A gemerged: filter, debris, cache, triggers, bash-leaks,
-      CodeQL. Verify-trio groen. (#12)
-- [x] `npm pack --dry-run` bevat geen `ook.md` / `test.md`.
-- [x] PR B gemerged: labels, template, TPS-opties, visibility.
-      Verify-trio groen. (#12)
-- [x] Gallery-contract gemerged (`chore/pi-dev-gallery`): keywords,
-      `publishConfig.access`, `pi.image`, `npm run verify:package`. (#11)
-- [x] PR C: merge to `main` tagged `v0.19.0` then `v0.19.1` then
-      `v0.19.2` and published (`npm view` = `0.19.2`). Same-job bump
-      publish via #16. CHE-40 tab-complete via #18.
-- [x] README skills-sectie waar; deze ROADMAP in sync met 0.19.2.
-- [x] CHE-40: `/powerline` subcommand-tab geland (#18). CHE-41/42
-      hernoemd naar wishcraft.
+Baseline: **v1.2.0**, published 2026-08-24.
+
+Pi is the engine. Wishcraft is the operator experience layer: Signal, Deck, skills, ideas, shell UX, hooks, repairs and policy without forking Pi core.
+
+Historical 0.x/1.0/vNext campaign detail belongs in `CHANGELOG.md` and `docs/design/`. This file describes only the current product contract and work that is still open.
+
+## Product boundary
+
+Wishcraft may extend the Pi experience, but it does not become:
+
+- a Pi fork or second agent engine;
+- a fleet/orchestration control plane;
+- a SaaS integrations bundle;
+- a second plugin runtime competing with Pi extensions;
+- a telemetry collector by default.
+
+External systems should connect through small contribution/integration contracts. Vendor-specific control planes belong outside Wishcraft.
+
+## Release line
+
+| Release | Theme | State | Done means |
+| --- | --- | --- | --- |
+| **1.2** | Operator Layer | shipped | Deck, universal Signal, structural appearance, motion gallery/composer, skill workbench and first-class motion accessibility |
+| **1.3** | Hardening | current | release invariant, render-path performance, one token source of truth, explicit renderer/lifecycle contracts, regression coverage |
+| **1.4** | Extension Contract | next | typed settings registry plus small contribution APIs; no new plugin runtime |
+| **1.5** | Craft Ecosystem | later | curated skill/package workflows built on Pi-native distribution and the contribution contract |
+| **2.0** | Stable Experience Platform | target | documented compatibility policy, migrations, performance budgets and stable public extension points |
+
+## 1.3 — Hardening
+
+No feature dump. This release exists to make the v1.2 surface trustworthy.
+
+### P0 — release integrity
+
+- One reusable `Verify` contract for PR verification and release gating.
+- Verify includes whitespace, typecheck, unit tests, circular dependency check and Pi package contract.
+- Release jobs depend on Verify and re-check the synchronized `origin/main` tree before tagging.
+- `main` should require the Verify check in repository rules before merge.
+
+### P0 — render/runtime performance
+
+- Deck paint must not run filesystem-backed skill discovery, skill doctor or settings parsing.
+- Expensive Deck data is cached as static snapshot state and refreshed only on open, relevant navigation or mutation.
+- Live model/Git/context/queue/Signal state remains cheap to repaint.
+- Idle motion stays 0 FPS.
+
+### P0 — appearance consistency
+
+- `src/config/types.ts` + `src/config/tokens.ts` are the canonical token contract.
+- `src/theme/tokens/*` is compatibility-only; it may re-export but may not define a second palette or semantic mapping.
+- One structural base must paint the same semantic roles regardless of the configuration path used to select it.
+
+### P0 — Signal contract
+
+- Signal is the universal status renderer for legacy and structural presets.
+- Legacy presets keep their existing segment/layout/color contract unless a structural appearance layer is explicitly selected.
+- Terminal one-shots (`success`, `warning`, `error`) settle to `idle/ready` after their finite burst.
+- Reduced/off/screen-reader modes communicate state without requiring animation.
+
+### P1 — verification matrix
+
+Add/keep regression coverage for:
+
+- widths around 40 / 80 / 120+ columns;
+- ASCII, Nerd Font and `NO_COLOR` rendering;
+- full / reduced / functional / off motion;
+- Deck render hot-path invariants;
+- legacy preset color compatibility;
+- release-gate dependency order;
+- Linux and macOS system-segment parsing.
+
+## 1.4 — Extension Contract
+
+The next architecture step is **composability**, not more built-in routes.
+
+### Typed settings registry
+
+One registry should drive:
+
+```text
+settings definition
+      │
+      ├─ parsing + validation
+      ├─ defaults + migrations
+      ├─ /wishcraft settings
+      ├─ Pi settings contribution (where supported)
+      └─ generated documentation/examples
+```
+
+This removes duplicate knowledge about settings and enables a real zero-config first run.
+
+### Small contribution API
+
+Target capabilities, subject to Pi host APIs:
+
+```text
+registerDeckRoute()
+registerSignalSource()
+registerMotion()
+registerAppearanceContribution()
+registerRecipeOrAction()
+contributeSettings()
+```
+
+Rules:
+
+- Pi remains the package/extension runtime.
+- Contributions are data/callback contracts, not arbitrary nested plugin loaders.
+- Public contracts are versioned and capability-scoped.
+- A failing contribution cannot take down Signal or the Deck.
+
+## 1.5 — Craft Ecosystem
+
+After the contribution/settings contracts are stable:
+
+- skill import/install workflows from explicit trusted sources;
+- curated recipes/actions that compose existing Wishcraft/Pi capabilities;
+- package discovery surfaced through Pi-native package distribution rather than a parallel Wishcraft marketplace;
+- export/import of appearance and motion recipes with validation.
+
+## 2.0 — Stable Experience Platform
+
+2.0 is justified when the public contracts, not the feature count, are stable.
+
+Required before 2.0:
+
+- compatibility and deprecation policy;
+- settings migrations with round-trip tests;
+- measured render/performance budgets;
+- stable contribution API with fault isolation;
+- release provenance and required repository checks;
+- docs generated from canonical contracts where practical;
+- no known duplicate sources of truth for tokens, settings or release verification.
+
+## Always-on engineering rules
+
+- English operator UI.
+- No synchronous discovery work in paint/render loops.
+- No background animation when nothing consumes it.
+- Core Pi tools are not silently rewritten by Wishcraft repairs.
+- Policies and hooks remain explicitly disableable.
+- Security-sensitive paths fail closed.
+- Package/release verification runs before npm publication.
+- New features must fit the operator-layer boundary above.

package/docs/commands.md

@@ -2,7 +2,7 @@
 
 ## Usage
 
-Activates automatically. Toggle with `/powerline`, switch presets with `/powerline <name>`, and move the primary row with `/powerline placement above|below|toggle`.
+Activates automatically. Toggle with `/signal` (alias `/powerline`). Switch layouts with `/signal <name>`. `/signal menu` opens Navigate / Configure / Status. `/wishcraft` opens the Deck; `/wishcraft settings` is the flat list. Move the primary row with `/signal placement above|below|toggle`.
 
 Use `/cd <path>` to continue the current conversation from another working directory. It supports relative paths, absolute paths, `~`, `~/...`, and directory completions. With no argument, `/cd` prints the current Pi session directory. The command switches into a cwd-updated session file so Pi tools and the footer path segment agree after the change.
 
@@ -101,8 +101,12 @@ Pi core renders the footer as static text, so live click is not possible; action
 - `/open-ports`: list listening ports and pick one
 - `/powerline doctor`: diagnostics overlay — settings file validity, unknown presets, Nerd Font detection, git polling, bash-mode status, and queue file health
 - `/powerline export`: export the current preset + effective layout + labels as a JSON snippet (Enter copies it to the clipboard)
-- `alt+p`: **powerline menu**: navigate the live segments (`↑`/`↓` + `enter`, `→`/`tab` opens a per-segment detail panel captured at open), configure (preset / TPS / UDP / segment visibility / labels / build custom preset), or open the full ports list
+- `alt+p`: **Wishcraft Deck** — operator overlay (Home, Signal, Skills, Ideas, Guardrails, Appearance, …). `g` then a jump key (`h` home, `s` signal, `a` appearance). Escape closes. `/signal menu` still opens Navigate / Configure / Status.
 - `alt+i`: **powerline info**: full open-ports list
+- `/wishcraft [route]`: open the Deck at a named route (`appearance`, `skills`, …)
+- `/wishcraft settings`: flat settings TUI, including `powerline.appearance.base` and `powerline.motionLevel`
+- Deck **Motion**: gallery + composer. `t` picks the event, Enter applies, `e` opens the composer
+- Deck **Skills**: workbench list with health; Enter inserts the skill body
 
 Both `alt+p` and `alt+i` are rebindable (see Keybinds below); changes apply after `/reload`.
 

package/docs/configuration.md

@@ -190,6 +190,27 @@ Make `open_ports` probe a named SSH host instead of the laptop:
 
 See [Segments & theming](./segments.md) for the probe's best-effort behavior and requirements.
 
+## Appearance
+
+`powerline.appearance` is independent of the information layout (`powerline.preset`). The structural base paints Signal colors and motion. Layout presets (`default`, `minimal`, `compact`, `full`, `nerd`, `ascii`, `chef`) keep their segment lists until you change `preset`.
+
+```json
+{
+  "powerline": {
+    "preset": "chef",
+    "appearance": {
+      "base": "lanternwake"
+    }
+  }
+}
+```
+
+Bases: `lanternwake`, `threadbound`, `scryglass`, `runebloom`, `moonwell`, `hexforge`, `vellum`, `wisp`, `starweave`, `crucible`. Apply from Deck → Appearance → Enter, `/wishcraft settings`, or `/signal hexforge` (a structural layout name also writes `appearance.base`). Optional mix keys: `palette`, `signalLayout`, `chrome`, `glyphs`, `deck`, `welcome`, `motion`.
+
+Until `appearance` is set, Signal keeps the layout preset colors. If `preset` itself is a structural name and `appearance` is empty, that name is treated as the base.
+
+`powerline.motionLevel` is `full`, `reduced`, `functional`, or `off`. Host flags still win: `NO_COLOR`, `WISHCRAFT_MOTION`, `WISHCRAFT_SCREEN_READER`, and `PREFER_REDUCED_MOTION`. Deck Motion → Enter writes `powerline.appearance.motion.<event>`.
+
 ## Status bridge for other extensions
 
 Powerline publishes its own state under a stable key set so ChefBar and other extensions can read it without depending on powerline internals: