@groeponline/pi-wishcraft 1.0.5 → 1.2.0

package/docs/design/theme-contract.md

@@ -0,0 +1,132 @@
+# Semantic Design Tokens & Theme Contract
+
+## Overview
+
+Wishcraft follows a token-driven design system inspired by Charm Crush. Rather than hardcoding ad-hoc color values or tying colors strictly to concrete segment names, themes are expressed through an abstract layer of **Semantic Design Tokens** (`WishcraftTokens`).
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   Wishcraft Presets                    │
+│      (Lanternwake · Threadbound · Scryglass · ...)     │
+└───────────────────────────┬────────────────────────────┘
+                            │ populates
+                            ▼
+┌────────────────────────────────────────────────────────┐
+│                   WishcraftTokens                      │
+│     (surface, text, primary, accent, motionHot, ...)   │
+└───────────────────────────┬────────────────────────────┘
+                            │ maps & derives
+                            ▼
+┌────────────────────────────────────────────────────────┐
+│                 Legacy SemanticColor                   │
+│        (model, gitClean, context, cost, border)        │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Token Specifications
+
+```typescript
+export interface WishcraftTokens {
+  // Surfaces & Backgrounds
+  surface: ColorValue;          // Base frame and background tint
+  surfaceRaised: ColorValue;    // Modals, popovers, and elevated cards
+
+  // Typography
+  text: ColorValue;             // Primary text and active values
+  textMuted: ColorValue;        // Secondary labels, timestamps, and dim chrome
+
+  // Brand & Accents
+  primary: ColorValue;          // Primary identity, active model badge
+  secondary: ColorValue;        // Path indicators, structural dividers
+  accent: ColorValue;           // Highlights, tags, key metric accents
+
+  // Feedback & State
+  success: ColorValue;          // Clean git status, healthy skills, completed tasks
+  warning: ColorValue;          // Uncommitted git diffs, warning limits, compact alerts
+  error: ColorValue;            // Tool execution failures, policy blocks, error states
+
+  // Interaction
+  focus: ColorValue;            // Focused input field, active navigation item
+  selection: ColorValue;        // Highlighted table row or search match
+
+  // Motion & Animation Channels
+  motionDim: ColorValue;        // Low-intensity background sweep or trailing tail
+  motionHot: ColorValue;        // High-intensity active pulse or spark
+  motionTrail: ColorValue;      // Intermediate gradient or propagation step
+}
+
+export type ColorValue = ThemeColor | `#${string}`;
+```
+
+---
+
+## Backward-Compatible Semantic Mapping
+
+To ensure 100% backward compatibility with pre-existing color configurations and third-party presets, legacy `SemanticColor` values are derived from `WishcraftTokens` according to this default mapping:
+
+| Legacy `SemanticColor` Key | Source `WishcraftToken` | Description |
+| :--- | :--- | :--- |
+| `model` | `tokens.primary` | Active LLM badge indicator |
+| `path` | `tokens.secondary` | Working directory and file paths |
+| `gitClean` | `tokens.success` | Clean git repository status |
+| `gitDirty` | `tokens.warning` | Dirty/uncommitted git changes |
+| `context` | `tokens.text` | Normal context token usage (< 70%) |
+| `contextWarn` | `tokens.warning` | Context warning threshold (70% - 90%) |
+| `contextError` | `tokens.error` | Critical context limit (> 90%) |
+| `cost` | `tokens.accent` | Session usage / cost metrics |
+| `queue` | `tokens.textMuted` | Queued command count badge |
+| `separator` | `tokens.textMuted` | Powerline segment divider symbols |
+| `border` | `tokens.surfaceRaised` | Deck outer frame and partition lines |
+
+---
+
+## Extended Preset Contract (`PresetDef`)
+
+The `PresetDef` schema extends legacy configurations with modular personality definitions:
+
+```typescript
+export interface PresetDef {
+  // Legacy Layout Properties (Retained for 100% compatibility)
+  leftSegments: SegmentType[];
+  rightSegments: SegmentType[];
+  secondarySegments?: SegmentType[];
+  separator: SeparatorStyle;
+  segmentOptions?: Record<string, SegmentOptions>;
+  colors?: Partial<Record<SemanticColor, ColorValue>>;
+
+  // vNext Structural Personality Definitions
+  tokens?: WishcraftTokens;
+  chrome?: ChromeSpec;
+  signal?: SignalSpec;
+  motion?: Partial<Record<MotionEvent, MotionRef>>;
+  deck?: DeckSpec;
+  welcome?: WelcomeSpec;
+  glyphs?: GlyphSet;
+}
+
+export interface ChromeSpec {
+  frame: "rounded" | "square" | "double" | "minimal" | "borderless";
+  corners: { tl: string; tr: string; bl: string; br: string };
+  dividers: { horizontal: string; vertical: string; cross: string };
+  density: "compact" | "medium" | "spacious";
+}
+
+export interface SignalSpec {
+  layout: "standard" | "capsule" | "woven" | "sparse" | "block";
+  separators: {
+    left: string;
+    right: string;
+    subLeft?: string;
+    subRight?: string;
+  };
+  caps: {
+    leftOpen?: string;
+    leftClose?: string;
+    rightOpen?: string;
+    rightClose?: string;
+  };
+  animation: string; // MotionRef ID
+}
+```

package/docs/design/vnext-overview.md

@@ -0,0 +1,55 @@
+# Wishcraft vNext — Architecture & Product Overview
+
+## Vision
+
+> **Wishcraft is Pi’s animated operator layer — intent, skills, ideas, guardrails, and session state made visible and controllable without turning Pi into an IDE.**
+
+In August 2026, terminal interfaces have moved far beyond static tables and rudimentary ASCII menus. Modern developer tools (PiTTy, Crush, OpenTUI, Drift, Termflix, Copilot CLI) demonstrate that terminal software can combine rich aesthetics with responsive, ergonomic workflows.
+
+Wishcraft vNext does not seek to replace Pi or turn it into a bloated, monolithic IDE. Instead, it acts as a **continuous operator layer**—a polished companion that weaves status, motion, craft, and control directly into terminal workflows.
+
+```
+┌────────────────────────── WISHCRAFT CONTINUOUS SURFACE ──────────────────────────┐
+│ ◈ AMBIENT HEADER: Model / Git Branch / Session Context / Active State            │
+├──────────────────────────────────────────────────────────────────────────────────┤
+│                                                                                  │
+│                                ACTIVE DECK ROUTE                                 │
+│                   (Home · Signal · Skills · Ideas · Appearance)                  │
+│                                                                                  │
+├──────────────────────────────────────────────────────────────────────────────────┤
+│ ❖ ANIMATED SIGNAL: ╾━━━━ main ━━━━╾✦╼━━━━ read_file ━━━━━━━ ctx █████░ 47%       │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## The Five Pillars
+
+### 1. Deck (`Alt+P` / `/wishcraft`)
+The Deck is the primary control surface for the agent operator. It provides a focused modal interface hosting structured routes for session management, tool inspections, skill workflows, and deep customization. Built using `ctx.ui.custom`, the Deck renders inside a single unified continuous outer frame, avoiding cluttered nested cards.
+
+### 2. Signal (`/signal`)
+Signal is Wishcraft's signature animated powerline. Configured with three independent lanes (*Left: Identity/Git*, *Center: Live Activity*, *Right: Metrics/Queue*), Signal provides continuous at-a-glance awareness. During active tasks (such as token streaming or tool execution), Signal dynamically pulses or sweeps along its connective track.
+
+### 3. Motion
+A centralized, event-driven terminal animation engine. Rather than scattering uncoordinated timers across components, a single unified scheduler drives visual channels with dedicated cadences. When the system is idle, the scheduler rests at **0 FPS**, eliminating CPU overhead.
+
+### 4. Craft
+Workflows for managing agent capabilities:
+- **Skills**: Discover, inspect health, execute, and author skills using an inline wizard.
+- **Ideas**: Quick capture and organization of thoughts and intents.
+- **Guardrails**: Policy inspection and execution safety gates.
+
+### 5. Appearance
+Ten structural presets that define distinct layout personalities, semantic design tokens, glyph grammars, and signature motion languages. Presets serve as cohesive starting points, but users remain free to decouple and customize every layer individually.
+
+---
+
+## Architectural Boundaries
+
+To ensure maximum stability, performance, and compatibility with the Pi ecosystem, Wishcraft enforces strict architectural boundaries:
+
+1. **Pi-Native Extensibility**: Wishcraft executes inside the standard Pi extension runtime. It does not attempt to hijack or replace Pi's root TUI transcript or editor.
+2. **Overlay Control Surface**: The Deck operates as an overlay via `ctx.ui.custom`. Closing the Deck immediately returns full focus to the standard Pi transcript.
+3. **No Mouse on Live Footer**: Pi renders the terminal footer as static text. Signal avoids fragile terminal mouse interceptors on the live footer, reserving rich pointer and keyboard interactions for the Deck.
+4. **Performance & CPU Budget**: Animations are strictly tied to real session events. When the agent is idle and no ambient animations are configured, all timers are cleared to achieve 0% CPU consumption.

package/docs/design/vnext-release-plan.md

@@ -0,0 +1,212 @@
+# Wishcraft vNext — Stacked PR Release Plan
+
+## Goal
+
+Wishcraft is Pi's animated operator layer — intent, skills, ideas, guardrails, and session state made visible and controllable without turning Pi into an IDE.
+
+The vNext release establishes five foundational pillars:
+
+1. **Deck** — The unified interactive control surface (`Alt+P` / `/wishcraft` and deep-link routes).
+2. **Signal** — The motion-aware animated powerline and status surface (`/signal`, with `/powerline` as compatibility alias).
+3. **Motion** — A unified, zero-overhead event-driven terminal animation engine.
+4. **Craft** — First-class workflows for Skills, Ideas, Guardrails, and session tools.
+5. **Appearance** — Ten structural presets, live semantic design tokens, and a full motion gallery with fuzzy search customizer.
+
+---
+
+## Working Method: Stacked PRs
+
+Each pull request branches off the immediately preceding PR branch (`vnext/00-design` $\rightarrow$ `vnext/01-motion-engine` $\rightarrow$ ... $\rightarrow$ `vnext/08-craft-docs`) and must be reviewed, tested, and merged in strict linear order.
+
+```mermaid
+graph LR
+  PR0["PR0: Design Corpus"] --> PR1["PR1: Motion Engine"]
+  PR1 --> PR2["PR2: Semantic Tokens"]
+  PR2 --> PR3["PR3: Preset Contract"]
+  PR3 --> PR4["PR4: Animated Signal"]
+  PR4 --> PR5["PR5: Wishcraft Deck"]
+  PR5 --> PR6["PR6: Appearance & Gallery"]
+  PR6 --> PR7["PR7: First-Class A11y"]
+  PR7 --> PR8["PR8: Craft, Skills & Docs"]
+```
+
+### Quality & Execution Invariants
+
+- **Zero Breakage**: Every single PR must keep `npm run typecheck && npm test && npx madge --circular` passing 100%.
+- **English UI Only**: All UI strings, labels, hints, and log outputs must be in clean, idiomatic English.
+- **Pure Function Testability**: All motion mathematics, preset resolution, token derivations, and event routing must be pure functions testable in Vitest/Node without headless `ctx.ui` dependencies.
+- **Backward Compatibility**: Existing `PresetDef` fields remain intact; all new fields (`tokens`, `chrome`, `signal`, `motion`, `deck`, `welcome`, `glyphs`) are optional so pre-existing presets continue to render seamlessly.
+- **Architecture Boundaries**: The Deck is implemented as a `ctx.ui.custom` overlay within the Pi extension sandbox. No root-TUI hijacking and no mouse handlers on the live terminal footer.
+
+---
+
+## PR Specifications Breakdown
+
+### PR 0 — Design Corpus (Docs Only)
+
+- **Branch**: `vnext/00-design`
+- **Impacted Paths**: `docs/design/*`, `docs/index.md`, `ROADMAP.md`
+- **Scope & Deliverables**:
+  1. Land the complete vNext design specifications (`vnext-overview.md`, `theme-contract.md`, `presets.md`, `motion-system.md`, `signal.md`, `accessibility.md`, `motion-gallery.md`, `deck-layout.md`, `responsive.md`, `regression-testing.md`).
+  2. Document explicit ROADMAP directional reconciliations:
+     - *Repeating Motion Scheduler vs Perf Budget*: Introducing a multi-cadence scheduler that drops to strict 0 FPS when idle, perfectly aligning with performance and low CPU usage requirements.
+     - *Deck Scope*: Formalizing the Deck as a multi-route `ctx.ui.custom` modal overlay, upholding the "no third control surface" and "no live footer mouse" principles.
+- **Done When**: All design documents are committed, cross-referenced in `docs/index.md` and `ROADMAP.md`, with zero runtime code changes in `src/`.
+
+---
+
+### PR 1 — Motion Engine (Core Foundation) — landed
+
+- **Branch**: `vnext/01-motion-engine`
+- **Shipped as**: `src/motion/{types,catalog,policy,frames,scheduler,index}.ts`, `tests/motion-engine.test.ts` (25 tests)
+- **Note**: `MotionScheduler` takes an injectable timer factory (defaulting to `createCoalescingTimer`) and an injectable clock, which is how the 0 FPS lifecycle is asserted without real timers. The router is `channelsForEvent` / `allowedChannels` rather than a separate class.
+- **Scope & Deliverables**:
+  1. Create `src/motion/` subsystem.
+  2. Implement `MotionScheduler`: generalises single-shot coalescing timers into a unified repeating loop supporting per-consumer cadences:
+     - Micro-spinner / Glyphs: `80–120ms`
+     - Signal Sweep: `80–120ms`
+     - Ambient Idle: `250–750ms`
+     - Finite Success / Burst: `250–500ms` total duration
+  3. Strict **0 FPS Idle Guarantee**: When no active animations or consumer subscriptions exist, timers are cleared and CPU usage is 0%.
+  4. Type Definitions:
+     - `MotionEvent`: `"idle" | "thinking" | "streaming" | "tool.start" | "tool.end" | "idea.capture" | "skill.insert" | "policy.deny" | "repair" | "compact" | "success" | "warning" | "error"`
+     - `MotionChannel`: `"workingGlyph" | "signal" | "deckTransient" | "panelIndicator" | "borderEmphasis" | "ambient"`
+  5. `MotionRouter`: Routes semantic events to active visual channels.
+  6. Data-driven `MotionDef` schema supporting both frame arrays and procedural generators (orbit, breathe, wave, bloom, relay).
+- **Done When**: Unit tests verify frame calculations, cadence throttling, event dispatch, and 0 FPS idle lifecycle without relying on `ctx.ui`.
+
+---
+
+### PR 2 — Semantic Design Tokens (Crush Pattern) — landed
+
+- **Branch**: `vnext/02-tokens`
+- **Shipped as**: `WishcraftTokens` in `src/config/types.ts`, mapping and resolution in `src/config/tokens.ts`, wired through `src/extension/core/segment-context.ts`, `tests/tokens.test.ts` (10 tests)
+- **Notes**: the token file lives under `src/config/` rather than `src/theme/` so it sits beside `PresetDef` and keeps `madge --circular` clean. Pi's four `thinking*` colors pass through untokenised; they belong to Pi's thinking levels, not the Wishcraft palette. `DEFAULT_TOKENS` reproduce `getDefaultColors()` exactly, which is asserted by test.
+- **Scope & Deliverables**:
+  1. Introduce `WishcraftTokens` structure:
+     - Surfaces: `surface`, `surfaceRaised`
+     - Typography: `text`, `textMuted`
+     - Brand / Accent: `primary`, `secondary`, `accent`
+     - Feedback / State: `success`, `warning`, `error`
+     - Interaction: `focus`, `selection`
+     - Motion: `motionDim`, `motionHot`, `motionTrail`
+  2. Map legacy `SemanticColor` keys (`model`, `gitClean`, `gitDirty`, `context`, `cost`, `queue`, `border`) to `WishcraftTokens` with 100% backward compatibility.
+  3. Ensure `ColorValue` continues supporting both Pi native `ThemeColor` tokens and custom `#hex` codes.
+- **Done When**: All color resolution routes through the token layer with zero visual regressions across all legacy preset color configurations.
+
+---
+
+### PR 3 — Structural Preset Contract & 10 Signature Presets — landed
+
+- **Branch**: `vnext/03-preset-contract`
+- **Impacted Paths**: `src/config/types.ts`, `src/config/structural-presets.ts`, `src/config/appearance.ts`, `tests/structural-presets.test.ts`
+- **Scope & Deliverables**:
+  1. Extend `PresetDef` with optional structural specifications: `tokens`, `chrome`, `signal`, `motion`, `deck`, `welcome`, `glyphs`.
+  2. Implement the **10 Structural Presets**:
+     - **Lanternwake** (Default Wishcraft Identity): Warm amber/ember tones, rounded frames, powerline separators, ember breathe motion.
+     - **Threadbound**: Woven craft aesthetic, indigo palette, knot separators (`╼·╾`), stitch travel motion.
+     - **Scryglass**: Glass/lens instruments, cyan/violet capsule segments (`╭ ╮`), refraction sweep motion.
+     - **Runebloom**: Organic alchemical sigils, gold/moss tones, sparse anchors, finite event bloom motion.
+     - **Moonwell**: Lunar night arcs (`◜◝◞◟`), silver/navy palette, lunar orbit breathe motion.
+     - **Hexforge**: Industrial heavy block geometry (`█`, `⬡`), heat orange palette, heat propagation motion.
+     - **Vellum**: Editorial grimoire, parchment/ink tones, borderless line reveal motion.
+     - **Wisp**: Minimal ethereal whitespace, mist grey/ice blue, phase drift ambient motion.
+     - **Starweave**: Celestial constellation nodes (`✦╲╱`), star separators, path traversal motion.
+     - **Crucible**: Liquid alchemical cells (`░▒▓█`), obsidian/magma palette, liquid level rise motion.
+  3. Ensure complete decoupling: Users can mix base preset + signal layout + palette + motion language + glyph sets.
+- **Done When**: All 10 presets are registered, tested for correct fallback handling (Nerd vs ASCII), and verified alongside the 7 legacy presets.
+
+---
+
+### PR 4 — Animated Signal (Powerline vNext) — landed
+
+- **Branch**: `vnext/04-signal`
+- **Impacted Paths**: `src/signal/*`, `src/extension/ui/status-line-renderers.ts`, `src/extension/session/session-lifecycle.ts`, `src/extension/commands/commands.ts`, `tests/signal.test.ts`
+- **Scope & Deliverables**:
+  1. Re-architect the powerline renderer into **Signal**: a motion-aware, 3-lane powerline:
+     - **Left Lane**: Model & Git status
+     - **Center Lane**: Live activity & tool state
+     - **Right Lane**: Context window usage & command queue
+  2. Connect Signal rendering to `MotionScheduler`: animated sweeps (e.g. traveling pulse or heat relay) only trigger during active streaming or tool execution.
+  3. Register `/signal` as the primary preferred command while maintaining `/powerline` as a transparent compatibility alias.
+  4. Preserve strict per-segment error boundary and fault isolation.
+- **Done When**: The live powerline animates smoothly during active agent work, immediately rests at 0 FPS when idle, and preserves all segment fallback safeguards.
+
+---
+
+### PR 5 — The Wishcraft Deck (Unified Control Surface) — landed
+
+- **Branch**: `vnext/05-deck`
+- **Impacted Paths**: `src/extension/ui/deck/*`, `src/extension/commands/commands.ts`, `src/extension/settings/wishcraft-config.ts`, `tests/deck.test.ts`
+- **Scope & Deliverables**:
+  1. Build the unified Deck overlay engine (`src/extension/ui/deck/`) using `ctx.ui.custom`.
+  2. Bind `Alt+P` and `/wishcraft` to `openWishcraftDeck("home")`.
+  3. Implement deep links: `/signal`, `/skills`, `/skills doctor`, `/ideas`, `/usage` routes.
+  4. Build Deck Routes:
+     - **Home**: Live session state, animated pulse, context percentage bar, next intent card, activity feed, skills health overview (no raw cost counters or static percentage grids).
+     - **Signal**: Powerline lane and module configuration.
+     - **Skills**: Skill catalog and diagnostics.
+     - **Ideas**: Captured thoughts and intent notes.
+     - **Guardrails**: Safety policy toggles and log history.
+     - **Shell**: Terminal environment & tooling diagnostics.
+     - **Usage**: Context and session metrics.
+     - **Appearance**: Preset, palette, and chrome controls.
+     - **Motion**: Animation settings and gallery trigger.
+     - **Shortcuts**: Fast keyboard navigation reference.
+     - **Diagnostics**: Health check and terminal capability inspector.
+  5. Employ a single continuous outer border frame with shared navigation headers, search inputs, modal pickers, preview cards, and key hints (no cheap nested cards).
+- **Done When**: `Alt+P` opens the full Deck with responsive route switching, keyboard shortcuts (`g s`, `g i`, `/`, `Esc`), and smooth rendering.
+
+---
+
+### PR 6 — Appearance Route, Motion Gallery & Composer — landed
+
+- **Branch**: `vnext/06-appearance`
+- **Impacted Paths**: `src/extension/ui/deck/routes/appearance.ts`, `src/extension/settings/wishcraft-config.ts`, `src/motion/gallery/*`, `tests/appearance/*`
+- **Scope & Deliverables**:
+  1. Appearance sub-routes: `Presets`, `Palette`, `Signal`, `Motion`, `Glyphs`, `Layout`, `Accessibility`.
+  2. **Motion Gallery**: Interactive catalog covering 50+ definitions grouped into:
+     - `Wishcraft` (Ember, Wisp, Bloom, Relay)
+     - `Matrix` (Lemniscate, Lunar, Wing, Petal)
+     - `Procedural` (Helix, Orbit, Ripple, Wave)
+     - `Classic` (Braille, Quarter, Bar, Bounce)
+     - `Favorites` & `Custom`
+  3. **Motion Composer**: Interactive tool to preview and tweak frame arrays, generator parameters (radius, trail, interval, easing), and assign motions to semantic channels.
+  4. Replace flat settings lists with **Fuzzy Search Configurator** (`/ appearance search`).
+  5. Live-reload on all configuration mutations.
+- **Done When**: Users can search any setting, preview motions in real time, customize animations, and save settings instantly.
+
+---
+
+### PR 7 — First-Class Accessibility & Fallbacks — landed
+
+- **Branch**: `vnext/07-accessibility`
+- **Impacted Paths**: `src/motion/accessibility.ts`, `src/theme/detect.ts`, `src/theme/icons.ts`, `tests/accessibility/*`
+- **Scope & Deliverables**:
+  1. Comprehensive Motion Levels:
+     - `Full`: Continuous sweeps, ambient glows, micro-spinners, and transitions.
+     - `Reduced`: Continuous motion disabled; replaced with instantaneous discrete state updates.
+     - `Functional Only`: State-critical indicators enabled; decorative ambient effects disabled.
+     - `Off`: Completely disables all repeating animations (0 FPS permanent).
+  2. Environment Degradation Modes:
+     - `NO_COLOR`: Disables ANSI color codes while retaining glyph animations and spacing.
+     - `Screen Reader Mode`: Motion disabled; delivers stable, high-contrast text strings.
+     - `Non-Truecolor / 8-Color Terminals`: Automatic palette quantization with ASCII glyph fallback.
+  3. Closes ROADMAP P1 Gap #4.
+- **Done When**: Automated test suites verify compliant rendering under `NO_COLOR=1`, `TERM=dumb`, reduced-motion flags, and ASCII-only terminals.
+
+---
+
+### PR 8 — Skill Workbench, wishcraft-tui Skill & Complete Docs — landed
+
+- **Branch**: `vnext/08-craft-docs`
+- **Impacted Paths**: `src/extension/skills/*`, `skills/wishcraft-tui/*`, `README.md`, `docs/*`, `ROADMAP.md`
+- **Scope & Deliverables**:
+  1. Upgrade Skill Manager into a full **Skill Workbench**:
+     - Detailed split-pane layout: List + Metadata + Health checks + Usage sparklines + Content preview.
+     - Inline Creation Wizard on `N` (guided metadata, triggers, and boilerplate).
+  2. Create `skills/wishcraft-tui/` project skill:
+     - `SKILL.md`
+     - Comprehensive reference catalog (`references/product-language.md`, `deck-layout.md`, `signal.md`, `motion-system.md`, `motion-gallery.md`, `theme-contract.md`, `accessibility.md`, `responsive.md`, `regression-testing.md`).
+  3. Update `README.md`, `docs/commands.md`, `docs/configuration.md`, and `ROADMAP.md` reflecting the new architecture and milestone completion.
+- **Done When**: The skill workbench is fully interactive, the AI skill is bundled and functional, and all documentation is complete and consistent.

package/docs/index.md

@@ -12,6 +12,24 @@ The README is the public landing page (`banner.png` only). Everything below live
 - [Working vibes](./working-vibes.md) — themed loading messages, modes, and configuration.
 - [Segments & theming](./segments.md) — segment reference, separators, thinking/path/git options, and theme overrides.
 
+## Design System & vNext Specifications
+
+- [vNext Stacked PR Release Plan](./design/vnext-release-plan.md) — The comprehensive implementation roadmap covering PR0 through PR8.
+- [vNext Architecture & Overview](./design/vnext-overview.md) — Product vision, five pillars, and architectural boundaries.
+- [Semantic Tokens & Theme Contract](./design/theme-contract.md) — `WishcraftTokens` schema and backward compatibility mappings.
+- [Ten Structural Presets](./design/presets.md) — Full catalog of signature structural presets (*Lanternwake*, *Threadbound*, *Scryglass*, etc.).
+- [Semantic Motion Engine](./design/motion-system.md) — Event-driven motion specifications, 0 FPS idle guarantee, channel matrix, and cadences.
+- [Signal — Animated Powerline](./design/signal.md) — 3-lane powerline architecture, live sweeps, and fault-isolated segments.
+- [Wishcraft Deck Layout](./design/deck-layout.md) — Continuous outer surface design, route catalog, deep links, and navigation ergonomics.
+- [Motion Gallery & Composer](./design/motion-gallery.md) — Animation catalog categories and real-time motion authoring specifications.
+- [Accessibility & Fallbacks](./design/accessibility.md) — Motion sensitivity levels, `NO_COLOR` compliance, and universal ASCII degradation.
+- [Responsive Layouts](./design/responsive.md) — Viewport width breakpoints and dynamic height constraints.
+- [Regression Testing](./design/regression-testing.md) — Pure-function unit test strategies, golden ANSI snapshots, and quality gates.
+
+## Core Skills
+
+- [Wishcraft TUI Skill](../skills/wishcraft-tui/SKILL.md) — Engineering guide and design rules for building Wishcraft components.
+
 ## Planning
 
-- [ROADMAP.md](../ROADMAP.md) — release campaigns and leftover 0.20 / 1.0 work.
+- [ROADMAP.md](../ROADMAP.md) — Release campaigns, remaining maturity gaps, and vNext stacked PR roadmap.

package/docs/segments.md

@@ -9,7 +9,7 @@
 
 ### Open-port process owners
 
-Open the segment detail view (`alt+p` → Navigate → `open_ports` → `→`) to see **which process owns each listening port**. It best-effort parses `ss -tulnp` (falling back to `netstat -tulnp`), so the row list shows `tcp:3000 → node (12345)` per port; a port without a visible owner is marked `(unknown)`. The result is cached for 2 seconds so opening detail stays cheap. The full `alt+i` ports list shows the raw `ss -p` process column as well.
+`alt+p` opens the Wishcraft Deck. The classic Navigate / Configure / Status menu is `/signal menu`. Open the segment detail view (`/signal menu` → Navigate → `open_ports` → `→`) to see **which process owns each listening port**. It best-effort parses `ss -tulnp` (falling back to `netstat -tulnp`), so the row list shows `tcp:3000 → node (12345)` per port; a port without a visible owner is marked `(unknown)`. The result is cached for 2 seconds so opening detail stays cheap. The full `alt+i` ports list shows the raw `ss -p` process column as well.
 
 ### Fleet open-ports (SSH probe)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.0.5",
-  "description": "Wishcraft cockpit for the pi coding agent — powerline status, vibes, idea inbox, bash mode, and full customization.",
+  "version": "1.2.0",
+  "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [
     "*.ts",
@@ -25,7 +25,12 @@
     "powerline",
     "status-bar",
     "extension",
-    "groeponline"
+    "groeponline",
+    "terminal-ui",
+    "developer-tools",
+    "agent-ui",
+    "productivity",
+    "hooks"
   ],
   "publishConfig": {
     "access": "public",
@@ -45,14 +50,16 @@
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test tests/**/*.test.ts",
     "release": "node scripts/release.mjs",
-    "prepublishOnly": "tsc --noEmit && node scripts/verify-package.mjs",
-    "verify:package": "node scripts/verify-package.mjs",
-    "circular": "madge --circular src index.ts bash-mode queue"
+    "prepublishOnly": "tsc --noEmit && node scripts/verify-package.mjs && npm run verify:pi-package",
+    "verify:package": "node scripts/verify-package.mjs && node scripts/verify-pi-package-contract.mjs",
+    "circular": "madge --circular src index.ts bash-mode queue",
+    "preview": "node --experimental-strip-types scripts/preview.mjs",
+    "verify:pi-package": "node scripts/verify-pi-package-contract.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.81.0 <0.85.0",
-    "@earendil-works/pi-coding-agent": ">=0.81.0 <0.85.0",
-    "@earendil-works/pi-tui": ">=0.81.0 <0.85.0"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",