omkit 0.4.7 → 0.8.0

package/dist/output/artifact/ArtifactStore.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+const MIME_BY_EXT = {
+    ".json": "application/json",
+    ".jsonl": "application/x-ndjson",
+    ".log": "text/plain",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".csv": "text/csv",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+};
+/**
+ * The run's curated artifacts — the files an om labelled via `ctx.artifact`, in
+ * registration order. Holds no I/O: the om already wrote the file, this records what it
+ * means. Unregistered files stay in the run folder and stay listed by anything
+ * enumerating it; curation raises signal, it does not gate access.
+ */
+export class ArtifactStore {
+    records = [];
+    register(name, file, nodeId, opts = {}) {
+        // `file` is documented absolute; a caller that passes a relative path still gets
+        // one back — resolved against process.cwd(), same base `path.resolve` uses by
+        // default — so every consumer (the return value, the timeline message, the
+        // on-disk rollups) carries a path that means the same thing without them.
+        const resolved = path.resolve(file);
+        const record = {
+            name,
+            file: resolved,
+            nodeId,
+            mime: opts.mime ?? mimeOf(resolved),
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+        };
+        this.records.push(record);
+        return record;
+    }
+    all() {
+        return this.records;
+    }
+}
+function mimeOf(file) {
+    return MIME_BY_EXT[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+}

package/dist/output/folder/RunFolder.d.ts

@@ -12,10 +12,32 @@ export declare class RunFolder {
     constructor(runName: string, hash: string);
     /** `<name>-<hash8>` — the run's folder name, unique per (defining file, name). */
     name(): string;
-    /** The absolute run directory, computed once and created on first access. */
+    /**
+     * The absolute run directory — claimed on first access, stable thereafter.
+     *
+     * Claiming and knowing the path are the same act: the directory is what makes a run's
+     * identity exclusive, so there is no meaningful "what would the path be" to answer
+     * before it exists.
+     */
     path(): string;
     /** Absolute path to `name` inside the run folder; ensures the folder exists. */
     file(name: string): string;
     /** Create the run folder synchronously (idempotent). */
     ensure(): void;
+    /**
+     * Take exclusive ownership of a `<date>/<time>` directory.
+     *
+     * `hms` has second resolution, so two runs of the same om starting within one second
+     * would otherwise share a folder — and that is not merely "the later one wins":
+     * `RawStream` opens `raw.jsonl` with `flags: "w"`, so two live runs both truncate it and
+     * then write at their own offsets, leaving bytes that are not valid JSONL. The MCP
+     * server makes this easy to reach, since `start_om` can put two children in flight.
+     *
+     * Finer timestamps would only lower the odds. `mkdirSync` without `recursive` throws
+     * `EEXIST` **atomically**, and that atomicity holds between processes — so the directory
+     * creation is itself the lock. The common case keeps a clean `16-39-29`; only a real
+     * collision produces `16-39-29-02`, zero-padded so lexical order stays chronological
+     * (which is what `latest` relies on).
+     */
+    private claim;
 }

package/dist/output/folder/RunFolder.js

@@ -1,7 +1,10 @@
 import { mkdirSync } from "node:fs";
 import path from "node:path";
-import { ymd, hms } from "../../foundation/format.js";
+import { ymd, hms, pad } from "../../foundation/format.js";
 import { fsSafe } from "../../foundation/fsSafe.js";
+import { newUuid, shortId } from "../../foundation/ids.js";
+/** Suffixed attempts (`-02` … `-99`) before falling back to a random, certainly-unique one. */
+const MAX_NUMBERED_ATTEMPTS = 99;
 /**
  * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
  * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
@@ -21,24 +24,65 @@ export class RunFolder {
     name() {
         return `${fsSafe(this.runName)}-${this.hash}`;
     }
-    /** The absolute run directory, computed once and created on first access. */
+    /**
+     * The absolute run directory — claimed on first access, stable thereafter.
+     *
+     * Claiming and knowing the path are the same act: the directory is what makes a run's
+     * identity exclusive, so there is no meaningful "what would the path be" to answer
+     * before it exists.
+     */
     path() {
-        if (this.dir)
-            return this.dir;
-        const now = new Date();
-        this.dir = path.resolve("logs", this.name(), ymd(now), hms(now, "-"));
+        if (!this.dir)
+            this.claim();
         return this.dir;
     }
     /** Absolute path to `name` inside the run folder; ensures the folder exists. */
     file(name) {
-        this.ensure();
         return path.join(this.path(), name);
     }
     /** Create the run folder synchronously (idempotent). */
     ensure() {
-        if (this.ensured)
-            return;
-        mkdirSync(this.path(), { recursive: true });
-        this.ensured = true;
+        this.path();
+    }
+    /**
+     * Take exclusive ownership of a `<date>/<time>` directory.
+     *
+     * `hms` has second resolution, so two runs of the same om starting within one second
+     * would otherwise share a folder — and that is not merely "the later one wins":
+     * `RawStream` opens `raw.jsonl` with `flags: "w"`, so two live runs both truncate it and
+     * then write at their own offsets, leaving bytes that are not valid JSONL. The MCP
+     * server makes this easy to reach, since `start_om` can put two children in flight.
+     *
+     * Finer timestamps would only lower the odds. `mkdirSync` without `recursive` throws
+     * `EEXIST` **atomically**, and that atomicity holds between processes — so the directory
+     * creation is itself the lock. The common case keeps a clean `16-39-29`; only a real
+     * collision produces `16-39-29-02`, zero-padded so lexical order stays chronological
+     * (which is what `latest` relies on).
+     */
+    claim() {
+        const now = new Date();
+        const parent = path.resolve("logs", this.name(), ymd(now));
+        mkdirSync(parent, { recursive: true });
+        const base = hms(now, "-");
+        for (let attempt = 0; attempt <= MAX_NUMBERED_ATTEMPTS; attempt += 1) {
+            // A random suffix as the last resort: bounded loops beat an unbounded one, and a
+            // hundred collisions inside one second means something stranger is going on.
+            const suffix = attempt === 0
+                ? ""
+                : attempt === MAX_NUMBERED_ATTEMPTS
+                    ? `-${shortId(newUuid())}`
+                    : `-${pad(attempt + 1)}`;
+            const candidate = path.join(parent, `${base}${suffix}`);
+            try {
+                mkdirSync(candidate); // deliberately not recursive — EEXIST is the lock
+                this.dir = candidate;
+                this.ensured = true;
+                return;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+            }
+        }
     }
 }

package/dist/output/writers/views.d.ts

@@ -21,6 +21,14 @@ export interface NodeView {
     readonly logFile: string;
     readonly children: readonly NodeView[];
 }
+/** A curated artifact, as projected into `result.json`. Data-only — no core import. */
+export interface ArtifactView {
+    readonly name: string;
+    /** Absolute path to the file. */
+    readonly file: string;
+    readonly description?: string;
+    readonly mime: string;
+}
 export interface RunView {
     readonly ok: boolean;
     readonly failures: ReadonlyArray<{
@@ -37,4 +45,6 @@ export interface RunView {
     /** Absolute path to `raw.jsonl`. */
     readonly rawStream: string;
     readonly root: NodeView;
+    /** Files the run labelled via `ctx.artifact`, in registration order. */
+    readonly artifacts: readonly ArtifactView[];
 }

package/dist/skill/file.d.ts

@@ -0,0 +1,26 @@
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export declare const SKILL_RELATIVE_PATH: string;
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export declare const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) \u2014 what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/** What a previously generated file still has to say for itself. */
+export interface ExistingSkill {
+    /** The `description:` value, verbatim — continuation lines and all. */
+    readonly description?: string;
+    /** The `registry-hash` from the generated-by marker, when the file carries one. */
+    readonly hash?: string;
+}
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export declare function readExisting(file: string): ExistingSkill;
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export declare function writeSkill(file: string, content: string): void;

package/dist/skill/file.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_NAME } from "./render.js";
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export const SKILL_RELATIVE_PATH = path.join(".claude", "skills", SKILL_NAME, "SKILL.md");
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) — what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export function readExisting(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const hash = /registry-hash:\s*([0-9a-f]{8})/.exec(text)?.[1];
+    const description = frontmatterDescription(text);
+    return { ...(description !== undefined ? { description } : {}), ...(hash ? { hash } : {}) };
+}
+/**
+ * Pull `description` out of the leading frontmatter, keeping any folded continuation lines
+ * exactly as written — they are re-emitted verbatim, so a wrapped description survives
+ * regeneration byte-for-byte instead of being reflowed into one long line.
+ */
+function frontmatterDescription(text) {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    if (block === undefined)
+        return undefined;
+    const lines = block.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.startsWith("description:"));
+    if (start === -1)
+        return undefined;
+    const value = [lines[start].slice("description:".length).trimStart()];
+    // A continuation is any indented line; the next unindented line starts a new key.
+    for (const line of lines.slice(start + 1)) {
+        if (!/^\s+\S/.test(line))
+            break;
+        value.push(line);
+    }
+    return value.join("\n");
+}
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export function writeSkill(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, "utf8");
+}

package/dist/skill/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.ts";
+export type { SkillCall, SkillEntry, SkillModel } from "./model.ts";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.ts";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.ts";
+export type { ExistingSkill } from "./file.ts";

package/dist/skill/index.js

@@ -0,0 +1,9 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.js";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.js";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.js";

package/dist/skill/model.d.ts

@@ -0,0 +1,55 @@
+import type { McpMode } from "../core/types.ts";
+import type { JsonSchema } from "../core/schema-json.ts";
+import type { OmCall, RegistrationSet, Registry } from "../client/registry.ts";
+/** One step in a rendered outline. Structurally an {@link OmCall}; named for the skill's vocabulary. */
+export type SkillCall = OmCall;
+/** One runnable thing the generated skill documents. */
+export interface SkillEntry {
+    readonly kind: "om" | "action";
+    readonly name: string;
+    /** Project-relative, forward slashes on every platform — so the file does not churn per-OS. */
+    readonly file: string;
+    readonly mode: McpMode;
+    /** The `.describe({ summary })` line. Absent when the author wrote none; never invented. */
+    readonly summary?: string;
+    /** A one-line sketch of the declared args, from {@link shapeHint}. */
+    readonly argHint?: string;
+    /** The raw schema, present only when `shapeHint` could not sketch it (per C7). */
+    readonly argSchema?: JsonSchema;
+    /** The static outline of the body. Absent when the walk found nothing recognisable. */
+    readonly calls?: readonly SkillCall[];
+    /** Why this entry cannot be called — carried through from discovery, rendered as a warning. */
+    readonly unavailable?: string;
+    /** Actions only: the exported binding a host om imports. */
+    readonly exportName?: string;
+    /** Actions only: true when the chain includes `.ref<…>()`, so it publishes a capability. */
+    readonly publishesCapability?: boolean;
+}
+/** Everything the renderer needs, plus the hash that detects drift against it. */
+export interface SkillModel {
+    readonly oms: readonly SkillEntry[];
+    readonly actions: readonly SkillEntry[];
+    /** First 8 hex of sha256 over the registry data below — never over the rendered markdown. */
+    readonly hash: string;
+}
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export declare function buildSkillModel(registrations: RegistrationSet, registry: Registry, root: string): SkillModel;
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export declare function registryHash(entries: readonly SkillEntry[]): string;

package/dist/skill/model.js

@@ -0,0 +1,116 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { shapeHint } from "../core/schema-hint.js";
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export function buildSkillModel(registrations, registry, root) {
+    const outlines = new Map(registry.oms.map((o) => [key(o.name, o.file), o.calls]));
+    const capabilities = new Map(registry.actions.map((a) => [key(a.name, a.file), a.publishesCapability]));
+    const oms = registrations.oms
+        .filter(isExposed)
+        .map((om) => omEntry(om, outlines.get(key(om.name, om.file)), root))
+        .sort(byName);
+    const actions = registrations.actions
+        .filter(isExposed)
+        .map((a) => actionEntry(a, capabilities.get(key(a.name, a.file)), root))
+        .sort(byName);
+    return { oms, actions, hash: registryHash([...oms, ...actions]) };
+}
+function isExposed(r) {
+    return r.mcp !== undefined;
+}
+/** Identity for cross-referencing the two discovery passes: an om is its name in its file. */
+function key(name, file) {
+    return `${name}\0${path.resolve(file)}`;
+}
+/** Alphabetical by name, then by file — so two same-named oms in different files stay ordered. */
+function byName(a, b) {
+    return a.name.localeCompare(b.name) || a.file.localeCompare(b.file);
+}
+function omEntry(om, calls, root) {
+    return {
+        kind: "om",
+        name: om.name,
+        file: relative(om.file, root),
+        mode: om.mcp?.mode ?? "settling",
+        ...describeArgs(om.inputSchema),
+        ...(om.summary ? { summary: om.summary } : {}),
+        ...(calls?.length ? { calls } : {}),
+        ...(om.unavailable ? { unavailable: om.unavailable } : {}),
+    };
+}
+function actionEntry(action, publishesCapability, root) {
+    return {
+        kind: "action",
+        name: action.name,
+        file: relative(action.file, root),
+        mode: action.mcp?.mode ?? "settling",
+        exportName: action.exportName,
+        ...(publishesCapability ? { publishesCapability: true } : {}),
+        ...describeArgs(action.inputSchema),
+        ...(action.summary ? { summary: action.summary } : {}),
+        ...(action.unavailable ? { unavailable: action.unavailable } : {}),
+    };
+}
+/**
+ * Sketch a schema, falling back to the schema itself. `shapeHint` is all-or-nothing by design,
+ * so a `undefined` return means the shape would have been misleading — the honest answer then
+ * is the raw JSON Schema the caller actually has to satisfy, not a partial sketch.
+ */
+function describeArgs(schema) {
+    if (!schema)
+        return {};
+    const hint = shapeHint(schema);
+    return hint === undefined ? { argSchema: schema } : { argHint: hint };
+}
+/** Project-relative with forward slashes; absolute only if the file lies outside the root. */
+function relative(file, root) {
+    const rel = path.relative(root, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return posix(file);
+    return posix(rel);
+}
+const posix = (p) => p.split(path.sep).join("/").split("\\").join("/");
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export function registryHash(entries) {
+    const material = entries.map((e) => [
+        e.kind,
+        e.name,
+        e.file,
+        e.mode,
+        e.summary ?? "",
+        e.exportName ?? "",
+        e.unavailable ?? "",
+        e.publishesCapability === true,
+        e.argSchema ?? e.argHint ?? "",
+        (e.calls ?? []).map((c) => [c.name, c.tag ?? ""]),
+    ]);
+    return createHash("sha256").update(canonical(material)).digest("hex").slice(0, 8);
+}
+/** JSON with object keys sorted at every depth, so key order can never change the hash. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}

package/dist/skill/render.d.ts

@@ -0,0 +1,18 @@
+import type { SkillModel } from "./model.ts";
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export declare const SKILL_NAME = "omkit-runs";
+/**
+ * The marker line that carries the staleness hash. Written by {@link renderSkill} and read
+ * back by the file layer, so the two agree on one format rather than two regexes.
+ */
+export declare const generatedBy: (hash: string) => string;
+/**
+ * Render the model as the skill's markdown.
+ *
+ * Deterministic by construction: no timestamps, no absolute paths, no iteration over unordered
+ * collections — the model arrives sorted. A generated file that is committed and churns on
+ * every run is a file people stop reading.
+ */
+export declare function renderSkill(model: SkillModel, opts: {
+    description: string;
+}): string;

package/dist/skill/render.js

@@ -0,0 +1,133 @@
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export const SKILL_NAME = "omkit-runs";
+/**
+ * The marker line that carries the staleness hash. Written by {@link renderSkill} and read
+ * back by the file layer, so the two agree on one format rather than two regexes.
+ */
+export const generatedBy = (hash) => `<!-- GENERATED by \`omkit skill\`. Do not edit. registry-hash: ${hash} -->`;
+/**
+ * Render the model as the skill's markdown.
+ *
+ * Deterministic by construction: no timestamps, no absolute paths, no iteration over unordered
+ * collections — the model arrives sorted. A generated file that is committed and churns on
+ * every run is a file people stop reading.
+ */
+export function renderSkill(model, opts) {
+    const lines = [
+        "---",
+        `name: ${SKILL_NAME}`,
+        `description: ${opts.description}`,
+        "---",
+        "",
+        "# omkit — runnable workflows",
+        "",
+        generatedBy(model.hash),
+        "",
+        ...howToRun(model),
+        ...workflows(model),
+        ...actions(model),
+        ...whereOutputLands(),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function howToRun(model) {
+    const example = model.oms[0]?.name ?? "<om>";
+    const withArgs = model.oms.find((o) => o.argHint !== undefined) ?? model.oms[0];
+    return [
+        "## How to run",
+        "",
+        "**Shell — always available:**",
+        "",
+        "```bash",
+        `npx omkit run ${example}`,
+        `OMKIT_ARGS='${exampleArgs(withArgs)}' npx omkit run ${withArgs?.name ?? example}`,
+        "```",
+        "",
+        "Arguments travel as one JSON object in `OMKIT_ARGS`. Anything an om declares but does not",
+        "receive is filled from the schema's defaults, and only then by asking.",
+        "",
+        '**MCP — if configured:** `run_om("<name>", { …args })` runs a settling workflow to',
+        "completion and returns its verdict; `start_om` starts a long-lived one and returns a run id",
+        "to poll with `get_run`, read with `tail_run`, and end with `cancel_run`.",
+        "",
+        "To wire it up: `claude mcp add omkit -- npx omkit mcp`",
+        "",
+        "At runtime `list_oms` is authoritative — this file is orientation, and can drift.",
+        "",
+    ];
+}
+/**
+ * A plausible `OMKIT_ARGS` value built from the first declared field, so the example shows the
+ * real shape rather than a placeholder. Falls back to an empty object when nothing is declared.
+ */
+function exampleArgs(entry) {
+    const match = entry?.argHint?.match(/\{ (\w+)\??: (\w+)/);
+    if (!match)
+        return "{}";
+    const [, field, type] = match;
+    const value = type === "string" ? '"…"' : type === "boolean" ? "false" : "0";
+    return `{"${field}":${value}}`;
+}
+function workflows(model) {
+    if (model.oms.length === 0) {
+        return ["## Workflows", "", "_None exposed. Mark an om with `.mcp()` to list it here._", ""];
+    }
+    return ["## Workflows", "", ...model.oms.flatMap((om) => entry(om, omHeading(om)))];
+}
+function actions(model) {
+    if (model.actions.length === 0)
+        return [];
+    return [
+        "## Actions",
+        "",
+        "An action is a step, not a run. It cannot execute on its own — omkit hosts it in a",
+        "generated om so it has a run to belong to, which means it gets its own run folder and",
+        "verdict like anything else.",
+        "",
+        ...model.actions.flatMap((a) => entry(a, `### \`${a.name}\``)),
+    ];
+}
+function omHeading(om) {
+    const mode = om.mode === "long-lived" ? "long-lived · `start_om` only, it does not finish" : "settling";
+    return `### \`${om.name}\` — ${mode}`;
+}
+function entry(e, heading) {
+    const lines = [heading, ""];
+    lines.push(e.summary ?? "_No summary. The author can add one with `.describe({ summary })`._", "");
+    lines.push(`- **Defined in:** \`${e.file}\``);
+    if (e.kind === "action" && e.exportName)
+        lines.push(`- **Exported as:** \`${e.exportName}\``);
+    if (e.argHint)
+        lines.push(`- **Args:** \`${e.argHint}\``);
+    if (e.calls?.length)
+        lines.push(`- **Calls:** ${e.calls.map(renderCall).join(" → ")}`);
+    if (e.publishesCapability) {
+        lines.push("- **Publishes a capability.** It hands a live handle to whatever runs after it. Run on", "  its own there is no downstream, so the handle goes nowhere — useful for a smoke test,", "  not for the thing the capability was for.");
+    }
+    if (e.unavailable)
+        lines.push(`- **Not callable:** ${e.unavailable}`);
+    if (e.argSchema) {
+        lines.push("- **Args** (no short form — the schema is the contract):", "", "```json");
+        lines.push(JSON.stringify(e.argSchema, null, 2));
+        lines.push("```");
+    }
+    lines.push("");
+    return lines;
+}
+const renderCall = (c) => c.tag ? `\`${c.name}\` [${c.tag}]` : `\`${c.name}\``;
+function whereOutputLands() {
+    return [
+        "## Where output lands",
+        "",
+        "`logs/<name>-<hash8>/<date>/<time>/` — `main.log`, `result.json`, `artifacts.log`,",
+        "`events.log`, `asserts.log`, `raw.jsonl`. A run's identity is its name plus its defining",
+        'file, so "the latest run of X" is always resolvable without parsing scrollback.',
+        "",
+        "## What the outlines above do and do not tell you",
+        "",
+        "**Calls** is a static reading of the body, not a trace. A conditional call is listed",
+        "unconditionally, a loop is listed once, an action chosen at runtime is not listed at all,",
+        'and a call made inside a helper function is invisible to it. Read it as "roughly what',
+        'happens in here" and read `result.json` for what actually did.',
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.4.7",
+  "version": "0.8.0",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -52,11 +53,13 @@
     "developer-tools"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "ink": "^7.1.1",
     "patch-console": "^2.0.0",
     "playwright-core": "^1.49.0",
     "react": "^19.2.8",
     "tsx": "4.23.1",
+    "zod": "^4.4.3",
     "zx": "^8.8.5"
   },
   "devDependencies": {