coaia-visualizer 1.6.1 → 1.6.3

package/rispecs/github-project-runtime-memory-integration.spec.md

@@ -1,381 +0,0 @@
-# 🔮 Future Integration: GitHub Project Runtime-Memory Visualization
-
-> How coaia-visualizer COULD render GitHub-Project sync state, project-field
-> provenance, and GitHub-linked action steps so charts produced and synced by
-> the `coaia-github` bridge gain a living "Project lens" without breaking
-> the current rendering pipeline.
-
-**Status**: 🔮 FUTURE / ASPIRATIONAL · spec-only · additive
-**Last Updated**: 2026-05-09
-**Framework**: RISE (Reverse-engineer · Intent-extract · Specify · Export)
-**Cross-references**:
-- [`README.md`](./README.md) — visualizer pillars, 4-pass parse, current components
-- [`pde-integration.spec.md`](./pde-integration.spec.md) — companion future spec, PDE source rendering
-- [`planning-integration.spec.md`](./planning-integration.spec.md) — companion future spec, plan source + sync state rendering
-- [`relation-graph-visualization.spec.md`](./relation-graph-visualization.spec.md) — current relation rendering, grouping by `relationType`
-- `coaia-narrative/rispecs/coaia-github/github-project-runtime-memory-schema-bridge.spec.md` — schema-bridge proposal that produces the metadata this spec consumes
-- `coaia-narrative/rispecs/coaia-github/README.md` — canonical Amun field map
-- `coaia-narrative/rispecs/schema-evolution-and-ecosystem-metadata.spec.md` — typed sub-object pattern (`metadata.pde`, `metadata.plan`, `metadata.accountability`, `metadata.source`)
-- mightyeagle worktree proposal: `rispecs/miadi-code/miadi-agent/orchestration-proposals/260509-github-projects-structural-runtime-memory.md`
-- `jgwill/coaia-agent#18` — runtime/visualizer container context (informational; this spec does not depend on it)
-
----
-
-## 1. Position Among Future-Integration Specs
-
-This spec is the third in a small family that all share the same posture:
-
-| Spec | Surfaces | Source metadata it reads |
-|---|---|---|
-| `pde-integration.spec.md` | Four-Directions quadrant, PDE provenance breadcrumb, implicit-intent badges, confidence bars | `pde_session` line, `metadata.pde.*` (per schema-evolution spec) |
-| `planning-integration.spec.md` | Plan source badge, parse-confidence color, plan-sync state, source-line link, re-sync action | `metadata.plan.*` |
-| **this spec** — `github-project-runtime-memory-integration.spec.md` | Project source badge, project-field provenance trail, sync-state indicator, project lens switcher, GitHub-linked action step badges | `metadata.github.*`, `metadata.source.system === 'coaia-github'` |
-
-The three specs **compose**: a single chart can carry PDE provenance, a
-plan link, and a GitHub Project mirror simultaneously. None of them
-replaces or hides the others. This spec is the GitHub layer of the same
-provenance trail.
-
----
-
-## 2. Structural Tension
-
-### 2.1 Current Reality
-- coaia-visualizer treats every chart identically. A chart with
-  `metadata.github.issue` populated looks the same as a hand-authored
-  chart. The 4-pass parse algorithm (`organizeData()`) does not look at
-  `metadata.github.*`, `metadata.source.system === 'coaia-github'`, nor at
-  any `gh:<owner>/<repo>#<num>` virtual entity Encoding B might produce.
-- coaia-visualizer does not write to GitHub at all. Today this is the
-  correct boundary — the visualizer is a renderer, not a bridge — but it
-  also means a practitioner inside the visualizer cannot see whether a
-  chart they are looking at has drifted from its GitHub Project mirror.
-- The relation graph component groups by `relationType` only. Custom-typed
-  relations carrying canonical names like `synced_to_github` (per the
-  schema-bridge spec §4) appear as a generic `custom` group with no
-  affordance.
-- Issue `jgwill/coaia-agent#18` ships the visualizer alongside
-  `coaia-narrative` inside the same `coaia-agent` runtime; that means once
-  the GitHub-bridge metadata is being written, the visualizer is the
-  natural surface to inspect it.
-
-### 2.2 Desired Outcome
-A chart that has been mirrored to a GitHub Project carries that fact
-**visibly** in the visualizer:
-- A `🪐 Project` source badge appears alongside the existing `🔬 PDE` and
-  `📋 Plan` badges.
-- A small sync-state pill (`✅ synced`, `⚠️ diverged`, `❌ conflict`,
-  `🌐 project-only`, `📂 chart-only`) sits under the badge.
-- A "Project lens" dropdown lets the practitioner switch between project
-  contexts when more than one Project mirrors the same chart.
-- Action steps with their own `metadata.github.issue` show a small issue
-  ref badge inline.
-- The relation-graph panel surfaces `synced_to_github` (and adjacent
-  bridge relations) under a dedicated section — not buried in `custom`.
-- A provenance trail row at the chart header reads:
-  `💬 Original Prompt → 🔬 PDE Decomposition → 📊 STC Chart → 🪐 GitHub Project Item`
-  whenever each segment is present.
-
-### 2.3 Tension
-The tension is between **the existing 4-pass parse algorithm** (which
-treats JSONL as a flat stream of entities and relations) and **the new
-provenance dimension** GitHub-bridge metadata adds. Resolution: the parse
-algorithm stays unchanged; rendering reads `metadata.github.*` opportunistically;
-no schema authority moves into the visualizer.
-
----
-
-## 3. Non-Breaking Posture
-
-This spec commits to four invariants:
-
-1. **No change to the 4-pass parse algorithm in `organizeData()`.** New
-   visualizer logic reads `metadata.github` after parsing, never during.
-2. **No new entity-type rendering path.** Encoding B virtual entities
-   (`entityType: "custom"`, `name: "gh:<owner>/<repo>#<num>"`) render via
-   the existing `custom` entity branch with a new optional badge — they do
-   not become first-class chart components.
-3. **No new relation-type enum reliance.** Bridge relations land via
-   `relationType: "custom"` with `metadata.context` carrying the canonical
-   name; the visualizer reads `metadata.context` to group them under a
-   "GitHub bridge" section. If `coaia-narrative` later promotes those
-   names, the visualizer reads the promoted form transparently.
-4. **No write path to GitHub.** The visualizer never calls `sync_*` tools.
-   Re-sync triggers are *advisory UI* (a button) that surface the bridge
-   tool name and arguments for the user to invoke through the runtime
-   (coaia-agent / coaia-narrative MCP). This mirrors the planning
-   integration's "re-sync trigger" affordance.
-
----
-
-## 4. Visual Surfaces
-
-### 4.1 Project Source Badge
-
-Component: `ProjectSourceBadge` (new, sibling to the proposed
-`PdeSourceBadge` and `PlanSourceBadge`).
-
-```
-🪐 Project: <ownerLogin>/<projectNumber> · <projectTitle>   [✅ synced]
-```
-
-| Element | Source | Style |
-|---|---|---|
-| `🪐` icon | constant | `indigo-500` to distinguish from `🔬` (amber, PDE) and `📋` (violet, plan) |
-| project ref | `metadata.github.projectItem.{projectOwner,projectNumber}` | tooltip exposes `itemId`, `url`, `projectTitle` |
-| sync pill | `metadata.github.syncState` | green `synced`, amber `diverged`, red `conflict`, slate `project-only`/`chart-only` |
-| lens switcher | when `metadata.github.projectItems` (plural) is present | small dropdown under the badge |
-
-**Trigger**: render only when `metadata.github.issue` exists on the chart
-entity OR when `metadata.source.system === 'coaia-github'` is set.
-
-### 4.2 Issue Ref Badge on Action Steps
-
-Component: `ActionStepIssueBadge`.
-
-```
-☐ Implement field hash routine                               [🪐 #142]
-```
-
-The badge shows `#<number>` only; tooltip expands to
-`<owner>/<repo>#<number>` and the issue URL. Render when an action_step
-entity has `metadata.github.issue`.
-
-### 4.3 Sync-State Pill (chart and action step)
-
-Same pill component reused at chart level (under the project source
-badge) and at action-step level (next to the issue ref badge, only when
-the per-action `metadata.github.syncState` exists). Identical color
-language as the planning-integration sync indicator (§ 1 of
-`planning-integration.spec.md`), so the practitioner reads sync state the
-same way for plans and projects.
-
-### 4.4 Provenance Trail Extension
-
-`pde-integration.spec.md` already proposes the breadcrumb component
-`ProvenanceTrail`. This spec extends it with a final segment when GitHub
-metadata is present:
-
-```
-💬 Original Prompt → 🔬 PDE Decomposition → 📊 STC Chart → 🪐 GitHub Project Item
-```
-
-Each segment remains independently optional. If only PDE and Project
-exist (no plan), the breadcrumb has three segments. Rendering rule: a
-segment appears iff its source metadata exists.
-
-### 4.5 Relation-Graph Section
-
-`relation-graph-visualization.spec.md` groups relations by `relationType`.
-Proposed extension: when grouping, peek at `metadata.context` for
-`custom`-typed relations and pull canonical bridge names into a separate
-"GitHub bridge" header section.
-
-```
-[GitHub bridge] (2)
-  synced_to_github
-    chart_42 → gh:jgwill/coaia-narrative#187           [✅ synced]
-  linked_to_issue
-    chart_42_action_2 → gh:jgwill/coaia-agent#18       [(unstored)]
-```
-
-This section appears only when at least one bridge relation exists. It
-keeps the existing flat-list rendering for charts with no GitHub metadata
-unchanged.
-
-### 4.6 Project Lens Switcher (multi-lens, deferred shape)
-
-When a chart's `metadata.github.projectItems` carries multiple project
-items, the project source badge gains a dropdown that lets the user pick
-which project's lens is "active" in the current visualizer view.
-"Active lens" is a UI state only — it does not change the JSONL. Switching
-lenses changes:
-
-- which `projectTitle` and `projectNumber` show in the badge,
-- which `Status` value the visualizer reads (Status is per project-item),
-- which `accountable_to` / `responsible_for` fields the visualizer prefers
-  if multiple project items disagree (rare but possible).
-
-Default lens: the first item in `projectItems`, OR `projectItem` (singular).
-Deferred until plural form is observed in real JSONL.
-
----
-
-## 5. Metadata Required From `coaia-narrative`
-
-This is the contract the schema-bridge spec must keep. The visualizer can
-do its job iff `metadata.github` follows the schema-bridge spec §3 shape.
-Concretely the visualizer reads, in this order of preference:
-
-1. `entity.metadata?.github?.issue` (canonical)
-2. `entity.metadata?.sync_target` (deprecated shorthand on chart)
-3. `entity.metadata?.github_ref` (deprecated shorthand on action step)
-
-For sync state:
-
-1. `entity.metadata?.github?.syncState`
-2. otherwise: visualizer renders no sync pill (silence is data — same
-   convention as `coaia-github` field resolution §9).
-
-For project context:
-
-1. `entity.metadata?.github?.projectItem`
-2. `entity.metadata?.github?.projectItems[0]`
-3. `entity.metadata?.sync_target` (legacy fallback)
-
-For source attribution:
-
-1. `entity.metadata?.source?.system === 'coaia-github'` → render
-   "Last synced by `coaia-github` (`<toolName>`) at `<lastSyncedAt>`" on hover.
-
-The visualizer MUST NOT invent any of the above. If metadata is absent,
-the corresponding surface is absent.
-
----
-
-## 6. What Is Not Stored in the Visualizer
-
-To keep the boundary clean, the visualizer:
-
-- Does not cache GitHub responses. Each render reads only what's in JSONL.
-- Does not maintain a separate "project view" data structure. Project lens
-  rendering is computed per-render from the chart's `metadata.github.*`.
-- Does not ship API tokens or auth flows. Those live in whichever runtime
-  hosts `coaia-github` MCP tools.
-- Does not show "live" GitHub state. If the practitioner needs live state,
-  they invoke `sync_project_to_chart` through the runtime; the visualizer
-  then reflects the refreshed JSONL on the next reload.
-
-This matches the existing pillar from `README.md`: the visualizer is a
-ceremonial instrument for holding tension visible — not a network client.
-
----
-
-## 7. Connection to `jgwill/coaia-agent#18`
-
-Issue #18 ships the visualizer inside the `coaia-agent` runtime so the
-runtime can act as a service. That makes the visualizer the **natural
-surface** to inspect what the GitHub bridge has done. Two specific
-implications:
-
-1. The visualizer process can rely on whatever JSONL `coaia-agent` writes
-   (per `pde-stc-session-lifecycle.spec.md` and
-   `visualizer-planning-narrative-flow.spec.md`). When `coaia-agent` later
-   invokes `coaia-github` MCP tools, the resulting `metadata.github.*`
-   appears in the same JSONL the visualizer is already watching (envs
-   `COAIAN_MF`, `COAIAV_PORT`, `COAIAV_AUDIO_DIR`).
-2. The "re-sync trigger" UI (§ 4) sends the canonical MCP tool name and
-   arguments back to the runtime. It does not call GitHub directly. This
-   keeps the visualizer port-bound (`4421:4321`, `4422:4422`) and free of
-   credentials.
-
-This spec does not require issue #18 to land before it can be implemented.
-The metadata it consumes can come from any runtime that uses the
-`coaia-github` bridge.
-
----
-
-## 8. Composition With PDE and Plan Specs (no duplication)
-
-| Concern | Owned by |
-|---|---|
-| Four-Directions quadrant view | `pde-integration.spec.md` |
-| Implicit-intent / confidence rendering | `pde-integration.spec.md` |
-| Plan source badge / parse confidence color | `planning-integration.spec.md` |
-| Plan ↔ chart sync indicator | `planning-integration.spec.md` |
-| Project source badge / project field provenance | **this spec** |
-| Project ↔ chart sync indicator | **this spec** |
-| Project lens switcher (multi-perspective) | **this spec** |
-| Provenance trail breadcrumb | `pde-integration.spec.md` (defines), this spec (extends) |
-| Relation-graph rendering | `relation-graph-visualization.spec.md` (defines), this spec (extends with GitHub-bridge section) |
-| 4-pass parse algorithm | `jsonl-parsing-data-types.spec.md` (unchanged) |
-
-When two indicators apply (e.g. a chart with both plan-sync state and
-project-sync state), they render side-by-side in the chart header. They
-do not collapse, because they describe different bridges.
-
----
-
-## 9. First Implementation Slice (3–5 steps)
-
-Each step is named with a RISE phase.
-
-1. **Specify**: land this document. Add a row to the `Future Integration
-   Specs` section of `README.md` linking it (one-line entry, additive).
-   *(Spec-only.)*
-2. **Reverse-engineer**: read one real `.coaia/pde/<uuid>.jsonl` file
-   produced after the schema-bridge spec's §10 step 5 ("smallest end-to-
-   end exercise"). Confirm that `metadata.github.*` is present and
-   matches the bridge spec §3 shape. If it does not, file findings into
-   the bridge spec's open questions before any UI work begins.
-3. **Intent-extract**: decide which surface lands first. Recommendation:
-   project source badge + sync-state pill (§4.1, §4.3). They are the
-   smallest visible win and exercise the dual-read fallback in §5.
-4. **Specify**: write a tight component-level rispec
-   `components/project-source-badge.spec.md` here in
-   `coaia-visualizer/rispecs/` that names the component shape, props, and
-   trigger conditions. *(Still spec-only — implementation is a later
-   issue.)*
-5. **Export**: when steps 2–4 hold, produce a single PR that adds the
-   `ProjectSourceBadge` and the sync-state pill, gated behind a feature
-   flag (`COAIAV_GITHUB_BRIDGE=1`). The flag protects existing JSONL
-   renders from any visual change. Do not ship the lens switcher,
-   provenance-trail extension, or relation-graph section in the same PR.
-
-Steps 1, 3, and 4 are spec-only. Step 2 is a single-file inspection. Step
-5 is the smallest UI exercise that does not require the relation-graph
-section or lens switcher.
-
----
-
-## 10. Quality Criteria
-
-- [x] No change required to `jsonl-parsing-data-types.spec.md` or to the
-      4-pass parse algorithm.
-- [x] No new `entityType` reliance. Encoding B virtual entities render via
-      the existing `custom` entity branch.
-- [x] No new `relationType` enum reliance. Bridge relations enter via
-      `relationType: "custom"` plus `metadata.context`.
-- [x] All UI surfaces are conditional on metadata existence.
-- [x] No write path to GitHub from the visualizer.
-- [x] Composition with `pde-integration.spec.md` and
-      `planning-integration.spec.md` is explicit and side-by-side, not
-      replacement.
-- [x] Required metadata shape is identical to the bridge spec §3 — no
-      visualizer-specific schema.
-- [x] First slice is small enough to ship behind a feature flag.
-
----
-
-## 11. Open Questions
-
-1. **Color choice for `🪐` Project badge.** Indigo proposed to distinguish
-   from PDE-amber and Plan-violet; final choice deferred to the design
-   pass that produces real component CSS.
-2. **What does sync-state `project-only` show on a chart card?**
-   Recommendation: render the chart with a slate "ghost" treatment and a
-   "Imported from project — chart not yet established" hint. Decision
-   deferred until the `sync_project_to_chart` MCP tool ships and produces
-   real `project-only` entities.
-3. **Relation-graph section for bridge relations.** Should
-   `synced_to_github` to a virtual `gh:` target render as an external
-   node (Encoding B) or as a metadata badge on the chart card (Encoding
-   A)? Per bridge spec §4.1, encoding is per-session config — the
-   visualizer reads whichever is present.
-4. **Lens switcher trigger threshold.** Show the dropdown only when
-   `projectItems.length >= 2`. When exactly one item exists, render it as
-   a flat badge.
-
----
-
-## 12. Out of Scope (defer)
-
-- Writing to GitHub from the visualizer.
-- Live GitHub-state polling, webhooks, or push-triggered re-renders.
-- Project lens switcher implementation (open question §11.4 must close
-  first).
-- Authentication, rate-limit, or token refresh UI.
-- Editing of `metadata.github.*` from the visualizer (ownership stays
-  with `coaia-github` per bridge spec §8).
-- A "lens entity" rendering pattern beyond the dropdown — see bridge
-  spec §4 promotion criterion.

package/rispecs/jsonl-parsing-data-types.spec.md

@@ -1,243 +0,0 @@
-# JSONL Parsing & Data Types
-## RISE Specification for Data Ingestion and Type System
-
-**Component Purpose**: Transform flat JSONL text into structured chart hierarchies through a 4-pass parsing algorithm, backed by a rigorous Entity/Relation type system that models structural tension.
-
-**Source Files**: `lib/types.ts`, `lib/jsonl-parser.ts`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Structured, navigable chart hierarchies from raw JSONL text files
-- Knowledge graphs with typed entities and relational connections
-- Telescoped parent-child chart hierarchies with automatic nesting
-- Resilient data structures that gracefully handle malformed input
-- Round-trip serialization: JSONL → ParsedData → JSONL without data loss
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-- coaia-narrative outputs flat JSONL files — one JSON object per line, no hierarchical structure
-- Each line is either an entity (5 types) or a relation (4 types)
-- Chart hierarchy exists only implicitly through naming conventions and metadata
-- Entity names follow patterns like `chart_1_desired_outcome` that encode relationships
-- Telescoped charts reference parents via `metadata.parentChart`
-
-### Desired Result
-- A fully assembled `ParsedData` structure where:
-  - Each `Chart` object contains its desired outcome, current reality, actions, and narrative beats
-  - Sub-charts are nested within their parent's `subCharts` array
-  - Root charts (level 0) are separately available for top-level navigation
-  - All entities are accessible by name via a Map
-  - All relations are collected in a flat array for graph operations
-
-### Natural Resolution
-The 4-pass `organizeData()` algorithm progressively builds structure from flat records, each pass resolving one layer of complexity until the full hierarchy emerges.
-
----
-
-## 📋 Type System
-
-### EntityRecord
-```typescript
-interface EntityRecord {
-  type: "entity"
-  name: string                    // Unique identifier, e.g. "chart_1_desired_outcome"
-  entityType:
-    | "structural_tension_chart"  // Root chart container
-    | "desired_outcome"           // What the user wants to create
-    | "current_reality"           // Honest assessment of what is
-    | "action_step"               // Step toward desired outcome
-    | "narrative_beat"            // Story documentation
-  observations: string[]          // Array of text descriptions
-  metadata: Record<string, any>   // chartId, level, dueDate, completionStatus, timestamps
-}
-```
-
-### RelationRecord
-```typescript
-interface RelationRecord {
-  type: "relation"
-  from: string                    // Source entity name
-  to: string                      // Target entity name
-  relationType:
-    | "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
-  metadata: Record<string, any>   // createdAt timestamp
-}
-```
-
-### Chart (Assembled)
-```typescript
-interface Chart {
-  id: string                      // e.g. "chart_1"
-  chartEntity: EntityRecord       // The structural_tension_chart entity
-  desiredOutcome?: EntityRecord   // Optional desired_outcome entity
-  currentReality?: EntityRecord   // Optional current_reality entity
-  actions: EntityRecord[]         // Array of action_step entities
-  narrativeBeats: EntityRecord[]  // Array of narrative_beat entities
-  subCharts: Chart[]              // Telescoped child charts
-  level: number                   // 0 = root, 1+ = sub-chart depth
-  parentChart?: string            // Parent chart ID reference
-  relations: RelationRecord[]     // Relations scoped to this chart
-}
-```
-
-### ParsedData (Top-Level)
-```typescript
-interface ParsedData {
-  charts: Chart[]                 // All chart objects
-  entities: Map<string, EntityRecord>  // All entities by name
-  relations: RelationRecord[]     // All relations
-  rootCharts: Chart[]             // Level 0 charts only
-}
-```
-
----
-
-## 📋 Parsing Algorithm: `parseJSONL(content: string): JSONLRecord[]`
-
-**Input**: Raw JSONL text (multi-line string)  
-**Output**: Array of validated JSONLRecord objects
-
-```
-1. Split content by newlines
-2. For each line:
-   a. Trim whitespace
-   b. Skip empty lines
-   c. Attempt JSON.parse()
-   d. If parse succeeds → include in result
-   e. If parse fails → log error via console.error("Failed to parse line:", line, error) and skip
-3. Return array of parsed records
-```
-
-**Resilience**: Malformed lines never crash the parser — they are logged via `console.error` and skipped. This allows partial files and hand-edited JSONL to be safely ingested.
-
----
-
-## 📋 Organization Algorithm: `organizeData(records: JSONLRecord[]): ParsedData`
-
-**Input**: Flat array of entity and relation records  
-**Output**: Fully assembled ParsedData with chart hierarchy
-
-### Pass 1: Separate Records
-```
-For each record:
-  If record.type === "entity" → add to entities Map (keyed by name)
-  If record.type === "relation" → add to relations array
-```
-
-### Pass 2: Assemble Chart Shells
-```
-For each entity where entityType === "structural_tension_chart":
-  Extract chartId from metadata.chartId OR entity.name.replace("_chart", "")
-  Create Chart object with:
-    - id = chartId
-    - chartEntity = this entity
-    - level = metadata.level || 0
-    - parentChart = metadata.parentChart (with "_chart" suffix stripped)
-    - Empty arrays for actions, narrativeBeats, subCharts, relations
-```
-
-### Pass 3: Populate Chart Components
-```
-For each entity (non-chart):
-  Extract chartId from name prefix (regex /^(chart_\d+)/)
-  Find matching chart
-  Based on entityType:
-    "desired_outcome"  → chart.desiredOutcome = entity
-    "current_reality"  → chart.currentReality = entity
-    "action_step"      → chart.actions.push(entity)
-    "narrative_beat"   → chart.narrativeBeats.push(entity)
-  
-  Collect relations where from or to references this chart's entities
-```
-
-### Pass 3.5: Recognize Telescoped Charts as Parent Actions
-```
-For each chart where level > 0 AND parentChart exists AND desiredOutcome exists:
-  Find parent chart by normalizing parentChart reference
-  If parent found:
-    Create synthetic action entity from chart's desiredOutcome with:
-      - isTelescopedChart = true
-      - telescopedChartId = this chart's ID
-      - completionStatus from chart metadata
-      - dueDate from chart metadata
-    Add to parent's actions (if not already present by name)
-```
-
-### Pass 4: Build Hierarchy
-```
-For each chart where level > 0:
-  Find parent chart by parentChart reference
-  If parent found:
-    parent.subCharts.push(this chart)
-
-Identify rootCharts = charts where level === 0 OR parentChart is undefined/null
-```
-
----
-
-## 📋 Helper Functions
-
-### `getChartSummary(chart: Chart): string`
-Returns first observation of desiredOutcome, truncated to 100 characters with "..." suffix.  
-Falls back to "No desired outcome" if absent.
-
-### `getChartProgress(chart: Chart): number`
-Calculates `(completedActions / totalActions) * 100`, rounded to nearest integer.  
-Returns 0 when no actions exist.
-
----
-
-## 📋 File Upload & Export
-
-### Upload Flow
-1. `FileUpload` component accepts `.jsonl` and `.txt` files via click or drag-drop
-2. `FileReader` API reads file contents as text
-3. `parseJSONL()` → `organizeData()` → `ParsedData` delivered to parent component
-4. Toast notification confirms successful load with chart count
-
-### Export Flow
-1. `ChartEditor.exportToJSONL()` serializes all entities and relations
-2. One JSON object per line (JSONL format)
-3. Entities first, then relations
-4. Result available as downloadable blob or POST body to API
-
-### Live Reload (useLivePolling hook)
-1. When `NEXT_PUBLIC_LIVE_MODE=true`, polls `/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 component for 2 seconds
-
----
-
-## ✅ Quality Criteria
-
-✅ **Parse Resilience**
-- Malformed JSONL lines never throw — they are logged via `console.error` and skipped
-- Empty lines and whitespace-only lines are filtered
-- Partial files produce partial but valid ParsedData
-
-✅ **Hierarchy Integrity**
-- Every sub-chart references its parent correctly
-- Telescoped actions appear in parent's action list with `isTelescopedChart` flag
-- Root charts always identified correctly (level 0)
-
-✅ **Round-Trip Fidelity**
-- `parseJSONL(exportToJSONL(data))` produces equivalent ParsedData
-- All metadata timestamps preserved through serialization
-- Entity names and relation references maintain referential integrity
-
----
-
-## 🔗 Related Components
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — consumes ParsedData for display
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — mutates entities and relations via ChartEditor
-- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — serves and receives ParsedData over HTTP