coaiajs 0.4.3 → 0.5.1

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

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.