coaia-visualizer 1.6.1 → 1.6.3

package/rispecs/chart-visualization-hierarchy.spec.md

@@ -1,235 +0,0 @@
-# Chart Visualization & Hierarchy
-## RISE Specification for Chart Display, Navigation, and Structural Tension Rendering
-
-**Component Purpose**: Render structural tension charts in navigable hierarchy and list views, enabling users to see the creative gap between desired outcomes and current reality at every level of depth.
-
-**Source Files**: `components/chart-list.tsx`, `components/chart-detail.tsx`, `components/chart-detail-editable.tsx`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Visual maps of structural tension across hierarchical chart trees
-- Navigable depth — drilling from root charts through telescoped sub-charts
-- At-a-glance progress awareness through progress bars and completion counts
-- Contextual detail views showing the full picture of any chart
-- Breadcrumb-style navigation that maintains context while exploring depth
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-Charts in coaia-narrative exist as flat JSONL records. A root chart with 3 levels of telescoped sub-charts is just 20+ entity records and 15+ relation records in a text file. There is no visual hierarchy, no at-a-glance progress, no way to "see" the structural tension.
-
-### Desired Result
-A two-pane interface where:
-- Left pane shows all charts in either hierarchy (tree) or flat list mode
-- Right pane shows full detail of the selected chart
-- Navigation stack enables drilling into sub-charts with back navigation
-- Every chart visually renders the tension between desired outcome and current reality
-- Progress bars show advancement toward completion
-
-### Natural Resolution
-The `ChartList` component transforms `ParsedData.rootCharts` into a navigable tree (via recursive `ChartTree` sub-component), while `ChartDetailEditable` renders the selected chart's full structure with inline editing. Stack-based navigation tracks the user's path through the hierarchy.
-
----
-
-## 📋 ChartList Component
-
-### Props
-```typescript
-interface ChartListProps {
-  data: ParsedData
-  selectedChart: Chart | null
-  onSelectChart: (chart: Chart) => void
-  mode: "hierarchy" | "list"
-  onDataUpdate?: (updatedData: ParsedData) => void
-}
-```
-
-### Two Display Modes
-
-**Hierarchy Mode** (default):
-- Renders `ChartTree` — a recursive component that displays root charts with expandable sub-charts
-- Each level is indented with left padding and vertical border
-- Chevron icons toggle expand/collapse state
-- Sub-charts nested within parent nodes
-
-**List Mode**:
-- Flat `ScrollArea` listing all charts regardless of level
-- Each chart rendered as `ChartItem`
-- No indentation or hierarchy
-
-### ChartItem Sub-Component
-Each chart item displays:
-- **Chart ID**: Badge with chart identifier (e.g., "chart_1")
-- **Level Badge**: Shows depth level (0 = root)
-- **Summary**: First 100 chars of desired outcome via `getChartSummary()`
-- **Narrative Beat Indicators**: If beats exist, shows first beat description snippet
-- **Action Count**: Number of action steps
-- **Progress Bar**: Visual bar showing `getChartProgress()` percentage
-- **Selected State**: Primary border highlight when this chart is selected
-
-### ChartTree Sub-Component
-```
-▼ chart_1 — "Build structural tension framework"    [Level 0] [3 actions] [66%]
-    ▶ chart_4 — "Design entity type system"          [Level 1] [2 actions] [50%]
-    ▼ chart_5 — "Implement parsing algorithm"         [Level 1] [4 actions] [25%]
-        ▶ chart_8 — "Handle malformed input"          [Level 2] [1 action]  [0%]
-  chart_2 — "Create UI component library"             [Level 0] [5 actions] [80%]
-```
-
-### AddMasterChart Integration
-When `onDataUpdate` prop is provided, an "Add Chart" button appears at the bottom of the list, triggering the `AddMasterChart` dialog for creating new root-level charts.
-
----
-
-## 📋 ChartDetail Component (Read-Only)
-
-> ⚠️ **Note**: This component exists in the codebase but is NOT rendered by `page.tsx`. The application exclusively uses `ChartDetailEditable` for all chart display. ChartDetail is retained for potential future read-only embedding scenarios.
-
-### Props
-```typescript
-interface ChartDetailProps {
-  chart: Chart
-  data: ParsedData
-}
-```
-
-### Renders (Top to Bottom)
-1. **Header Card**: Chart title (from desired outcome), level badge, creation date, due date
-2. **Structural Tension Card** (section order is critical — maintains the creative tension visual):
-   - **Desired Outcome** in teal-colored box (chart-1 theme) — the vision
-   - **Action Steps** with completion indicators and due dates — the path
-   - **Current Reality** observations in amber-colored box (chart-2 theme) — where you are now
-3. **Narrative Beats Section**: If beats exist, renders `NarrativeBeats` component
-4. **Sub-Charts List**: Child charts listed at bottom
-
-### ActionItem Sub-Component
-```
-┌──────────────────────────────────────────────┐
-│ ○  Action Step Title                         │
-│    Due: 2024-03-15                           │
-│ ──────────────────────────────────────────── │
-│ ✓  Completed Action (strikethrough text)     │
-│    Completed: 2024-03-10                     │
-└──────────────────────────────────────────────┘
-```
-- Circle icon (`○`) for incomplete, check icon (`✓`) for complete
-- Strikethrough styling applied to completed actions
-- Due date displayed below action text when present
-
----
-
-## 📋 ChartDetailEditable Component
-
-### Props
-```typescript
-interface ChartDetailEditableProps {
-  chart: Chart
-  data: ParsedData
-  onUpdate: (updatedData: ParsedData) => void
-  onNavigateToSubChart?: (subChart: Chart) => void
-  onNavigateBack?: () => void
-}
-```
-
-### Additional Features (Beyond Read-Only)
-- **Back Button**: Appears when navigation stack has entries (i.e., `chartNavigationStack.length > 0`), calls `onNavigateBack()`
-- **Inline Editing**: Uses `EditDesiredOutcome`, `EditCurrentReality`, `EditActionStep` components
-- **Due Date Editor**: `EditChartDueDate` component on header card
-- **Add Action Step**: `AddActionStep` form at bottom of actions list
-- **Telescope Actions**: Each action has telescope icon to create/navigate to sub-chart
-- **Completion Toggle**: Checkbox-style toggle on each action
-
-### Structural Tension Card Section Order
-The Structural Tension card renders three sections top-to-bottom, separated by `<Separator>` elements:
-1. **Desired Outcome** (Target icon, chart-1 color) — `EditDesiredOutcome`
-2. **Action Steps** (ListChecks icon, chart-3 color) — `EditActionStep` list + `AddActionStep` form
-3. **Current Reality** (MapPin icon, chart-2 color) — `EditCurrentReality`
-
-> ⚠️ This order is intentional. Action Steps sit between outcome and reality to represent the bridge across the structural tension gap.
-
-### applyEdit Pattern
-All edits follow a consistent pattern:
-```
-1. Create ChartEditor instance from current ParsedData
-2. Call appropriate editor method (e.g., updateDesiredOutcome)
-3. Get updated ParsedData via editor.getUpdatedData()
-4. Pass to onUpdate() callback → parent state updates → re-render
-```
-
-### Telescoping Flow
-```
-User clicks telescope icon on action
-       │
-       ├─ If action already has telescoped chart:
-       │    → onNavigateToSubChart(existingSubChart)
-       │
-       └─ If action has no telescoped chart:
-            → ChartEditor.createTelescopedChartFromAction()
-            → New sub-chart created with action as desired outcome
-            → onUpdate(newData)
-            → onNavigateToSubChart(newSubChart)
-```
-
----
-
-## 📋 Navigation Stack
-
-The main page (`app/page.tsx`) maintains a `chartNavigationStack: Chart[]` array:
-
-```typescript
-handleNavigateToSubChart(subChart: Chart):
-  1. Push current selectedChart onto stack
-  2. Set selectedChart = subChart
-
-handleNavigateBack():
-  1. Pop last chart from stack
-  2. Set selectedChart = popped chart (or null if stack empty)
-```
-
-This enables unlimited depth navigation with consistent back-button behavior.
-
----
-
-## 📋 View Mode Toggle
-
-The main page offers a `viewMode` toggle between "hierarchy" and "list":
-- **Hierarchy**: Shows `ChartList` in tree mode with expand/collapse
-- **List**: Shows `ChartList` in flat mode — useful for searching or quick overview
-
-Toggle rendered as `Tabs` component at the top of the left pane.
-
----
-
-## ✅ Quality Criteria
-
-✅ **Structural Tension Visible**
-- Every chart clearly displays desired outcome and current reality in contrasting color boxes
-- The gap between them is the structural tension — always visible, never hidden
-
-✅ **Navigation Integrity**
-- Back button always returns to correct parent chart
-- Stack correctly tracks multi-level depth navigation
-- Sub-charts display in both hierarchy tree and detail view
-
-✅ **Progress Awareness**
-- Progress bars calculate from action completion status
-- Summary text truncated consistently at 100 characters
-- Level badges distinguish root charts from sub-charts at a glance
-
-✅ **Responsive Layout**
-- Two-pane layout with scrollable chart list and detail view
-- Responsive typography (md: breakpoints for text sizing)
-- Hover-triggered toolbars for editing actions
-
----
-
-## 🔗 Related Components
-
-- [jsonl-parsing-data-types.spec.md](./jsonl-parsing-data-types.spec.md) — provides ParsedData consumed by these components
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — editing components used within ChartDetailEditable
-- [narrative-beats-display.spec.md](./narrative-beats-display.spec.md) — NarrativeBeats rendered within chart detail
-- [relation-graph-visualization.spec.md](./relation-graph-visualization.spec.md) — RelationGraph rendered in relations tab

package/rispecs/cli-mode.spec.md

@@ -1,224 +0,0 @@
-# CLI Mode
-## RISE Specification for Command-Line Interface and Deployment
-
-**Component Purpose**: Launch the coaia-visualizer from the terminal with a single command, supporting both local Next.js development and Docker containerized deployment, configurable via flags and environment variables.
-
-**Source Files**: `cli.ts`, `Dockerfile`, `package.json` (bin field)
-
-**Key Dependencies**: `minimist` (argument parsing), `dotenv` (env file loading)
-
-> **Note**: The CLI uses ESM (`import` syntax). The compiled output targets ES modules.
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- Instant visualization of any local JSONL memory file via `coaia-visualizer --memory-path ./file.jsonl`
-- Containerized deployments with volume-mounted memory files
-- Configurable live-polling sessions with auto-reload
-- Audio-enabled sessions with auto-play capability
-- Zero-configuration startup with sensible defaults
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-JSONL memory files sit on the filesystem. Opening them requires a running web server, environment variables, and browser navigation. Docker deployment needs image management, port mapping, and volume mounting. These steps are manual without the CLI.
-
-### Desired Result
-A single `coaia-visualizer` command that:
-1. Resolves the memory file path (from flag, env var, or default)
-2. Starts the appropriate server (Next.js local or Docker container)
-3. Opens the browser automatically
-4. Handles graceful shutdown on SIGINT
-
-### Natural Resolution
-The CLI script (`cli.ts`) compiles to `dist/cli.js` and is registered as the `coaia-visualizer` npm binary. It resolves configuration from three layers (args > env > defaults), then spawns either a Docker container or a local Next.js dev server.
-
----
-
-## 📋 Command-Line Flags
-
-```
-coaia-visualizer [options]
-
-Options:
-  --memory-path, -M PATH    Path to JSONL memory file (default: ./memory.jsonl)
-  --port, -p PORT            Server port (default: 4321)
-  --docker, -d               Run in Docker container
-  --docker-image IMAGE       Custom Docker image (default: jgwill/coaia:visualizer)
-  --pull                     Pull Docker image before running
-  --live                     Enable live file polling
-  --poll-interval MS         Polling frequency in milliseconds (default: 2000)
-  --auto-play                Auto-play audio files
-  --audio-dir PATH           Directory for audio files
-  --no-open                  Don't auto-open browser
-  --help, -h                 Show help text
-```
-
----
-
-## 📋 Environment Variables
-
-| Variable | Flag Equivalent | Default | Purpose |
-|:---|:---|:---|:---|
-| `COAIAN_MF` | `--memory-path` | `./memory.jsonl` | Memory file path |
-| `COAIAV_MEMORY_PATH` | *(internal)* | — | Resolved absolute path (set by CLI from `COAIAN_MF`). API routes read this variable. |
-| `COAIAV_MEMORY_DISPLAY_NAME` | *(internal)* | — | Original filename for UI display. Set by CLI to preserve the actual filename when Docker remaps to `/data/memory.jsonl`. Falls back to `path.basename(COAIAV_MEMORY_PATH)` if unset. |
-| `COAIAV_PORT` | `--port` | `4321` | Server port |
-| `COAIAV_LIVE` | `--live` | `false` | Enable live polling |
-| `COAIAV_POLL_INTERVAL` | `--poll-interval` | `2000` | Polling interval (ms) |
-| `COAIAV_AUTO_PLAY` | `--auto-play` | `false` | Auto-play audio |
-| `COAIAV_AUDIO_DIR` | `--audio-dir` | — | Audio directory path |
-| `COAIAN_API_TOKEN` | — | auto-generated | API authentication token |
-
----
-
-## 📋 Configuration Priority
-
-```
-1. Command-line flags     (highest priority)
-2. Environment variables
-3. .env file values
-4. Default values          (lowest priority)
-```
-
----
-
-## 📋 Execution Modes
-
-### Local Mode (Default)
-
-```
-coaia-visualizer --memory-path ./memory.jsonl --port 3000
-```
-
-**Process**:
-1. Resolve absolute path to memory file
-2. Set environment variables: `COAIAV_MEMORY_PATH`, `COAIAV_MEMORY_DISPLAY_NAME`, `PORT`, `NEXT_PUBLIC_LIVE_MODE`, `NEXT_PUBLIC_POLL_INTERVAL`, `COAIAV_AUTO_PLAY`, `COAIAV_AUDIO_DIR`
-3. Spawn `npm run dev` in the coaia-visualizer package directory
-4. Inherit stdio for visible server output
-5. Wait 3 seconds, then auto-open browser at `http://localhost:{port}`
-6. Listen for SIGINT → gracefully terminate child process
-
-### Docker Mode
-
-```
-coaia-visualizer --docker --memory-path ./memory.jsonl --pull
-```
-
-**Process**:
-1. If `--pull` flag → execute `docker pull {image}` first
-2. Resolve absolute path to memory file
-3. Execute Docker run:
-   ```
-   docker run --rm
-     -p {hostPort}:{containerPort}
-     -v {absPath}:/data/memory.jsonl
-     -e COAIAV_MEMORY_PATH=/data/memory.jsonl
-     -e COAIAV_MEMORY_DISPLAY_NAME={originalFilename}
-     -e PORT={containerPort}
-     -e NEXT_PUBLIC_LIVE_MODE={live}
-     -e NEXT_PUBLIC_POLL_INTERVAL={interval}
-     {image}
-   ```
-4. Container port: always 4321 internally
-5. Auto-open browser at `http://localhost:{hostPort}`
-
-### Docker Constants
-```typescript
-const DOCKER_IMAGE = 'jgwill/coaia:visualizer'
-const CONTAINER_PORT = 4321
-```
-
----
-
-## 📋 Dockerfile (Production)
-
-**Base**: `node:22-alpine` (two-stage build)
-
-### Builder Stage
-1. Install pnpm via corepack
-2. Copy `package.json` + `pnpm-lock.yaml`
-3. Install dependencies (skip prepare hook)
-4. Copy source files
-5. Build: `pnpm prepare && pnpm build` (CLI + Next.js)
-
-### Runner Stage
-1. Copy dependencies from builder
-2. Prune dev dependencies
-3. Copy built `.next/`, `public/`, `next.config.mjs`
-4. Copy `docker-entrypoint.sh`
-5. **VOLUME**: `/data` (mount point for JSONL files)
-6. **ENV**: `PORT=4321`, `COAIAV_MEMORY_PATH=/data/memory.jsonl`
-7. **ENTRYPOINT**: `docker-entrypoint.sh`
-8. **EXPOSE**: 4321
-
----
-
-## 📋 npm Package Entry
-
-```json
-{
-  "bin": {
-    "coaia-visualizer": "dist/cli.js"
-  }
-}
-```
-
-**Build CLI**: `npm run build:cli` → `tsc` compiles `cli.ts` → `dist/cli.js`  
-**Prepare hook**: `npm run build:cli` runs automatically on `npm install`
-
-### Global Installation
-```bash
-npm install -g coaia-visualizer
-coaia-visualizer --memory-path /path/to/memory.jsonl
-```
-
----
-
-## 📋 Creative Advancement Scenario
-
-### Scenario: Quick Visualization of Agent Session
-**User Intent**: See the structural tension charts my AI agent created during a session  
-**Current Structural Reality**: Agent wrote to `./memory.jsonl` via coaia-narrative MCP, but the file is raw JSONL  
-
-**Natural Progression**:
-1. User runs: `coaia-visualizer -M ./memory.jsonl --live`
-2. CLI resolves absolute path, sets env vars
-3. Next.js dev server starts with live polling enabled
-4. Browser opens to `http://localhost:4321`
-5. Charts load from filesystem automatically
-6. Live polling detects agent writes → UI auto-refreshes
-7. User navigates charts while agent continues working
-8. SIGINT → graceful shutdown
-
----
-
-## ✅ Quality Criteria
-
-✅ **Zero-Config Startup**
-- Sensible defaults for all settings (port 4321, ./memory.jsonl, no live mode)
-- Works with just `coaia-visualizer` in a directory with `memory.jsonl`
-
-✅ **Configuration Flexibility**
-- Three-layer configuration (flags > env > defaults)
-- All settings available as both flags and environment variables
-
-✅ **Docker Parity**
-- Docker mode produces identical user experience to local mode
-- Volume mounting correctly maps host file into container
-- Environment variables pass through to container
-
-✅ **Graceful Lifecycle**
-- Auto-open browser after startup delay
-- SIGINT terminates child process cleanly
-- Docker `--rm` flag cleans up containers
-
----
-
-## 🔗 Related Components
-
-- [api-mcp-interface.spec.md](./api-mcp-interface.spec.md) — API routes served by the server CLI starts
-- [app.spec.md](./app.spec.md) — full application that CLI launches