coaia-visualizer 1.6.1 → 1.6.3

package/rispecs/app.spec.md

@@ -1,364 +0,0 @@
-# COAIA Visualizer — Application Specification
-## RISE Specification for the Complete Application
-
-> Interactive web-based visualizer and editor that transforms coaia-narrative JSONL memory files into navigable structural tension chart hierarchies with full editing, API access, and AI agent integration.
-
-**Document Version**: 1.0  
-**Framework**: RISE  
-**Component**: Application Root  
-**Target Audience**: LLM agents rebuilding or extending the visualizer, developers contributing to coaia-visualizer
-
----
-
-## 🎯 OVERVIEW: What COAIA Visualizer Enables Users to Create
-
-COAIA Visualizer enables users to **create living, interactive maps of structural tension** — making visible the creative gap between Current Reality and Desired Outcome across any number of interconnected charts.
-
-Users can:
-- **Upload JSONL memory files** and see them transformed into hierarchical chart structures
-- **Navigate structural tension charts** with telescoped sub-charts that fractal into deeper detail
-- **Edit desired outcomes, current reality observations, and action steps** directly in the UI
-- **Track creative advancement** through action completion, progress observations, and due dates
-- **View narrative beats** that document the story of structural work across multi-universe perspectives
-- **Explore relations** between charts, outcomes, realities, and actions
-- **Access all capabilities programmatically** via REST API and MCP server for AI agent workflows
-- **Deploy anywhere** via CLI, Docker, or Vercel
-
-This is **not** a project management tool or issue tracker. It is a **ceremonial instrument** for practitioners of structural tension — Robert Fritz's creative orientation methodology — who need to see, hold, and advance the tension between what is and what they want to create.
-
-### Distinction from Traditional Tools
-
-| Traditional Dashboard | COAIA Visualizer |
-|:---|:---|
-| Tracks problems to solve | Holds tension between reality and vision |
-| Status: open/closed/blocked | Status: advancing toward desired outcome |
-| Hierarchy = organizational breakdown | Hierarchy = telescoped depth of inquiry |
-| Completion = problem eliminated | Completion = structural tension resolved through creation |
-
----
-
-## 📊 CORE FUNCTIONAL COMPONENTS
-
-### 1. JSONL Parsing & Data Types Engine
-**Purpose**: Transform flat JSONL lines into structured chart hierarchies  
-**Spec File**: [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md)
-
-**What It Enables Users to Create**: Structured knowledge graphs from raw text memory files  
-**Natural Progression**:
-1. User provides JSONL content (file upload, API, or filesystem)
-2. `parseJSONL()` splits lines and parses JSON records
-3. `organizeData()` runs 4-pass algorithm: separate → assemble → populate → hierarchy
-4. Chart objects emerge with desired outcomes, current realities, actions, narrative beats
-5. Telescoped sub-charts are recognized and linked to parent charts
-6. Root charts (level 0) are identified for top-level navigation
-
-**Key Structural Dynamics**:
-- Entity/Relation model: EntityRecord (5 entity types) + RelationRecord (4 relation types)
-- Chart assembly from entity name patterns: `chart_N_desired_outcome`, `chart_N_current_reality`
-- Hierarchical linking via metadata.parentChart and level fields
-- Resilient parsing: malformed lines silently skipped
-
----
-
-### 2. Chart Visualization & Hierarchy
-**Purpose**: Render structural tension charts in navigable hierarchy and list views  
-**Spec File**: [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md)
-
-**What It Enables Users to Create**: Visual maps of structural tension at any depth  
-**Natural Progression**:
-1. ChartList renders root charts in hierarchy (tree) or flat list mode
-2. Each chart shows summary, progress bar, level badge, narrative beat indicators
-3. User selects a chart → ChartDetail or ChartDetailEditable appears
-4. Detail view shows desired outcome, current reality, actions, beats, relations
-5. User clicks telescope icon → navigates to sub-chart with back-button stack
-6. Breadcrumb-style navigation maintains context across depth levels
-
----
-
-### 3. Chart Editing Workflow
-**Purpose**: Enable direct manipulation of structural tension chart data  
-**Spec File**: [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md)
-
-**What It Enables Users to Create**: Updated charts reflecting creative advancement  
-**Natural Progression**:
-1. User hovers over desired outcome → edit button appears → click to edit
-2. User modifies text → saves → ChartEditor applies mutation
-3. Current reality observations can be added, edited, or removed individually
-4. Action steps support add, edit, complete, toggle, delete, and date changes
-5. Actions can telescope into full sub-charts (creating new chart hierarchies)
-6. New master charts can be created via dialog form or inline create form
-7. All changes tracked as unsaved until explicit save to filesystem/API
-
----
-
-### 4. REST API & MCP Interface
-**Purpose**: Provide programmatic access for AI agents and external tools  
-**Spec File**: [api-mcp-interface.spec.md](./api-mcp-interface.spec.md)
-
-**What It Enables Users to Create**: AI-augmented structural tension workflows  
-**Key Structural Dynamics**:
-- 6 REST API route groups: charts CRUD, search, JSONL I/O, watch, audio
-- 15 MCP tools mapped 1:1 to chart operations
-- Bearer token authentication via COAIAN_API_TOKEN
-- Backup creation before every write operation
-
----
-
-### 5. CLI & Deployment
-**Purpose**: Launch the visualizer from terminal with filesystem paths  
-**Spec File**: [cli-mode.spec.md](./cli-mode.spec.md)
-
-**What It Enables Users to Create**: Instant visualization of any local memory file  
-**Key Structural Dynamics**:
-- `coaia-visualizer --memory-path ./memory.jsonl` launches the full app
-- Docker mode for containerized deployment
-- Environment variable configuration for all settings
-- Auto-open browser with graceful shutdown
-
----
-
-### 6. Narrative Beats Display
-**Purpose**: Render the story layer of structural tension work  
-**Spec File**: [narrative-beats-display.spec.md](./narrative-beats-display.spec.md)
-
-**What It Enables Users to Create**: Visible narrative context for structural work  
-
----
-
-### 7. Relation Graph Visualization
-**Purpose**: Display inter-entity connections  
-**Spec File**: [relation-graph-visualization.spec.md](./relation-graph-visualization.spec.md)
-
-**What It Enables Users to Create**: Maps of kinship between charts, outcomes, and actions  
-
----
-
-### 8. UI Component Library
-**Purpose**: Provide consistent, themed UI primitives  
-**Spec File**: [ui-component-library.spec.md](./ui-component-library.spec.md)
-
----
-
-## 🔧 HOW COMPONENTS INTERCONNECT
-
-### Data Flow Architecture
-
-```
-                    ┌──────────────────────┐
-                    │   JSONL Source        │
-                    │  (File / API / CLI)   │
-                    └──────────┬───────────┘
-                               │
-                    ┌──────────▼───────────┐
-                    │   parseJSONL()        │
-                    │   organizeData()      │
-                    │   → ParsedData        │
-                    └──────────┬───────────┘
-                               │
-              ┌────────────────┼────────────────┐
-              │                │                │
-     ┌────────▼────┐  ┌───────▼──────┐  ┌──────▼──────┐
-     │  ChartList  │  │ ChartDetail  │  │  DataStats  │
-     │  (navigate) │  │ (view/edit)  │  │  (summary)  │
-     └─────────────┘  └──────┬───────┘  └─────────────┘
-                             │
-           ┌─────────────────┼───────────────────┐
-           │                 │                   │
-   ┌───────▼───────┐ ┌──────▼──────┐  ┌─────────▼─────────┐
-   │ Edit*         │ │ Narrative   │  │  RelationGraph    │
-   │ Components    │ │ Beats       │  │  (connections)     │
-   └───────┬───────┘ └─────────────┘  └───────────────────┘
-           │
-   ┌───────▼───────┐
-   │ ChartEditor   │
-   │ (mutations)   │
-   └───────┬───────┘
-           │
-   ┌───────▼───────┐     ┌────────────────┐
-   │ exportToJSONL │────▶│  POST /api/jsonl│
-   └───────────────┘     └────────────────┘
-```
-
-### Structural Advancement Pattern
-
-```
-Upload JSONL → Parse → Organize → Display Charts
-     │                                    │
-     │                              User Selects Chart
-     │                                    │
-     │                              View Structural Tension
-     │                              (Desired Outcome ↔ Current Reality)
-     │                                    │
-     │                              Edit / Add Actions / Telescope
-     │                                    │
-     │                              ChartEditor Mutates Entities
-     │                                    │
-     │                              Mark Actions Complete
-     │                              (auto-updates parent reality)
-     │                                    │
-     └──── Save to JSONL ◀───────── Export Changes
-```
-
----
-
-## 🎯 CREATIVE ADVANCEMENT SCENARIOS
-
-### Scenario 1: First-Time Visualization
-**User Intent**: See my coaia-narrative memory file as interactive charts  
-**Current Structural Reality**: Raw JSONL file with hundreds of lines, no visual structure  
-**Natural Progression**:
-1. User opens coaia-visualizer in browser
-2. Uploads `.jsonl` file via drag-drop or file picker
-3. parseJSONL processes all lines, skipping malformed entries
-4. organizeData assembles charts with telescoped hierarchy
-5. ChartList shows root charts with summaries and progress bars
-6. User selects first chart → sees desired outcome, current reality, actions
-7. DataStats shows total charts, actions completed/total, entities, relations
-**Supporting Features**: FileUpload (drag-drop), organizeData (4-pass), DataStats (summary cards)
-
-### Scenario 2: Advancing Through Structural Tension
-**User Intent**: Update my charts to reflect creative progress  
-**Current Structural Reality**: Charts exist but reality observations are outdated  
-**Natural Progression**:
-1. User selects chart from hierarchy view
-2. Hovers over current reality section → edit buttons appear
-3. Adds new observation: "Completed initial prototype"
-4. Marks action step as complete → parent current reality auto-updates
-5. Creates new action step with specific current reality assessment
-6. Telescopes complex action into sub-chart for detailed tracking
-7. Saves all changes → backup created → JSONL persisted
-**Supporting Features**: EditCurrentReality, EditActionStep, ChartEditor (mutations), API backup
-
-### Scenario 3: AI Agent Workflow
-**User Intent**: Let my AI agent manage structural tension charts programmatically  
-**Current Structural Reality**: Charts exist in JSONL but agent has no access  
-**Natural Progression**:
-1. Start visualizer with `--memory-path` and `COAIAN_API_TOKEN`
-2. Configure Claude Desktop with MCP server connection
-3. Agent calls `list_charts` to survey existing charts
-4. Agent calls `create_chart` with desired outcome and current reality
-5. Agent calls `add_action_step` to create telescoped sub-charts
-6. Agent calls `mark_action_complete` as work progresses
-7. Agent calls `get_chart_progress` to assess advancement
-**Supporting Features**: MCP server (15 tools), REST API, Bearer token auth
-
----
-
-## 📋 Page State Management
-
-The main page (`app/page.tsx`) serves as the primary orchestrator, managing all application state through React hooks:
-
-### useState Hooks (7)
-```typescript
-const [data, setData] = useState<ParsedData | null>(null)         // Parsed chart data
-const [selectedChart, setSelectedChart] = useState<Chart | null>(null) // Currently viewed chart
-const [chartNavigationStack, setChartNavigationStack] = useState<Chart[]>([]) // Back-nav stack
-const [viewMode, setViewMode] = useState<"hierarchy" | "list">("hierarchy") // List display mode
-const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false) // Dirty flag for save prompt
-const [activeTab, setActiveTab] = useState<string>("upload")      // Upload/Create tab toggle
-const [isLive, setIsLive] = useState(false)                       // Live polling flash state
-```
-
-### Auto-Load Behavior
-On mount, the page checks for server-side JSONL data availability:
-1. Fetches `/api/jsonl` to check if a memory file is configured
-2. If content is returned → parses and sets data automatically (no upload needed)
-3. If no content → shows Upload/Create tab interface
-4. This enables the CLI `--memory-path` workflow to display charts immediately
-
----
-
-## 🛠️ IMPLEMENTATION REQUIREMENTS
-
-### Technology Stack
-- **Runtime**: Next.js 16.0.10 + React 19.2.0 + TypeScript
-- **Styling**: Tailwind CSS 4.1.9 with dark/light theme via next-themes
-- **UI Primitives**: Radix UI (20+ components) with shadcn patterns
-- **Charts**: recharts 2.15.4
-- **Forms**: react-hook-form + zod 3.25.76 validation
-- **Icons**: lucide-react
-- **Toast**: sonner
-- **MCP**: @modelcontextprotocol/sdk 1.25.2
-- **Deployment**: Vercel, Docker (node:22-alpine), CLI (npm global)
-
-### Core Data Structures
-
-```typescript
-interface EntityRecord {
-  type: "entity"
-  name: string
-  entityType: "structural_tension_chart" | "desired_outcome" | 
-              "current_reality" | "action_step" | "narrative_beat"
-  observations: string[]
-  metadata: Record<string, any>
-}
-
-interface RelationRecord {
-  type: "relation"
-  from: string
-  to: string
-  relationType: "contains" | "creates_tension_with" | 
-                "advances_toward" | "documents"
-  metadata: Record<string, any>
-}
-
-interface Chart {
-  id: string
-  chartEntity: EntityRecord
-  desiredOutcome?: EntityRecord
-  currentReality?: EntityRecord
-  actions: EntityRecord[]
-  narrativeBeats: EntityRecord[]
-  subCharts: Chart[]
-  level: number
-  parentChart?: string
-  relations: RelationRecord[]
-}
-
-interface ParsedData {
-  charts: Chart[]
-  entities: Map<string, EntityRecord>
-  relations: RelationRecord[]
-  rootCharts: Chart[]
-}
-```
-
----
-
-## ✅ QUALITY CRITERIA FOR IMPLEMENTATION
-
-✅ **Structural Tension Preserved**
-- Every chart displays the tension between desired outcome and current reality
-- Creative language maintained throughout (create, build, establish — never fix, solve, eliminate)
-- Action completion advances parent current reality automatically
-
-✅ **Navigation Integrity**
-- Telescoped hierarchies navigate correctly with back-button stack
-- Sub-charts link bidirectionally to parents
-- Root charts always accessible from top-level list
-
-✅ **Data Fidelity**
-- JSONL round-trip: upload → edit → export produces valid JSONL
-- Malformed lines silently skipped, never corrupt valid data
-- Backup created before every write operation
-
-✅ **Agent Accessibility**
-- All 15 MCP tools produce consistent JSON responses
-- REST API returns proper HTTP status codes with error messages
-- Token authentication protects all mutating endpoints
-
----
-
-## 🔗 Component Specification Files
-
-| Spec File | Focus |
-|:---|:---|
-| [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) | Parsing, types, data organization |
-| [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) | Chart display and navigation |
-| [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) | Edit operations and ChartEditor |
-| [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) | REST API and MCP server |
-| [cli-mode.spec.md](./cli-mode.spec.md) | CLI launcher and Docker |
-| [narrative-beats-display.spec.md](./narrative-beats-display.spec.md) | Narrative beat rendering |
-| [relation-graph-visualization.spec.md](./relation-graph-visualization.spec.md) | Entity relation graphs |
-| [ui-component-library.spec.md](./ui-component-library.spec.md) | UI primitives and theming |
-| [accountability-responsibility.rispec.md](./accountability-responsibility.rispec.md) | Accountability/responsibility visual distinction |

package/rispecs/chart-editing-workflow.spec.md

@@ -1,297 +0,0 @@
-# Chart Editing Workflow
-## RISE Specification for Chart Mutations, Edit Components, and Creation Flows
-
-**Component Purpose**: Enable direct manipulation of structural tension chart data — editing desired outcomes, current reality observations, action steps, due dates, and chart creation — all through a consistent ChartEditor mutation pattern.
-
-**Source Files**: `lib/chart-editor.ts`, `components/edit-desired-outcome.tsx`, `components/edit-current-reality.tsx`, `components/edit-action-step.tsx`, `components/edit-chart-due-date.tsx`, `components/add-action-step.tsx`, `components/add-master-chart.tsx`, `components/create-chart-form.tsx`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Updated desired outcomes reflecting refined creative vision
-- New current reality observations documenting honest assessment of what is
-- Action steps that advance toward desired outcomes
-- Telescoped sub-charts from action steps for deeper structural exploration
-- New master charts establishing fresh structural tension
-- Due date targets for charts and individual action steps
-- Completion tracking that automatically updates parent chart reality
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-JSONL files are flat text. Editing means manipulating entity records, maintaining referential integrity across relations, auto-incrementing chart IDs, and propagating completion status to parent charts. All mutations must be serializable back to valid JSONL.
-
-### Desired Result
-A unified editing experience where every structural tension element can be modified inline, with changes flowing through a single `ChartEditor` class that guarantees:
-- Entity integrity (names, types, references preserved)
-- Relation consistency (no orphaned references)
-- Automatic side-effects (completion updates parent reality)
-- Timestamp tracking on every mutation
-- Serializable output for persistence
-
-### Natural Resolution
-The `ChartEditor` class encapsulates all mutation logic. Edit components provide UI for specific operations and delegate to ChartEditor via the `applyEdit()` pattern in `ChartDetailEditable`.
-
----
-
-## 📋 ChartEditor Class
-
-### Constructor
-```typescript
-constructor(parsedData: ParsedData)
-```
-Creates a new Map from entities and a new array from relations (SHALLOW copies — entity objects are shared references). Mutations to entity properties (observations, metadata) will affect the original ParsedData. This is a known design trade-off.
-
-### ChartUpdate Interface
-```typescript
-interface ChartUpdate {
-  type: "update_desired_outcome" | "update_current_reality" | "add_observation"
-        | "update_action" | "add_action" | "delete_action"
-        | "toggle_action_completion" | "update_due_date" | "update_action_due_date"
-  chartId: string
-  data: any
-}
-```
-
-### Mutation Methods
-
-| Method | Signature | Side Effects |
-|:---|:---|:---|
-| `updateDesiredOutcome` | `(chartId, newText)` | Replaces observations[0], sets updatedAt |
-| `addCurrentRealityObservation` | `(chartId, observation)` | Pushes to observations[], sets updatedAt |
-| `updateCurrentReality` | `(chartId, newObservations[])` | Deduplicates and merges, sets updatedAt |
-| `updateCurrentRealityObservation` | `(chartId, index, newText)` | Updates specific observation at index |
-| `deleteCurrentRealityObservation` | `(chartId, index)` | Removes observation at index |
-| `addActionStep` | `(parentChartId, title, reality, dueDate?)` | **Creates new telescoped chart** with desired_outcome, current_reality, 4 relations. Uses `chart.chartEntity.name` to find the parent chart entity. Auto-calculates dueDate as midpoint between now and parent dueDate |
-| `updateActionStep` | `(chartId, actionName, description)` | Updates action observations |
-| `markActionStepComplete` | `(actionStepName)` | Sets completionStatus=true, appends "Completed: ..." to parent current_reality |
-| `updateActionProgress` | `(actionStepName, observation, updateReality?)` | Appends to action observations, optionally updates parent current_reality with "Progress on ..." |
-| `toggleActionCompletion` | `(actionName)` | Toggles completionStatus, sets/deletes completedAt |
-| `updateActionDueDate` | `(actionName, dueDate)` | Updates action entity dueDate metadata. **Note**: Only operates on entities with entityType `action_step`. |
-| `deleteActionStep` | `(actionName)` | Removes entity and all connected relations |
-| `createTelescopedChartFromAction` | `(parentChartId, actionName)` | Converts existing action to full sub-chart, marks original with isTelescopedChart flag. Default current reality: `"Starting work on this action step"` |
-| `updateChartDueDate` | `(chartId, dueDate)` | Updates chart entity dueDate metadata |
-
-### Output Methods
-
-| Method | Returns | Purpose |
-|:---|:---|:---|
-| `exportToJSONL()` | `string` | Serializes all entities then relations as JSONL |
-| `getUpdatedData()` | `ParsedData` | Rebuilds ParsedData from current entities/relations |
-
-### Entity Naming Convention
-All entities follow the pattern: `{chartId}_{entityType}`
-- `chart_1_desired_outcome`
-- `chart_1_current_reality`
-- `chart_1_action_1`, `chart_1_action_2`, etc.
-
-### Chart ID Auto-Increment
-```
-Find max N from all existing chart_N entities
-New chart ID = chart_(N+1)
-```
-
-### Timestamp Convention
-All mutations set `metadata.updatedAt = new Date().toISOString()` (ISO 8601)
-
----
-
-## 📋 Edit Components
-
-### EditDesiredOutcome
-```
-┌────────────────────────────────────────┐
-│ ✦ Desired Outcome          [✏️ hover] │
-│                                        │
-│ "Build a structural tension visualizer │
-│  that makes creative advancement       │
-│  visible and navigable"                │
-│                                        │
-└────────────────────────────────────────┘
-```
-- **Display mode**: Teal-colored box with observation text and hover-triggered pencil icon
-- **Edit mode**: Textarea with Save/Cancel buttons
-- **Validation**: Non-empty text required
-- **Callback**: `onSave(newText: string)`
-
-### EditCurrentReality
-```
-┌────────────────────────────────────────┐
-│ ◈ Current Reality                      │
-│                                        │
-│ • "JSONL parser handles all 5 entity   │
-│    types correctly"          [✏️] [🗑️] │
-│                                        │
-│ • "Chart hierarchy displays 3 levels   │
-│    but navigation stack incomplete"    │
-│                              [✏️] [🗑️] │
-│                                        │
-│ [+ Add Observation]                    │
-└────────────────────────────────────────┘
-```
-- **Display mode**: List of observations in amber-colored boxes, each with hover edit/delete icons
-- **Edit mode**: Per-observation textarea with Save/Cancel
-- **Add mode**: Separate textarea for new observations
-- **Callbacks**: `onUpdate(index, newText)`, `onAdd(observation)`, `onDelete(index)`
-
-### EditActionStep
-```
-┌──────────────────────────────────────────────────────┐
-│ [○] [🔭]  1. Design entity type system  [✏️] [📅] [🗑️] │
-│                                          (hover toolbar)  │
-│           Due: 2024-03-15                                 │
-│                                                           │
-│ [✓] [🔭→] 2. Implement parsing (chart_4) ✦ Telescoped    │
-│           Due: 2024-03-20  ✓ Completed                    │
-└───────────────────────────────────────────────────────────┘
-```
-- **Completion toggle**: Circle (incomplete) / Check (complete) button on left
-- **Telescope button**: Creates or navigates to sub-chart
-  - Gradient background if already telescoped
-  - Different icon states for "create" vs "navigate"
-- **Hover toolbar**: Edit, Date picker, Delete buttons appear on hover
-- **Edit mode**: Textarea with Save/Cancel for description
-- **Date picker**: Calendar popover with clear option
-- **Callbacks**: `onUpdate`, `onToggleComplete`, `onMarkComplete`, `onUpdateDueDate`, `onDelete`, `onNavigateToChart`, `onCreateTelescopedChart`
-
-### EditChartDueDate
-- Popover trigger showing current date or "Set due date"
-- Calendar picker with clear button
-- **Callback**: `onUpdate(date: string | null)`
-
----
-
-## 📋 Creation Components
-
-### AddActionStep
-```
-[+ Add Action Step]  ← collapsed state
-
-┌────────────────────────────────┐
-│ Action Title *                 │
-│ ┌────────────────────────────┐ │
-│ │                            │ │
-│ └────────────────────────────┘ │
-│                                │
-│ Current Reality *              │
-│ ┌────────────────────────────┐ │
-│ │ Honest assessment of where │ │
-│ │ this action starts from    │ │
-│ └────────────────────────────┘ │
-│                                │
-│ Due Date (optional)            │
-│ [📅 Pick date]                 │
-│                                │
-│ [Save] [Cancel]                │
-└────────────────────────────────┘
-```
-- Collapsible: button toggles to form
-- **Required**: Action title + Current reality (creative orientation enforced)
-- **Optional**: Due date via calendar popover
-- Calls `ChartEditor.addActionStep()` which creates a full telescoped sub-chart
-
-### AddMasterChart (Dialog)
-- Plus icon button triggers dialog
-- Fields: Desired Outcome (textarea), Current Reality Observations (multiple textareas with add/remove), Due Date (date input)
-- Creates 3 entities (chart, desired_outcome, current_reality) and 3 relations
-- Generates next chart_N ID automatically
-
-### CreateChartForm (Inline)
-- Card-based form embedded in the main page's "Create" tab
-- Same fields as AddMasterChart but inline instead of dialog
-- Creates complete ParsedData structure for new chart
-- Validates required fields (desired outcome + at least one observation)
-
----
-
-## 📋 Edit Flow Integration
-
-### applyEdit Pattern (in ChartDetailEditable)
-```typescript
-function applyEdit(editFn: (editor: ChartEditor) => void) {
-  const editor = new ChartEditor(data)  // Clone current state
-  editFn(editor)                         // Apply mutation
-  const updatedData = editor.getUpdatedData()  // Rebuild ParsedData
-  onUpdate(updatedData)                  // Propagate to parent
-}
-```
-
-### Parent State Management (in Page)
-```typescript
-handleDataUpdate(updatedData: ParsedData):
-  1. Set data = updatedData
-  2. Set hasUnsavedChanges = true
-  3. Find selectedChart in updated data (maintain selection)
-  4. Update selectedChart reference
-```
-
-### Save Flow
-```
-User clicks Save
-  → ChartEditor.exportToJSONL() produces JSONL string
-  → POST /api/jsonl with content body
-  → API creates timestamped backup
-  → API writes new content to memory file
-  → hasUnsavedChanges = false
-  → Toast notification confirms save
-```
-
----
-
-## 📋 Creative Advancement Scenario
-
-### Scenario: Telescoping an Action Into Depth
-**User Intent**: Break a complex action step into a full structural tension chart  
-**Current Structural Reality**: Action "Design authentication system" sits as a single line item  
-**Desired Outcome**: A sub-chart with its own desired outcome, current reality, and action steps
-
-**Natural Progression**:
-1. User hovers over the action → telescope icon appears
-2. User clicks telescope → `ChartEditor.createTelescopedChartFromAction()` fires
-3. New `chart_N` created with:
-   - level = parent.level + 1
-   - desired_outcome = action's description text
-   - current_reality = "Starting work on this action step"
-   - parentChart = parent's chart ID
-   - dueDate = midpoint between now and parent's dueDate
-4. Original action marked with `isTelescopedChart: true` and `telescopedChartId`
-5. New chart appears in parent's sub-charts list
-6. UI navigates to new chart (pushed onto navigation stack)
-7. User can now add actions, observations, and further telescope within the sub-chart
-
----
-
-## ✅ Quality Criteria
-
-✅ **Mutation Integrity**
-- ChartEditor clones data — no external state mutation
-- Every mutation timestamps with ISO 8601 updatedAt
-- Entity names and relation references always consistent
-
-✅ **Completion Propagation**
-- Marking action complete auto-updates parent current reality
-- Completion status toggles cleanly between true/false
-- CompletedAt timestamp set/cleared appropriately
-
-✅ **Telescoping Correctness**
-- New sub-charts always have level = parent.level + 1
-- Parent-child relations created bidirectionally
-- Original action flagged with telescoped metadata
-- Due date auto-calculated as midpoint
-
-✅ **Edit UX**
-- All edit components require non-empty validation
-- Hover-triggered toolbars prevent visual clutter
-- Cancel always reverts to original value
-- Add forms collapse to single button when not in use
-
----
-
-## 🔗 Related Components
-
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — type system consumed and produced by ChartEditor
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — display components that host edit components
-- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API routes that invoke ChartEditor for server-side mutations