coaiajs 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/KINSHIP.md +1 -1
  2. package/README.md +191 -75
  3. package/dist/mcp/config.d.ts.map +1 -0
  4. package/dist/mcp/config.js +0 -2
  5. package/dist/mcp/config.js.map +1 -0
  6. package/dist/mcp/prompts.d.ts.map +1 -0
  7. package/dist/mcp/prompts.js.map +1 -0
  8. package/dist/mcp/resources.d.ts.map +1 -0
  9. package/dist/mcp/resources.js.map +1 -0
  10. package/dist/mcp/server.d.ts.map +1 -0
  11. package/dist/mcp/server.js +1 -1
  12. package/dist/mcp/server.js.map +1 -0
  13. package/dist/mcp/tools/coaiapy-tools.d.ts.map +1 -0
  14. package/dist/mcp/tools/coaiapy-tools.js.map +1 -0
  15. package/dist/mcp/tools/index.d.ts.map +1 -0
  16. package/dist/mcp/tools/index.js.map +1 -0
  17. package/dist/src/audio.d.ts.map +1 -0
  18. package/dist/src/audio.js.map +1 -0
  19. package/dist/src/cli-helpers.d.ts.map +1 -0
  20. package/dist/src/cli-helpers.js.map +1 -0
  21. package/dist/src/cli.d.ts.map +1 -0
  22. package/dist/src/cli.js.map +1 -0
  23. package/dist/src/config.d.ts.map +1 -0
  24. package/dist/src/config.js.map +1 -0
  25. package/dist/src/environment.d.ts.map +1 -0
  26. package/dist/src/environment.js.map +1 -0
  27. package/dist/src/github.d.ts.map +1 -0
  28. package/dist/src/github.js.map +1 -0
  29. package/dist/src/index.d.ts +1 -0
  30. package/dist/src/index.d.ts.map +1 -0
  31. package/dist/src/index.js +1 -0
  32. package/dist/src/index.js.map +1 -0
  33. package/dist/src/langfuse/client.d.ts.map +1 -0
  34. package/dist/src/langfuse/client.js.map +1 -0
  35. package/dist/src/langfuse/comments.d.ts.map +1 -0
  36. package/dist/src/langfuse/comments.js.map +1 -0
  37. package/dist/src/langfuse/datasets.d.ts.map +1 -0
  38. package/dist/src/langfuse/datasets.js.map +1 -0
  39. package/dist/src/langfuse/index.d.ts.map +1 -0
  40. package/dist/src/langfuse/index.js.map +1 -0
  41. package/dist/src/langfuse/media.d.ts.map +1 -0
  42. package/dist/src/langfuse/media.js.map +1 -0
  43. package/dist/src/langfuse/observations.d.ts.map +1 -0
  44. package/dist/src/langfuse/observations.js.map +1 -0
  45. package/dist/src/langfuse/prompts.d.ts.map +1 -0
  46. package/dist/src/langfuse/prompts.js.map +1 -0
  47. package/dist/src/langfuse/scores.d.ts.map +1 -0
  48. package/dist/src/langfuse/scores.js.map +1 -0
  49. package/dist/src/langfuse/traces.d.ts.map +1 -0
  50. package/dist/src/langfuse/traces.js.map +1 -0
  51. package/dist/src/llm.d.ts.map +1 -0
  52. package/dist/src/llm.js.map +1 -0
  53. package/dist/src/narrative/graph-manager.d.ts.map +1 -0
  54. package/dist/src/narrative/graph-manager.js.map +1 -0
  55. package/dist/src/narrative/index.d.ts.map +1 -0
  56. package/dist/src/narrative/index.js.map +1 -0
  57. package/dist/src/narrative/markdown-export.d.ts.map +1 -0
  58. package/dist/src/narrative/markdown-export.js.map +1 -0
  59. package/dist/src/narrative/tool-definitions.d.ts.map +1 -0
  60. package/dist/src/narrative/tool-definitions.js.map +1 -0
  61. package/dist/src/narrative/tool-handlers.d.ts.map +1 -0
  62. package/dist/src/narrative/tool-handlers.js.map +1 -0
  63. package/dist/src/narrative/types.d.ts.map +1 -0
  64. package/dist/src/narrative/types.js.map +1 -0
  65. package/dist/src/narrative/validation.d.ts.map +1 -0
  66. package/dist/src/narrative/validation.js.map +1 -0
  67. package/dist/src/pde/index.d.ts.map +1 -0
  68. package/dist/src/pde/index.js.map +1 -0
  69. package/dist/src/pde/mcp-handlers.d.ts.map +1 -0
  70. package/dist/src/pde/mcp-handlers.js.map +1 -0
  71. package/dist/src/pde/mcp-tools.d.ts.map +1 -0
  72. package/dist/src/pde/mcp-tools.js.map +1 -0
  73. package/dist/src/pde/session-manager.d.ts.map +1 -0
  74. package/dist/src/pde/session-manager.js.map +1 -0
  75. package/dist/src/pde/stc-mapper.d.ts.map +1 -0
  76. package/dist/src/pde/stc-mapper.js.map +1 -0
  77. package/dist/src/pipeline/index.d.ts.map +1 -0
  78. package/dist/src/pipeline/index.js.map +1 -0
  79. package/dist/src/pipeline/template-engine.d.ts.map +1 -0
  80. package/dist/src/pipeline/template-engine.js.map +1 -0
  81. package/dist/src/planning/index.d.ts.map +1 -0
  82. package/dist/src/planning/index.js.map +1 -0
  83. package/dist/src/planning/mcp-handlers.d.ts.map +1 -0
  84. package/dist/src/planning/mcp-handlers.js.map +1 -0
  85. package/dist/src/planning/mcp-tools.d.ts.map +1 -0
  86. package/dist/src/planning/mcp-tools.js.map +1 -0
  87. package/dist/src/planning/plan-parser.d.ts.map +1 -0
  88. package/dist/src/planning/plan-parser.js.map +1 -0
  89. package/dist/src/redis.d.ts.map +1 -0
  90. package/dist/src/redis.js.map +1 -0
  91. package/dist/src/types.d.ts.map +1 -0
  92. package/dist/src/types.js.map +1 -0
  93. package/dist/src/version.d.ts.map +1 -0
  94. package/dist/src/version.js.map +1 -0
  95. package/llms-full.txt +361 -0
  96. package/llms.txt +43 -0
  97. package/package.json +79 -12
  98. package/.claude/settings.local.json +0 -17
  99. package/.claude-plugin/marketplace.json +0 -26
  100. package/articles/academic/NOTES.md +0 -1
  101. package/articles/academic/README.md +0 -1
  102. package/articles/academic/creative-orientation-vs-problem-solving.md +0 -177
  103. package/articles/academic/jsonl-knowledge-graphs-agent-memory.md +0 -142
  104. package/articles/academic/langfuse-observability-llm-pipelines.md +0 -144
  105. package/articles/academic/medicine-wheel-software-architecture.md +0 -163
  106. package/articles/academic/mmot-autonomous-agents.md +0 -156
  107. package/articles/academic/model-context-protocol-interagent.md +0 -161
  108. package/articles/academic/pde-prompt-decomposition.md +0 -186
  109. package/articles/academic/structural-tension-in-ai-agents.md +0 -134
  110. package/articles/reviews/mcp-protocol-design-review.md +0 -170
  111. package/articles/reviews/observability-ai-systems-review.md +0 -176
  112. package/articles/reviews/prompt-engineering-decomposition-review.md +0 -184
  113. package/articles/surveys/agent-orchestration-survey.md +0 -186
  114. package/articles/surveys/knowledge-graph-storage-survey.md +0 -204
  115. package/articles/surveys/structural-tension-methodology-survey.md +0 -154
  116. package/articles/technical/aws-sdk-v3-polly.md +0 -270
  117. package/articles/technical/commander-cli-framework.md +0 -262
  118. package/articles/technical/dotenv-config-patterns.md +0 -360
  119. package/articles/technical/ioredis-vs-redis.md +0 -142
  120. package/articles/technical/langfuse-js-sdk-vs-rest.md +0 -191
  121. package/articles/technical/mcp-sdk-typescript.md +0 -291
  122. package/articles/technical/octokit-github-api.md +0 -293
  123. package/articles/technical/openai-sdk-modern.md +0 -231
  124. package/articles/technical/yaml-parsing-node.md +0 -266
  125. package/articles/technical/zod-runtime-validation.md +0 -212
  126. package/coaiajs-langfuse-claude-plugin/.claude-plugin/marketplace.json +0 -16
  127. package/coaiajs-langfuse-claude-plugin/.claude-plugin/plugin.json +0 -10
  128. package/coaiajs-langfuse-claude-plugin/.mcp.json +0 -8
  129. package/coaiajs-langfuse-claude-plugin/README.md +0 -60
  130. package/mcp/config.ts +0 -225
  131. package/mcp/prompts.ts +0 -131
  132. package/mcp/resources.ts +0 -84
  133. package/mcp/server.ts +0 -519
  134. package/mcp/tools/coaiapy-tools.ts +0 -366
  135. package/mcp/tools/index.ts +0 -4
  136. package/src/audio.ts +0 -76
  137. package/src/cli-helpers.ts +0 -86
  138. package/src/cli.ts +0 -1261
  139. package/src/config.ts +0 -207
  140. package/src/environment.ts +0 -171
  141. package/src/github.ts +0 -143
  142. package/src/index.ts +0 -82
  143. package/src/langfuse/client.ts +0 -105
  144. package/src/langfuse/comments.ts +0 -52
  145. package/src/langfuse/datasets.ts +0 -178
  146. package/src/langfuse/index.ts +0 -37
  147. package/src/langfuse/media.ts +0 -193
  148. package/src/langfuse/observations.ts +0 -155
  149. package/src/langfuse/prompts.ts +0 -157
  150. package/src/langfuse/scores.ts +0 -456
  151. package/src/langfuse/traces.ts +0 -353
  152. package/src/llm.ts +0 -106
  153. package/src/narrative/graph-manager.ts +0 -1358
  154. package/src/narrative/index.ts +0 -188
  155. package/src/narrative/markdown-export.ts +0 -535
  156. package/src/narrative/tool-definitions.ts +0 -635
  157. package/src/narrative/tool-handlers.ts +0 -528
  158. package/src/narrative/types.ts +0 -9
  159. package/src/narrative/validation.ts +0 -179
  160. package/src/pde/index.ts +0 -34
  161. package/src/pde/mcp-handlers.ts +0 -359
  162. package/src/pde/mcp-tools.ts +0 -201
  163. package/src/pde/session-manager.ts +0 -248
  164. package/src/pde/stc-mapper.ts +0 -298
  165. package/src/pipeline/index.ts +0 -7
  166. package/src/pipeline/template-engine.ts +0 -398
  167. package/src/planning/index.ts +0 -32
  168. package/src/planning/mcp-handlers.ts +0 -369
  169. package/src/planning/mcp-tools.ts +0 -155
  170. package/src/planning/plan-parser.ts +0 -587
  171. package/src/redis.ts +0 -111
  172. package/src/types.ts +0 -281
  173. package/src/version.ts +0 -39
  174. package/test/config.test.mjs +0 -93
  175. package/tsconfig.json +0 -26
package/llms-full.txt ADDED
@@ -0,0 +1,361 @@
1
+ # coaiajs — Full Reference
2
+
3
+ > Complete API surface for `coaiajs`: every entry point, every export, all 63 MCP tools, and the full CLI. Written for AI agents integrating against this package.
4
+
5
+ Package: `coaiajs` · License: MIT · Node.js >= 20 · **ESM only**
6
+
7
+ ---
8
+
9
+ ## 1. Orientation
10
+
11
+ `coaiajs` is the TypeScript consolidation of four CoAIA projects — `coaia-narrative` (knowledge graph, charts), `coaia-pde` (Prompt Decomposition Engine), `coaia-planning` (action planning), and `coaiapy` (Redis/LLM/audio/GitHub/config). It is consumable three ways, all sharing the same modules and the same type system (`src/types.ts`):
12
+
13
+ 1. **Library** — `import { ... } from 'coaiajs'`
14
+ 2. **CLI** — `npx coaia <command>`
15
+ 3. **MCP server** — `npx coaiajs-mcp` (stdio)
16
+
17
+ ### Central concept: the structural tension chart
18
+
19
+ The core data model comes from Robert Fritz's creative process framework. A chart holds three parts:
20
+
21
+ - **Desired Outcome** — what is to be created
22
+ - **Current Reality** — an honest assessment of where things stand
23
+ - **Action Steps** — steps holding the tension between the two; any step can *telescope* into its own sub-chart
24
+
25
+ Charts are stored as JSONL entities in a knowledge graph. "MMOT" (Managerial Moment of Truth) is a structured evaluation over a chart: acknowledge → analyze → plan → recommit.
26
+
27
+ ### Rules that prevent the common mistakes
28
+
29
+ - **ESM only.** `require('coaiajs')` fails. Use `import`. The package sets `"type": "module"`.
30
+ - **Never import `coaiajs/src/...`.** `src/` is not in the published tarball. Use the documented subpaths. (Older documentation showed `coaiajs/src/redis.js`; that path has never resolved from an installed package.)
31
+ - **No side effects at import.** Importing opens no connection and reads no file. Clients are constructed on first use.
32
+ - **Close what you open.** `disconnect()` on Redis; `resetClient()` on any module to drop cached client state (primarily for tests).
33
+
34
+ ---
35
+
36
+ ## 2. Installation
37
+
38
+ ```bash
39
+ npm install coaiajs
40
+ ```
41
+
42
+ ```typescript
43
+ import { tash, fetch, narrative } from 'coaiajs';
44
+ import { parsePlan } from 'coaiajs/planning';
45
+ import type { StructuralTensionPlan, Entity, CoaiaConfig } from 'coaiajs';
46
+ ```
47
+
48
+ TypeScript consumers should use `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` so the `exports` map and its `.d.ts` files resolve correctly.
49
+
50
+ ---
51
+
52
+ ## 3. Library API
53
+
54
+ Root import exposes everything below plus five namespaces (`langfuse`, `narrative`, `pde`, `planning`, `pipeline`) and 26 shared types. A subpath import and its root namespace are the same module.
55
+
56
+ ### `coaiajs/config`
57
+
58
+ ```
59
+ readConfig, getConfig, resetConfig, config, mergeConfigs, findExistingConfig, findEnvFiles
60
+ ```
61
+
62
+ Resolution order (highest wins): environment variables → `.env` files (explicit `--env`, `COAIAJS_ENV_PATH`, `COAIAPY_ENV_PATH`, `./.env`, `~/.coaia/.env`) → `coaia.json` (`./coaia.json`, `~/coaia.json`, `~/.coaia/config.json`) → defaults.
63
+
64
+ ### `coaiajs/redis`
65
+
66
+ ```
67
+ tash, fetch, del, keys, exists, disconnect, getClient, resetClient
68
+ ```
69
+
70
+ `tash`/`fetch` are SET/GET shorthand carried over from coaiapy. TTL is expressed in **minutes** at the CLI layer (default `5555`).
71
+
72
+ ```typescript
73
+ import { tash, fetch, disconnect } from 'coaiajs/redis';
74
+ await tash('session:42', JSON.stringify({ phase: 'design' }));
75
+ const raw = await fetch('session:42');
76
+ await disconnect();
77
+ ```
78
+
79
+ ### `coaiajs/llm`
80
+
81
+ ```
82
+ llm, transcribeAudio, generateImage, abstractProcess, resetClient
83
+ ```
84
+
85
+ OpenAI-backed. `abstractProcess` applies a named tag/template to text; `transcribeAudio` uses Whisper.
86
+
87
+ ### `coaiajs/audio`
88
+
89
+ ```
90
+ synthesize, resetClient
91
+ ```
92
+
93
+ AWS Polly text-to-speech.
94
+
95
+ ### `coaiajs/github`
96
+
97
+ ```
98
+ listIssues, getIssue, getIssueComments, resetClient
99
+ ```
100
+
101
+ Octokit-backed; reads `GITHUB_TOKEN`.
102
+
103
+ ### `coaiajs/environment`
104
+
105
+ ```
106
+ EnvironmentManager, createEnvironment, findEnvironment
107
+ ```
108
+
109
+ ### `coaiajs/version`
110
+
111
+ ```
112
+ getPackageVersion
113
+ ```
114
+
115
+ Returns the resolved version of the installed package, read from `package.json` at runtime.
116
+
117
+ ### `coaiajs/narrative`
118
+
119
+ ```
120
+ KnowledgeGraphManager, ValidationSchemas, validate,
121
+ addAction, completeAction, addObservation, setDueDate, setCurrentChart, getCurrentChart,
122
+ updateChart, viewChart, listCharts, getProgress, getStats, performMmot,
123
+ exportChart, exportAllCharts, exportChartToMarkdown, exportAllChartsToMarkdown,
124
+ exportChartProgress, exportChartStats, writeMarkdownToFile, getDefaultFilename,
125
+ handleToolCall, ALL_TOOL_DEFINITIONS, CORE_TOOLS, KG_TOOLS, NARRATIVE_TOOLS, STC_TOOLS
126
+ ```
127
+
128
+ ```typescript
129
+ import { KnowledgeGraphManager } from 'coaiajs/narrative';
130
+ const kg = new KnowledgeGraphManager('./memory.jsonl');
131
+ const graph = await kg.readGraph();
132
+ ```
133
+
134
+ ### `coaiajs/pde`
135
+
136
+ ```
137
+ SessionManager, sessionManager, StcMapper, stcMapper,
138
+ importDecomposition, listDecompositions, listSessions, showSession,
139
+ handlePdeTool, PDE_MCP_TOOLS
140
+ ```
141
+
142
+ ### `coaiajs/planning`
143
+
144
+ ```
145
+ parsePlan, parsePlanContent, planToSTC, convertToChart, decompositionResultToPlan,
146
+ syncToChart, syncToPlan, exportToJSONL, handlePlanningTool, PLANNING_MCP_TOOLS
147
+ ```
148
+
149
+ ```typescript
150
+ import { parsePlan, planToSTC } from 'coaiajs/planning';
151
+ const plan = await parsePlan('./PLAN.md');
152
+ const chart = planToSTC(plan);
153
+ ```
154
+
155
+ ### `coaiajs/pipeline`
156
+
157
+ ```
158
+ MobileTemplateEngine, TemplateLoader, TemplateRenderer
159
+ ```
160
+
161
+ ### `coaiajs/langfuse`
162
+
163
+ Client and errors: `LangfuseClient`, `LangfuseApiError`, `getClient`, `resetClient`, `nowISO`, `detectContentType`
164
+
165
+ - **Traces:** `createTrace`, `addTrace`, `getTrace`, `listTraces`, `patchTraceOutput`, `traceView`, `sessionView`
166
+ - **Observations:** `addObservation`, `addObservations`, `getObservation`
167
+ - **Prompts:** `createPrompt`, `getPrompt`, `listPrompts`
168
+ - **Datasets:** `createDataset`, `getDataset`, `listDatasets`, `createDatasetItem`, `listDatasetItems`
169
+ - **Scores:** `createScore`, `listScores`, `createScoreForTarget`, `applyScoreToTrace`, `createScoreConfig`, `getScoreConfig`, `listScoreConfigs`, `applyScoreConfig`, `importScoreConfigs`, `exportScoreConfigs`, `getBuiltInPresets`, `installPreset`
170
+ - **Comments:** `createComment`, `getComment`, `listComments`
171
+ - **Media:** `uploadAndAttachMedia`, `getMedia`
172
+ - **Formatters:** `formatTracesTable`, `formatTracesMarkdown`, `formatTraceTree`, `formatObservationDisplay`, `formatPromptDisplay`, `formatPromptsTable`, `formatDatasetsTable`, `formatDatasetForFinetuning`, `formatScoresTable`, `formatScoreConfigsTable`, `formatMediaDisplay`
173
+
174
+ ### Exported types
175
+
176
+ ```
177
+ Entity, EntityMetadata, Relation, RelationMetadata, KnowledgeGraph, McpToolResult,
178
+ PrimaryIntent, SecondaryIntent, ContextRequirements, ExpectedOutputs,
179
+ DirectionItem, DirectionMap, ActionItem, AmbiguityFlag,
180
+ DecompositionResult, StoredDecomposition, DecompositionOptions, PdeSession,
181
+ StructuralElement, StructuralTensionPlan,
182
+ ScoreCategory, ScoreConfig,
183
+ PipelineVariable, PipelineStep, PipelineTemplate, CoaiaConfig
184
+ ```
185
+
186
+ ---
187
+
188
+ ## 4. MCP Server
189
+
190
+ ```bash
191
+ npx coaiajs-mcp
192
+ ```
193
+
194
+ Transport: **stdio**. Serves **63 tools, 3 prompts, 1 listable resource**.
195
+
196
+ Flags: `--memory-path <path>` (JSONL knowledge graph), `--plans-dir <path>`, `--feature-level <level>`.
197
+
198
+ Claude Code / client registration:
199
+
200
+ ```json
201
+ {
202
+ "mcpServers": {
203
+ "coaia": { "command": "npx", "args": ["-y", "--package=coaiajs", "coaiajs-mcp"] }
204
+ }
205
+ }
206
+ ```
207
+
208
+ ### Feature levels
209
+
210
+ `COAIAJS_FEATURES` selects the exposed tool set; default `STANDARD`.
211
+
212
+ | Level | Effect |
213
+ |---|---|
214
+ | `MINIMAL` | Core tash/fetch and essential graph tools |
215
+ | `STANDARD` | Default — the 63 tools listed below |
216
+ | `OBSERVABILITY` | Same set as `STANDARD` |
217
+ | `FULL` | Everything, including media tools |
218
+
219
+ ### Tools — coaiapy + Langfuse (20)
220
+
221
+ ```
222
+ coaia_tash, coaia_fetch,
223
+ coaia_fuse_trace_create, coaia_fuse_add_observation, coaia_fuse_trace_patch_output,
224
+ coaia_fuse_trace_get, coaia_fuse_trace_view, coaia_fuse_observation_get,
225
+ coaia_fuse_traces_list, coaia_fuse_traces_session_view,
226
+ coaia_fuse_prompts_list, coaia_fuse_prompts_get,
227
+ coaia_fuse_datasets_list, coaia_fuse_datasets_get,
228
+ coaia_fuse_score_configs_list, coaia_fuse_score_configs_get, coaia_fuse_score_apply,
229
+ coaia_fuse_comments_list, coaia_fuse_comments_get, coaia_fuse_comments_create
230
+ ```
231
+
232
+ ### Tools — narrative / knowledge graph (27)
233
+
234
+ ```
235
+ create_entities, create_relations, add_observations,
236
+ delete_entities, delete_observations, delete_relations,
237
+ read_graph, search_nodes, open_nodes,
238
+ create_structural_tension_chart, manage_action_step, add_action_step,
239
+ telescope_action_step, remove_action_step, mark_action_complete,
240
+ get_chart_progress, list_active_charts, get_chart, get_action_step,
241
+ update_action_progress, update_current_reality, update_desired_outcome,
242
+ perform_mmot_evaluation,
243
+ create_narrative_beat, telescope_narrative_beat, list_narrative_beats,
244
+ init_llm_guidance
245
+ ```
246
+
247
+ ### Tools — PDE (10)
248
+
249
+ ```
250
+ import_pde_decomposition, create_stc_from_pde, list_pde_decompositions,
251
+ get_session, list_sessions, complete_session,
252
+ pde_update_action_progress, pde_mark_action_complete,
253
+ pde_add_action_step, pde_update_current_reality
254
+ ```
255
+
256
+ The last four carry a `pde_` prefix because their unprefixed names belong to the narrative group. Calling `add_action_step` targets the narrative chart; `pde_add_action_step` targets the PDE session.
257
+
258
+ ### Tools — planning (6)
259
+
260
+ ```
261
+ parse_plan_structural, plan_to_stc, sync_plan_to_chart,
262
+ sync_chart_to_plan, create_plan_trace, pde_to_plan
263
+ ```
264
+
265
+ ### Prompts (3)
266
+
267
+ - `mia_miette_duo` — dual AI embodiment for narrative-driven technical work
268
+ - `create_observability_pipeline` — step-by-step guide for creating a Langfuse observability pipeline
269
+ - `analyze_audio_workflow` — workflow for audio analysis
270
+
271
+ ### Resources
272
+
273
+ - `coaia://templates/` — listable; returns all pipeline templates
274
+ - `coaia://templates/{name}` — readable URI pattern; a single template
275
+ - `coaia://templates/{name}/variables` — readable URI pattern; a template's variables
276
+
277
+ ### Error convention
278
+
279
+ Tool failures return a normal result with `isError: true` and a text explanation rather than a JSON-RPC error. An unknown tool name yields `Unknown tool: <name>`.
280
+
281
+ ---
282
+
283
+ ## 5. CLI
284
+
285
+ ```bash
286
+ npx coaia <command>
287
+ ```
288
+
289
+ Global options: `--env <path>` · `-M, --memory-path <path>` · `--json` · `--no-color` · `-V, --version` · `-h, --help`
290
+
291
+ | Command | Aliases | Purpose |
292
+ |---|---|---|
293
+ | `tash <key> [value]` | `m` | Store a key-value pair in Redis. `-F/--file` reads value from a file; `-T/--ttl` in minutes (default 5555) |
294
+ | `fetch <key>` | | Get a value from Redis |
295
+ | `llm <user> [system]` | | Raw LLM call |
296
+ | `summarize [text]` | `s` | Summarize text |
297
+ | `transcribe <file>` | `t` | Transcribe audio via Whisper |
298
+ | `p <tag> [text]` | | Process text with a custom tag |
299
+ | `init` | | Create a sample `coaia.json` |
300
+ | `fuse` | | Langfuse operations |
301
+ | `narrative` | `n` | Structural tension chart operations |
302
+ | `pde` | | Prompt Decomposition Engine |
303
+ | `plan` | | Structural tension plan operations |
304
+ | `pipeline` | | Pipeline template operations |
305
+ | `env` | | Environment variable management |
306
+ | `gh` | | GitHub operations |
307
+
308
+ Subcommands:
309
+
310
+ - **`fuse`** — `traces`, `prompts`, `datasets`, `sessions`, `scores` (`sc`), `score-configs` (`scc`), `comments`, `media`, `dataset-items`, `projects`
311
+ - **`narrative`** — `list` (`ls`), `view` (`v`), `current` (`cur`), `update` (`up`), `add-action` (`aa`), `add-obs` (`ao`), `complete` (`done`), `export` (`exp`), `export-all`, `stats` (`st`), `progress` (`pg`), `mmot`, `set-date` (`sd`)
312
+ - **`pde`** — `import <pdeId>`, `list`, `sessions`, `show <sessionId>`
313
+ - **`plan`** — `parse <planPath>`, `convert <planPath>`, `sync-to-chart <planPath> <chartsPath>`, `sync-to-plan <chartsPath> <planPath>`
314
+ - **`pipeline`** — `list`, `show <name>`, `create <name>`, `init <name>`
315
+ - **`env`** — `init`, `list`, `source`, `set <key> <value>`, `get <key>`, `unset <key>`, `clear`, `save`
316
+ - **`gh`** — `issues`
317
+
318
+ ---
319
+
320
+ ## 6. Configuration reference
321
+
322
+ | Variable | Description |
323
+ |---|---|
324
+ | `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | Upstash Redis endpoint and token; preferred over direct Redis URLs |
325
+ | `KV_REST_API_URL` / `KV_REST_API_TOKEN` | Vercel KV REST aliases for Upstash Redis |
326
+ | `KV_URL` / `REDIS_URL` | Redis connection URL (`redis://` or `rediss://`) |
327
+ | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` / `REDIS_SSL` | Traditional Redis configuration |
328
+ | `UPSTASH_HOST` / `UPSTASH_PASSWORD` | coaiapy-compatible fallback aliases |
329
+ | `OPENAI_API_KEY` | OpenAI API key |
330
+ | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Langfuse credentials |
331
+ | `AWS_ACCESS_KEY_ID` | AWS credentials for Polly |
332
+ | `GITHUB_TOKEN` | GitHub API token |
333
+ | `COAIAJS_ENV_PATH` / `COAIAPY_ENV_PATH` | Explicit `.env` file locations |
334
+ | `COAIAJS_FEATURES` | MCP feature level |
335
+
336
+ `coaia.json`:
337
+
338
+ ```json
339
+ {
340
+ "redis": { "url": "redis://localhost:6379" },
341
+ "openai": { "apiKey": "sk-...", "model": "gpt-4o" },
342
+ "langfuse": { "publicKey": "pk-...", "secretKey": "sk-..." },
343
+ "github": { "token": "ghp_..." }
344
+ }
345
+ ```
346
+
347
+ ---
348
+
349
+ ## 7. Working on this codebase
350
+
351
+ ```bash
352
+ npm install
353
+ npm run build # tsc
354
+ npm run lint # tsc --noEmit
355
+ npm test # node --test
356
+ npm run dev # tsc --watch
357
+ ```
358
+
359
+ Conventions: ESM only, relative imports end in `.js` · `strict: true`, no unjustified `any` · shared types live in `src/types.ts` · clients lazy, each module exports `resetClient()` · no side effects at import time.
360
+
361
+ Per-module RISE specifications live in `rispecs/`, one file per module.
package/llms.txt ADDED
@@ -0,0 +1,43 @@
1
+ # coaiajs
2
+
3
+ > TypeScript package consolidating the CoAIA (Creative Orientation AI Architecture) ecosystem into one installable unit: a **library**, a **CLI** (`coaia`), and an **MCP server** (`coaiajs-mcp`, 63 tools). Its core data model is the *structural tension chart* — desired outcome, current reality, and telescoping action steps — backed by a JSONL knowledge graph.
4
+
5
+ Install with `npm install coaiajs`. Requires Node.js >= 20. **ESM only** — there is no CommonJS build, so `require('coaiajs')` will not work. Ships `.d.ts` for every entry point.
6
+
7
+ Key facts an agent usually needs first:
8
+
9
+ - Import from `coaiajs` (root) or a subpath such as `coaiajs/narrative`. **Do not** import `coaiajs/src/*.js` — `src/` is not shipped in the published package.
10
+ - Clients (Redis, OpenAI, Polly, Octokit) are lazy: importing a module opens no connection and reads no file. Call `disconnect()` when finished.
11
+ - Config precedence: environment variables > `.env` files > `coaia.json` > defaults.
12
+ - The MCP server serves 63 tools, 3 prompts, and 1 listable resource over stdio. `COAIAJS_FEATURES` (`MINIMAL`/`STANDARD`/`OBSERVABILITY`/`FULL`) controls the tool set; default is `STANDARD`.
13
+
14
+ ## Documentation
15
+
16
+ - [README](./README.md): install, the three consumption modes, configuration, architecture
17
+ - [llms-full.txt](./llms-full.txt): complete API surface — every export, every MCP tool, every CLI command, in one file
18
+ - [CLAUDE.md](./CLAUDE.md): repository conventions for agents working *on* this codebase
19
+ - [KINSHIP.md](./KINSHIP.md): lineage and type provenance from the four origin projects
20
+
21
+ ## Entry points
22
+
23
+ - `coaiajs`: everything, plus `langfuse`/`narrative`/`pde`/`planning`/`pipeline` namespaces and shared types
24
+ - `coaiajs/config`: configuration resolution — `readConfig`, `getConfig`, `resetConfig`
25
+ - `coaiajs/redis`: `tash`, `fetch`, `del`, `keys`, `exists`, `disconnect`
26
+ - `coaiajs/llm`: `llm`, `transcribeAudio`, `generateImage`, `abstractProcess`
27
+ - `coaiajs/audio`: `synthesize` (AWS Polly)
28
+ - `coaiajs/github`: `listIssues`, `getIssue`, `getIssueComments`
29
+ - `coaiajs/environment`: `EnvironmentManager`, `createEnvironment`, `findEnvironment`
30
+ - `coaiajs/version`: `getPackageVersion`
31
+ - `coaiajs/langfuse`: tracing, observations, prompts, datasets, scores, comments, media
32
+ - `coaiajs/narrative`: `KnowledgeGraphManager`, structural tension charts, markdown export
33
+ - `coaiajs/pde`: Prompt Decomposition Engine — sessions, STC mapping
34
+ - `coaiajs/planning`: `parsePlan`, `planToSTC`, `syncToChart`, `syncToPlan`
35
+ - `coaiajs/pipeline`: pipeline template engine
36
+
37
+ ## Specifications
38
+
39
+ - [rispecs/](./rispecs/): RISE specification files, one per module (config, redis, langfuse, narrative, PDE, planning, pipeline, CLI, MCP, audio)
40
+
41
+ ## Optional
42
+
43
+ - [Claude Code plugin](./coaiajs-langfuse-claude-plugin/): registers the MCP server in Claude Code via `npx`
package/package.json CHANGED
@@ -1,8 +1,74 @@
1
1
  {
2
2
  "name": "coaiajs",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "type": "module",
5
5
  "description": "CoAIA unified TypeScript monorepo — CLI, MCP server, and library consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy patterns into one package.",
6
+ "main": "./dist/src/index.js",
7
+ "types": "./dist/src/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/src/index.d.ts",
11
+ "import": "./dist/src/index.js"
12
+ },
13
+ "./config": {
14
+ "types": "./dist/src/config.d.ts",
15
+ "import": "./dist/src/config.js"
16
+ },
17
+ "./redis": {
18
+ "types": "./dist/src/redis.d.ts",
19
+ "import": "./dist/src/redis.js"
20
+ },
21
+ "./llm": {
22
+ "types": "./dist/src/llm.d.ts",
23
+ "import": "./dist/src/llm.js"
24
+ },
25
+ "./audio": {
26
+ "types": "./dist/src/audio.d.ts",
27
+ "import": "./dist/src/audio.js"
28
+ },
29
+ "./github": {
30
+ "types": "./dist/src/github.d.ts",
31
+ "import": "./dist/src/github.js"
32
+ },
33
+ "./environment": {
34
+ "types": "./dist/src/environment.d.ts",
35
+ "import": "./dist/src/environment.js"
36
+ },
37
+ "./version": {
38
+ "types": "./dist/src/version.d.ts",
39
+ "import": "./dist/src/version.js"
40
+ },
41
+ "./langfuse": {
42
+ "types": "./dist/src/langfuse/index.d.ts",
43
+ "import": "./dist/src/langfuse/index.js"
44
+ },
45
+ "./narrative": {
46
+ "types": "./dist/src/narrative/index.d.ts",
47
+ "import": "./dist/src/narrative/index.js"
48
+ },
49
+ "./pde": {
50
+ "types": "./dist/src/pde/index.d.ts",
51
+ "import": "./dist/src/pde/index.js"
52
+ },
53
+ "./planning": {
54
+ "types": "./dist/src/planning/index.d.ts",
55
+ "import": "./dist/src/planning/index.js"
56
+ },
57
+ "./pipeline": {
58
+ "types": "./dist/src/pipeline/index.d.ts",
59
+ "import": "./dist/src/pipeline/index.js"
60
+ },
61
+ "./package.json": "./package.json"
62
+ },
63
+ "files": [
64
+ "dist",
65
+ "rispecs",
66
+ "README.md",
67
+ "KINSHIP.md",
68
+ "CLAUDE.md",
69
+ "llms.txt",
70
+ "llms-full.txt"
71
+ ],
6
72
  "bin": {
7
73
  "coaia": "dist/src/cli.js",
8
74
  "coaiajs-mcp": "dist/mcp/server.js"
@@ -15,28 +81,29 @@
15
81
  "dev": "tsc --watch",
16
82
  "start": "node dist/src/cli.js",
17
83
  "mcp": "node dist/mcp/server.js",
84
+ "pretest": "tsc",
18
85
  "test": "node --test",
19
86
  "lint": "tsc --noEmit"
20
87
  },
21
88
  "dependencies": {
22
- "@modelcontextprotocol/sdk": "^1.25.0",
23
- "ioredis": "^5.4.0",
24
- "zod": "^3.23.0",
89
+ "@aws-sdk/client-polly": "^3.1117.0",
90
+ "@modelcontextprotocol/sdk": "^1.30.0",
91
+ "@octokit/rest": "^21.1.1",
92
+ "chalk": "^5.6.2",
25
93
  "commander": "^12.1.0",
26
- "openai": "^4.70.0",
27
- "@aws-sdk/client-polly": "^3.700.0",
28
- "@octokit/rest": "^21.0.0",
29
- "dotenv": "^16.4.0",
94
+ "dotenv": "^16.6.1",
95
+ "ioredis": "^5.11.1",
30
96
  "js-yaml": "^4.1.0",
31
- "langfuse": "^3.0.0",
97
+ "langfuse": "^3.38.20",
32
98
  "minimist": "^1.2.8",
33
- "chalk": "^5.3.0",
34
- "uuid": "^11.1.0"
99
+ "openai": "^4.104.0",
100
+ "uuid": "^11.1.1",
101
+ "zod": "^3.25.76"
35
102
  },
36
103
  "devDependencies": {
37
- "@types/node": "^22.0.0",
38
104
  "@types/js-yaml": "^4.0.9",
39
105
  "@types/minimist": "^1.2.5",
106
+ "@types/node": "^22.0.0",
40
107
  "@types/uuid": "^10.0.0",
41
108
  "typescript": "^5.7.0"
42
109
  },
@@ -1,17 +0,0 @@
1
- {
2
- "permissions": {
3
- "allow": [
4
- "mcp__claude_ai_Notion__notion-create-pages",
5
- "Bash(git add *)",
6
- "Bash(git config *)",
7
- "Bash(git commit *)",
8
- "Bash(gh issue *)",
9
- "Bash(git rebase *)",
10
- "Bash(git push *)"
11
- ],
12
- "additionalDirectories": [
13
- "/src/coaiapy",
14
- "/workspace/repos/jgwill/miadi-orchestration-kit"
15
- ]
16
- }
17
- }
@@ -1,26 +0,0 @@
1
- {
2
- "name": "coaiajs-marketplace",
3
- "owner": {
4
- "name": "Guillaume Isabelle",
5
- "email": "jgi@jgwill.com",
6
- "url": "https://github.com/jgwill"
7
- },
8
- "metadata": {
9
- "description": "CoAIA Claude Code plugins",
10
- "version": "0.3.0"
11
- },
12
- "plugins": [
13
- {
14
- "name": "coaiajs-langfuse",
15
- "source": "./coaiajs-langfuse-claude-plugin",
16
- "description": "CoAIA unified MCP — 64+ tools (structural tension charts, narrative knowledge graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
17
- "version": "0.3.0",
18
- "author": {
19
- "name": "Guillaume Isabelle",
20
- "url": "https://github.com/jgwill"
21
- },
22
- "license": "MIT",
23
- "keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
24
- }
25
- ]
26
- }
@@ -1 +0,0 @@
1
- These article were written by AI
@@ -1 +0,0 @@
1
- These article were written by AI