coaiajs 0.4.3 → 0.5.1

package/dist/src/skill.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+export declare 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 declare const SKILL_FILES: readonly string[];
+/** Directory inside the package holding the skill's markdown. */
+export declare function getPackagedSkillDir(): string;
+/**
+ * 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 declare function renderToolMap(): string;
+/** Read one packaged skill file and fill its placeholders. */
+export declare function renderSkillFile(relativeFilePath: string): string;
+/** Every skill file, rendered, keyed by its path within the skill directory. */
+export declare function renderSkill(): Map<string, string>;
+export declare function getSkillInstallDir(globalInstall: boolean): string;
+export declare function getClaudeSkillLinkPath(globalInstall: boolean): string;
+/** Print the packaged SKILL.md, rendered. */
+export declare function showSkill(): void;
+export interface InstallSkillOptions {
+    global?: boolean;
+    force?: boolean;
+    yes?: boolean;
+}
+export declare function installSkill(options?: InstallSkillOptions): Promise<string>;
+export interface SkillCheckResult {
+    status: 'current' | 'stale' | 'missing';
+    installDir: string;
+    packageVersion: string;
+    /** Version recorded in the installed SKILL.md frontmatter, when one is readable. */
+    installedVersion?: string;
+    /** Files whose installed content differs from what this package would write. */
+    differing: string[];
+    /** Files this package ships that the install does not have. */
+    absent: string[];
+}
+/**
+ * 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 declare function checkSkill(options?: {
+    global?: boolean;
+}): SkillCheckResult;
+/** Human-readable form of a check, for the CLI. */
+export declare function formatSkillCheck(result: SkillCheckResult): string;
+//# sourceMappingURL=skill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA2BH,eAAO,MAAM,UAAU,YAAY,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAWxC,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AA8CD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAwBtC;AA6BD,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAYhE;AAED,gFAAgF;AAChF,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBjD;AAID,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAIjE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAIrE;AAyFD,6CAA6C;AAC7C,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBrF;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,gBAAgB,CA6B/E;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAqBjE"}

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/types.d.ts

@@ -1,8 +1,169 @@
 export interface Entity {
+    /** Present on records read straight from the JSONL store, where it carries the line's kind. */
+    type?: string;
     name: string;
     entityType: string;
     observations: string[];
     metadata?: EntityMetadata;
+    [key: string]: unknown;
+}
+export type GithubSyncState = 'synced' | 'diverged' | 'conflict' | 'project-only' | 'chart-only';
+export type GithubSyncAuthority = 'jsonl' | 'project';
+export interface GithubIssueRef {
+    owner: string;
+    repo: string;
+    number: number;
+    nodeId?: string;
+    url?: string;
+}
+export interface GithubProjectItemRef {
+    projectNumber: number;
+    projectOwner: string;
+    projectTitle?: string;
+    itemId: string;
+    url?: string;
+}
+export interface GithubBridgeMetadata {
+    issue?: GithubIssueRef;
+    projectItem?: GithubProjectItemRef;
+    projectItems?: GithubProjectItemRef[];
+    syncState?: GithubSyncState;
+    lastSyncedAt?: string;
+    fieldHash?: string;
+    authoritativeOnLastSync?: GithubSyncAuthority;
+}
+export type GithubChartProvenance = GithubBridgeMetadata;
+export type GithubActionStepProvenance = GithubBridgeMetadata;
+export interface LegacyGithubSyncTarget {
+    owner?: string;
+    repo?: string;
+    issue_number?: number;
+    issueNumber?: number;
+    number?: number;
+    node_id?: string;
+    nodeId?: string;
+    issue_url?: string;
+    url?: string;
+    project_id?: string;
+    projectId?: string;
+    project_number?: number;
+    projectNumber?: number;
+    project_owner?: string;
+    projectOwner?: string;
+    project_title?: string;
+    projectTitle?: string;
+    item_id?: string;
+    itemId?: string;
+    project_url?: string;
+}
+export interface LegacyGithubRef {
+    owner?: string;
+    repo?: string;
+    issue_number?: number;
+    issueNumber?: number;
+    number?: number;
+    node_id?: string;
+    nodeId?: string;
+    issue_url?: string;
+    url?: string;
+}
+export type SourceSystem = 'coaia-narrative' | 'coaia-pde' | 'coaia-planning' | 'mcp-pde' | 'manual' | 'miadi' | 'coaia-github' | 'coaiajs' | (string & {});
+export interface SourceProvenance {
+    system: SourceSystem;
+    version?: string;
+    toolName?: string;
+    sessionId?: string;
+    createdAt?: string;
+}
+/**
+ * Deep Research Foundations metadata for tracking research packet context and evaluation status.
+ * Used by Atlas Chronicle and research delegation workflows.
+ *
+ * @see https://github.com/avadisabelle/coaia-narrative/issues/39
+ */
+export interface DeepResearchFoundationMetadata {
+    packetRoot?: string;
+    foundationType?: string;
+    parentIssue?: string;
+    baselineIssue?: string;
+    inquiryIssue?: string;
+    protocolIssue?: string;
+    schemaIssue?: string;
+    visualizerIssue?: string;
+    expectedArtifacts?: string[];
+    producedArtifacts?: string[];
+    evaluationStatus?: 'expected' | 'delegated' | 'produced' | 'evaluated';
+    privacyClass?: 'public-safe' | 'private' | 'mixed';
+    publicationStatus?: 'planned' | 'draft' | 'reviewed' | 'published';
+    commitHandles?: string[];
+}
+/**
+ * Hermes session lineage metadata tracking conversation branching and handoff state.
+ * Used for reconstructing branch maps and session traceability.
+ *
+ * @see https://github.com/avadisabelle/coaia-narrative/issues/40
+ */
+export interface HermesSessionLineageMetadata {
+    platform?: string;
+    parentChartId?: string;
+    sourceBeat?: string;
+    originalSessionId?: string;
+    branchSessionId?: string;
+    branchIndex?: number;
+    copiedMessageCount?: number;
+    branchPurpose?: string;
+    relatedIssues?: string[];
+    handoffState?: 'requirements-created' | 'implementation-ready' | 'returned-to-parent';
+}
+/**
+ * Beat-level lived session context metadata capturing the embodied condition of working sessions.
+ * Records land-based learning, voice/terminal mode, environmental constraints, and continuity context.
+ *
+ * @see https://github.com/avadisabelle/coaia-narrative/issues/42
+ */
+export interface SessionContextMetadata {
+    mode?: 'voice' | 'terminal' | 'mixed';
+    setting?: 'desk' | 'walking' | 'land-based' | 'transit' | 'unknown';
+    landBasedLearning?: boolean;
+    environmentNotes?: string[];
+    listeningContext?: string;
+    captureQuality?: 'clear' | 'windy' | 'partial';
+    continuationKind?: 'branch' | 'parent-return' | 'follow-up';
+    privateChroniclePath?: string;
+    publicSummaryAllowed?: boolean;
+}
+export interface WampumBeadPosition {
+    row: number;
+    col: number;
+}
+export interface WampumCeremonyLink {
+    ceremonyType: 'commitment' | 'accountability' | 'witness' | 'renewal';
+    chartId?: string;
+    beatName?: string;
+    witnessNames?: string[];
+    renewalDate?: string;
+    notes?: string;
+}
+export interface WampumBead {
+    id: string;
+    mnemonic: string;
+    color: 'white' | 'purple' | 'black' | 'mixed';
+    position: WampumBeadPosition;
+    reading: string;
+    relationalReadings?: Record<string, string>;
+    ceremonyLink?: WampumCeremonyLink;
+    observations: string[];
+    createdAt: string;
+}
+export interface WampumBeltMetadata {
+    beltId: string;
+    title: string;
+    purpose: string;
+    rows: number;
+    cols: number;
+    beads: WampumBead[];
+    createdAt: string;
+    updatedAt: string;
 }
 export interface EntityMetadata {
     dueDate?: string;
@@ -49,23 +210,51 @@ export interface EntityMetadata {
         lessons: string[];
     };
     order?: number;
+    github?: GithubBridgeMetadata;
+    source?: SourceProvenance;
+    /** Deep Research Foundations metadata for research packet tracking and evaluation. */
+    foundation?: DeepResearchFoundationMetadata;
+    /** Hermes session lineage metadata for conversation branching and handoff tracking. */
+    sessionLineage?: HermesSessionLineageMetadata;
+    /** Beat-level lived session context capturing embodied working conditions. */
+    sessionContext?: SessionContextMetadata;
+    /** Wampum Belt metadata for non-linear mnemonic sequencing with ceremony links. */
+    wampumBelt?: WampumBeltMetadata;
+    /** Belt identifier carried on the wampum_belt entity itself. */
+    beltId?: string;
+    /** @deprecated Use github.issue and github.projectItem instead. */
+    sync_target?: LegacyGithubSyncTarget;
+    /** @deprecated Use github.issue instead. */
+    github_ref?: LegacyGithubRef;
+    [key: string]: unknown;
 }
 export interface Relation {
+    /** Present on records read straight from the JSONL store, where it carries the line's kind. */
+    type?: string;
     from: string;
     to: string;
     relationType: string;
     metadata?: RelationMetadata;
+    [key: string]: unknown;
 }
 export interface RelationMetadata {
     createdAt?: string;
     strength?: number;
     context?: string;
     description?: string;
+    beltId?: string;
+    [key: string]: unknown;
 }
 export interface KnowledgeGraph {
     entities: Entity[];
     relations: Relation[];
+    /**
+     * The store's lines exactly as they were read, kept so a write can round-trip
+     * fields this package does not model. Absent on a graph built in memory.
+     */
+    rawRecords?: JsonlRecord[];
 }
+export type JsonlRecord = Record<string, unknown>;
 export interface McpToolResult {
     content: Array<{
         type: string;