xtctx 0.3.2 → 0.11.3

package/README.md

@@ -1,149 +1,182 @@
 # xtctx
 
-[![CI](https://github.com/fstubner/xtctx/actions/workflows/ci.yml/badge.svg)](https://github.com/fstubner/xtctx/actions/workflows/ci.yml)
-[![Release Please](https://github.com/fstubner/xtctx/actions/workflows/release-please.yml/badge.svg)](https://github.com/fstubner/xtctx/actions/workflows/release-please.yml)
-[![Latest Release](https://img.shields.io/github/v/release/fstubner/xtctx?sort=semver)](https://github.com/fstubner/xtctx/releases)
+[![CI](https://github.com/fstubner/xtctx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fstubner/xtctx/actions/workflows/ci.yml)
+[![Landing Deploy](https://github.com/fstubner/xtctx/actions/workflows/deploy-landing.yml/badge.svg?branch=main)](https://github.com/fstubner/xtctx/actions/workflows/deploy-landing.yml)
+[![Release Please](https://github.com/fstubner/xtctx/actions/workflows/release-please.yml/badge.svg?branch=main)](https://github.com/fstubner/xtctx/actions/workflows/release-please.yml)
+[![npm Publish](https://github.com/fstubner/xtctx/actions/workflows/publish.yml/badge.svg)](https://github.com/fstubner/xtctx/actions/workflows/publish.yml)
+[![Latest Release](https://img.shields.io/github/v/release/fstubner/xtctx?display_name=tag&sort=semver)](https://github.com/fstubner/xtctx/releases)
 [![License](https://img.shields.io/github/license/fstubner/xtctx)](LICENSE)
-[![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node >=24](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 
-xtctx is a local-first context runtime for AI coding assistants.
+xtctx is local cross-tool handoff for AI coding agents.
 
-It lets Claude Code, Codex, Cursor, Copilot, and Gemini share the same project memory so you can switch tools without re-briefing each session.
+It configures your project so the next tool you open can find recent local
+transcript sessions and retrieve the raw messages through MCP. It does not run
+a daemon, host an API, generate summaries, or maintain durable project memory.
 
-## Core Capabilities
+The intended user is a solo developer who switches between local coding agents
+and wants the next agent to recover recent context without a pasted recap.
 
-- Cross-tool retrieval with MCP tools (`xtctx_search`, `xtctx_project_knowledge`, etc.)
-- Durable project knowledge in `.xtctx/knowledge`
-- File-first config sync into tool-native instruction files
-- One runtime process that serves:
-  - MCP server
-  - HTTP API (`/api/*`)
-  - bundled web UI (`/`)
-
-## Knowledge Types
-
-xtctx stores structured records as:
-
-- `decision`
-- `error_solution`
-- `insight`
-- `convention`
-- `gotcha`
-- `faq`
-
-## Practical Workflow (Tool Handoff)
-
-1. Start in your repo with `xtctx init`.
-2. Define shared rules in `.xtctx/tool-config/shared.yaml`.
-3. Run `xtctx sync` to generate managed sections for each tool.
-4. Start `xtctx serve`.
-5. At the beginning of every coding session:
-   - call `xtctx_search`
-   - call `xtctx_project_knowledge`
-6. After finishing work, write outcomes back with:
-   - `xtctx_save_decision`
-   - `xtctx_save_error_solution`
-   - `xtctx_save_insight`
-   - `xtctx_save_faq`
-
-This gives a repeatable loop: recall -> implement -> write back.
-
-## Quick Start
-
-Install and build:
-
-```bash
-npm ci
-npm --prefix web ci
-npm --prefix landing ci
-npm run build
-```
-
-Initialize project context:
-
-```bash
-npx xtctx init
-```
-
-Sync shared config into tool-native files:
-
-```bash
-npx xtctx sync
-```
-
-Start runtime services:
+## Workflow
 
 ```bash
-npx xtctx serve
+npx -y xtctx setup
+npx -y xtctx status
+npx -y xtctx disconnect antigravity
 ```
 
-Open:
-
-- Runtime web app: `http://127.0.0.1:3232/`
-- Health: `http://127.0.0.1:3232/health`
-- API: `http://127.0.0.1:3232/api/*`
-
-Optional full re-index:
-
-```bash
-npx xtctx ingest --full
-```
-
-## MCP Client Command
+`xtctx setup` writes project-level MCP config with `npx -y xtctx`, installs
+real hooks where a tool supports them, and writes managed instruction blocks
+that point agents to the MCP retrieval tools. It also syncs selected project
+skills from `.xtctx/skills` into verified native or adapter surfaces for
+supported tools. Antigravity MCP is always written to the app-level config
+because Antigravity has no project MCP file. Use `xtctx setup --global-mcp`
+to also configure the global-only GitHub Copilot CLI surface.
+
+`xtctx status` reports actual handoff state: config, MCP command, local SQLite
+index, detected transcript stores, hook mode, managed-block drift, and stale
+generated references. It also reports selected skills, generated skill targets,
+target drift, and tools that do not have a verified skill surface.
+It reports the current local cache rather than forcing a transcript scan. If
+the index is empty, ask a configured agent to call `xtctx_recent_sessions`.
+
+`xtctx disconnect <tool>` stops xtctx from managing one tool for the project.
+It removes the xtctx MCP entry for that tool, removes managed instruction
+blocks where that tool owns them, removes supported startup hooks, and marks the
+tool disabled in `.xtctx/config.yaml`. It removes generated skill adapters for
+that tool. It does not delete transcript sources, canonical project skills, or
+the local SQLite cache. Use `xtctx disconnect --all` to remove xtctx from every
+supported tool. Antigravity stores MCP config at app level, so
+`xtctx disconnect antigravity` removes the xtctx entry from Antigravity for the
+current user account.
+
+Generated MCP clients should use:
 
 ```json
 {
-  "command": "npx",
-  "args": ["xtctx", "serve", "--mcp-only", "--project", "/absolute/path/to/project"]
+  "mcpServers": {
+    "xtctx": {
+      "command": "npx",
+      "args": ["-y", "xtctx"]
+    }
+  }
 }
 ```
 
-## File-First Configuration
-
-Primary config source is `.xtctx/config.yaml`.
+When invoked by an MCP client over stdio, bare `xtctx` starts the MCP server.
+When invoked in a normal terminal, it shows the human CLI.
+
+## MCP Tools
+
+- `xtctx_recent_sessions` lists recent indexed transcript sessions.
+- `xtctx_session_detail` returns raw messages for a `session_ref`.
+- `xtctx_search_sessions` hybrid-searches chronological transcript windows with local semantic vectors plus keyword fallback.
+- `xtctx_continuity_status` reports wiring and local index diagnostics.
+- `xtctx_handoff_manifest` returns a read-only orchestrator envelope with stable
+  session handoff IDs and pointers to raw-detail retrieval. A caller can attach
+  a correlation ID; xtctx echoes it but does not persist task state.
+
+The MCP tools scan transcript stores lazily and update `.xtctx/state/xtctx.db`
+on demand. The database is a rebuildable cache; the source transcripts remain
+authoritative.
+
+Semantic search embeds sliding windows of raw transcript turns, not generated
+summaries. Window text includes role, timestamp, and message order so retrieval
+can prefer the relevant point in the conversation, then return the matching
+message range for `xtctx_session_detail`.
+
+## Supported Tools
+
+- Claude Code
+- Cursor
+- Codex
+- GitHub Copilot
+- Google Antigravity
+- opencode
+- GitHub Copilot CLI
+
+Each tool has a scraper for local handoff storage. Antigravity support reads
+full transcript steps from the running local Antigravity language server when
+it is available, and falls back to readable `brain` artifacts when the encrypted
+`.pb` conversation store cannot be queried. Setup writes Antigravity MCP config
+and a managed `GEMINI.md` handoff block (Antigravity CLI keeps project-memory
+compatibility with that file). Some tools have native MCP config or executable
+startup hooks; others receive MCP config plus managed instructions only.
+`xtctx status` labels the real mode for each integration.
+
+## Limits
+
+- xtctx is local-only. It does not upload transcripts or run telemetry.
+- Transcript formats belong to each upstream tool and can drift. The drift
+  tests and nightly canary exist to catch parser breakage, but `xtctx status`
+  is still the source of truth for your machine.
+- Semantic search is lazy. The first semantic or hybrid query may initialize
+  the local embedding provider and create local vectors; hybrid search falls
+  back to keyword search if vector generation is unavailable.
+- Antigravity conversation `.pb` files are not parsed directly; retrieval uses
+  the local language-server API when available, otherwise readable `brain`
+  artifacts.
+
+## Skill Sync
+
+Project skills live in `.xtctx/skills/<skill-id>/SKILL.md`. Fresh setup writes
+the built-in `xtctx-handoff` skill. Interactive setup also inventories skills
+from connected tool surfaces and lets you select which ones to keep in sync for
+the project. Non-interactive `xtctx setup --yes` is conservative: it syncs the
+built-in skill plus any skills already selected in `.xtctx/config.yaml`.
+
+Skill sync uses real target surfaces only:
+
+- Claude Code receives native project skills under `.claude/skills/`.
+- Cursor receives generated rule adapters under `.cursor/rules/xtctx-skills/`.
+- GitHub Copilot receives generated instruction adapters under `.github/instructions/`.
+- Antigravity, Codex, opencode, and Copilot CLI receive skill pointers through
+  managed handoff blocks (`GEMINI.md` / `AGENTS.md` / Copilot instructions).
+- Tools without a verified native or adapter surface are reported as unsupported.
+
+## Project Files
+
+- `.xtctx/config.yaml`: project xtctx configuration
+- `.xtctx/skills/<skill-id>/SKILL.md`: canonical local project skills
+- `.xtctx/state/xtctx.db`: local handoff cache, never commit
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/xtctx.mdc`, `.github/copilot-instructions.md`: managed handoff instructions where applicable
+
+Content outside `<!-- xtctx:begin -->` / `<!-- xtctx:end -->` fences is
+preserved. Run `xtctx setup --repair` to replace stale or duplicated generated
+blocks.
 
-Environment variables are optional explicit overrides only.
-
-Security-related overrides:
-
-- `XTCTX_API_TOKEN`
-- `XTCTX_ALLOWED_ORIGINS`
-- `XTCTX_ALLOW_LOCALHOST_ORIGINS`
-- `XTCTX_RATE_LIMIT_WINDOW_MS`
-- `XTCTX_RATE_LIMIT_MAX`
-
-## UIs
-
-- `web/`: runtime product UI served by `xtctx serve` (dark mode default with toggle)
-- `landing/`: public landing site deployed to GitHub Pages (dark mode default with toggle)
-
-Local previews:
+## Development
 
 ```bash
-npm run web:dev
-npm run landing:dev
-npm run landing:preview
+npm ci
+npm --prefix landing ci
+npm run verify:release
 ```
 
-## CLI Commands
-
-- `xtctx init [path]`
-- `xtctx serve [--mcp-only] [--project <path>]`
-- `xtctx ingest [--full] [--project <path>]`
-- `xtctx sync [--project <path>]`
-
-## Development
-
-Full validation:
+Useful focused checks:
 
 ```bash
-npm run verify:release
+npm test
+npm run test:drift
+npm run lint
+npm run build
+npm run demo:public
 ```
 
-Release automation:
+`npm run demo:public` creates synthetic Claude Code and Codex transcript stores
+in a temporary project, starts the built MCP server, and calls the public
+handoff tools. It does not scan private local transcript directories. See
+[`docs/demo.md`](docs/demo.md).
+
+## Orchestrator Integration
+
+xtctx is supporting fabric, not an orchestrator. An external control plane can
+call `xtctx_handoff_manifest` to obtain project-scoped handoff IDs and the
+corresponding `xtctx_session_detail` calls, then retain its own task, branch,
+ownership, and scheduling state. See
+[`docs/orchestrator-integration.md`](docs/orchestrator-integration.md).
 
-- Conventional commits feed Release Please
-- Release PR merge on `main` creates GitHub release
-- GitHub release publication triggers npm publish via OIDC trusted publishing
+## Release
 
-See `CONTRIBUTING.md` and `SECURITY.md` for contributor and security policy details.
+Release Please manages versions and changelog. GitHub Releases publish to npm
+through OIDC trusted publishing.

package/dist/src/cli/disconnect.d.ts

@@ -0,0 +1,8 @@
+export interface DisconnectCliOptions {
+    projectPath?: string;
+    tool?: string;
+    all?: boolean;
+    yes?: boolean;
+}
+export declare function runDisconnect(options?: DisconnectCliOptions): Promise<void>;
+//# sourceMappingURL=disconnect.d.ts.map

package/dist/src/cli/disconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disconnect.d.ts","sourceRoot":"","sources":["../../../src/cli/disconnect.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAerF"}

package/dist/src/cli/disconnect.js

@@ -0,0 +1,42 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { describeDisconnectPlan, disconnectProject, printDisconnectResult, } from "../config/disconnect.js";
+export async function runDisconnect(options = {}) {
+    if (!options.yes) {
+        const confirmed = await confirmDisconnect(options);
+        if (!confirmed) {
+            process.stdout.write("xtctx disconnect cancelled.\n");
+            return;
+        }
+    }
+    const result = await disconnectProject({
+        projectPath: options.projectPath,
+        tool: options.tool,
+        all: options.all,
+    });
+    printDisconnectResult(result);
+}
+async function confirmDisconnect(options) {
+    const plan = describeDisconnectPlan(options);
+    process.stdout.write(`xtctx disconnect will remove handoff management for ${plan.tools.join(", ")}\n`);
+    process.stdout.write(`Project: ${plan.projectRoot}\n`);
+    for (const write of plan.writes) {
+        const note = write.note ? ` (${write.note})` : "";
+        process.stdout.write(`  ${write.kind.padEnd(22)} ${write.path}${note}\n`);
+    }
+    for (const warning of plan.warnings) {
+        process.stdout.write(`  warning ${warning}\n`);
+    }
+    if (input.isTTY !== true || output.isTTY !== true) {
+        throw new Error("Refusing non-interactive disconnect without --yes.");
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question("Apply these changes? [y/N] ");
+        return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=disconnect.js.map

package/dist/src/cli/disconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disconnect.js","sourceRoot":"","sources":["../../../src/cli/disconnect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AASjC,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAgC,EAAE;IACpE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YACtD,OAAO;QACT,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;QACrC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IACH,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,OAA6B;IAC5D,MAAM,IAAI,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uDAAuD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;IACvD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC;IAC5E,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,OAAO,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAC;QAChE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC;IACtF,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/src/cli/hook.d.ts

@@ -0,0 +1,7 @@
+export interface HookOptions {
+    projectPath?: string;
+    tool?: string;
+    event?: string;
+}
+export declare function runHook(options?: HookOptions): Promise<void>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/src/cli/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/cli/hook.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BtE"}

package/dist/src/cli/hook.js

@@ -0,0 +1,32 @@
+import { createProjectServices } from "../runtime/services.js";
+export async function runHook(options = {}) {
+    if (options.event && options.event !== "session-start") {
+        return;
+    }
+    // Fail open throughout: this runs inside the host agent's session startup,
+    // so a broken index or config must never surface as a startup error there.
+    let services;
+    try {
+        services = await createProjectServices(options.projectPath);
+        const status = await services.sessions.getStatus();
+        const tool = options.tool ?? "unknown";
+        process.stdout.write([
+            "# xtctx handoff",
+            "",
+            `Tool: ${tool}`,
+            `Project root: ${services.projectRoot}`,
+            `Last scan: ${status.last_scan_at ?? "never"}`,
+            "",
+            "Recent transcript context is available through MCP.",
+            "Call `xtctx_recent_sessions`, then `xtctx_session_detail` for relevant sessions.",
+            "",
+        ].join("\n"));
+    }
+    catch {
+        return;
+    }
+    finally {
+        await services?.sessions.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=hook.js.map

package/dist/src/cli/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../../src/cli/hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAQ/D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAAuB,EAAE;IACrD,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;QACvD,OAAO;IACT,CAAC;IAED,2EAA2E;IAC3E,2EAA2E;IAC3E,IAAI,QAAuE,CAAC;IAC5E,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC;QAEvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;YACE,iBAAiB;YACjB,EAAE;YACF,SAAS,IAAI,EAAE;YACf,iBAAiB,QAAQ,CAAC,WAAW,EAAE;YACvC,cAAc,MAAM,CAAC,YAAY,IAAI,OAAO,EAAE;YAC9C,EAAE;YACF,qDAAqD;YACrD,kFAAkF;YAClF,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;YAAS,CAAC;QACT,MAAM,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/src/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AASA,wBAAsB,IAAI,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AAYA,wBAAsB,IAAI,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAsG7D"}

package/dist/src/cli/index.js

@@ -1,55 +1,108 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { runIngest } from "./ingest.js";
-import { runInit } from "./init.js";
-import { runServe } from "./serve.js";
-import { runSync } from "./sync.js";
-const CLI_VERSION = "0.1.0";
+import { runDisconnect } from "./disconnect.js";
+import { runHook } from "./hook.js";
+import { runSetup } from "./setup.js";
+import { runStatus } from "./status.js";
+import { createProjectServices } from "../runtime/services.js";
+import { startMcpServer } from "../mcp/server.js";
+import { readXtctxPackage } from "../utils/package-info.js";
+const { version: CLI_VERSION } = readXtctxPackage(import.meta.url);
 export async function main(argv = process.argv) {
+    if (shouldStartMcp(argv)) {
+        const services = await createProjectServices(process.cwd());
+        let closed = false;
+        const shutdown = (exit) => {
+            if (closed)
+                return;
+            closed = true;
+            void services.sessions
+                .close()
+                .catch(() => { })
+                .finally(() => {
+                if (exit)
+                    process.exit(0);
+            });
+        };
+        process.once("SIGINT", () => shutdown(true));
+        process.once("SIGTERM", () => shutdown(true));
+        await startMcpServer({ sessions: services.sessions }, () => shutdown(false));
+        return;
+    }
     const program = new Command();
     program
         .name("xtctx")
-        .description("Cross-tool context for AI coding agents")
-        .version(CLI_VERSION);
+        .description("Local cross-tool handoff for AI coding agents")
+        .version(CLI_VERSION)
+        .showHelpAfterError();
     program
-        .command("init")
-        .argument("[projectPath]", "Project root to initialize")
-        .option("-f, --force", "Overwrite existing xtctx config files", false)
-        .description("Scaffold .xtctx in the target project")
+        .command("setup")
+        .argument("[projectPath]", "Project root to configure")
+        .option("-p, --project <path>", "Project root to configure")
+        .option("-y, --yes", "Apply setup without prompting", false)
+        .option("--repair", "Remove legacy generated xtctx config before writing current setup", false)
+        .option("--global-mcp", "Also configure Copilot CLI global MCP (Antigravity MCP is always configured)", false)
+        .description("Configure MCP, hooks, managed handoff instructions, and synced skills")
         .action(async (projectPath, options) => {
-        await runInit({ projectPath, force: options.force });
-    });
-    program
-        .command("serve")
-        .option("-p, --project <path>", "Project root (defaults to cwd)")
-        .option("--mcp-only", "Only start MCP server (skip ingestion/web notices)", false)
-        .description("Start xtctx services (currently MCP server)")
-        .action(async (options) => {
-        await runServe({
-            projectPath: options.project,
-            mcpOnly: options.mcpOnly,
+        const globalOptions = program.opts();
+        await runSetup({
+            projectPath: options.project ?? globalOptions.project ?? projectPath,
+            yes: options.yes,
+            repair: options.repair,
+            includeGlobalMcp: options.globalMcp,
         });
     });
     program
-        .command("sync")
+        .command("status")
         .option("-p, --project <path>", "Project root (defaults to cwd)")
-        .description("Generate tool-native config files from shared config")
+        .description("Diagnose xtctx handoff wiring and local transcript index")
         .action(async (options) => {
-        await runSync({ projectPath: options.project });
+        const globalOptions = program.opts();
+        await runStatus({ projectPath: options.project ?? globalOptions.project });
     });
     program
-        .command("ingest")
-        .option("-p, --project <path>", "Project root (defaults to cwd)")
-        .option("--full", "Run a full re-sync instead of incremental", false)
-        .description("Manually trigger ingestion")
-        .action(async (options) => {
-        await runIngest({
-            projectPath: options.project,
-            full: options.full,
+        .command("disconnect")
+        .argument("[tool]", "Tool to stop managing for this project")
+        .option("--all", "Disconnect xtctx from all supported tools", false)
+        .option("-p, --project <path>", "Project root")
+        .option("-y, --yes", "Apply disconnect without prompting", false)
+        .description("Remove xtctx management from a tool without deleting transcript data")
+        .action(async (tool, options) => {
+        const globalOptions = program.opts();
+        await runDisconnect({
+            tool,
+            all: options.all,
+            projectPath: options.project ?? globalOptions.project,
+            yes: options.yes,
         });
     });
+    program
+        .option("--hook <event>", "Internal hook event name")
+        .option("--tool <tool>", "Tool invoking an internal hook")
+        .option("-p, --project <path>", "Project root");
+    program.action(async () => {
+        const options = program.opts();
+        if (options.hook) {
+            await runHook({
+                event: options.hook,
+                tool: options.tool,
+                projectPath: options.project,
+            });
+            return;
+        }
+        program.outputHelp();
+    });
     await program.parseAsync(argv);
 }
+function shouldStartMcp(argv) {
+    if (argv.length > 2) {
+        return false;
+    }
+    if (process.env.XTCTX_NO_AUTO_MCP === "1") {
+        return false;
+    }
+    return process.stdin.isTTY !== true && process.stdout.isTTY !== true;
+}
 main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);

package/dist/src/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;IAC5C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,yCAAyC,CAAC;SACtD,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,eAAe,EAAE,4BAA4B,CAAC;SACvD,MAAM,CAAC,aAAa,EAAE,uCAAuC,EAAE,KAAK,CAAC;SACrE,WAAW,CAAC,uCAAuC,CAAC;SACpD,MAAM,CAAC,KAAK,EAAE,WAA+B,EAAE,OAA2B,EAAE,EAAE;QAC7E,MAAM,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,sBAAsB,EAAE,gCAAgC,CAAC;SAChE,MAAM,CAAC,YAAY,EAAE,oDAAoD,EAAE,KAAK,CAAC;SACjF,WAAW,CAAC,6CAA6C,CAAC;SAC1D,MAAM,CAAC,KAAK,EAAE,OAA+C,EAAE,EAAE;QAChE,MAAM,QAAQ,CAAC;YACb,WAAW,EAAE,OAAO,CAAC,OAAO;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,MAAM,CAAC,sBAAsB,EAAE,gCAAgC,CAAC;SAChE,WAAW,CAAC,sDAAsD,CAAC;SACnE,MAAM,CAAC,KAAK,EAAE,OAA6B,EAAE,EAAE;QAC9C,MAAM,OAAO,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,sBAAsB,EAAE,gCAAgC,CAAC;SAChE,MAAM,CAAC,QAAQ,EAAE,2CAA2C,EAAE,KAAK,CAAC;SACpE,WAAW,CAAC,4BAA4B,CAAC;SACzC,MAAM,CAAC,KAAK,EAAE,OAA4C,EAAE,EAAE;QAC7D,MAAM,SAAS,CAAC;YACd,WAAW,EAAE,OAAO,CAAC,OAAO;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/setup.d.ts

@@ -0,0 +1,8 @@
+export interface SetupCliOptions {
+    projectPath?: string;
+    yes?: boolean;
+    repair?: boolean;
+    includeGlobalMcp?: boolean;
+}
+export declare function runSetup(options?: SetupCliOptions): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/src/cli/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/cli/setup.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAsB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3E"}