coaia-visualizer 1.6.1 → 1.6.3

package/mcp/test_mcp/.gemini/settings.json

@@ -1,18 +0,0 @@
-{
-  "mcpServers": {
-	   "chart-coaia-narrative-legacy-mcp": {
-         "command": "npx",
-         "args": ["-y", "${CNCV}", "--memory-path", "${memories}/trading-chart.coaia-narrative.jsonl" ]
-    },
-     "charts-mcp": {
-      "command": "node",
-      "args": [
-        "/workspace/repos/jgwill/coaia-visualizer-feat-4/mcp/dist/index.js"
-      ],
-      "env": {
-      "COAIAN_API_TOKEN":"123",
-      "COAIAV_API_URL":"http://localhost:4321"
-      }
-    }
-  }
-}

package/rispecs/README.md

@@ -1,170 +0,0 @@
-# COAIA Visualizer — RISE Specification Directory
-
-> Complete RISE specifications for `coaia-visualizer` v1.5.5 — the interactive web-based visualizer and editor for Structural Tension Charts from coaia-narrative JSONL files.
-
-**Framework**: RISE (Reverse-engineer · Intent · Specifications · Export)  
-**Target Audience**: LLM agents, developers, and contributors rebuilding or extending coaia-visualizer  
-**Canonical Types**: [`coaia-visualizer/lib/types.ts`](../lib/types.ts)  
-**Parent Kinship**: [`coaia-narrative`](../../coaia-narrative/) — data source and memory layer
-
----
-
-## 📚 Main Overview
-
-- **[app.spec.md](./app.spec.md)** — Complete application specification
-  - What coaia-visualizer enables users to create
-  - How all components interconnect
-  - Creative intent and structural orientation
-
----
-
-## 🔧 Component Specifications
-
-1. **[jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md)**
-   - JSONL parsing engine and 4-pass organization algorithm
-   - EntityRecord, RelationRecord, Chart, ParsedData type system
-   - KnowledgeGraph assembly from flat JSONL lines
-   - File upload, export, and live reload
-
-2. **[chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md)**
-   - ChartList with hierarchy and flat list modes
-   - ChartDetail and ChartDetailEditable views
-   - Telescoped navigation and sub-chart drilling
-   - Progress bars, summary truncation, narrative beat indicators
-
-3. **[chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md)**
-   - Edit desired outcomes, current reality observations, action steps
-   - Due date management with calendar popover
-   - Add/remove/toggle actions and charts
-   - CreateChartForm and AddMasterChart creation flows
-   - ChartEditor class mutation patterns
-
-4. **[api-mcp-interface.spec.md](./api-mcp-interface.spec.md)**
-   - REST API routes (charts CRUD, search, JSONL I/O, watch, audio)
-   - MCP server with 15 tools for AI agent access
-   - Bearer token authentication (COAIAN_API_TOKEN)
-   - CoaiaVisualizerClient API wrapper
-
-5. **[cli-mode.spec.md](./cli-mode.spec.md)**
-   - CLI entry point with `--memory-path` flag
-   - Docker and local Next.js execution modes
-   - Environment variable configuration
-   - Auto-open browser and graceful shutdown
-
-6. **[narrative-beats-display.spec.md](./narrative-beats-display.spec.md)**
-   - Narrative beat card rendering
-   - Multi-universe perspective badges
-   - Act sequencing, dramatic type, prose display
-   - Lessons learned and timestamp metadata
-
-7. **[relation-graph-visualization.spec.md](./relation-graph-visualization.spec.md)**
-   - Inter-chart relation graph rendering
-   - Entity connection display grouped by relation type
-   - contains, creates_tension_with, advances_toward, documents relations
-   - Entity observation preview
-
-8. **[ui-component-library.spec.md](./ui-component-library.spec.md)**
-   - Radix UI / shadcn-based component primitives
-   - Dark/light theme support via next-themes
-   - DataStats dashboard cards
-   - LiveIndicator polling status display
-   - Tailwind CSS utility patterns
-
-9. **[accountability-responsibility.rispec.md](./accountability-responsibility.rispec.md)** *(existing)*
-   - Rendering accountability/responsibility distinctions in chart UI
-   - Schema consumption from entity metadata
-
----
-
-## 🔮 Future Integration Specs
-
-10. **[pde-integration.spec.md](./pde-integration.spec.md)** *(future/aspirational)*
-    - Four Directions Medicine Wheel quadrant visualization
-    - PDE source linking with decomposition provenance trail
-    - Implicit intent badges and confidence indicators
-    - Direction-based action grouping (EAST/SOUTH/WEST/NORTH)
-    - Extends: chart-visualization-hierarchy, jsonl-parsing-data-types
-
-11. **[planning-integration.spec.md](./planning-integration.spec.md)** *(future/aspirational)*
-    - Plan source indicator with parse confidence scoring
-    - Bidirectional sync status (synced/diverged/conflict)
-    - Plan section mapping for action step provenance
-    - Confidence-based color coding for human review focus
-    - Re-sync trigger to push edits back to plan markdown
-    - Extends: chart-visualization-hierarchy, chart-editing-workflow, api-mcp-interface
-
----
-
-## 🎯 Core Creative Intent
-
-coaia-visualizer enables users to **create living, navigable maps of structural tension** — transforming flat JSONL memory files into interactive hierarchies where:
-
-- **Desired outcomes** are visible as aspirational anchors
-- **Current reality** is honestly assessed and continuously updated
-- **Action steps** telescope into full sub-charts, creating fractal depth
-- **Narrative beats** weave story across the structural work
-- **Relations** reveal the kinship between charts, actions, and outcomes
-
-This is **not** a dashboard for monitoring problems. It is a **ceremonial instrument** for holding creative tension — the generative gap between what is and what must become.
-
----
-
-## 🏗️ Three Core Pillars
-
-### 1. Creative Orientation (NOT Problem-Solving)
-Every chart begins with a **Desired Outcome** — what the user wants to create. The system refuses "fix" and "solve" framing. Current Reality is an honest assessment, never a complaint.
-
-### 2. Structural Tension (Current Reality ↔ Desired Outcome)
-The irreducible gap between reality and vision generates the *mana* that drives action. The visualizer makes this tension **visible and navigable** — not as anxiety but as creative fuel.
-
-### 3. Advancing Patterns (NOT Oscillating)
-Action steps advance toward outcomes. Completed actions update parent reality. Telescoped charts create depth without losing context. The system structurally prevents oscillation between problem and relief.
-
----
-
-## 📐 Data Flow Architecture
-
-```
-JSONL File / API
-       │
-       ▼
-  parseJSONL()        ─── Flat records (entities + relations)
-       │
-       ▼
-  organizeData()      ─── 4-pass: separate → chart assembly → populate → hierarchy
-       │
-       ▼
-  ParsedData          ─── Charts[], Entities Map, Relations[], RootCharts[]
-       │
-       ├──▶ page.tsx           ─── Main orchestrator (state management, routing)
-       ├──▶ ChartList         ─── Hierarchy/List navigation
-       ├──▶ ChartDetail       ─── Read-only display (unused by page.tsx)
-       ├──▶ ChartDetailEdit   ─── Full editing via ChartEditor
-       ├──▶ NarrativeBeats    ─── Story layer
-       ├──▶ RelationGraph     ─── Inter-entity connections
-       └──▶ DataStats         ─── Summary metrics
-       │
-       ▼
-  ChartEditor.exportToJSONL()  ─── Serialize back to JSONL
-       │
-       ▼
-  POST /api/jsonl     ─── Persist with backup
-       │
-       ▼
-  COAIAV_MEMORY_PATH  ─── Filesystem path resolved by CLI / env
-```
-
----
-
-## ✅ Quality Test: Can Another LLM Rebuild This?
-
-Given these specifications alone, an LLM agent should be able to:
-
-- ✅ Parse any coaia-narrative JSONL file into navigable chart hierarchies
-- ✅ Render structural tension (desired outcome vs current reality) with correct visual language
-- ✅ Implement telescoped navigation between parent and sub-charts
-- ✅ Build all 15 MCP tools matching the existing API surface
-- ✅ Create the CLI with Docker and local execution modes
-- ✅ Reproduce the edit workflow: desired outcome → current reality → action steps → completion
-- ✅ Display narrative beats with multi-universe perspectives
-- ✅ Maintain creative orientation framing throughout all UI text

package/rispecs/accountability-responsibility.rispec.md

@@ -1,110 +0,0 @@
-# RISPEC: Accountability & Responsibility Rendering in coaia-visualizer
-
-> How the visualizer displays accountability and responsibility distinctions in Structural Tension Charts
-
-## 🎯 What This Enables Users to Create
-
-- Visual clarity on who holds accountability for chart outcomes
-- Inline responsibility attribution on action steps
-- Delegation chain awareness across chart hierarchies
-- Filtered views by responsible entity type (human / AI / pair)
-
-## Current Reality
-
-`coaia-visualizer` renders STCs from coaia-narrative JSONL. It shows chart components (desired outcome, current reality, action steps), telescoping navigation, and completion status. There is no visual representation of:
-- Who is accountable for a chart's desired outcome
-- Who is responsible for each action step
-- The delegation chain between them
-
-## Desired Result
-
-The visualizer renders accountability and responsibility as first-class visual elements:
-- **Chart header**: shows the accountable entity with a distinct badge
-- **Action steps**: show responsible entity/entities inline
-- **Delegation view**: optional view showing the accountability→responsibility chain
-
-## UI Components
-
-### Chart Header — Accountability Badge
-
-```
-┌─────────────────────────────────────────┐
-│ 🎯 Deploy PDE across all variants      │
-│ ◉ Accountable: jgi (human)             │
-│ Due: 2026-03-21                         │
-└─────────────────────────────────────────┘
-```
-
-- `◉` icon distinguishes accountability from responsibility
-- Color-coded by `accountableEntityType`: human (blue), ai_companion (purple), team_lead (green)
-- Click to view accountability context
-
-### Action Steps — Responsibility Indicators
-
-```
-□ Audit mcp-pde implementation          → mia, sub-agent:south
-□ Update coaia-pde stc-mapper           → mia
-■ Research IAIP reference format        → sub-agent:south ✓ completedBy: south-3
-```
-
-- Responsible entities shown inline, right-aligned
-- `pair` type shows both entities with a link icon
-- Completed steps show `completedBy` if different from responsible
-
-### Delegation Chain View (Optional Panel)
-
-```
-jgi (accountable)
-├── delegates → mia (NORTH actions)
-├── delegates → sub-agent:south (SOUTH actions)
-├── co-holds → jgi + miette (WEST actions)
-└── retains → jgi (EAST actions)
-```
-
-### Filter/Group Controls
-
-- Filter action steps by responsible entity
-- Group by responsibility type (human / AI / pair)
-- Highlight items where responsibility ≠ completed-by (delegation shift)
-
-## Schema Consumption
-
-Reads from Entity.metadata:
-
-```typescript
-// Chart entity
-metadata.accountability?.accountableEntity
-metadata.accountability?.accountableEntityType
-metadata.accountability?.accountabilityContext
-
-// Action step entity
-metadata.responsibility?.responsibleEntities
-metadata.responsibility?.responsibilityType
-metadata.responsibility?.delegatedFrom
-metadata.assignedTo  // backward compat fallback
-```
-
-## Backward Compatibility
-
-When `accountability` / `responsibility` fields are absent:
-- Chart header shows no accountability badge (no default assumption)
-- Action steps show no responsibility indicator
-- Existing charts render identically to current behavior
-
-## Dependency
-
-- Canonical schema: `coaia-narrative/rispecs/accountability-responsibility-distinction.rispec.md`
-- Data source: coaia-narrative JSONL with Entity.metadata extensions
-
-## Priority
-
-Medium — rendering follows schema. Implement after coaia-narrative schema extension is merged.
-
----
-
-## 🔗 Related Components
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — ChartDetail/ChartDetailEditable host accountability badges in header
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — EditActionStep would need responsibility indicator integration
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — EntityRecord metadata extensions for accountability/responsibility fields
-- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API routes would need to support accountability/responsibility updates

package/rispecs/api-mcp-interface.spec.md

@@ -1,287 +0,0 @@
-# API & MCP Interface
-## RISE Specification for REST API, MCP Server, and Agent Access Patterns
-
-**Component Purpose**: Provide complete programmatic access to structural tension chart operations via REST API endpoints and a 15-tool MCP server, enabling AI agents and external tools to create, read, update, and delete charts with the same fidelity as the web UI.
-
-**Source Files**: `app/api/**/*.ts`, `mcp/src/index.ts`, `mcp/src/tools/index.ts`, `mcp/src/api-client.ts`, `lib/api-auth.ts`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- AI agent workflows that manage structural tension charts programmatically
-- Automated chart creation from Claude, GPT, or any MCP-compatible agent
-- External tool integrations via standard REST API calls
-- Secure multi-user access with token-based authentication
-- Live data synchronization between web UI and agent sessions
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-coaia-narrative stores data as JSONL files on disk. Without an API layer, agents must read/write files directly, parse JSONL manually, and implement their own chart assembly logic. The MCP protocol exists but needs a server that maps chart operations to tool definitions.
-
-### Desired Result
-A complete API surface where:
-- 6 REST route groups expose all chart operations
-- 15 MCP tools provide agent-native access
-- Bearer token authentication protects all mutating endpoints
-- Every write operation creates a timestamped backup
-- Response formats are consistent (JSON with error/success patterns)
-
-### Natural Resolution
-The REST API implements chart operations using `ChartEditor` and JSONL parsing. The MCP server wraps the REST API via `CoaiaVisualizerClient`, translating tool calls into HTTP requests. Both share the same authentication layer.
-
----
-
-## 📋 Authentication (`lib/api-auth.ts`)
-
-### Token Resolution
-```
-1. Check COAIAN_API_TOKEN environment variable
-2. If set → use as API token
-3. If not set → generate random 64-char hex token (crypto.randomBytes(32))
-4. Cache generated token for process lifetime
-5. Log generated token to console with warning (development convenience)
-```
-
-### Request Validation
-```typescript
-validateApiToken(request: NextRequest): boolean
-  1. Extract Authorization header
-  2. Match regex /^Bearer\s+(.+)$/
-  3. Compare extracted token against getApiToken()
-  4. Return true only if match
-```
-
-### Middleware Pattern
-```typescript
-withAuth(handler): wrappedHandler
-  1. Call validateApiToken(request)
-  2. If invalid → return 401 { error: "Unauthorized" }
-  3. If valid → delegate to handler(request, context)
-```
-
-### Response Helpers
-- `successResponse(data, status=200)` → `NextResponse.json(data, { status })`
-- `errorResponse(message, status=400)` → `NextResponse.json({ error: message }, { status })`
-- `unauthorizedResponse()` → 401 with explanation message
-
----
-
-## 📋 REST API Routes
-
-### GET /api/charts — List Charts
-**Auth**: Required (withAuth)  
-**Query Params**:
-- `level` — Filter by chart depth (number)
-- `rootOnly` — Return only level-0 charts (boolean)
-
-**Response**: `{ charts: Chart[], total: number, memoryPath: string }`
-
-### POST /api/charts — Create Chart
-**Auth**: Required (withAuth)  
-**Body**:
-```json
-{
-  "desiredOutcome": "string (required)",
-  "currentReality": "string (required)",
-  "dueDate": "ISO date string (optional)",
-  "parentChartId": "string (optional, for sub-charts)"
-}
-```
-**Behavior**:
-1. Generate new chart_N ID (max existing + 1)
-2. Create 3 entities: chart, desired_outcome, current_reality
-3. Create 3 relations: contains (×2), creates_tension_with
-4. If parentChartId: create parent→child contains relation
-5. Create timestamped backup of existing file
-6. Write updated JSONL
-
-**Response**: `{ chartId: string, message: string, backup: string }`
-
-### GET /api/charts/[id] — Get Chart
-**Auth**: Required  
-**Response**: Full Chart object with all properties
-
-### POST /api/charts/[id] — Update Chart
-**Auth**: Required  
-**Body**: Object with one or more update operations:
-
-| Operation | Fields | Effect |
-|:---|:---|:---|
-| `updateDesiredOutcome` | `{ text: string }` | Replace desired outcome |
-| `addCurrentRealityObservation` | `{ observation: string }` | Add observation |
-| `updateCurrentReality` | `{ observations: string[] }` | Replace observations |
-| `updateCurrentRealityObservation` | `{ index, text }` | Update specific observation |
-| `deleteCurrentRealityObservation` | `{ index }` | Remove observation |
-| `addActionStep` | `{ title, currentReality, dueDate? }` | Create telescoped action |
-| `updateActionStep` | `{ actionName, description }` | Update action text |
-| `toggleActionCompletion` | `{ actionName }` | Toggle done status |
-| `markActionComplete` | `{ actionStepName }` | Complete + update parent |
-| `updateActionProgress` | `{ actionStepName, observation, updateReality? }` | Add progress |
-| `updateActionDueDate` | `{ actionName, dueDate }` | Change action date |
-| `deleteActionStep` | `{ actionName }` | Remove action |
-| `createTelescopedChart` | `{ actionName }` | Convert action to sub-chart |
-| `updateDueDate` | `{ dueDate }` | Change chart date |
-
-**Response**: `{ chart: Chart, updates: string[], backup: string, message: string }`
-
-### DELETE /api/charts/[id] — Delete Chart
-**Auth**: Required  
-**Behavior**: Recursively deletes chart + all sub-charts, their entities, and all related relations  
-**Response**: `{ message: string, deletedEntities: string[], backup: string }`
-
-### GET /api/charts/search — Search Charts
-**Auth**: Required  
-**Query Params**:
-- `q` — Text search (case-insensitive, searches outcomes/reality/actions)
-- `level` — Filter by depth
-- `completed` — Boolean: all actions done?
-- `hasActions` — Boolean: has action steps?
-
-**Response**: `{ charts: Chart[], total: number, query: { q, level, completed, hasActions } }`
-
-### GET /api/jsonl — Read Memory File
-**Auth**: Not required  
-**Dependency**: Requires `COAIAV_MEMORY_PATH` environment variable to locate the JSONL file on disk  
-**Filename Resolution**: Uses `COAIAV_MEMORY_DISPLAY_NAME` if set, otherwise falls back to `path.basename(COAIAV_MEMORY_PATH)`. This preserves the original filename when Docker remaps paths to `/data/memory.jsonl`.  
-**Response**: `{ content: string, filename: string, path: string }`
-
-### POST /api/jsonl — Write Memory File
-**Auth**: Not required  
-**Body**: `{ content: string }`  
-**Behavior**: Creates timestamped backup, writes new content  
-**Response**: `{ success: true, backupPath: string }`
-
-### GET /api/watch — File Statistics
-**Auth**: Not required  
-**Response**: `{ lastModified: number, beatCount: number, fileSize: number, totalRecords: number }`  
-**Purpose**: Support live polling for file change detection
-
-### GET /api/audio/[filename] — Serve Audio
-**Auth**: Not required  
-**Security**: Only serves `.mp3` files from `COAIAV_AUDIO_DIR`  
-**Response**: Binary MP3 with 1-year cache header  
-
----
-
-## 📋 MCP Server (`mcp/`)
-
-### Configuration
-- **Transport**: stdio (standard input/output)
-- **API Base URL**: `COAIAV_API_URL` env var (default fallback: `http://localhost:3000`)
-- **Token**: `COAIAN_API_TOKEN` env var (required — server refuses to start without it)
-
-### 15 MCP Tools
-
-| # | Tool Name | Required Args | Optional Args | Maps To |
-|:---|:---|:---|:---|:---|
-| 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` | — | query, 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 of response data" }],
-  "isError": false
-}
-```
-Error responses set `isError: true` with error message in text field.
-
-### CoaiaVisualizerClient (`mcp/src/api-client.ts`)
-HTTP wrapper class used by the MCP server.
-
-> **Note**: The client uses a simplified `Chart` type (plain objects, not full `EntityRecord` instances). Entity names returned by the API may differ from those used internally by `ChartEditor` (e.g., API route params use `chartId` while ChartEditor methods reference `chart.chartEntity.name`).
-
-```typescript
-class CoaiaVisualizerClient {
-  constructor(config: { baseUrl: string, token: string })
-  
-  listCharts(options?): Promise<Chart[]>
-  getChart(id: string): Promise<Chart>
-  createChart(data): Promise<{ chartId: string }>
-  updateChart(id, updates): Promise<Chart>
-  createTelescopedChart(chartId, actionName): Promise<Chart>
-  deleteChart(id): Promise<void>
-  searchCharts(query): Promise<Chart[]>
-  getChartProgress(chart): number       // Local computation
-  getChartSummary(chart): string        // Local computation (100 char truncate)
-}
-```
-
----
-
-## 📋 Agent Access Scenario
-
-### Claude Desktop Configuration
-```json
-{
-  "mcpServers": {
-    "coaia-visualizer": {
-      "command": "node",
-      "args": ["path/to/mcp/dist/index.js"],
-      "env": {
-        "COAIAN_API_TOKEN": "your-token-here",
-        "COAIAV_API_URL": "http://localhost:3000"
-      }
-    }
-  }
-}
-```
-
-### Typical Agent Session
-```
-1. Agent calls list_charts → gets all chart summaries
-2. Agent calls get_chart(chartId) → gets full detail
-3. Agent calls update_current_reality → adds new observations
-4. Agent calls add_action_step → creates telescoped sub-chart
-5. Agent calls mark_action_complete → action done + parent updated
-6. Agent calls get_chart_progress → checks advancement percentage
-```
-
----
-
-## ✅ Quality Criteria
-
-✅ **API Completeness**
-- Every operation available in the web UI is also available via API
-- 15 MCP tools cover all chart lifecycle operations
-- Search supports text, level, completion, and action filters
-
-✅ **Authentication Security**
-- All chart mutation endpoints require Bearer token
-- Token from environment variable or auto-generated
-- Consistent 401 response for unauthorized requests
-
-✅ **Data Safety**
-- Timestamped backup created before every write
-- Recursive deletion handles sub-chart cascades
-- Error responses include descriptive messages
-
-✅ **Agent Ergonomics**
-- All responses are JSON (parseable by agents)
-- Tool descriptions include required/optional parameter documentation
-- MCP tools use JSON Schema inputSchema for parameter validation
-
----
-
-## 🔗 Related Components
-
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — ChartEditor class used by API routes
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — types shared between API and client
-- [cli-mode.spec.md](./cli-mode.spec.md) — CLI starts the server that API routes run on