@groeponline/pi-wishcraft 1.1.0 → 1.2.0

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.

package/docs/design/signal.md

@@ -0,0 +1,68 @@
+# Signal — The Animated Powerline Specification
+
+## Overview
+
+**Signal** is Wishcraft's animated powerline. While previous terminal footers were static rows of plain text, Signal turns status into an informative, living track.
+
+- **Primary Command**: `/signal` (opens the Signal configuration deck or toggles view modes).
+- **Compatibility Alias**: `/powerline` (retained for backward compatibility).
+
+---
+
+## 3-Lane Architecture
+
+Signal divides status information into three distinct, customizable lanes:
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│ LEFT LANE                    CENTER LANE                    RIGHT LANE           │
+│ Model · Git Status           Live Activity & Tools          Context · Queue      │
+├──────────────────────────────┼──────────────────────────────┼────────────────────┤
+│ ◆ GPT-5.6 ╾━━━━ main ━━━━    │ ╾✦╼━━━━ read_file ━━━━━━━    │ ctx █████░ 47%     │
+└──────────────────────────────┴──────────────────────────────┴────────────────────┘
+```
+
+1. **Left Lane (Identity & Workspace)**
+   - Active Model badge (with provider color accent)
+   - Git branch and repository clean/dirty status
+   - Workspace directory (truncated gracefully on compact displays)
+
+2. **Center Lane (Live Activity & Motion)**
+   - Current agent state (Thinking, Streaming, Tool Execution)
+   - Active tool call indicator (`read_file`, `grep`, `execute_command`)
+   - Traveling motion pulse representing data throughput
+
+3. **Right Lane (Metrics & Session)**
+   - Context window progress bar and percentage
+   - Queued user/agent instructions count
+   - Session cost / token consumption (if enabled)
+
+---
+
+## Live Motion Sweeps
+
+Signal animates only when actual work is being processed. The track reflects execution states through traveling pulses:
+
+### Token Streaming Wave
+```
+t0:  ◆ GPT-5.6 ╾▓▒░━━━━ main ━━━━━━━━━ read ━━━━━━━━━ ctx 47%
+t1:  ◆ GPT-5.6 ━╾▓▒░━━━ main ━━━━━━━━━ read ━━━━━━━━━ ctx 47%
+t2:  ◆ GPT-5.6 ━━━╾▓▒░━ main ━━━━━━━━━ read ━━━━━━━━━ ctx 47%
+t3:  ◆ GPT-5.6 ━━━━━━━━ main ╾▓▒░━━━━━ read ━━━━━━━━━ ctx 47%
+```
+
+### Tool Execution Traveling Pulse
+```
+t0:  read ━━━╾✦╼━━━ grep ━━━━━━━━━ edit ━━━━━━━━━
+t1:  read ✓ ━━━━━━━ grep ━━━╾✦╼━━━ edit ━━━━━━━━━
+t2:  read ✓ ━━━━━━━ grep ✓ ━━━━━━━ edit ━━━╾✦╼━━━
+```
+
+---
+
+## Fault Isolation & Error Boundaries
+
+Signal builds on Pi-Wishcraft's existing segment architecture:
+- Every segment executes in an isolated `try/catch` wrapper.
+- If an individual segment fails (e.g. git command timeout or unexpected API response), it degrades gracefully to a silent fallback or a compact warning glyph without crashing the surrounding status line.
+- Segment separators adjust dynamically when neighboring segments are hidden or empty.