coaiajs 0.1.0 → 0.1.1

package/rispecs/01-core-config.spec.md

@@ -9,7 +9,7 @@ A unified config loader that provides every CoAiA module with its settings throu
 ## Structural Tension
 
 **Current Reality:**
-- `src/config.ts` is fully implemented (172 lines) with `readConfig()`, `getConfig()`, `mergeConfigs()`, `resetConfig()`, and a `config` Proxy for lazy access
+- [`src/config.ts`](../src/config.ts) is implemented with `readConfig()`, `getConfig()`, `mergeConfigs()`, `resetConfig()`, and a `config` Proxy for lazy access
 - Supports env vars > .env > coaia.json > defaults priority chain
 - Searches for `coaia.json` or `.coaia/config.json` in cwd and home directory
 - Covers Redis (URL, host/port, Upstash), Langfuse, OpenAI, AWS, GitHub credentials
@@ -30,42 +30,12 @@ Config system that handles all module configuration needs including:
 
 ```typescript
 interface CoaiaConfig {
-  // Redis
-  redis_url?: string;
-  redis_host?: string;
-  redis_port?: number;
-
-  // Langfuse
-  langfuse_secret_key?: string;
-  langfuse_public_key?: string;
-  langfuse_host?: string;
-  langfuse_dataset_name?: string;
-  langfuse_prompt_cache_ttl?: number;
-
-  // OpenAI
-  openai_api_key?: string;
-  openai_model?: string;
-
-  // AWS (Polly)
-  aws_access_key_id?: string;
-  aws_secret_access_key?: string;
-  aws_region?: string;
-  aws_polly_voice?: string;
-
-  // GitHub
-  github_token?: string;
-
-  // Narrative
-  memory_file_path?: string;
-
-  // PDE
-  pde_dir?: string;
-
-  // Pipeline
-  pipeline_template_dir?: string;
-
-  // MCP
-  mcp_mode?: 'MINIMAL' | 'STANDARD' | 'FULL';
+  redis?: { url?: string; host?: string; port?: number; password?: string; upstashUrl?: string; upstashToken?: string };
+  langfuse?: { publicKey?: string; secretKey?: string; baseUrl?: string };
+  openai?: { apiKey?: string; model?: string };
+  aws?: { accessKeyId?: string; secretAccessKey?: string; region?: string };
+  github?: { token?: string };
+  [key: string]: unknown;
 }
 ```
 

package/rispecs/02-redis-module.spec.md

@@ -9,11 +9,12 @@ A thin Redis wrapper providing `tash(key, value, ttl?)` and `fetch(key)` with la
 ## Structural Tension
 
 **Current Reality:**
-- `src/redis.ts` is fully implemented (94 lines) with `tash()`, `fetch()`, `del()`, `keys()`, `exists()`, `disconnect()`, `resetClient()`
+- [`src/redis.ts`](../src/redis.ts) is implemented with `tash()`, `fetch()`, `del()`, `keys()`, `exists()`, `disconnect()`, `resetClient()`
 - Uses ioredis with lazy connection
 - Supports direct URL, Upstash REST (`rediss://`) URLs, host/port fallback
 - Key-value operations with optional TTL
 - Parity with coaiapy's `tash/fetch` pattern achieved
+- [`mcp/server.ts`](../mcp/server.ts) wires `coaia_tash` and `coaia_fetch` through the Redis module.
 
 **Desired Outcome:**
 Redis module with everything currently implemented plus:

package/rispecs/03-langfuse-module.spec.md

@@ -9,11 +9,13 @@ A comprehensive Langfuse client covering traces, observations, prompts, datasets
 ## Structural Tension
 
 **Current Reality:**
-- `src/langfuse/` directory exists but is empty
-- Types defined in `src/types.ts`: `ScoreCategory`, `ScoreConfig`
-- coaiapy's `cofuse.py` is 4,480 lines covering: traces, observations (spans/generations/events), prompts, datasets, scores, score configs, comments, media, projects
-- cofuse.py uses raw `requests` library against Langfuse REST API
-- No MCP tools exist for Langfuse in any parent project
+- [`src/langfuse/`](../src/langfuse/) is implemented as a REST client module split by domain:
+  - [`client.ts`](../src/langfuse/client.ts) centralizes auth, base URL, JSON requests, and errors.
+  - [`traces.ts`](../src/langfuse/traces.ts), [`observations.ts`](../src/langfuse/observations.ts), [`prompts.ts`](../src/langfuse/prompts.ts), [`datasets.ts`](../src/langfuse/datasets.ts), [`scores.ts`](../src/langfuse/scores.ts), [`comments.ts`](../src/langfuse/comments.ts), and [`media.ts`](../src/langfuse/media.ts) port the coaiapy `cofuse.py` surface.
+  - [`index.ts`](../src/langfuse/index.ts) exposes a public barrel for `coaiajs/langfuse`.
+- [`mcp/server.ts`](../mcp/server.ts) wires coaiapy-compatible Langfuse MCP tools such as `coaia_fuse_trace_create`, `coaia_fuse_add_observation`, `coaia_fuse_score_apply`, comments, prompts, datasets, and media.
+- Types defined in [`src/types.ts`](../src/types.ts): `ScoreCategory`, `ScoreConfig`.
+- Remaining gap: not every Langfuse formatting and cache helper from `cofuse.py` has a TypeScript equivalent; the core trace/observation/prompt/dataset/score/comment/media path is present.
 
 **Desired Outcome:**
 TypeScript Langfuse client with:

package/rispecs/04-narrative-engine.spec.md

@@ -11,15 +11,15 @@ A KnowledgeGraphManager that provides full CRUD for entities and relations store
 ## Structural Tension
 
 **Current Reality:**
-- `src/narrative/` directory exists but is empty
-- Types fully defined in `src/types.ts`: `Entity`, `EntityMetadata`, `Relation`, `RelationMetadata`, `KnowledgeGraph`, `McpToolResult`
-- coaia-narrative v0.12.0 has a working implementation:
-  - `graph-manager.ts` (1,294 lines) — the core engine
-  - `tool-definitions.ts` — 27 MCP tool schemas
-  - `tool-handlers.ts` — tool implementation connecting MCP to graph manager
-  - `tool-groups.ts` — tool filtering by group (STC_TOOLS, KG_TOOLS, CORE_TOOLS)
-  - `types.ts` — type definitions (absorbed into coaiajs `src/types.ts`)
-- coaia-narrative rispecs are the most mature (15 specs) — detailed behavioral specifications exist for every capability
+- [`src/narrative/`](../src/narrative/) is implemented:
+  - [`graph-manager.ts`](../src/narrative/graph-manager.ts) is the core JSONL graph/STC/narrative/MMOT engine.
+  - [`tool-definitions.ts`](../src/narrative/tool-definitions.ts) defines the MCP tool schemas and groups.
+  - [`tool-handlers.ts`](../src/narrative/tool-handlers.ts) connects MCP tool calls to `KnowledgeGraphManager`.
+  - [`markdown-export.ts`](../src/narrative/markdown-export.ts) handles chart, progress, stats, and all-chart markdown exports.
+  - [`index.ts`](../src/narrative/index.ts) exposes library and CLI helper functions for `coaiajs/narrative`.
+- Types are shared through [`src/types.ts`](../src/types.ts) and re-exported through [`src/narrative/types.ts`](../src/narrative/types.ts).
+- [`mcp/server.ts`](../mcp/server.ts) now routes narrative tools to `handleToolCall()` with a `KnowledgeGraphManager`.
+- `coaia narrative list` smoke-tested successfully against an empty memory file.
 
 **Desired Outcome:**
 Narrative engine in `src/narrative/` that:

package/rispecs/05-pde-engine.spec.md

@@ -9,13 +9,15 @@ A PDE module that transforms `DecompositionResult` objects into coaia-narrative-
 ## Structural Tension
 
 **Current Reality:**
-- `src/pde/` directory exists but is empty
-- PDE types fully defined in `src/types.ts`: `DecompositionResult`, `PrimaryIntent`, `SecondaryIntent`, `DirectionMap`, `ActionItem`, `AmbiguityFlag`, `StoredDecomposition`, `PdeSession`
-- coaia-pde v0.1.1 has a working implementation:
-  - `stc-mapper.ts` (~300 lines) — transforms DecompositionResult → Entity[]/Relation[]
-  - `session-manager.ts` — persists PDE sessions as JSONL
-  - `mcp-server.ts` — 12 MCP tools
-- coaia-pde rispec exists: `pde-to-stc-transformation.rispec.md` — defines the Four Directions → STC mapping
+- [`src/pde/`](../src/pde/) is implemented:
+  - [`stc-mapper.ts`](../src/pde/stc-mapper.ts) transforms `DecompositionResult` into coaia-narrative-compatible `Entity[]` and `Relation[]`.
+  - [`session-manager.ts`](../src/pde/session-manager.ts) persists PDE/STC sessions as JSONL in `.coaia/pde/`.
+  - [`mcp-tools.ts`](../src/pde/mcp-tools.ts) defines 10 implemented MCP tool schemas.
+  - [`mcp-handlers.ts`](../src/pde/mcp-handlers.ts) handles import, STC creation, session listing/viewing, action progress, action completion, current-reality updates, and session completion.
+  - [`index.ts`](../src/pde/index.ts) exposes library and CLI helper functions.
+- PDE types are defined in [`src/types.ts`](../src/types.ts): `DecompositionResult`, `PrimaryIntent`, `SecondaryIntent`, `DirectionMap`, `ActionItem`, `AmbiguityFlag`, `StoredDecomposition`, `PdeSession`.
+- [`mcp/server.ts`](../mcp/server.ts) wires PDE tools and namespaces session-action tools that conflict with narrative names (`pde_add_action_step`, `pde_update_current_reality`, etc.).
+- Remaining gap: prompt decomposition itself (`pde_decompose`, `pde_parse_response`, `pde_get`, `pde_list`, `pde_export_markdown`) is not implemented inside `coaiajs`; `coaiajs` currently consumes stored/external PDE outputs and maps them to STC.
 
 **Desired Outcome:**
 PDE engine in `src/pde/` that:
@@ -77,22 +79,20 @@ class SessionManager {
 }
 ```
 
-## MCP Tools (12)
+## MCP Tools (Implemented)
 
 | Tool | Purpose |
 |------|---------|
-| `pde_decompose` | Build prompts for LLM-driven decomposition |
-| `pde_parse_response` | Parse LLM response into DecompositionResult |
-| `pde_get` | Retrieve stored decomposition by ID |
-| `pde_list` | List stored decompositions |
-| `pde_export_markdown` | Export as git-diffable markdown |
-| `pde_to_stc` | Transform decomposition into STC |
-| `pde_preview_stc` | Preview STC mapping without creating |
-| `pde_create_session` | Create new PDE session |
-| `pde_get_session` | Get session details |
-| `pde_list_sessions` | List all sessions |
-| `pde_session_status` | Get session transformation status |
-| `pde_bridge_plan` | Bridge to planning engine |
+| `import_pde_decomposition` | Load stored `.pde` decomposition and create an STC session |
+| `create_stc_from_pde` | Create an STC session from an in-memory `DecompositionResult` |
+| `list_pde_decompositions` | List importable stored PDE decomposition files |
+| `get_session` | Get PDE/STC session state |
+| `list_sessions` | List PDE/STC sessions |
+| `pde_update_action_progress` | Add factual progress to a session action |
+| `pde_mark_action_complete` | Mark a session action complete |
+| `pde_add_action_step` | Add a session action step |
+| `pde_update_current_reality` | Add observations to session current reality |
+| `complete_session` | Mark a session completed |
 
 ## Relation to Planning Engine
 
@@ -106,7 +106,7 @@ Claude Plan mode → plan.md → coaiajs planning-engine → narrative JSONL →
 ## Quality Criteria
 
 - ✅ StcMapper produces entities/relations compatible with narrative engine's JSONL format
-- ✅ All 12 coaia-pde MCP tools produce identical results
-- ✅ PDE sessions are persisted as `.pde/*.json` files
-- ✅ Preview mapping shows the transformation without side effects
+- ✅ Implemented PDE MCP tools route through `mcp/server.ts`
+- ✅ PDE sessions are persisted as `.coaia/pde/*.jsonl` files
+- ⚠️ Preview mapping and native prompt decomposition remain desired capabilities
 - ✅ Ambiguities from decomposition surface as tension sources in the STC

package/rispecs/06-planning-engine.spec.md

@@ -9,12 +9,13 @@ A planning module that parses markdown plans (particularly Claude Plan mode outp
 ## Structural Tension
 
 **Current Reality:**
-- `src/planning/` directory exists but is empty
-- Types defined in `src/types.ts`: `StructuralTensionPlan`, `StructuralElement`
-- coaia-planning v0.1.0 has a working implementation:
-  - `plan-parser.ts` (821 lines) — parses markdown plans into structured objects
-  - `tools/index.ts` — 5 MCP tools + 1 PDE bridge tool
-- No rispecs exist for coaia-planning — this is the first specification
+- [`src/planning/`](../src/planning/) is implemented:
+  - [`plan-parser.ts`](../src/planning/plan-parser.ts) parses markdown plans, converts plans to STC entities/relations, exports JSONL, and converts `DecompositionResult` to plan/STC output.
+  - [`mcp-tools.ts`](../src/planning/mcp-tools.ts) defines 6 MCP tool schemas.
+  - [`mcp-handlers.ts`](../src/planning/mcp-handlers.ts) handles parse, plan-to-STC, plan-to-chart sync, chart-to-plan sync, plan trace creation, and PDE-to-plan conversion.
+  - [`index.ts`](../src/planning/index.ts) exposes library and CLI helper functions.
+- Types are defined in [`src/types.ts`](../src/types.ts): `StructuralTensionPlan`, `StructuralElement`.
+- [`mcp/server.ts`](../mcp/server.ts) routes planning tools to `handlePlanningTool()`.
 
 **Desired Outcome:**
 Planning engine in `src/planning/` that:
@@ -108,21 +109,21 @@ STC → Plan:
 
 Conflict resolution: STC wins by default (it is the source of truth). Conflicts are reported in `SyncResult.conflicts` for human review.
 
-## MCP Tools (6)
+## MCP Tools (Implemented)
 
 | Tool | Purpose |
 |------|---------|
-| `plan_parse` | Parse markdown plan into structured object |
+| `parse_plan_structural` | Parse markdown plan into structured object |
 | `plan_to_stc` | Convert parsed plan to STC entities |
-| `plan_from_stc` | Generate plan markdown from STC |
-| `plan_sync` | Bidirectional sync between plan and STC |
-| `plan_diff` | Show differences between plan and STC |
-| `plan_bridge_pde` | Import PDE decomposition as plan |
+| `sync_plan_to_chart` | Write plan-derived STC JSONL |
+| `sync_chart_to_plan` | Generate plan markdown from STC JSONL |
+| `create_plan_trace` | Generate trace payload for plan→STC transformation |
+| `pde_to_plan` | Convert PDE decomposition into STC JSONL |
 
 ## Quality Criteria
 
 - ✅ Parses Claude Plan mode output without modification
 - ✅ Checkbox state (`[ ]` / `[x]`) maps correctly to action completion
 - ✅ Sub-items preserved through parse → STC → plan round-trip
-- ✅ Bidirectional sync detects and reports conflicts
+- ✅ Bidirectional sync supports dry-run and write modes
 - ✅ Generated markdown is readable and re-parseable

package/rispecs/07-pipeline-templates.spec.md

@@ -9,13 +9,13 @@ A template engine that loads pipeline definitions, renders them with `{{variable
 ## Structural Tension
 
 **Current Reality:**
-- `src/pipeline/` directory exists but is empty
-- Types defined in `src/types.ts`: `PipelineVariable`, `PipelineStep`, `PipelineTemplate`
-- coaiapy has two relevant files:
-  - `pipeline.py` — loads and executes pipeline templates
-  - `mobile_template.py` — a specific pipeline template for mobile workflows
-- Pipeline templates use `{{variable}}` Mustache-style substitution
-- No MCP tools exist for pipelines in any parent project
+- [`src/pipeline/`](../src/pipeline/) is implemented:
+  - [`template-engine.ts`](../src/pipeline/template-engine.ts) ports coaiapy `pipeline.py` and `mobile_template.py` patterns into `MobileTemplateEngine`, `TemplateLoader`, and `TemplateRenderer`.
+  - [`index.ts`](../src/pipeline/index.ts) exports the public pipeline API.
+- Types are defined in [`src/types.ts`](../src/types.ts): `PipelineVariable`, `PipelineStep`, `PipelineTemplate`.
+- Pipeline templates use `{{variable}}` substitution, simple filters, conditionals, defaults, and built-in functions.
+- [`mcp/resources.ts`](../mcp/resources.ts) exposes template listing, template detail, and template-variable resources.
+- Remaining gap: pipeline execution as a first-class MCP tool remains desired; current implementation renders template steps but does not execute external action dependencies.
 
 **Desired Outcome:**
 Pipeline engine in `src/pipeline/` that:

package/rispecs/08-cli-interface.spec.md

@@ -9,12 +9,11 @@ A single `coaia` CLI binary that provides subcommands for every CoAiA module —
 ## Structural Tension
 
 **Current Reality:**
-- CLI entry point defined in `package.json` as `"coaia": "./dist/src/cli.js"` but no implementation exists
-- commander dependency is installed
-- coaiapy has an argparse-based CLI covering: tash, fetch, env, pipeline, transcribe, synthesize, fuse, gh
-- coaia-narrative has a minimist-based CLI covering: chart visualization, markdown export, progress display
-- coaia-pde has no CLI
-- coaia-planning has no CLI
+- [`package.json`](../package.json) defines `"coaia": "./dist/src/cli.js"`.
+- [`src/cli.ts`](../src/cli.ts) implements a commander-based CLI covering root coaiapy parity commands, Langfuse, pipeline, environment, GitHub, narrative, PDE, and planning command groups.
+- [`src/narrative/index.ts`](../src/narrative/index.ts), [`src/pde/index.ts`](../src/pde/index.ts), and [`src/planning/index.ts`](../src/planning/index.ts) expose helper functions used by the CLI dynamic module loader.
+- `npx coaia --help` works from an installed package tarball.
+- Remaining gaps: `synthesize` and explicit `mcp` CLI subcommands are desired but not currently registered as CLI groups.
 
 **Desired Outcome:**
 Unified CLI at `src/cli.ts` using commander, with subcommands:
@@ -26,12 +25,10 @@ coaia env [list|get|set|unset|init]
 coaia fuse [traces|trace|prompts|scores|datasets]
 coaia pipeline [list|render|execute] <template>
 coaia transcribe <audio-file>
-coaia synthesize <text> --output <file>
 coaia gh [issues|issue|comments]
 coaia narrative [charts|chart|progress|export]
-coaia pde [decompose|list|get|export|to-stc]
-coaia plan [parse|to-stc|from-stc|sync|diff]
-coaia mcp [start|tools]
+coaia pde [import|list|sessions|show]
+coaia plan [parse|convert|sync-to-chart|sync-to-plan]
 ```
 
 ## Core Structure
@@ -54,7 +51,6 @@ program.addCommand(ghCommands());
 program.addCommand(narrativeCommands());
 program.addCommand(pdeCommands());
 program.addCommand(planCommands());
-program.addCommand(mcpCommands());
 ```
 
 ## Command Details
@@ -95,26 +91,18 @@ coaia narrative export <id> [--format md|json]  # Export chart
 
 ### PDE Commands
 ```
-coaia pde decompose <prompt>            # Decompose a prompt
+coaia pde import <id>                   # Import stored PDE decomposition into STC session
 coaia pde list                          # List decompositions
-coaia pde get <id>                      # Get decomposition
-coaia pde export <id>                   # Export as markdown
-coaia pde to-stc <id>                   # Transform to STC
+coaia pde sessions                      # List PDE sessions
+coaia pde show <session-id>             # Show PDE session state
 ```
 
 ### Plan Commands
 ```
 coaia plan parse <file>                 # Parse plan markdown
-coaia plan to-stc <file>                # Convert plan to STC
-coaia plan from-stc <chart-id>          # Generate plan from STC
-coaia plan sync <file> <chart-id>       # Bidirectional sync
-coaia plan diff <file> <chart-id>       # Show differences
-```
-
-### MCP Commands
-```
-coaia mcp start [--mode MINIMAL|STANDARD|FULL]  # Start MCP server
-coaia mcp tools [--mode X]                       # List available tools
+coaia plan convert <file>               # Convert plan to STC JSONL
+coaia plan sync-to-chart <file> <jsonl> # Sync plan into chart JSONL
+coaia plan sync-to-plan <jsonl> <file>  # Sync chart JSONL back to plan markdown
 ```
 
 ## Output Formatting

package/rispecs/09-mcp-server.spec.md

@@ -9,36 +9,36 @@ A single MCP server (`coaiajs-mcp`) that consolidates the 44 tools from coaia-na
 ## Structural Tension
 
 **Current Reality:**
-- MCP server entry defined in `package.json` as `"coaiajs-mcp": "./dist/mcp/server.js"` but `mcp/` directory is empty (only a `tools/` subdirectory stub)
-- `@modelcontextprotocol/sdk` v1.25.0 is installed as a dependency
-- Four separate MCP servers exist in parent projects:
-  - coaia-narrative: 27 tools (STC lifecycle, knowledge graph, narrative beats, MMOT)
-  - coaia-pde: 12 tools (decomposition, session management, STC transformation)
-  - coaia-planning: 5 tools (plan parsing, plan↔STC sync, PDE bridge)
-  - coaiapy: 0 MCP tools (Python library only, no MCP)
-- Each parent server has its own startup, tool registration, and transport handling
-- Users currently need 3 MCP server entries in their config to access all tools
+- [`package.json`](../package.json) defines `"coaiajs-mcp": "./dist/mcp/server.js"`.
+- [`mcp/server.ts`](../mcp/server.ts) implements stdio MCP transport using `@modelcontextprotocol/sdk`.
+- [`mcp/config.ts`](../mcp/config.ts) implements `MINIMAL`, `STANDARD`, `OBSERVABILITY`, and `FULL` feature sets via `COAIAJS_FEATURES` or `--features`.
+- [`mcp/tools/coaiapy-tools.ts`](../mcp/tools/coaiapy-tools.ts) defines coaiapy-compatible Redis and Langfuse tool schemas.
+- [`mcp/resources.ts`](../mcp/resources.ts) implements `coaia://templates/` resources backed by the pipeline template loader.
+- [`mcp/prompts.ts`](../mcp/prompts.ts) implements the three coaiapy-mcp prompt templates.
+- `npx coaiajs-mcp` starts successfully from an installed package tarball and reports `STANDARD: 64 tools, 3 prompts, 3 resources`.
+- Remaining gap: several desired package-native tool groups (audio and pipeline execution tools) are not exposed as standalone MCP tools yet; pipeline templates are currently exposed as resources.
 
 **Desired Outcome:**
 Single MCP server at `mcp/server.ts` providing:
-- All 44 parent tools with identical schemas and behavior
-- 20 new tools for previously-CLI-only functionality
-- Feature gating via `COAIAJS_MCP_MODE` environment variable
+- Parent and coaiapy-compatible tools through one stdio server
+- Template resources and workflow prompts from coaiapy-mcp
+- Feature gating via `COAIAJS_FEATURES` or `--features`
 - Single server entry in MCP client config
 
 ## Feature Gating
 
 ```typescript
-type McpMode = 'MINIMAL' | 'STANDARD' | 'FULL';
+type FeatureLevel = 'MINIMAL' | 'STANDARD' | 'OBSERVABILITY' | 'FULL';
 ```
 
 | Mode | Tools loaded | Use case |
 |------|-------------|----------|
-| **MINIMAL** | STC tools (11), KG tools (9), MMOT (2), narrative beats (3) = **25** | Memory-constrained agents, basic STC workflow |
-| **STANDARD** | MINIMAL + PDE (12) + planning (6) + Redis (5) = **48** | Standard development sessions |
-| **FULL** | STANDARD + Langfuse (8) + pipeline (3) + audio (2) + guidance (3) = **64** | Full-featured agent sessions |
+| **MINIMAL** | Redis + Langfuse observability core tools | Observability-only sessions |
+| **STANDARD** | MINIMAL + narrative + PDE + planning tools | Standard development sessions |
+| **OBSERVABILITY** | Alias of STANDARD in current implementation | Compatibility mode |
+| **FULL** | All registered tools, including media tools | Full-featured agent sessions |
 
-Default mode: `STANDARD`.
+Default feature level: `STANDARD`.
 
 ## Server Architecture
 
@@ -82,47 +82,44 @@ Narrative Beats: `create_narrative_beat`, `telescope_narrative_beat`, `list_narr
 
 MMOT: `perform_mmot_evaluation`, `init_llm_guidance`
 
-### PDE Engine (12 tools — STANDARD+)
+### PDE Engine (10 tools — STANDARD+)
 
-`pde_decompose`, `pde_parse_response`, `pde_get`, `pde_list`, `pde_export_markdown`, `pde_to_stc`, `pde_preview_stc`, `pde_create_session`, `pde_get_session`, `pde_list_sessions`, `pde_session_status`, `pde_bridge_plan`
+`import_pde_decomposition`, `create_stc_from_pde`, `list_pde_decompositions`, `get_session`, `list_sessions`, `pde_update_action_progress`, `pde_mark_action_complete`, `pde_add_action_step`, `pde_update_current_reality`, `complete_session`
 
 ### Planning Engine (6 tools — STANDARD+)
 
-`plan_parse`, `plan_to_stc`, `plan_from_stc`, `plan_sync`, `plan_diff`, `plan_bridge_pde`
+`parse_plan_structural`, `plan_to_stc`, `sync_plan_to_chart`, `sync_chart_to_plan`, `create_plan_trace`, `pde_to_plan`
 
-### Redis (5 tools — STANDARD+)
+### Redis
 
-`redis_tash`, `redis_fetch`, `redis_del`, `redis_keys`, `redis_exists`
+`coaia_tash`, `coaia_fetch`
 
-### Langfuse (8 tools — FULL only)
+### Langfuse
 
-`langfuse_list_traces`, `langfuse_get_trace`, `langfuse_list_prompts`, `langfuse_get_prompt`, `langfuse_list_datasets`, `langfuse_list_scores`, `langfuse_create_score`, `langfuse_list_score_configs`
+`coaia_fuse_trace_create`, `coaia_fuse_add_observation`, `coaia_fuse_trace_patch_output`, `coaia_fuse_trace_get`, `coaia_fuse_trace_view`, `coaia_fuse_observation_get`, `coaia_fuse_traces_list`, `coaia_fuse_traces_session_view`, comments, prompts, datasets, score configs, score application, and media tools.
 
-### Pipeline (3 tools — FULL only)
+### Resources
 
-`pipeline_list`, `pipeline_render`, `pipeline_execute`
+`coaia://templates/`, `coaia://templates/{name}`, `coaia://templates/{name}/variables`
 
-### Audio (2 tools — FULL only)
+### Prompts
 
-`audio_transcribe`, `audio_synthesize`
+`mia_miette_duo`, `create_observability_pipeline`, `analyze_audio_workflow`
 
 ## Tool Registration Pattern
 
-Each module provides a `registerXxxTools(server: McpServer)` function:
+The current server uses plain tool definition arrays plus dispatch handlers:
 
 ```typescript
-// mcp/tools/redis.ts
-export function registerRedisTools(server: McpServer) {
-  server.tool('redis_tash', 'Store a value in Redis with optional TTL', {
-    key: z.string().describe('Redis key'),
-    value: z.string().describe('Value to store'),
-    ttl: z.number().optional().describe('TTL in seconds'),
-  }, async ({ key, value, ttl }) => {
-    await tash(key, value, ttl);
-    return { content: [{ type: 'text', text: `Stored ${key}` }] };
-  });
-  // ... more tools
-}
+const allToolDefs = [
+  ...getCoaiapyToolDefinitions(featureConfig),
+  ...getNarrativeToolDefinitions(featureConfig),
+  ...getPdeToolDefinitions(featureConfig),
+  ...getPlanningToolDefinitions(featureConfig),
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allToolDefs }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => routeToolCall(request.params));
 ```
 
 ## Transport
@@ -132,9 +129,9 @@ stdio transport only (standard MCP pattern). Server reads JSON-RPC from stdin, w
 ## Quality Criteria
 
 - ✅ Single MCP config entry replaces three separate servers
-- ✅ All 44 parent tools produce identical results to their parent implementations
+- ✅ Implemented parent tools route to TypeScript handlers instead of placeholders
 - ✅ Feature gating reduces tool count without breaking functionality
-- ✅ `COAIAJS_MCP_MODE=MINIMAL` loads ≤25 tools
-- ✅ Server starts in <500ms for MINIMAL mode
+- ✅ `COAIAJS_FEATURES` and `--features` select feature level
+- ✅ Server starts from installed tarball with `npx coaiajs-mcp`
 - ✅ Tool descriptions are self-documenting (LLMs understand usage without external docs)
 - ✅ Error responses include actionable information

package/rispecs/10-audio-module.spec.md

@@ -9,11 +9,11 @@ An audio module providing speech-to-text transcription via OpenAI Whisper and te
 ## Structural Tension
 
 **Current Reality:**
-- `src/audio.ts` is fully implemented (76 lines) with `synthesize()` function using AWS Polly
-- `src/llm.ts` includes `transcribeAudio()` using OpenAI Whisper
+- [`src/audio.ts`](../src/audio.ts) implements `synthesize()` with AWS Polly and lazy client initialization.
+- [`src/llm.ts`](../src/llm.ts) implements `transcribeAudio()` with OpenAI Whisper and exposes `llm()`, `generateImage()`, and `abstractProcess()`.
 - Both use lazy client initialization
 - coaiapy's `syntation.py` provides the same functionality via boto3 and openai Python packages
-- No MCP tools exist for audio in any parent project
+- Remaining gap: audio is available through the library and CLI transcription path, but standalone MCP audio tools are not wired yet.
 
 **Desired Outcome:**
 Audio module consolidating transcription and synthesis in one place:

package/rispecs/KINSHIP.md

@@ -4,7 +4,7 @@
 
 **Name:** coaiajs rispecs
 **Role:** RISE-based structural specifications for the coaiajs platform
-**Status:** Genesis (2026-03-11)
+**Status:** Maintained implementation-linked specs (updated 2026-05-07)
 
 ## Lineage
 
@@ -34,10 +34,10 @@ These specifications synthesize the creative intent, structural patterns, and be
 ## Accountabilities
 
 1. **Completeness** — These specs are sufficient for another LLM to re-implement the entire coaiajs platform from scratch
-2. **Accuracy** — Current reality assessments are honest and factual, reflecting actual implementation state as of 2026-03-11
+2. **Accuracy** — Current reality assessments are honest and factual, reflecting actual implementation state as of 2026-05-07
 3. **Creative orientation** — All desired outcomes use creation language, not problem-solving language
 4. **Backward compatibility** — Specs preserve behavioral compatibility with parent projects
-5. **Independence** — Specs are codebase-agnostic; they describe behavior, not implementation
+5. **Traceability** — Specs link to the code files that carry current behavior
 
 ## Consumers
 
@@ -53,4 +53,4 @@ These specifications synthesize the creative intent, structural patterns, and be
 
 **Desired Outcome:** These rispecs serve as the single source of truth for what coaiajs should become — complete enough for autonomous re-implementation, accurate enough for MMOT self-evaluation.
 
-**Current Reality:** 13 spec files covering the full platform. Parent project rispecs remain authoritative for deep behavioral details (especially coaia-narrative's 15 specs). These specs provide the consolidation vision and module boundaries.
+**Current Reality:** 13 spec files covering the full platform. Parent project rispecs remain authoritative for deep behavioral details (especially coaia-narrative's 15 specs). These specs now include implementation links for `src/`, `mcp/`, and package metadata so evaluators can trace desired behavior to current code.

package/rispecs/README.md

@@ -7,6 +7,15 @@
 
 These rispecs define the structural specifications for **coaiajs** — the unified TypeScript platform that consolidates `coaiapy`, `coaia-narrative`, `coaia-pde`, and `coaia-planning` into a single modern Node.js package.
 
+## RISE Framework Source
+
+These specs use the RISE Framework at `/src/llms/llms-rise-framework.txt` as the governing method:
+
+- **Reverse-engineer** parent package behavior from `coaiapy`, `coaia-narrative`, `coaia-pde`, and `coaia-planning`.
+- **Intent-extract** the creative outcome each module makes possible.
+- **Specify** the structural tension between current implementation and desired package behavior.
+- **Export** enough code-linked detail for an evaluator or implementation agent to act without rediscovery.
+
 ## Specification Index
 
 ### Platform
@@ -73,6 +82,22 @@ These rispecs define the structural specifications for **coaiajs** — the unifi
 └─────────────────────────────────────────────────────┘
 ```
 
+## Implementation Map
+
+| Spec | Primary implementation |
+|------|------------------------|
+| 00 platform | [`package.json`](../package.json), [`src/index.ts`](../src/index.ts) |
+| 01 config | [`src/config.ts`](../src/config.ts), [`src/types.ts`](../src/types.ts) |
+| 02 redis | [`src/redis.ts`](../src/redis.ts), [`mcp/tools/coaiapy-tools.ts`](../mcp/tools/coaiapy-tools.ts) |
+| 03 langfuse | [`src/langfuse/`](../src/langfuse/), [`mcp/server.ts`](../mcp/server.ts) |
+| 04 narrative | [`src/narrative/`](../src/narrative/), [`src/narrative/index.ts`](../src/narrative/index.ts) |
+| 05 PDE | [`src/pde/`](../src/pde/), [`src/pde/mcp-tools.ts`](../src/pde/mcp-tools.ts) |
+| 06 planning | [`src/planning/`](../src/planning/), [`src/planning/mcp-tools.ts`](../src/planning/mcp-tools.ts) |
+| 07 pipeline | [`src/pipeline/`](../src/pipeline/), [`mcp/resources.ts`](../mcp/resources.ts) |
+| 08 CLI | [`src/cli.ts`](../src/cli.ts), [`package.json`](../package.json) `bin.coaia` |
+| 09 MCP | [`mcp/server.ts`](../mcp/server.ts), [`mcp/config.ts`](../mcp/config.ts), [`mcp/prompts.ts`](../mcp/prompts.ts) |
+| 10 audio | [`src/audio.ts`](../src/audio.ts), [`src/llm.ts`](../src/llm.ts) |
+
 ## Conventions
 
 - **Creative orientation**: Desired Outcome describes what IS CREATED, not what is fixed
@@ -80,7 +105,7 @@ These rispecs define the structural specifications for **coaiajs** — the unifi
 - **Structural tension**: The gap between current and desired that drives advancement
 - **Variable detail**: Broad for obvious patterns, precise for critical behavior
 - **Naming**: `NN-kebab-case.spec.md`
-- **Codebase-agnostic**: Specs describe behavior, not implementation details
+- **Code-linked**: Specs describe behavior and link to the implementation files that currently carry it
 
 ## Relationship to Parent Rispecs
 
@@ -91,10 +116,11 @@ These rispecs define the structural specifications for **coaiajs** — the unifi
 | coaia-planning | — | No rispecs yet — spec 06 here is the first |
 | coaiapy | — | No rispecs — specs 01-03, 07, 10 here are the first |
 
-## RISE Framework Reference
+## Maintenance Protocol
+
+When code changes, update the relevant spec in the same pass:
 
-These specs follow the RISE Framework (`/src/llms/llms-rise-framework.txt`):
-- **R**everse-engineer: Extract creative intent from parent projects
-- **I**ntent-extract: Identify what each module enables users to create
-- **S**pecify: Define structural tension between current and desired
-- **E**xport: Produce specs sufficient for autonomous re-implementation
+1. Adjust **Current Reality** to match implemented files and verified behavior.
+2. Add or revise implementation links in the local spec and this README map.
+3. Keep **Desired Outcome** forward-looking only where a gap remains.
+4. Re-run `npm run build`, `npm test`, and `npm pack --dry-run` before handing off.