coaia-visualizer 1.6.3 → 1.6.5

package/rispecs/app.spec.md

@@ -0,0 +1,364 @@
+# 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

@@ -0,0 +1,297 @@
+# 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