@vib3code/sdk 2.0.1 → 2.0.3-canary.91a95f3

package/DOCS/VISUAL_ANALYSIS_TABLESIDE.md

@@ -0,0 +1,86 @@
+# Visual Analysis: tableside.com.au
+
+**Captured: 2026-02-10 via Playwright with wheel-based scrolling**
+**Method**: Real Chromium screenshots at 5 scroll positions (wheel events)
+**Page height**: 8,370px (~9.3x viewport)
+
+---
+
+## Scroll Journey (Frame by Frame)
+
+### s00 — Top (scrollY=0)
+**Bold typography hero with warm palette**
+- Background: warm cream/beige (#F5EDE4 range)
+- "TABLESIDE" logo top-left in coral/orange + "CREATIVES" subscript
+- Hamburger menu (three lines) top-right in coral
+- MASSIVE bold sans-serif text: "FOOD & DRINK DIGITAL CREATIVES" in coral/orange (#E85D3A range)
+- Text fills ~70% of viewport, extremely bold weight (900+), tight line-height
+- Below hero: "HOSPITALITY MARKETING AUSTRALIA" in black, right-aligned
+- "WHAT WE DO" label left side
+- Large body text in coral: "Crafting bold, unforgettable brands through content to propel hospitality and food & beverage businesses towards sustainable growth and standout success."
+- Social links: INSTAGRAM, FACEBOOK, LINKEDIN, TIKTOK — right-aligned, stacked
+- Chat widget bottom-right
+- **Pattern**: Typography-as-hero with strong brand color. The hero text IS the brand statement, rendered in the signature coral color at maximum weight. Social links positioned as a sidebar element right-aligned.
+
+### s01 — scrollY=2400
+**Portfolio card: asymmetric split layout**
+- Large food photography LEFT (~50% viewport width): close-up of artisanal pizza
+- Card text RIGHT: "ROCCELLA EAST MELB" restaurant name + orange icon
+- "WEB, CONTENT, PAID, SOCIAL & EDM" service tags + "+ INFO" link in coral
+- Below: second portfolio card beginning — dark photo of restaurant interior
+- "STEER DINING ROOM" title overlaid on dark photo, bottom-left
+- **Pattern**: Asymmetric portfolio cards. Image takes one half, text the other. The split is ~50/50 with generous spacing. Different cards have different background treatments (light photo vs dark atmospheric photo).
+
+### s02 — scrollY=4800
+**Small dark portfolio card**
+- Dark restaurant interior photo with chefs in white uniforms
+- "WAGYU YA TEPPANYAKI" title overlaid top in white
+- "WEB, CONTENT, PAID, SOCIALS & EDM" service tags bottom-left
+- "YAKIKAMI" title visible below
+- Card appears much smaller than previous cards (~40% viewport height)
+- **Pattern**: Variable card sizing. Not all portfolio cards are the same size. This card is notably smaller and darker than the previous ones, creating visual rhythm through size variation.
+
+### s03 — scrollY=7200
+**CTA section with strong color**
+- Solid coral/orange background filling top ~40% of viewport
+- "READY TO TAKE A SEAT AT OUR TABLE?" in large white text, centered
+- "BOOK FREE STRATEGY SESSION" button: white border on coral background, centered
+- Below CTA: split-color footer section
+  - LEFT half: warm cream with contact info, address, phone, hours
+  - RIGHT half: dark navy (#1A1A3E) with food photography (overhead table shot with multiple dishes)
+  - Photo floats slightly above the navy background edge
+
+### s04 — scrollY=7470 (bottom)
+**Footer nav + legal**
+- Footer navigation bar: HOME, WORK, SERVICES, ABOUT US, JOBS, CONTACT, NEWS (left-aligned in coral)
+- Social links: INSTAGRAM, FACEBOOK, LINKEDIN (right-aligned in coral)
+- Bottom bar: Privacy Policy, "TABLESIDE" centered logo, © 2024
+- **Pattern**: Footer uses the brand coral for all link text against cream background. Clean horizontal nav layout.
+
+---
+
+## Key Design Patterns for VIB3+ Translation
+
+### 1. Three-Tone Palette (Cream + Coral + Navy)
+The site uses exactly three colors consistently: warm cream background, coral/orange for typography and accents, dark navy for contrast sections. No gradients, no additional colors.
+**For VIB3+**: A disciplined three-tone palette could anchor the landing page — e.g., dark background + one accent hue from the visualizer + white text.
+
+### 2. Variable Portfolio Card Sizing
+Portfolio cards are NOT uniform. Some span full viewport height, others are compact. Some have light photos, others have dark atmospheric shots. Size variation creates rhythm.
+**For VIB3+**: Cascade cards don't all need to be the same size. The clip-path morphing system could make some cards appear larger (wider window) and others more compact (narrower window), even though the underlying card is the same size.
+
+### 3. Split-Color Sections
+The contact/footer area uses a vertical split: cream on the left, navy on the right, with a food photo bridging the two zones. This creates a strong compositional split.
+**For VIB3+**: Could use a vertical split in the CTA or feature sections — one half showing one visualization system, the other showing a different one.
+
+### 4. CTA as Bold Color Block
+The CTA section is a solid block of coral color with white text. Simple, bold, impossible to scroll past without noticing.
+**For VIB3+**: The CTA section could use a solid color block with a visualizer running behind it at low opacity, creating color + depth.
+
+### 5. Service Tags as Metadata
+Each portfolio card lists specific services (WEB, CONTENT, PAID, SOCIAL & EDM) in small uppercase text. This adds information density without cluttering the visual.
+**For VIB3+**: Cascade cards could show parameter metadata (geometry name, system type, hue value) in small utility text that adds technical depth.
+
+---
+
+*Analysis based on actual Playwright screenshots captured with wheel-event scrolling.*

package/DOCS/{BLUEPRINT_EXECUTION_PLAN_2026-01-07.md → archive/BLUEPRINT_EXECUTION_PLAN_2026-01-07.md}

@@ -1,6 +1,6 @@
 # Blueprint execution plan (2026-01-07)
 
-This execution plan operationalizes the strategic blueprint and defines what each session should deliver. Each session should update `DOCS/SESSION_LOG_2026-01-07.md` with timestamped progress and keep the checklist current.
+This execution plan operationalizes the strategic blueprint and defines what each session should deliver. Each session should update `DOCS/archive/SESSION_LOG_2026-01-07.md` with timestamped progress and keep the checklist current.
 
 ## Session cadence
 - **Start of session**: review this plan and the strategic blueprint.

package/DOCS/{DEV_TRACK_ANALYSIS.md → archive/DEV_TRACK_ANALYSIS.md}

@@ -1,5 +1,8 @@
 # Dev track analysis and next steps
 
+> **Archived document:** This file is retained for historical reference in `DOCS/archive/` and is not part of the active docs set.
+
+
 This document summarizes the current development track status, highlights gaps, and proposes the
 next execution steps. It should be updated after each multi-system delivery.
 

package/DOCS/{SYSTEM_AUDIT_2026-01-30.md → archive/SYSTEM_AUDIT_2026-01-30.md}

@@ -1,5 +1,8 @@
 # VIB3+ CORE System Audit
 
+> **Archived document:** This file is retained for historical reference in `DOCS/archive/` and is not part of the active docs set.
+
+
 **Date**: January 30, 2026
 **Version**: 2.0.0 (`@vib3code/sdk`)
 **Branch**: `claude/phase-5-hardening-a4Wzn`

package/DOCS/{DEV_TRACK_SESSION_2026-01-31.md → dev-tracks/DEV_TRACK_SESSION_2026-01-31.md}

@@ -87,7 +87,7 @@
 | File | Purpose |
 |------|---------|
 | `DOCS/MASTER_PLAN_2026-01-31.md` | Master plan with 43 items |
-| `DOCS/DEV_TRACK_SESSION_2026-01-31.md` | This session log |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-01-31.md` | This session log |
 | `DOCS/OBS_SETUP_GUIDE.md` | OBS integration guide |
 | `LICENSE` | MIT License |
 | `CHANGELOG.md` | v1.0.0 + v2.0.0 release notes |

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-06.md

@@ -0,0 +1,231 @@
+# Development Session — 2026-02-06
+
+**Session type**: Full codebase audit + hygiene + MCP server + agent docs + testing
+**Branch**: `claude/project-review-planning-NWnhW`
+**Operator**: Claude Code (Opus 4.6)
+
+---
+
+## Session Overview
+
+Two consecutive work phases:
+
+1. **Phase A (Hygiene)**: Full 751-file audit, identified 9 bugs, fixed 8
+2. **Phase B (Infrastructure)**: Bug fixes, test verification, real MCP server, agent packs, landing page
+
+---
+
+## Phase A — Codebase Audit + Hygiene
+
+### Corrected from initial analysis
+
+| Item | Initial Assessment | Verified Status |
+|------|-------------------|----------------|
+| npm publish | Assumed not done | **Published**: `@vib3code/sdk@2.0.1` live on npm (Feb 3) |
+| CanvasManager.js | Assumed dead code | **Used by VIB3Engine** but API contract broken |
+| `u_breath` in shader-verify | Assumed tool wrong | **Tool correct** — inline had it, external files didn't |
+
+### Hygiene Fixes (Commit 1: `9e858a2`)
+
+| # | Fix | File(s) | Severity |
+|---|-----|---------|----------|
+| 1 | CanvasManager rewrite to match VIB3Engine API | `src/core/CanvasManager.js` (217→110 lines) | CRITICAL |
+| 2 | HolographicRendererAdapter import fix | `src/core/renderers/HolographicRendererAdapter.js:2` | CRITICAL |
+| 3 | TradingCardManager broken import paths | `src/export/TradingCardManager.js:60-63` | HIGH |
+| 4 | External shader u_breath sync | 4 shader files (GLSL + WGSL) | HIGH |
+| 5 | Version strings unified to 2.0.1 | VIB3Engine, Parameters, ErrorReporter | MEDIUM |
+| 6 | Viewer ReactivityManager renamed | `src/viewer/ViewerInputHandler.js` | MEDIUM |
+| 7 | Stale package-lock.json removed | Root (-240 KB) | LOW |
+| 8 | CHANGELOG v2.0.1 entries added | `CHANGELOG.md` | Docs |
+
+---
+
+## Phase B — Infrastructure + MCP + Testing
+
+### Bug Fixes (Commit 2)
+
+| # | Fix | File(s) | Lines |
+|---|-----|---------|-------|
+| 1 | FacetedSystem RendererContract compliance — added `init()`, `resize()`, `dispose()` | `src/faceted/FacetedSystem.js:588-600` | +13 |
+| 2 | Holographic breath desync — removed independent fallback cycle | `src/holograms/HolographicVisualizer.js:954-958` | 3 changed |
+| 3 | Test version assertion updated | `tests/e2e/SDK-Integration.test.js:292` | 1 line |
+
+**Test Results**: 933/933 passing (43 test files, 0 failures)
+
+### MCP Server (Option A — Real Protocol)
+
+**New File**: `src/agent/mcp/stdio-server.js` (230 lines)
+
+Implements proper JSON-RPC 2.0 over stdio per the Model Context Protocol spec:
+
+| Feature | Status |
+|---------|--------|
+| `initialize` / `initialized` handshake | Working |
+| `tools/list` — exposes all 19 tools with schemas | Working |
+| `tools/call` — routes to MCPServer handlers | Working |
+| `resources/list` — 4 documentation resources | Working |
+| `resources/read` — serves CLAUDE.md, geometry summary, control ref, live state | Working |
+| `ping` | Working |
+| Error handling (parse errors, unknown methods, etc.) | Working |
+
+**Tested**: All 3 protocol methods verified via stdio pipe.
+
+**Binary added**: `vib3-mcp` in package.json bin section.
+
+### Agent Documentation Pack
+
+**New Directory**: `agent-config/`
+
+| File | Purpose | Size |
+|------|---------|------|
+| `mcp-config.json` | Drop-in MCP client config for Claude Desktop / Cursor | Config |
+| `README.md` | Complete setup instructions + tool reference | 2 KB |
+| `claude-agent-context.md` | Precompiled context pack for Claude agents | 3 KB |
+| `openai-agent-context.md` | OpenAI function calling schemas + integration guide | 4 KB |
+
+### Dependencies
+
+- `pnpm install --frozen-lockfile` — all deps installed successfully
+- vitest 1.6.1, playwright 1.58.0, happy-dom 20.4.0 confirmed working
+
+---
+
+## Files Changed Summary (Both Phases)
+
+### Phase A (Commit 1)
+| File | Action |
+|------|--------|
+| `src/core/CanvasManager.js` | Rewritten (110 lines) |
+| `src/core/renderers/HolographicRendererAdapter.js` | Import fix |
+| `src/core/VIB3Engine.js` | Version: 1.2.0 → 2.0.1 |
+| `src/core/Parameters.js` | Version: 1.0.0 → 2.0.1 |
+| `src/core/ErrorReporter.js` | Version: 2.0.0 → 2.0.1 |
+| `src/export/TradingCardManager.js` | Fixed imports |
+| `src/shaders/quantum/quantum.frag.glsl` | +u_breath |
+| `src/shaders/faceted/faceted.frag.glsl` | +u_breath |
+| `src/shaders/quantum/quantum.frag.wgsl` | +breath field |
+| `src/shaders/faceted/faceted.frag.wgsl` | +breath field |
+| `src/viewer/ReactivityManager.js` → `ViewerInputHandler.js` | Renamed |
+| `src/viewer/index.js` | Updated import |
+| `package-lock.json` | Deleted |
+| `CHANGELOG.md` | +v2.0.1 entries |
+
+### Phase B (Commit 2)
+| File | Action |
+|------|--------|
+| `src/faceted/FacetedSystem.js` | +init(), +resize(), +dispose() |
+| `src/holograms/HolographicVisualizer.js` | Fixed breath desync |
+| `tests/e2e/SDK-Integration.test.js` | Updated version assertion |
+| `src/agent/mcp/stdio-server.js` | **NEW** — Real MCP server |
+| `package.json` | +vib3-mcp binary |
+| `agent-config/mcp-config.json` | **NEW** — MCP client config |
+| `agent-config/README.md` | **NEW** — Agent setup guide |
+| `agent-config/claude-agent-context.md` | **NEW** — Claude context pack |
+| `agent-config/openai-agent-context.md` | **NEW** — OpenAI context pack |
+| `index-v2.html` | **NEW** — Enhanced landing page (2100+ lines) |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-06.md` | Updated with Phase C |
+
+---
+
+## Phase C — Enhanced Landing Page (Commit 3)
+
+### `index-v2.html` — Choreographed Multi-Instance GSAP Showcase (2100+ lines)
+
+A complete Canvas2D-based landing page with 10 concurrent visualizer instances showing all 3 systems:
+
+| Section | Instances | Feature |
+|---------|-----------|---------|
+| **Hero** | 1x QuantumViz | Parallax inversion on scroll, density ramps up, 4D rotation increases |
+| **Trinity** | 1x bg + 3x cards (Quantum/Faceted/Holographic) | Hover: card density decreases + speed freezes, bg density increases + matches hue, others mute |
+| **Morph** | 3x (Faceted → Quantum → Holographic) | Scroll-locked pin, crossfade between systems, per-phase parameter animation |
+| **Playground** | 1x FacetedViz | 12 live parameter sliders with real-time update |
+| **Suck-Up** | 1x (dynamic) | Click card → visualizer animates from card position → expands to 90vw/90vh fullscreen |
+
+### Key Technical Decisions
+
+- **Canvas2D** (not WebGL) to avoid context limits with 10+ concurrent instances
+- **IntersectionObserver** gates rendering to only visible canvases
+- **30fps throttle** for battery-friendly performance
+- **prefers-reduced-motion** support throughout (instant opacity, no animations)
+- **ResizeObserver** per canvas for responsive DPR-aware sizing
+- All 8 base geometries + 2 warp functions + 6D rotation implemented in JS
+- GSAP ScrollTrigger for all scroll-locked choreography
+
+### Agent-First Features in Landing Page
+
+- "Download Agent Pack" button → generates claude-agent-context.md blob
+- "CLAUDE.md" download button → generates project instructions
+- "MCP Config" download → generates mcp-config.json
+- Copy-to-clipboard install command
+- MCP config code card with syntax highlighting
+- Tool list with 7 key tools shown
+
+---
+
+## Test Health
+
+| Metric | Value |
+|--------|-------|
+| **Unit test files** | 43 |
+| **Test cases** | 933 passing, 0 failing |
+| **Duration** | ~18s |
+| **Covered modules** | Math (100%), Render (100%), Geometry (100%), Scene (100%), Agent/Telemetry (good), Creative (partial) |
+| **Known gaps** | VIB3Engine, CanvasManager, Visualizers (direct), Viewer module, WebXR/WebGPU Compute/OffscreenWorker, Gallery, LLM, WASM loader |
+
+---
+
+## Exhale / Breath Feature Analysis
+
+### What It Is
+Global organic breathing cycle (VitalitySystem.js) — 6-second cosine wave oscillating 0→1→0, modulating all 3 visualization systems:
+
+| System | Effect | Modulation Factor |
+|--------|--------|------------------|
+| Quantum | Lattice brightness pulse | +40% at full exhale |
+| Faceted | Pattern intensity pulse | +30% at full exhale |
+| Holographic | Projection expansion + glow + density | +20% / +10% / +40% |
+
+### Bug Found & Fixed
+HolographicVisualizer had independent fallback breath cycle (line 955-958) that ran out of sync when VitalitySystem value wasn't received. Fixed to use centralized value with 0.0 default.
+
+---
+
+## Remaining Development Track
+
+### Critical Path for Launch
+
+| Priority | Item | Status |
+|----------|------|--------|
+| DONE | Real MCP server (JSON-RPC 2.0 over stdio) | `stdio-server.js` working |
+| DONE | Agent documentation packs | Claude + OpenAI configs |
+| DONE | All tests passing (933/933) | Verified |
+| DONE | Enhanced landing page (index-v2.html) | Multi-instance GSAP showcase (2100+ lines) |
+| NEXT | Claude Code skill (wraps MCP) | After landing page |
+| NEXT | Test coverage for v2.0.0 modules | 18 modules at 0% |
+
+### Short-Term
+
+- WebGPU end-to-end verification
+- Resolve duplicate CollectionManager
+- Demo videos/GIFs
+- Gallery app with shareable URLs
+
+### Medium-Term
+
+- API reference site (JSDoc → Docusaurus)
+- Figma Community plugin publish
+- Discord / community setup
+- Interactive tutorial
+
+---
+
+## Project Health Snapshot
+
+| Metric | Value |
+|--------|-------|
+| **npm package** | `@vib3code/sdk@2.0.1` (published) |
+| **MCP server** | Working (JSON-RPC 2.0/stdio, 19 tools, 4 resources) |
+| **Tests** | 933/933 passing |
+| **Agent packs** | Claude + OpenAI configs ready |
+| **Critical bugs fixed** | 5 (CanvasManager, HolographicAdapter, Faceted contract, breath desync, TradingCardManager) |
+| **CI workflows** | 9 GitHub Actions |

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-13.md

@@ -0,0 +1,114 @@
+# Development Session — 2026-02-13
+
+**Session type**: Agent Harness Implementation — MCP tools, ChoreographyPlayer, aesthetic mapping, headless rendering
+**Branch**: `claude/clause-code-skill-0PV33`
+**Operator**: Claude Code (Opus 4.6)
+**Parent work**: Builds on Phase 7 agent-power tools added earlier this session (7 new MCP tools, 2 Claude Code skills)
+
+---
+
+## Session Overview
+
+This session had two phases:
+
+### Phase 1 — Claude Code Skills + Initial Agent Tools (Commit 1)
+
+- Created 2 Claude Code skills (`.claude/commands/vib3-design.md`, `.claude/commands/vib3-dev.md`)
+- Added 7 new MCP tools (19 → 26): `describe_visual_state`, `batch_set_parameters`, `create_timeline`, `play_transition`, `apply_color_preset`, `set_post_processing`, `create_choreography`
+- Created agent harness architecture doc (`DOCS/AGENT_HARNESS_ARCHITECTURE.md`)
+- Added `.claude/settings.json` with shader validation pre-commit hook
+
+### Phase 2 — Harness Runtime Implementation (Commit 2)
+
+Implementing the concrete runtime pieces described in `DOCS/AGENT_HARNESS_ARCHITECTURE.md`:
+
+1. **`capture_screenshot` MCP tool** — Composites all 5 canvas layers → base64 PNG
+2. **`ChoreographyPlayer`** — Runtime class that plays back `create_choreography` JSON specs, manages scene transitions, per-scene timelines, system switching
+3. **`AestheticMapper`** — Text-description → parameter range mapping with 60+ vocabulary words across 6 categories (emotions, styles, colors, motion, depth, geometry)
+4. **`design_from_description` MCP tool** — Uses AestheticMapper to convert natural language to params
+5. **`play_choreography` MCP tool** — Loads and plays choreography specs with play/pause/stop/seek
+6. **`control_timeline` MCP tool** — Controls previously created ParameterTimeline instances
+7. **`get_aesthetic_vocabulary` MCP tool** — Lists all known descriptor words by category
+8. **Headless renderer** — Puppeteer-based CLI tool for capturing frames without a browser
+
+---
+
+## Files Created
+
+| File | Purpose | ~Lines |
+|------|---------|--------|
+| `.claude/commands/vib3-design.md` | Design/navigation Claude Code skill | 350 |
+| `.claude/commands/vib3-dev.md` | Development/expansion Claude Code skill | 350 |
+| `.claude/settings.json` | Shader validation pre-commit hook | 15 |
+| `DOCS/AGENT_HARNESS_ARCHITECTURE.md` | Agent harness roadmap document | 200 |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-13.md` | This file | — |
+| `src/creative/ChoreographyPlayer.js` | Multi-scene choreography playback runtime | 380 |
+| `src/creative/AestheticMapper.js` | Text-description → VIB3+ parameter mapping | 500 |
+| `tools/headless-renderer.js` | Puppeteer headless frame capture CLI | 220 |
+
+## Files Modified
+
+| File | Change | Risk |
+|------|--------|------|
+| `src/agent/mcp/tools.js` | Added 12 new tool definitions (total: 31) | LOW — additive only, all appended at end |
+| `src/agent/mcp/MCPServer.js` | Added 3 imports + 10 new handler methods + 5 new switch cases | LOW — additive only |
+| `agent-config/README.md` | Updated tool count (31) and table with new categories | LOW — docs only |
+| `agent-config/claude-agent-context.md` | Updated version, added power/choreography workflows, aesthetic vocabulary | LOW — docs only |
+
+## MCP Tool Inventory (31 total)
+
+| Phase | Tools Added | Count |
+|-------|------------|-------|
+| Original | get_sdk_context, verify_knowledge, create_4d_visualization, set_rotation, set_visual_parameters, switch_system, change_geometry, get_state, randomize_parameters, reset_parameters, save_to_gallery, load_from_gallery, search_geometries, get_parameter_schema | 14 |
+| Phase 6.5 | set_reactivity_config, get_reactivity_config, configure_audio_band, export_package | 4 |
+| Phase 6.6 | apply_behavior_preset, list_behavior_presets | 2 |
+| Phase 7 | describe_visual_state, batch_set_parameters, create_timeline, play_transition, apply_color_preset, set_post_processing, create_choreography | 7 |
+| Phase 7.1 | capture_screenshot, design_from_description, get_aesthetic_vocabulary, play_choreography, control_timeline | 4 |
+
+## Potential Conflicts with Parallel Work
+
+| File | Conflict Zone | Resolution |
+|------|--------------|------------|
+| `src/agent/mcp/tools.js` | End of `toolDefinitions` object (lines 648+) | Take both — all additions are appended after `list_behavior_presets` |
+| `src/agent/mcp/MCPServer.js` | Switch statement (lines 166-197), new methods (lines 1345+) | Take both — new switch cases + methods at end of class |
+| `agent-config/README.md` | Tool count number and table | Manual merge — update count, combine tables |
+| `agent-config/claude-agent-context.md` | Workflow section | Manual merge — keep both workflow blocks |
+| `package.json` | Only if parallel work adds exports | Our changes don't touch package.json |
+| `src/creative/` | New files only | No conflict — `ChoreographyPlayer.js` and `AestheticMapper.js` are new |
+
+## Notes for Future Sessions
+
+- `ChoreographyPlayer` imports `ParameterTimeline` and `TransitionAnimator` from `src/creative/`
+- `capture_screenshot` only works in browser context (needs canvas access); returns structured error in Node
+- `AestheticMapper` is stateless — can be used standalone or via MCP tool
+- Headless renderer is a standalone CLI tool in `tools/`, not imported by the SDK itself
+- MCPServer lazily creates `_aestheticMapper`, `_choreographyPlayer`, `_liveTimelines` on first use
+- `control_timeline` materializes stored timeline data into live `ParameterTimeline` instances on first play
+- Color preset values in `ChoreographyPlayer.COLOR_PRESET_MAP` must stay in sync with `MCPServer.applyColorPreset`
+
+## Architecture Notes
+
+```
+Agent → MCP Tool Call
+        ↓
+MCPServer.handleToolCall(name, args)
+        ↓
+┌─────────────────────────────────┐
+│ Phase 7 Handler Methods         │
+│                                 │
+│ captureScreenshot()             │  ← canvas.toDataURL composite
+│ designFromDescription()         │  ← AestheticMapper.resolveToValues
+│ playChoreographyTool()          │  ← ChoreographyPlayer.load + .play
+│ controlTimeline()               │  ← ParameterTimeline.play/pause/seek
+│ getAestheticVocabulary()        │  ← AestheticMapper.getVocabularyByCategory
+│                                 │
+│ Earlier Phase 7:                │
+│ describeVisualState()           │  ← natural language description
+│ batchSetParameters()            │  ← atomic multi-param set
+│ createTimeline()                │  ← build timeline spec
+│ playTransition()                │  ← TransitionAnimator.sequence
+│ applyColorPreset()              │  ← hue/sat/intensity mapping
+│ setPostProcessing()             │  ← effect pipeline config
+│ createChoreography()            │  ← multi-scene spec builder
+└─────────────────────────────────┘
+```

package/DOCS/dev-tracks/README.md

@@ -0,0 +1,10 @@
+# Development Track Logs
+
+Detailed, session-level implementation notes are stored here.
+
+## Sessions
+
+- [2026-01-31 session](DEV_TRACK_SESSION_2026-01-31.md)
+- [2026-02-06 session](DEV_TRACK_SESSION_2026-02-06.md)
+
+Roadmap references are maintained in [`DOCS/ROADMAP.md`](../ROADMAP.md).

package/README.md

@@ -2,12 +2,18 @@
 
 **General-purpose 4D rotation visualization SDK** for plugins, extensions, wearables, and agentic AI integration.
 
-[![Tests](https://img.shields.io/badge/tests-693%2B%20passing-brightgreen)](#testing)
-[![Version](https://img.shields.io/badge/version-2.0.0-blue)](#)
+[![Tests](https://img.shields.io/badge/tests-CI%20tracked-brightgreen)](DOCS/STATUS.md#test-status)
+[![Version](https://img.shields.io/badge/version-2.0.3-blue)](DOCS/STATUS.md#vib3-sdk-status)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 ---
 
+## Documentation
+
+The main documentation entrypoint is [`DOCS/README.md`](./DOCS/README.md), which includes canonical docs, persona-based reading paths, taxonomy, and source-of-truth ownership.
+
+---
+
 ## Quick Reference
 
 | Metric | Value |
@@ -29,7 +35,7 @@
 - **Agentic Integration:** MCP server with 14 tools for AI agent control
 - **Cross-Platform:** Web, WASM, Flutter support
 
-### New in v2.0.0
+### New in current release (v2.0.x)
 
 - **Universal Spatial Input:** 8 input sources (tilt, gyroscope, gamepad, mouse, MIDI, audio, programmatic, perspective) with 6 built-in profiles (card tilt, wearable, game, VJ, UI, XR)
 - **Creative Tooling:** 22 color presets, 14 easing transitions, 14 post-processing effects, keyframe timeline with BPM sync
@@ -176,7 +182,7 @@ engine.randomizeAll();
 engine.resetAll();
 ```
 
-### Spatial Input API (v2.0.0)
+### Spatial Input API (v2.0.x)
 
 ```javascript
 // Enable spatial input with a profile
@@ -194,7 +200,7 @@ engine.setSpatialDramaticMode(true); // 8x amplification
 //                     vjAudioSpatial, uiElement, immersiveXR
 ```
 
-### Framework Integration (v2.0.0)
+### Framework Integration (v2.0.x)
 
 ```javascript
 // React
@@ -348,17 +354,17 @@ echo 'geometry 10' | node src/cli/index.js
 │   │   ├── cli/              # CLI interface
 │   │   └── telemetry/        # Instrumentation
 │   ├── export/               # Export generators
-│   ├── reactivity/           # Reactivity + SpatialInputSystem (v2.0.0)
-│   ├── creative/             # Color presets, transitions, post-FX, timeline (v2.0.0)
-│   ├── integrations/         # React, Vue, Svelte, Figma, Three.js, TD, OBS (v2.0.0)
-│   └── advanced/             # WebXR, WebGPU compute, MIDI, AI, Worker (v2.0.0)
+│   ├── reactivity/           # Reactivity + SpatialInputSystem (current release series)
+│   ├── creative/             # Color presets, transitions, post-FX, timeline (current release series)
+│   ├── integrations/         # React, Vue, Svelte, Figma, Three.js, TD, OBS (current release series)
+│   └── advanced/             # WebXR, WebGPU compute, MIDI, AI, Worker (current release series)
 ├── tools/                    # Tooling (+ shader-sync-verify.js)
 ├── cpp/                      # C++ math core (WASM)
 ├── js/                       # Client-side integration
-├── tests/                    # Test suite (693+ tests)
+├── tests/                    # Test suite (CI-tracked status)
 ├── DOCS/                     # Documentation
 │   ├── SYSTEM_INVENTORY.md   # Complete system reference
-│   ├── SYSTEM_AUDIT_2026-01-30.md  # Full system audit
+│   ├── archive/SYSTEM_AUDIT_2026-01-30.md  # Full system audit (archived)
 │   ├── CLI_ONBOARDING.md     # Agent CLI setup
 │   └── CONTROL_REFERENCE.md  # UI parameters
 └── types/                    # TypeScript definitions
@@ -379,7 +385,7 @@ npm test -- --coverage
 npm test -- tests/agent/AgentCLI.test.js
 ```
 
-**Current Status:** 693+ tests passing
+**Current Status:** See [`DOCS/STATUS.md`](DOCS/STATUS.md) for release and CI-linked test status.
 
 ---
 
@@ -387,13 +393,20 @@ npm test -- tests/agent/AgentCLI.test.js
 
 | Document | Description |
 |----------|-------------|
+| [`DOCS/STATUS.md`](DOCS/STATUS.md) | Canonical release status (version, date, platforms, CI test status) |
+| [`DOCS/SYSTEM_INVENTORY.md`](DOCS/SYSTEM_INVENTORY.md) | Complete technical reference |
+| [`DOCS/SYSTEM_AUDIT_2026-01-30.md`](DOCS/SYSTEM_AUDIT_2026-01-30.md) | Full system audit |
 | [`DOCS/SYSTEM_INVENTORY.md`](DOCS/SYSTEM_INVENTORY.md) | Complete technical reference (v2.0.0) |
+| [`DOCS/PRODUCT_STRATEGY.md`](DOCS/PRODUCT_STRATEGY.md) | Product strategy: personas, use-cases, differentiation, and metrics |
+| [`DOCS/ROADMAP.md`](DOCS/ROADMAP.md) | Strategy goals mapped to technical epics and module ownership |
+| [`DOCS/README.md`](DOCS/README.md) | Documentation index and navigation hub |
 | [`DOCS/SYSTEM_AUDIT_2026-01-30.md`](DOCS/SYSTEM_AUDIT_2026-01-30.md) | Full system audit (v2.0.0) |
+| [`DOCS/archive/SYSTEM_AUDIT_2026-01-30.md`](DOCS/archive/SYSTEM_AUDIT_2026-01-30.md) | Full system audit (v2.0.0, archived) |
 | [`DOCS/CLI_ONBOARDING.md`](DOCS/CLI_ONBOARDING.md) | Agent CLI setup guide |
 | [`DOCS/CONTROL_REFERENCE.md`](DOCS/CONTROL_REFERENCE.md) | UI parameter reference |
 | [`24-GEOMETRY-6D-ROTATION-SUMMARY.md`](24-GEOMETRY-6D-ROTATION-SUMMARY.md) | Geometry encoding details |
 | [`DOCS/GPU_DISPOSAL_GUIDE.md`](DOCS/GPU_DISPOSAL_GUIDE.md) | Resource management |
-| [`CLAUDE.md`](CLAUDE.md) | AI/Developer technical reference (v2.0.0) |
+| [`CLAUDE.md`](CLAUDE.md) | AI/Developer technical reference |
 
 ---