@pome-sh/cli 0.19.0 → 0.21.0

package/dist/src/cli/criterion-binding.js

@@ -1,111 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * F-1134 — does a `[code]` criterion bind to a check its twin declares?
- *
- * A criterion that binds nothing is not an error anywhere: the grader skips it
- * and the score is computed over the rest, so the denominator moves for a reason
- * nobody wrote down. Three doors already refuse one — `save_task` and
- * `validate_task` over the hosted MCP, and the corpus gate in CI — and a
- * local-only author authoring tasks in their own repo reaches none of them.
- * `pome` is meant to work offline, so a gap that only appears offline is a gap.
- *
- * OFFLINE BY CONSTRUCTION. Nothing here consults the cloud. Binding is a
- * question about the sentence and the CLI's own pinned declaration, and any
- * answer that needed the network would inherit F-1132's skew problem in the one
- * mode where this gap lives. The digest handshake in `checks-add.ts` remains the
- * place where the two pins are compared — that is a question about WRITING a
- * sentence, and it is a different question from whether one already binds.
- *
- * Resolution comes from `./checks.js` and nowhere else. That module is already a
- * deliberate SECOND resolution point (pome-cloud's registry is the first); a
- * third would be a third thing that can silently resolve nothing, which is
- * F-989's lesson.
- */
-import { checkNearMissPattern, checkPattern, templateSlots } from "@pome-sh/sdk/checks";
-import { readCodeCriteria } from "../task/parseTask.js";
-import { checksFor } from "./checks.js";
-export function bindCriterion(criterion) {
-    const declared = checksFor(criterion.twin);
-    if (declared.length === 0)
-        return { kind: "no-vocabulary" };
-    const text = criterion.text.trim();
-    // EVERY exact pattern first, across the whole twin, before any near-miss. A
-    // near-miss opens each slot to `.+?`, so one check's near-miss can swallow
-    // another's perfectly valid sentence; interleaving the two passes would report
-    // a criterion that grades fine as a corrupted instance of its neighbour.
-    for (const def of declared) {
-        if (checkPattern(def).test(text))
-            return { kind: "bound", checkId: def.id };
-    }
-    for (const def of declared) {
-        const near = text.match(checkNearMissPattern(def));
-        if (!near)
-            continue;
-        const offender = firstInvalidSlot(def, near);
-        // A near-miss whose every slot value is valid would have matched the exact
-        // pattern, unless the non-greedy split landed elsewhere than the typed one
-        // would. Keep looking rather than reporting a corruption we cannot name.
-        if (offender)
-            return { kind: "corrupted", checkId: def.id, ...offender };
-    }
-    return { kind: "unbound" };
-}
-/** Which slot the sentence filled with something its type rejects. Group `i + 1`
- *  is slot `i` — `defineCheck` asserts every slot pattern is group-free so those
- *  indices cannot shift, and the near-miss pattern's `.+?` is group-free too. */
-function firstInvalidSlot(def, match) {
-    const { params } = templateSlots(def.template);
-    for (const [index, name] of params.entries()) {
-        const type = def.params[name];
-        const value = match[index + 1];
-        if (!new RegExp(`^${type.pattern}$`).test(value)) {
-            return { slot: name, value, example: type.example };
-        }
-    }
-    return undefined;
-}
-/** Classify every `[code]` criterion in a task file. Three buckets, because the
- *  interesting one is the third and lumping the second into the first is how a
- *  tool ends up promising more than it checked. */
-export function auditCodeCriteria(markdown) {
-    const audit = { bound: 0, unanswerable: [], findings: [] };
-    for (const criterion of readCodeCriteria(markdown)) {
-        const binding = bindCriterion(criterion);
-        if (binding.kind === "bound")
-            audit.bound += 1;
-        else if (binding.kind === "no-vocabulary")
-            audit.unanswerable.push(criterion);
-        else
-            audit.findings.push({ criterion, binding });
-    }
-    return audit;
-}
-/** The author-facing report, one block per finding. Names the file so it stands
- *  on its own in a scrollback that already carries a write summary, and echoes
- *  each sentence verbatim so the author can find the line. */
-export function formatBindingReport(findings, file) {
-    const count = findings.length;
-    const blocks = findings.flatMap(({ criterion, binding }) => [
-        `    - ${criterion.marker} ${criterion.text}`,
-        ...(binding.kind === "unbound"
-            ? [
-                `      Binds nothing ${criterion.twin} declares, so the grader skips it and`,
-                `      the score is computed without it.`,
-            ]
-            : [
-                `      Says ${binding.checkId}, but \`${binding.slot}\` = ${JSON.stringify(binding.value)} is not a valid`,
-                `      value for that slot (e.g. ${binding.example}). It will be reported as`,
-                `      corrupted_check_instance:${binding.checkId}.`,
-            ]),
-        "",
-    ]);
-    const twins = [...new Set(findings.map((f) => f.criterion.twin))].sort();
-    return [
-        `⚠ ${file} — ${count} [code] ${count === 1 ? "criterion" : "criteria"} will not be graded:`,
-        "",
-        ...blocks,
-        `  Run ${twins.map((t) => `\`pome checks ${t}\``).join(", ")} to see the sentences that do bind,`,
-        `  then \`pome checks add\` to write one — pome renders the English, so a`,
-        `  criterion it wrote cannot fail to bind.`,
-    ].join("\n");
-}

package/dist/src/cli/default-task.d.ts

@@ -1,38 +0,0 @@
-/** Design default k for "run yours" (moment 05: "Their agent · k=5"). */
-export declare const DEFAULT_TASK_TRIALS = 5;
-export declare const DEFAULT_TASK_DIR = "tasks";
-export declare const DEFAULT_TASK_FILENAME = "first-run-demo.md";
-export interface DefaultTaskResolution {
-    /** Absolute path of the task markdown to run. */
-    path: string;
-    /** Project-relative path, for terminal copy. */
-    relativePath: string;
-    /** True when this call dropped the copy (first use). */
-    copied: boolean;
-    /** False when the packaged md's Config fence couldn't be located, so the
-     *  k=5 default could not be pinned into the copy. */
-    trialsApplied: boolean;
-}
-/** Pin `runs: N` inside the ## Config yaml fence. No-op (applied=true) when
- *  the fence already sets runs; applied=false when no fence exists. */
-export declare function withDefaultTrials(source: string, runs?: number): {
-    content: string;
-    applied: boolean;
-};
-/** Swap the packaged maintainer preamble (the CANONICAL/lockstep warning —
- *  true of the packaged md, wrong and confusing in the user's copy) for the
- *  user-facing comment. When no preamble exists, insert after the H1. */
-export declare function withUserCopyComment(source: string): string;
-/**
- * Resolve the bare-`pome run` default task, dropping the user copy on first
- * use. Never clobbers an existing tasks/first-run-demo.md — that file is
- * the user's (possibly edited) task from a prior bare run.
- */
-export declare function ensureDefaultTask(cwd?: string): Promise<DefaultTaskResolution>;
-export declare function copyAnnounceLine(res: DefaultTaskResolution): string;
-/** Printed when the Config fence couldn't be found in the packaged md, so
- *  the copy runs k=1 unless the user passes -n (honest, never silent). */
-export declare function trialsPinFallbackLine(): string;
-/** Moment-05 frame ("that was ours, run yours"), printed once the doctor
- *  gate and credential resolution have passed, ahead of the run output. */
-export declare function runYoursFrameLines(): string[];

package/dist/src/cli/default-task.js

@@ -1,141 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// FDRS-645 — "run yours": bare `pome run` (no path) defaults to the demo
-// task, closing the demo → run-yours seam (north-star moment 05: their
-// agent, k=5, the same task they just watched the demo agent attempt).
-//
-// The default is a USER-VISIBLE COPY at tasks/first-run-demo.md, dropped
-// on first use from the packaged demo task (src/demo/first-run-demo.md plus
-// its compiled seed sidecar — the client parser requires the sidecar when a
-// prose ## Seed State section is present). The copy — never the canonical
-// packaged md — gains `runs: 5`, so the design's k=5 default rides the
-// existing scenario-config `runs` mechanism (an explicit -n still wins) and
-// the packaged md stays byte-identical to the server-owned judge definition
-// regenerated from it (pome-cloud#209 lockstep).
-//
-// The packaged md's maintainer comment (the CANONICAL/lockstep warning) is
-// swapped for a user-facing one in the copy: the copy is the user's file —
-// authenticated runs are judged against the criteria declared in it.
-import { constants, existsSync, statSync } from "node:fs";
-import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { DEMO_TASK_NAME, demoTaskPath } from "../demo/task.js";
-import { HostedUsageError } from "../hosted/errors.js";
-/** Design default k for "run yours" (moment 05: "Their agent · k=5"). */
-export const DEFAULT_TASK_TRIALS = 5;
-export const DEFAULT_TASK_DIR = "tasks";
-export const DEFAULT_TASK_FILENAME = `${DEMO_TASK_NAME}.md`;
-const USER_COPY_COMMENT = `<!--
-Copied into your project by \`pome run\` — the "run yours" default: the same
-task the demo agent just attempted, now for your agent. This copy is yours.
-Edit the prompt/criteria freely (your runs are judged against the criteria
-declared in this file), or delete it and the next bare \`pome run\` re-copies
-the original. Config pins runs: ${DEFAULT_TASK_TRIALS} — an explicit -n overrides it.
--->`;
-/** The ## Config section's fenced yaml block: (heading + everything up to
- *  and including the opening fence line)(fence body)(closing fence). The
- *  gap between heading and fence never crosses into another ## section. */
-const CONFIG_FENCE_RE = /(##[ \t]*config[^\n]*\n(?:(?!\n##[ \t])[\s\S])*?```(?:yaml)?[ \t]*\n)([\s\S]*?)(```)/i;
-/** Pin `runs: N` inside the ## Config yaml fence. No-op (applied=true) when
- *  the fence already sets runs; applied=false when no fence exists. */
-export function withDefaultTrials(source, runs = DEFAULT_TASK_TRIALS) {
-    const match = CONFIG_FENCE_RE.exec(source);
-    if (!match)
-        return { content: source, applied: false };
-    const [whole, head, body, tail] = match;
-    if (/^[ \t]*runs[ \t]*:/m.test(body))
-        return { content: source, applied: true };
-    const glue = body === "" || body.endsWith("\n") ? "" : "\n";
-    const content = source.slice(0, match.index) +
-        head +
-        body +
-        `${glue}runs: ${runs}\n` +
-        tail +
-        source.slice(match.index + whole.length);
-    return { content, applied: true };
-}
-/** Swap the packaged maintainer preamble (the CANONICAL/lockstep warning —
- *  true of the packaged md, wrong and confusing in the user's copy) for the
- *  user-facing comment. When no preamble exists, insert after the H1. */
-export function withUserCopyComment(source) {
-    const commentRe = /<!--[\s\S]*?-->/;
-    const comment = commentRe.exec(source);
-    const firstSection = source.search(/^##[ \t]/m);
-    if (comment && (firstSection === -1 || comment.index < firstSection)) {
-        return (source.slice(0, comment.index) +
-            USER_COPY_COMMENT +
-            source.slice(comment.index + comment[0].length));
-    }
-    const h1 = /^#[ \t].+$/m.exec(source);
-    if (!h1)
-        return `${USER_COPY_COMMENT}\n\n${source}`;
-    const insertAt = h1.index + h1[0].length;
-    return `${source.slice(0, insertAt)}\n\n${USER_COPY_COMMENT}${source.slice(insertAt)}`;
-}
-/**
- * Resolve the bare-`pome run` default task, dropping the user copy on first
- * use. Never clobbers an existing tasks/first-run-demo.md — that file is
- * the user's (possibly edited) task from a prior bare run.
- */
-export async function ensureDefaultTask(cwd = process.cwd()) {
-    const relativePath = join(DEFAULT_TASK_DIR, DEFAULT_TASK_FILENAME);
-    const target = join(cwd, relativePath);
-    if (existsSync(target)) {
-        return { path: target, relativePath, copied: false, trialsApplied: true };
-    }
-    // A `scenarios` path that exists as a FILE would make the mkdir below
-    // throw a raw EEXIST (exit 2). Name the actual problem as a usage error.
-    const dir = join(cwd, DEFAULT_TASK_DIR);
-    if (existsSync(dir) && !statSync(dir).isDirectory()) {
-        throw new HostedUsageError(`\`${DEFAULT_TASK_DIR}\` exists as a file in this project — the bare \`pome run\` default drops its task into a ${DEFAULT_TASK_DIR}/ directory. Move the file aside, or pass a task path explicitly.`);
-    }
-    const packagedMd = demoTaskPath();
-    const packagedSeed = packagedMd.replace(/\.md$/, ".seed.json");
-    if (!existsSync(packagedSeed)) {
-        throw new Error(`Packaged demo seed not found at ${packagedSeed}. This is a packaging ` +
-            "bug — scripts/copy-prompts.mjs ships src/demo/ (task md + seed " +
-            "sidecar) into dist/.");
-    }
-    const raw = await readFile(packagedMd, "utf8");
-    const pinned = withDefaultTrials(withUserCopyComment(raw));
-    await mkdir(dir, { recursive: true });
-    // Seed first, md last: the md's presence is the commit point (the parser
-    // hard-requires the sidecar once the md's prose ## Seed State is seen), so
-    // a crash between the two writes never strands a half-usable default.
-    // COPYFILE_EXCL: NO file under tasks/ is ever overwritten — a user who
-    // deleted only the md but kept an edited seed keeps their seed.
-    try {
-        await copyFile(packagedSeed, target.replace(/\.md$/, ".seed.json"), constants.COPYFILE_EXCL);
-    }
-    catch (err) {
-        if (err.code !== "EEXIST")
-            throw err;
-    }
-    try {
-        // "wx": never overwrite — if a concurrent run raced the copy in, theirs
-        // wins and this invocation just runs it.
-        await writeFile(target, pinned.content, { encoding: "utf8", flag: "wx" });
-    }
-    catch (err) {
-        if (err.code === "EEXIST") {
-            return { path: target, relativePath, copied: false, trialsApplied: true };
-        }
-        throw err;
-    }
-    return { path: target, relativePath, copied: true, trialsApplied: pinned.applied };
-}
-export function copyAnnounceLine(res) {
-    return `copied the demo task into ${res.relativePath} — this copy is yours to edit`;
-}
-/** Printed when the Config fence couldn't be found in the packaged md, so
- *  the copy runs k=1 unless the user passes -n (honest, never silent). */
-export function trialsPinFallbackLine() {
-    return `couldn't pin runs: ${DEFAULT_TASK_TRIALS} in the copy — pass -n ${DEFAULT_TASK_TRIALS} for the design default`;
-}
-/** Moment-05 frame ("that was ours, run yours"), printed once the doctor
- *  gate and credential resolution have passed, ahead of the run output. */
-export function runYoursFrameLines() {
-    return [
-        `run yours · ${DEMO_TASK_NAME}`,
-        "that was ours — now it's your agent on the same task the demo just ran.",
-    ];
-}

package/dist/src/cli/defaults.d.ts

@@ -1,4 +0,0 @@
-/** Production defaults (override with env / CLI flags at call sites). */
-export declare const DEFAULT_CONTROL_PLANE_URL = "https://api.pome.sh";
-export declare const DEFAULT_DASHBOARD_URL = "https://app.pome.sh";
-export declare const DEFAULT_DOCS_SITE_ORIGIN = "https://docs.pome.sh";

package/dist/src/cli/defaults.js

@@ -1,5 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/** Production defaults (override with env / CLI flags at call sites). */
-export const DEFAULT_CONTROL_PLANE_URL = "https://api.pome.sh";
-export const DEFAULT_DASHBOARD_URL = "https://app.pome.sh";
-export const DEFAULT_DOCS_SITE_ORIGIN = "https://docs.pome.sh";

package/dist/src/cli/docs-topics.d.ts

@@ -1,13 +0,0 @@
-/**
- * Static index of public Mintlify pages on docs.pome.sh — avoids scraping HTML.
- * The authored docs live in the `pome` repo and publish through Mintlify; this
- * package keeps only topic metadata for URL navigation.
- */
-export interface DocsTopic {
-    id: string;
-    title: string;
-    /** Path on the docs site, e.g. /getting-started */
-    path: string;
-    keywords: string[];
-}
-export declare const DOCS_TOPICS: DocsTopic[];

package/dist/src/cli/docs-topics.js

@@ -1,157 +0,0 @@
-export const DOCS_TOPICS = [
-    {
-        id: "pome",
-        title: "Pome",
-        path: "/introduction",
-        keywords: ["overview", "what is pome", "platform", "agents"],
-    },
-    {
-        id: "getting-started",
-        title: "Quickstart",
-        path: "/getting-started",
-        keywords: ["install", "quickstart", "setup", "begin"],
-    },
-    {
-        id: "existing-agent",
-        title: "Bring your own agent",
-        path: "/existing-agent",
-        keywords: [
-            "existing agent",
-            "own agent",
-            "already have an agent",
-            "bring your own",
-            "register",
-            "pome.json",
-            "connect",
-            // Migrated from the retired skills-setup topic (F-893): wiring your own
-            // agent is now the "bring your own agent" path. ("pome-setup" / "setup"
-            // already resolve to getting-started via its "setup" keyword.)
-            "wire",
-        ],
-    },
-    {
-        id: "how-pome-works",
-        title: "How Pome works",
-        path: "/docs/how-pome-works",
-        keywords: ["twins", "scenarios", "runs", "scoring", "artifacts", "loop"],
-    },
-    // F-889 dropped the Gen-1 /setup and /test-with-pome skill pages from the
-    // docs nav; F-893 retired the CLI commands that pointed at them. The two
-    // topic entries are gone, but their still-live keywords are MIGRATED onto the
-    // surviving replacement topics so `pome docs <kw>` keeps routing:
-    //   wire → existing-agent;  test-with-pome / pome-test → cli-run;
-    //   eval → cli (the CLI reference index — no dedicated eval page exists).
-    //   (setup / pome-setup / register / run scenarios / /setup all already
-    //   resolve via existing substrings — see the tests.)
-    {
-        id: "dashboard",
-        title: "Pome Dashboard",
-        path: "/docs/dashboard",
-        keywords: ["runs", "agents", "clones", "judge", "web"],
-    },
-    {
-        id: "twins",
-        title: "Twins overview",
-        path: "/docs/twins/index",
-        keywords: ["sandbox", "digital twin", "hosted"],
-    },
-    {
-        id: "github",
-        title: "GitHub twin",
-        path: "/docs/twins/github",
-        keywords: ["git", "repo", "issues", "mcp", "scenarios"],
-    },
-    {
-        id: "stripe",
-        title: "Stripe twin",
-        path: "/docs/twins/stripe",
-        keywords: ["payments", "x402", "refund", "payment intent", "stripe"],
-    },
-    {
-        id: "slack",
-        title: "Slack twin",
-        path: "/docs/twins/slack",
-        keywords: ["messaging", "channels", "workspace", "slack", "exfiltration"],
-    },
-    {
-        id: "gmail",
-        title: "Gmail twin",
-        path: "/docs/twins/gmail",
-        keywords: ["email", "inbox", "drafts", "labels", "gmail", "mcp"],
-    },
-    {
-        id: "cli",
-        title: "Command Line Interface",
-        path: "/docs/cli",
-        // "eval" migrated from the retired skills-test topic (F-893): there is no
-        // dedicated `pome eval` docs page, and it is a distinct workflow from
-        // `pome inspect`, so it routes to the CLI reference index that documents
-        // every command rather than to a sibling command's page.
-        keywords: ["commands", "flags", "pome run", "reference", "eval"],
-    },
-    {
-        id: "cli-run",
-        title: "pome run",
-        path: "/docs/cli/run",
-        keywords: [
-            "run",
-            "scenario",
-            "agent",
-            "flags",
-            "artifacts",
-            "default",
-            "demo task",
-            "run yours",
-            // Migrated from the retired skills-test topic (F-893): running tasks is
-            // how you test an agent with pome.
-            "test-with-pome",
-            "pome-test",
-        ],
-    },
-    {
-        id: "cli-session",
-        title: "pome session",
-        path: "/docs/cli/session",
-        keywords: ["session", "hosted", "sandbox", "twin"],
-    },
-    {
-        id: "cli-tasks",
-        title: "pome tasks",
-        // F-912 — the M4 docs door renamed the docs.pome.sh page from
-        // /docs/cli/scenarios to /docs/cli/tasks (a redirect keeps the old URL
-        // alive), so `path` now points at the new route. The "scenarios" keyword
-        // stays so `pome docs scenarios` still resolves to this topic.
-        path: "/docs/cli/tasks",
-        keywords: ["tasks", "scenarios", "catalog", "copy", "library", "twin"],
-    },
-    {
-        id: "cli-compile-seeds",
-        title: "pome compile-seeds",
-        path: "/docs/cli/compile-seeds",
-        keywords: ["compile-seeds", "seed", "sidecar", "compiler", "anthropic"],
-    },
-    {
-        id: "cli-inspect",
-        title: "pome inspect",
-        path: "/docs/cli/inspect",
-        keywords: ["inspect", "score", "trace", "artifacts", "verdicts"],
-    },
-    {
-        id: "cli-init",
-        title: "pome init",
-        path: "/docs/cli/init",
-        keywords: ["init", "scaffold", "pome.json", "manifest", "project"],
-    },
-    {
-        id: "troubleshooting",
-        title: "Troubleshooting",
-        path: "/docs/troubleshooting",
-        keywords: ["errors", "help", "fix", "debug"],
-    },
-    {
-        id: "changelog",
-        title: "Changelog",
-        path: "/changelog",
-        keywords: ["release", "version", "news"],
-    },
-];

package/dist/src/cli/docs.d.ts

@@ -1,7 +0,0 @@
-import { type DocsTopic } from "./docs-topics.js";
-export declare function findTopic(raw: string, topics: DocsTopic[]): DocsTopic | null;
-export declare function suggestTopics(raw: string, topics: DocsTopic[]): string;
-export declare function runDocsCommand(topicArg: string | undefined, opts: {
-    site?: string;
-    urlOnly?: boolean;
-}): Promise<void>;

package/dist/src/cli/docs.js

@@ -1,178 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * `pome docs` — topic-first links to canonical documentation.
- *
- * - `pome --help` / `pome help` — Commander-generated flag + subcommand reference (terse).
- * - `pome docs [topic]` — stable docs.pome.sh URLs for narrative docs.
- * - `pome <cmd> --help` — per-command options.
- */
-import { createInterface } from "node:readline";
-import { DEFAULT_DOCS_SITE_ORIGIN } from "./defaults.js";
-import { DOCS_TOPICS } from "./docs-topics.js";
-function useColor() {
-    return Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
-}
-function dim(s) {
-    return useColor() ? `\x1b[2m${s}\x1b[0m` : s;
-}
-function bold(s) {
-    return useColor() ? `\x1b[1m${s}\x1b[0m` : s;
-}
-function wrapLine(text, width) {
-    if (text.length <= width)
-        return [text];
-    const words = text.split(/\s+/);
-    const lines = [];
-    let cur = "";
-    for (const w of words) {
-        const next = cur.length === 0 ? w : `${cur} ${w}`;
-        if (next.length > width) {
-            if (cur.length > 0)
-                lines.push(cur);
-            cur = w;
-        }
-        else {
-            cur = next;
-        }
-    }
-    if (cur.length > 0)
-        lines.push(cur);
-    return lines;
-}
-export function findTopic(raw, topics) {
-    const q = raw.trim().toLowerCase();
-    if (!q)
-        return null;
-    const byId = topics.find((t) => t.id === q);
-    if (byId)
-        return byId;
-    const byKw = topics.find((t) => t.keywords.some((k) => k.toLowerCase() === q || q.includes(k.toLowerCase())));
-    if (byKw)
-        return byKw;
-    const fuzzy = topics.find((t) => t.title.toLowerCase().includes(q) ||
-        t.id.includes(q) ||
-        t.path.toLowerCase().includes(q));
-    return fuzzy ?? null;
-}
-export function suggestTopics(raw, topics) {
-    const q = raw.trim().toLowerCase();
-    const scored = topics
-        .map((t) => {
-        let score = 0;
-        if (t.id.startsWith(q))
-            score += 3;
-        for (const k of t.keywords) {
-            if (k.startsWith(q))
-                score += 2;
-            if (k.includes(q))
-                score += 1;
-        }
-        return { t, score };
-    })
-        .filter((x) => x.score > 0)
-        .sort((a, b) => b.score - a.score)
-        .slice(0, 5)
-        .map((x) => x.t.id);
-    if (scored.length === 0) {
-        return `Unknown docs topic "${raw}". Run \`pome docs\` for the index.`;
-    }
-    return `Unknown docs topic "${raw}". Did you mean: ${scored.join(", ")}?`;
-}
-function topicMatchesFilter(t, filter) {
-    if (!filter)
-        return true;
-    const f = filter.toLowerCase();
-    return (t.id.includes(f) ||
-        t.title.toLowerCase().includes(f) ||
-        t.keywords.some((k) => k.toLowerCase().includes(f)) ||
-        t.path.toLowerCase().includes(f));
-}
-async function promptLine(rl, q) {
-    return await new Promise((resolve) => rl.question(q, resolve));
-}
-function printTopicUrl(topic, site) {
-    console.log(`${site}${topic.path}`);
-}
-export async function runDocsCommand(topicArg, opts) {
-    const site = (opts.site ?? DEFAULT_DOCS_SITE_ORIGIN).replace(/\/$/, "");
-    const width = Math.max(40, Math.min(100, process.stdout.columns ?? 80));
-    const ttyIn = process.stdin.isTTY === true;
-    const ttyOut = process.stdout.isTTY === true;
-    const interactive = ttyIn && ttyOut && !topicArg && !opts.urlOnly;
-    if (topicArg) {
-        const match = findTopic(topicArg, DOCS_TOPICS);
-        if (!match) {
-            console.error(suggestTopics(topicArg, DOCS_TOPICS));
-            process.exitCode = 2;
-            return;
-        }
-        printTopicUrl(match, site);
-        return;
-    }
-    if (!ttyOut || opts.urlOnly) {
-        for (const t of DOCS_TOPICS) {
-            console.log(`${t.id}\t${site}${t.path}`);
-        }
-        return;
-    }
-    console.log(bold("Pome docs"));
-    console.log(dim("URL navigator for docs.pome.sh · `pome --help` lists commands; docs.pome.sh hosts narrative docs."));
-    console.log(dim("Example: `pome docs getting-started` prints the canonical quickstart URL."));
-    console.log("");
-    if (!interactive) {
-        let i = 1;
-        for (const t of DOCS_TOPICS) {
-            const title = `${i}. ${t.title} ${dim(`(${t.id})`)}`;
-            console.log(title);
-            for (const line of wrapLine(`${site}${t.path}`, width - 2)) {
-                console.log(`   ${dim(line)}`);
-            }
-            console.log("");
-            i += 1;
-        }
-        return;
-    }
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let filter = "";
-    try {
-        while (true) {
-            const list = DOCS_TOPICS.filter((t) => topicMatchesFilter(t, filter));
-            console.log(filter
-                ? dim(`Filter: "${filter}" (${list.length} topics) — Enter clears filter`)
-                : dim("Type to filter topics (substring), a number to open, topic id, or Enter to clear filter / exit"));
-            list.forEach((t, idx) => {
-                console.log(`${dim(`${idx + 1}.`)} ${t.title} ${dim(`(${t.id})`)}`);
-            });
-            if (list.length === 0) {
-                console.log(dim("(no matches — edit filter)"));
-            }
-            const answer = (await promptLine(rl, dim("› "))).trim();
-            if (answer === "") {
-                if (filter) {
-                    filter = "";
-                    continue;
-                }
-                return;
-            }
-            const direct = findTopic(answer, DOCS_TOPICS);
-            if (direct && (list.includes(direct) || filter === "")) {
-                printTopicUrl(direct, site);
-                filter = "";
-                continue;
-            }
-            const n = Number.parseInt(answer, 10);
-            if (Number.isFinite(n) &&
-                n >= 1 &&
-                n <= list.length &&
-                answer === String(n)) {
-                printTopicUrl(list[n - 1], site);
-                filter = "";
-                continue;
-            }
-            filter = answer;
-        }
-    }
-    finally {
-        rl.close();
-    }
-}