coaia-visualizer 1.6.3 → 1.6.4

package/index.tsx

@@ -13,6 +13,31 @@ export type {
 // JSONL Parser
 export { parseJSONL, organizeData, getChartSummary, getChartProgress } from "./lib/jsonl-parser"
 
+// GitHub provenance helpers
+export {
+  GITHUB_BRIDGE_RELATION_TYPES,
+  GITHUB_PROJECT_FIELD_KEYS,
+  GITHUB_SYNC_STATES,
+  formatGithubIssueRef,
+  formatProjectItemRef,
+  getGithubBridgeRelationType,
+  getGithubEntityProvenance,
+  getGithubIssueRef,
+  getGithubProjectItems,
+  getGithubSource,
+  getGithubSyncState,
+  getProjectFieldEntries,
+} from "./lib/github-provenance"
+export type {
+  GithubBridgeRelationType,
+  GithubEntityProvenance,
+  GithubIssueRef,
+  GithubProjectFieldEntry,
+  GithubProjectItemRef,
+  GithubSourceProvenance,
+  GithubSyncState,
+} from "./lib/github-provenance"
+
 // Utilities
 export { cn } from "./lib/utils"
 
@@ -28,6 +53,7 @@ export { ChartDetail } from "./components/chart-detail"
 export { DataStats } from "./components/data-stats"
 export { CreateChartForm } from "./components/create-chart-form"
 export { NarrativeBeats } from "./components/narrative-beats"
+export { ActionStepIssueBadge, ProjectSourceBadge, SyncStatePill } from "./components/github-provenance"
 export { LiveIndicator } from "./components/live-indicator"
 export { ThemeToggle } from "./components/theme-toggle"
 export { EditDesiredOutcome } from "./components/edit-desired-outcome"

package/lib/chart-editor.ts

@@ -1,8 +1,8 @@
 // lib/chart-editor.ts - Chart editing logic
 
-import type { EntityRecord, RelationRecord, ParsedData } from "./types"
-import { buildMetadataWarnings, buildRecordProjections, serializeParsedData } from "./jsonl-preservation"
-import { buildRiseSpecs } from "./jsonl-parser"
+import type { EntityRecord, RelationRecord, ParsedData } from "./types.ts"
+import { buildMetadataWarnings, buildRecordProjections, serializeParsedData } from "./jsonl-preservation.ts"
+import { buildRiseSpecs } from "./jsonl-parser.ts"
 
 export interface ChartUpdate {
   type:

package/lib/github-provenance.ts

@@ -0,0 +1,316 @@
+import type { EntityRecord, RelationRecord } from "./types.ts"
+
+export const GITHUB_SYNC_STATES = ["synced", "diverged", "conflict", "project-only", "chart-only"] as const
+
+export type GithubSyncState = (typeof GITHUB_SYNC_STATES)[number]
+
+export interface GithubIssueRef {
+  owner: string
+  repo: string
+  number: number
+  nodeId?: string
+  url?: string
+}
+
+export interface GithubProjectItemRef {
+  projectOwner?: string
+  projectNumber?: number
+  projectTitle?: string
+  itemId?: string
+  projectId?: string
+  url?: string
+  fields?: Record<string, unknown>
+  fieldValues?: Record<string, unknown>
+  projectFields?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export interface GithubSourceProvenance {
+  system?: string
+  toolName?: string
+  sessionId?: string
+  createdAt?: string
+  version?: string
+  [key: string]: unknown
+}
+
+export interface GithubEntityProvenance {
+  issue?: GithubIssueRef
+  projectItems: GithubProjectItemRef[]
+  syncState?: GithubSyncState
+  lastSyncedAt?: string
+  source?: GithubSourceProvenance
+  hasGithubMetadata: boolean
+}
+
+export interface GithubProjectFieldEntry {
+  key: string
+  label: string
+  value: string
+}
+
+export const GITHUB_PROJECT_FIELD_KEYS = [
+  "goal",
+  "current_reality",
+  "observations",
+  "question",
+  "Status",
+  "phase",
+  "session_id",
+  "four_dir_east",
+  "four_dir_south",
+  "four_dir_west",
+  "four_dir_north",
+  "relational_assessed",
+  "relational_principles",
+] as const
+
+export const GITHUB_BRIDGE_RELATION_TYPES = ["synced_to_github", "linked_to_issue", "project_lens_of"] as const
+
+export type GithubBridgeRelationType = (typeof GITHUB_BRIDGE_RELATION_TYPES)[number]
+
+const PROJECT_FIELD_LABELS: Record<string, string> = {
+  goal: "goal",
+  current_reality: "current reality",
+  observations: "observations",
+  question: "question",
+  Status: "Status",
+  phase: "phase",
+  session_id: "session",
+  four_dir_east: "East",
+  four_dir_south: "South",
+  four_dir_west: "West",
+  four_dir_north: "North",
+  relational_assessed: "relational assessed",
+  relational_principles: "relational principles",
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim()
+    }
+  }
+}
+
+function firstNumber(...values: unknown[]): number | undefined {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value
+    }
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value)
+      if (Number.isFinite(parsed)) {
+        return parsed
+      }
+    }
+  }
+}
+
+function normalizeIssueCandidate(candidate: unknown): GithubIssueRef | undefined {
+  if (!isRecord(candidate)) return undefined
+
+  const owner = firstString(candidate.owner, candidate.ownerLogin, candidate.repositoryOwner)
+  const repo = firstString(candidate.repo, candidate.repository, candidate.repositoryName)
+  const number = firstNumber(candidate.number, candidate.issue_number, candidate.issueNumber, candidate.issue)
+
+  if (!owner || !repo || !number) return undefined
+
+  return {
+    owner,
+    repo,
+    number,
+    nodeId: firstString(candidate.nodeId, candidate.node_id),
+    url: firstString(candidate.url, candidate.html_url) ?? `https://github.com/${owner}/${repo}/issues/${number}`,
+  }
+}
+
+function normalizeProjectItemCandidate(candidate: unknown, fallbackOwner?: string): GithubProjectItemRef | undefined {
+  if (!isRecord(candidate)) return undefined
+
+  const projectOwner = firstString(candidate.projectOwner, candidate.owner, candidate.ownerLogin, fallbackOwner)
+  const projectNumber = firstNumber(candidate.projectNumber, candidate.project_number, candidate.number)
+  const itemId = firstString(candidate.itemId, candidate.item_id, candidate.projectItemId, candidate.project_id)
+  const projectId = firstString(candidate.projectId, candidate.project_id)
+  const projectTitle = firstString(candidate.projectTitle, candidate.title, candidate.project)
+  const url = firstString(candidate.url)
+
+  if (!projectOwner && !projectNumber && !itemId && !projectId && !projectTitle && !url) {
+    return undefined
+  }
+
+  return {
+    ...candidate,
+    projectOwner,
+    projectNumber,
+    projectTitle,
+    itemId,
+    projectId,
+    url,
+  }
+}
+
+export function getGithubIssueRef(entity?: EntityRecord): GithubIssueRef | undefined {
+  if (!entity) return undefined
+
+  const metadata = entity.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const githubRef = isRecord(metadata.github_ref) ? metadata.github_ref : undefined
+
+  return normalizeIssueCandidate(github?.issue) ?? normalizeIssueCandidate(syncTarget) ?? normalizeIssueCandidate(githubRef)
+}
+
+export function getGithubProjectItems(entity?: EntityRecord): GithubProjectItemRef[] {
+  if (!entity) return []
+
+  const metadata = entity.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const fallbackOwner = getGithubIssueRef(entity)?.owner
+
+  if (Array.isArray(github?.projectItems)) {
+    return github.projectItems
+      .map((item) => normalizeProjectItemCandidate(item, fallbackOwner))
+      .filter((item): item is GithubProjectItemRef => Boolean(item))
+  }
+
+  const canonicalProjectItem = normalizeProjectItemCandidate(github?.projectItem, fallbackOwner)
+  if (canonicalProjectItem) {
+    return [canonicalProjectItem]
+  }
+
+  const legacyProjectItem = normalizeProjectItemCandidate(syncTarget, fallbackOwner)
+  return legacyProjectItem ? [legacyProjectItem] : []
+}
+
+export function getGithubSyncState(entityOrMetadata?: EntityRecord | Record<string, unknown>): GithubSyncState | undefined {
+  const metadata =
+    entityOrMetadata && "metadata" in entityOrMetadata && isRecord(entityOrMetadata.metadata)
+      ? entityOrMetadata.metadata
+      : entityOrMetadata
+
+  if (!isRecord(metadata)) return undefined
+
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const syncState = github?.syncState ?? metadata.syncState
+
+  return typeof syncState === "string" && GITHUB_SYNC_STATES.includes(syncState as GithubSyncState)
+    ? (syncState as GithubSyncState)
+    : undefined
+}
+
+export function getGithubSource(entity?: EntityRecord): GithubSourceProvenance | undefined {
+  if (!entity) return undefined
+
+  const source = entity.metadata?.source
+  return isRecord(source) ? (source as GithubSourceProvenance) : undefined
+}
+
+export function getGithubEntityProvenance(entity?: EntityRecord): GithubEntityProvenance {
+  const metadata = entity?.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const issue = getGithubIssueRef(entity)
+  const projectItems = getGithubProjectItems(entity)
+  const syncTarget = isRecord(metadata.sync_target) ? metadata.sync_target : undefined
+  const githubRef = isRecord(metadata.github_ref) ? metadata.github_ref : undefined
+  const source = getGithubSource(entity)
+
+  return {
+    issue,
+    projectItems,
+    syncState: getGithubSyncState(entity),
+    lastSyncedAt: firstString(github?.lastSyncedAt, metadata.lastSyncedAt),
+    source,
+    hasGithubMetadata:
+      Boolean(github) ||
+      Boolean(syncTarget) ||
+      Boolean(githubRef) ||
+      source?.system === "coaia-github" ||
+      Boolean(issue) ||
+      projectItems.length > 0,
+  }
+}
+
+export function formatGithubIssueRef(issue?: GithubIssueRef): string | undefined {
+  if (!issue) return undefined
+  return `${issue.owner}/${issue.repo}#${issue.number}`
+}
+
+export function formatProjectItemRef(projectItem?: GithubProjectItemRef): string | undefined {
+  if (!projectItem) return undefined
+
+  if (projectItem.projectOwner && projectItem.projectNumber) {
+    return `${projectItem.projectOwner}/${projectItem.projectNumber}`
+  }
+
+  return projectItem.projectTitle || projectItem.itemId || projectItem.projectId || projectItem.url
+}
+
+export function getProjectFieldEntries(
+  entity: EntityRecord | undefined,
+  projectItem?: GithubProjectItemRef,
+): GithubProjectFieldEntry[] {
+  const metadata = entity?.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const sources = [
+    projectItem?.fields,
+    projectItem?.fieldValues,
+    projectItem?.projectFields,
+    github?.fields,
+    github?.fieldValues,
+    github?.projectFields,
+    metadata,
+    github,
+  ].filter(isRecord)
+
+  return GITHUB_PROJECT_FIELD_KEYS.flatMap((key) => {
+    for (const source of sources) {
+      if (!(key in source)) continue
+      const value = stringifyFieldValue(source[key])
+      if (value) {
+        return [{ key, label: PROJECT_FIELD_LABELS[key], value }]
+      }
+    }
+    return []
+  })
+}
+
+export function getGithubBridgeRelationType(relation: RelationRecord): GithubBridgeRelationType | undefined {
+  const relationType = relation.relationType
+  if (GITHUB_BRIDGE_RELATION_TYPES.includes(relationType as GithubBridgeRelationType)) {
+    return relationType as GithubBridgeRelationType
+  }
+
+  const metadata = relation.metadata ?? {}
+  const github = isRecord(metadata.github) ? metadata.github : undefined
+  const context = firstString(
+    metadata.context,
+    metadata.relation,
+    metadata.relationName,
+    metadata.semanticType,
+    github?.context,
+    github?.relation,
+  )
+
+  return GITHUB_BRIDGE_RELATION_TYPES.includes(context as GithubBridgeRelationType)
+    ? (context as GithubBridgeRelationType)
+    : undefined
+}
+
+function stringifyFieldValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined
+  if (typeof value === "string") return value.trim() || undefined
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  if (Array.isArray(value)) {
+    const rendered = value.map(stringifyFieldValue).filter(Boolean).join(", ")
+    return rendered || undefined
+  }
+  if (isRecord(value)) {
+    return firstString(value.name, value.text, value.value, value.title, value.label) ?? JSON.stringify(value)
+  }
+}

package/lib/jsonl-parser.ts

@@ -1,5 +1,5 @@
-import type { Chart, EntityRecord, JSONLRecord, ParsedData, RawJSONLRecord, RelationRecord, RiseSpecProjection } from "./types"
-import { buildMetadataWarnings, buildRecordProjections, normalizeJsonlRecord } from "./jsonl-preservation"
+import type { Chart, EntityRecord, JSONLRecord, ParsedData, RawJSONLRecord, RelationRecord, RiseSpecProjection } from "./types.ts"
+import { buildMetadataWarnings, buildRecordProjections, normalizeJsonlRecord } from "./jsonl-preservation.ts"
 
 export function parseJSONL(content: string): RawJSONLRecord[] {
   const lines = content.trim().split("\n")

package/lib/types.ts

@@ -3,7 +3,14 @@
 export interface EntityRecord {
   type: "entity"
   name: string
-  entityType: "structural_tension_chart" | "desired_outcome" | "current_reality" | "action_step" | "narrative_beat"
+  entityType:
+    | "structural_tension_chart"
+    | "desired_outcome"
+    | "current_reality"
+    | "action_step"
+    | "narrative_beat"
+    | "custom"
+    | (string & {})
   observations: string[]
   metadata: Record<string, any>
   [key: string]: any
@@ -13,7 +20,13 @@ export interface RelationRecord {
   type: "relation"
   from: string
   to: string
-  relationType: "contains" | "creates_tension_with" | "advances_toward" | "documents"
+  relationType:
+    | "contains"
+    | "creates_tension_with"
+    | "advances_toward"
+    | "documents"
+    | "custom"
+    | (string & {})
   metadata: Record<string, any>
   [key: string]: any
 }

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

@@ -0,0 +1,18 @@
+{
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coaia-visualizer",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "private": false,
   "type": "module",
   "main": "./index.tsx",
@@ -9,6 +9,7 @@
     ".": "./index.tsx",
     "./lib/types": "./lib/types.ts",
     "./lib/jsonl-parser": "./lib/jsonl-parser.ts",
+    "./lib/github-provenance": "./lib/github-provenance.ts",
     "./lib/utils": "./lib/utils.ts",
     "./hooks/*": "./hooks/*.ts",
     "./components/*": "./components/*.tsx",
@@ -23,25 +24,24 @@
     "components/**/*",
     "hooks/**/*",
     "lib/**/*",
-    "styles/**/*",
-    "public/**/*",
     "dist/**/*",
-    "mcp/dist/**/*",
-    "mcp/src/**/*",
-    "mcp/package.json",
-    "mcp/package-lock.json",
-    "mcp/README.md",
-    "mcp/Dockerfile",
-    "mcp/tsconfig.json",
-    "index.tsx",
+    "mcp/**/*",
+    "public/**/*",
+    "rispecs/**/*",
+    "styles/**/*",
     "cli.ts",
+    "index.tsx",
     "skill.ts",
-    "components.json",
-    "mcp-config.json",
     "next-env.d.ts",
     "next.config.mjs",
     "postcss.config.mjs",
     "tsconfig.json",
+    "Dockerfile",
+    "Dockerfile.app",
+    "docker-build-push.sh",
+    "docker-entrypoint.sh",
+    "components.json",
+    "mcp-config.json",
     "README.md",
     "README_TELESCOPED_NAVIGATION.md",
     "KINSHIP.md",
@@ -57,6 +57,7 @@
     "test": "playwright test",
     "test:rich-jsonl": "playwright test test-scripts/rich-jsonl-preservation.spec.ts",
     "test:global-cli": "playwright test test-scripts/test-global-cli.spec.ts",
+    "verify:github-provenance": "node --experimental-strip-types --experimental-specifier-resolution=node test-scripts/verify-github-provenance.mjs",
     "docker:build": "docker build -t jgwill/coaia:visualizer .",
     "docker:push": "docker push jgwill/coaia:visualizer",
     "docker:build-push": "npm run docker:build && npm run docker:push",

package/rispecs/README.md

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