omkit 0.4.8 → 0.8.0

package/dist/actions/drive-page.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { action } from "../core/action.js";
+import { chromePage } from "./chrome-page.js";
+/**
+ * Evaluate an expression in a live page and report what came back.
+ *
+ * Reaches its page either way round, and that is the point. Given a **handle** it drives a
+ * page an earlier action in the same run already published — the cheap path, and the one an
+ * om driving its own stack should take. Given a **CDP address** it attaches to a browser in
+ * another process entirely, which is what lets this action be described by a schema and
+ * called by name from outside: `browser` and {@link chromePage} publish capability handles,
+ * and a handle is not something a caller across a process boundary can pass.
+ *
+ * Nothing here is owned. `chromePage` closes only a CDP connection it opened, and closing a
+ * CDP connection disconnects the client rather than stopping the browser — so this finishing,
+ * failing, or being cancelled never tears down the stack it attached to, in either mode.
+ */
+export const drivePage = action("drivePage")
+    .describe({
+    summary: "Evaluate JS in a live page — a handle from this run, or a tab of a browser reached over CDP — and report the result.",
+})
+    .run(async ({ snapshot, artifact, artifactsFolder }, opts) => {
+    const { target = "localhost:9222", match, url } = opts;
+    // `chromePage` is daemon-shaped: it stays alive until something stops it, so a run that
+    // only awaits its `.ref` never settles — the tree finishes while the process is still
+    // held open, and the caller waits out a timeout for a run that is already done. Keep the
+    // handle and release it, the same shape `tskb:build` uses for its watcher.
+    const attached = chromePage("target", target, {
+        ...(url === undefined ? {} : { url }),
+        ...(match === undefined ? {} : { match }),
+    }).tag("page:attach");
+    try {
+        const page = await attached.ref;
+        return await evaluateIn(page, opts, { snapshot, artifact, artifactsFolder });
+    }
+    finally {
+        // Releases the daemon whether the expression threw or not. Cancelling closes the CDP
+        // connection, which disconnects this client and leaves the browser to its owner.
+        attached.cancel();
+    }
+});
+/** The work itself, split out so the daemon handle above has one obvious release point. */
+async function evaluateIn(page, opts, { snapshot, artifact, artifactsFolder }) {
+    const { js, screenshot = true } = opts;
+    const title = await page.title();
+    void snapshot("page", { title, url: page.url() });
+    // Evaluated as an expression in page context. A string is sent verbatim, which is what
+    // keeps it clear of the esbuild `__name` rewriting that catches serialized *functions*
+    // under tsx — see the shim in chrome-page.ts.
+    let value;
+    try {
+        value = await page.evaluate(js);
+    }
+    catch (cause) {
+        // A page-side stack means little to a caller who only sent a string, so lead with the
+        // expression that failed and keep the original as the cause.
+        throw new Error(`the expression threw in the page: ${js}`, { cause });
+    }
+    void snapshot("result", { js, value });
+    console.log(`result: ${JSON.stringify(value) ?? "undefined"}`);
+    const result = { value, title, url: page.url() };
+    if (!screenshot)
+        return result;
+    const file = path.join(artifactsFolder, "page.png");
+    await page.screenshot({ path: file });
+    artifact("page.png", file, { description: `The page after evaluating: ${js}` });
+    return { ...result, screenshot: file };
+}

package/dist/actions/index.d.ts

@@ -17,8 +17,10 @@ export type { WatchDirOptions, WatchDirEvents } from "./watch-dir.ts";
 export { tailLog } from "./tail-log.ts";
 export type { TailLogOptions } from "./tail-log.ts";
 export { prompt } from "./prompt.ts";
-export type { PromptOptions, InputPromptOptions, ChoicePromptOptions, PromptChoice, PromptVia, PromptEvents, } from "./prompt.ts";
-export { chromePage } from "./chrome-page.ts";
-export type { ChromePageOptions, ChromePageEvents, ChromePageSource, Page, Browser, BrowserContext, } from "./chrome-page.ts";
+export type { PromptOptions, InputPromptOptions, ChoicePromptOptions, MultilinePromptOptions, MultilineUntil, PromptChoice, PromptVia, PromptEvents, } from "./prompt.ts";
+export { chromePage, selectPage, pagesOf } from "./chrome-page.ts";
+export type { ChromePageOptions, ChromePageEvents, ChromePageSource, PageMatch, Page, Browser, BrowserContext, } from "./chrome-page.ts";
 export { browser } from "./browser.ts";
 export type { BrowserOptions } from "./browser.ts";
+export { drivePage } from "./drive-page.ts";
+export type { DrivePageOptions, DrivePageResult } from "./drive-page.ts";

package/dist/actions/index.js

@@ -10,5 +10,6 @@ export { watch } from "./watch.js";
 export { watchDir } from "./watch-dir.js";
 export { tailLog } from "./tail-log.js";
 export { prompt } from "./prompt.js";
-export { chromePage } from "./chrome-page.js";
+export { chromePage, selectPage, pagesOf } from "./chrome-page.js";
 export { browser } from "./browser.js";
+export { drivePage } from "./drive-page.js";

package/dist/actions/prompt.d.ts

@@ -20,7 +20,33 @@ export interface ChoicePromptOptions extends PromptCommon {
     /** Default selection — a choice value or a 1-based index. Default: the first choice. */
     default?: string | number;
 }
-export type PromptOptions = InputPromptOptions | ChoicePromptOptions;
+/** How a multiline prompt decides the user is done. */
+export type MultilineUntil = "json" | string | ((text: string) => boolean);
+export interface MultilinePromptOptions extends PromptCommon {
+    kind: "multiline";
+    /** A one-line type sketch printed under the message. */
+    hint?: string;
+    /** Default `"json"` — stop once the text parses as JSON. */
+    until?: MultilineUntil;
+    /** Value used on EOF with no input, or on timeout. Default "". */
+    default?: string;
+}
+export type PromptOptions = InputPromptOptions | ChoicePromptOptions | MultilinePromptOptions;
+/** Reads one line, or `undefined` at EOF. */
+export type LineReader = () => Promise<string | undefined>;
+/**
+ * Accumulate lines until `until` says stop, or EOF. Exported for testing: keeping the
+ * termination rule separate from the terminal means it can be driven by a scripted
+ * reader instead of a TTY.
+ *
+ * `"json"` is self-terminating — pasting a pretty-printed blob just works, with no
+ * sentinel to explain. A sentinel line is excluded from the result.
+ *
+ * Note there is deliberately no Ctrl-D/EOF-by-keystroke terminator: readline treats it as
+ * a close, and `prompt` builds and tears down an interface per call, so it risks leaving
+ * stdin unusable for later prompts in the same run.
+ */
+export declare function readUntil(read: LineReader, until: MultilineUntil): Promise<string>;
 /** How a prompt's answer was decided. */
 export type PromptVia = "input" | "default" | "timeout";
 export interface PromptEvents {
@@ -31,10 +57,11 @@ export interface PromptEvents {
     };
 }
 /**
- * Asks the terminal a question — free-text **input** or a **choice** — and resolves
- * with the answer, which it also attaches as the handle (`prompt(...).ref` feeds
- * another action). A timeout (default 30s) falls back to the default so an
- * unattended run never blocks; teardown also unblocks a pending prompt.
+ * Asks the terminal a question — free-text **input**, a **choice**, or a **multiline**
+ * block (see {@link readUntil} for how it ends) — and resolves with the answer, which it
+ * also attaches as the handle (`prompt(...).ref` feeds another action). A timeout
+ * (default 30s) falls back to the default so an unattended run never blocks; teardown
+ * also unblocks a pending prompt.
  */
 export declare const prompt: import("../index.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
 export {};

package/dist/actions/prompt.js

@@ -1,15 +1,56 @@
 import { createInterface } from "node:readline/promises";
 import { action } from "../core/action.js";
 import { activeSupervisor } from "../core/interaction.js";
+/**
+ * Accumulate lines until `until` says stop, or EOF. Exported for testing: keeping the
+ * termination rule separate from the terminal means it can be driven by a scripted
+ * reader instead of a TTY.
+ *
+ * `"json"` is self-terminating — pasting a pretty-printed blob just works, with no
+ * sentinel to explain. A sentinel line is excluded from the result.
+ *
+ * Note there is deliberately no Ctrl-D/EOF-by-keystroke terminator: readline treats it as
+ * a close, and `prompt` builds and tears down an interface per call, so it risks leaving
+ * stdin unusable for later prompts in the same run.
+ */
+export async function readUntil(read, until) {
+    const lines = [];
+    for (;;) {
+        const line = await read();
+        if (line === undefined)
+            break; // EOF
+        if (typeof until === "string" && until !== "json" && line === until)
+            break;
+        lines.push(line);
+        const text = lines.join("\n");
+        if (until === "json" && parses(text))
+            break;
+        if (typeof until === "function" && until(text))
+            break;
+    }
+    return lines.join("\n");
+}
+function parses(text) {
+    if (text.trim() === "")
+        return false;
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
 /** Route the request over the supervisor channel, resolving the raw answer against the choices. */
 async function askSupervisor(supervisor, ctx, waitSignal) {
     const { opts, message, defaultValue, resolveRaw } = ctx;
     const spec = {
-        kind: opts.kind === "choice" ? "choice" : "input",
+        kind: opts.kind === "choice" ? "choice" : opts.kind === "multiline" ? "multiline" : "input",
         message,
         default: defaultValue,
         ...(opts.kind === "choice" ? { choices: asChoices(opts.choices) } : {}),
+        ...(opts.kind === "multiline" && opts.hint ? { hint: opts.hint } : {}),
     };
     const answer = await supervisor.request(spec, waitSignal);
     const resolved = resolveRaw(answer.value);
@@ -18,9 +59,44 @@ async function askSupervisor(supervisor, ctx, waitSignal) {
     return { value: resolved, via: answer.via ?? "input" };
 }
 /** Read the answer straight from the terminal (the bare, unsupervised path). */
-async function askTerminal(query, resolveRaw, defaultValue, waitSignal) {
+async function askTerminal(query, resolveRaw, defaultValue, waitSignal, multiline) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
+        if (multiline) {
+            process.stdout.write(query);
+            // Iterate the interface instead of calling `rl.question` per line. A paste arrives as a
+            // single chunk and readline emits every line in it synchronously, so a one-shot `question`
+            // takes the first line and the rest are emitted with no listener and lost — which would
+            // break the one case this kind exists for. The async iterator queues lines and applies
+            // backpressure, so a pasted blob and a typed one read the same.
+            const it = rl[Symbol.asyncIterator]();
+            // Nothing can abort a pending `it.next()`, so an abort (prompt timeout or run teardown)
+            // closes the interface, which ends the iteration. `waitSignal` then tells that apart from
+            // a genuinely closed stream below.
+            const onAbort = () => void rl.close();
+            if (waitSignal.aborted)
+                onAbort();
+            else
+                waitSignal.addEventListener("abort", onAbort, { once: true });
+            try {
+                const read = async () => {
+                    const { value, done } = await it.next();
+                    return done ? undefined : value; // done → end of input
+                };
+                const text = await readUntil(read, multiline.until);
+                // Giving up is not end-of-input. Propagate so the action's outer catch labels the answer
+                // `timeout` and falls back to the default, the same as the `input` and `choice` kinds —
+                // half a JSON blob is not a useful answer, so the partial text is dropped here.
+                if (waitSignal.aborted)
+                    throw new Error("prompt aborted");
+                if (text.trim() === "")
+                    return { value: defaultValue, via: "default" };
+                return { value: text, via: "input" };
+            }
+            finally {
+                waitSignal.removeEventListener("abort", onAbort);
+            }
+        }
         const raw = (await rl.question(query, { signal: waitSignal })).trim();
         if (raw === "")
             return { value: defaultValue, via: "default" };
@@ -35,10 +111,11 @@ async function askTerminal(query, resolveRaw, defaultValue, waitSignal) {
     }
 }
 /**
- * Asks the terminal a question — free-text **input** or a **choice** — and resolves
- * with the answer, which it also attaches as the handle (`prompt(...).ref` feeds
- * another action). A timeout (default 30s) falls back to the default so an
- * unattended run never blocks; teardown also unblocks a pending prompt.
+ * Asks the terminal a question — free-text **input**, a **choice**, or a **multiline**
+ * block (see {@link readUntil} for how it ends) — and resolves with the answer, which it
+ * also attaches as the handle (`prompt(...).ref` feeds another action). A timeout
+ * (default 30s) falls back to the default so an unattended run never blocks; teardown
+ * also unblocks a pending prompt.
  */
 export const prompt = action("prompt")
     .emits()
@@ -50,7 +127,13 @@ export const prompt = action("prompt")
     let query;
     let defaultValue;
     let resolveRaw;
-    if (opts.kind === "choice") {
+    if (opts.kind === "multiline") {
+        defaultValue = opts.default ?? "";
+        message = opts.message ?? "Input:";
+        query = opts.hint ? `${message}\n  ${opts.hint}\n> ` : `${message}\n> `;
+        resolveRaw = (raw) => raw;
+    }
+    else if (opts.kind === "choice") {
         const choices = asChoices(opts.choices);
         const { default: def } = opts;
         const picked = typeof def === "number"
@@ -83,6 +166,7 @@ export const prompt = action("prompt")
     const waitSignal = AbortSignal.any([signal, onTimeout.signal]);
     let value = defaultValue;
     let via = "default";
+    const multiline = opts.kind === "multiline" ? { until: opts.until ?? "json" } : undefined;
     const supervisor = activeSupervisor();
     try {
         // Supervised: hand off to whoever owns the terminal (Ink app / MCP client). Bare: read
@@ -90,7 +174,7 @@ export const prompt = action("prompt")
         // silent supervisor (or nobody) can't wedge the run.
         const outcome = supervisor
             ? await askSupervisor(supervisor, { opts, message, defaultValue, resolveRaw }, waitSignal)
-            : await askTerminal(query, resolveRaw, defaultValue, waitSignal);
+            : await askTerminal(query, resolveRaw, defaultValue, waitSignal, multiline);
         value = outcome.value;
         via = outcome.via;
     }

package/dist/cli/commands/help.js

@@ -13,12 +13,18 @@ export function helpText() {
         "  run [om]     run an om — interactive picker if no om is given, else by name or file path",
         "  ls           list the discovered oms and actions",
         "  check        typecheck the project (tsc --noEmit)",
+        "  skill        generate .claude/skills/omkit-runs/SKILL.md from what this project exposes",
+        "  mcp          serve this project over MCP on stdio (for Claude and other assistants)",
         "  init         scaffold a starter project (tsconfig.omkit.json + sample oms/ and actions/)",
         "  help         show this help",
         "",
         "Flags:",
         "  --tsconfig <path>   project config to scan (default: tsconfig.omkit.json)",
         "  --json              machine-readable output (ls)",
+        "  --describe          import the oms to show their summaries (ls) — slower, runs no workflow",
+        "  --check             report drift and exit non-zero instead of writing (skill)",
+        "  --out <path>        write somewhere else (skill)",
+        "  --root <path>       the project the skill describes, if the tsconfig sits below it (skill)",
         "  --inspect[=port]    run the om in a forked child with the Node inspector open (default port 9229)",
         "  -h, --help          show this help",
         "",

package/dist/cli/commands/init.js

@@ -16,7 +16,7 @@ const TSCONFIG = `{
 const DEV_OM = `import { om } from "omkit";
 import { command, healthcheck } from "omkit/actions";
 
-om("dev", async () => {
+om("dev").run(async () => {
   command("npm run dev", { cwd: "api" }).tag("api");
   const up = await healthcheck({ url: "http://localhost:3000" }).result;
   if (!up.ok) return;

package/dist/cli/commands/ls.d.ts

@@ -1,5 +1,12 @@
-import type { Registry } from "../../client/registry.ts";
+import type { RegistrationSet, Registry } from "../../client/registry.ts";
+export interface FormatOptions {
+    readonly json?: boolean;
+    /**
+     * What the oms and actions declare, from the discovery fork. Present only under
+     * `--describe`: reading it costs an import of every candidate file, which is why plain
+     * `ls` stays AST-only and prints exactly what it always did.
+     */
+    readonly registrations?: RegistrationSet;
+}
 /** Render a {@link Registry} for the terminal (plain text) or as JSON. */
-export declare function formatRegistry(registry: Registry, opts?: {
-    json?: boolean;
-}): string;
+export declare function formatRegistry(registry: Registry, opts?: FormatOptions): string;

package/dist/cli/commands/ls.js

@@ -2,24 +2,44 @@ import path from "node:path";
 /** Render a {@link Registry} for the terminal (plain text) or as JSON. */
 export function formatRegistry(registry, opts = {}) {
     if (opts.json)
-        return JSON.stringify(registry, null, 2);
-    const lines = [];
-    lines.push(`oms (${registry.oms.length})`);
-    for (const om of registry.oms) {
-        lines.push(`  ${om.name}  ${path.basename(om.file)}:${om.line}`);
-    }
-    lines.push("");
-    lines.push(`actions (${registry.actions.length})`);
-    for (const a of registry.actions) {
-        const tags = [a.publishesCapability ? "ref" : "", a.events ? "events" : ""].filter(Boolean);
-        const suffix = tags.length ? `  [${tags.join(", ")}]` : "";
-        lines.push(`  ${a.name}  ${path.basename(a.file)}${suffix}`);
-    }
+        return renderJson(registry, opts.registrations);
+    const declared = index(opts.registrations);
+    const lines = [
+        `oms (${registry.oms.length})`,
+        ...registry.oms.flatMap((om) => row(`${om.name}  ${path.basename(om.file)}:${om.line}`, [], declared?.get(key(om.name, om.file)))),
+        "",
+        `actions (${registry.actions.length})`,
+        ...registry.actions.flatMap((a) => row(`${a.name}  ${path.basename(a.file)}`, [a.publishesCapability ? "ref" : "", a.events ? "events" : ""], declared?.get(key(a.name, a.file)))),
+    ];
     if (registry.warnings.length) {
-        lines.push("");
-        lines.push(`warnings (${registry.warnings.length})`);
+        lines.push("", `warnings (${registry.warnings.length})`);
         for (const w of registry.warnings)
             lines.push(`  ${w}`);
     }
     return lines.join("\n");
 }
+/** One entry: its head line with any markers, plus an indented summary when one was declared. */
+function row(head, tags, meta) {
+    const all = [...tags, ...mcpTags(meta)].filter(Boolean);
+    const suffix = all.length ? `  [${all.join(", ")}]` : "";
+    return meta?.summary ? [`  ${head}${suffix}`, `    ${meta.summary}`] : [`  ${head}${suffix}`];
+}
+function renderJson(registry, registrations) {
+    return JSON.stringify(registrations ? { ...registry, ...registrations } : registry, null, 2);
+}
+/** Declarations keyed by name-in-file, so a name reused across files cannot cross over. */
+function index(set) {
+    if (!set)
+        return undefined;
+    const byKey = new Map();
+    for (const r of [...set.oms, ...set.actions])
+        byKey.set(key(r.name, r.file), r);
+    return byKey;
+}
+const key = (name, file) => `${name}\0${path.resolve(file)}`;
+/** `[mcp]` / `[mcp, long-lived]` — only meaningful once the fork has told us what is exposed. */
+function mcpTags(meta) {
+    if (!meta?.mcp)
+        return [];
+    return meta.mcp.mode === "long-lived" ? ["mcp", "long-lived"] : ["mcp"];
+}

package/dist/cli/commands/mcp.d.ts

@@ -0,0 +1,10 @@
+import type { OmkitClient } from "../../client/index.ts";
+/**
+ * The `mcp` command: serve this project over MCP on stdio, until the client hangs up.
+ *
+ * Deliberately silent. Every other command prints; this one must not, because its stdout
+ * is the protocol stream — a banner here reaches the client as a JSON parse error.
+ */
+export declare function mcpCommand(client: OmkitClient, opts: {
+    root: string;
+}): Promise<void>;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,13 @@
+import { startMcpServer } from "../../mcp/server.js";
+/**
+ * The `mcp` command: serve this project over MCP on stdio, until the client hangs up.
+ *
+ * Deliberately silent. Every other command prints; this one must not, because its stdout
+ * is the protocol stream — a banner here reaches the client as a JSON parse error.
+ */
+export async function mcpCommand(client, opts) {
+    await startMcpServer({ client, root: opts.root });
+    // `connect` resolves once the transport is bound; the transport keeps the process alive
+    // from here, so hold the command open rather than falling out of `main` and exiting.
+    await new Promise(() => { });
+}

package/dist/cli/commands/skill.d.ts

@@ -0,0 +1,17 @@
+import type { OmkitClient } from "../../client/index.ts";
+export interface SkillOptions {
+    /** Project root the skill is written relative to — the directory owning the tsconfig. */
+    readonly root: string;
+    /** Override the output path (still resolved against `root` when relative). */
+    readonly out?: string;
+    /** Compare hashes and exit non-zero on drift instead of writing. */
+    readonly check?: boolean;
+}
+/**
+ * The `skill` command: generate `.claude/skills/omkit-runs/SKILL.md` from what this project's
+ * oms and actions declare, so an assistant knows what is runnable before its first tool call.
+ *
+ * Generation runs no workflow. It uses the same `OMKIT_DISCOVER=1` fork the MCP server's
+ * `list_oms` uses, which returns from `launch()` before an execution tree exists.
+ */
+export declare function skillCommand(client: OmkitClient, opts: SkillOptions): Promise<void>;

package/dist/cli/commands/skill.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { buildSkillModel, readExisting, renderSkill, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH, } from "../../skill/index.js";
+const EMPTY_REGISTRY = { oms: [], actions: [], warnings: [] };
+/**
+ * The `skill` command: generate `.claude/skills/omkit-runs/SKILL.md` from what this project's
+ * oms and actions declare, so an assistant knows what is runnable before its first tool call.
+ *
+ * Generation runs no workflow. It uses the same `OMKIT_DISCOVER=1` fork the MCP server's
+ * `list_oms` uses, which returns from `launch()` before an execution tree exists.
+ */
+export async function skillCommand(client, opts) {
+    const file = path.resolve(opts.root, opts.out ?? SKILL_RELATIVE_PATH);
+    const registrations = await client.discoverRegistrations();
+    const model = buildSkillModel(registrations, registrations.registry ?? EMPTY_REGISTRY, opts.root);
+    const existing = readExisting(file);
+    if (opts.check) {
+        reportCheck(file, existing.hash, model.hash);
+        return;
+    }
+    // The description is the skill's loading trigger and is authored, so an existing one always
+    // wins; the fallback is only ever written into a file that does not exist yet.
+    const content = renderSkill(model, { description: existing.description ?? DEFAULT_DESCRIPTION });
+    writeSkill(file, content);
+    const total = model.oms.length + model.actions.length;
+    console.log(`wrote ${path.relative(opts.root, file) || file}`);
+    console.log(`  ${model.oms.length} om${model.oms.length === 1 ? "" : "s"}, ` +
+        `${model.actions.length} action${model.actions.length === 1 ? "" : "s"}  ` +
+        `[registry-hash: ${model.hash}]`);
+    if (total === 0) {
+        console.log("  nothing is exposed yet — mark an om or action with .mcp() to list it");
+    }
+    reportWarnings(registrations.warnings);
+}
+/**
+ * `--check` is for a hook or a CI step, so it says what changed and sets the exit code rather
+ * than writing. A file with no marker at all counts as drift: it was hand-written or predates
+ * the generator, and either way regenerating is the fix.
+ */
+function reportCheck(file, existing, fresh) {
+    if (existing === fresh) {
+        console.log(`up to date  [registry-hash: ${fresh}]`);
+        return;
+    }
+    const detail = existing === undefined ? "no registry-hash found" : `has ${existing}`;
+    console.error(`${file} is stale — ${detail}, project is ${fresh}`);
+    console.error("run `omkit skill` to regenerate");
+    process.exitCode = 1;
+}
+/** Discovery degrades to warnings rather than failing, so they have to reach the terminal. */
+function reportWarnings(warnings) {
+    if (warnings.length === 0)
+        return;
+    console.error(`\nwarnings (${warnings.length})`);
+    for (const w of warnings)
+        console.error(`  ${w}`);
+}

package/dist/cli/index.d.ts

@@ -7,6 +7,14 @@ export interface Cli {
     tsconfig: string;
     /** Set by `--help`/`-h` (the `help` command is carried on `command` instead). */
     help: boolean;
+    /** `ls --describe`: import the oms to read their summaries, instead of staying AST-only. */
+    describe: boolean;
+    /** `skill --check`: report drift and exit non-zero instead of writing. */
+    check: boolean;
+    /** `skill --out <path>`: write somewhere other than `.claude/skills/omkit-runs/SKILL.md`. */
+    out?: string;
+    /** `skill --root <path>`: the project the skill describes, when the tsconfig sits below it. */
+    root?: string;
     /** The Node inspector, if requested via `--inspect[=port]`. */
     inspect?: InspectOptions;
 }

package/dist/cli/index.js

@@ -33,6 +33,10 @@ export function parseCli(argv) {
             json: { type: "boolean", default: false },
             tsconfig: { type: "string", default: "tsconfig.omkit.json" },
             help: { type: "boolean", short: "h", default: false },
+            describe: { type: "boolean", default: false },
+            check: { type: "boolean", default: false },
+            out: { type: "string" },
+            root: { type: "string" },
         },
         allowPositionals: true,
     });
@@ -42,6 +46,10 @@ export function parseCli(argv) {
         json: Boolean(values.json),
         tsconfig: values.tsconfig,
         help: Boolean(values.help),
+        describe: Boolean(values.describe),
+        check: Boolean(values.check),
+        ...(values.out === undefined ? {} : { out: values.out }),
+        ...(values.root === undefined ? {} : { root: values.root }),
         inspect,
     };
 }
@@ -62,6 +70,62 @@ async function checkCommand(client) {
     await renderDiagnostics({ kind: n === 0 ? "ok" : "error", title, items }, n === 0 ? process.stdout : process.stderr);
     process.exitCode = n === 0 ? 0 : 1;
 }
+/**
+ * The `ls` command: print the discovered oms and actions.
+ *
+ * `--describe` is the only path here that imports user code. Without it `ls` is the AST scan
+ * and nothing else — the property that keeps it instant and safe to run in any repo, including
+ * one whose oms would start servers if they were evaluated.
+ */
+async function lsCommand(client, cli) {
+    const { formatRegistry } = await import("./commands/ls.js");
+    const { withSpinner } = await import("./ui/Report.js");
+    if (!cli.describe) {
+        const registry = await withSpinner("discovering…", () => client.discover());
+        console.log(formatRegistry(registry, { json: cli.json }));
+        return;
+    }
+    const registrations = await withSpinner("reading declarations…", () => client.discoverRegistrations());
+    const registry = registrations.registry ?? (await client.discover());
+    console.log(formatRegistry(registry, { json: cli.json, registrations }));
+}
+/** The `init` command: scaffold a starter project in the current directory. */
+async function initCommand() {
+    const { scaffold } = await import("./commands/init.js");
+    const { created, skipped } = scaffold(process.cwd());
+    for (const f of created)
+        console.log(`created ${f}`);
+    for (const f of skipped)
+        console.log(`exists, skipped ${f}`);
+}
+/** The `skill` command: generate the runnable-workflow map for an assistant to read. */
+async function generateSkill(client, cli) {
+    const { skillCommand } = await import("./commands/skill.js");
+    // The root decides two things at once — where `.claude/` goes, and what the recorded paths are
+    // relative to — so it is one setting, not two. It defaults to the tsconfig's directory (the
+    // common layout, where they are the same place); `--root` covers the repo that keeps its om
+    // project in a subfolder, where the reader's cwd is the repo and so the paths must be too.
+    const root = cli.root ? path.resolve(cli.root) : path.dirname(path.resolve(cli.tsconfig));
+    await skillCommand(client, { root, check: cli.check, ...(cli.out ? { out: cli.out } : {}) });
+}
+/**
+ * Every command, by name. A table rather than a chain of `if`s: each entry is one lazy import
+ * and one call, so adding a command cannot quietly grow the entry point's branching.
+ */
+const COMMANDS = {
+    init: () => initCommand(),
+    ls: (client, cli) => lsCommand(client, cli),
+    check: (client) => checkCommand(client),
+    mcp: async (client) => {
+        const { mcpCommand } = await import("./commands/mcp.js");
+        await mcpCommand(client, { root: process.cwd() });
+    },
+    skill: (client, cli) => generateSkill(client, cli),
+    run: async (client, cli) => {
+        const { runCommand } = await import("./commands/run.js");
+        await runCommand(client, { target: cli.target, inspect: cli.inspect });
+    },
+};
 /** The bin entry: route to a lazily-imported command; owns stdout and the exit code. */
 async function main() {
     const cli = parseCli(process.argv.slice(2));
@@ -71,37 +135,15 @@ async function main() {
         console.log(helpText());
         return;
     }
-    const inspect = cli.inspect;
-    const client = createOmkitClient({ tsconfig: cli.tsconfig, inspect });
-    if (cli.command === "init") {
-        const { scaffold } = await import("./commands/init.js");
-        const { created, skipped } = scaffold(process.cwd());
-        for (const f of created)
-            console.log(`created ${f}`);
-        for (const f of skipped)
-            console.log(`exists, skipped ${f}`);
-        return;
-    }
-    if (cli.command === "ls") {
-        const { formatRegistry } = await import("./commands/ls.js");
-        const { withSpinner } = await import("./ui/Report.js");
-        const registry = await withSpinner("discovering…", () => client.discover());
-        console.log(formatRegistry(registry, { json: cli.json }));
-        return;
-    }
-    if (cli.command === "check") {
-        await checkCommand(client);
-        return;
-    }
-    if (cli.command === "run") {
-        const { runCommand } = await import("./commands/run.js");
-        await runCommand(client, { target: cli.target, inspect: cli.inspect });
+    const handler = COMMANDS[cli.command];
+    if (!handler) {
+        const { helpText } = await import("./commands/help.js");
+        console.error(`unknown command "${cli.command}"\n`);
+        console.error(helpText());
+        process.exitCode = 1;
         return;
     }
-    const { helpText } = await import("./commands/help.js");
-    console.error(`unknown command "${cli.command}"\n`);
-    console.error(helpText());
-    process.exitCode = 1;
+    await handler(createOmkitClient({ tsconfig: cli.tsconfig, inspect: cli.inspect }), cli);
 }
 /**
  * True when this module is the process entry point — not when a test imports `parseCli`.