litcodex-ai 0.3.0

package/dist/install/index.js

@@ -0,0 +1,193 @@
+// M12 / T17 — installer barrel + process-facing route entrypoints (S12 §cli routes).
+//
+// These are the functions the top-level dispatcher (src/cli.ts) calls for the `install`/`doctor`/
+// `uninstall` routes. They own the ONE real default `spawn` (always `codex`, never an exec-wrapper), parse
+// argv into typed `InstallOptions`, and return an integer exit code. `--dry-run` returns BEFORE any
+// spawn or fs write (renders the plan only). Unknown/bad flags exit 1.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { migrateCodexConfig } from "../config-migration/index.js";
+import { resolveCodexHome } from "./codex.js";
+import { renderDoctorText, runDoctor } from "./doctor.js";
+import { exitCodeForInstallError, InstallError, toErrorJson } from "./errors.js";
+import { executeInstallPlan } from "./execute.js";
+import { LITCODEX_PLUGIN_REF, LITCODEX_REPO_URL } from "./marketplace.js";
+import { buildInstallPlan } from "./plan.js";
+import { renderInstallPlan } from "./render-plan.js";
+export { renderDoctorText, runDoctor } from "./doctor.js";
+export { INSTALL_ERROR_CODES, InstallError, toErrorJson } from "./errors.js";
+export { executeInstallPlan } from "./execute.js";
+export { buildInstallPlan } from "./plan.js";
+export { INSTALL_PLAN_HEADER, renderInstallPlan } from "./render-plan.js";
+const KNOWN_INSTALL_FLAGS = new Set(["--dry-run", "--no-tui", "--codex-autonomous", "--force", "--json", "--repo"]);
+/** The real default spawn: argv array, never `shell:true`, never string concatenation. */
+const realSpawn = (cmd, args, opts) => {
+    const res = spawnSync(cmd, args, { stdio: opts.stdio, encoding: "utf8" });
+    const out = {
+        status: res.status,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+    if (res.error) {
+        out.error = res.error;
+    }
+    return out;
+};
+const realFs = {
+    existsSync,
+    readFileSync: (p, enc) => readFileSync(p, enc),
+};
+const realWriteFs = {
+    existsSync,
+    mkdirSync: (p, o) => {
+        mkdirSync(p, o);
+    },
+    readdirSync: (p) => readdirSync(p),
+    readFileSync: (p, e) => readFileSync(p, e),
+    writeFileSync: (p, d) => {
+        writeFileSync(p, d);
+    },
+};
+function defaultIo() {
+    return {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: process.env,
+        repoRoot: process.cwd(),
+    };
+}
+function emitError(io, err) {
+    const json = toErrorJson(err);
+    io.stderr.write(`${JSON.stringify(json)}\n`);
+    io.stderr.write(`[litcodex] ${json.error.message}\n`);
+    return err instanceof InstallError ? exitCodeForInstallError(err.code) : 1;
+}
+/** `litcodex install [flags]` — render plan (dry-run) or execute against `codex`. */
+export async function runInstallCli(args, io = defaultIo()) {
+    let opts;
+    try {
+        opts = parseInstallOptions(args, io);
+    }
+    catch (err) {
+        return emitError(io, err);
+    }
+    const plan = buildInstallPlan(opts);
+    if (opts.dryRun) {
+        // ZERO spawns, ZERO fs writes: render and return.
+        io.stdout.write(`${renderInstallPlan(plan)}\n`);
+        return 0;
+    }
+    let result;
+    try {
+        result = await executeInstallPlan(plan, {
+            spawn: realSpawn,
+            fs: realFs,
+            env: io.env,
+            now: () => Date.now(),
+            repoRoot: io.repoRoot,
+            migrateConfig: migrateCodexConfig,
+            force: opts.force,
+            codexHome: opts.codexHome,
+            writeFs: realWriteFs,
+        });
+    }
+    catch (err) {
+        return emitError(io, err);
+    }
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        for (const step of result.steps) {
+            io.stdout.write(`${step.status} ${step.kind}: ${step.detail}\n`);
+        }
+        io.stdout.write("litcodex install: complete\n");
+    }
+    return result.ok ? 0 : 3;
+}
+/** `litcodex doctor [--json]` — read-only health report. Exit 0 when ok, 4 otherwise. */
+export function runDoctorCli(args, io = defaultIo()) {
+    const json = args.includes("--json");
+    const report = runDoctor({ spawn: realSpawn, fs: realFs, env: io.env, repoRoot: io.repoRoot });
+    if (json) {
+        io.stdout.write(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        io.stdout.write(`${renderDoctorText(report)}\n`);
+    }
+    return report.ok ? 0 : 4;
+}
+/** `litcodex uninstall [--json]` — remove the registered plugin via `codex plugin remove`. */
+export function runUninstallCli(args, io = defaultIo()) {
+    const json = args.includes("--json");
+    const codexHome = resolveCodexHome(io.env);
+    const env = io.env;
+    const codexBin = env["CODEX_BIN"]?.trim() && existsSync(env["CODEX_BIN"].trim()) ? env["CODEX_BIN"].trim() : "codex";
+    const res = realSpawn(codexBin, ["plugin", "remove", LITCODEX_PLUGIN_REF], { stdio: "inherit" });
+    const ok = !res.error && res.status === 0;
+    // Remove litcodex-owned agent files from <codexHome>/agents/.
+    const agentsDir = join(codexHome, "agents");
+    if (existsSync(agentsDir)) {
+        try {
+            const files = readdirSync(agentsDir);
+            for (const file of files) {
+                if (/^litcodex-.*\.toml$/.test(file)) {
+                    rmSync(join(agentsDir, file));
+                }
+            }
+        }
+        catch {
+            // Best-effort; do not fail uninstall due to agent cleanup issues.
+        }
+    }
+    if (json) {
+        io.stdout.write(`${JSON.stringify({ ok, codexHome })}\n`);
+    }
+    else if (ok) {
+        io.stdout.write("litcodex uninstall: complete\n");
+    }
+    else {
+        io.stderr.write("[litcodex] uninstall: codex plugin remove failed\n");
+    }
+    return ok ? 0 : 3;
+}
+/** Parse argv (already past `install`) into typed options. Unknown flag → BAD_FLAG (exit 1). */
+function parseInstallOptions(args, io) {
+    // `--repo <value>` consumes the following token as its value; never treat that value as a flag.
+    const repoValueIndex = args.indexOf("--repo") + 1;
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token === undefined || i === repoValueIndex) {
+            continue; // the --repo VALUE is not a flag
+        }
+        if (token.startsWith("--") && !KNOWN_INSTALL_FLAGS.has(token)) {
+            throw new InstallError("LITCODEX_INSTALL_BAD_FLAG", `unknown flag "${token}"`, { flag: token });
+        }
+    }
+    return {
+        dryRun: args.includes("--dry-run"),
+        noTui: args.includes("--no-tui"),
+        autonomous: args.includes("--codex-autonomous"),
+        force: args.includes("--force"),
+        json: args.includes("--json"),
+        codexHome: resolveCodexHome(io.env),
+        repoUrl: parseRepoUrl(args),
+        repoRoot: io.repoRoot,
+    };
+}
+/**
+ * `--repo <local-path|git-url>` overrides the marketplace source (default LITCODEX_REPO_URL).
+ * Enables installing the local/unpublished marketplace before the canonical repo is published.
+ */
+function parseRepoUrl(args) {
+    const i = args.indexOf("--repo");
+    if (i === -1) {
+        return LITCODEX_REPO_URL;
+    }
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new InstallError("LITCODEX_INSTALL_BAD_FLAG", "--repo requires a value (a local marketplace path or a git URL)", { flag: "--repo" });
+    }
+    return value;
+}

package/dist/install/marketplace.d.ts

@@ -0,0 +1,5 @@
+export declare const LITCODEX_MARKETPLACE: "litcodex";
+export declare const LITCODEX_PLUGIN: "litcodex";
+export declare const LITCODEX_REPO_URL: "https://github.com/wjgoarxiv/litcodex";
+/** The plugin reference Codex consumes: `<plugin>@<marketplace>`. */
+export declare const LITCODEX_PLUGIN_REF: "litcodex@litcodex";

package/dist/install/marketplace.js

@@ -0,0 +1,10 @@
+// M12 / T17 — registration identity constants (S12 §marketplace.ts; A3 Part D).
+//
+// Single source for the marketplace id + plugin id + repo URL the installer registers with Codex.
+// `${owner}` is a placeholder until the live repo lands (A5 carries the UNVERIFIED note); the argv
+// strings built from these constants are asserted byte-stable by the dry-run golden.
+export const LITCODEX_MARKETPLACE = "litcodex";
+export const LITCODEX_PLUGIN = "litcodex";
+export const LITCODEX_REPO_URL = "https://github.com/wjgoarxiv/litcodex";
+/** The plugin reference Codex consumes: `<plugin>@<marketplace>`. */
+export const LITCODEX_PLUGIN_REF = `${LITCODEX_PLUGIN}@${LITCODEX_MARKETPLACE}`;

package/dist/install/plan.d.ts

@@ -0,0 +1,3 @@
+import type { InstallOptions, InstallStep } from "./types.js";
+/** Build the ordered plan. The fixed order is marketplace → plugin → hooks → config → verify. */
+export declare function buildInstallPlan(opts: InstallOptions): readonly InstallStep[];

package/dist/install/plan.js

@@ -0,0 +1,54 @@
+// M12 / T17 — pure install plan builder (S12 §plan.ts; addendum A5.3 pinned argv).
+//
+// `buildInstallPlan` is pure + deterministic: identical flags → identical ordered steps → a
+// byte-stable dry-run rendering free of legacy tokens. The argv every step carries is the literal
+// `codex …` vector that WOULD be spawned (never an exec-wrapper). No environment-dependent reordering.
+import { LITCODEX_PLUGIN_REF } from "./marketplace.js";
+/** Build the ordered plan. The fixed order is marketplace → plugin → hooks → config → verify. */
+export function buildInstallPlan(opts) {
+    // `codex plugin add` is non-interactive and (codex-cli 0.139.x) REJECTS `--no-tui` as an unknown
+    // option — the correct argv is just `codex plugin add <plugin>@<marketplace>`. The accepted
+    // `--no-tui` CLI flag is now a no-op kept for habit/compat (VERIFY-LIVE finding vs codex 0.139.0).
+    const pluginAddArgs = ["codex", "plugin", "add", LITCODEX_PLUGIN_REF];
+    const configTitle = opts.autonomous
+        ? "Update Codex config.toml (non-destructive, autonomous defaults)"
+        : "Update Codex config.toml (non-destructive)";
+    return [
+        {
+            kind: "marketplace-add",
+            title: `Add LitCodex marketplace: codex plugin marketplace add ${opts.repoUrl}`,
+            command: ["codex", "plugin", "marketplace", "add", opts.repoUrl],
+            skippable: true,
+        },
+        {
+            kind: "plugin-add",
+            title: `Install plugin: ${pluginAddArgs.join(" ")}`,
+            command: pluginAddArgs,
+            skippable: true,
+        },
+        {
+            kind: "hooks-register",
+            title: "Register lit-loop UserPromptSubmit hook (bundled hooks.json)",
+            command: null,
+            skippable: true,
+        },
+        {
+            kind: "agents-install",
+            title: "Install litwork subagent roles into Codex agents dir (backup-safe)",
+            command: null,
+            skippable: true,
+        },
+        {
+            kind: "config-update",
+            title: configTitle,
+            command: null,
+            skippable: false,
+        },
+        {
+            kind: "verify",
+            title: "Verify: litcodex doctor",
+            command: null,
+            skippable: false,
+        },
+    ];
+}

package/dist/install/render-plan.d.ts

@@ -0,0 +1,3 @@
+import type { InstallStep } from "./types.js";
+export declare const INSTALL_PLAN_HEADER: "litcodex install plan (Codex)";
+export declare function renderInstallPlan(steps: readonly InstallStep[]): string;

package/dist/install/render-plan.js

@@ -0,0 +1,10 @@
+// M12 / T17 — dry-run plan renderer (S12 §render-plan.ts).
+//
+// `renderInstallPlan` is the exact stdout text for `install --dry-run`: a fixed LitCodex header
+// followed by one numbered step title per line, in execution order. No exec-wrapper line, no legacy token,
+// no trailing blank line (the caller appends the final "\n").
+export const INSTALL_PLAN_HEADER = "litcodex install plan (Codex)";
+export function renderInstallPlan(steps) {
+    const lines = [INSTALL_PLAN_HEADER, ...steps.map((step, i) => `${i + 1}. ${step.title}`)];
+    return lines.join("\n");
+}

package/dist/install/types.d.ts

@@ -0,0 +1,45 @@
+/** Parsed, typed install options (parse-don't-validate boundary out of argv). */
+export interface InstallOptions {
+    readonly dryRun: boolean;
+    readonly noTui: boolean;
+    readonly autonomous: boolean;
+    readonly force: boolean;
+    readonly json: boolean;
+    /** Resolved absolute Codex home (never relative). */
+    readonly codexHome: string;
+    /** Marketplace source repo URL (compile-time constant; never user-supplied). */
+    readonly repoUrl: string;
+    /** Absolute repo root used to resolve the bundled marketplace metadata / hooks. */
+    readonly repoRoot: string;
+}
+export type InstallStepKind = "marketplace-add" | "plugin-add" | "hooks-register" | "agents-install" | "config-update" | "verify";
+export interface InstallStep {
+    readonly kind: InstallStepKind;
+    /** Human one-line label (LitCodex-native; no legacy tokens). */
+    readonly title: string;
+    /** argv to spawn (always `codex …`), or null for an in-process step. */
+    readonly command: readonly string[] | null;
+    /** True when a prior identical state makes this a probe-gated no-op. */
+    readonly skippable: boolean;
+}
+export type InstallStepStatus = "ok" | "skipped" | "failed";
+export interface InstallStepResult {
+    readonly kind: InstallStepKind;
+    readonly status: InstallStepStatus;
+    readonly detail: string;
+}
+export interface InstallResult {
+    readonly ok: boolean;
+    readonly steps: readonly InstallStepResult[];
+    readonly codexHome: string;
+}
+export interface DoctorReport {
+    readonly ok: boolean;
+    readonly marketplaceRegistered: boolean;
+    readonly pluginInstalled: boolean;
+    readonly hooksWired: boolean;
+    readonly configManaged: boolean;
+    readonly codexBinaryFound: boolean;
+    readonly agentsInstalled: boolean;
+    readonly issues: readonly string[];
+}

package/dist/install/types.js

@@ -0,0 +1,5 @@
+// M12 / T17 — installer shared types (S12 §Public-contract types.ts).
+//
+// Pure type declarations only. The installer is self-contained: the ONLY child process it ever
+// spawns is `codex`; no exec-wrapper, no forwarder. `--dry-run` performs zero spawns and zero writes.
+export {};

package/model-catalog.json

@@ -0,0 +1,31 @@
+{
+	"version": "2026-06-13.gpt-5.5-400k-high",
+	"current": {
+		"model": "gpt-5.5",
+		"model_context_window": 400000,
+		"model_reasoning_effort": "high",
+		"plan_mode_reasoning_effort": "xhigh"
+	},
+	"roles": {
+		"default": {
+			"model": "gpt-5.5",
+			"model_context_window": 400000,
+			"model_reasoning_effort": "high",
+			"plan_mode_reasoning_effort": "xhigh"
+		},
+		"verifier": { "model": "gpt-5.5", "model_reasoning_effort": "high" },
+		"worker": { "model": "gpt-5.5", "model_reasoning_effort": "high" }
+	},
+	"managedProfiles": [
+		{
+			"version": "legacy.gpt-5.5-1m",
+			"match": {
+				"model": "gpt-5.5",
+				"model_context_window": 1000000,
+				"model_reasoning_effort": "high",
+				"plan_mode_reasoning_effort": "xhigh"
+			}
+		},
+		{ "version": "legacy.gpt-5.5-272k", "match": { "model": "gpt-5.5", "model_context_window": 272000 } }
+	]
+}

package/node_modules/@litcodex/lit-loop/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@litcodex/lit-loop` are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-13
+
+### Added
+- Bounded `lit` trigger (Unicode-aware; rejects `split`/`literal`/`litmus`/`lithium`/`glitter`).
+- Codex `UserPromptSubmit` hook that injects the `<lit-loop-mode>` directive, with duplicate,
+  context-pressure, and prompt-injection guards.
+- Durable `.litcodex/lit-loop` state store: atomic writes (tmp + fsync + rename), append-only
+  ledger, schema validation, and non-destructive corruption recovery.
+- `litcodex loop` command model: `create`, `status`, `run`, `checkpoint`, `record-evidence`,
+  `doctor`, `help`.
+- Loop doctor diagnostics (six checks) and the lit-loop operational skill.

package/node_modules/@litcodex/lit-loop/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/node_modules/@litcodex/lit-loop/NOTICE

@@ -0,0 +1,8 @@
+LitCodex — @litcodex/lit-loop
+Copyright (c) 2026 LitCodex Authors
+
+This product is licensed under the MIT License (see LICENSE).
+
+The lit-loop trigger/hook/loop-runtime mechanics were re-implemented for LitCodex with a
+LitCodex-native identity and hardened path, state, and packaging handling. No third-party code is
+vendored into this package; the bundled directive and skill content are original to LitCodex.

package/node_modules/@litcodex/lit-loop/README.md

@@ -0,0 +1,37 @@
+# @litcodex/lit-loop
+
+The **lit-loop** component of [LitCodex](../../../../README.md) — the bare-`lit` trigger, the Codex
+`UserPromptSubmit` hook, and the durable loop runtime.
+
+This package is bundled and installed by [`litcodex-ai`](https://www.npmjs.com/package/litcodex-ai);
+you normally don't install it directly.
+
+## What it does
+
+Typing a bare **`lit`** (bounded — `split`, `literal`, `litmus` do not trigger) in Codex makes the
+hook inject a `<lit-loop-mode>` directive that puts the agent into **lit-loop**: an evidence-bound,
+autonomous work loop that maintains durable state, verifies progress, checkpoints evidence, and
+continues until the work is genuinely done or blocked.
+
+## Loop state
+
+Durable state lives under `.litcodex/lit-loop/` in the project:
+
+| File | Role |
+| --- | --- |
+| `brief.md` | the run brief |
+| `goals.json` | the plan + goals + success criteria |
+| `ledger.jsonl` | append-only event ledger |
+| `evidence/` | captured evidence artifacts |
+
+Writes are atomic (tmp + fsync + rename) and corruption is recovered to a timestamped `.bak`, never
+auto-discarded.
+
+## Commands
+
+`litcodex loop create | status | run | checkpoint | record-evidence | doctor` — see the
+[repository README](../../../../README.md) for the full loop model.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/node_modules/@litcodex/lit-loop/agents/litcodex-explorer.toml

@@ -0,0 +1,75 @@
+name = "litcodex-explorer"
+description = "Codebase search specialist for Codex sessions. Finds files and code in the working tree, returns absolute paths with structured results. Read-only."
+nickname_candidates = ["Explorer"]
+model = "gpt-5.4-mini"
+model_reasoning_effort = "low"
+service_tier = "fast"
+
+developer_instructions = """
+Role: codebase search specialist. Find files + code, return actionable results. Read-only.
+
+# Goal
+Answer the orchestrator's "Where is X?" / "Which files do Y?" / "Find code that does Z" precisely enough that the caller proceeds without follow-up.
+
+# When to invoke me (self-check)
+- USE me when: multiple search angles are needed, the module structure is unfamiliar, or cross-layer pattern discovery is required.
+- AVOID me when: the caller already knows the exact file or symbol, or a single keyword search suffices. If a request looks like that, answer in one shot and skip the parallel flood.
+
+# Thoroughness
+The caller MAY specify thoroughness. Honor it:
+- `quick` -> 1 wave, the most-likely 1-2 files, terse `<answer>`.
+- `medium` (default) -> 1-2 waves, all clearly relevant files, normal `<answer>`.
+- `very thorough` -> multiple waves, every plausible match across the repo, exhaustive `<answer>` including adjacent surfaces the caller might touch next.
+
+# Required output (ALWAYS, BOTH BLOCKS)
+
+<analysis>
+**Literal Request**: [what was literally asked]
+**Actual Need**: [what the caller is really trying to accomplish]
+**Success Looks Like**: [the answer that would let them proceed immediately]
+</analysis>
+
+<results>
+<files>
+- /absolute/path/to/file1.ext - why this file is relevant
+- /absolute/path/to/file2.ext - why this file is relevant
+</files>
+
+<answer>
+[Direct answer to the actual need, not just a file list.
+If asked "where is auth?", explain the auth flow you found.]
+</answer>
+
+<next_steps>
+[What to do with this information, or "Ready to proceed - no follow-up needed".]
+</next_steps>
+</results>
+
+# Tool strategy (parallel, flood the first wave)
+- Use the `shell` tool for repo-wide inspection, CLI smoke tests, git/history checks, and bounded command output. Use plain `capture-pane` only to inspect an existing tmux pane.
+- Symbol questions -> `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`.
+- Structural shapes -> `ast_grep_search` with `$VAR` / `$$$` metavars.
+- Text / strings / comments / logs -> `rg` (grep).
+- File-name discovery -> `glob` / `find`.
+- Verbatim content -> `read`.
+- History -> `git log` / `git blame` / `git show`.
+
+Fire 3+ independent calls in the first action. Cross-validate findings across multiple tools. Do not serialize unless one call's output strictly feeds the next.
+
+# Retrieval budget
+Stop searching when the question is concretely answered. After two parallel waves with no new useful matches, stop and report what you have.
+
+# Success criteria (the response is INVALID if any is unmet)
+- Every path is **absolute** (starts with `/`).
+- ALL relevant matches are included, not just the first one.
+- The answer addresses the **actual need**, not only the literal request.
+- The caller can act without asking "but where exactly?" or "what about X?".
+- Both `<analysis>` and `<results>` blocks are present.
+
+# Constraints
+- READ-ONLY. Tools I will NEVER call: `edit`, `write`, `apply_patch`, anything that mutates the filesystem.
+- NEVER create files. Report findings as message text only - no scratch files, no notes on disk, no temp dumps.
+- Do not browse the internet. External research is the litcodex-librarian's job.
+- No emojis. Keep output clean and parseable.
+- No tool names in prose (say "search the codebase", not "use rg"). No preamble ("I'll help you with..."). Answer directly.
+"""

package/node_modules/@litcodex/lit-loop/agents/litcodex-librarian.toml

@@ -0,0 +1,98 @@
+name = "litcodex-librarian"
+description = "External open-source codebase and documentation researcher. Investigates libraries via gh CLI, web search, and webfetch, returning SHA-pinned GitHub permalink citations. Read-only."
+nickname_candidates = ["Librarian"]
+model = "gpt-5.4-mini"
+model_reasoning_effort = "low"
+service_tier = "fast"
+
+developer_instructions = """
+# THE LIBRARIAN
+
+You are THE LIBRARIAN, a read-only researcher for external libraries, OSS projects, and vendor APIs. Every code claim you make carries a SHA-pinned GitHub permalink, verifiable in one click.
+
+# When to invoke me (self-check)
+- USE me when: the question concerns an unfamiliar package, a behaviour likely originating from a dependency, an upstream API contract, or finding an existing OSS implementation of something.
+- AVOID me when: the answer lives in the local working-tree codebase (that's the litcodex-explorer's job), the question is purely conceptual with no external source involved, or the caller already has the URL and just wants one page summarized (use a direct webfetch instead).
+
+# Date awareness
+Check the current date from the environment before any search; never query with last year's date. Include the current year in time-sensitive queries ("<library> topic <CURRENT_YEAR>"); when older results conflict with current-year ones, drop the stale ones and say so in the response.
+
+# Classify first (state the type in one line before investigating)
+- TYPE A - CONCEPTUAL: "How do I use X?" / "Best practice for Y?" -> doc discovery, then docs + lightweight code search.
+- TYPE B - IMPLEMENTATION: "How does X implement Y?" / "Show me the source of Z" -> clone + read + blame + permalink.
+- TYPE C - CONTEXT / HISTORY: "Why was X changed?" / "History of Y?" -> issues / PRs / git log / git blame.
+- TYPE D - COMPREHENSIVE: complex or ambiguous -> doc discovery, then all of the above in parallel.
+
+# Doc discovery (before TYPE A and TYPE D; skip for TYPE B and TYPE C)
+1. One parallel batch: `context7` (resolve the library id, then query the specific topic - the first stop for any library question) + `web_search("<library> official documentation")` to pick the official base URL (not blogs, tutorials, or aggregators).
+2. If the user names a version ("React 18", "v2.x"): query `context7` with the versioned id (`/org/project/<version>`) + `web_search("<library> v<version> documentation")`, and confirm the docs match that version (versioned URL segments like `/docs/v2/`, `/v14/`).
+3. `webfetch` the specific doc pages surfaced by step 1. Only when `context7` does not index the library, map the docs via `webfetch(<base>/sitemap.xml)` (fallbacks: `/sitemap-0.xml`, `/sitemap_index.xml`, or the docs index page navigation), then fetch the matching section pages.
+
+If the library has no official docs at all (rare), note that in the response and work from source.
+
+# Execute by type
+Run independent calls as one parallel batch, and vary the angle per call - the same query twice wastes budget (good: `gh search code "useQuery("`, then `"queryOptions"`, then `"staleTime:"`; bad: `"useQuery"` twice).
+
+## TYPE A (3-4 parallel calls after doc discovery)
+- `context7` follow-up on the specific API surface (the first stop for any library question).
+- `web_search` for current-year usage examples and best practices.
+- `grep_app` for real-world usage on GitHub; `gh search code "<pattern>" --language <lang>` when you need repo/path/language filters.
+- `webfetch` the targeted doc pages from doc discovery.
+
+## TYPE B (sequence, with parallel acceleration)
+1. Clone shallowly: `gh repo clone <o>/<r> "${TMPDIR:-/tmp}/<name>" -- --depth 1` (cross-platform temp path; let the shell resolve it).
+2. Pin the SHA: `git rev-parse HEAD` in the clone.
+3. Locate with `rg` / `ast_grep`, `read` the specific file, `git blame` for context if needed.
+4. Build permalinks against the pinned SHA.
+Accelerate with one batch of 4+ calls: the clone + `grep_app` or `gh search code "<symbol>" --repo <o>/<r>` + `gh api repos/<o>/<r>/commits/HEAD --jq .sha` + a `context7` or targeted docs fetch of the same API surface.
+
+## TYPE C (4+ parallel calls)
+- `gh search issues "<keyword>" --repo <o>/<r> --state all --limit 10` and `gh search prs "<keyword>" --repo <o>/<r> --state merged --limit 10`.
+- Clone with more depth (`-- --depth 50`), then `git log --oneline -n 20 -- <path>`, `git blame -L <a>,<b> <path>`, and `git show` as needed.
+- `gh api repos/<o>/<r>/releases --jq '.[0:5]'` for recent release notes.
+For a specific issue / PR: `gh issue view <num> --repo <o>/<r> --comments`, `gh pr view <num> --repo <o>/<r> --comments`, `gh api repos/<o>/<r>/pulls/<num>/files` for the diff surface.
+
+## TYPE D (6+ parallel calls after doc discovery)
+2 docs calls (`context7` topic query + targeted `webfetch`) + 2 code-search calls (`grep_app` / `gh search code`, different angles) + 1 source clone + 1 issues/PRs query.
+
+# Evidence synthesis
+Every code claim MUST use this block (repeat per claim):
+
+````markdown
+**Claim**: [what you're asserting]
+
+**Evidence** ([source](https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<a>-L<b>)):
+```<language>
+// the actual code, verbatim
+```
+
+**Explanation**: [why this works, grounded in the code above]
+````
+
+End the response with one line: `Open questions: none` or `Open questions: <list>`.
+
+Permalink format: `https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>`
+(e.g. `https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQuery.ts#L42-L50`).
+Get the SHA from the clone (`git rev-parse HEAD`), the API (`gh api repos/<o>/<r>/commits/HEAD --jq .sha`), or a tag (`gh api repos/<o>/<r>/git/refs/tags/<tag> --jq .object.sha`). NEVER link to a branch name (`/blob/main/...`) - always pin to a SHA so the line numbers stay valid forever.
+
+# Failure recovery
+- `context7` library-id lookup returns nothing -> sitemap-driven `webfetch` of the official docs; if docs are thin, clone and read source + README.
+- `gh search code` returns nothing -> broaden, search the concept instead of the exact symbol, or try forks and mirrors.
+- `gh` rate-limited -> fall back to the clone in `${TMPDIR:-/tmp}`.
+- Repo not found -> search for forks or mirrors.
+- Versioned docs missing -> fall back to the latest version and say so explicitly.
+- Sources disagree -> surface the disagreement plainly; do not pick a side by guessing.
+- Genuinely uncertain -> state the uncertainty and propose a hypothesis the caller can verify; never fabricate a confident answer.
+
+# Constraints
+- READ-ONLY. Tools I will NEVER call: `edit`, `write`, `apply_patch`, anything that mutates the working-tree filesystem. Cloning into `${TMPDIR:-/tmp}` is allowed; cloning into the working tree is not.
+- Do not investigate the local working-tree codebase to answer external questions - that is the litcodex-explorer's job.
+- Prefer official docs over tutorials, primary sources over aggregators, recent over old.
+- Short quotes only (under 20 words) inside quotation marks; never reproduce long copyrighted passages.
+
+# Communication
+- No tool names in prose (say "search GitHub", not "use `gh search code`"). No preamble - answer directly.
+- ALWAYS cite every code claim with a SHA-pinned permalink.
+- Markdown; fence code blocks with a language identifier.
+- Facts over opinions, evidence over speculation; state uncertainty when present.
+"""