coaiajs 0.5.0 → 0.5.2

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`.

package/skills/coaiajs/references/reading-the-store.md

@@ -0,0 +1,66 @@
+# Reading the Store
+
+`coaiajs` owns the writes. Anything that renders a chart store — a dashboard, a report, a
+Twine promotion, another agent — needs the store's shape, and re-deriving that shape by
+hand is where readers quietly go wrong.
+
+It is not a style problem. When a hand-rolled reader drifts from the writer, it does not
+break: it renders **less**. A chart holding real work looks identical to an empty one.
+
+## Use the contract
+
+```typescript
+import { parseStore, getWork, getChartEntity } from 'coaiajs/narrative/contract';
+import { readFile } from 'node:fs/promises';
+
+const store = parseStore(await readFile('./memory.jsonl', 'utf8'));
+const chart = getChartEntity(store, 'chart_1757200000000');
+const work  = getWork(store, 'chart_1757200000000');
+```
+
+The contract keeps three rules:
+
+1. **Zero I/O.** No `fs`, no `process`, no network. The caller owns reading; this owns
+   shape.
+2. **Never imports the server.** The package root is safe to import, but the contract
+   lives behind its own subpath so a renderer pulls nothing it does not need.
+3. **Tolerant by construction, honest about what it skipped.** One unparseable line is
+   skipped and counted in `skipped`, where `parseJsonlMemory` — correctly, for a writer —
+   throws.
+
+Classification is **not** defined in the contract. `jsonl-records.ts` holds the single
+definition, and both the writer and the contract import it. The first draft of the
+contract re-implemented classification by hand and a review measured it returning 73
+entities where the writer returned 76: it dropped the legacy `type:"narrative_beat"`
+dialect and reported the losses as corruption. Duplication relocated rather than removed.
+
+## What it gives you
+
+| Export | Use |
+|---|---|
+| `parseStore(raw)` | `{ entities: Map, relations: [], skipped: number }` |
+| `ENTITY_TYPES` | Every entity kind the writer writes |
+| `MMOT_PHASES`, `CREATING_PHASES` | The vocabularies, including `full` |
+| `chartEntityName`, `desiredOutcomeName`, `currentRealityName` | The naming scheme, once |
+| `getChartEntity`, `getDesiredOutcome`, `getCurrentReality` | Chart parts by id |
+| `getFlatActionSteps`, `getChildCharts`, `getWork` | The two shapes work takes, counted once |
+| `getMmotBeats`, `getMmotEvaluations` | The MMOT trail |
+| `storeRevision`, `revisionOf` | Cheap change detection between reads |
+
+## What `skipped` cannot tell you
+
+Writes are temp-file-plus-rename, so a reader should never see a torn file and
+`skipped > 0` genuinely suggests a foreign or damaged line.
+
+But a store truncated by something *other* than this package can still be a syntactically
+perfect prefix: every whole line parses, and the result is simply a smaller store with
+`skipped === 0`. No reader can detect that from content alone. If it matters, compare
+entity counts across reads.
+
+## Writing from outside
+
+If you must write, go through `KnowledgeGraphManager` or
+`readJsonlMemoryFile` / `writeJsonlMemoryFile`. They preserve fields this package does not
+model — another consumer's metadata survives — and they write atomically. A bare
+`writeFile` over the store truncates first, and a reader landing in that window gets a
+valid partial store.

package/skills/coaiajs/references/structural-tension-charting.md

@@ -0,0 +1,71 @@
+# Structural Tension Charting
+
+A chart has three core parts:
+
+1. **Desired Outcome** — what the user wants to create.
+2. **Current Reality** — the honest present state in relation to that outcome.
+3. **Action Steps** — strategic secondary choices that support the primary choice.
+
+Action steps are not independent checklist items. They must make sense together as an
+overview strategy. Test them with: "If these steps were taken, would the desired outcome
+likely be created?"
+
+Each action step is a telescoped chart. Its title becomes the desired outcome of the child
+chart, and it needs its own current reality. Never use "ready to begin" as that reality.
+
+Good current reality examples:
+
+- "No Django experience."
+- "Package builds locally, publish dry-run not inspected."
+- "Budget: $5000."
+- "Completed models section, struggling with views."
+
+Poor current reality examples:
+
+- "Ready to begin."
+- "Need to retrieve the notes."
+- "Excited to start."
+- "Prepared to tackle the action step."
+
+## How a chart is laid out in the store
+
+For a chart with id `chart_1757200000000`:
+
+| Entity | `entityType` |
+|---|---|
+| `chart_1757200000000_chart` | `structural_tension_chart` |
+| `chart_1757200000000_desired_outcome` | `desired_outcome` |
+| `chart_1757200000000_current_reality` | `current_reality` |
+| `chart_1757200000000_action_1` … `_action_N` | `action_step` |
+
+A telescoped child chart is a full chart of its own, carrying `metadata.parentChart` and,
+when it grew out of a specific step, `metadata.parentActionStep`.
+
+## The two shapes work takes
+
+This is the single most common source of a wrong reading. A chart holds its work in **two**
+shapes:
+
+1. `action_step` entities that live on the chart itself.
+2. Telescoped child charts, which is what `add_action_step` produces.
+
+Counting or rendering only one of them under-reports. A chart built entirely with
+`add_action_step` used to report `0/0` progress while holding real work, and a chart
+holding eight of its own steps used to render as "(No action steps yet)".
+
+A child telescoped out of one of the chart's own steps is that same result seen closer up.
+It counts **once**, through the step — not twice.
+
+`getChartProgress`, `listActiveCharts`, `updateChartDueDate`, and
+`coaiajs/narrative/contract`'s `getWork()` all apply that rule. Prefer them over walking
+the graph by hand.
+
+## Moving a date
+
+Use `update_chart_due_date`. It moves the chart and its desired outcome together, records
+the move as an observation on the chart, and reports how many open steps still fall after
+the new date. Pass `redistributeActionSteps: true` to spread those open steps evenly
+between now and the new date.
+
+Do not hand-edit the JSONL to change a date. Several MCP instances can point at one store
+with no lock; a hand-edit races every one of them.

package/skills/coaiajs/references/wampum-belts.md

@@ -0,0 +1,72 @@
+# Wampum Belts
+
+A Wampum Belt is a non-linear mnemonic grid that runs in **parallel** with the linear
+narrative beats. Beats are a sequence; a belt is a surface where position itself carries
+meaning.
+
+Reach for a belt when the order of things is not a line: when a reading depends on where
+it sits relative to its neighbours, when several perspectives on one bead are all true,
+or when a commitment needs a witness rather than a timestamp.
+
+## Shape
+
+A belt has `rows` × `cols` positions. Each position holds at most one bead, written once.
+
+A bead carries:
+
+| Field | Meaning |
+|---|---|
+| `mnemonic` | Short anchor phrase |
+| `color` | `white`, `purple`, `black`, or `mixed` |
+| `position` | `{ row, col }`, zero-indexed, inside the grid |
+| `reading` | The canonical meaning |
+| `relationalReadings` | Optional per-perspective readings, keyed `left` / `center` / `right` / `row:N` / `col:N` |
+| `ceremonyLink` | Optional tie to a chart or a beat |
+| `observations` | Free notes |
+
+`read_wampum_belt` with a `position` resolves the reading for that position: it prefers
+`col:N`, then `row:N`, then the positional label (`left` / `center` / `right`), and falls
+back to the canonical `reading`.
+
+## Ceremony links
+
+`ceremonyLink.ceremonyType` is one of `commitment`, `accountability`, `witness`, or
+`renewal`. With `chartId` it writes a `wampum_holds_accountable` edge to that chart; with
+`beatName` it writes a `wampum_witnesses` edge to that beat.
+
+**The edge is subject to the bead, not the belt.** A relation's identity in the store is
+`(from, to, relationType)`. With the belt as subject, a second bead linking the same chart
+under a different `ceremonyType` collided on that triple: the existence check matched, the
+edge was skipped, and the bead kept a ceremony type the graph had no edge for. Silent
+discard, with the bead's own record disagreeing with the graph and nothing saying so.
+
+A bead id is `bead_<beltId>_<row>_<col>` and a position is written once, so
+`(bead, target, relationType)` is unique by construction and every ceremony link survives
+carrying its own type.
+
+## Tools
+
+```json
+{ "tool": "create_wampum_belt",
+  "arguments": { "title": "Release ceremony", "purpose": "Hold what each step promised", "rows": 2, "cols": 3 } }
+```
+
+```json
+{ "tool": "add_wampum_bead",
+  "arguments": {
+    "beltId": "belt_1757200000000",
+    "mnemonic": "witnessed",
+    "color": "purple",
+    "position": { "row": 0, "col": 1 },
+    "reading": "The publish was seen by someone other than its author",
+    "relationalReadings": { "center": "seen from the middle of the belt" },
+    "ceremonyLink": { "ceremonyType": "witness", "chartId": "chart_1757200000000" }
+  } }
+```
+
+```json
+{ "tool": "read_wampum_belt", "arguments": { "beltId": "belt_1757200000000" } }
+```
+
+Out-of-bounds positions, occupied positions, and non-integer grids are refused with the
+reason named.