@litfamily/litopencode 1.0.0

package/dist/cli/loop.d.ts

@@ -0,0 +1,3 @@
+import type { CliResult, LoopArgs } from "./types.ts";
+import type { LoopCommand } from "./args.ts";
+export declare function runLoopCommand(command: LoopCommand, loop: LoopArgs): Promise<CliResult>;

package/dist/cli/loop.js

@@ -0,0 +1,135 @@
+import { completeGoals, createGoals, EvidenceLedgerError, evaluateGoalGate, readEvidenceLedgerStatus, recordCheckpoint, recordEvidence, recordReviewBlocker, recordSteering, resolveReviewBlocker } from "../ledger.js";
+import { createRuntimePaths } from "../state.js";
+import { readObservations, recordObservation, SkillObserverError } from "../skill-observer.js";
+// Exit codes are distinct so a caller can tell a refusal from a usage error: 2 is a malformed
+// invocation, 3 is a deliberate refusal, 1 is a gate that did not pass.
+const usageExit = 2;
+const refusedExit = 3;
+const gateExit = 1;
+function requireOption(value, option) {
+    if (value === undefined || value.trim() === "")
+        throw new UsageError(`${option} is required`);
+    return value;
+}
+class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}
+function ok(loop, payload, text) {
+    return { exitCode: 0, stdout: loop.json ? `${JSON.stringify(payload, null, 2)}` : text };
+}
+function describeGoal(goal) {
+    const gate = evaluateGoalGate(goal);
+    const lines = [
+        `${goal.id} [${goal.status}] ${goal.title || goal.objective}`,
+        `  session: ${goal.sessionId}`,
+        `  gate: ${gate.passed ? "PASSED" : "NOT PASSED"}`
+    ];
+    for (const criterion of goal.criteria) {
+        const kinds = criterion.evidence.map((entry) => entry.kind).join(", ") || "no evidence";
+        lines.push(`  ${criterion.id} [${criterion.status}] ${criterion.scenario} (${kinds})`);
+    }
+    for (const blocker of goal.reviewBlockers) {
+        lines.push(`  ${blocker.id} [${blocker.resolved ? "resolved" : "open"}] ${blocker.detail}`);
+    }
+    if (!gate.passed)
+        for (const reason of gate.reasons)
+            lines.push(`  - ${reason}`);
+    return lines.join("\n");
+}
+export async function runLoopCommand(command, loop) {
+    const root = loop.projectRoot;
+    try {
+        if (command === "create-goals") {
+            const goal = await createGoals(root, {
+                sessionId: requireOption(loop.sessionId, "--session-id"),
+                objective: requireOption(loop.objective, "--objective"),
+                title: loop.title,
+                criteria: loop.criteria,
+                force: loop.force
+            });
+            const paths = createRuntimePaths(root);
+            return ok(loop, { created: true, goal }, `created ${goal.id} for session ${goal.sessionId} with ${goal.criteria.length} criteria\n` +
+                `  state: ${paths.goalsFile}\n  brief: ${paths.briefFile}\n  ledger: ${paths.ledgerFile}`);
+        }
+        if (command === "status") {
+            const status = await readEvidenceLedgerStatus(root);
+            if (status.goals.length === 0) {
+                return ok(loop, { activeGoalId: "", goals: [] }, "no goals recorded; run create-goals to open one");
+            }
+            return ok(loop, status, status.goals.map(describeGoal).join("\n"));
+        }
+        if (command === "record-observation") {
+            const record = recordObservation(root, {
+                signal: requireOption(loop.signal, "--signal"),
+                skillId: requireOption(loop.skillId, "--skill-id"),
+                observed: requireOption(loop.observed, "--observed"),
+                proposal: requireOption(loop.proposal, "--proposal")
+            });
+            return ok(loop, { recorded: true, observation: record }, `recorded a ${record.signal} observation on ${record.skillId} as an unapplied proposal`);
+        }
+        if (command === "list-observations") {
+            const records = readObservations(root);
+            return ok(loop, { observations: records }, records.length === 0
+                ? "no observations recorded"
+                : records.map((record) => `${record.signal} ${record.skillId}: ${record.proposal}`).join("\n"));
+        }
+        if (command === "record-evidence") {
+            const criterion = await recordEvidence(root, {
+                criterionId: requireOption(loop.criterionId, "--criterion-id"),
+                kind: requireOption(loop.kind, "--kind"),
+                ref: requireOption(loop.ref, "--ref"),
+                detail: loop.detail,
+                status: loop.status
+            });
+            return ok(loop, { recorded: true, criterion }, `recorded ${criterion.evidence[criterion.evidence.length - 1]?.kind} evidence on ${criterion.id} ` +
+                `(status ${criterion.status}, ${criterion.evidence.length} entries retained)`);
+        }
+        if (command === "checkpoint") {
+            const checkpoint = await recordCheckpoint(root, {
+                summary: requireOption(loop.summary, "--summary"),
+                activeCriterion: loop.criterionId
+            });
+            return ok(loop, { recorded: true, checkpoint }, `recorded ${checkpoint.id}${checkpoint.activeCriterion === "" ? "" : ` on ${checkpoint.activeCriterion}`}: ${checkpoint.summary}`);
+        }
+        if (command === "steer") {
+            const steering = await recordSteering(root, {
+                directive: requireOption(loop.directive, "--directive"),
+                kind: loop.kind
+            });
+            const text = steering.criterionId === undefined
+                ? `recorded ${steering.id} (${steering.kind}): ${steering.directive}`
+                : `recorded ${steering.id} (${steering.kind}); added pending ${steering.criterionId}: ${steering.directive}`;
+            return ok(loop, { recorded: true, steering }, text);
+        }
+        if (command === "record-review-blockers") {
+            const blocker = loop.resolve === undefined
+                ? await recordReviewBlocker(root, {
+                    detail: requireOption(loop.detail, "--detail"),
+                    needsUserDecision: loop.needsUserDecision
+                })
+                : await resolveReviewBlocker(root, { blockerId: loop.resolve });
+            const status = await readEvidenceLedgerStatus(root);
+            const goalStatus = status.goals.find((goal) => goal.id === status.activeGoalId)?.status ?? "unknown";
+            return ok(loop, { recorded: true, blocker, goalStatus }, `recorded ${blocker.id}; goal status is now ${goalStatus}`);
+        }
+        const result = await completeGoals(root);
+        if (!result.completed) {
+            const text = [`BLOCKED: ${result.goalId} did not pass the completion gate.`, ...result.reasons.map((reason) => `  - ${reason}`)].join("\n");
+            return { exitCode: gateExit, stdout: loop.json ? JSON.stringify(result, null, 2) : undefined, stderr: loop.json ? undefined : text };
+        }
+        return ok(loop, result, `completed ${result.goalId}`);
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return { exitCode: usageExit, stderr: error.message };
+        if (error instanceof SkillObserverError && error.code === "OBSERVER_SECRET_REFUSED") {
+            return { exitCode: refusedExit, stderr: `REFUSED (BLOCKED_OBSERVER_SECRET): ${error.message}` };
+        }
+        if (error instanceof EvidenceLedgerError)
+            return { exitCode: refusedExit, stderr: `REFUSED (${error.code}): ${error.message}` };
+        throw error;
+    }
+}

package/dist/cli/lsp-capability.d.ts

@@ -0,0 +1,17 @@
+export type LspServerReport = {
+    readonly id: string;
+    readonly command: string;
+    readonly extensions: readonly string[];
+    readonly disabled: boolean;
+};
+export type LspCapabilityReport = {
+    readonly declared: boolean;
+    readonly servers: readonly LspServerReport[];
+    readonly servedExtensions: readonly string[];
+    readonly disabledServers: readonly string[];
+    readonly malformed: readonly string[];
+    readonly verdict: "declared" | "none-declared" | "unknown";
+    readonly note: string;
+};
+export declare function inspectLspCapability(hostConfig: Record<string, unknown> | null): LspCapabilityReport;
+export declare function servesExtension(report: LspCapabilityReport, extension: string): boolean;

package/dist/cli/lsp-capability.js

@@ -0,0 +1,92 @@
+// Reports what language-server coverage the OpenCode host actually declares.
+//
+// LitOpenCode bundles no language server and starts no daemon. The `lsp` and `lsp-setup` skills both
+// depend on one question being answerable before anything else: does a server exist for the file
+// type in front of me? Without this check the answer is a guess, and the failure mode the two skills
+// exist to prevent -- reporting "no errors" from an environment where nothing inspected the file --
+// is exactly what a guess produces.
+//
+// This reads the host's declaration. It never starts a server, never installs one, and never writes
+// configuration.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readCommand(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && value.length > 0 && typeof value[0] === "string")
+        return value.join(" ");
+    return "";
+}
+// Two spellings exist across the family's config dialects: an `extensions` array and an
+// `extensionToLanguage` map. Both are read, because a host that uses either is still serving.
+function readExtensions(entry) {
+    const collected = [];
+    const extensions = entry["extensions"];
+    if (Array.isArray(extensions)) {
+        for (const extension of extensions)
+            if (typeof extension === "string")
+                collected.push(extension);
+    }
+    const map = entry["extensionToLanguage"];
+    if (isRecord(map))
+        collected.push(...Object.keys(map));
+    return [...new Set(collected.map((extension) => (extension.startsWith(".") ? extension : `.${extension}`)))].sort();
+}
+export function inspectLspCapability(hostConfig) {
+    if (hostConfig === null) {
+        return {
+            declared: false,
+            servers: [],
+            servedExtensions: [],
+            disabledServers: [],
+            malformed: [],
+            verdict: "unknown",
+            note: "No readable OpenCode config, so language-server coverage could not be determined. Treat an empty diagnostic result as no evidence rather than a clean result."
+        };
+    }
+    const lsp = hostConfig["lsp"];
+    if (!isRecord(lsp)) {
+        return {
+            declared: false,
+            servers: [],
+            servedExtensions: [],
+            disabledServers: [],
+            malformed: [],
+            verdict: "none-declared",
+            note: "The OpenCode config declares no lsp block. The host may still serve some languages natively; confirm before reporting diagnostics as clean, and use the lsp-setup skill for an unserved file type."
+        };
+    }
+    const servers = [];
+    const malformed = [];
+    for (const [id, rawEntry] of Object.entries(lsp)) {
+        if (!isRecord(rawEntry)) {
+            malformed.push(id);
+            continue;
+        }
+        servers.push({
+            id,
+            command: readCommand(rawEntry["command"]),
+            extensions: readExtensions(rawEntry),
+            disabled: rawEntry["disabled"] === true
+        });
+    }
+    const enabled = servers.filter((server) => !server.disabled);
+    const servedExtensions = [...new Set(enabled.flatMap((server) => server.extensions))].sort();
+    return {
+        declared: servers.length > 0,
+        servers,
+        servedExtensions,
+        disabledServers: servers.filter((server) => server.disabled).map((server) => server.id),
+        malformed,
+        verdict: enabled.length > 0 ? "declared" : "none-declared",
+        note: enabled.length > 0
+            ? "Diagnostics for a served extension are real evidence. For any extension not listed here, an empty diagnostic result means nothing was checked; use the lsp-setup skill."
+            : "Every declared server is disabled or malformed, so no extension is currently served. Treat empty diagnostics as absence of capability."
+    };
+}
+// The question the lsp and lsp-setup skills actually ask, answerable per file.
+export function servesExtension(report, extension) {
+    const normalized = extension.startsWith(".") ? extension.toLowerCase() : `.${extension.toLowerCase()}`;
+    return report.servedExtensions.some((candidate) => candidate.toLowerCase() === normalized);
+}

package/dist/cli/managed-skill-assets.d.ts

@@ -0,0 +1,23 @@
+import type { LitOpenCodeRuntimeSkillId } from "../skills.ts";
+export type ManagedSkillId = "lit-comprehend" | "lit-handoff" | "lit-scientific-visualization" | "frontend-ui-ux" | "visual-qa" | "lit-plan" | "browser-drive" | "skill-observer" | "autoresearch" | "autoconference" | "wikify";
+export type CanonicalManagedAsset = {
+    readonly path: string;
+    readonly sha256: string;
+};
+export type ManagedSkillDefinition = {
+    readonly distributionFiles: readonly string[];
+    /** Canonical assets may live outside the native skill wrapper, at this path relative to it. */
+    readonly canonicalRoot?: string;
+    readonly canonicalFiles: readonly CanonicalManagedAsset[];
+};
+export type ManagedVendorAsset = CanonicalManagedAsset;
+export declare function managedSkillDefinition(id: LitOpenCodeRuntimeSkillId): ManagedSkillDefinition | undefined;
+export declare function managedVendorAssets(): readonly ManagedVendorAsset[];
+export declare function previousManagedSkillId(id: LitOpenCodeRuntimeSkillId): string | undefined;
+export declare function assetPathsForManagedSkill(id: LitOpenCodeRuntimeSkillId): readonly string[];
+export declare function expectedManagedSkillFiles(id: LitOpenCodeRuntimeSkillId): readonly string[];
+export declare const installedCanonicalDirectory = "canonical";
+export declare function nativeManagedSkillReferences(id: LitOpenCodeRuntimeSkillId, content: string): string;
+export declare function expectedInstalledSkillFiles(id: LitOpenCodeRuntimeSkillId): readonly string[];
+export declare function isRecursivelyManagedSkill(id: LitOpenCodeRuntimeSkillId): id is ManagedSkillId;
+export declare function managedSkillDiscoveryDescription(id: LitOpenCodeRuntimeSkillId): string;

package/dist/cli/managed-skill-assets.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { renamedSkillIds } from "../skill-renames.js";
+const manifestUrl = new URL("../../skills/managed-skill-manifest.json", import.meta.url);
+const managedSkillManifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+if (managedSkillManifest.schemaVersion !== 1) {
+    throw new Error(`Unsupported managed-skill manifest schema: ${String(managedSkillManifest.schemaVersion)}`);
+}
+export function managedSkillDefinition(id) {
+    if (id !== "lit-comprehend" &&
+        id !== "lit-handoff" &&
+        id !== "lit-scientific-visualization" &&
+        id !== "browser-drive" &&
+        id !== "skill-observer" &&
+        id !== "frontend-ui-ux" &&
+        id !== "visual-qa" &&
+        id !== "lit-plan" &&
+        id !== "autoresearch" &&
+        id !== "autoconference" &&
+        id !== "wikify") {
+        return undefined;
+    }
+    return managedSkillManifest.skills[id];
+}
+export function managedVendorAssets() {
+    return managedSkillManifest.vendorFiles ?? [];
+}
+export function previousManagedSkillId(id) {
+    const previous = managedSkillManifest.renamedSkills?.[id];
+    const expected = Object.entries(renamedSkillIds).find(([canonical]) => canonical === id)?.[1];
+    if (previous !== expected)
+        throw new Error(`Managed skill rename manifest drift: ${id}`);
+    return previous;
+}
+export function assetPathsForManagedSkill(id) {
+    const definition = managedSkillDefinition(id);
+    if (definition === undefined)
+        return [];
+    return [
+        ...definition.distributionFiles.filter((relativePath) => relativePath !== "SKILL.md"),
+        ...(definition.canonicalRoot === undefined ? definition.canonicalFiles.map((asset) => asset.path) : [])
+    ];
+}
+export function expectedManagedSkillFiles(id) {
+    const definition = managedSkillDefinition(id);
+    return definition === undefined
+        ? ["SKILL.md"]
+        : [
+            ...definition.distributionFiles,
+            ...(definition.canonicalRoot === undefined ? definition.canonicalFiles.map((asset) => asset.path) : [])
+        ];
+}
+export const installedCanonicalDirectory = "canonical";
+export function nativeManagedSkillReferences(id, content) {
+    const root = managedSkillDefinition(id)?.canonicalRoot;
+    return root === undefined ? content : content.replaceAll(root, `./${installedCanonicalDirectory}`);
+}
+export function expectedInstalledSkillFiles(id) {
+    const definition = managedSkillDefinition(id);
+    return definition?.canonicalRoot === undefined
+        ? expectedManagedSkillFiles(id)
+        : [
+            ...definition.distributionFiles,
+            ...definition.canonicalFiles.map((asset) => `${installedCanonicalDirectory}/${asset.path}`)
+        ];
+}
+export function isRecursivelyManagedSkill(id) {
+    return managedSkillDefinition(id) !== undefined;
+}
+// Every runtime skill id must map to a capability-shaped trigger, because this string is the ONLY
+// thing the host reads when deciding whether to surface a skill. A name-echo description ("trigger
+// when the user asks for <id>") fires only when the user already knows the skill exists, so it never
+// surfaces the skill at the moment it is needed. The record is total by type: adding a runtime skill
+// id without writing its trigger is a compile error, not a silent fallback.
+const skillDiscoveryDescriptions = Object.freeze({
+    "workflow-loop": "Trigger when the user wants a multi-step LitOpenCode work loop started, resumed, or kept running — bare `lit`, `/lit`, `/litwork`, \"keep going\", \"continue the loop\" — or when a request needs goal binding, ordered execution, and ledger-backed progress across turns instead of one answer.",
+    "durable-litgoal": "Trigger when work needs an objective that outlives the current turn: binding a goal with checkable criteria, reading or appending the `.litopencode/litgoal` ledger, resuming a schema-3 bounded-authority work record, or answering \"what was I working on\" from durable state rather than chat memory.",
+    "agent-roster": "Trigger when deciding which OpenCode agent should do the work, and again the moment work is about to be split across several lanes at once — before delegating through the task tool, when a request fans out into planning, implementation, review, research, or verification lanes, or when the user asks which agents exist and what each is permitted to touch. Delegation here is depth-one, so lanes need non-overlapping slices, explicit per-lane state, and a completion claim that aggregates every lane's evidence rather than summarising it.",
+    "lit-plan": "Trigger when the user asks for a plan, checklist, approach, or design before implementation, or when a request is large or risky enough that execution must not start until scope, non-goals, ordered action/output/verification items, and a falsifiable DoneClaim are agreed. Do not trigger to perform the work itself.",
+    "start-work": "Trigger when an approved plan or an explicit go-ahead already exists and implementation should begin or resume — \"start work\", \"execute the plan\", \"pick up where we left off\" — so the loop runs in verifiable slices with delegation lanes, evidence, and an independent verifier before any completion claim.",
+    "review-work": "Trigger when something must be judged rather than produced: a draft plan needing a PASS / ITERATE / NEEDS-CONTEXT achievability verdict, or finished work needing the five-lane scope-diff, tests-evidence, package-payload, security-provenance, and real-surface-docs check before it can be called done.",
+    litresearch: "Trigger when a question needs sourced investigation rather than recall — comparing options, confirming whether a library, API, or behavior actually works as claimed, gathering public evidence across several sources — so verified facts, hypotheses, contradictions, and residual uncertainty stay separated before a verdict.",
+    "reference-benchmark-claims": "Trigger before writing any comparative or superiority claim about this package — \"faster than\", \"better than\", \"always wins\", \"무조건\" — so the wording is classified against the measured benchmark suite and universal all-task claims are blocked rather than shipped.",
+    "native-goal-verdict": "Trigger when someone assumes the OpenCode host has a built-in goal primitive — asking for `/goal`, native goal tracking, or host-side objective state — so the answer reflects the verified host capability and routes to LitOpenCode durable goal state instead of promising an integration that does not exist.",
+    "doctor-installer": "Trigger when the plugin itself must be installed, inspected, repaired, or previewed: \"install litopencode\", missing commands or skills after an update, a plugin that will not load, editing `litopencode.json` routes, or testing an unpublished local checkout before it reaches a registry.",
+    "search-workflow-ideas": "Trigger when planning how to retrieve something from public sources — choosing a route, deciding what counts as evidence for a retrieval claim, or setting the A/B probes that must prove a behavior change across the CLI, plugin, command, tool, and package surfaces.",
+    "lit-fetch": "Trigger when a public HTTP(S) page, README, raw file, or API response must actually be fetched, so retrieval runs through the SSRF guards and returns a typed verdict, and so authentication, paywall, rate-limit, consent, and challenge boundaries become stop conditions instead of improvised workarounds.",
+    "release-guardrails": "Trigger before any release-shaped action — version bump, tag, publish, changelog, \"is this ready to ship\" — so vocabulary scanning, version lockstep, and a real dry-pack manifest run before the claim is made and publication stays behind explicit user approval.",
+    "lit-init": "Trigger when a repository needs agent-facing guidance created or refreshed: \"set up AGENTS.md\", \"document this repo for agents\", onboarding an unfamiliar codebase, or a restructure that left directory guidance stale and misleading.",
+    "lit-crucible": "Trigger before planning when the approach itself is uncertain, contested, or expensive to reverse — competing designs, hidden coupling, a request to pressure-test assumptions or find what will go wrong — so independent read-only lanes attack the idea and only surviving evidence-backed insights reach lit-plan.",
+    refactor: "Trigger when code should change shape without changing behavior: extracting, renaming, deduplicating, splitting an overgrown module, or paying down structure the user calls messy or hard to follow — so the behavior boundary is pinned by before/after checks and feature work is not smuggled into the diff.",
+    "lit-burnoff": "Trigger when text or code reads as machine-written and should not — comments restating the code, hedging filler, decorative headings, invented emphasis — or when the user asks to \"clean this up\", \"make it less AI\", or strip generated padding, while facts, APIs, tests, and accessibility behavior stay intact.",
+    "lit-burnoff-file": "Trigger right after a single source file was edited and should be cleaned against its own diff — restated comments, hedging filler, unused scaffolding, an abstraction introduced for one call site — without touching any other file or changing what the code does.",
+    "comment-checker": "Trigger right after an edit added or changed comments, to decide per comment whether it survives: delete anything that restates the line below it, keep anything that records a reason, a constraint, or a trap the code cannot state itself.",
+    "lit-code": "Trigger whenever code is being written or changed — implementing a feature, fixing a defect, adding a test, wiring a surface — so the smallest correct change wins over an invented abstraction and the change is paired with a real-surface probe before it is claimed done.",
+    debugging: "Trigger when something is broken and the cause is not yet known — a failing test, a stack trace, a wrong result, \"it worked yesterday\", flaky or intermittent behavior, a fix that did not take — so the failure is reproduced and the mechanism proven before any code is edited.",
+    "lit-commit": "Trigger for any git operation or question: staging, committing, branching, diff review, an unexpectedly dirty worktree, rebase or history inspection, or preparing a PR — so state is inspected before it is mutated and no commit, push, tag, reset, clean, or history rewrite happens without explicit authorization.",
+    lsp: "Trigger when a code question is better answered by the language server than by reading files — real diagnostics after an edit, where a symbol is defined, who calls it, what a type actually resolves to — and when a rename or signature change needs its true blast radius before it is made.",
+    "lsp-setup": "Trigger when the file type being edited has no language server behind it — diagnostics come back empty for a language the host does not serve, or the user asks why there are no errors, no go-to-definition, no rename — so the gap is named and a compiler or test fallback replaces the missing signal.",
+    rules: "Trigger before editing an unfamiliar repository, or when the user invokes house style, conventions, or \"the rules\" — so the shipped rule files are located and ordered before code is written rather than discovered by a reviewer afterwards.",
+    "deep-interview": "Trigger when a request is too broad or underspecified to plan — \"make it better\", \"add auth\", \"build the dashboard\", a one-line feature ask with no acceptance criteria — so the forks that change scope, risk, or acceptance get settled into a decision-complete brief before lit-plan starts.",
+    "browser-drive": "Trigger only when the answer lives in a running page and the user explicitly asked to drive one \u2014 the exact `browser-drive` name, or a page task that no document can settle. LitOpenCode bundles no browser and no driver: probe by identity, quote the probe, and stop at BLOCKED_BROWSER_DRIVER_UNAVAILABLE, BLOCKED_BROWSER_DRIVER_IDENTITY_UNVERIFIED, or BLOCKED_BROWSER_DRIVER_CLEANUP_FAILED rather than substituting a fetch. A passing mention of a browser or a URL is not a request, and checking how a surface looks is visual-qa.",
+    "skill-observer": "Trigger when work has just ended and something in it was instructive \u2014 the exact `skill-observer` name, a repeated correction, or repeated work no skill covered. Observation and review enqueue pending records only; an explicit foreground `litopencode skill-loop apply <id>` is the separate approval act for one agent-marked user skill, with a durable rollback receipt.",
+    "structural-search": "Trigger when the target of a search or a rewrite is a syntax SHAPE rather than a string — \"find every call site that passes a callback\", \"rewrite these imports\", \"locate declarations of this form\", any codemod — so the query survives line breaks, argument spread, and comments that defeat a regex. Also when a text search has already produced a match set nobody trusts. LitOpenCode bundles no engine: probe by identity, and label a textual fallback as textual.",
+    "lit-korean": "Trigger when Korean prose needs to read naturally — a draft that sounds translated, overwrought, or machine-written, a request to 다듬기 / 자연스럽게 / 문장 정리, or review of Korean documentation — while meaning, technical terms, numbers, citations, and the author's voice are preserved.",
+    "lit-comprehend": "Trigger when the user needs to UNDERSTAND completed work rather than just see its status — after a long agent session, an overnight lit-loop, or a multi-file change — so the answer is a self-contained explainer artifact with delta-anchored themes, intuition-first diagrams, a micro-world, and an honesty ledger, not a chronological recap.",
+    "lit-recap": "Trigger when the user asks what has happened so far — \"recap\", \"리캡\", \"where are we\", \"summarize this session\", or resuming after a break — so the answer is a read-only Korean-default digest built from the durable ledger and session evidence instead of a new action.",
+    "lit-handoff": "Trigger only for explicit `/lit-handoff`, an exact bare `handoff` message, or native selection by the exact `lit-handoff` id.",
+    "lit-scientific-visualization": "Trigger only for explicit `/lit-scientific-visualization`, an exact bare `lit-scientific-visualization` message, or native selection by the exact `lit-scientific-visualization` id.",
+    "frontend-ui-ux": "Trigger the moment interface work is described, not after it starts — \"design a settings page\", \"redesign the dashboard\", \"build a login screen\", or any making verb aimed at a UI, screen, layout, component, or stylesheet — so the design contract and the existing tokens shape the work before markup exists. Also on the exact `frontend-ui-ux` id. The SKILL.md reference router names which of the fifteen shipped reference documents answers which question.",
+    "visual-qa": "Trigger when a rendered surface needs to be checked rather than described — an explicit `visual-qa` request, or verifying that an interface change actually looks and behaves right. Selection does not make a browser callable: the shipped capture playbook names the exact blocked code per unavailable channel, and a blocked check reported honestly outranks an unproven pass.",
+    autoresearch: "Trigger when a measurable objective needs repeated hypothesis, experiment, evaluation, and keep/revert decisions, or when its debug, fix, learn, plan, predict, reason, scenario, security, or readiness modes fit the request.",
+    autoconference: "Trigger when several genuinely independent research lanes should explore partitions and exchange peer-reviewed packets; block rather than role-play when the current root lacks real OpenCode task capability.",
+    wikify: "Trigger when the current project needs a maintained local markdown wiki: initialize structure, ingest inert sources, query grounded pages, save durable context, or lint provenance, navigation, contradictions, and drift."
+});
+export function managedSkillDiscoveryDescription(id) {
+    return skillDiscoveryDescriptions[id];
+}

package/dist/cli/model-catalog.d.ts

@@ -0,0 +1,21 @@
+import type { InstallModelEffort, InstallModelRoute } from "./types.ts";
+export type ModelProvider = "openai" | "xai";
+export type ModelMenuRow = {
+    readonly provider: ModelProvider;
+    readonly model: string;
+    readonly effort: InstallModelEffort;
+    readonly efforts: readonly InstallModelEffort[];
+    readonly hint: string;
+};
+export type ProviderMenuRow = {
+    readonly provider: ModelProvider;
+    readonly label: string;
+    readonly credentialEnv: string;
+};
+export declare const providerMenu: readonly ProviderMenuRow[];
+export declare function hostCatalogPath(): string;
+export declare function modelMenuRows(provider: ModelProvider): readonly ModelMenuRow[];
+export declare function isModelProvider(value: string): value is ModelProvider;
+export declare function providerCredentialEnv(provider: string): string | undefined;
+export declare function stripFastSuffix(model: string): string;
+export declare function resolveModelRoute(provider: string, model: string, effort: InstallModelEffort | undefined, optionName: string): InstallModelRoute;

package/dist/cli/model-catalog.js

@@ -0,0 +1,107 @@
+import fsSync from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isRecord } from "./json.js";
+export const providerMenu = [
+    { provider: "openai", label: "OpenAI GPT-6 Astra / GPT-5.6 family", credentialEnv: "OPENAI_API_KEY" },
+    { provider: "xai", label: "xAI Grok", credentialEnv: "XAI_API_KEY" }
+];
+const effortRank = ["low", "medium", "high", "xhigh", "max"];
+// The OpenAI rows are the product policy, not the host catalog. Astra is
+// reasoning-only: all five host-supported effort names are carried through
+// the native `variant`/`reasoningEffort` fields.
+const openaiRows = [
+    { provider: "openai", model: "gpt-6-astra", effort: "xhigh", efforts: ["low", "medium", "high", "xhigh", "max"], hint: "frontier reasoning (recommended lead)" },
+    { provider: "openai", model: "gpt-5.6-sol", effort: "xhigh", efforts: ["high", "xhigh", "max"], hint: "deepest reasoning, slowest (legacy lead)" },
+    { provider: "openai", model: "gpt-5.6-luna", effort: "max", efforts: ["high", "max"], hint: "balanced (recommended helper)" },
+    { provider: "openai", model: "gpt-5.6", effort: "high", efforts: ["high", "xhigh", "max"], hint: "" },
+    { provider: "openai", model: "gpt-5.6-terra", effort: "xhigh", efforts: ["high", "xhigh"], hint: "" }
+];
+// Used only when the host catalog (~/.cache/opencode/models.json) is absent or unreadable.
+const fallbackXaiRows = [
+    { provider: "xai", model: "grok-4.6", effort: "xhigh", efforts: ["low", "medium", "high", "xhigh"], hint: "frontier reasoning (catalog unavailable)" },
+    { provider: "xai", model: "grok-4.5", effort: "high", efforts: ["low", "medium", "high"], hint: "catalog unavailable" },
+    { provider: "xai", model: "grok-4.3", effort: "high", efforts: ["low", "medium", "high"], hint: "catalog unavailable" }
+];
+const xaiRowLimit = 3;
+export function hostCatalogPath() {
+    const cacheHome = process.env.XDG_CACHE_HOME;
+    const base = cacheHome && cacheHome.length > 0 ? cacheHome : path.join(os.homedir(), ".cache");
+    return path.join(base, "opencode", "models.json");
+}
+function isEffort(value) {
+    return typeof value === "string" && effortRank.includes(value);
+}
+function catalogEfforts(entry) {
+    if (!Array.isArray(entry.reasoning_options))
+        return [];
+    const values = [];
+    for (const option of entry.reasoning_options) {
+        if (!isRecord(option) || option.type !== "effort" || !Array.isArray(option.values))
+            continue;
+        for (const value of option.values)
+            if (isEffort(value) && !values.includes(value))
+                values.push(value);
+    }
+    return values.sort((left, right) => effortRank.indexOf(left) - effortRank.indexOf(right));
+}
+function xaiRowsFromCatalog() {
+    let parsed;
+    try {
+        parsed = JSON.parse(fsSync.readFileSync(hostCatalogPath(), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.xai) || !isRecord(parsed.xai.models))
+        return undefined;
+    const rows = [];
+    for (const [id, entry] of Object.entries(parsed.xai.models)) {
+        if (!isRecord(entry) || entry.reasoning !== true)
+            continue;
+        const efforts = catalogEfforts(entry);
+        if (efforts.length === 0)
+            continue;
+        const release = typeof entry.release_date === "string" ? entry.release_date : "";
+        const top = efforts[efforts.length - 1];
+        if (top === undefined)
+            continue;
+        rows.push({ row: { provider: "xai", model: id, effort: top, efforts, hint: "released " + (release || "unknown") }, release });
+    }
+    if (rows.length === 0)
+        return undefined;
+    rows.sort((left, right) => (left.row.model === "grok-4.6" ? -1 : right.row.model === "grok-4.6" ? 1 : right.release.localeCompare(left.release)));
+    return rows.slice(0, xaiRowLimit).map((entry) => entry.row);
+}
+export function modelMenuRows(provider) {
+    if (provider === "openai")
+        return openaiRows;
+    return xaiRowsFromCatalog() ?? fallbackXaiRows;
+}
+export function isModelProvider(value) {
+    return providerMenu.some((row) => row.provider === value);
+}
+export function providerCredentialEnv(provider) {
+    return providerMenu.find((row) => row.provider === provider)?.credentialEnv;
+}
+// OpenCode exposes `<id>-fast` as a priority-tier alias for legacy OpenAI
+// rows; Astra has no inferred `-fast` alias and remains an exact model id.
+export function stripFastSuffix(model) {
+    return model !== "gpt-6-astra-fast" && model.endsWith("-fast") ? model.slice(0, -"-fast".length) : model;
+}
+export function resolveModelRoute(provider, model, effort, optionName) {
+    if (!isModelProvider(provider)) {
+        throw new Error(optionName + " provider must be one of " + providerMenu.map((row) => row.provider).join(", ") + " (got " + provider + ")");
+    }
+    const rows = modelMenuRows(provider);
+    const row = rows.find((candidate) => candidate.model === (provider === "openai" ? stripFastSuffix(model) : model));
+    if (row === undefined) {
+        throw new Error(optionName + " model " + provider + "/" + model + " is not offered; choose one of " + rows.map((candidate) => candidate.model).join(", "));
+    }
+    if (effort !== undefined && !row.efforts.includes(effort)) {
+        if (row.model === "gpt-5.6-luna")
+            throw new Error("Luna effort must be high or max");
+        throw new Error(provider + "/" + model + " accepts effort " + row.efforts.join(", ") + " (got " + effort + ")");
+    }
+    return { provider, model, effort: effort ?? row.effort };
+}

package/dist/cli/model-policy.d.ts

@@ -0,0 +1,3 @@
+import type { InstallModelSelection, InstallPermissionMode, ModelConfigClassification } from "./types.ts";
+export declare function classifyModelConfig(rawConfig: Record<string, unknown> | null): ModelConfigClassification;
+export declare function selectedLitConfig(rawConfig: Record<string, unknown> | null, selection: InstallModelSelection | undefined, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, outputStyle?: string): Record<string, unknown>;