@vib3code/sdk 2.0.3-canary.3b3ca18 → 2.0.3-canary.4e0dace

package/DOCS/archive/SESSION_014_PLAN.md

@@ -1,195 +1 @@
-# VIB3+ SDK - Session 014 Plan & Status
-
-**Date:** 2026-01-25
-**Branch:** `claude/phase-5-hardening-a4Wzn`
-**Session:** 014
-
----
-
-## Executive Summary
-
-This session completed a comprehensive system review and implemented agent onboarding improvements. The VIB3+ SDK is a **general-purpose 4D rotation visualization SDK** for plugins, extensions, wearables, and agentic AI integration.
-
----
-
-## System Architecture (Verified)
-
-### Core Metrics
-| Component | Value |
-|-----------|-------|
-| **Active Systems** | 3 (Quantum, Faceted, Holographic) |
-| **Placeholder Systems** | 1 (Polychora - TBD) |
-| **Rotation Planes** | 6 (XY, XZ, YZ + XW, YW, ZW) |
-| **Base Geometries** | 8 |
-| **Core Warp Types** | 3 (Base, Hypersphere, Hypertetrahedron) |
-| **Total Geometries** | 24 (8 base × 3 cores) |
-| **Canvas Layers** | 5 per system |
-| **MCP Tools** | 14 |
-| **Tests Passing** | 693+ |
-
-### Geometry Encoding Formula
-```
-geometry_index = core_index * 8 + base_index
-
-Where:
-- core_index: 0 (Base), 1 (Hypersphere), 2 (Hypertetrahedron)
-- base_index: 0-7 (tetrahedron, hypercube, sphere, torus, klein, fractal, wave, crystal)
-```
-
----
-
-## Changes Made This Session
-
-### 1. UI: Full 24 Geometry Support
-**File:** `sdk/index.html`
-- Added Core Type dropdown (Base, Hypersphere, Hypertetrahedron)
-- Implemented proper geometry encoding: `coreType * 8 + baseGeometry`
-- Updated geometry display to show "Geometry X / 24"
-- Fixed geometry buttons to work with core type selector
-
-### 2. Documentation: System Inventory
-**File:** `DOCS/SYSTEM_INVENTORY.md`
-- Complete technical inventory
-- Architecture diagram
-- All 4 systems documented
-- 24 geometry encoding explained
-- 6D rotation system documented
-- MCP tools reference
-- Agent onboarding quiz
-
-### 3. MCP: Agent Onboarding Tools
-**Files:** `src/agent/mcp/tools.js`, `src/agent/mcp/MCPServer.js`
-
-New tools added:
-- `get_sdk_context` - Returns essential SDK context on first connection
-- `verify_knowledge` - Multiple choice quiz to verify understanding
-
-Quiz format (answers: c, b, c, a, b, b):
-```
-Q1: How many rotation planes? a)3 b)4 c)6 d)8
-Q2: Geometry formula? a)base*3+core b)core*8+base c)base+core d)core*base
-Q3: Canvas layers per system? a)3 b)4 c)5 d)6
-Q4: Which are the 3 ACTIVE systems? a)quantum,faceted,holographic b)quantum,faceted,polychora c)all four d)none
-Q5: How many base geometry types? a)6 b)8 c)10 d)24
-Q6: Core warp types? a)base,sphere,cube b)base,hypersphere,hypertetrahedron c)2D,3D,4D d)none
-```
-
-### 4. Polychora Marked as TBD
-- Polychora system marked as placeholder/TBD in MCP responses
-- Quiz updated to test knowledge that only 3 systems are ACTIVE
-- System exists but not production-ready
-
----
-
-## Phase Status
-
-| Phase | Status | Notes |
-|-------|--------|-------|
-| **Phase 1: Foundation** | ✅ Complete | Math, geometry, parameters |
-| **Phase 2: Rendering** | ✅ Mostly Complete | Contracts exist, 4 adapters |
-| **Phase 3: Agentic** | ✅ Complete | MCP, CLI, Telemetry |
-| **Phase 4: WebGPU** | 🔄 Scaffold | Needs shader pipeline |
-| **Phase 5: Hardening** | 🔄 In Progress | 693 tests passing |
-
----
-
-## Known Issues
-
-1. **Polychora not production-ready** - Keep as TBD placeholder
-2. **WebGPU backend incomplete** - Scaffold exists, needs shader pipeline
-3. **Timing test flaky** - `withTiming` test sometimes fails by <1ms
-4. **Playwright test config** - Browser tests don't run in vitest
-
----
-
-## Planned Future Work
-
-### Phase 2 Consolidation (Rendering)
-- [ ] Audit all 4 systems for RendererContract compliance
-- [ ] Extract shared scene graph code
-- [ ] Document lifecycle rules in code
-- [ ] Add contract compliance tests
-
-### Phase 4 (WebGPU)
-- [ ] Complete WebGPU shader pipeline
-- [ ] Port shaders from WebGL to WGSL
-- [ ] Benchmark WebGL vs WebGPU
-
-### Phase 5 (Hardening)
-- [ ] Fix flaky timing test
-- [ ] Separate Playwright tests from vitest
-- [ ] Add more integration tests
-- [ ] Browser rendering verification
-
-### Documentation
-- [ ] Consolidate scattered docs
-- [ ] Archive outdated docs
-- [ ] Create "Start Here" guide for new agents
-- [ ] Add code examples to SYSTEM_INVENTORY.md
-
----
-
-## File References
-
-### Primary Documentation
-| File | Purpose |
-|------|---------|
-| `DOCS/SYSTEM_INVENTORY.md` | Complete system reference |
-| `DOCS/CLI_ONBOARDING.md` | Agent CLI setup |
-| `DOCS/CONTROL_REFERENCE.md` | UI parameters |
-| `24-GEOMETRY-6D-ROTATION-SUMMARY.md` | Geometry encoding |
-
-### Core Source Files
-| File | Purpose |
-|------|---------|
-| `src/core/VIB3Engine.js` | Main unified engine |
-| `src/core/RendererContracts.js` | Shared interfaces |
-| `src/quantum/QuantumEngine.js` | Quantum system |
-| `src/faceted/FacetedSystem.js` | Faceted system |
-| `src/holograms/RealHolographicSystem.js` | Holographic system |
-| `src/core/PolychoraSystem.js` | Polychora (TBD) |
-| `src/agent/mcp/MCPServer.js` | MCP server |
-| `src/agent/mcp/tools.js` | MCP tool definitions |
-| `src/agent/cli/AgentCLI.js` | CLI interface |
-
----
-
-## Git Commits This Session
-
-1. `feat(ui): Add full 24 geometry support with core type selector`
-2. `docs(sdk): Add comprehensive system inventory and agent onboarding tools`
-3. (pending) `feat(mcp): Add multiple choice quiz and mark Polychora as TBD`
-
----
-
-## Testing Commands
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test file
-npm test -- tests/agent/AgentCLI.test.js
-
-# Run with coverage
-npm test -- --coverage
-
-# Start dev server
-npm run dev:web
-```
-
----
-
-## Quiz Answers Reference
-
-For agent onboarding quiz (`verify_knowledge`):
-- Q1 (rotation planes): **c** (6)
-- Q2 (geometry formula): **b** (core*8+base)
-- Q3 (canvas layers): **c** (5)
-- Q4 (active systems): **a** (quantum, faceted, holographic)
-- Q5 (base geometries): **b** (8)
-- Q6 (core types): **b** (base, hypersphere, hypertetrahedron)
-
----
-
-*Document generated: Session 014, 2026-01-25*
+Last reviewed: 2026-02-17

package/DOCS/archive/SESSION_LOG_2026-01-07.md

@@ -1,56 +1 @@
-# Session log (2026-01-07)
-
-## 18:40:40
-- Logged required tooling and onboarding plan for agentic CLI workflows.
-- Created a dated dev track plan to anchor upcoming work.
-- Documented telemetry export flow in the onboarding guide.
-
-## 23:19:52
-- Added onboarding verification prompts to ensure agents can name geometry types and controls.
-
-## 23:34:16
-- Clarified the onboarding knowledge check to allow continuation while pointing to the correct reference docs.
-
-## 23:37:38
-- Added a copy/paste knowledge-check template and planned it in the dev track.
-
-## 02:07:46
-- Captured the unified SDK strategic blueprint and linked it from the README.
-
-## 02:10:12
-- Expanded the strategic blueprint into detailed actions and created an execution plan checklist.
-
-## 02:42:14
-- Added 4D rotation matrices, projection helpers, and stability tests; checked off Phase 1 math foundation items.
-
-## 02:42:36
-- Ran `pnpm test` to validate rotation and projection math helpers.
-
-## 02:46:57
-- Added renderer and resource manager contracts and checked off the Phase 2 interface definition.
-
-## 02:53:28
-- Implemented Phase 3 agentic integration: MCP tool definitions, telemetry spans/error schema, and agent CLI JSON/non-interactive export.
-
-## 02:53:50
-- Added CLI error handling for invalid pack JSON with structured telemetry errors.
-
-## 03:09:19
-- Completed Phase 4 cross-platform scaffolding: WASM target, Flutter render command buffer, and WebGPU feature flags.
-
-## 03:13:25
-- Completed Phase 5 deliverables: licensing tiers, export formats with golden snapshot coverage, and XR benchmark docs.
-
-## 03:13:48
-- Ran `pnpm test` to update export format snapshots and validate test coverage.
-
-## 13:19:14
-- Added scene graph scaffolding and documented GPU disposal patterns for Phase 2.
-
-## 2026-01-23 22:04 (Session 011)
-- Fixed rotation stability test precision tolerance (Float32Array drift over 2000 iterations).
-- Expanded LICENSING_TIERS.md with implementation details: key format, activation flow, token schema, offline validation, feature gating.
-- Expanded EXPORT_FORMATS.md with format specifications, golden snapshot test implementation, and CI integration.
-- Expanded XR_BENCHMARKS.md with metrics collection, benchmark runner, regression detection, and performance overlay.
-- Added CLI `validate` command for validating scene packs, manifests, and tool responses.
-- All 584 tests passing.
+Last reviewed: 2026-02-17

package/DOCS/archive/STRATEGIC_BLUEPRINT_2026-01-07.md

@@ -1,72 +1 @@
-# Strategic development blueprint (2026-01-07)
-
-This document captures the unified SDK direction for VIB3+ and provides an actionable architecture spine for agentic-first development.
-
-## Unified architecture stack
-- **Rendering core**: WebGL engine becomes the renderer of record.
-- **Agentic wrapper**: MCP/automation layer orchestrates workflows, telemetry, and validation.
-- **SDK scaffolding**: Public API layer with modular packages for core, math, geometry, materials, webgl, webgpu, agent, and cli.
-
-## Package layout target
-```
-@vib3/core      → Scene graph, resource management, abstract renderer
-@vib3/math      → 4D vectors, rotors, matrices, projections
-@vib3/geometry  → Polychora, tesseracts, slicing algorithms
-@vib3/materials → Shaders, holographic/quantum rendering modes
-@vib3/webgl     → WebGL 2.0 backend
-@vib3/webgpu    → WebGPU backend (experimental)
-@vib3/agent     → MCP server, tools, telemetry
-@vib3/cli       → Agent-friendly CLI interface
-```
-
-## Math + rendering principles
-- 4D rotations require rotors or 4×4 matrices; avoid storing orientation as Euler angles.
-- Provide stereographic and perspective projections with singularity clamping.
-- Renormalize rotors/matrices periodically to avoid drift.
-
-## Agentic API design
-- Prefer workflow-oriented tools (create scene, apply rotations, render preview) over low-level API exposure.
-- Emit structured telemetry with explicit error codes, suggestions, and valid options.
-- Add JSON output mode, non-interactive flags, and streaming progress events to the CLI.
-
-## Cross-platform strategy
-- Plan a shared core (Rust/C++/WASM) with thin platform bindings (web, Flutter, native).
-- Batch render commands to avoid per-frame FFI overhead.
-- Share shader sources and cross-compile to target platforms.
-
-## Licensing direction (draft)
-- MIT runtime for core packages with paid tiers for advanced tooling and exports.
-- Provide transparent changelogs, pricing notices, and grandfathering policies.
-
-## Phased roadmap
-1. **Math foundation**: rotors, projections, core polychora generators.
-2. **Rendering core**: renderer abstraction, system consolidation, resource disposal.
-3. **Agentic integration**: MCP tools, telemetry, CLI JSON outputs.
-4. **Cross-platform**: WASM core, Flutter bindings, WebGPU backend.
-5. **Production hardening**: licensing, editor tooling, export formats, XR integration.
-
-## Detailed blueprint actions
-### Phase 1 — Mathematical foundation
-- Implement rotor/matrix utilities for all six rotation planes.
-- Provide stereographic + perspective projection helpers with clamping.
-- Add automated stability tests for rotation drift.
-
-### Phase 2 — Rendering core consolidation
-- Extract renderer contracts and resource manager interfaces.
-- Unify the four visualization systems behind a shared scene graph.
-- Document disposal patterns to prevent GPU leaks.
-
-### Phase 3 — Agentic integration
-- Define MCP tools around workflows (create scene, apply rotation, render preview).
-- Add telemetry spans and error schemas for validation and tooling.
-- Implement CLI JSON output modes and non-interactive flags.
-
-### Phase 4 — Cross-platform execution
-- Formalize a WASM target and shared math core.
-- Add Flutter bindings with a batched render command buffer.
-- Prototype WebGPU backend behind feature flags.
-
-### Phase 5 — Production hardening
-- Draft licensing tiers and activation flow.
-- Add export format support with golden snapshot tests.
-- Document XR integration and performance benchmarks.
+Last reviewed: 2026-02-17