@litfamily/litopencode 1.0.29 → 1.0.31

package/dist/cli/install.d.ts

@@ -1,2 +1,10 @@
 import type { CliResult, InstallModelSelection, InstallPermissionMode, InstallProgress, ModelPromptMode, PermissionPromptMode } from "./types.ts";
-export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode): Promise<CliResult>;
+import { type HostChoice } from "./host-detect.ts";
+/**
+ * OpenCode 2 merges its own `plugins` key with the OpenCode 1 `plugin` list and refuses a second plugin
+ * with the same id, so a LitOpenCode entry under `plugins` is removed when OpenCode 2 is a target. The
+ * one registration stays in `plugin`, which both hosts read.
+ */
+export declare function withoutV2PluginEntries(config: Record<string, unknown> | null): Record<string, unknown> | null;
+export declare function assertNoHostOnlyKeysAdded(before: Record<string, unknown> | null, next: Record<string, unknown> | null): void;
+export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode, host?: HostChoice): Promise<CliResult>;

package/dist/cli/install.js

@@ -1,10 +1,9 @@
-import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { promisify } from "node:util";
 import { createRuntimePaths } from "../state.js";
 import { describeCommandAliasMutation, ensureCommandAliases, inspectCommandAliases } from "./command-aliases.js";
+import { execCommand } from "./command-plan.js";
 import { openCodeHostCapabilities } from "./host-capabilities.js";
 import { applyHostLimits, describeHostLimitMutation, ensureHostLimits } from "./host-limits.js";
 import { assertExistingModelRoutesSafe, migrateRetiredEfforts, describeInstallRoutes, describeLitConfigMutation, ensureLitConfig, OpenCodeConfigCommentError, readExistingOutputStyle, readInstallModelClassification, readInstallModelSelection, renderOpenCodeConfig, writeOpenCodeConfig } from "./install-config.js";
@@ -16,8 +15,8 @@ import { litOpenCodeConfigFileForOpenCodeRoot } from "../state.js";
 import { describeNativeSkillMutation, ensureNativeSkills, inspectNativeSkills } from "./native-skills.js";
 import { applyPluginMutation, describePluginMutation, isLitOpenCodeEntry } from "./plugin-mutation.js";
 import { prewarmMotionRuntime } from "./motion-runtime.js";
-import { applyTuiWrites, backupTuiFiles, inspectTuiPlugin, planTuiInstall } from "./tui-config.js";
-const execFileAsync = promisify(execFile);
+import { applyCliJsonCleanup, applyTuiWrites, backupTuiFiles, inspectTuiPlugin, planCliJsonCleanup, planTuiInstall, skippedTuiPlan } from "./tui-config.js";
+import { confirmUnplacedOpenCode, detectOpenCodeHosts, targetsV1, targetsV2 } from "./host-detect.js";
 function withProgress(progress, label, task) {
     return progress === undefined ? task() : progress.run(label, task);
 }
@@ -107,9 +106,18 @@ async function openCodeInstallTarget(metadata) {
     const spec = pluginSpec(metadata);
     return { value: spec, label: spec };
 }
-async function installWithOpenCode(target) {
+async function openCodeVersion(command) {
     try {
-        await execFileAsync("opencode", ["plugin", target.value, "--global", "--force"], {
+        const { stdout } = await execCommand(command, ["--version"], { timeout: 15_000, maxBuffer: 64 * 1024 });
+        return String(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function installWithOpenCode(target, command = "opencode") {
+    try {
+        await execCommand(command, ["plugin", target.value, "--global", "--force"], {
             timeout: 120_000,
             maxBuffer: 1024 * 1024 * 4
         });
@@ -147,14 +155,41 @@ async function normalizeOpenCodeEntries(root, target) {
         await writeOpenCodeConfig(configFile, { ...config, plugin: nextPlugin });
     }
 }
+function v2PluginEntryId(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value))
+        return value.package;
+    return value;
+}
+/**
+ * OpenCode 2 merges its own `plugins` key with the OpenCode 1 `plugin` list and refuses a second plugin
+ * with the same id, so a LitOpenCode entry under `plugins` is removed when OpenCode 2 is a target. The
+ * one registration stays in `plugin`, which both hosts read.
+ */
+export function withoutV2PluginEntries(config) {
+    if (config === null || !Array.isArray(config.plugins))
+        return config;
+    const kept = config.plugins.filter((entry) => !isLitOpenCodeEntry(v2PluginEntryId(entry)));
+    return kept.length === config.plugins.length ? config : { ...config, plugins: kept };
+}
+// OpenCode 1 refuses to start when the shared config holds the OpenCode 2 `permissions` key, and OpenCode 2
+// keeps `policies` there too. LitOpenCode never writes either; this check makes that a hard rule.
+const hostOnlyKeys = ["permissions", "policies"];
+export function assertNoHostOnlyKeysAdded(before, next) {
+    for (const key of hostOnlyKeys) {
+        if (next !== null && key in next && JSON.stringify(next[key]) !== JSON.stringify(before?.[key])) {
+            throw new Error(`Refusing to write the OpenCode 2 \`${key}\` key into the shared config.`);
+        }
+    }
+}
 // Works out every OpenCode config edit the install will make before anything is written, and returns
 // the refusal when one of them would delete a user comment. On the default root OpenCode registers the
 // plugin itself; LitOpenCode then only cleans up stale entries and sets host limits.
-async function commentLossRefusal(root, configFile, target, before, mutation, reconfigureHostLimits, useOpenCodeInstaller) {
+async function commentLossRefusal(root, configFile, target, before, mutation, reconfigureHostLimits, useOpenCodeInstaller, stripV2Plugins = false) {
     const planned = [];
+    const v2 = (next) => (stripV2Plugins ? withoutV2PluginEntries(next) : next);
     if (!useOpenCodeInstaller) {
         const next = applyPluginMutation(before, mutation, target.value);
-        planned.push({ file: configFile, next: reconfigureHostLimits ? applyHostLimits(next) : next });
+        planned.push({ file: configFile, next: v2(reconfigureHostLimits ? applyHostLimits(next) : next) });
     }
     else {
         for (const file of openCodeConfigCandidates(root)) {
@@ -170,7 +205,7 @@ async function commentLossRefusal(root, configFile, target, before, mutation, re
                 if (JSON.stringify(normalized) !== JSON.stringify(registered))
                     next = { ...config, plugin: normalized };
             }
-            planned.push({ file, next: file === configFile && reconfigureHostLimits ? applyHostLimits(next) : next });
+            planned.push({ file, next: v2(file === configFile && reconfigureHostLimits ? applyHostLimits(next) : next) });
         }
     }
     try {
@@ -186,7 +221,7 @@ async function commentLossRefusal(root, configFile, target, before, mutation, re
     }
     return undefined;
 }
-async function verifyInstalledSurfaces(root, configFile, target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle) {
+async function verifyInstalledSurfaces(root, configFile, target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle, host = { mode: "v1", binaries: [], evidence: { cliJson: false, tuiJson: false } }) {
     const config = await readJsonObjectIfPresent(configFile);
     const pluginEntries = Array.isArray(config?.plugin) ? config.plugin : [];
     const pluginIds = pluginEntries.map((entry) => typeof entry === "string" ? entry : Array.isArray(entry) && typeof entry[0] === "string" ? entry[0] : "");
@@ -195,12 +230,20 @@ async function verifyInstalledSurfaces(root, configFile, target, metadata, selec
     const litConfig = await describeLitConfigMutation(root, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle);
     const commandAliases = await inspectCommandAliases(root);
     const nativeSkills = await inspectNativeSkills(root, metadata);
-    const tui = await inspectTuiPlugin(root, target.value);
     const failures = [];
     if (targetCount !== 1 || staleLitEntries.length > 0)
         failures.push("plugin registration");
-    if (!tui.ok)
-        failures.push("TUI plugin registration in " + tui.path);
+    if (targetsV1(host.mode)) {
+        const tui = await inspectTuiPlugin(root, target.value);
+        if (!tui.ok)
+            failures.push("TUI plugin registration in " + tui.path);
+    }
+    if (targetsV2(host.mode)) {
+        if (withoutV2PluginEntries(config) !== config)
+            failures.push("duplicate LitOpenCode entry under plugins");
+        if ((await planCliJsonCleanup(root)).removed > 0)
+            failures.push("LitOpenCode entry left in cli.json");
+    }
     if (litConfig.changed)
         failures.push("LitOpenCode routes");
     if (!commandAliases.ok)
@@ -214,7 +257,7 @@ async function verifyInstalledSurfaces(root, configFile, target, metadata, selec
     if (failures.length > 0)
         throw new Error("Install verification failed: " + failures.join("; "));
 }
-export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto") {
+export async function install(root, dryRun, modelSelection = undefined, modelPrompt = "auto", permissionMode = "safe", permissionModeExplicit = false, permissionPrompt = "auto", progress, outputStylePrompt = "auto", host = "auto") {
     const retiredNotice = await migrateRetiredEfforts(root, dryRun);
     if (retiredNotice !== undefined)
         process.stdout.write(retiredNotice + "\n");
@@ -233,33 +276,66 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         await activeProgress.start(pluginSpec(metadata));
     }
     const spec = pluginSpec(metadata);
-    const resolved = await withProgress(activeProgress, "Resolve package", async () => {
+    const located = await withProgress(activeProgress, "Resolve package", async () => {
         const paths = createRuntimePaths(root);
         const useOpenCodeInstaller = shouldUseOpenCodeInstaller(root);
         const target = useOpenCodeInstaller ? await openCodeInstallTarget(metadata) : { value: spec, label: spec };
-        return { paths, useOpenCodeInstaller, target };
+        // A custom root says nothing about which host reads it, so only its config files count there.
+        const detection = await detectOpenCodeHosts({
+            root,
+            override: host,
+            ...(useOpenCodeInstaller ? {} : { resolvePackage: async () => undefined })
+        });
+        return { paths, useOpenCodeInstaller, target, detection };
     });
-    const inspected = await withProgress(activeProgress, "Read OpenCode config", async () => {
-        const configFile = resolved.useOpenCodeInstaller
+    const resolveFor = (detection) => {
+        const forV1 = targetsV1(detection.mode);
+        const forV2 = targetsV2(detection.mode);
+        // `opencode plugin` is the OpenCode 1 command; OpenCode 2 installs the package itself on first load.
+        const runInstaller = located.useOpenCodeInstaller && forV1;
+        const opencodeIsV2 = [...detection.binaries, ...(detection.unplaced ?? [])].some((found) => found.command === "opencode" && found.major === 2);
+        if (runInstaller && detection.v1Command === undefined && opencodeIsV2) {
+            throw new Error("Found no OpenCode 1 command: `opencode` is OpenCode 2, and `opencode plugin` would change OpenCode 2's config. Install for OpenCode 2 with --host v2, or put OpenCode 1 on PATH as `opencode`.");
+        }
+        return { ...located, detection, runInstaller, forV1, forV2 };
+    };
+    const inspect = async (current) => {
+        const configFile = current.useOpenCodeInstaller
             ? await openCodeManagedConfigFile(root)
-            : resolved.paths.opencodeConfigFile;
+            : current.paths.opencodeConfigFile;
         const before = await readJsonObjectIfPresent(configFile);
         return {
             configFile,
             before,
-            mutation: describePluginMutation(before, resolved.target.value),
+            mutation: describePluginMutation(before, current.target.value),
             litopencodeConfig: await describeLitConfigMutation(root, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle),
             commandAliases: await describeCommandAliasMutation(root),
             nativeSkills: await describeNativeSkillMutation(root, metadata),
             hostLimits: describeHostLimitMutation(before, selectedModel !== undefined),
-            tui: await planTuiInstall(root, resolved.target.value),
+            tui: current.forV1 ? await planTuiInstall(root, current.target.value) : skippedTuiPlan(root),
+            cliJson: current.forV2 ? await planCliJsonCleanup(root) : { path: path.join(path.resolve(root), "cli.json"), removed: 0 },
             routes: dryRun
                 ? await describeInstallRoutes(root, before, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle)
                 : undefined
         };
-    });
-    const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes, tui } = inspected;
-    const blocked = (await commentLossRefusal(root, configFile, resolved.target, before, mutation, hostLimits.reconfigure, resolved.useOpenCodeInstaller)) ?? tui.blocked;
+    };
+    const refusalFor = async (current, plan) => (await commentLossRefusal(root, plan.configFile, current.target, plan.before, plan.mutation, plan.hostLimits.reconfigure, current.runInstaller, current.forV2)) ?? plan.tui.blocked ?? plan.cliJson.blocked;
+    let resolved = resolveFor(located.detection);
+    let inspected = await withProgress(activeProgress, "Read OpenCode config", async () => inspect(resolved));
+    let blocked = await refusalFor(resolved, inspected);
+    // A real install that passed every refusal is about to run `opencode plugin`. An `opencode` only guessed
+    // to be OpenCode 1 answers `--version` first, so an OpenCode 2 installed outside npm gets the OpenCode 2
+    // setup instead. A dry run and a refused install start nothing.
+    if (blocked === undefined && !dryRun && resolved.runInstaller) {
+        const confirmed = await confirmUnplacedOpenCode(resolved.detection, openCodeVersion);
+        if (confirmed !== resolved.detection) {
+            resolved = resolveFor(confirmed);
+            inspected = await inspect(resolved);
+            blocked = await refusalFor(resolved, inspected);
+        }
+    }
+    const { configFile, before, mutation, litopencodeConfig, commandAliases, nativeSkills, hostLimits, routes, tui, cliJson } = inspected;
+    const v2PluginsChanged = resolved.forV2 && withoutV2PluginEntries(before) !== before;
     const report = {
         dryRun,
         path: configFile,
@@ -269,12 +345,20 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         nativeSkills,
         tui: tui.report,
         patch: mutation.patch,
-        changed: mutation.changed || litopencodeConfig.changed || commandAliases.changed || nativeSkills.changed || hostLimits.changed || tui.report.changed,
+        changed: mutation.changed || litopencodeConfig.changed || commandAliases.changed || nativeSkills.changed || hostLimits.changed || tui.report.changed || cliJson.removed > 0 || v2PluginsChanged,
         ...(blocked === undefined ? {} : { blocked }),
         routes,
         hostLimits: { path: configFile, ...hostLimits },
         capabilities: openCodeHostCapabilities(),
-        package: { name: metadata.name, version: metadata.version }
+        package: { name: metadata.name, version: metadata.version },
+        host: {
+            mode: resolved.detection.mode,
+            binaries: resolved.detection.binaries,
+            ...(resolved.detection.unplaced === undefined ? {} : { unplaced: resolved.detection.unplaced }),
+            evidence: resolved.detection.evidence,
+            ...(resolved.detection.override === undefined ? {} : { override: resolved.detection.override })
+        },
+        cliJson: { path: cliJson.path, removed: cliJson.removed, changed: cliJson.removed > 0 }
     };
     if (dryRun) {
         return {
@@ -295,30 +379,49 @@ export async function install(root, dryRun, modelSelection = undefined, modelPro
         await ensureCommandAliases(root);
     });
     await withProgress(activeProgress, "Register plugin", async () => {
-        if (resolved.useOpenCodeInstaller) {
+        if (resolved.runInstaller) {
             // The package's `./tui` export makes `opencode plugin` add the TUI entry itself, so back up
             // first, then normalize whatever it wrote without a second backup.
             await backupTuiFiles(tui);
-            await installWithOpenCode(resolved.target);
+            // Both config candidates as they were, so an OpenCode 2 key added to either one is caught.
+            const candidates = openCodeConfigCandidates(root);
+            const snapshots = new Map(await Promise.all(candidates.map(async (file) => [file, await readJsonObjectIfPresent(file)])));
+            await installWithOpenCode(resolved.target, resolved.detection.v1Command ?? "opencode");
             const installed = await readJsonObjectIfPresent(configFile);
             if (!Array.isArray(installed?.plugin) || !installed.plugin.some((entry) => (Array.isArray(entry) ? entry[0] : entry) === resolved.target.value))
                 throw new Error("OpenCode did not register the requested package target");
             await normalizeOpenCodeEntries(root, resolved.target);
+            if (resolved.forV2) {
+                for (const file of candidates) {
+                    const current = await readJsonObjectIfPresent(file);
+                    const stripped = withoutV2PluginEntries(current);
+                    if (stripped === current || stripped === null)
+                        continue;
+                    assertNoHostOnlyKeysAdded(snapshots.get(file) ?? null, stripped);
+                    await writeOpenCodeConfig(file, stripped);
+                }
+            }
             await ensureHostLimits(configFile, await readJsonObjectIfPresent(configFile), hostLimits.reconfigure);
             const settled = await planTuiInstall(root, resolved.target.value);
             if (settled.blocked !== undefined)
                 throw new OpenCodeConfigCommentError(settled.blocked);
             await applyTuiWrites(settled.writes, { backup: false });
+            for (const file of candidates)
+                assertNoHostOnlyKeysAdded(snapshots.get(file) ?? null, await readJsonObjectIfPresent(file));
             return;
         }
         await applyTuiWrites(tui.writes);
         const withPlugin = applyPluginMutation(before, mutation, resolved.target.value);
-        const next = hostLimits.reconfigure ? applyHostLimits(withPlugin) : withPlugin;
-        if (JSON.stringify(next) === JSON.stringify(before))
+        const limited = hostLimits.reconfigure ? applyHostLimits(withPlugin) : withPlugin;
+        const next = resolved.forV2 ? withoutV2PluginEntries(limited) : limited;
+        assertNoHostOnlyKeysAdded(before, next);
+        if (next === null || JSON.stringify(next) === JSON.stringify(before))
             return;
         await writeOpenCodeConfig(configFile, next);
     });
-    await withProgress(activeProgress, "Verify install", async () => verifyInstalledSurfaces(root, configFile, resolved.target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle));
+    if (resolved.forV2)
+        await applyCliJsonCleanup(cliJson);
+    await withProgress(activeProgress, "Verify install", async () => verifyInstalledSurfaces(root, configFile, resolved.target, metadata, selectedModel, selectedPermissionMode, selectedPermissionExplicit, selectedOutputStyle, resolved.detection));
     await activeProgress?.complete();
     // MO-A-42: the installer attempts the motion pre-warm; a failure never fails the install.
     const motionReceipt = wrapReceiptLine(prewarmMotionRuntime(metadata.packageRoot));

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

@@ -1,5 +1,5 @@
 import type { LitOpenCodeRuntimeSkillId } from "../skills.ts";
-export type ManagedSkillId = "lit-comprehend" | "lit-handoff" | "lit-scientific-visualization" | "lit-diagram-drawer" | "lit-pptx" | "lit-typographic-motion" | "lit-docx" | "readme-studio" | "frontend-ui-ux" | "visual-qa" | "lit-plan" | "browser-drive" | "lit-humanizer" | "autoresearch" | "autoconference" | "wikify";
+export type ManagedSkillId = "lit-brainstorm" | "lit-comprehend" | "lit-handoff" | "lit-scientific-visualization" | "lit-diagram-drawer" | "lit-pptx" | "lit-typographic-motion" | "lit-docx" | "readme-studio" | "frontend-ui-ux" | "visual-qa" | "lit-plan" | "browser-drive" | "lit-humanizer" | "autoresearch" | "autoconference" | "wikify";
 export type CanonicalManagedAsset = {
     readonly path: string;
     readonly sha256: string;

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

@@ -6,7 +6,8 @@ if (managedSkillManifest.schemaVersion !== 1) {
     throw new Error(`Unsupported managed-skill manifest schema: ${String(managedSkillManifest.schemaVersion)}`);
 }
 export function managedSkillDefinition(id) {
-    if (id !== "lit-comprehend" &&
+    if (id !== "lit-brainstorm" &&
+        id !== "lit-comprehend" &&
         id !== "lit-handoff" &&
         id !== "lit-scientific-visualization" &&
         id !== "lit-diagram-drawer" &&
@@ -79,7 +80,7 @@ export function isRecursivelyManagedSkill(id) {
 // 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. Also trigger when one request hands over a whole feature, fix, or ticket to carry through to done — build it, add tests, verify against each acceptance condition and on the real user-facing path, clean up temporary artifacts, then report what changed (\"start to finish\", \"end to end\", \"see it through\", \"처음부터 끝까지\", \"끝까지 해줘\"). Do not trigger for a question, an explanation, or a one-line snippet.",
-    "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.",
+    litgoal: "Trigger when work needs a finish line that outlives the current turn — litgoal sets and keeps it, lit-loop and start-work run toward it: 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.",
@@ -92,6 +93,7 @@ const skillDiscoveryDescriptions = Object.freeze({
     "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-brainstorm": "Trigger when the question is still open and the user wants options before a decision — \"what could we call it\", \"any ideas for\", \"how else could we do this\", \"brainstorm\", \"ideation\", `lit idea`, `lit brainstorm` — so many different options are generated, clustered, scored against stated criteria, and narrowed to a short list with trade-offs before one hand-off to deep-interview or lit-plan. Do not trigger to plan a chosen thing, to interview toward one spec, or to implement.",
     "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.",
@@ -113,7 +115,7 @@ const skillDiscoveryDescriptions = Object.freeze({
     "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.",
     "lit-diagram-drawer": "Select this skill from OpenCode's native skill picker when the user needs an architecture map, workflow, schema, decision path, schedule, or conceptual chart. Route product pages and interface layouts to frontend-ui-ux; route measured scientific data and statistical figures to lit-scientific-visualization. Do not claim a slash command or bare-chat route.",
     "lit-pptx": "Select for a PowerPoint deck or presentation, including a bounded lit request for slides. Keep editable Markdown and PPTX together, run the QA gate, and inspect the render.",
-    "lit-typographic-motion": "Select for a new film or video. Write the treatment first, then render on the stage path (a captured page) or the type path (words alone), gate it and look at the frames; editing existing footage or embedding a video in a page is outside this route.",
+    "lit-typographic-motion": "Select for a new film or video. Write the treatment first, then render on the stage path (a captured page) or the type path (words alone), gate it and look at the frames; a README cover loop takes cover mode. Editing existing footage or embedding a video in a page is outside this route.",
     "lit-docx": "Select for a Word report, proposal, or document, including a bounded lit report request. Keep editable Markdown and DOCX together; select publisher profiles when specified and inspect rendered pages.",
     "readme-studio": "Select by native skill name for factual README writing and local cover composition. Inspect actual session image capability; never infer generation support or authorize publication from selection.",
     "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 compact direction and existing tokens shape the authorized build. Evolve the contract with implementation and inspect renders; review and plan intent remains read-only. Also on the exact `frontend-ui-ux` id. The SKILL.md reference router names which of the sixteen shipped reference documents answers which question.",

package/dist/cli/office-dependencies.d.ts

@@ -1,3 +1,5 @@
+/** A venv keeps its interpreter in `Scripts` on Windows and in `bin` elsewhere. */
+export declare const venvPythonMarker: (platform?: NodeJS.Platform) => string;
 export declare function inspectOfficeDependencies(): {
     pptx: {
         nodeReady: boolean;

package/dist/cli/office-dependencies.js

@@ -3,21 +3,25 @@ import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { findCommandOnPath } from "./host-detect.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const cacheRoot = path.join(process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache"), "litopencode", "office");
 function cached(label, lock, marker) {
     const digest = createHash("sha256").update(readFileSync(path.join(packageRoot, lock))).digest("hex").slice(0, 16);
     return existsSync(path.join(cacheRoot, `${label}-${digest}`, marker));
 }
+/** A venv keeps its interpreter in `Scripts` on Windows and in `bin` elsewhere. */
+export const venvPythonMarker = (platform = process.platform) => (platform === "win32" ? "Scripts/python.exe" : "bin/python");
 export function inspectOfficeDependencies() {
-    const onPath = (name) => (process.env.PATH ?? "").split(path.delimiter).some((dir) => existsSync(path.join(dir, name)));
+    const onPath = (name) => findCommandOnPath(name) !== undefined;
+    const python = venvPythonMarker();
     return {
         pptx: {
             nodeReady: cached("node", "skills/lit-pptx/package-lock.json", "node_modules/pptxgenjs"),
-            pythonReady: cached("python-pptx", "skills/lit-pptx/requirements.lock", "bin/python")
+            pythonReady: cached("python-pptx", "skills/lit-pptx/requirements.lock", python)
         },
         docx: {
-            pythonReady: cached("python-docx", "skills/lit-docx/requirements.lock", "bin/python")
+            pythonReady: cached("python-docx", "skills/lit-docx/requirements.lock", python)
         },
         optional: { pandoc: onPath("pandoc"), xelatex: onPath("xelatex"), soffice: onPath("soffice") }
     };

package/dist/cli/scientific-visualization-dependencies.js

@@ -15,7 +15,7 @@ const optionalModules = Object.freeze([
 ]);
 function selectedInterpreter() {
     const explicit = process.env.LITOPENCODE_SCIENTIFIC_PYTHON?.trim();
-    return explicit && explicit.length > 0 ? explicit : "python3";
+    return explicit && explicit.length > 0 ? explicit : process.platform === "win32" ? "python" : "python3";
 }
 function unavailableReport(command) {
     return {

package/dist/cli/tui-config.d.ts

@@ -37,8 +37,6 @@ export declare function applyTuiWrites(writes: readonly PlannedWrite[], options?
 }): Promise<void>;
 /** Backs up the TUI files a plan is about to change, for writers outside LitOpenCode such as `opencode plugin`. */
 export declare function backupTuiFiles(plan: TuiInstallPlan): Promise<void>;
-/** Removes LitOpenCode's own TUI entries, and only those, from tui.json and tui.jsonc. */
-export declare function removeTuiPlugin(root: string, dryRun: boolean): Promise<TuiRemovalReport>;
 export type TuiInspection = {
     readonly path: string;
     readonly expected: string;
@@ -49,4 +47,31 @@ export type TuiInspection = {
     readonly error?: string;
 };
 export declare function inspectTuiPlugin(root: string, expected: string): Promise<TuiInspection>;
+export declare const cliConfigFile = "cli.json";
+export type CliJsonCleanupPlan = {
+    readonly path: string;
+    readonly removed: number;
+    readonly write?: PlannedWrite;
+    readonly blocked?: string;
+};
+/** Plans the removal of LitOpenCode's own entries from the `plugins` list of cli.json, without writing. */
+export declare function planCliJsonCleanup(root: string): Promise<CliJsonCleanupPlan>;
+/** Writes a cli.json cleanup plan, backing the file up first. Returns the backup path. */
+export declare function applyCliJsonCleanup(plan: CliJsonCleanupPlan): Promise<string | undefined>;
+/** The TUI part of an install that targets OpenCode 2 only: nothing to write in tui.json. */
+export declare function skippedTuiPlan(root: string): TuiInstallPlan;
+/**
+ * `tui remove`: takes LitOpenCode's own entries out of tui.json/tui.jsonc and, unless only OpenCode 1 is
+ * targeted, out of cli.json, each with a backup. Both files are read and planned first, so a malformed or
+ * comment-losing file refuses before anything is written. A dry run only counts.
+ */
+export declare function removeTuiEntries(root: string, dryRun: boolean, options: {
+    readonly cliJson: boolean;
+}): Promise<TuiRemovalReport & {
+    readonly cliJson?: {
+        readonly path: string;
+        readonly removed: number;
+        readonly backup?: string;
+    };
+}>;
 export {};

package/dist/cli/tui-config.js

@@ -132,8 +132,8 @@ export async function backupTuiFiles(plan) {
     for (const write of plan.writes)
         await backup(write);
 }
-/** Removes LitOpenCode's own TUI entries, and only those, from tui.json and tui.jsonc. */
-export async function removeTuiPlugin(root, dryRun) {
+/** Plans the removal of LitOpenCode's own TUI entries, and only those, from tui.json and tui.jsonc, without writing. */
+async function planTuiRemoval(root) {
     const files = await Promise.all(tuiConfigCandidates(root).map(readTuiFile));
     const writes = [];
     for (const file of files) {
@@ -146,6 +146,9 @@ export async function removeTuiPlugin(root, dryRun) {
         const kept = plugins.filter((_value, index) => !owned.includes(index));
         writes.push({ write: render(file, { ...file.config, plugin: kept }), removed: owned.length });
     }
+    return writes;
+}
+async function applyTuiRemoval(writes, dryRun) {
     const reports = [];
     for (const { write, removed } of writes) {
         if (dryRun) {
@@ -196,3 +199,75 @@ export async function inspectTuiPlugin(root, expected) {
         ok: present && entries === 1
     };
 }
+// OpenCode 2 keeps its terminal settings in one global cli.json, and its first TUI start copies the
+// tui.json plugin list there. A LitOpenCode entry in cli.json is loaded after the TUI the server plugin
+// brings and wins by id, so a stale pin would shadow the current TUI. OpenCode 2 loads LitOpenCode's TUI
+// from the server plugin on its own; the installer and `tui remove` therefore take LitOpenCode out of
+// cli.json, keeping every other entry, the comments and a backup.
+export const cliConfigFile = "cli.json";
+function cliEntryId(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const pkg = value.package;
+        return typeof pkg === "string" ? pkg : "";
+    }
+    return "";
+}
+/** Plans the removal of LitOpenCode's own entries from the `plugins` list of cli.json, without writing. */
+export async function planCliJsonCleanup(root) {
+    const file = path.join(path.resolve(root), cliConfigFile);
+    const current = await readTuiFile(file);
+    const plugins = Array.isArray(current.config?.plugins) ? current.config.plugins : [];
+    const kept = [];
+    for (const value of plugins) {
+        const id = cliEntryId(value);
+        if (id !== "" && (isLitOpenCodeEntry(id) || (await isLitOpenCodePathEntry(root, id))))
+            continue;
+        kept.push(value);
+    }
+    const removed = plugins.length - kept.length;
+    if (removed === 0 || current.config === null)
+        return { path: file, removed: 0 };
+    try {
+        return { path: file, removed, write: render(current, { ...current.config, plugins: kept }) };
+    }
+    catch (error) {
+        if (!(error instanceof OpenCodeConfigCommentError))
+            throw error;
+        return { path: file, removed, blocked: error.message };
+    }
+}
+/** Writes a cli.json cleanup plan, backing the file up first. Returns the backup path. */
+export async function applyCliJsonCleanup(plan) {
+    if (plan.write === undefined)
+        return undefined;
+    const backupPath = await backup(plan.write);
+    await writeTextAtomically(plan.write.path, plan.write.text);
+    return backupPath;
+}
+/** The TUI part of an install that targets OpenCode 2 only: nothing to write in tui.json. */
+export function skippedTuiPlan(root) {
+    return {
+        report: { path: tuiConfigCandidates(root)[0], alreadyPresent: false, changed: false, add: [], currentCount: 0, resultCount: 0, cleaned: [] },
+        writes: []
+    };
+}
+/**
+ * `tui remove`: takes LitOpenCode's own entries out of tui.json/tui.jsonc and, unless only OpenCode 1 is
+ * targeted, out of cli.json, each with a backup. Both files are read and planned first, so a malformed or
+ * comment-losing file refuses before anything is written. A dry run only counts.
+ */
+export async function removeTuiEntries(root, dryRun, options) {
+    const tuiPlan = await planTuiRemoval(root);
+    const cliPlan = options.cliJson ? await planCliJsonCleanup(root) : undefined;
+    if (cliPlan?.blocked !== undefined)
+        throw new OpenCodeConfigCommentError(cliPlan.blocked);
+    const tui = await applyTuiRemoval(tuiPlan, dryRun);
+    if (cliPlan === undefined)
+        return tui;
+    if (dryRun || cliPlan.write === undefined)
+        return { ...tui, cliJson: { path: cliPlan.path, removed: cliPlan.removed } };
+    const backupPath = await applyCliJsonCleanup(cliPlan);
+    return { ...tui, cliJson: { path: cliPlan.path, removed: cliPlan.removed, ...(backupPath === undefined ? {} : { backup: backupPath }) } };
+}

package/dist/cli/types.d.ts

@@ -10,6 +10,7 @@ export type PackageMetadata = {
     readonly version: string;
     readonly packageRoot: string;
 };
+import type { HostBinary, HostChoice, HostDetection, HostMode } from "./host-detect.ts";
 export type ParsedArgs = {
     readonly command?: string;
     readonly root: string;
@@ -27,6 +28,7 @@ export type ParsedArgs = {
     readonly outputStylePrompt: PermissionPromptMode;
     readonly loop: LoopArgs;
     readonly tuiAction?: string;
+    readonly host: HostChoice;
 };
 export type LoopArgs = {
     readonly projectRoot: string;
@@ -190,4 +192,19 @@ export type InstallReport = {
     readonly routes?: InstallRouteReport;
     readonly capabilities: OpenCodeHostCapabilities;
     readonly package: Pick<PackageMetadata, "name" | "version">;
+    readonly host?: {
+        readonly mode: HostMode;
+        readonly binaries: readonly HostBinary[];
+        readonly unplaced?: HostDetection["unplaced"];
+        readonly evidence: {
+            readonly cliJson: boolean;
+            readonly tuiJson: boolean;
+        };
+        readonly override?: string;
+    };
+    readonly cliJson?: {
+        readonly path: string;
+        readonly removed: number;
+        readonly changed: boolean;
+    };
 };

package/dist/cli.js

@@ -10,7 +10,7 @@ import { defaultOpenAiRoutes, legacyFastAliasHelp, modelEffortHelp, openaiModelH
 import { fetchPublicSource } from "./lit-fetch.js";
 import { readPackageMetadata } from "./cli/json.js";
 import { runMotionRuntime } from "./cli/motion-runtime.js";
-import { removeTuiPlugin } from "./cli/tui-config.js";
+import { removeTuiEntries } from "./cli/tui-config.js";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 function helpText() {
@@ -86,7 +86,8 @@ function helpText() {
         "            ships a per-channel capture playbook, and keeps blocked codes separate from fail codes.",
         "  lit-diagram-drawer creates conceptual, editorial, and technical diagrams with packaged type guides,",
         "                     local verifiers, bounded importers, and exports that never install tools.",
-        "  lit-typographic-motion directs films from a treatment: a captured stage page or the type engine.",
+        "  lit-typographic-motion directs films from a treatment: a captured stage page or the type engine,",
+        "                         and seamless README cover loops gated on the decoded WebP.",
         "  Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.",
         "  Each skill resolves its own helpers inside its own installed tree; these skills add no command,",
         "  MCP, agent, authentication, or write authority.",
@@ -138,9 +139,11 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         if (isLoopCommand(parsed.command))
             return await runLoopCommand(parsed.command, parsed.loop, parsed.dryRun);
         if (parsed.command === "doctor")
-            return await doctor(parsed.root);
-        if (parsed.command === "tui")
-            return { exitCode: 0, stdout: JSON.stringify(await removeTuiPlugin(parsed.root, parsed.dryRun), null, 2) };
+            return await doctor(parsed.root, parsed.host);
+        if (parsed.command === "tui") {
+            const removed = await removeTuiEntries(parsed.root, parsed.dryRun, { cliJson: parsed.host !== "v1" });
+            return { exitCode: 0, stdout: JSON.stringify(removed, null, 2) };
+        }
         if (parsed.command === "fetch-public") {
             if (!parsed.fetchPublicUrl)
                 return { exitCode: 2, stderr: "fetch-public requires a URL" };
@@ -154,7 +157,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return { exitCode: output.ok ? 0 : 1, stdout: renderFetchPublicText(output) };
         }
         if (parsed.command === "install") {
-            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt);
+            return await install(parsed.root, parsed.dryRun, parsed.modelSelection, parsed.modelPrompt, parsed.permissionMode, parsed.permissionModeExplicit, parsed.permissionPrompt, options.installProgress, parsed.outputStylePrompt, parsed.host);
         }
         return { exitCode: 2, stderr: `Unknown command: ${parsed.command}` };
     }