coaia-visualizer 1.5.9 → 1.6.0

package/STUDY_REPORT.md

@@ -1,510 +0,0 @@
-# coaia-visualizer — Comprehensive Project Study Report
-
-> **Purpose**: Thorough analysis for reusable package design  
-> **Version studied**: 1.5.8  
-> **Generated**: 2025-07-27
-
----
-
-## 1. What coaia-visualizer Does
-
-**coaia-visualizer** is an interactive web-based tool that transforms coaia-narrative **JSONL memory files** into navigable, editable **Structural Tension Chart (STC)** hierarchies. It is built as a **ceremonial instrument** for practitioners of Robert Fritz's creative orientation methodology — not a project management dashboard.
-
-### Core Capabilities
-
-| Capability | Description |
-|:---|:---|
-| **JSONL Parsing** | Ingests flat JSONL files (one JSON object per line), parsing entity and relation records into structured chart hierarchies via a 4-pass algorithm |
-| **Chart Visualization** | Renders charts in hierarchy (tree) or flat list mode with progress bars, level badges, summary text, and telescoped navigation |
-| **Chart Editing** | Inline editing of desired outcomes, current reality observations, action steps; adding/deleting/completing actions; telescoping actions into full sub-charts |
-| **API Access** | 6 REST API route groups (charts CRUD, search, JSONL I/O, watch, audio) with Bearer token auth |
-| **MCP Server** | 15 MCP tools mapped 1:1 to chart operations for AI agent integration |
-| **CLI & Docker** | `coaia-visualizer --memory-path ./file.jsonl` launches the full app locally or in Docker |
-| **Live Mode** | File-watching with auto-reload when JSONL is modified by agents |
-| **Narrative Beats** | Renders story-layer documentation with act numbering, dramatic types, multi-universe perspectives |
-| **Relation Graphs** | Displays inter-entity connections grouped by relation type (contains, creates_tension_with, advances_toward, documents) |
-| **Reusable Package** | Exports types, parser, components, hooks, and UI primitives via `index.tsx` for consumption by other projects |
-
-### Structural Tension Philosophy
-
-The tool enforces **creative orientation** (not problem-solving). Every chart starts with a **Desired Outcome** (what the user wants to create), holds **Current Reality** as honest assessment, and drives **Action Steps** that advance toward the vision. The irreducible gap between reality and vision is the *structural tension* — visualized as the core UI element.
-
----
-
-## 2. Architecture Overview
-
-### Technology Stack
-
-| Layer | Technology | Version |
-|:---|:---|:---|
-| Runtime | Next.js (App Router) | 16.0.10 |
-| UI Framework | React | 19.2.0 |
-| Language | TypeScript | 5.x |
-| Styling | Tailwind CSS | 4.1.9 |
-| UI Primitives | Radix UI (20+ packages) + shadcn patterns | Various |
-| Charts | recharts | 2.15.4 |
-| Forms | react-hook-form + zod | 7.60.0 / 3.25.76 |
-| Icons | lucide-react | 0.454.0 |
-| Toast | sonner | 1.7.4 |
-| MCP | @modelcontextprotocol/sdk | 1.25.2 (main), 0.6.0 (mcp/) |
-| Themes | next-themes | 0.4.6 |
-| Testing | Playwright | 1.58.2 |
-| Deployment | Docker (node:22-alpine), Vercel, npm global |  |
-
-### Project Structure
-
-```
-coaia-visualizer/
-├── index.tsx                    # Package entry: exports types, parser, components, hooks, UI
-├── cli.ts                       # CLI entry point (compiles to dist/cli.js)
-├── package.json                 # v1.5.8, bin: coaia-visualizer
-│
-├── lib/                         # Core logic layer
-│   ├── types.ts                 # EntityRecord, RelationRecord, Chart, ParsedData
-│   ├── jsonl-parser.ts          # parseJSONL(), organizeData(), helpers
-│   ├── chart-editor.ts          # ChartEditor class (576 lines, all mutation logic)
-│   ├── api-auth.ts              # Token auth: getApiToken(), validateApiToken(), withAuth()
-│   └── utils.ts                 # cn() utility (clsx + tailwind-merge)
-│
-├── components/                  # React components
-│   ├── chart-list.tsx           # Hierarchy/flat list with ChartTree recursive component
-│   ├── chart-detail.tsx         # Read-only chart view (retained but unused by page.tsx)
-│   ├── chart-detail-editable.tsx # Full editing view (primary detail component)
-│   ├── edit-desired-outcome.tsx  # Inline desired outcome editor
-│   ├── edit-current-reality.tsx  # Observation list editor (add/edit/delete)
-│   ├── edit-action-step.tsx      # Action with completion toggle, telescope, date, delete
-│   ├── edit-chart-due-date.tsx   # Calendar popover for chart due dates
-│   ├── add-action-step.tsx       # Collapsible form for new actions
-│   ├── add-master-chart.tsx      # Dialog for new root charts
-│   ├── create-chart-form.tsx     # Inline chart creation form (Create tab)
-│   ├── narrative-beats.tsx       # Narrative beat cards with universe badges
-│   ├── relation-graph.tsx        # Grouped relation display
-│   ├── data-stats.tsx            # 4-card summary (charts, actions, entities, relations)
-│   ├── file-upload.tsx           # Drag-and-drop .jsonl/.txt upload
-│   ├── live-indicator.tsx        # Green pulse dot for live mode
-│   ├── page-with-editing.tsx     # (wrapper component)
-│   ├── theme-provider.tsx        # next-themes wrapper
-│   ├── theme-toggle.tsx          # Sun/Moon toggle, hydration-safe
-│   └── ui/                      # 12 shadcn/Radix primitives
-│       ├── badge.tsx, button.tsx, calendar.tsx, card.tsx
-│       ├── dialog.tsx, input.tsx, label.tsx, popover.tsx
-│       ├── scroll-area.tsx, separator.tsx, tabs.tsx, textarea.tsx
-│
-├── hooks/
-│   ├── use-live-polling.ts      # Polls /api/watch, triggers reload on new data
-│   └── use-toast.ts             # Toast hook (inactive; sonner is used instead)
-│
-├── app/                         # Next.js App Router
-│   ├── layout.tsx               # Root layout with ThemeProvider
-│   ├── page.tsx                 # Main orchestrator (7 useState hooks, auto-load)
-│   ├── globals.css              # Tailwind + theme CSS variables
-│   └── api/                     # REST API routes
-│       ├── charts/              # CRUD + search
-│       ├── jsonl/               # Read/write JSONL file
-│       ├── watch/               # File statistics for polling
-│       └── audio/               # MP3 serving
-│
-├── mcp/                         # Standalone MCP server (separate package)
-│   ├── package.json             # coaia-visualizer-mcp v1.0.0
-│   ├── src/
-│   │   ├── index.ts             # MCP server (stdio transport)
-│   │   ├── tools/index.ts       # 15 tool definitions with JSON Schema
-│   │   └── api-client.ts        # CoaiaVisualizerClient HTTP wrapper
-│   └── dist/                    # Compiled output
-│
-├── rispecs/                     # 14 RISE specification files
-├── samples/                     # Sample JSONL files
-├── test-data/                   # Test fixtures
-└── test-scripts/                # Playwright test specs
-```
-
-### Data Flow
-
-```
-JSONL Source (file/API/CLI)
-        │
-        ▼
-  parseJSONL(content)            Split lines → JSON.parse each → skip malformed
-        │
-        ▼
-  organizeData(records)          4-pass: separate → chart shells → populate → hierarchy
-        │
-        ▼
-  ParsedData                     { charts[], entities Map, relations[], rootCharts[] }
-        │
-   ┌────┴────────────────────────────┐
-   │              │                  │
-ChartList    ChartDetailEditable   DataStats
-(navigate)   (view + edit)         (summary)
-               │
-          ChartEditor              Mutation class → exportToJSONL()
-               │
-          POST /api/jsonl          Backup → write → persist
-```
-
----
-
-## 3. RISE Specification Summary (All 14 Files)
-
-### 3.1 rispecs/README.md
-Index document listing all specs with navigation. Defines the three core pillars: Creative Orientation, Structural Tension, Advancing Patterns. Includes the full data flow diagram and a quality test checklist.
-
-### 3.2 app.spec.md — Application Root
-The master spec. Defines:
-- What coaia-visualizer enables (8 user capabilities)
-- All 8 functional components with cross-references
-- Data flow architecture diagram
-- 3 creative advancement scenarios (first-time visualization, advancing through tension, AI agent workflow)
-- Page state management (7 useState hooks + auto-load behavior)
-- Complete technology stack
-- Core data structures (EntityRecord, RelationRecord, Chart, ParsedData)
-
-### 3.3 jsonl-parsing-data-types.spec.md — Parsing Engine
-Defines:
-- **Type system**: EntityRecord (5 entity types), RelationRecord (4 relation types), Chart, ParsedData
-- **parseJSONL()**: Line splitting, JSON.parse with console.error fallback, malformed-line resilience
-- **organizeData()**: 4-pass algorithm:
-  - Pass 1: Separate entities into Map, relations into array
-  - Pass 2: Assemble chart shells from `structural_tension_chart` entities
-  - Pass 3: Populate charts with desired_outcome, current_reality, action_step, narrative_beat
-  - Pass 3.5: Recognize telescoped sub-charts as parent action steps (synthetic entities)
-  - Pass 4: Build hierarchy (parent-child linking), identify rootCharts
-- **Helpers**: getChartSummary() (100-char truncation), getChartProgress() (completed/total %)
-- **Live reload**: useLivePolling hook polls /api/watch, compares beatCount
-
-### 3.4 chart-visualization-hierarchy.spec.md — Display & Navigation
-Defines:
-- **ChartList**: Two modes — hierarchy (recursive ChartTree with expand/collapse) and flat list
-- **ChartItem**: ID badge, level badge, summary, narrative indicators, action count, progress bar
-- **ChartDetail**: Read-only view (retained but NOT rendered by page.tsx)
-- **ChartDetailEditable**: Primary view with back button, inline editing, telescope actions, completion toggle
-- **Section order**: Desired Outcome → Action Steps → Current Reality (intentional — actions bridge the gap)
-- **Navigation stack**: `chartNavigationStack: Chart[]` with push/pop for unlimited depth drilling
-- **applyEdit pattern**: ChartEditor instance → mutation → getUpdatedData() → onUpdate()
-
-### 3.5 chart-editing-workflow.spec.md — Mutations & Creation
-Defines:
-- **ChartEditor class** (576 lines): 14 mutation methods, constructor takes ParsedData (shallow clone)
-- **Mutation methods**: updateDesiredOutcome, addCurrentRealityObservation, updateCurrentReality, updateCurrentRealityObservation, deleteCurrentRealityObservation, addActionStep, updateActionStep, markActionStepComplete, updateActionProgress, toggleActionCompletion, updateActionDueDate, deleteActionStep, createTelescopedChartFromAction, updateChartDueDate
-- **ChartUpdate interface**: 9 update types
-- **Edit components**: EditDesiredOutcome (hover pencil → textarea), EditCurrentReality (per-observation edit/delete + add), EditActionStep (completion toggle, telescope, hover toolbar, date picker, delete), EditChartDueDate (calendar popover)
-- **Creation components**: AddActionStep (collapsible form, creates telescoped sub-chart), AddMasterChart (dialog with 3 entities + 3 relations), CreateChartForm (inline card form)
-- **Telescoping flow**: Click telescope → ChartEditor.createTelescopedChartFromAction() → new chart at level+1 → navigate
-- **Save flow**: ChartEditor.exportToJSONL() → POST /api/jsonl → backup → persist
-
-### 3.6 api-mcp-interface.spec.md — REST API & MCP Server
-Defines:
-- **Authentication**: COAIAN_API_TOKEN env var (or auto-generated 64-char hex), Bearer token validation, withAuth middleware
-- **REST routes**: 6 groups (see Section 4 below)
-- **15 MCP tools**: Mapped 1:1 to REST operations (see Section 4 below)
-- **MCP transport**: stdio
-- **CoaiaVisualizerClient**: HTTP wrapper class for MCP server → REST API communication
-- **Agent scenario**: Claude Desktop configuration example + typical 6-step agent session
-
-### 3.7 cli-mode.spec.md — CLI & Deployment
-Defines:
-- **CLI flags**: --memory-path, --port, --docker, --docker-image, --pull, --live, --poll-interval, --auto-play, --audio-dir, --no-open, --help
-- **Environment variables**: COAIAN_MF, COAIAV_MEMORY_PATH, COAIAV_PORT, COAIAV_LIVE, etc.
-- **Configuration priority**: CLI flags > env vars > .env file > defaults
-- **Local mode**: Spawns `npm run dev`, waits 3s, auto-opens browser, SIGINT graceful shutdown
-- **Docker mode**: `docker run --rm -p -v -e` with CONTAINER_PORT=4321
-- **Dockerfile**: Two-stage node:22-alpine build, VOLUME /data, EXPOSE 4321
-- **npm binary**: `coaia-visualizer` → `dist/cli.js`
-
-### 3.8 narrative-beats-display.spec.md — Story Layer
-Defines:
-- **NarrativeBeats component**: Props = `{ beats: EntityRecord[] }`
-- **Beat metadata**: act (number), type_dramatic (string), universes (string[]), timestamp, narrative.description, narrative.prose, narrative.lessons
-- **Render**: Card with act/type header, universe badges, description, quoted prose, bulleted lessons
-- **Three universes**: engineer-world, ceremony-world, story-engine-world
-- **Empty state**: "No narrative beats documented yet"
-- **Placement**: Between Structural Tension section and Actions/Relations tabs
-
-### 3.9 relation-graph-visualization.spec.md — Entity Connections
-Defines:
-- **RelationGraph component**: Props = `{ chart: Chart, data: ParsedData }`
-- **Grouping**: Relations reduced into type-keyed groups with counts
-- **Display**: Badge per relation type, from→to pairs with entity observation previews
-- **4 relation types**: contains, creates_tension_with, advances_toward, documents
-- **Integration**: Tab alongside actions in chart detail views
-
-### 3.10 ui-component-library.spec.md — UI Primitives
-Defines:
-- **12 UI primitives**: Badge (4 variants), Button (6 variants, 6 sizes), Card (+6 sub-components), Dialog, Input, Label, Textarea, Tabs, Calendar, Popover, ScrollArea, Separator
-- **cn() utility**: clsx + tailwind-merge for safe class composition
-- **Theme system**: next-themes provider (default: dark), ThemeToggle (hydration-safe)
-- **Color tokens**: chart-1 (teal/outcomes), chart-2 (amber/reality), chart-3 (beats), chart-4 (stats)
-- **DataStats**: 4-card grid (Charts, Actions completed/total, Entities, Relations)
-- **LiveIndicator**: Animated green pulse when live data detected
-- **FileUpload**: Drag-drop + click-to-browse for .jsonl/.txt
-
-### 3.11 planning-integration.spec.md — 🔮 FUTURE
-Aspirational spec for visualizing charts born from coaia-planning's `plan_to_stc` tool:
-- Plan source badge with confidence scores
-- Bidirectional sync status (synced/diverged/conflict)
-- Plan section mapping for action provenance
-- Confidence-based color coding (≥0.9 default, 0.7-0.89 amber, <0.5 red)
-- Re-sync trigger to push edits back to plan markdown
-- 8 new UI components, 4 new API endpoints proposed
-
-### 3.12 pde-integration.spec.md — 🔮 FUTURE
-Aspirational spec for visualizing charts born from PDE decomposition:
-- Four Directions Medicine Wheel quadrant layout (EAST/SOUTH/WEST/NORTH)
-- PDE source linking with decomposition provenance trail
-- Implicit intent badges (⚡ Inferred)
-- Confidence bars per action step
-- Direction-based action grouping
-- 8 new UI components proposed
-
-### 3.13 accountability-responsibility.rispec.md — Accountability/Responsibility
-Medium-priority spec for rendering accountability/responsibility distinctions:
-- Chart header: accountability badge (who is accountable for the outcome)
-- Action steps: inline responsibility indicators
-- Delegation chain view (optional panel)
-- Filter/group by responsible entity type (human/AI/pair)
-- Consumes metadata.accountability and metadata.responsibility from entities
-
-### 3.14 relation-to-mcp-structural-thinking.kin.md — Kinship Document
-Kinship relationship between coaia-visualizer and mcp-structural-thinking:
-- Envisioned: three-universe validation scores as visual badges per chart
-- Reactive pattern highlights inline in chart text
-- Consensus status (✅/❌) on chart headers
-- coaia-visualizer owns rendering UX; mcp-structural-thinking provides data
-
----
-
-## 4. MCP Tools (15 Tools)
-
-The MCP server runs as a separate process (`mcp/src/index.ts`) communicating over stdio. It wraps the REST API via `CoaiaVisualizerClient`.
-
-| # | Tool | Required Args | Optional Args | REST Mapping |
-|---|------|---------------|---------------|:-------------|
-| 1 | `list_charts` | — | level, rootOnly | GET /api/charts |
-| 2 | `get_chart` | chartId | — | GET /api/charts/{id} |
-| 3 | `create_chart` | desiredOutcome, currentReality | dueDate, parentChartId | POST /api/charts |
-| 4 | `update_chart` | chartId | desiredOutcome, currentReality, dueDate | POST /api/charts/{id} |
-| 5 | `add_action_step` | parentChartId, actionStepTitle, currentReality | dueDate | POST /api/charts/{id} |
-| 6 | `update_action_step` | chartId, actionName, description | — | POST /api/charts/{id} |
-| 7 | `mark_action_complete` | chartId, actionStepName | — | POST /api/charts/{id} |
-| 8 | `update_action_progress` | chartId, actionStepName, progressObservation | updateCurrentReality | POST /api/charts/{id} |
-| 9 | `update_current_reality` | chartId, newObservations | — | POST /api/charts/{id} |
-| 10 | `toggle_action_completion` | chartId, actionName | — | POST /api/charts/{id} |
-| 11 | `delete_action_step` | chartId, actionName | — | POST /api/charts/{id} |
-| 12 | `create_telescoped_chart` | chartId, actionName | — | POST /api/charts/{id} |
-| 13 | `delete_chart` | chartId | — | DELETE /api/charts/{id} |
-| 14 | `search_charts` | — | q, level, completed, hasActions | GET /api/charts/search |
-| 15 | `get_chart_progress` | chartId | — | GET /api/charts/{id} + compute |
-
-### Tool Response Format
-```json
-{
-  "content": [{ "type": "text", "text": "<JSON string>" }],
-  "isError": false
-}
-```
-
----
-
-## 5. Key Patterns
-
-### 5.1 JSONL Entity/Relation Model
-
-All data is stored as flat JSONL — one JSON object per line. Two record types:
-
-**EntityRecord** — 5 entity types:
-- `structural_tension_chart` — chart container
-- `desired_outcome` — the creative vision
-- `current_reality` — honest assessment of what is
-- `action_step` — step toward desired outcome
-- `narrative_beat` — story documentation
-
-**RelationRecord** — 4 relation types:
-- `contains` — chart contains outcome/reality/action
-- `creates_tension_with` — reality creates tension with outcome
-- `advances_toward` — action/sub-chart advances toward parent outcome
-- `documents` — beat documents chart activity
-
-### 5.2 Entity Naming Convention
-
-Entities follow the pattern `{chartId}_{entityType}`:
-```
-chart_1_chart                → structural_tension_chart entity
-chart_1_desired_outcome      → desired_outcome entity
-chart_1_current_reality      → current_reality entity
-chart_1_action_1             → action_step entity
-chart_1_beat_1               → narrative_beat entity
-```
-
-Chart IDs auto-increment: find max N from existing `chart_N` entities, new chart = `chart_(N+1)`.
-
-### 5.3 4-Pass Organization Algorithm
-
-```
-Pass 1: Separate      entities → Map<name, EntityRecord>, relations → RelationRecord[]
-Pass 2: Chart Shells   structural_tension_chart entities → Chart objects with level, parentChart
-Pass 3: Populate       Match entities to charts by name prefix (regex /^(chart_\d+)/)
-Pass 3.5: Telescoped   Sub-charts (level > 0) → synthetic action entities in parent chart
-Pass 4: Hierarchy      Build parent-child tree, identify rootCharts (level === 0)
-```
-
-### 5.4 Telescoping Pattern
-
-Actions can "telescope" into full sub-charts for deeper structural exploration:
-
-1. User clicks telescope icon on an action step
-2. `ChartEditor.createTelescopedChartFromAction()` creates new `chart_N` at `level+1`
-3. Action's description becomes the new chart's desired outcome
-4. Default current reality: `"Starting work on this action step"`
-5. Original action flagged with `isTelescopedChart: true` and `telescopedChartId`
-6. Navigation stack pushes current chart, navigates to new sub-chart
-7. Due date auto-calculated as midpoint between now and parent's dueDate
-
-### 5.5 ChartEditor Mutation Pattern (applyEdit)
-
-All edits follow a consistent pattern:
-```typescript
-function applyEdit(editFn: (editor: ChartEditor) => void) {
-  const editor = new ChartEditor(data)      // Shallow clone current state
-  editFn(editor)                             // Apply mutation
-  const updatedData = editor.getUpdatedData() // Rebuild ParsedData
-  onUpdate(updatedData)                       // Propagate to parent state
-}
-```
-
-### 5.6 Completion Propagation
-
-When an action is marked complete:
-1. `completionStatus = true`, `completedAt` set to ISO timestamp
-2. Parent chart's current_reality automatically updated with "Completed: ..." observation
-3. Progress bar recalculates `(completed / total) * 100`
-
-### 5.7 Save Flow with Backup
-
-```
-ChartEditor.exportToJSONL()   → entities first, relations second (one per line)
-POST /api/jsonl               → API creates timestamped backup → writes new content
-hasUnsavedChanges = false     → toast notification
-```
-
-### 5.8 Live Polling
-
-When `NEXT_PUBLIC_LIVE_MODE=true`:
-1. `useLivePolling` hook polls `GET /api/watch` at configurable interval
-2. Compares `beatCount` with cached value
-3. If count increased → triggers full data reload from filesystem
-4. `isLive` flag flashes the LiveIndicator for 2 seconds
-
----
-
-## 6. Package Exports (Reusable Surface)
-
-The `index.tsx` entry point exports everything needed for external consumption:
-
-### Types
-- `EntityRecord`, `RelationRecord`, `JSONLRecord`, `Chart`, `ParsedData`
-
-### Core Logic
-- `parseJSONL(content: string): JSONLRecord[]`
-- `organizeData(records: JSONLRecord[]): ParsedData`
-- `getChartSummary(chart: Chart): string`
-- `getChartProgress(chart: Chart): number`
-- `cn(...inputs: ClassValue[]): string`
-
-### Hooks
-- `useLivePolling` — file-watching polling hook
-- `useToast` — toast hook (inactive; sonner used directly)
-
-### Application Components (16)
-- `FileUpload`, `ChartList`, `ChartDetailEditable`, `ChartDetail`
-- `DataStats`, `CreateChartForm`, `NarrativeBeats`, `LiveIndicator`
-- `ThemeToggle`, `EditDesiredOutcome`, `EditCurrentReality`, `EditActionStep`
-- `EditChartDueDate`, `AddActionStep`, `AddMasterChart`
-
-### UI Primitives (12)
-- `Badge`, `Button`, `Calendar`, `Card` (+5 sub-components)
-- `Dialog` (+6 sub-components), `Input`, `Label`, `Popover` (+2 sub-components)
-- `ScrollArea`, `Separator`, `Tabs` (+3 sub-components), `Textarea`
-
----
-
-## 7. Dependencies Analysis
-
-### Production Dependencies (42 packages)
-
-| Category | Packages |
-|:---|:---|
-| **Framework** | next 16.0.10, react 19.2.0, react-dom 19.2.0 |
-| **UI Primitives** | 20 @radix-ui/* packages (accordion through tooltip) |
-| **Styling** | class-variance-authority, clsx, tailwind-merge, tailwindcss-animate |
-| **Forms** | react-hook-form, @hookform/resolvers, zod |
-| **Charting** | recharts 2.15.4 |
-| **Date** | date-fns 4.1.0, react-day-picker 9.8.0 |
-| **MCP** | @modelcontextprotocol/sdk 1.25.2 |
-| **UI Extras** | lucide-react, sonner, cmdk, vaul, input-otp, embla-carousel-react, react-resizable-panels |
-| **Theme** | next-themes |
-| **CLI** | minimist, @types/minimist, dotenv |
-| **Validation** | @cfworker/json-schema |
-| **Analytics** | @vercel/analytics |
-
-### Dev Dependencies (7 packages)
-- @playwright/test, @tailwindcss/postcss, @types/node, @types/react, @types/react-dom, postcss, tailwindcss, tw-animate-css, typescript
-
-### MCP Server Dependencies (separate package)
-- @modelcontextprotocol/sdk ^0.6.0, dotenv ^17.2.3
-
-### Note on Dependency Weight
-The 20 Radix UI packages are the heaviest dependency cluster. Many are imported by shadcn patterns but not all are actively used by current components (e.g., accordion, avatar, context-menu, hover-card, menubar, navigation-menu, radio-group, slider, switch, toggle, toggle-group are present in package.json but have no corresponding component in `components/ui/`). A reusable package extraction could trim these significantly.
-
----
-
-## 8. Kinship & Ecosystem Position
-
-From KINSHIP.md:
-
-- **Ancestor**: `coaia-narrative` — defines the JSONL schema this tool reads
-- **Siblings**: `coaia-pde` (produces JSONL), `coaia-planning` (produces JSONL), `mia-code/miaco` (creates charts)
-- **Role**: Network servant — serves STC charts as interactive web UI and exposes them over MCP/API
-- **Steward**: Guillaume (jgwill)
-- **Boundaries**: Does NOT define schema (reads coaia-narrative format), does NOT decompose prompts or create charts (only visualizes/edits)
-
----
-
-## 9. Reusable Package Design Considerations
-
-### Already Reusable
-1. **Type system** (`lib/types.ts`) — 40 lines, zero dependencies, fully portable
-2. **JSONL parser** (`lib/jsonl-parser.ts`) — 179 lines, depends only on types.ts
-3. **ChartEditor** (`lib/chart-editor.ts`) — 576 lines, depends only on types.ts
-4. **Package exports** (`index.tsx`) — already structured for external consumption
-
-### Extraction-Ready
-1. **UI primitives** (`components/ui/`) — 12 shadcn components, standard patterns, theme-dependent
-2. **Application components** — depend on UI primitives + lib/types + lib/jsonl-parser
-3. **Hooks** — useLivePolling is self-contained (needs API endpoint)
-
-### Tightly Coupled
-1. **API routes** (`app/api/`) — Next.js App Router specific, env-var dependent
-2. **MCP server** (`mcp/`) — already a separate package, couples to REST API via HTTP
-3. **CLI** (`cli.ts`) — depends on package directory structure, spawns processes
-4. **Page orchestrator** (`app/page.tsx`) — top-level state management, not extractable
-
-### Recommendations for Reusable Package
-1. Extract `lib/` as a standalone `coaia-visualizer-core` package (types + parser + editor, ~800 lines, zero React dependency)
-2. Extract `components/` as a `coaia-visualizer-components` package (requires React 19 + Radix + Tailwind)
-3. Keep `mcp/` as its own package (already structured this way)
-4. Keep API routes and page orchestrator in the Next.js app
-
----
-
-## 10. Quality & Testing
-
-- **Playwright tests** (`test-scripts/`) for E2E testing
-- **Parse resilience**: Malformed lines logged via console.error and skipped (never crash)
-- **Round-trip fidelity**: parseJSONL(exportToJSONL(data)) produces equivalent ParsedData
-- **Backup safety**: Every write operation creates timestamped backup
-- **Auth**: Bearer token on all mutating endpoints (COAIAN_API_TOKEN or auto-generated)
-- **JSONL validity**: All exported content is one JSON object per line
-
----
-
-*Report complete. All 14 rispecs read. All source directories explored. Ready for reusable package design work.*

package/components.json

@@ -1,21 +0,0 @@
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "app/globals.css",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "iconLibrary": "lucide"
-}