@litfamily/litcodex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LitCodex Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/cover.webp" width="100%" alt="LitCodex v5 armory cover" /></p>
+
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B mark" /></p>
+
+<details>
+<summary>Copy ASCII logo</summary>
+
+```
+                             ▄▄▄▄
+                   ▗███▌   ▗██████▖
+ ▗▄▄▄▄▄          ▗▟████▌   ▝██████▘
+ ▐█████        ▗▟██████▌    ▝▀▜█▀▘
+ ▐█████      ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+ ▐█████    ▗▟█████████████████████████ ▐█▀
+ ▐█████    ████████████████████████████▀
+ ▐█████    ██▛▘   ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖
+ ▐█████    ▀    ▄██ ████▌█████████████▌
+ ▐█████       ▄████ ████▌█████████████▌
+ ▐█████     ▄█████▛
+ ▐█████  ▗▟█████▀▘       ▄▄▄▄▄     ▗▖
+ ▐█████ ▐█████▀          █████     ▐▛▀
+ ▐█████ ▐███▀            █████
+ ▐█████ ▐█▀              █████
+ ▐█████ ▝                █████
+ ▐█████▄▄▄▄▄▄▄▖          █████
+ ▐███████████▛           █████
+ ▐██████████▀            █████
+
+LIT · codex
+```
+
+</details>
+
+<p align="center">
+<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/badge-version.svg" alt="1.0.0" /></a>
+<a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/badge-license.svg" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+<a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+</p>
+
+# @litfamily/litcodex
+
+**Keep the work lit.**
+
+**You have been handed a spark.<br>
+Bring it to the work you want to finish.**
+
+A bug to fix. A screen to build. A project to finish.
+
+Starting takes a sentence. Picking up where you left off takes more: the decisions you made,
+the checks you ran, and the next thing to try.
+
+**LIT keeps that spark with your project.** Goals, plans, checked results, and next steps stay in
+local records that a later session can read. An enduring spark means work you can return to;
+it is not a promise that an agent runs forever.
+
+**Where one conversation ends, the next stretch of work can begin.**
+
+Plan, execute, and verify work in Codex CLI. Type `lit` to keep goals, checks, and evidence with your project.
+
+The source tree retains `docs/assets/cover.svg` as the editable, low-bandwidth vector fallback; the WebP above is the README cover.
+
+[한국어](https://github.com/wjgoarxiv/litcodex/blob/main/README-Ko-KR.md) · [Install](#install) · [First lit](#activate-lit) · [Commands](#commands) · [Documentation](#documentation)
+
+## Start with one lit task
+
+Append `lit` to a prompt to activate the Codex CLI hook. It routes the request into the durable loop; Codex still owns model execution.
+
+| Prompt or route | Effect |
+| --- | --- |
+| `lit` | Start a bounded task with goals and checks in the project. |
+| `handoff` or `/lit-handoff` | Carry the checked result and next step to another session. |
+| `lit-plan` | Prepare a plan and success criteria before editing. |
+| `lit start work <approved-plan>` | Execute an approved plan. |
+| `review-work` | Review the change and its evidence. |
+| `litresearch` | Record source-backed research and uncertainty. |
+
+The hook is an entry signal; it does not prove that a model result or visual check completed.
+
+<p align="center"><a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/ignition-poster.png" width="720" alt="Ignition motion poster" /></a></p>
+
+Select the poster for the optional film; this README keeps motion opt-in.
+
+## Practical routes and visual cues
+
+Use `lit` to start a bounded task, `handoff` or `/lit-handoff` to carry checked work forward,
+`lit-plan` to set criteria before editing, `lit start work <approved-plan>` to execute an approved
+plan, `review-work` to inspect the change, and `litresearch` to record sources and uncertainty. Each
+route keeps its expected effect in project-local records; no new slash route is introduced here.
+Host limit: Codex CLI owns hook and agent execution, while authentication, model access, permissions,
+and any visual check remain host capabilities. A route mark or static editorial image is not completion
+evidence.
+
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/litcodex-ignition-1600.webp" width="49%" alt="LitCodex ignition editorial cue" /> <img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/litcodex-continuity-1600.webp" width="49%" alt="LitCodex continuity editorial cue" /></p>
+
+## What is LitCodex
+
+LitCodex adds planning, review, research, and a durable execution loop to Codex CLI. Its `UserPromptSubmit`
+hook routes your request into the right discipline; the bundled library provides 39 skills. A goal is complete
+only after every success criterion passes. The npm package is self-contained and installs without a GitHub clone.
+
+## Install
+
+> Install `@litfamily/litcodex@1.0.0` with the scoped command below. See [migration guidance](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md).
+
+With **Node.js 22+** and **Codex CLI** installed, run:
+
+```sh
+npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex install
+```
+
+The installer registers the plugin, hooks, and agents, then updates managed keys in `~/.codex/config.toml`.
+It asks for the lead model, helper model, and output style. Codex authentication and model access are required
+when you run model work; installation itself does not require GitHub credentials.
+
+Preview changes with `npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex --dry-run install`. For unattended setup, use
+`npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex install --yes`. An explicit `--style <id>` still applies.
+
+For a persistent command:
+
+```sh
+npm install -g @litfamily/litcodex
+litcodex install
+```
+
+> Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex <command>`, such as `npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex doctor`.
+
+For an isolated trial apart from existing settings, follow the [isolated trial guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial).
+Changing only `CODEX_HOME` can still discover settings in your existing home.
+
+Windows supports the installer and CLI shims. Descriptor-dependent Python routes require POSIX and fail
+closed on Windows with `BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME`. See [platform and prompt policy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#install).
+
+## Activate lit
+
+Open Codex in your project, approve the LitCodex hooks in startup review, and type:
+
+```text
+lit add input validation to the signup form
+```
+
+A bare `lit` selects `<lit-loop-mode>`. The hook supplies a compact status mark; the reply begins with
+`▲ LIT · <discipline>`. Codex uses the documented single-line status fallback. `split`, `literal`, and `litmus` stay inert.
+Code spans and fences are ignored; slash-command-style mentions are ignored except the explicit `/litresearch` research route.
+
+The exact bare `lit-scientific-visualization` hook route selects
+`<lit-scientific-visualization-mode>`; it does not install Python dependencies. Both this and
+exact bare `handoff` are exact-only routes.
+
+### Make one small thing
+
+Start in an empty project with a task you can inspect:
+
+```text
+lit build a single-file HTML task list in this folder. Do not install dependencies.
+Check adding and completing a task, and record anything you could not verify.
+```
+
+Look for the result, the checks actually performed, and the unfinished work. A status mark confirms
+routing; it does not prove the page works. Ask for `lit recap` to read the recorded state. Before
+leaving the session, send exact bare `handoff` as its own message. In the next session, ask Codex
+to read that packet and the project goals before continuing.
+
+| Step | What stays with the work |
+| --- | --- |
+| Plan | A goal with checks that can pass or fail |
+| Make | A small result you can inspect |
+| Verify | Evidence for each completed criterion; blockers stay open |
+| Hand off | Decisions, remaining work, and where to resume |
+
+Native Codex goals and the local loop ledger have separate boundaries. A paused or blocked native
+goal needs the documented recovery step below; a handoff does not silently resume it.
+
+## Commands
+
+### In the Codex composer
+
+| Type this | Mode | What it does |
+| --- | --- | --- |
+| `lit` or `lit-loop` | **lit-loop** | Durable, evidence-checkpointed execution |
+| `litwork` | **litwork** | Outcome-first work with manual-QA evidence |
+| `lit-plan` or `lit plan` | **lit-plan** | Planning-only, bounded plan with evidence and a Final DoneClaim |
+| `deep-interview` or `lit deep interview` | **deep-interview** | Planning-only discovery for ambiguous briefs |
+| `litgoal` or `lit goal` | **litgoal** | Bind an objective and criteria into loop state |
+| `lit-recap` or `lit recap` | **lit-recap** | Read-only recap from `.litcodex` ledgers |
+| `lit-comprehend` or `comprehend` | **lit-comprehend** | Build a self-contained explainer outside the worktree |
+| `review-work` or `lit review` | **review-work** | Read-only plan or completed-work review |
+| `litresearch`, `/litresearch`, or `lit research` | **litresearch** | Research journal separating facts, hypotheses, sources, and uncertainty |
+| `lit start work <plan-name>` | **Start Work** | Execute an approved plan with durable evidence |
+| exact bare `handoff` | **lit-handoff** | Create or refresh a secret-safe continuation packet |
+| exact bare `lit-scientific-visualization` | **lit-scientific-visualization** | Load the publication plotting adapter through the hook |
+
+Typing the same mode again in one session is idempotent. Standalone skills can also be selected by exact ID
+from the Codex picker or with a scoped mention, including `$litcodex:lit-handoff` and
+`$litcodex:lit-scientific-visualization`, `$litcodex:lit-korean`, and `$litcodex:lit-fetch`.
+
+### CLI commands
+
+| Command | Purpose |
+| --- | --- |
+| `litcodex install` | Register the LitCodex plugin and hook |
+| `litcodex doctor` | Diagnose installation, loop state, host capabilities, and effective config |
+| `litcodex uninstall` | Remove the plugin and LitCodex-managed config |
+| `litcodex config migrate` | Preview or apply managed Codex config keys |
+| `litcodex hook user-prompt-submit` | Run the host hook entrypoint |
+| `litcodex observer` | Record one proposal from bounded JSON on stdin |
+| `litcodex skill-loop <command>` | Review, approve, reject, roll back, or curate agent-owned skill proposals |
+| `litcodex loop create` | Derive goals and criteria from a brief |
+| `litcodex loop status --json` | Inspect loop state as JSON |
+| `litcodex loop run` | Select the next runnable goal |
+| `litcodex loop record-evidence` | Record a criterion pass, fail, or blocked result |
+| `litcodex loop checkpoint` | Complete a goal only when every criterion passes |
+| `litcodex loop doctor` | Diagnose or recover loop state |
+
+Use the Codex skill picker for the full library. Previous leading skill names redirect for one release;
+see [rename compatibility](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#skill-rename-compatibility) and [CHANGELOG.md](https://github.com/wjgoarxiv/litcodex/blob/main/CHANGELOG.md).
+
+## Loop state
+
+Project state stays under `.litcodex/lit-loop/`: `brief.md`, `goals.json`, `ledger.jsonl`, and `evidence/`.
+Writes are atomic; a damaged goals file is preserved as `.bak`. Local state is excluded from Git and packages.
+See [state and recovery](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#loop-state).
+
+## Verify it worked
+
+```sh
+npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex doctor
+```
+
+`litcodex doctor` checks registration, hooks, config, and host capabilities. `litcodex loop doctor` checks
+project loop state. A successful installation check does not prove authenticated model or child execution.
+
+## Safety
+
+- Plans and evidence stay reviewable. No criterion is marked complete merely because a test command ran.
+- Installation preserves unrelated Codex settings. Preview changes before `--reconfigure`.
+- Skill learning requires explicit review and apply; `autoApply` stays `false`. Only marked agent-owned skills
+  may be changed. [Approval, rollback, and recovery rules](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#skill-learning-loop).
+- The doctor diagnostic core never modifies Codex config, install state, or plugin state. An eligible interactive
+  doctor may show a cached advisory notice. Its detached worker performs a fixed registry refresh at
+  `~/.litcodex/update-check.json`; that worker never installs packages.
+  A separate foreground updater can install a newer global package after eligible interactive management commands.
+  Set `LITCODEX_NO_UPDATE_CHECK=1` to disable both update paths. Failed, `--json`, `--dry-run`, non-TTY, CI,
+  and opt-out doctor paths stay side-effect-free. See [privacy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md).
+- Model routes are configuration choices, not guarantees of access or execution. See [managed model compatibility](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#safety).
+
+## Troubleshooting
+
+- **Pane closes before any output:** the failing stage is unknown. In an already-open terminal, run help,
+  install, and doctor separately and retain each exit status. Follow the [staged trial](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial),
+  then launch the host yourself.
+- No activation: run `litcodex doctor` and check hook approval in Codex.
+- Command missing: use the npx form above or check the npm global bin directory in `PATH`.
+- Native goal paused or blocked: use `/goal resume`, confirm it is active, then retry
+  `litcodex loop run --retry-failed`. Preserve the unfinished goal. [Recovery details](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md#troubleshooting).
+
+## Uninstall
+
+```sh
+npm exec --yes --package @litfamily/litcodex@1.0.0 -- litcodex uninstall
+```
+
+`litcodex uninstall` removes the plugin and LitCodex-managed config while preserving unrelated settings.
+
+## Documentation
+
+- [Usage reference](https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md) — complete routes, model configuration, platform limits, and recovery.
+- [LitCodex contract](https://github.com/wjgoarxiv/litcodex/blob/main/docs/spec/litcodex-contract.md) — hooks, native goal boundaries, and evidence requirements.
+- [Reference analysis](https://github.com/wjgoarxiv/litcodex/blob/main/docs/reference-analysis.md) — design and compatibility decisions.
+- [Release provenance](https://github.com/wjgoarxiv/litcodex/blob/main/docs/release/provenance.md), [publish checklist](https://github.com/wjgoarxiv/litcodex/blob/main/docs/release/publish-checklist.md), and [CHANGELOG.md](https://github.com/wjgoarxiv/litcodex/blob/main/CHANGELOG.md).
+
+The bundled skill library also includes `autoconference`, `autoresearch`, `browser-drive`, `coding-session-audit`,
+`comment-checker`, `debugging`, `frontend-ui-ux`, `lit-commit`, `lit-crucible`, `lit-init`, `lit-korean`, `lit-fetch`,
+`litcodex-contribute-bug-fix`, `litcodex-doctor`, `litcodex-report-bug`, `lsp`, `lsp-setup`, `lit-code`, `refactor`,
+`lit-burnoff`, `skill-observer`, `structural-search`, `lit-team`, `visual-qa`, and `wikify`.
+
+Tests, fixtures, test helpers, and Vitest configuration remain tracked repository coverage and are excluded from npm and installed marketplace payloads.
+
+[Contributing](https://github.com/wjgoarxiv/litcodex/blob/main/CONTRIBUTING.md) · [Security](https://github.com/wjgoarxiv/litcodex/blob/main/SECURITY.md) · [Code of conduct](https://github.com/wjgoarxiv/litcodex/blob/main/CODE_OF_CONDUCT.md) · [Support](https://github.com/wjgoarxiv/litcodex/blob/main/SUPPORT.md) · [Privacy](https://github.com/wjgoarxiv/litcodex/blob/main/docs/privacy.md)
+
+## Ignition motion
+
+Select the poster to watch the 10-second film.
+
+<p align="center"><a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.0/readme-assets/ignition-poster.png" width="720" alt="Ignition motion graphic poster" /></a></p>
+
+[Animated GIF](https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-readme.gif) · [Media and icon credits](https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/README.md)
+
+## License
+
+MIT

package/bin/litcodex.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Authored ESM entry for the `litcodex` bin (A3 D1: self-contained CLI).
+//
+// This file owns the shebang and process.exit. It imports the compiled,
+// self-contained dispatcher from ../dist/cli.js and runs it. It performs NO
+// forwarding and spawns NO child process — all routing lives in the dispatcher.
+
+import { runCli } from "../dist/cli.js";
+
+const exitCode = await runCli(process.argv.slice(2));
+
+process.exit(exitCode);

package/dist/auto-update.d.ts

@@ -0,0 +1,27 @@
+import { type CheckGate } from "./update-check.js";
+export declare const FOREGROUND_AUTO_UPDATE_TIMEOUT_MS = 55000;
+export interface ForegroundAutoUpdateOptions extends CheckGate {
+    readonly current: string;
+    readonly stderr: NodeJS.WritableStream;
+    readonly cwd?: string;
+    readonly helperPath?: string;
+}
+export interface ForegroundAutoUpdateReceipt {
+    readonly status: "updated" | "up-to-date" | "skipped" | "failed" | "unknown-state" | "locked" | "throttled";
+    readonly reason?: string;
+    readonly latestVersion?: string;
+    readonly verificationStatus?: "verified" | "mismatch" | "unavailable" | "not-run";
+    readonly verifiedVersion?: string;
+    readonly verificationDetail?: string;
+    readonly doctorStatus?: "passed" | "failed" | "unavailable" | "not-run";
+    readonly doctorDetail?: string;
+    readonly receiptPath?: string;
+}
+/**
+ * Run the installed component's updater synchronously after a successful eligible command.
+ *
+ * The detached cache-only notifier remains a separate route. This helper intentionally waits for
+ * the foreground process and carries only typed command metadata into the updater child.
+ */
+export declare function runForegroundAutoUpdate(options: ForegroundAutoUpdateOptions): ForegroundAutoUpdateReceipt | null;
+export declare function resolveAutoUpdateHelper(): string | null;

package/dist/auto-update.js

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { shouldCheck } from "./update-check.js";
+export const FOREGROUND_AUTO_UPDATE_TIMEOUT_MS = 55_000;
+/**
+ * Run the installed component's updater synchronously after a successful eligible command.
+ *
+ * The detached cache-only notifier remains a separate route. This helper intentionally waits for
+ * the foreground process and carries only typed command metadata into the updater child.
+ */
+export function runForegroundAutoUpdate(options) {
+    if (!shouldCheck(options))
+        return null;
+    const helper = options.helperPath ?? resolveAutoUpdateHelper();
+    if (!helper || !existsSync(helper))
+        return null;
+    const helperEnv = {
+        ...options.env,
+        ["LITCODEX_CURRENT_VERSION"]: options.current,
+    };
+    const result = spawnSync(process.execPath, [helper, "run-management", `--current-version=${options.current}`, `--argv-json=${JSON.stringify(options.argv)}`], {
+        cwd: options.cwd ?? process.cwd(),
+        env: helperEnv,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+        timeout: FOREGROUND_AUTO_UPDATE_TIMEOUT_MS,
+        killSignal: "SIGTERM",
+    });
+    const receipt = typeof result.stdout === "string" ? parseReceipt(result.stdout) : null;
+    if (receipt === null) {
+        if (result.status === 0 && result.error === undefined && result.signal === null)
+            return null;
+        const detail = result.error?.message ??
+            (result.signal ? `helper terminated:${result.signal}` : `helper exit:${String(result.status)}`);
+        const blocked = { status: "unknown-state", reason: detail };
+        options.stderr.write(`\n⚠️ Foreground update barrier could not produce a receipt: ${detail}. Run litcodex doctor.\n`);
+        return blocked;
+    }
+    if (receipt.status === "updated") {
+        options.stderr.write(`\n🔥 Foreground update barrier applied ${options.current} → ${receipt.latestVersion ?? "latest stable"} (version + doctor verified ${receipt.verifiedVersion ?? receipt.latestVersion ?? "stable target"}).\n`);
+    }
+    else if (receipt.status === "failed") {
+        options.stderr.write(`\n⚠️ Foreground update barrier failed: ${receipt.reason ?? "unknown error"}.\n`);
+    }
+    else if (receipt.status === "unknown-state") {
+        options.stderr.write(`\n⚠️ Foreground update barrier left installation state unknown: ${receipt.reason ?? "rollback failed"}. Run litcodex doctor.\n`);
+    }
+    return receipt;
+}
+export function resolveAutoUpdateHelper() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "../../plugins/litcodex/components/auto-update/dist/cli.js"),
+        join(here, "../marketplace/plugins/litcodex/components/auto-update/dist/cli.js"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+function parseReceipt(raw) {
+    const line = raw.trim().split("\n").at(-1);
+    if (line === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        const value = parsed;
+        const status = value["status"];
+        if (status !== "updated" &&
+            status !== "up-to-date" &&
+            status !== "skipped" &&
+            status !== "failed" &&
+            status !== "unknown-state" &&
+            status !== "locked" &&
+            status !== "throttled") {
+            return null;
+        }
+        return {
+            status,
+            ...(typeof value["reason"] === "string" ? { reason: value["reason"] } : {}),
+            ...(typeof value["latestVersion"] === "string" ? { latestVersion: value["latestVersion"] } : {}),
+            ...(value["verificationStatus"] === "verified" ||
+                value["verificationStatus"] === "mismatch" ||
+                value["verificationStatus"] === "unavailable" ||
+                value["verificationStatus"] === "not-run"
+                ? { verificationStatus: value["verificationStatus"] }
+                : {}),
+            ...(typeof value["verifiedVersion"] === "string" ? { verifiedVersion: value["verifiedVersion"] } : {}),
+            ...(typeof value["verificationDetail"] === "string"
+                ? { verificationDetail: value["verificationDetail"] }
+                : {}),
+            ...(value["doctorStatus"] === "passed" ||
+                value["doctorStatus"] === "failed" ||
+                value["doctorStatus"] === "unavailable" ||
+                value["doctorStatus"] === "not-run"
+                ? { doctorStatus: value["doctorStatus"] }
+                : {}),
+            ...(typeof value["doctorDetail"] === "string" ? { doctorDetail: value["doctorDetail"] } : {}),
+            ...(typeof value["receiptPath"] === "string" ? { receiptPath: value["receiptPath"] } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { Gpt56Profile, ReasoningEffort } from "./config-migration/gpt56-policy.js";
+/** Pure model-route readers used by the synchronous dry-run dispatcher. */
+export declare function readModelChoice(args: readonly string[]): Gpt56Profile;
+export declare function readLeadModelChoice(args: readonly string[]): string;
+export declare function readSubagentModelChoice(args: readonly string[]): string;
+export declare function readSubagentEffortChoice(args: readonly string[]): ReasoningEffort;
+export declare function readEffortChoice(args: readonly string[]): ReasoningEffort;

package/dist/cli-model-route.js

@@ -0,0 +1,47 @@
+/** Pure model-route readers used by the synchronous dry-run dispatcher. */
+export function readModelChoice(args) {
+    if (!args.includes("--model"))
+        return "astra";
+    const value = args[args.indexOf("--model") + 1];
+    if (value === "gpt-6-astra" || value === "astra")
+        return "astra";
+    if (value === "sol" || value === "gpt-5.6")
+        return "sol";
+    if (value === "terra")
+        return "terra";
+    return "luna";
+}
+export function readLeadModelChoice(args) {
+    const value = args[args.indexOf("--model") + 1];
+    if (value === "gpt-6-astra" || value === "astra")
+        return "gpt-6-astra";
+    if (value === "sol")
+        return "gpt-5.6-sol";
+    if (value === "gpt-5.6")
+        return "gpt-5.6";
+    return value === "terra" ? "gpt-5.6-terra" : value === "luna" ? "gpt-5.6-luna" : "gpt-6-astra";
+}
+export function readSubagentModelChoice(args) {
+    const value = args[args.indexOf("--subagent-model") + 1];
+    if (value === "gpt-6-astra" || value === "astra")
+        return "gpt-6-astra";
+    if (value === "gpt-5.6")
+        return "gpt-5.6";
+    return value === "terra" ? "gpt-5.6-terra" : value === "luna" ? "gpt-5.6-luna" : "gpt-5.6-luna";
+}
+export function readSubagentEffortChoice(args) {
+    const value = args[args.indexOf("--subagent-effort") + 1];
+    const model = readSubagentModelChoice(args);
+    return effortForModel(value, model, "max");
+}
+export function readEffortChoice(args) {
+    const value = args[args.indexOf("--effort") + 1];
+    return effortForModel(value, readLeadModelChoice(args), "xhigh");
+}
+function effortForModel(value, model, fallback) {
+    if (model === "gpt-6-astra" &&
+        (value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max")) {
+        return value;
+    }
+    return value === "high" || value === "xhigh" || value === "max" ? value : fallback;
+}

package/dist/cli.d.ts

@@ -0,0 +1,23 @@
+/** Error code emitted when a subcommand is not in the routing table. */
+export declare const UNKNOWN_COMMAND_CODE: "LITCODEX_INSTALL_UNKNOWN_COMMAND";
+/** Router usage code (EX_USAGE) for an unknown `config` sub-subcommand. */
+export declare const CONFIG_USAGE_EXIT_CODE: 64;
+/** Outcome of dispatching an argv vector. Pure: no process side effects. */
+export interface DispatchResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * Pure dispatcher. Parses argv (already sliced past `node bin`), strips the position-independent
+ * `--dry-run` flag, answers `--help`/`--version` locally, and routes the first non-flag token.
+ * Unknown token → exit 1. No process spawns. No forwarding.
+ */
+export declare function dispatch(argv: readonly string[]): DispatchResult;
+/**
+ * Async process entry used by `bin/litcodex.js`. It owns the side-effecting routes: install/doctor/
+ * uninstall (install/* modules, which are the ONLY code that ever spawns `codex`), `config migrate`
+ * (M13, in-process), and the bundled `@litcodex/lit-loop` runtime routes `loop`/`hook`/`observer`. Returns the
+ * integer exit code; the bin owns `process.exit`. No forwarding, no exec-wrapper, no harness.
+ */
+export declare function runCli(argv: readonly string[]): Promise<number>;