coaiajs 0.5.0 → 0.5.1

package/dist/src/skill.js

@@ -0,0 +1,341 @@
+/**
+ * coaiajs — the packaged agent skill.
+ *
+ * WHY THE CONTENT IS NOT IN THIS FILE
+ *
+ * The lineage this is adapted from (coaia-narrative's `src/skill.ts`) embedded ~250
+ * lines of markdown as `['---', 'name: ...', ...].join('\n')`. That works, and it is
+ * unreadable: a documentation change shows up in review as a diff of quoted string
+ * fragments, no markdown tool can lint it, and the prose cannot be read in the form
+ * the reader will see.
+ *
+ * So the skill lives as real markdown under `skills/coaiajs/`, shipped by the `files`
+ * field, and is read from the package root at run time. `tests/skill.test.mjs` fails
+ * if a file listed here does not resolve, which is the failure mode this trades for.
+ *
+ * WHY THE TOOL MAP IS GENERATED
+ *
+ * A hand-written tool table drifts from the server the moment a tool is added, and a
+ * skill that advertises a tool the server does not serve teaches an agent to make a
+ * call that fails. `{{TOOL_MAP}}` is rendered from `ALL_TOOL_DEFINITIONS` — the same
+ * array the MCP server registers — so the two cannot disagree.
+ */
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative as relativePath, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { getPackageRoot, getPackageVersion } from './version.js';
+import { ALL_TOOL_DEFINITIONS, CORE_TOOLS, STC_TOOLS, NARRATIVE_TOOLS, WAMPUM_TOOLS, KG_TOOLS, } from './narrative/index.js';
+export const SKILL_NAME = 'coaiajs';
+/**
+ * Files that make up the skill, in the order a reader meets them.
+ *
+ * Listed explicitly rather than discovered by walking the directory: a stray file
+ * under `skills/` should not silently become part of what gets installed, and a
+ * missing one should be an error rather than a quietly shorter skill.
+ */
+export const SKILL_FILES = [
+    'SKILL.md',
+    'references/creative-orientation.md',
+    'references/structural-tension-charting.md',
+    'references/delayed-resolution.md',
+    'references/narrative-beats.md',
+    'references/wampum-belts.md',
+    'references/reading-the-store.md',
+    'references/beyond-narrative.md',
+    'references/mcp-tools.md',
+    'references/install-and-environment.md',
+];
+/** Directory inside the package holding the skill's markdown. */
+export function getPackagedSkillDir() {
+    return join(getPackageRoot(), 'skills', SKILL_NAME);
+}
+// ─── Tool map generation ──────────────────────────────────────────────
+/**
+ * Abbreviations whose trailing period does not end a sentence. Without these,
+ * `open_nodes` — whose description reads "…by exact name (e.g. 'chart_123_chart')" —
+ * rendered as "Open specific entity nodes by exact name (e.g." in the table, which
+ * reads as a truncation bug rather than as a description.
+ */
+const NON_TERMINAL_ABBREVIATIONS = ['e.g', 'i.e', 'etc', 'vs', 'cf', 'approx', 'no'];
+/**
+ * One line of description, trimmed to something a table cell can hold.
+ *
+ * Leading emphasis markers ("🚨 NEW LLM?", "✨ RECOMMENDED:", "⚠️ DEPRECATED:") are kept
+ * deliberately — they carry the tool's own stance about itself, and a map that hides a
+ * deprecation is worse than one that shows it.
+ */
+function shortDescription(description) {
+    const collapsed = description.replace(/\s+/g, ' ').trim();
+    // Cut at the first period that actually ends a sentence: followed by whitespace and
+    // something that starts one, and not preceded by an abbreviation or a single letter.
+    let sentence = collapsed;
+    for (const match of collapsed.matchAll(/\.(?=\s+[A-Z0-9`'"(\u{1F300}-\u{1FAFF}])/gu)) {
+        const before = collapsed.slice(0, match.index);
+        const lastWord = (/([A-Za-z.]+)$/.exec(before)?.[1] ?? '').toLowerCase();
+        if (NON_TERMINAL_ABBREVIATIONS.includes(lastWord))
+            continue;
+        if (/^[a-z]$/.test(lastWord))
+            continue; // an initial, not a sentence end
+        sentence = collapsed.slice(0, match.index + 1);
+        break;
+    }
+    const escaped = sentence.replace(/\|/g, '\\|');
+    return escaped.length > 180 ? `${escaped.slice(0, 177)}…` : escaped;
+}
+const TOOL_GROUP_ORDER = [
+    { title: 'Start here', names: CORE_TOOLS },
+    { title: 'Structural tension charts', names: STC_TOOLS },
+    { title: 'Narrative beats', names: NARRATIVE_TOOLS },
+    { title: 'Wampum belts', names: WAMPUM_TOOLS },
+    { title: 'Knowledge graph', names: KG_TOOLS },
+];
+/**
+ * Render the narrative tool surface as grouped markdown tables, from the definitions
+ * the MCP server actually registers. A tool that belongs to no group still appears,
+ * under "Other" — a tool silently absent from its own map is the drift this avoids.
+ */
+export function renderToolMap() {
+    const byName = new Map(ALL_TOOL_DEFINITIONS.map(t => [t.name, t]));
+    const placed = new Set();
+    const sections = [];
+    for (const group of TOOL_GROUP_ORDER) {
+        const rows = [];
+        for (const name of group.names) {
+            const tool = byName.get(name);
+            if (!tool || placed.has(name))
+                continue;
+            placed.add(name);
+            rows.push(`| \`${name}\` | ${shortDescription(tool.description)} |`);
+        }
+        if (rows.length === 0)
+            continue;
+        sections.push(`### ${group.title}\n\n| Tool | Use |\n|---|---|\n${rows.join('\n')}`);
+    }
+    const leftover = ALL_TOOL_DEFINITIONS.filter(t => !placed.has(t.name));
+    if (leftover.length > 0) {
+        const rows = leftover.map(t => `| \`${t.name}\` | ${shortDescription(t.description)} |`);
+        sections.push(`### Other\n\n| Tool | Use |\n|---|---|\n${rows.join('\n')}`);
+    }
+    return sections.join('\n\n');
+}
+// ─── Rendering ────────────────────────────────────────────────────────
+/** Placeholders a packaged skill file may carry. */
+function substitutions() {
+    return {
+        VERSION: getPackageVersion(),
+        // The narrative/chart surface only. The server also serves Langfuse, PDE, and
+        // planning tools, and counting those here would mean importing the MCP feature
+        // config into the library — see references/beyond-narrative.md instead.
+        NARRATIVE_TOOL_COUNT: String(ALL_TOOL_DEFINITIONS.length),
+        TOOL_MAP: renderToolMap(),
+    };
+}
+function applySubstitutions(content, values) {
+    return content.replace(/\{\{([A-Z_]+)\}\}/g, (whole, key) => {
+        const value = values[key];
+        if (value === undefined) {
+            throw new Error(`Packaged skill carries an unknown placeholder {{${key}}}. ` +
+                `Add it to substitutions() in src/skill.ts or remove it from the markdown.`);
+        }
+        return value;
+    });
+}
+/** Read one packaged skill file and fill its placeholders. */
+export function renderSkillFile(relativeFilePath) {
+    const source = join(getPackagedSkillDir(), relativeFilePath);
+    let raw;
+    try {
+        raw = readFileSync(source, 'utf8');
+    }
+    catch {
+        throw new Error(`Packaged skill file missing: ${source}. ` +
+            `The published package must ship skills/ — check the "files" field in package.json.`);
+    }
+    return applySubstitutions(raw, substitutions());
+}
+/** Every skill file, rendered, keyed by its path within the skill directory. */
+export function renderSkill() {
+    const values = substitutions();
+    const rendered = new Map();
+    for (const file of SKILL_FILES) {
+        const source = join(getPackagedSkillDir(), file);
+        let raw;
+        try {
+            raw = readFileSync(source, 'utf8');
+        }
+        catch {
+            throw new Error(`Packaged skill file missing: ${source}. ` +
+                `The published package must ship skills/ — check the "files" field in package.json.`);
+        }
+        rendered.set(file, applySubstitutions(raw, values));
+    }
+    return rendered;
+}
+// ─── Install locations ────────────────────────────────────────────────
+export function getSkillInstallDir(globalInstall) {
+    return globalInstall
+        ? resolve(homedir(), '.agents', 'skills', SKILL_NAME)
+        : resolve(process.cwd(), '.agents', 'skills', SKILL_NAME);
+}
+export function getClaudeSkillLinkPath(globalInstall) {
+    return globalInstall
+        ? resolve(homedir(), '.claude', 'skills', SKILL_NAME)
+        : resolve(process.cwd(), '.claude', 'skills', SKILL_NAME);
+}
+function pathExists(pathName) {
+    try {
+        lstatSync(pathName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function removePath(pathName) {
+    const stat = lstatSync(pathName);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        rmSync(pathName, { recursive: true, force: true });
+    }
+    else {
+        unlinkSync(pathName);
+    }
+}
+function writeRenderedSkill(targetDir, force) {
+    // Render before touching anything on disk: a missing packaged file must not leave
+    // a half-written skill where a whole one used to be.
+    const rendered = renderSkill();
+    if (pathExists(targetDir)) {
+        if (!force) {
+            throw new Error(`Skill already exists: ${targetDir} (use --force to replace it)`);
+        }
+        removePath(targetDir);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    for (const [file, content] of rendered) {
+        const destination = resolve(targetDir, file);
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, content, 'utf-8');
+    }
+}
+function ensureClaudeSymlink(linkPath, targetDir, force) {
+    const parentDir = dirname(linkPath);
+    if (pathExists(parentDir)) {
+        const resolvedTargetParent = realpathSync(dirname(targetDir));
+        const resolvedLinkParent = realpathSync(parentDir);
+        // Already the same directory — Claude sees the skill without a link.
+        if (resolvedTargetParent === resolvedLinkParent) {
+            return false;
+        }
+    }
+    const linkTarget = relativePath(parentDir, targetDir) || '.';
+    mkdirSync(parentDir, { recursive: true });
+    if (pathExists(linkPath)) {
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink() && readlinkSync(linkPath) === linkTarget) {
+            return true;
+        }
+        if (!force) {
+            throw new Error(`Claude skill path already exists: ${linkPath} (use --force to replace it)`);
+        }
+        removePath(linkPath);
+    }
+    symlinkSync(linkTarget, linkPath, 'dir');
+    return true;
+}
+async function shouldCreateClaudeSymlink(linkPath, autoYes) {
+    if (autoYes)
+        return true;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(`Tip: create a Claude symlink manually at ${linkPath}`);
+        return false;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`Create a symlink in ${linkPath}? [y/N] `);
+        const normalized = answer.trim().toLowerCase();
+        return normalized === 'y' || normalized === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+// ─── Commands ─────────────────────────────────────────────────────────
+/** Print the packaged SKILL.md, rendered. */
+export function showSkill() {
+    process.stdout.write(renderSkillFile('SKILL.md'));
+}
+export async function installSkill(options = {}) {
+    const globalInstall = options.global === true;
+    const installDir = getSkillInstallDir(globalInstall);
+    writeRenderedSkill(installDir, options.force === true);
+    console.log(`Installed the coaiajs skill (v${getPackageVersion()}) to ${installDir}`);
+    const claudeLinkPath = getClaudeSkillLinkPath(globalInstall);
+    if (await shouldCreateClaudeSymlink(claudeLinkPath, options.yes === true)) {
+        const linked = ensureClaudeSymlink(claudeLinkPath, installDir, options.force === true);
+        console.log(linked
+            ? `Linked Claude skill at ${claudeLinkPath}`
+            : `Claude already sees the skill via ${dirname(claudeLinkPath)}`);
+    }
+    return installDir;
+}
+/**
+ * Compare an installed skill against the packaged one.
+ *
+ * The failure this exists for is silent: a skill installed by an older `coaiajs`
+ * describes an older tool surface, sits there looking authoritative, and nothing in
+ * the normal flow ever says so. An agent then reads a tool map that no longer matches
+ * the server it is talking to.
+ */
+export function checkSkill(options = {}) {
+    const installDir = getSkillInstallDir(options.global === true);
+    const packageVersion = getPackageVersion();
+    if (!pathExists(installDir)) {
+        return { status: 'missing', installDir, packageVersion, differing: [], absent: [...SKILL_FILES] };
+    }
+    const rendered = renderSkill();
+    const differing = [];
+    const absent = [];
+    let installedVersion;
+    for (const [file, expected] of rendered) {
+        let actual;
+        try {
+            actual = readFileSync(resolve(installDir, file), 'utf8');
+        }
+        catch {
+            absent.push(file);
+            continue;
+        }
+        if (file === 'SKILL.md') {
+            installedVersion = /^\s*packageVersion:\s*"?([^"\n]+)"?\s*$/m.exec(actual)?.[1]?.trim();
+        }
+        if (actual !== expected)
+            differing.push(file);
+    }
+    const status = differing.length === 0 && absent.length === 0 ? 'current' : 'stale';
+    return { status, installDir, packageVersion, installedVersion, differing, absent };
+}
+/** Human-readable form of a check, for the CLI. */
+export function formatSkillCheck(result) {
+    const lines = [];
+    switch (result.status) {
+        case 'missing':
+            lines.push(`No skill installed at ${result.installDir}`);
+            lines.push(`Install it with: coaia skill install`);
+            break;
+        case 'current':
+            lines.push(`Skill at ${result.installDir} is current (v${result.packageVersion})`);
+            break;
+        case 'stale':
+            lines.push(`Skill at ${result.installDir} is stale: installed from ` +
+                `v${result.installedVersion ?? 'unknown'}, package is v${result.packageVersion}`);
+            if (result.absent.length > 0)
+                lines.push(`  absent: ${result.absent.join(', ')}`);
+            if (result.differing.length > 0)
+                lines.push(`  differs: ${result.differing.join(', ')}`);
+            lines.push(`Refresh it with: coaia skill install --force`);
+            break;
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=skill.js.map

package/dist/src/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/skill.ts"],"names":[],"mappings":"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"}

package/dist/src/version.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Directory holding this package's own `package.json`.
+ *
+ * Anything shipped alongside `dist/` — the packaged skill under `skills/`, the
+ * Custom GPT specs, the rispecs — is found from here rather than from
+ * `process.cwd()`, which is the caller's directory and says nothing about where
+ * the package was installed.
+ */
+export declare function getPackageRoot(): string;
 /** Resolved version of the installed `coaiajs` package. */
 export declare function getPackageVersion(): string;
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAYA,2DAA2D;AAC3D,wBAAgB,iBAAiB,IAAI,MAAM,CAyB1C"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CA0BvC;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C"}

package/dist/src/version.js

@@ -1,33 +1,49 @@
-// coaiajs/src/version.ts — single source of truth for the runtime version.
-// Reads package.json at runtime so the CLI banner, the MCP handshake, and the
-// published package can never drift apart again.
+// coaiajs/src/version.ts — single source of truth for the runtime version and the
+// installed package root. Reads package.json at runtime so the CLI banner, the MCP
+// handshake, the packaged skill, and the published package can never drift apart.
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const PACKAGE_NAME = 'coaiajs';
-let cached;
-/** Resolved version of the installed `coaiajs` package. */
-export function getPackageVersion() {
-    if (cached)
-        return cached;
+let cachedVersion;
+let cachedRoot;
+/**
+ * Directory holding this package's own `package.json`.
+ *
+ * Anything shipped alongside `dist/` — the packaged skill under `skills/`, the
+ * Custom GPT specs, the rispecs — is found from here rather than from
+ * `process.cwd()`, which is the caller's directory and says nothing about where
+ * the package was installed.
+ */
+export function getPackageRoot() {
+    if (cachedRoot)
+        return cachedRoot;
     const here = dirname(fileURLToPath(import.meta.url));
     // dist/src/version.js -> package root is two levels up.
     // src/version.ts (ts-node/tsx) -> package root is one level up.
-    const candidates = [join(here, '..', '..', 'package.json'), join(here, '..', 'package.json')];
-    for (const candidate of candidates) {
+    const candidates = [join(here, '..', '..'), join(here, '..')];
+    for (const root of candidates) {
         let raw;
         try {
-            raw = readFileSync(candidate, 'utf8');
+            raw = readFileSync(join(root, 'package.json'), 'utf8');
         }
         catch {
             continue; // not at this depth; try the next candidate
         }
         const pkg = JSON.parse(raw);
         if (pkg.name === PACKAGE_NAME && pkg.version) {
-            cached = pkg.version;
-            return cached;
+            cachedRoot = root;
+            cachedVersion = pkg.version;
+            return cachedRoot;
         }
     }
-    throw new Error(`Unable to resolve ${PACKAGE_NAME} version: no package.json found near ${here}`);
+    throw new Error(`Unable to resolve the ${PACKAGE_NAME} package root: no matching package.json near ${here}`);
+}
+/** Resolved version of the installed `coaiajs` package. */
+export function getPackageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    getPackageRoot(); // populates cachedVersion, or throws naming the reason
+    return cachedVersion;
 }
 //# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,iDAAiD;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,YAAY,GAAG,SAAS,CAAC;AAE/B,IAAI,MAA0B,CAAC;AAE/B,2DAA2D;AAC3D,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,wDAAwD;IACxD,gEAAgE;IAChE,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IAE9F,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,4CAA4C;QACxD,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwC,CAAC;QACnE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC;YACrB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,qBAAqB,YAAY,wCAAwC,IAAI,EAAE,CAChF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mFAAmF;AACnF,kFAAkF;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,YAAY,GAAG,SAAS,CAAC;AAE/B,IAAI,aAAiC,CAAC;AACtC,IAAI,UAA8B,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,wDAAwD;IACxD,gEAAgE;IAChE,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAE9D,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,4CAA4C;QACxD,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwC,CAAC;QACnE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC7C,UAAU,GAAG,IAAI,CAAC;YAClB,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,yBAAyB,YAAY,gDAAgD,IAAI,EAAE,CAC5F,CAAC;AACJ,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,iBAAiB;IAC/B,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,cAAc,EAAE,CAAC,CAAC,uDAAuD;IACzE,OAAO,aAAuB,CAAC;AACjC,CAAC"}

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