coaiajs 0.5.0 → 0.5.2

package/docs/LINEAGE-COAIA-NARRATIVE.md

@@ -0,0 +1,150 @@
+# Lineage: coaia-narrative → coaiajs
+
+## What the relationship is
+
+`coaiajs` is the package we maintain. `avadisabelle/coaia-narrative` is where several of
+these ideas were first built and several of these bugs were first paid for.
+
+That makes this a **one-way port, not a mirror**. We read that repository for corrections
+worth carrying, we decide what shape they take here, and we own the result. Nothing in
+this package is expected to stay byte-identical to anything over there, and a future
+instance should not treat a difference as drift to be undone.
+
+The direction never reverses. We do not push changes back, and we do not wait on that
+repository before fixing something here.
+
+## Ported through
+
+| | |
+|---|---|
+| Upstream repo | `avadisabelle/coaia-narrative` (`git@github.com:avadisabelle/coaia-narrative.git`) |
+| Original snapshot taken at | `12c60f8` (2026-03-08) — landed here as `d6a544e`, 2026-03-11 |
+| **Ported through** | **`68f6e2f`** — merge of PR #55, upstream v0.16.2, 2026-08-11 |
+| Landed here as | `03658fa` (narrative parity) and the commit adding this file |
+| Tracking issue | jgwill/coaiajs#13 |
+
+**Update the "Ported through" row in the same commit that lands the next port.** It is the
+only record of where the last one stopped, and a port that does not update it costs the
+next instance the whole diff again.
+
+## How to find the next port
+
+```bash
+UPSTREAM=/path/to/coaia-narrative        # or: git clone git@github.com:avadisabelle/coaia-narrative.git
+PORTED_THROUGH=68f6e2f
+
+cd "$UPSTREAM" && git fetch --all
+
+# What changed in code since we last looked
+git diff --stat "$PORTED_THROUGH..origin/main" -- '*.ts'
+
+# Release-shaped commits carry their reason in the subject line — read these first,
+# they are usually one measured failure each
+git log --oneline "$PORTED_THROUGH..origin/main"
+
+# The full text of one change, with its comments, which is where the reasoning lives
+git show <sha>
+```
+
+Upstream writes its commit subjects as the failure that was found, not as the change that
+was made ("a --memory-path carrying an unexpanded shell variable is refused"). Read the
+subject lines before the diff — they tell you which changes carry a real finding and which
+are packaging.
+
+## How to port
+
+The two trees are not diff-compatible. When the March snapshot was taken it was
+reformatted (single quotes, trailing commas, prettier widths), types were moved to
+`src/types.ts`, and `LLM_GUIDANCE` was inlined. `git apply` will not work and should not
+be attempted. Port **semantically**: read the upstream change, understand the finding
+behind it, then write it here in this codebase's shape.
+
+Rules that have held so far:
+
+1. **Carry the reasoning, not just the code.** Upstream comments name the date, the
+   measurement, and the cost of the bug. Those comments are the most valuable part of the
+   change — a future reader who does not know why a guard exists will delete it. Rewrite
+   them for this package's context rather than dropping them.
+2. **Adapt anything that names the other package.** Binary names, MCP server names,
+   environment variables, and example issue references all differ. A copy that still says
+   `cnarrative` or `COAIA_TOOLS` is wrong here even if it compiles.
+3. **Put the change where this codebase already puts that kind of thing.** Shared types go
+   in `src/types.ts`, not a per-module types file. The memory-path guard belongs in the
+   `KnowledgeGraphManager` constructor here, because that covers the CLI, the MCP server,
+   and library consumers at once — upstream put it in its single entry point because that
+   is all it has.
+4. **Write a test per finding.** `tests/narrative-parity.test.js` is organised as one
+   `describe` per finding, named for the behaviour it holds. A ported correction with no
+   test is a correction that will be un-ported by the next refactor.
+5. **Update the docs in the same commit.** `test/docs.test.mjs` fails the build when
+   `README.md` / `llms.txt` / `llms-full.txt` disagree with the served tool surface, so
+   this is enforced, not optional.
+
+## What has been adapted rather than copied
+
+### The skill (`src/skill.ts`, `skills/coaiajs/`)
+
+Upstream ships `cnarrative skill show|install`. We ship `coaia skill show|install|check`.
+Four deliberate differences:
+
+| | upstream | here | why |
+|---|---|---|---|
+| Content location | ~250 lines of markdown as a TypeScript string array | real `.md` files under `skills/coaiajs/`, shipped via `files` | a doc change should read as a doc diff, and markdown tooling should be able to see it |
+| Tool map | hand-written table | generated from `ALL_TOOL_DEFINITIONS` at render time | a hand-written map advertises tools the server does not serve the moment one is added |
+| Subject | `coaia-narrative`, `cnarrative`, `COAIA_TOOLS` | `coaiajs`, `coaia`, `coaiajs-mcp`, `COAIAJS_FEATURES` | it has to describe the surface it actually installs next to |
+| Staleness | not detectable | `coaia skill check`, plus `packageVersion` in the installed frontmatter | a skill installed by an older version describes an older surface and nothing else says so |
+
+The reference set is also larger, because this package has more surface: `wampum-belts.md`,
+`reading-the-store.md`, and `beyond-narrative.md` (PDE, planning, Langfuse, pipeline) have
+no upstream counterpart.
+
+**If upstream changes its skill content, do not copy the change in.** Read what it learned
+and decide whether it applies to our surface. These are two skills describing two packages.
+
+### The read contract subpath
+
+Upstream publishes `coaia-narrative/contract` because its package root **is** the MCP
+server bootstrap — importing it starts a stdio server, so a renderer must have a separate
+door. Our root is a plain library and has no such hazard. We publish
+`coaiajs/narrative/contract` anyway, because the other reason holds: a renderer should be
+able to pull the store's shape without pulling the whole package.
+
+## Deliberately not ported
+
+| Upstream | Why not |
+|---|---|
+| `index.ts` / `cli.ts` entry points | We have our own, with a different command surface and argument style |
+| `generated-llm-guidance.ts` | Inlined here as `LLM_GUIDANCE_FULL` / `_QUICK` / `_SAVE_DIRECTIVE` in `src/narrative/tool-handlers.ts` |
+| `src/help.ts`, `src/tool-groups.ts` | Commander provides help; the groups live in `src/narrative/tool-definitions.ts` |
+| `handlers/` (push, issues, ceremony, story-engine) | Webhook event handlers for that repo's deployment, not library capability |
+| `types.ts`'s `Direction = 'EAST' \| 'SOUTH' \| ...` | Unused upstream, and the name is already taken here by the PDE lowercase direction type |
+| `scripts/check-schema-parity.cjs` | Bound to that repo's `schema/` fixtures |
+
+Revisit any of these if the reason stops being true. Record the decision here when you do.
+
+## Where this package is deliberately ahead or different
+
+Do not "correct" these back toward upstream:
+
+- **`setDueDate` goes through `updateChartDueDate`.** It used to re-serialise the store by
+  hand with `writeFileSync`, which ignored `--memory-path` and dropped unmodelled fields.
+- **The memory-path guard is in the constructor**, so it covers library consumers, not only
+  a CLI entry point.
+- **`mcp/server.ts` catches that guard** and exits 1 with a one-line refusal rather than an
+  unhandled throw.
+- **`src/version.ts` exports `getPackageRoot()`**, which is how anything shipped beside
+  `dist/` (the skill, the Custom GPT specs) is located. Do not reach for `process.cwd()`.
+- **Tool counts in the docs are enforced by `test/docs.test.mjs`.** Upstream has no
+  equivalent; do not relax ours to match.
+
+## Checklist for the next port
+
+- [ ] `git log --oneline <PORTED_THROUGH>..origin/main` in the upstream checkout; read the subjects
+- [ ] `git diff --stat <PORTED_THROUGH>..origin/main -- '*.ts'`
+- [ ] For each change: is it a finding, packaging, or entry-point specific?
+- [ ] Port the findings semantically, carrying their reasoning as comments
+- [ ] One `describe` block per finding in `tests/narrative-parity.test.js`
+- [ ] `npm run build && npm test` — the docs suite will catch a stale tool count
+- [ ] `coaia skill check` after a local install, if the tool surface changed
+- [ ] Update **Ported through** above, and the "not ported" table if a decision changed
+- [ ] Bump the version, publish, and note the upstream range in the commit body

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.2",
   "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,165 @@
+---
+name: coaiajs
+description: 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. Use when working with desired outcomes and current reality, telescoping action steps, creative orientation, chart memory, or the coaia CLI and coaiajs-mcp MCP server.
+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 MCP server serves {{TOOL_COUNT}} tools at the default `STANDARD` level, of which
+{{NARRATIVE_TOOL_COUNT}} are the chart and knowledge-graph surface. The rest are Redis and
+Langfuse, prompt decomposition, and planning — all mapped below.
+
+Its core data model is the structural tension chart — desired outcome, current reality,
+telescoping action steps — backed by a JSONL knowledge graph. Everything else either feeds
+that model or observes it.
+
+## 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
+
+The CLI is for quick inspection, exports, local chart context, and everything that is
+easier to type than to call.
+
+```bash
+coaia narrative list -M ./memory.jsonl
+coaia narrative view <chartId> -M ./memory.jsonl
+coaia narrative export <chartId> --output chart.md -M ./memory.jsonl
+coaia narrative link-issue <chartId> owner/repo#123 -M ./memory.jsonl
+coaia fuse traces list
+coaia tash mykey "value" && coaia fetch mykey
+```
+
+{{CLI_MAP}}
+
+## 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
+
+Generated from the server's own tool definitions, so it cannot list a tool that is not
+served or omit one that is.
+
+{{TOOL_MAP}}
+
+Two names appear in both the narrative and PDE groups with different meaning.
+`add_action_step`, `update_action_progress`, `mark_action_complete`, and
+`update_current_reality` target the narrative chart; their `pde_`-prefixed twins target
+the PDE session. Calling the wrong one writes to the wrong store and reports success.
+
+## 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,71 @@
+# Beyond Narrative
+
+`coaiajs` consolidates four CoAIA sub-projects. The chart engine is the centre, but three
+other surfaces feed it and one observes it.
+
+The tools themselves are in SKILL.md's generated Tool Map. This file is what the map cannot
+tell you: when to reach for each surface, and where they overlap dangerously.
+
+## 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.
+
+Four of its tools carry a `pde_` prefix — `pde_add_action_step`,
+`pde_update_action_progress`, `pde_mark_action_complete`, `pde_update_current_reality` —
+because their unprefixed names belong to the narrative group. `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.
+
+Choose the sync direction deliberately: `sync_plan_to_chart` treats the plan as
+authoritative, `sync_chart_to_plan` treats the chart as authoritative. 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.