context-slice 1.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContextSlice contributors
+
+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,349 @@
+# ContextSlice
+
+> Less context. Unchanged signal.
+>
+> Give your coding assistant the smallest useful slice of your codebase.
+
+<p align="center">
+  <img src="assets/context-slice-hero.png" alt="Source files converging into a focused ContextSlice context" width="100%" />
+</p>
+
+You just joined a codebase with hundreds of files. Where do you start without
+feeding an entire repository to an AI assistant?
+
+ContextSlice builds a small, task-specific context from Java, TypeScript, TSX,
+JavaScript, Python, Rust, and Go source. It finds the target symbol, follows
+relevant callers and callees, and reports what was included or left out.
+
+It is local, read-only, and deterministic: Tree-sitter performs the structural
+analysis, SQLite stores the index, and no source code is sent to a hosted
+service by ContextSlice.
+
+## Quick start
+
+### Claude Code plugin
+
+Install it directly from the GitHub marketplace:
+
+```text
+/plugin marketplace add nvxtien/context-slice
+/plugin install context-slice@context-slice-marketplace
+```
+
+The plugin provides a skill that tells Claude Code to request a focused
+ContextSlice preview before reading source files. The MCP server then targets
+the project Claude Code has open.
+
+### Codex plugin
+
+Add the GitHub marketplace to Codex:
+
+```sh
+codex plugin marketplace add nvxtien/context-slice
+codex plugin marketplace list
+```
+
+Then open `/plugins`, choose `Context Slice Marketplace`, and install
+`context-slice`. The plugin includes the same ContextSlice skill and stdio MCP
+server for the project Codex has open.
+
+### CLI and MCP
+
+```sh
+context-slice init
+context-slice preview "explain the payment retry flow" --explain
+```
+
+For a new checkout, see [Installation](#installation) for the local build and
+MCP setup.
+
+## Why use it
+
+- Whole files contain too much unrelated code.
+- Task names are often enough to locate the relevant symbol, callers, and callees.
+- Strict budgets make omissions visible instead of silently overflowing context.
+- Unresolved dynamic dispatch stays unresolved rather than being guessed.
+- The target repository is never edited; only `.context-slice/` is written locally.
+
+## Supported languages
+
+| Language   | Extensions                     | Notes                                                                     |
+| ---------- | ------------------------------ | ------------------------------------------------------------------------- |
+| Java       | `.java`                        | Classes, interfaces, records, enums, methods, constructors                |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.d.ts` | Imports, re-exports and barrels, overloads, arrow functions               |
+| TSX        | `.tsx`                         | React components, handlers, JSX component references                      |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs`   | Same adapter as TypeScript (JS is parsed as untyped TS); CommonJS (`require`/`module.exports`) is not recognized as imports/exports — see Known limitations below |
+| Python     | `.py`, `.pyi`                  | Packages and `__init__` re-exports, decorators, `self`/`cls`, dataclasses |
+| Rust       | `.rs`                          | Functions, structs, enums, traits, impls, modules; `use`/re-export resolution; self/associated/trait call resolution |
+| Go         | `.go`                          | Functions, methods (incl. generic receivers), structs, interfaces, struct embedding and interface satisfaction; same-package, import-qualified and receiver-typed call resolution |
+
+One repository can hold all of them. See [docs/typescript-support.md](docs/typescript-support.md), [docs/python-support.md](docs/python-support.md) and [docs/rust-support.md](docs/rust-support.md) for what each language's resolution does and does not cover.
+
+## Scope
+
+- Tree-sitter structural and semantic analysis; no compiler, JDT, tsserver, Pyright, mypy, or LSP dependency, and no code is executed.
+- A local stdio MCP server and a local SQLite cache under `.context-slice/`.
+- Integrates with Codex and Claude Code through one stable command: `context-slice mcp`.
+- Validated on macOS arm64 with Node 20 and Node 22. Other platforms are expected to work but are unverified.
+
+## Installation
+
+### Codex plugin (GitHub marketplace)
+
+This repository includes a portable Codex plugin manifest and a separate
+Codex marketplace entry backed by the npm runtime package. After publishing
+the package, add the marketplace and install `context-slice` from `/plugins`:
+
+```sh
+codex plugin marketplace add nvxtien/context-slice
+```
+
+Restart Codex after changing the plugin or marketplace files so it refreshes
+the local marketplace snapshot.
+
+### Claude Code plugin (GitHub marketplace)
+
+This repository is also a Claude Code plugin. For local development or a local
+checkout, use the path form instead:
+
+```sh
+git clone https://github.com/nvxtien/context-slice.git
+cd context-slice
+npm ci
+npm run build
+```
+
+```text
+/plugin marketplace add /absolute/path/to/context-slice
+/plugin install context-slice@context-slice-marketplace
+```
+
+The current plugin runs the compiled `dist/` output, so a local checkout must
+run `npm ci` and `npm run build` before first use. Re-run `npm run build` after
+pulling updates. Its MCP server targets `${CLAUDE_PROJECT_DIR}`, not the plugin
+repository itself.
+
+### Local development
+
+ContextSlice is not published to npm yet. From this checkout, install and link the local executable:
+
+```sh
+npm ci
+npm run build
+npm link
+```
+
+### Tarball validation
+
+The package is publish-ready but is not currently published to the npm registry. Build and install the release-candidate tarball from a checkout (`npm ci` is required because `npm pack` compiles TypeScript first):
+
+```sh
+npm ci
+npm pack
+npm install -g ./context-slice-1.8.2.tgz
+context-slice --version
+```
+
+Node.js 20 or newer is required. `npm install` downloads the native `better-sqlite3` and `tree-sitter` builds for your platform, so it needs registry access.
+
+The isolated packaging smoke test uses a temporary npm prefix and does not depend on `npm link`:
+
+```sh
+npm run benchmark:v08
+```
+
+Registry installation (`npm install -g context-slice`) and `npx context-slice` remain publication-dependent and are not claimed as supported yet.
+
+### CLI examples
+
+Then, in a Java repository:
+
+```sh
+cd /absolute/path/to/my-java-project
+context-slice init
+context-slice preview "explain payment retry flow" --explain
+```
+
+`init` creates `.context-slice/index.sqlite` automatically. Repository discovery uses `--repo` when given, otherwise the nearest Git root, otherwise the working directory.
+
+In a TypeScript or TSX repository the workflow is identical:
+
+```sh
+cd /absolute/path/to/my-typescript-project
+context-slice init
+context-slice preview "explain the order create flow" --explain
+```
+
+```text
+Target: OrderService.create
+Context: 139/1200 tokens; 5 items included
+
+Included:
+- task target: OrderService.create — Selected because the task names create.
+- direct caller: createOrder — Direct caller of OrderService.create.
+- direct callee: SqlOrderRepository.save — Direct callee of OrderService.create.
+```
+
+In a Rust repository the workflow is identical:
+
+```sh
+cd /absolute/path/to/my-rust-project
+context-slice init
+context-slice preview "explain the retry loop" --explain
+```
+
+`status` reports the file count per extension, so a mixed repository shows `.java`, `.ts`, `.tsx` and `.rs` separately.
+
+Use `context-slice --version` and `context-slice --help` to inspect the installed package without relying on the source checkout.
+
+### Cache, cleanup, and uninstall
+
+The only files ContextSlice writes are in `<repository>/.context-slice/`. That directory contains its own `.gitignore`, so it never shows up in `git status` and you do not need to edit your repository's `.gitignore`. ContextSlice never writes into its installed package directory.
+
+- Rebuild from scratch: `rm -rf .context-slice && context-slice init`
+- Remove ContextSlice from a repository: `rm -rf .context-slice`
+- Uninstall the CLI: `npm uninstall -g context-slice` (repository caches are left in place; remove them as above)
+
+Caches are versioned. A cache written by a different index schema, older or newer, is discarded and rebuilt automatically; it is never reused.
+
+## CLI workflow
+
+```sh
+context-slice init
+context-slice status
+context-slice doctor
+context-slice preview "explain retryPayment" --budget 1200 --explain
+context-slice preview "explain retryPayment" --json
+context-slice mcp
+```
+
+| Command          | Purpose                                                          |
+| ---------------- | ---------------------------------------------------------------- |
+| `init`           | Discover the repository and create/refresh the local index.      |
+| `index`          | Refresh the index explicitly.                                    |
+| `status`         | Show readiness, schema, cache freshness, and last refresh.       |
+| `doctor`         | Check repository, Java source, cache, and MCP command readiness. |
+| `preview <task>` | Return a deterministic, strict-budget context preview.           |
+| `mcp`            | Start the stdio MCP server with the stable public command.       |
+
+Use `--repo /absolute/path` to select a repository. `--json` provides a stable automation-oriented result. Normal commands are quiet; `--explain` displays why each item was included or omitted.
+
+Exit codes are `0` for success, `2` for user or configuration errors, and `1` for unexpected failures. Errors include a remediation, for example increasing `--budget` when the selected target cannot fit.
+
+## Example: inspectable context reduction
+
+```text
+Target: demo.PaymentService.retryPayment
+Context: 286/1200 tokens; 3 items included
+
+Included:
+- task target: demo.PaymentService.retryPayment — Selected because the task names retryPayment.
+- direct caller: demo.PaymentController.retry — Direct caller of demo.PaymentService.retryPayment.
+- direct callee: demo.PaymentService.audit — Direct callee of demo.PaymentService.retryPayment.
+```
+
+ContextSlice may also include sibling members that share state or local semantics with the target — a field it writes, the getter that exposes it, the constructor that supplies a dependency — plus a declaration-line skeleton of the enclosing type. It does not expand to the whole class or file. See [docs/context-composition.md](docs/context-composition.md).
+
+The target body is always first. Related symbols use compact skeletons. The command never silently exceeds its budget; skipped candidates are reported as `context budget`, and unresolved calls remain unresolved rather than being guessed.
+
+## Codex setup
+
+After installing ContextSlice, register its one stable MCP command for a Java repository:
+
+```sh
+codex mcp add context-slice -- context-slice mcp --repo /absolute/path/to/my-java-project
+codex mcp list
+```
+
+Codex also supports project-scoped configuration in `.codex/config.toml` for trusted projects. See the [official OpenAI MCP documentation](https://developers.openai.com/es-419/docs/extend/mcp?surface=cli) for the current Codex CLI and configuration options.
+
+Suggested assistant instruction:
+
+```text
+For Java implementation or explanation tasks, request context.preview with the task first.
+Use the target, inclusion explanations, omissions, and unresolved calls to decide whether to
+request context.symbol, context.callers, or context.slice. Do not assume unresolved runtime
+dispatch has a concrete implementation.
+```
+
+## Claude Code setup
+
+Use the equivalent local stdio registration for the same command:
+
+```sh
+claude mcp add --transport stdio context-slice -- context-slice mcp --repo /absolute/path/to/my-java-project
+claude mcp list
+```
+
+Verify command syntax against `claude mcp --help` in the installed Claude Code version before sharing configuration. ContextSlice itself speaks standard stdio MCP; this repository does not claim to have exercised every Claude Code release.
+
+## How it works
+
+1. Discover a Java repository and scan source while ignoring common generated/build directories.
+2. Store symbols, call edges, hashes, schema version, and refresh time in a local SQLite cache.
+3. Refresh before preview or MCP tool execution so changed Java files are not silently served stale.
+4. Select a target from task text, then include the target body plus ranked direct callers/callees until the strict token budget is full.
+
+Available MCP tools are `context.search`, `context.symbol`, `context.callers`, `context.preview`, `context.slice`, and `context.diff`. MCP stdout contains protocol messages only; diagnostics must not corrupt stdio framing.
+
+## Trust and explainability
+
+ContextSlice is deliberately conservative:
+
+- Context previews use only task text, repository source, index data, and configuration. They do not read benchmark answers, required facts, expected symbols, or manual baselines.
+- Call resolution distinguishes exact, probable, and unresolved edges. It does not invent runtime dispatch targets.
+- `CURRENT`, `STALE`, `REFRESHING`, and `ERROR` are the workflow state vocabulary. The CLI exposes the observable cache state; preview/MCP refresh before serving context.
+- Preview, status, doctor, and MCP lookup operations are read-only except for the local cache.
+
+## Benchmarks
+
+Run the workflow benchmark locally:
+
+```sh
+npm run benchmark:v07
+```
+
+It writes [JSON](benchmarks/results/v0.7-developer-workflow.json) and [Markdown](benchmarks/results/v0.7-developer-workflow.md) reports with fresh init, cold index, first/warm preview, one-file refresh, and first/subsequent MCP query timings. Timings apply only to the recorded local fixture environment. Codex/Claude telemetry is optional and is reported as unavailable when the runtime provides none.
+
+`npm run benchmark:v03` through `benchmark:v06` first run `npm run benchmark:checkouts`, which fetches the pinned benchmark repositories from `benchmarks/repositories.json` (network required; about 120 MB).
+
+Run `npm run benchmark:v08` for the tarball packaging, isolated installation, upgrade, uninstall, MCP, path-with-spaces, nested-cwd, publish-dry-run, and clean-room self-trial report in [JSON](benchmarks/results/v0.8-packaging-installation.json) and [Markdown](benchmarks/results/v0.8-packaging-installation.md). External developer participation is explicitly deferred; this is not a multi-user study.
+
+Earlier semantic/context measurements remain available:
+
+In the 15-task Java benchmark across three pinned Java repositories, ContextSlice reduced median context size by 94.55% while preserving 100% required-fact recall and 100% retrieval recall. In the separate 15-task TypeScript benchmark across three pinned TypeScript/TSX repositories, it reduced median context size by 83.32% with 95.56% required-fact recall and 100% retrieval recall. Context sizes are deterministic estimates from the built-in estimator, not assistant telemetry, so these are estimated token reductions rather than observed input token usage. The two benchmarks use different repositories and tasks and are not comparable to each other.
+
+Run the TypeScript benchmark with `npm run benchmark:v11`; its report is [v1.1 TypeScript support](benchmarks/results/v1.1-typescript-support.md).
+
+Rust support is measured separately across three pinned repositories (walkdir, mini-redis, ripgrep's `crates/ignore`). Module-path assignment, `use` resolution and re-export resolution were measured on real repositories (module resolution 64-100% depending on crate layout, anchored `use` resolution 100%, re-export resolution 100%; see [v1.5 Phase 1](benchmarks/results/v1.5-phase1-rust-real-repositories.md)). In the 15-task Rust benchmark across the same three repositories, ContextSlice reduced median context size by 93.52% while preserving 100% required-fact recall and 100% retrieval recall, with 0% whole-file fallback; see [v1.5 Phase 3](benchmarks/results/v1.5-phase3-rust-tasks.md). Rust resolution is static analysis, Tree-sitter-first: there is no rust-analyzer or rustc dependency, macro-generated semantics may remain unresolved, and trait dispatch may remain conservative (structural evidence only).
+
+- [v0.6 developer context efficiency](benchmarks/results/v0.6-developer-context-efficiency.md) compares auditable manual whole-file baselines with ContextSlice on pinned Java repositories. Token counts are deterministic estimates unless telemetry is explicitly available.
+- [v0.5 semantic call resolution](benchmarks/results/v0.5-semantic-call-resolution.md) documents declared versus runtime target limitations.
+- [v0.4 symbol index hardening](benchmarks/results/v0.4-symbol-index-hardening.md) documents stable symbol identity and lookup behavior.
+
+## Limitations
+
+- Java, TypeScript, TSX, JavaScript, Python, Rust and Go only; no other languages, embeddings, vector database, compiler, tsserver, type checker, rust-analyzer, rustc, or LSP integration.
+- Python is dynamic: receivers built by factories, `getattr`, dynamic imports and monkey patching stay unresolved rather than guessed.
+- Rust: `#[cfg(...)]` alternatives are all attached as probable call targets and all reachable via context composition (`runtimeTargetIds`), not just the first-listed one. The macro-argument call-recovery denylist covers format/log/assert/panic-style macros plus `anyhow!`/`bail!`/`matches!`; `ensure!`/`dbg!` are deliberately not denylisted (their arguments are genuine expressions). `Cargo.toml` is read for workspace crate-name resolution (`[package]` + `[workspace].members`, including simple `dir/*` globs); still inferred from directory layout only within a single crate (e.g. a crate's own `tests/`/`src/bin/*` referencing it by name is classified external).
+- TypeScript resolution is structural. Receivers whose type needs inference, CommonJS `require`, and imports that leave the checked-out source stay unresolved rather than guessed.
+- JavaScript reuses the TypeScript adapter as-is (JS is a syntactic subset of TS). CommonJS (`require()`/`module.exports`) is not recognized as imports/exports at all — only ES `import`/`export` syntax is; symbol and call extraction are unaffected by module system. A property-assigned function expression (`obj.method = function(){}`) at module level IS extracted as a symbol; `module.exports`/`exports` targets are left alone, per the CommonJS limitation above. See [benchmarks/results/v1.7-javascript-support.md](benchmarks/results/v1.7-javascript-support.md).
+- Go resolution reaches across packages within the same module (interface satisfaction, and method calls through a package-qualified local variable), and `go.work` multi-module workspaces are supported. Interface satisfaction now matches exact method signatures, not just names, and a constructor-typed local variable (`x := NewFoo()`) resolves by the constructor's real declared return type. Still: struct embedding's own promotion lookup stays same-package. See [benchmarks/results/v1.6-go-support.md](benchmarks/results/v1.6-go-support.md).
+- Target selection from task text is heuristic and may choose a nearby but not ideal symbol. Naming the method in the task gives a better slice.
+- Tree-sitter analysis cannot prove runtime dispatch, framework-generated implementations, or all generic/fluent call behavior.
+- Token counts are estimates, not model-provider usage telemetry.
+- Sibling composition uses syntactic evidence (`this.field` and Java field names). State shared through an intermediate object is not detected.
+- The local index is an aid to request context, not a substitute for code review or tests.
+- Validated on macOS arm64 (Node 20.19.5 and 22.12.0). Linux and Windows are unverified.
+- Usability evidence comes from a scripted self clean-room trial; no external developer trial has been run yet.
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm test
+npm run benchmark:v07
+```
+
+`npm run release:rc` performs the v0.9 clean-room release-candidate validation: fresh clone, `npm ci`, build, tests, regressions, `npm pack`, and an isolated install with a temporary `HOME` and npm cache against a freshly cloned Java repository. See [docs/release-readiness-v0.9.md](docs/release-readiness-v0.9.md) and [CHANGELOG.md](CHANGELOG.md).

package/dist/src/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { ProjectIndex } from "./indexer/index.js";
+import { packageInfo } from "./package-info.js";
+import { buildPreview } from "./workflow/preview.js";
+import { WorkflowError } from "./workflow/errors.js";
+import { resolveRepositoryRoot } from "./workflow/repository.js";
+function usage() {
+    return [
+        "Usage: context-slice <init|index|status|doctor|preview|mcp> [options]",
+        "",
+        "Options:",
+        "  --repo <path>     Repository root (defaults to nearest Git root)",
+        "  --budget <tokens> Strict token budget for preview",
+        "  --json            Emit stable JSON output",
+        "  --explain         Include inclusion and omission explanations",
+        "  --verbose         Include additional operational detail",
+        "",
+        "Commands:",
+        "  init              Create or refresh the repository index",
+        "  index             Refresh the repository index",
+        "  status            Show cache freshness and readiness",
+        "  doctor            Diagnose repository and cache setup",
+        "  preview <task>    Build a strict-budget context preview",
+        "  mcp               Start the stdio MCP server",
+    ].join("\n");
+}
+function parse(argv) {
+    const result = {
+        positional: [],
+        json: false,
+        explain: false,
+        verbose: false,
+        version: false,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (!result.command && !value.startsWith("-")) {
+            result.command = value;
+            continue;
+        }
+        if (value === "--repo") {
+            result.repository = argv[++index];
+            continue;
+        }
+        if (value === "--budget") {
+            const raw = argv[++index];
+            const budget = Number(raw);
+            if (!Number.isInteger(budget) || budget <= 0)
+                throw new WorkflowError("INVALID_ARGUMENT", `Invalid --budget value: ${raw ?? "missing"}`, "Pass a positive integer token budget.");
+            result.budget = budget;
+            continue;
+        }
+        if (value === "--json") {
+            result.json = true;
+            continue;
+        }
+        if (value === "--explain") {
+            result.explain = true;
+            continue;
+        }
+        if (value === "--verbose") {
+            result.verbose = true;
+            continue;
+        }
+        if (value === "--version") {
+            result.version = true;
+            continue;
+        }
+        if (value === "--help" || value === "-h") {
+            result.command = "help";
+            continue;
+        }
+        if (value.startsWith("-"))
+            throw new WorkflowError("INVALID_ARGUMENT", `Unknown option: ${value}`, "Run context-slice --help to see supported options.");
+        result.positional.push(value);
+    }
+    return result;
+}
+function plural(count, word) {
+    return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function print(value, args, command, human) {
+    process.stdout.write(args.json
+        ? `${JSON.stringify({ ok: true, command, result: value }, null, 2)}\n`
+        : `${human}\n`);
+}
+function renderPreview(preview, explain) {
+    const lines = [`Target: ${preview.target.qualifiedName ?? preview.target.name}`];
+    if (preview.baseline.wholeFileTokens > 0)
+        lines.push(`Saved ${Math.round(preview.baseline.reduction * 100)}% context ` +
+            `(${preview.estimatedTokens} vs ${preview.baseline.wholeFileTokens} tokens, ` +
+            `${plural(preview.baseline.files, "file")} read in full instead of sliced)`);
+    lines.push(`Context: ${preview.estimatedTokens}/${preview.budget} tokens; ${plural(preview.included.length, "item")} included`);
+    if (explain) {
+        lines.push("", "Included:", ...preview.included.map((item) => `- ${item.reason}: ${item.symbol} — ${item.explanation}`));
+        if (preview.omitted.length)
+            lines.push("Omitted:", ...preview.omitted.map((item) => `- ${item.symbol}: ${item.reason}`));
+        if (preview.unresolved.length)
+            lines.push("Unresolved calls:", ...preview.unresolved.map((call) => `- ${call.calleeName}`));
+    }
+    return `${lines.join("\n")}\n\n${preview.rendered}`;
+}
+async function execute(args) {
+    const command = args.command;
+    if (args.version)
+        return print(packageInfo.version, args, "version", packageInfo.version);
+    if (!command || command === "help")
+        return print({ usage: usage() }, args, "help", usage());
+    if (!["init", "index", "status", "doctor", "preview", "mcp"].includes(command))
+        throw new WorkflowError("INVALID_ARGUMENT", `Unknown command: ${command}`, usage());
+    const repository = resolveRepositoryRoot({
+        cwd: process.cwd(),
+        repository: args.repository,
+    });
+    if (command === "mcp") {
+        const { startMcpServer } = await import("./server/mcp-server.js");
+        await startMcpServer(repository);
+        return;
+    }
+    const index = new ProjectIndex(repository);
+    if (command === "init" || command === "index") {
+        const refreshed = index.refresh();
+        const body = { repository, ...refreshed };
+        const human = [
+            `Repository: ${repository}`,
+            `Indexed ${plural(refreshed.summary.files, "source file")} (${plural(refreshed.summary.symbols, "symbol")}) across ${Object.entries(refreshed.summary.filesByLanguage)
+                .map(([language, count]) => `${language}: ${count}`)
+                .join(", ")}.`,
+            'Next: context-slice preview "explain <symbol>"',
+        ].join("\n");
+        return print(body, args, command, human);
+    }
+    if (command === "status") {
+        const freshness = index.inspect();
+        const body = {
+            repository,
+            ready: freshness.state === "CURRENT",
+            freshness,
+        };
+        const human = [
+            `Repository: ${repository}`,
+            `Index: ${freshness.state}`,
+            `Source files: ${freshness.indexedFiles}/${freshness.sourceFiles}`,
+            ...Object.entries(freshness.filesByExtension)
+                .sort()
+                .map(([extension, count]) => `  ${extension}: ${count}`),
+            `Schema: ${freshness.schemaVersion}`,
+            `Last refresh: ${freshness.lastRefreshedAt ?? "never"}`,
+        ].join("\n");
+        return print(body, args, command, human);
+    }
+    if (command === "doctor") {
+        const freshness = index.inspect();
+        const checks = [
+            { name: "repository", status: "ok", detail: repository },
+            {
+                name: "source",
+                status: "ok",
+                detail: `${plural(freshness.sourceFiles, "file")} found`,
+            },
+            {
+                name: "index",
+                status: freshness.state === "CURRENT" ? "ok" : "action",
+                detail: freshness.state === "CURRENT" ? "ready" : "Run context-slice index",
+            },
+            {
+                name: "mcp",
+                status: "ok",
+                detail: "Configure command: context-slice mcp",
+            },
+        ];
+        const body = { repository, freshness, checks };
+        const human = checks
+            .map((check) => `${check.status === "ok" ? "OK" : "ACTION"} ${check.name}: ${check.detail}`)
+            .join("\n");
+        return print(body, args, command, human);
+    }
+    const refreshed = index.refresh();
+    const preview = buildPreview(index, args.positional.join(" "), {
+        budget: args.budget,
+    });
+    const body = { repository, refresh: refreshed.freshness, ...preview };
+    return print(body, args, command, renderPreview(preview, args.explain));
+}
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        await execute(parse(argv));
+    }
+    catch (error) {
+        if (error instanceof WorkflowError) {
+            process.stderr.write(`${error.code}: ${error.message}\n${error.remediation}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        process.stderr.write(`INTERNAL_ERROR: ${error instanceof Error ? error.message : String(error)}\nRun context-slice doctor for repository readiness.\n`);
+        process.exitCode = 1;
+    }
+}
+await main();