# coaiajs

> 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`, 67 tools). Its core data model is the *structural tension chart* — desired outcome, current reality, and telescoping action steps — backed by a JSONL knowledge graph.

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.

Key facts an agent usually needs first:

- 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.
- Clients (Redis, OpenAI, Polly, Octokit) are lazy: importing a module opens no connection and reads no file. Call `disconnect()` when finished.
- Config precedence: environment variables > `.env` files > `coaia.json` > defaults.
- The MCP server serves 67 tools, 3 prompts, and 1 listable resource over stdio. `COAIAJS_FEATURES` (`MINIMAL`/`STANDARD`/`OBSERVABILITY`/`FULL`) controls the tool set; default is `STANDARD`.

## Documentation

- [README](./README.md): install, the three consumption modes, configuration, architecture
- [llms-full.txt](./llms-full.txt): complete API surface — every export, every MCP tool, every CLI command, in one file
- [CLAUDE.md](./CLAUDE.md): repository conventions for agents working *on* this codebase
- [KINSHIP.md](./KINSHIP.md): lineage and type provenance from the four origin projects
- [docs/LINEAGE-COAIA-NARRATIVE.md](./docs/LINEAGE-COAIA-NARRATIVE.md): how corrections are carried forward from `avadisabelle/coaia-narrative` — where the last port stopped, how to find the next one, and what is deliberately not copied

## Entry points

- `coaiajs`: everything, plus `langfuse`/`narrative`/`pde`/`planning`/`pipeline` namespaces and shared types
- `coaiajs/config`: configuration resolution — `readConfig`, `getConfig`, `resetConfig`
- `coaiajs/redis`: `tash`, `fetch`, `del`, `keys`, `exists`, `disconnect`
- `coaiajs/llm`: `llm`, `transcribeAudio`, `generateImage`, `abstractProcess`
- `coaiajs/audio`: `synthesize` (AWS Polly)
- `coaiajs/github`: `listIssues`, `getIssue`, `getIssueComments`
- `coaiajs/environment`: `EnvironmentManager`, `createEnvironment`, `findEnvironment`
- `coaiajs/version`: `getPackageVersion`
- `coaiajs/langfuse`: Langfuse v4-compatible OpenTelemetry tracing, Observations API v2, Scores API v3, prompts, datasets, comments, media, projects
- `coaiajs/media-upload-proxy`: deployable `openaiFileIdRefs` to Langfuse media upload bridge (`coaiajs-media-proxy` binary)
- `coaiajs/narrative`: `KnowledgeGraphManager`, structural tension charts, markdown export, Wampum Belt sequencing, GitHub issue linkage, loss-free JSONL round-tripping
- `coaiajs/narrative/contract`: the store read contract for renderers — zero I/O, tolerant of a bad line
- `coaiajs/skill`: the packaged agent skill — render, install, and check it (`coaia skill show|install|check`)
- `coaiajs/pde`: Prompt Decomposition Engine — sessions, STC mapping
- `coaiajs/planning`: `parsePlan`, `planToSTC`, `syncToChart`, `syncToPlan`
- `coaiajs/pipeline`: pipeline template engine

## Specifications

- [rispecs/](./rispecs/): RISE specification files, one per module (config, redis, langfuse, narrative, PDE, planning, pipeline, CLI, MCP, audio)

## Optional

- [Claude Code plugin](./coaiajs-langfuse-claude-plugin/): registers the MCP server in Claude Code via `npx`