@groeponline/pi-wishcraft 1.1.0 → 1.3.0

package/docs/design/accessibility.md

@@ -0,0 +1,71 @@
+# First-Class Accessibility & Graceful Degradation
+
+## Overview
+
+Terminal environments vary drastically—from modern GPU-accelerated terminals with full truecolor and Nerd Font glyphs to low-bandwidth SSH sessions, restricted 8-color virtual consoles, and screen readers.
+
+Wishcraft treats accessibility and environmental adaptability as first-class architectural constraints, directly resolving ROADMAP P1 Gap #4.
+
+---
+
+## Motion Levels
+
+Users can configure global motion sensitivity via settings or keyboard shortcuts:
+
+```
+Motion Sensitivity:
+(●) Full              - Continuous sweeps, micro-spinners, and transitions
+( ) Reduced           - Instant state changes; continuous loops replaced by static glyphs
+( ) Functional Only   - Task indicators active; decorative ambient motion disabled
+( ) Off               - 100% static display; zero animated frames
+```
+
+---
+
+## Environment Degradation Matrix
+
+```
+┌───────────────────┬───────────────────┬───────────────────┬────────────────────┐
+│ ENVIRONMENT       │ MOTION BEHAVIOR   │ COLOR PALETTE     │ GLYPH RENDERING    │
+├───────────────────┼───────────────────┼───────────────────┼────────────────────┤
+│ Modern Truecolor  │ Full FPS & Sweeps │ True 24-bit RGB   │ Full Nerd Fonts    │
+│ Standard 256 Color│ Full FPS & Sweeps │ ANSI-256 Mapped   │ Unicode / Nerd     │
+│ Basic 8/16 Color  │ Simplified Pulse  │ Basic ANSI        │ Clean ASCII        │
+│ NO_COLOR Set      │ Glyphs Active     │ No ANSI Escapes   │ Unicode / ASCII    │
+│ prefers-reduced   │ Discrete States   │ Full Color        │ Standard Glyphs    │
+│ Screen Reader     │ Disabled (0 FPS)  │ High Contrast     │ Descriptive Text   │
+└───────────────────┴───────────────────┴───────────────────┴────────────────────┘
+```
+
+---
+
+## Concrete Degradation Policies
+
+### 1. `NO_COLOR` Compliance
+When the `NO_COLOR` environment variable is detected:
+- All ANSI color codes and RGB background styling are stripped.
+- Spatial layout, separators, and glyph animations remain active to convey status through structure.
+
+### 2. `prefers-reduced-motion`
+When reduced motion is requested by the OS or user configuration:
+- Continuous sweeps along the Signal track are disabled.
+- Spinners transition immediately to static state markers (`[..]`, `[ok]`, `[!]`).
+- Transient notifications appear statically without fade-in or slide-in transitions.
+
+### 3. Screen Reader Mode
+- Motion engine is completely stopped (0 FPS).
+- Powerline separators and visual spacers are suppressed.
+- Status is formatted as clean, semantic plain text (e.g. `Model: GPT-5.6 | Git: main (clean) | State: Streaming | Context: 47%`).
+
+### 4. ASCII Fallback Strategy
+Every custom Unicode icon and Nerd Font symbol provides a guaranteed 1-to-1 ASCII equivalent:
+
+| Semantic Icon | Nerd Font Glyph | Unicode Default | ASCII Fallback |
+| :--- | :--- | :--- | :--- |
+| Model | `󰚩` | `◈` | `[*]` |
+| Git Branch | `` | `⎇` | `branch:` |
+| Git Clean | `✔` | `✓` | `ok` |
+| Git Dirty | `✎` | `⚡` | `*` |
+| Streaming | `󱐋` | `✦` | `~` |
+| Tool Call | `󰒓` | `◆` | `>` |
+| Error | `󰅚` | `✗` | `ERR` |

package/docs/design/deck-layout.md

@@ -0,0 +1,69 @@
+# Deck Layout & Interactive Route Architecture
+
+## Overview
+
+The **Wishcraft Deck** (`Alt+P` / `/wishcraft`) is the central control surface for the agent operator. It replaces fragmented menus with a cohesive, keyboard-first modal overlay built inside `ctx.ui.custom`.
+
+---
+
+## The Continuous Surface Design
+
+Unlike cheap TUIs that stack boxes inside boxes with conflicting borders, the Deck utilizes a **single continuous outer frame** partitioned into an ambient header, the active route viewport, and a contextual footer.
+
+```
+╭────────────────────────────── WISHCRAFT DECK ──────────────────────────────╮
+│ ◈ GPT-5.6 HIGH        main +12      context 47%        ◆ STREAMING         │
+├──────────────┬──────────────────────────────────────┬───────────────────────┤
+│ NAVIGATION   │ ACTIVE ROUTE: HOME                   │ ACTIVITY FEED         │
+│              │                                      │                       │
+│ ◉ Home       │  CURRENT SESSION                     │ 21:16 read_file       │
+│ ◆ Signal     │  ◆ Streaming response                │ 21:16 grep_pattern    │
+│ ◇ Skills  27 │  ━━━━╾✦╼━━━━━━━━━━━━                 │ 21:15 skill.load      │
+│ ◇ Ideas    4 │                                      │                       │
+│ ◇ Guardrails │  Context Capacity                    │ SKILLS HEALTH         │
+│ ◇ Shell      │  ████████░░░░░ 47% (94k / 200k)      │ ✓ 25 healthy          │
+│ ◇ Usage      │                                      │ !  2 warnings         │
+│ ◇ Appearance │  NEXT INTENT                         │                       │
+│ ◇ Motion     │  Improve Signal motion engine        │ GUARDRAILS            │
+│ ◇ Shortcuts  │  [Run]  [Open Skill]  [Review]       │ Policy: STRICT (Enf)  │
+├──────────────┴──────────────────────────────────────┴───────────────────────┤
+│ / Search     g s Skills     g i Ideas     ? Help     Esc Close Deck         │
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+---
+
+## Route Catalog & Deep Links
+
+| Route | Deep Link Command | Purpose & Main Components |
+| :--- | :--- | :--- |
+| **`Home`** | `/wishcraft` / `Alt+P` | Live session overview, intent card, context bar, recent activity stream. |
+| **`Signal`** | `/signal` | Visual powerline editor, lane assignments, separator picker. |
+| **`Skills`** | `/skills` | Skill catalog, inline creation wizard, health diagnostics. |
+| **`Skills Doctor`**| `/skills doctor` | Deep validation of skill frontmatter, descriptions, and triggers. |
+| **`Ideas`** | `/ideas` | Rapid capture and organization of intent notes and future tasks. |
+| **`Guardrails`** | `/guardrails` | Safety policies, denial logs, execution boundaries. |
+| **`Shell`** | `/shell` | Execution environment inspect, tool binary availability. |
+| **`Usage`** | `/usage` | Detailed token statistics and context window metrics. |
+| **`Appearance`**| `/appearance` | Preset picker, semantic token overrides, layout density. |
+| **`Motion`** | `/motion` | Motion Gallery, Composer, accessibility sensitivity sliders. |
+| **`Shortcuts`** | `/shortcuts` | Keyboard navigation and jump-mode cheat sheet. |
+| **`Diagnostics`**| `/diagnostics` | Terminal capabilities, color support, and encoding checks. |
+
+---
+
+## Navigation Ergonomics
+
+Wishcraft combines **Posting-style jump shortcuts** with a fast **fuzzy command palette**:
+
+1. **Global Jump Keys**:
+   - `g h` $\rightarrow$ Jump to Home
+   - `g s` $\rightarrow$ Jump to Skills
+   - `g i` $\rightarrow$ Jump to Ideas
+   - `g a` $\rightarrow$ Jump to Appearance
+   - `g m` $\rightarrow$ Jump to Motion
+2. **Fuzzy Search Palette (`/`)**:
+   - Typing `/` anywhere in the Deck opens the instant search bar.
+   - Matches routes, config keys, actions, and skills with real-time highlighted filtering.
+3. **Key Hints**:
+   - The footer always renders context-relevant shortcuts, eliminating the need to memorize keybindings.

package/docs/design/motion-gallery.md

@@ -0,0 +1,80 @@
+# Motion Gallery & Composer Specification
+
+## Overview
+
+The **Motion Gallery** provides an interactive catalog of animations categorized across curated styles. The **Motion Composer** allows developers and power users to author, preview, and assign custom motion definitions directly inside the terminal interface.
+
+---
+
+## Gallery Categories
+
+```
+╭─ Motion Gallery ─────────────────────────────────────────────────────────────╮
+│ / Search motions (e.g. "lunar", "sweep", "ember")                             │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ Wishcraft         Matrix          Procedural        Classic        Custom    │
+│                                                                              │
+│ ◈ Ember Relay     ∞ Lemniscate    ⠿ Helix Phase     ⠋ Braille      ✦ User-1  │
+│ ◇ Wisp Drift      ◎ Lunar Orbit   ≋ Wave Stream     ◐ Quarter                │
+│ ✦ Sigil Bloom     △ Wing Pulse    ⡿ Orbital Spin   ▏ Bar Fill               │
+│ ⬡ Heat Propagate  ✧ Petal Shimmer ≋ Ripple Surface  ● Bounce                 │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ PREVIEW:                                                                     │
+│                                                                              │
+│                 ━━━━━━╾✦╼━━━━━━━━━━━━━                                       │
+│                          → 90ms                                              │
+│                                                                              │
+│ Channels: [✓] Working Glyph   [✓] Signal Track   [ ] Transient   [✓] Task    │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ Space Play/Pause   E Edit in Composer   D Duplicate   F Favorite   Enter Apply│
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+### 1. Wishcraft (Signature Metaphors)
+- `ember-relay`: Traveling spark across segmented track.
+- `wisp-drift`: Subtle breathing glyph with gentle phase oscillation.
+- `sigil-bloom`: Expanding concentric geometry that settles upon completion.
+- `heat-propagate`: Thermal matrix diffusion across block elements.
+
+### 2. Matrix (Geometrical & Celestial)
+- `lemniscate`: Infinity figure-eight traversal.
+- `lunar-orbit`: Sinusoidal orbital node path.
+- `wing-pulse`: Dual metronome oscillation.
+- `petal-shimmer`: Expanding and contracting radial points.
+
+### 3. Procedural (Fluid & Wave Mechanics)
+- `helix-phase`: Intertwined dual-strand cycle.
+- `wave-stream`: Progressive sine wave amplitude sweep.
+- `ripple-surface`: Concentric wavefront propagation.
+
+### 4. Classic (Reliable Terminal Spinners)
+- `braille-cycle`: Canonical 8-dot Braille loop (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`).
+- `quarter-circle`: Rotating four-quadrant glyphs (`◐◓◑◒`).
+- `bar-fill`: Smooth horizontal bar progression (`▏▎▍▌▋▊▉█`).
+
+---
+
+## Motion Composer
+
+The Composer enables real-time parameter tweaking and frame array authoring:
+
+```
+╭─ Motion Composer: Ember Relay ───────────────────────────────────────────────╮
+│ TIMELINE                                                                     │
+│ 0ms          90ms         180ms        270ms        360ms                    │
+│ ├───◇──────────├───◈──────────├───◆──────────├───◈──────────├───◇────────────│
+│                                                                              │
+│ PARAMETERS                                                                   │
+│ Geometry:        Linear Track (1D)                                           │
+│ Interval:        90 ms                                                       │
+│ Direction:       Forward (→)                                                 │
+│ Easing:          Sinusoidal Pulse                                            │
+│ Color Role:      motionHot (#fbbf24)                                         │
+│ Fallback Glyph:  ◆                                                           │
+│                                                                              │
+│ ASSIGNED CHANNELS                                                            │
+│ [*] Working Glyph   [*] Signal Track   [ ] Border   [*] Task Status          │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ Ctrl+S Save   Tab Next Field   Space Test   Esc Discard                      │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```

package/docs/design/motion-system.md

@@ -0,0 +1,119 @@
+# Semantic Motion Engine & Scheduler
+
+## Architectural Invariants
+
+1. **Centralized Dispatch**: Components never launch ad-hoc `setInterval()` loops. All rendering cadences are driven by a single `MotionScheduler`.
+2. **0 FPS Idle Guarantee**: When no animations or active consumers exist, timers are torn down completely. CPU usage is strictly 0%.
+3. **Semantic Event Driven**: Animations are triggered by semantic agent lifecycle events (`streaming`, `tool.start`, `policy.deny`), not arbitrary frame tickers.
+4. **Pure Function Calculations**: Motion algorithms, frame interpolations, and physics math are pure, unit-testable functions independent of the TUI renderer.
+
+---
+
+## Semantic Motion Events
+
+```typescript
+export type MotionEvent =
+  | "idle"           // System at rest
+  | "thinking"       // Agent formulating response
+  | "streaming"      // Token output active
+  | "tool.start"     // Invoking external tool
+  | "tool.end"       // Tool execution resolved
+  | "idea.capture"   // Intent/Idea logged to deck
+  | "skill.insert"   // Skill inserted into editor
+  | "policy.deny"    // Action blocked by guardrail
+  | "repair"         // Healing or recovering from error
+  | "compact"        // Context window compaction
+  | "success"        // Task completed successfully
+  | "warning"        // Approaching threshold/warning
+  | "error";         // Exception or fatal failure
+```
+
+---
+
+## Output Channels & Event Routing Matrix
+
+There are six independent visual output channels:
+- **`workingGlyph`**: Spinner or working status glyph in the prompt / header.
+- **`signal`**: Animated track in the powerline.
+- **`deckTransient`**: Ephemeral banner or toast inside the Deck overlay.
+- **`panelIndicator`**: Localized progress indicator in active sub-panels.
+- **`borderEmphasis`**: Transient glow or color pulse along outer frame borders.
+- **`ambient`**: Subtle low-frequency breath when explicitly enabled.
+
+```
+┌───────────────┬──────────────┬──────────────┬───────────────┬─────────────────┬─────────────────┬───────────┐
+│ EVENT         │ WORKING GLYPH│ SIGNAL ANIM  │ DECK TRANSIENT│ PANEL INDICATOR │ BORDER EMPHASIS │ AMBIENT   │
+├───────────────┼──────────────┼──────────────┼───────────────┼─────────────────┼─────────────────┼───────────┤
+│ idle          │ —            │ —            │ —             │ —               │ —               │ ● (Opt)   │
+│ thinking      │ ● Pulse      │ ● Dim Sweep  │ —             │ —               │ —               │ —         │
+│ streaming     │ ● Active     │ ● Hot Sweep  │ —             │ ● Token Flow    │ —               │ —         │
+│ tool.start    │ ● Working    │ ● Segment Run│ —             │ ● Tool Status   │ —               │ —         │
+│ tool.end      │ —            │ ● Settle     │ —             │ ● Checkmark     │ —               │ —         │
+│ idea.capture  │ —            │ —            │ ● "+1 Idea"   │ —               │ —               │ —         │
+│ skill.insert  │ —            │ ● Edge Jump  │ ● Toast       │ —               │ —               │ —         │
+│ policy.deny   │ —            │ —            │ ● Blocked Card│ —               │ ● Error Flash   │ —         │
+│ repair        │ ● Spinner    │ —            │ ● Recovery    │ ● Diagnostic    │ —               │ —         │
+│ compact       │ ● Compress   │ ● Shrink Bar │ ● Compact Msg │ ● Context Bar   │ —               │ —         │
+│ success       │ —            │ ● Bloom (Fin)│ ● Done Banner │ —               │ ● Success Flash │ —         │
+│ warning       │ —            │ —            │ ● Warning Card│ —               │ ● Warn Flash    │ —         │
+│ error         │ —            │ —            │ ● Error Modal │ —               │ ● Error Flash   │ —         │
+└───────────────┴──────────────┴──────────────┴───────────────┴─────────────────┴─────────────────┴───────────┘
+```
+
+---
+
+## Channel Cadences & Scheduler Design
+
+Different visual elements operate at distinct frame rates to optimize visual clarity while conserving system resources:
+
+| Channel | Target Cadence | Lifecycle |
+| :--- | :--- | :--- |
+| **`workingGlyph`** | `80ms – 120ms` per frame | Active while agent processes |
+| **`signal` Sweep** | `80ms – 120ms` per frame | Active during stream / tool execution |
+| **`panelIndicator`** | `120ms – 250ms` per frame | Active while sub-view is busy |
+| **`borderEmphasis`** | `200ms – 400ms` total burst | Finite (1 to 3 frames) |
+| **`deckTransient`** | `250ms – 500ms` total display | Finite auto-dismissing |
+| **`ambient` Idle** | `250ms – 750ms` per frame | Runs only when explicitly opted-in |
+
+### State Transition Diagram
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle: Initialize
+  Idle --> ActiveMotion: MotionEvent Received (streaming, tool.start)
+  ActiveMotion --> ActiveMotion: Tick registered consumers (80-120ms)
+  ActiveMotion --> FiniteBurst: Success / Error Event
+  FiniteBurst --> Idle: Burst Complete (no consumers)
+  Idle --> [*]: Dispose Scheduler (0 FPS)
+```
+
+---
+
+## Motion Definition Schema (`MotionDef`)
+
+Motions are defined declaratively as pure data structures:
+
+```typescript
+export interface MotionDef {
+  id: string;
+  name: string;
+  category: "wishcraft" | "matrix" | "procedural" | "classic" | "custom";
+  kind: "frames" | "generator";
+  loop: "while-active" | "finite" | "ambient";
+  colorRole: keyof WishcraftTokens;
+  fallbackGlyph: string;
+
+  // Discrete Frame Sequences
+  frames?: string[];
+
+  // Procedural Generator Specification
+  generator?: {
+    geometry: "linear" | "orbit" | "wave" | "bloom" | "liquid";
+    interval: number;
+    trailLength?: number;
+    radius?: number;
+    direction?: "forward" | "reverse" | "pingpong";
+    easing?: "linear" | "sinusoidal" | "exponential";
+  };
+}
+```

package/docs/design/presets.md

@@ -0,0 +1,196 @@
+# Structural Presets Specification
+
+## Overview
+
+Wishcraft introduces **ten signature structural presets**. A preset is not merely a color skin; it defines a complete design system combining:
+1. **Token Palette**: Cohesive semantic colors.
+2. **Chrome Geometry**: Frame borders, corners, divider styles, and density.
+3. **Signal Grammar**: Lane structure, module capsules, separators, and caps.
+4. **Glyph Grammar**: Curated Unicode and Nerd Font iconography with clean ASCII fallbacks.
+5. **Signature Motion**: Procedural animations reflecting the preset's identity.
+
+---
+
+## The Ten Structural Presets
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│ PRESET           CHARACTER                   SIGNAL STRUCTURE       SIGNATURE MOTION   │
+├────────────────────────────────────────────────────────────────────────────────────────┤
+│ 1. Lanternwake   Warm Amber / Signature Dark Fluid Segments         Ember Breathe      │
+│ 2. Threadbound   Woven Craft / Indigo        Thin Knot Wire         Stitch Travel      │
+│ 3. Scryglass     Refractive Glass / Cyan     Capsule Lenses         Refraction Sweep   │
+│ 4. Runebloom     Organic Alchemical Sigils   Sparse Anchors         Sigil Bloom        │
+│ 5. Moonwell      Nocturnal Orbit / Silver    Arc Segments           Lunar Breathe      │
+│ 6. Hexforge      Heavy Industrial Steel      Block Hexagons         Heat Propagation   │
+│ 7. Vellum        Editorial Grimoire          Borderless Line        Writing Reveal     │
+│ 8. Wisp          Ethereal Minimalist         Max Whitespace         Phase Drift        │
+│ 9. Starweave     Celestial Cartography       Constellation Nodes    Path Traversal     │
+│ 10. Crucible     Alchemical Fluid / Magma    Cell Meter Rise        Liquid Surge       │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 1. Lanternwake (Default Signature Identity)
+- **Concept**: Warm amber and glowing embers in a dark room. Grounded in Wishcraft's original lantern metaphor.
+- **Tokens**:
+  - `primary`: `#f59e0b` (Warm Amber)
+  - `accent`: `#ea580c` (Ember Orange)
+  - `surface`: `#0f172a` (Deep Slate)
+  - `motionHot`: `#fbbf24` (Golden Flare)
+  - `motionTrail`: `#78350f` (Ember Ash)
+- **Signal Grammar**:
+  ```
+  ◇ GPT-5.6 ━━━╾✦╼━━━━ main ━━━━━ read ━━━━━ ctx 47%
+  ```
+- **Motion**: `ember.breathe` — utilizes the mathematical formula from `renderLantern` ($\sin(t \times 1.1) + \sin(t \times 7.3)$) to pulse only during active events.
+
+---
+
+### 2. Threadbound
+- **Concept**: Artisan tailoring and woven loom mechanics.
+- **Tokens**:
+  - `primary`: `#6366f1` (Indigo Thread)
+  - `accent`: `#ec4899` (Magenta Stitch)
+  - `surface`: `#18181b` (Zinc Weave)
+- **Signal Grammar**:
+  ```
+  model ──╼·╾──── branch ──╼·╾──── tool ──╼◆╾── context
+  ```
+- **Motion**: `stitch.travel` — step pulse traveling smoothly across thread nodes.
+
+---
+
+### 3. Scryglass
+- **Concept**: Precision optics, lenses, and refractive glass capsules.
+- **Tokens**:
+  - `primary`: `#06b6d4` (Prism Cyan)
+  - `accent`: `#8b5cf6` (Lens Violet)
+  - `surface`: `#090d16` (Deep Glass)
+- **Signal Grammar**:
+  ```
+  ╭ GPT-5.6 ╮────╭ main ╮────╭ read ╮────╭ 47% ╮
+  ╰─────────╯    ╰──────╯    ╰──────╯    ╰─────╯
+  ```
+- **Motion**: `refraction.sweep` — light wave passing through each capsule sequentially.
+
+---
+
+### 4. Runebloom
+- **Concept**: Ancient stone sigils bursting into life upon magic release.
+- **Tokens**:
+  - `primary`: `#10b981` (Emerald Moss)
+  - `accent`: `#eab308` (Rune Gold)
+  - `surface`: `#0c140f` (Forest Granite)
+- **Signal Grammar**:
+  ```
+  ◇  GPT-5.6  ·  main  ·  read  ·  47%
+  ```
+- **Motion**: `bloom.on-event` — geometry expands outwardly on state changes, then stabilizes into quiet repose.
+
+---
+
+### 5. Moonwell
+- **Concept**: Nocturnal sanctuary, silver light, and celestial orbits.
+- **Tokens**:
+  - `primary`: `#94a3b8` (Moon Silver)
+  - `accent`: `#38bdf8` (Starlight Sky)
+  - `surface`: `#020617` (Midnight Black)
+- **Signal Grammar**:
+  ```
+  ◜ GPT-5.6 ─── ◝ main ─── ◞ read ─── ◟ 47%
+  ```
+- **Motion**: `lunar.breathe` — smooth sinusoidal phase transitions echoing orbital mechanics.
+
+---
+
+### 6. Hexforge
+- **Concept**: Heavy forge machinery, steel plating, and thermal conduits.
+- **Tokens**:
+  - `primary`: `#f97316` (Forge Orange)
+  - `accent`: `#ef4444` (Molten Red)
+  - `surface`: `#1c1917` (Anvil Dark)
+- **Signal Grammar**:
+  ```
+  ⬡ GPT-5.6 ▰▰ MAIN ▰▰ ◆ READ ▰▰ 47% ⬡
+  ```
+- **Motion**: `heat.propagate` — thermal wave advancing across block matrices (`█▓▒░`).
+
+---
+
+### 7. Vellum
+- **Concept**: Modern editorial, typography, and calligraphic ink strokes.
+- **Tokens**:
+  - `primary`: `#d97706` (Old Gold Ink)
+  - `accent`: `#a16207` (Deep Sepia)
+  - `surface`: `#1a1815` (Dark Parchment)
+- **Signal Grammar**:
+  ```
+  Wishcraft / GPT-5.6
+  ──────────────────────────────────────╾ main · read · ctx 47%
+  ```
+- **Motion**: `writing.reveal` — rule line draws from left to right during streaming output.
+
+---
+
+### 8. Wisp
+- **Concept**: Minimalist ethereal calm, generous negative space, pure essential information.
+- **Tokens**:
+  - `primary`: `#cbd5e1` (Morning Mist)
+  - `accent`: `#38bdf8` (Ethereal Blue)
+  - `surface`: `#0b0f19` (Void Blue)
+- **Signal Grammar**:
+  ```
+  ◌ GPT-5.6   main · read · 47%
+  ```
+- **Motion**: `phase.drift` — subtle, low-frequency opacity breathing.
+
+---
+
+### 9. Starweave
+- **Concept**: Astrological star maps, navigational geometry, and connected constellations.
+- **Tokens**:
+  - `primary`: `#a855f7` (Cosmic Purple)
+  - `accent`: `#38bdf8` (Nebula Cyan)
+  - `surface`: `#050515` (Deep Space)
+- **Signal Grammar**:
+  ```
+  ✦ GPT-5.6 ───· main ·───◆ read ───✦ 47%
+  ```
+- **Motion**: `path.traverse` — stellar particle moving across intersecting coordinate edges.
+
+---
+
+### 10. Crucible
+- **Concept**: Dynamic alchemical fluid levels, bubbling reactions, and exothermic changes.
+- **Tokens**:
+  - `primary`: `#ec4899` (Alchemical Rose)
+  - `accent`: `#f43f5e` (Catalyst Crimson)
+  - `surface`: `#110b11` (Basalt Stone)
+- **Signal Grammar**:
+  ```
+  [▓▓▓ GPT-5.6] [▒▒ main] [░ read] [█ 47%]
+  ```
+- **Motion**: `liquid.rise` — cell density shifts dynamically in response to token consumption rates.
+
+---
+
+## Decoupled Customization Architecture
+
+Presets represent harmonious default pairings, but Wishcraft allows complete independence across every dimension:
+
+```
+┌────────────────────────────────────────────────────────┐
+│                User Custom Configuration               │
+│                                                        │
+│  Base Preset:       Lanternwake                        │
+│  Signal Layout:     Threadbound                        │
+│  Token Palette:     Scryglass                          │
+│  Working Motion:    Lunar Breathe                      │
+│  Tool Motion:       Heat Propagate                     │
+│  Frame Chrome:      Vellum                             │
+│  Glyph Set:         Nerd Font (Full)                   │
+└────────────────────────────────────────────────────────┘
+```
+No layer is locked; users can selectively override any aspect without fork or code changes.

package/docs/design/regression-testing.md

@@ -0,0 +1,54 @@
+# Automated Regression Testing & TUI Quality Strategy
+
+## Overview
+
+A polished terminal application requires strict regression testing across layout math, animation timelines, token calculations, and ANSI output correctness.
+
+Wishcraft establishes a multi-tiered test strategy that verifies behavior without unstable end-to-end terminal dependencies.
+
+---
+
+## Testing Tiers
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 1. Pure Unit Tests (Fast, 100% Deterministic)         │
+│    - Token color mappings                              │
+│    - Preset resolution & overrides                     │
+│    - Motion frame calculations                         │
+│    - Event router dispatch matrices                    │
+└───────────────────────────┬────────────────────────────┘
+                            │
+┌───────────────────────────▼────────────────────────────┐
+│ 2. Layout & String Geometry Tests                      │
+│    - Grapheme cluster width calculation                │
+│    - Responsive breakpoint truncation                  │
+│    - Box-drawing alignment & corner connections        │
+└───────────────────────────┬────────────────────────────┘
+                            │
+┌───────────────────────────▼────────────────────────────┐
+│ 3. Snapshot & Golden Master Tests                      │
+│    - ANSI escape sequence validation                   │
+│    - 10 Preset layout golden snapshots                 │
+│    - NO_COLOR and ASCII fallback exports               │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Test Automation Invariants
+
+1. **No Headless TUI Requirement**: Core algorithms must never instantiate `ctx.ui` or direct terminal stdout in tests. Renderers emit plain string buffers or token trees.
+2. **Deterministic Time Control**: The `MotionScheduler` accepts an injected virtual clock or step function for precise, millisecond-accurate timeline assertions.
+3. **Circular Dependency Prevention**: Verified automatically on every build via `npx madge --circular src/`.
+4. **Strict TypeScript Checking**: `tsc --noEmit` runs under strict mode with zero implicit `any`.
+
+---
+
+## Golden Test Fixtures
+
+Every signature preset maintains a golden ANSI snapshot for standard viewport dimensions (`120x30`, `80x24`, `50x15`):
+- `tests/fixtures/presets/lanternwake-120x30.snap`
+- `tests/fixtures/presets/scryglass-80x24.snap`
+- `tests/fixtures/presets/hexforge-no-color.snap`
+- `tests/fixtures/presets/vellum-ascii-fallback.snap`

package/docs/design/responsive.md

@@ -0,0 +1,53 @@
+# Responsive Layout & Terminal Viewport Adaptations
+
+## Overview
+
+Terminal viewports vary significantly across devices, window panes, and split layouts. Wishcraft dynamically responds to viewport width and height constraints through intelligent layout degradation.
+
+---
+
+## Responsive Breakpoints
+
+| Viewport Width | Class | Layout Strategy |
+| :--- | :--- | :--- |
+| **$\ge 120$ cols** | **Wide** | Full 3-column Deck (Nav + Main View + Sidebar) + Full 3-Lane Signal |
+| **$80 - 119$ cols**| **Standard**| 2-column Deck (Nav + Main View) + Standard 3-Lane Signal |
+| **$50 - 79$ cols** | **Compact** | 1-column Deck (Collapsible Nav) + Compressed 2-Lane Signal |
+| **$< 50$ cols**    | **Minimal** | Modal Stack Deck + Single-Lane Essential Status |
+
+---
+
+## Signal Lane Degradation
+
+```
+Wide (120+ cols):
+◆ GPT-5.6 ╾━━━━ main (clean) ━━━━╾✦╼━━━━ read_file: src/render/powerline.ts ━━━━━━━ ctx █████░ 47% (94k)
+
+Standard (80-119 cols):
+◆ GPT-5.6 ╾━━━━ main ━━━━╾✦╼━━━━ read_file ━━━━━━━ ctx 47%
+
+Compact (50-79 cols):
+◆ GPT-5.6 ── main ── read ── 47%
+
+Minimal (< 50 cols):
+◆ GPT-5.6 · 47%
+```
+
+---
+
+## Deck Viewport Adaptations
+
+1. **Wide Viewport ($\ge 120$ cols)**:
+   - Navigation pane (20% width)
+   - Route workspace (55% width)
+   - Activity feed & health sidebar (25% width)
+2. **Standard Viewport ($80 - 119$ cols)**:
+   - Sidebar collapses into tabbed secondary panes.
+   - Main workspace expands to utilize 75% width.
+3. **Compact Viewport ($50 - 79$ cols)**:
+   - Top-level route icons replace full text navigation.
+   - Main workspace occupies full width.
+   - Jump shortcuts remain fully active.
+4. **Vertical Constraints ($< 24$ rows)**:
+   - Ambient header and footer padding are compacted to single rows.
+   - Activity stream truncates to most recent 2 events.