coaiajs 0.5.0 → 0.5.1

package/llms-full.txt

@@ -110,9 +110,10 @@ EnvironmentManager, createEnvironment, findEnvironment
 
 ```
 getPackageVersion
+getPackageRoot
 ```
 
-Returns the resolved version of the installed package, read from `package.json` at runtime.
+`getPackageVersion` returns the resolved version of the installed package, read from `package.json` at runtime. `getPackageRoot` returns the directory holding that `package.json` — the way anything shipped beside `dist/` (the packaged skill under `skills/`, the Custom GPT specs) is located. Do not use `process.cwd()` for that; it is the caller's directory and says nothing about where the package was installed.
 
 ### `coaiajs/narrative`
 
@@ -174,6 +175,26 @@ const store = parseStore(await readFile('./memory.jsonl', 'utf8'));
 const work = getWork(store, 'chart_1757200000000');
 ```
 
+### `coaiajs/skill`
+
+The agent skill this package ships, describing its own surface.
+
+```
+SKILL_NAME, SKILL_FILES, getPackagedSkillDir,
+renderSkill, renderSkillFile, renderToolMap,
+showSkill, installSkill, checkSkill, formatSkillCheck,
+getSkillInstallDir, getClaudeSkillLinkPath
+```
+
+```bash
+coaia skill show                 # print the packaged SKILL.md, rendered
+coaia skill install --yes        # ./.agents/skills/coaiajs + the .claude/skills symlink
+coaia skill install --global     # ~/.agents/skills/coaiajs
+coaia skill check                # current / stale / missing; exits non-zero unless current
+```
+
+The content lives as real markdown under `skills/coaiajs/` rather than as strings in the TypeScript, so a documentation change reads as a documentation diff. The `{{TOOL_MAP}}` placeholder inside `SKILL.md` is rendered from `ALL_TOOL_DEFINITIONS` — the same array the MCP server registers — so an installed skill cannot advertise a tool the server does not serve. The version it was rendered from is recorded in the installed frontmatter as `packageVersion`, which is what `checkSkill` reads.
+
 ### `coaiajs/pde`
 
 ```
@@ -367,6 +388,7 @@ Global options: `--env <path>` · `-M, --memory-path <path>` · `--json` · `--n
 | `p <tag> [text]` | | Process text with a custom tag |
 | `init` | | Create a sample `coaia.json` |
 | `fuse` | | Langfuse operations |
+| `skill` | | The packaged agent skill: show, install, check |
 | `narrative` | `n` | Structural tension chart operations |
 | `pde` | | Prompt Decomposition Engine |
 | `plan` | | Structural tension plan operations |
@@ -377,7 +399,8 @@ Global options: `--env <path>` · `-M, --memory-path <path>` · `--json` · `--n
 Subcommands:
 
 - **`fuse`** — `traces`, `prompts`, `datasets`, `sessions`, `scores` (`sc`), `score-configs` (`scc`), `comments`, `media`, `dataset-items`, `projects`
-- **`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`)
+- **`skill`** — `show`, `install` (`--global`, `--yes`, `--force`), `check` (`--global`)
+- **`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`, `--redistribute`), `link-issue`
 - **`pde`** — `import <pdeId>`, `list`, `sessions`, `show <sessionId>`
 - **`plan`** — `parse <planPath>`, `convert <planPath>`, `sync-to-chart <planPath> <chartsPath>`, `sync-to-plan <chartsPath> <planPath>`
 - **`pipeline`** — `list`, `show <name>`, `create <name>`, `init <name>`
@@ -428,3 +451,7 @@ npm run dev        # tsc --watch
 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.
 
 Per-module RISE specifications live in `rispecs/`, one file per module.
+
+### Carrying corrections forward from coaia-narrative
+
+`src/narrative/` began as a snapshot of `avadisabelle/coaia-narrative` and still takes corrections from it — one way. `docs/LINEAGE-COAIA-NARRATIVE.md` records where the last port stopped (upstream `68f6e2f`, v0.16.2), how to compute the next diff, what was adapted rather than copied and why, and what is deliberately not ported. Read it before porting anything from that repository. The two trees are not diff-compatible; port semantically and carry the reasoning, not just the code.

package/llms.txt

@@ -17,6 +17,7 @@ Key facts an agent usually needs first:
 - [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
 
@@ -32,6 +33,7 @@ Key facts an agent usually needs first:
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coaiajs",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "CoAIA unified TypeScript monorepo — CLI, MCP server, and library consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy patterns into one package.",
   "main": "./dist/src/index.js",
@@ -54,6 +54,10 @@
       "types": "./dist/src/narrative/contract.d.ts",
       "import": "./dist/src/narrative/contract.js"
     },
+    "./skill": {
+      "types": "./dist/src/skill.d.ts",
+      "import": "./dist/src/skill.js"
+    },
     "./pde": {
       "types": "./dist/src/pde/index.d.ts",
       "import": "./dist/src/pde/index.js"
@@ -70,6 +74,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "docs",
     "agents/custom_gpt",
     "rispecs",
     "README.md",

package/skills/coaiajs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: coaiajs
+description: Use coaiajs to create and manage Structural Tension Charts, narrative beats, Wampum Belts, MMOT evaluations, PDE decompositions, action plans, and Langfuse-traced pipelines over a JSONL knowledge graph.
+license: MIT
+compatibility: Requires the coaiajs package. CLI: coaia. MCP server: coaiajs-mcp.
+metadata:
+  author: Guillaume D. Isabelle
+  package: coaiajs
+  packageVersion: "{{VERSION}}"
+allowed-tools: Bash(coaia:*), Bash(coaiajs-mcp:*)
+---
+
+# coaiajs
+
+`coaiajs` is the structural tension surface of the COAIA family, consolidated into one
+installable unit: a library, a CLI (`coaia`), and an MCP server (`coaiajs-mcp`). Use it when
+an assistant should help create outcomes, hold current reality clearly, track strategic
+secondary choices, archive significant learning, and keep that work traced.
+
+The chart and knowledge-graph surface below is {{NARRATIVE_TOOL_COUNT}} tools. The same
+server also serves Langfuse, PDE, and planning tools — see `references/beyond-narrative.md`.
+
+Its core data model is the structural tension chart — desired outcome, current reality,
+telescoping action steps — backed by a JSONL knowledge graph.
+
+## Status
+
+!`coaia --version 2>/dev/null || echo "Not installed: npm install -g coaiajs"`
+
+## First Principles
+
+- Work from creative orientation: ask what result the user wants to create, not what
+  problem should disappear.
+- Hold desired outcome and current reality at the same time. Do not collapse the tension
+  with "ready to begin" defaults.
+- Treat action steps as strategic secondary choices. They are not a to-do list.
+- Every action step is also a telescoped chart with its own desired outcome and current
+  reality.
+- Use narrative beats for significant learning moments, not routine task tracking.
+- Use a Wampum Belt when the sequence is not linear and position carries meaning.
+
+## MCP Setup
+
+Use the MCP server when the assistant needs write access to chart memory:
+
+```json
+{
+  "mcpServers": {
+    "coaiajs": {
+      "command": "npx",
+      "args": ["-y", "coaiajs", "coaiajs-mcp", "--memory-path", "/absolute/path/to/memory.jsonl"],
+      "env": {
+        "COAIAJS_FEATURES": "STANDARD"
+      }
+    }
+  }
+}
+```
+
+`--memory-path` must be a real, expanded path. A path still carrying `${VAR}` is refused
+at startup rather than opened — see `references/install-and-environment.md` for why that
+refusal is the kind answer.
+
+When a new session connects, call `init_llm_guidance` first: `format: "full"` for first
+use, `format: "quick"` for a refresh.
+
+## CLI Inspection Flow
+
+The CLI is for quick inspection, exports, and local chart context:
+
+```bash
+coaia narrative list -M ./memory.jsonl
+coaia narrative view <chartId> -M ./memory.jsonl
+coaia narrative stats -M ./memory.jsonl
+coaia narrative export <chartId> --output chart.md -M ./memory.jsonl
+coaia narrative link-issue <chartId> owner/repo#123 -M ./memory.jsonl
+```
+
+## Core Workflow
+
+1. Read chart state before writing anything:
+
+```text
+list_active_charts
+```
+
+2. Create a chart only when there is a new primary desired outcome:
+
+```json
+{
+  "tool": "create_structural_tension_chart",
+  "arguments": {
+    "desiredOutcome": "A release process that runs the same way every time",
+    "currentReality": "Build and publish steps are manual and easy to miss",
+    "dueDate": "2027-06-01T00:00:00.000Z",
+    "actionSteps": ["Document release checks", "Verify npm package contents"],
+    "githubIssue": "jgwill/coaiajs#13"
+  }
+}
+```
+
+`githubIssue` is optional and takes the FULL `owner/repo#number` path. A bare `#number`
+is refused: charts travel between repositories, and a bare number cites the wrong project
+as soon as the chart is read somewhere else.
+
+3. Add or expand action steps with `manage_action_step`:
+
+```json
+{
+  "tool": "manage_action_step",
+  "arguments": {
+    "parentReference": "chart_123",
+    "actionDescription": "Verify npm package contents",
+    "currentReality": "No package dry-run has been inspected for this release"
+  }
+}
+```
+
+4. Track advancement without pretending completion:
+
+```text
+update_action_progress
+update_current_reality
+mark_action_complete
+```
+
+5. Move a date with `update_chart_due_date` rather than editing the JSONL by hand. Several
+   MCP instances can point at one store with no lock, which is how a hand-edit becomes a
+   lost write.
+
+6. Use `perform_mmot_evaluation` when output and expected performance diverge, or when a
+   chart needs a truth-based review.
+
+7. Create a narrative beat when the work produced a significant learning moment across
+   engineer-world, ceremony-world, and story-engine-world.
+
+## Tool Map
+
+{{TOOL_MAP}}
+
+## References
+
+- `references/creative-orientation.md` — the creation-vs-problem-solving distinction
+- `references/structural-tension-charting.md` — chart and action-step rules
+- `references/delayed-resolution.md` — current reality discipline
+- `references/narrative-beats.md` — story archive usage
+- `references/wampum-belts.md` — non-linear mnemonic sequencing
+- `references/reading-the-store.md` — reading a chart store without re-deriving its shape
+- `references/beyond-narrative.md` — PDE, planning, Langfuse, pipeline
+- `references/mcp-tools.md` — feature levels and environment variables
+- `references/install-and-environment.md` — install, run, and the refusals worth knowing

package/skills/coaiajs/references/beyond-narrative.md

@@ -0,0 +1,82 @@
+# Beyond Narrative
+
+`coaiajs` consolidates four CoAIA sub-projects. The chart engine is the centre, but three
+other surfaces feed it and one observes it.
+
+## PDE — Prompt Decomposition Engine
+
+Decomposes a complex prompt into an intent map — primary intent, secondary intents,
+context requirements, expected outputs, and the four directions — then turns that map into
+a chart.
+
+| Tool | Use |
+|---|---|
+| `import_pde_decomposition` | Bring a decomposition JSON into the session store |
+| `create_stc_from_pde` | Turn a decomposition into a structural tension chart |
+| `list_pde_decompositions` | See what has been imported |
+| `get_session`, `list_sessions`, `complete_session` | Session lifecycle |
+| `pde_update_action_progress`, `pde_mark_action_complete`, `pde_add_action_step`, `pde_update_current_reality` | The chart verbs, targeting the PDE session |
+
+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. Getting this wrong writes to the wrong store and reports success.
+
+```bash
+coaia pde --help
+```
+
+## Planning
+
+Parses a structured plan file into structural tension form and keeps it in sync with a
+chart store, in both directions.
+
+| Tool | Use |
+|---|---|
+| `parse_plan_structural` | Read a plan file into chart shape |
+| `plan_to_stc` | Create charts from a plan |
+| `sync_plan_to_chart` | Plan is authoritative |
+| `sync_chart_to_plan` | Chart is authoritative |
+| `create_plan_trace` | Emit a Langfuse trace for the plan |
+| `pde_to_plan` | Turn a decomposition into a plan |
+
+Choose the sync direction deliberately. Both write.
+
+```bash
+coaia plan --help
+```
+
+## Langfuse
+
+Traces, observations, scores, prompts, datasets, comments, and media, over the Langfuse
+REST API. Use it to make the chart work observable rather than to store it — the JSONL
+store remains the record.
+
+```bash
+coaia fuse traces list
+coaia fuse trace view <traceId>
+coaia fuse prompts get <name>
+```
+
+The `coaia_fuse_*` MCP tools mirror these. Media tools are `FULL`-level only.
+
+## Pipeline
+
+A Jinja2-style template engine for prompt pipelines, exposed as the `coaia://templates/`
+MCP resources and the `coaia pipeline` commands.
+
+```bash
+coaia pipeline list
+coaia pipeline run <name>
+```
+
+## Redis shorthand
+
+`tash` / `fetch` are the COAIA SET/GET shorthand, used for stashing plan perspectives and
+intermediate content:
+
+```bash
+coaia tash mykey "value"
+coaia fetch mykey
+```
+
+Prefer the CLI over the MCP tool for these — it is the more reliable path.

package/skills/coaiajs/references/creative-orientation.md

@@ -0,0 +1,42 @@
+# Creative Orientation
+
+Creative orientation focuses on bringing desired results into being. Reactive orientation
+focuses on removing unwanted conditions. `coaiajs` biases toward creation.
+
+Ask: "What do you want to create?" Then define current reality in relation to that
+desired outcome.
+
+Structural tension is not a gap to bridge. It is the active disequilibrium created by
+holding desired outcome and current reality clearly at the same time.
+
+Use this language:
+
+| Avoid | Prefer |
+|---|---|
+| bridge the gap | resolve the tension |
+| close the gap | advance toward the desired outcome |
+| tasks to fix the problem | strategic secondary choices |
+| ready to begin | factual current reality |
+
+A useful chart advances toward a created result. It does not merely remove a discomfort.
+
+## The guard, and what it does not do
+
+`create_structural_tension_chart` refuses a desired outcome containing `fix`, `solve`,
+`eliminate`, `prevent`, `stop`, `avoid`, `reduce`, or `remove`, and answers with the
+teaching above.
+
+It matches on **word boundaries**, not substrings. This matters: an earlier version used
+`.includes()` and so read the letters of those words inside longer ones. Two measured
+refusals, on outcomes already written in creative orientation:
+
+- "a fixed ladder of named rungs" — refused for `fix`
+- "carry one to completion or resolve it" — refused for `solve`
+
+Both authors rephrased around the error without asking why, which is the quiet cost: a
+guard that fires on innocent text teaches the caller to edit for the checker rather than
+for the reader. Sharper still, the second example is the phrasing the COAIA guidance
+itself prescribes.
+
+The word list is unchanged. An outcome that genuinely says "eliminate" or "reduce" should
+still be met with the teaching. Only the matching was corrected.

package/skills/coaiajs/references/delayed-resolution.md

@@ -0,0 +1,48 @@
+# Delayed Resolution
+
+Tolerate discrepancy and delayed resolution. Do not smooth over the contradiction between
+desired outcome and current reality.
+
+When information is missing, ask for current reality or name the missing reality
+explicitly. Do not invent readiness.
+
+`create_structural_tension_chart` refuses a current reality containing "ready to",
+"prepared to", "all set", "ready for", or "set to", and answers with the principle. That
+refusal exists because a readiness assumption prematurely resolves the tension the chart
+was created to hold.
+
+## MMOT — the Managerial Moment of Truth
+
+Run `perform_mmot_evaluation` when output and expected performance diverge. Four phases,
+in order:
+
+1. **Acknowledge** the difference between expected and delivered.
+2. **Analyze** how it came to pass.
+3. **Update** the chart and current reality.
+4. **Recommit** or redirect based on what is now true.
+
+Call with `phase` set to one of those, or omit it for `full`.
+
+## What `updateReality` governs
+
+`updateReality` controls **one** record: the append into current reality. The chart's own
+`metadata.mmotEvaluations[]` trail is a separate record and is written whenever an
+assessment was made.
+
+An earlier version gated both on that one flag, so a caller who only asked to leave
+current reality alone lost the evaluation entirely — while still being handed a full
+phase response that read like a success. The response line now names which records were
+actually written:
+
+- `✅ Evaluation stored: chart MMOT trail + current reality.`
+- `✅ Evaluation stored: chart MMOT trail (current reality left untouched, as requested).`
+
+Read that line. A success line that names the wrong record is the same failure class as a
+success line over zero bytes.
+
+## Elements of Performance
+
+Pass `elementsOfPerformance` when creating a chart to define what the MMOT will evaluate
+against. Each is `{ description, type }` where `type` is `DESIGN` (structural intent,
+architecture) or `EXECUTION` (delivery, implementation quality). Without them, MMOT still
+runs, but it has nothing concrete to compare the work to.

package/skills/coaiajs/references/install-and-environment.md

@@ -0,0 +1,85 @@
+# Install And Environment
+
+## Install
+
+```bash
+npm install -g coaiajs
+coaia --version
+```
+
+## The skill
+
+```bash
+coaia skill show                 # print the packaged SKILL.md
+coaia skill install              # write ./.agents/skills/coaiajs
+coaia skill install --global     # write ~/.agents/skills/coaiajs
+coaia skill install --yes        # also create the .claude/skills/coaiajs symlink
+coaia skill install --force      # replace an existing install
+coaia skill check                # is the installed skill current?
+```
+
+`coaia skill check` compares an installed skill against the packaged one and reports
+`current`, `stale`, or `missing`. Run it after upgrading `coaiajs`: a skill installed by an
+older version describes an older tool surface, and nothing else will tell you.
+
+The tool map inside `SKILL.md` is generated from the server's own tool definitions at
+install time, so an installed skill cannot advertise a tool this package does not serve.
+The version it was generated from is recorded in the frontmatter as `packageVersion`.
+
+## Run the MCP server
+
+```bash
+coaiajs-mcp --memory-path ./memory.jsonl
+COAIAJS_FEATURES=FULL coaiajs-mcp --memory-path ./memory.jsonl
+```
+
+## Inspect from the CLI
+
+```bash
+coaia narrative list -M ./memory.jsonl
+coaia narrative view <chartId> -M ./memory.jsonl
+coaia narrative stats -M ./memory.jsonl
+coaia narrative progress <chartId> -M ./memory.jsonl
+coaia narrative export <chartId> --output chart.md -M ./memory.jsonl
+coaia narrative set-date <chartId> 2027-06-01T00:00:00Z --redistribute -M ./memory.jsonl
+coaia narrative link-issue <chartId> owner/repo#123 -M ./memory.jsonl
+```
+
+## Refusals worth knowing about
+
+### A memory path carrying an unexpanded shell variable
+
+```
+Refusing to open memory store: the path contains an unexpanded shell variable.
+  got: ${MIADI_CHART_MEMORY_PATH}
+```
+
+A seat once booted with that variable unset, so its `.mcp.json` handed the process the
+placeholder verbatim. The server started happily and wrote live charts into a file
+literally named `${MIADI_CHART_MEMORY_PATH}`. Nothing failed — the charts were simply
+somewhere nobody would look, and another seat auditing the boot found them.
+
+The sibling failure is worse and is why this is fatal rather than a warning: had the
+variable been set to a path that does not exist, the server would have started **clean and
+empty**, and the seat would have reported its whole store lost. A store is the one input
+where "start anyway" is never the kind answer.
+
+`$` is legal in a filename, so a path containing `$` alone is fine. Only `${` is refused —
+a caller writing that is quoting a shell it expected to have run.
+
+### A bare GitHub issue number
+
+`githubIssue` and `link_chart_to_github_issue` require the full `owner/repo#number` path.
+A bare `#42` resolves against whichever repository the reader happens to be in, which is
+how an issue from one project ends up cited as another project's.
+
+### A malformed tool call
+
+See `mcp-tools.md`. Nothing is written and the offending fragment is quoted back.
+
+## What this package does not lock
+
+Writes are atomic — temp file, then rename — so a reader never sees a torn store. That
+removes torn **reads**; it does not provide compare-and-swap. Two processes that both
+load, then both write, still lose the earlier update, and both report success. If several
+MCP instances point at one store, keep their write windows apart.

package/skills/coaiajs/references/mcp-tools.md

@@ -0,0 +1,83 @@
+# MCP Tools And Environment
+
+The MCP server is `coaiajs-mcp`. It speaks stdio and serves tools, prompts, and resources.
+
+## Feature levels
+
+`COAIAJS_FEATURES` selects the tool set. Default is `STANDARD`.
+
+| Level | Serves |
+|---|---|
+| `MINIMAL` | Redis shorthand and the core Langfuse read/write tools |
+| `STANDARD` | Default — everything except the media tools |
+| `OBSERVABILITY` | Langfuse-focused |
+| `FULL` | Everything, including media upload/get |
+
+Pass `--features <LEVEL>` on the command line to override the environment.
+
+## Tool groups (library-side)
+
+`coaiajs/narrative` exports these name lists so a caller can gate its own surface:
+
+| Group | Contents |
+|---|---|
+| `CORE_TOOLS` | The minimal list / create / add / complete workflow |
+| `STC_TOOLS` | Chart creation, action steps, progress, reality, outcome, due date, GitHub link, MMOT |
+| `NARRATIVE_TOOLS` | Narrative beat creation, telescoping, listing |
+| `WAMPUM_TOOLS` | Belt creation, bead placement, belt reading |
+| `KG_TOOLS` | Lower-level knowledge graph entities and relations |
+
+Prefer STC tools for chart work. Use KG tools only when deliberately managing generic
+entities and relations — they bypass the chart-shaped validation.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `COAIAJS_FEATURES` | Feature level: `MINIMAL` / `STANDARD` / `OBSERVABILITY` / `FULL` |
+| `COAIAJS_MEMORY_PATH` | Default JSONL store path for CLI and MCP server |
+| `COAIA_CURRENT_CHART_ID` | Chart the CLI treats as current (`coaia narrative current`) |
+| `REDIS_URL` / `REDIS_HOST` etc. | Redis endpoint for `tash` / `fetch` |
+| `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST` | Langfuse credentials |
+| `OPENAI_API_KEY` | LLM and transcription calls |
+
+Config resolution order is: environment variables, then `.env`, then `coaia.json`.
+
+## Arguments this server will tell you about
+
+Two behaviours worth relying on:
+
+**Unknown arguments are named, not swallowed.** A tool call carrying a key the schema does
+not know still succeeds, but the result appends:
+
+```
+⚠️ Ignored unrecognised argument(s): dueDte. They were NOT applied — check the tool's inputSchema for the accepted names.
+```
+
+A dropped argument is otherwise invisible from the caller's side — the call succeeds, the
+record is written, and the ignored part looks exactly like an honoured one.
+
+**Every validation problem is reported at once.** Two missing required fields come back in
+one message rather than costing a round trip each.
+
+**`telescope_action_step` accepts `actionSteps`** as an alias for `initialActionSteps`,
+because its sibling `create_structural_tension_chart` names the same concept `actionSteps`
+and callers reach for that name.
+
+## Refusals
+
+A call whose argument tags did not parse arrives with its own raw text inside a value.
+That is refused at the write boundary, with the fragment quoted and nothing written:
+
+```
+Malformed call refused — nothing was written.
+
+`currentReality` carries unparsed call syntax, not prose:
+    </currentReality>
+That is a closing tag for the 'currentReality' argument.
+```
+
+The refusal exists because that text used to persist verbatim: a live store was found
+carrying seven observations ending in `</currentReality>` followed by a parameter block,
+rendered as prose by every consumer since. A read-side filter arrives too late — anything
+that reaches the JSONL is already in every reader's render.

package/skills/coaiajs/references/narrative-beats.md

@@ -0,0 +1,44 @@
+# Narrative Beats
+
+Narrative beats document significant learning moments. They are not replacements for
+charts or action steps, and they are not routine task tracking.
+
+Create a beat when a moment matters across multiple perspectives:
+
+- **engineer-world** — technical structure and consequences
+- **ceremony-world** — relational protocol and accountability
+- **story-engine-world** — narrative progression and meaning
+
+A useful beat carries title, act, dramatic type, universes, description, prose, and
+lessons. Use beats after a real transition, discovery, crisis, MMOT, or integration
+moment.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `create_narrative_beat` | Archive a significant multi-universe learning moment |
+| `telescope_narrative_beat` | Break a beat into sub-beats with their own current reality |
+| `list_narrative_beats` | Review the archive, optionally filtered by parent chart |
+
+## Beat-level session context
+
+`metadata.sessionContext` records the embodied condition of the session a beat came from:
+`mode` (voice / terminal / mixed), `setting` (desk / walking / land-based / transit),
+`landBasedLearning`, `environmentNotes`, `captureQuality`, and whether a public summary is
+allowed. Use it when the conditions of the work are part of what the beat means.
+
+`metadata.sessionLineage` records conversation branching — parent chart, source beat,
+original and branch session ids, branch purpose, and handoff state — so a branch map can
+be reconstructed later.
+
+## The legacy on-disk dialect
+
+Some live stores hold beats written with a top-level `type: "narrative_beat"` rather than
+`type: "entity"` with `entityType: "narrative_beat"`. Both are read, both round-trip as
+themselves, and a writer never flattens one into the other.
+
+This matters to anyone reading the store directly: a reader that does not know the legacy
+dialect renders **fewer beats than exist** and may report the difference as corruption.
+Use `coaiajs/narrative/contract` rather than classifying records by hand — see
+`reading-the-store.md`.