@oxagen/cli 0.6.0 → 0.6.1

package/dist/commands/rules.d.ts

@@ -0,0 +1,19 @@
+/**
+ * rules command — manage and test workspace rules.
+ *
+ *   oxagen rules list                    List rules and which are hard-enforced
+ *   oxagen rules show <name>             Show a rule's text + guard
+ *   oxagen rules new <name>              Scaffold .oxagen/rules/<name>.md
+ *   oxagen rules check <tool> <subject>  Dry-run a tool call against the guards
+ *
+ * Rules are injected into the agent's system prompt every turn and their guards
+ * are hard-enforced at the tool gate.
+ */
+import { type LoadRulesOptions } from "../rules/index.js";
+export type RulesCmdCtx = Pick<LoadRulesOptions, "cwd" | "userRulesDir">;
+export declare function rulesList(ctx?: RulesCmdCtx): void;
+export declare function rulesShow(name: string, ctx?: RulesCmdCtx): void;
+export declare function rulesNew(name: string, ctx?: RulesCmdCtx): void;
+/** Dry-run a proposed tool call against the rule guards (no model, no side effect). */
+export declare function rulesCheck(tool: string, subject: string, ctx?: RulesCmdCtx): void;
+//# sourceMappingURL=rules.d.ts.map

package/dist/commands/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/commands/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAyC,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGjG,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,cAAc,CAAC,CAAC;AAUzE,wBAAgB,SAAS,CAAC,GAAG,GAAE,WAAgB,GAAG,IAAI,CAWrD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,WAAgB,GAAG,IAAI,CAuBnE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,WAAgB,GAAG,IAAI,CAalE;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,WAAgB,GAAG,IAAI,CAkBrF"}

package/dist/commands/rules.js

@@ -0,0 +1,96 @@
+/**
+ * rules command — manage and test workspace rules.
+ *
+ *   oxagen rules list                    List rules and which are hard-enforced
+ *   oxagen rules show <name>             Show a rule's text + guard
+ *   oxagen rules new <name>              Scaffold .oxagen/rules/<name>.md
+ *   oxagen rules check <tool> <subject>  Dry-run a tool call against the guards
+ *
+ * Rules are injected into the agent's system prompt every turn and their guards
+ * are hard-enforced at the tool gate.
+ */
+import { loadRules, guardsToDeny, scaffoldRule } from "../rules/index.js";
+import { evaluateLocalPermission } from "../settings/permissions-gate.js";
+/** Map the friendly `check` tool arg to a CLI tool id + the input field. */
+const TOOL_ALIAS = {
+    bash: { tool: "bash", field: "command" },
+    edit: { tool: "edit_file", field: "path" },
+    write: { tool: "write_file", field: "path" },
+    read: { tool: "read_file", field: "path" },
+};
+export function rulesList(ctx = {}) {
+    const rules = loadRules(ctx).sort((a, b) => a.id.localeCompare(b.id));
+    if (rules.length === 0) {
+        console.log("No rules defined. Create one with `oxagen rules new <name>`.");
+        return;
+    }
+    console.log("Workspace rules:\n");
+    for (const r of rules) {
+        console.log(`  ${r.id}${r.guard ? "  [enforced]" : ""}`);
+        if (r.description)
+            console.log(`    ${r.description}`);
+    }
+}
+export function rulesShow(name, ctx = {}) {
+    const rule = loadRules(ctx).find((r) => r.id === name);
+    if (!rule) {
+        console.error(`Unknown rule "${name}". Run \`oxagen rules list\`.`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`# ${rule.id}`);
+    if (rule.description)
+        console.log(rule.description);
+    console.log(`\nsource: ${rule.source}`);
+    if (rule.guard) {
+        const g = rule.guard;
+        const parts = [
+            g.tool ? `tool=${g.tool}` : "",
+            g.denyPathGlob ? `denyPath=${g.denyPathGlob}` : "",
+            g.denyCommandGlob ? `denyCommand=${g.denyCommandGlob}` : "",
+        ].filter(Boolean);
+        console.log(`guard:  ${parts.join("  ")}  (hard-enforced)`);
+    }
+    else {
+        console.log("guard:  (none — prompt-only)");
+    }
+    console.log("\n--- rule ---\n");
+    console.log(rule.text);
+}
+export function rulesNew(name, ctx = {}) {
+    if (!/^[A-Za-z0-9][\w-]*$/.test(name)) {
+        console.error(`Invalid rule name "${name}". Use letters, digits, dashes, underscores.`);
+        process.exitCode = 1;
+        return;
+    }
+    const { path, created } = scaffoldRule({ name, cwd: ctx.cwd });
+    if (created) {
+        console.log(`✓ Created rule ${path}`);
+        console.log("  Add a guard (guard-tool / guard-deny-path / guard-deny-command) to hard-enforce it.");
+    }
+    else {
+        console.log(`${path} already exists — left untouched.`);
+    }
+}
+/** Dry-run a proposed tool call against the rule guards (no model, no side effect). */
+export function rulesCheck(tool, subject, ctx = {}) {
+    const alias = TOOL_ALIAS[tool.toLowerCase()];
+    if (!alias) {
+        console.error(`Unknown tool "${tool}". Use one of: ${Object.keys(TOOL_ALIAS).join(", ")}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { deny, reasons } = guardsToDeny(loadRules(ctx));
+    const input = { [alias.field]: subject };
+    const result = evaluateLocalPermission(alias.tool, input, { deny });
+    if (result.decision === "deny") {
+        const why = result.rule ? reasons[result.rule] ?? result.reason : result.reason;
+        console.log(`⛔ BLOCKED: ${tool} ${subject}`);
+        console.log(`   ${why}`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log(`✓ allowed: ${tool} ${subject} (no guard matched)`);
+    }
+}
+//# sourceMappingURL=rules.js.map

package/dist/commands/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/commands/rules.ts"],"names":[],"mappings":"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"}

package/dist/commands/settings.d.ts

@@ -0,0 +1,10 @@
+import { type ResolveSettingsOptions } from "../settings/index.js";
+/** Resolution context shared by every handler (paths come from here in tests). */
+export type SettingsCtx = Pick<ResolveSettingsOptions, "cwd" | "userSettingsPath" | "projectDirName">;
+export declare function settingsShow(ctx?: SettingsCtx): void;
+export declare function settingsPath(ctx?: SettingsCtx): void;
+export declare function settingsGet(key: string, ctx?: SettingsCtx): void;
+export declare function settingsSet(key: string, value: string, scopeArg?: string, ctx?: SettingsCtx): void;
+export declare function settingsValidate(ctx?: SettingsCtx): void;
+export declare function settingsInit(scopeArg?: string, ctx?: SettingsCtx): void;
+//# sourceMappingURL=settings.d.ts.map

package/dist/commands/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/commands/settings.ts"],"names":[],"mappings":"AAiBA,OAAO,EAOL,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAI9B,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,sBAAsB,EAAE,KAAK,GAAG,kBAAkB,GAAG,gBAAgB,CAAC,CAAC;AAgBtG,wBAAgB,YAAY,CAAC,GAAG,GAAE,WAAgB,GAAG,IAAI,CAaxD;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,WAAgB,GAAG,IAAI,CAOxD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,WAAgB,GAAG,IAAI,CAQpE;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,GAAE,WAAgB,GACpB,IAAI,CAcN;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,WAAgB,GAAG,IAAI,CAgB5D;AAED,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,WAAgB,GAAG,IAAI,CAc3E"}

package/dist/commands/settings.js

@@ -0,0 +1,117 @@
+/**
+ * settings command — inspect and edit the unified `settings.json`.
+ *
+ *   oxagen settings                 Show the merged settings + where each scope lives
+ *   oxagen settings path            List the three scope files and their status
+ *   oxagen settings get <key>       Print a value (dotted, e.g. permissions.defaultMode)
+ *   oxagen settings set <key> <val> Write a value (model | apiUrl | env.NAME)
+ *   oxagen settings validate        Validate every scope file against the schema
+ *   oxagen settings init            Write a documented starter file (project scope)
+ *
+ * `set` / `init` target a single scope (default: project) so the user/project/
+ * local layering stays meaningful.
+ *
+ * Every handler accepts an optional resolution context (cwd / userSettingsPath)
+ * so the command is exercisable in tests without touching the real `~/.config`.
+ */
+import { existsSync } from "node:fs";
+import { loadSettings, getScopePaths, writeSettingsValue, writeStarterSettings, } from "../settings/index.js";
+const SCOPES = ["user", "project", "local"];
+function isScope(value) {
+    return SCOPES.includes(value);
+}
+/** Navigate a dotted path (e.g. "permissions.defaultMode") into the settings. */
+function getByPath(settings, key) {
+    let cur = settings;
+    for (const part of key.split(".")) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+export function settingsShow(ctx = {}) {
+    const { settings, scopes } = loadSettings({ ...ctx, noCache: true });
+    console.log("Effective settings (merged user → project → local):\n");
+    console.log(JSON.stringify(settings, null, 2));
+    const present = scopes.filter((s) => s.settings || s.error);
+    console.log("\nScopes:");
+    if (present.length === 0) {
+        console.log("  (no settings files found — run `oxagen settings init`)");
+    }
+    for (const s of present) {
+        const status = s.error ? `⚠ ${s.error}` : "ok";
+        console.log(`  ${s.scope.padEnd(8)} ${s.path}  [${status}]`);
+    }
+}
+export function settingsPath(ctx = {}) {
+    const paths = getScopePaths(ctx);
+    console.log("Settings scope files (lowest → highest precedence):\n");
+    for (const scope of SCOPES) {
+        const path = paths[scope];
+        console.log(`  ${scope.padEnd(8)} ${path}  ${existsSync(path) ? "(exists)" : "(absent)"}`);
+    }
+}
+export function settingsGet(key, ctx = {}) {
+    const { settings } = loadSettings({ ...ctx, noCache: true });
+    const value = getByPath(settings, key);
+    if (value === undefined) {
+        console.log(`${key}: (not set)`);
+        return;
+    }
+    console.log(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+}
+export function settingsSet(key, value, scopeArg, ctx = {}) {
+    const scope = scopeArg ?? "project";
+    if (!isScope(scope)) {
+        console.error(`Unknown scope "${scope}". Use one of: ${SCOPES.join(", ")}`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const path = writeSettingsValue({ ...ctx, scope, key, value });
+        console.log(`✓ ${key} = ${value}  (${scope}: ${path})`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
+}
+export function settingsValidate(ctx = {}) {
+    const { scopes } = loadSettings({ ...ctx, noCache: true });
+    let ok = true;
+    let checked = 0;
+    for (const s of scopes) {
+        if (!s.settings && !s.error)
+            continue; // absent file — nothing to validate
+        checked++;
+        if (s.error) {
+            ok = false;
+            console.error(`✗ ${s.scope} (${s.path}): ${s.error}`);
+        }
+        else {
+            console.log(`✓ ${s.scope} (${s.path})`);
+        }
+    }
+    if (checked === 0)
+        console.log("No settings files found.");
+    if (!ok)
+        process.exitCode = 1;
+}
+export function settingsInit(scopeArg, ctx = {}) {
+    const scope = scopeArg ?? "project";
+    if (!isScope(scope)) {
+        console.error(`Unknown scope "${scope}". Use one of: ${SCOPES.join(", ")}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { path, created } = writeStarterSettings({ ...ctx, scope });
+    if (created) {
+        console.log(`✓ Wrote starter settings to ${path}`);
+        console.log("  Edit it to add permissions, hooks, env, and MCP servers.");
+    }
+    else {
+        console.log(`${path} already exists — left untouched.`);
+    }
+}
+//# sourceMappingURL=settings.js.map

package/dist/commands/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/commands/settings.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -13,6 +13,7 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import pkg from "../package.json" with { type: "json" };
+import { parseModeArg } from "./agent/permissions.js";
 // The Oxagen context engine pulls in DuckDB, a native CommonJS dependency that
 // references a bare `require`. Under pure-ESM execution that global is absent, so
 // loading the store throws "require is not defined". Provide the shim before any
@@ -30,15 +31,40 @@ program
     .version(version)
     .argument("[prompt...]", "One-shot prompt (runs and exits)")
     .option("-m, --model <slug>", "Gateway model slug (overrides config/default)")
+    .option("--agent <name>", "Run the one-shot prompt as a named agent definition")
     .option("--readonly", "Read-only mode: read/search/explain only — no file edits or commands", false)
+    .option("--mode <mode>", "Permission mode: ask | accept-edits | bypass | readonly (REPL default: ask; one-shot ungated unless set)")
     .option("--no-pipeline", "Skip prompt evaluation, context injection, and completeness judging")
+    .option("--verbose", "Capture + emit full per-turn telemetry (per-phase timing, model+token+cost, tool results)", false)
     .action(async (promptWords, opts) => {
     const prompt = promptWords.join(" ").trim();
+    let mode;
+    if (opts.mode) {
+        mode = parseModeArg(opts.mode);
+        if (!mode) {
+            process.stderr.write(`Error: invalid --mode "${opts.mode}". Use ask, accept-edits, bypass, or readonly.\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
     const runOpts = {
         model: opts.model,
         readOnly: opts.readonly,
+        mode,
         bare: opts.pipeline === false,
+        verbose: opts.verbose,
     };
+    // --agent: run the prompt as a named agent (its prompt, tools, model).
+    if (opts.agent) {
+        if (!prompt) {
+            process.stderr.write("Error: --agent requires a prompt, e.g. `oxagen --agent reviewer \"…\"`.\n");
+            process.exitCode = 1;
+            return;
+        }
+        const { runAgentOneShot } = await import("./repl/one-shot.js");
+        await runAgentOneShot(prompt, opts.agent, runOpts);
+        return;
+    }
     if (prompt) {
         // One-shot mode: run prompt, stream response, exit
         const { runOneShot } = await import("./repl/one-shot.js");
@@ -117,7 +143,23 @@ program
     const { handleReplay } = await import("./commands/replay.js");
     await handleReplay(turn, opts);
 });
-// ── graph: knowledge-graph search ─────────────────────────────────────────────
+// ── cost: project + report model cost from the baked-in rate card ─────────────
+program
+    .command("cost")
+    // The root's global `-m, --model` is reused (commander binds it to the parent),
+    // so the action reads merged opts via optsWithGlobals() to see --model here.
+    .description("Project model cost from the baked-in rate card, or roll up this project's spend")
+    .option("--in <tokens>", "Input token count to price", (v) => parseInt(v, 10))
+    .option("--out <tokens>", "Output token count to price", (v) => parseInt(v, 10))
+    .option("--rates", "Print the baked-in rate card", false)
+    .option("--session", "Roll up what this project's recorded turns actually cost, by model", false)
+    .option("--json", "Output JSON", false)
+    .action(async (_opts, command) => {
+    const merged = command.optsWithGlobals();
+    const { handleCost } = await import("./commands/cost.js");
+    await handleCost(merged);
+});
+// ── graph: knowledge-graph search + pull + status ─────────────────────────────
 const graph = program.command("graph").description("Query the knowledge graph");
 graph
     .command("search")
@@ -132,6 +174,30 @@ graph
     const { handleGraphSearch } = await import("./commands/graph.search.js");
     await handleGraphSearch(opts);
 });
+graph
+    .command("pull")
+    .description("Download an incremental snapshot of the workspace graph into a local DuckDB replica")
+    .option("--full", "Ignore the saved cursor and re-pull the entire graph", false)
+    .option("-l, --labels <csv>", "Comma-separated domain labels to filter (e.g. Person,SourceFile)")
+    .option("--no-system", "Exclude product-owned (system) nodes")
+    .option("--json", "Output summary as JSON")
+    .action(async (opts) => {
+    const { handleGraphPull } = await import("./commands/graph.pull.js");
+    await handleGraphPull({
+        full: opts.full,
+        labels: opts.labels,
+        noSystem: opts.system === false,
+        json: opts.json,
+    });
+});
+graph
+    .command("status")
+    .description("Show the state of the local workspace-graph replica")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { handleGraphStatus } = await import("./commands/graph.status.js");
+    await handleGraphStatus(opts);
+});
 // ── config: local configuration ───────────────────────────────────────────────
 program
     .command("config")
@@ -142,6 +208,232 @@ program
     const { handleConfig } = await import("./commands/config.js");
     await handleConfig(key, value);
 });
+// ── settings: the unified settings.json driver ────────────────────────────────
+const settings = program
+    .command("settings")
+    .description("Inspect and edit the unified settings.json (model, env, permissions, hooks, MCP)")
+    .action(async () => {
+    const { settingsShow } = await import("./commands/settings.js");
+    settingsShow();
+});
+settings
+    .command("show")
+    .description("Show the merged settings and which scope each file lives in")
+    .action(async () => {
+    const { settingsShow } = await import("./commands/settings.js");
+    settingsShow();
+});
+settings
+    .command("path")
+    .description("List the three scope files (user / project / local) and their status")
+    .action(async () => {
+    const { settingsPath } = await import("./commands/settings.js");
+    settingsPath();
+});
+settings
+    .command("get")
+    .description("Print a value by dotted key (e.g. permissions.defaultMode)")
+    .argument("<key>", "Dotted settings key")
+    .action(async (key) => {
+    const { settingsGet } = await import("./commands/settings.js");
+    settingsGet(key);
+});
+settings
+    .command("set")
+    .description("Set a value (model | apiUrl | env.NAME) in a scope")
+    .argument("<key>", "model, apiUrl, or env.NAME")
+    .argument("<value>", "Value to write")
+    .option("--scope <scope>", "user | project | local (default: project)")
+    .action(async (key, value, opts) => {
+    const { settingsSet } = await import("./commands/settings.js");
+    settingsSet(key, value, opts.scope);
+});
+settings
+    .command("validate")
+    .description("Validate every scope file against the settings schema")
+    .action(async () => {
+    const { settingsValidate } = await import("./commands/settings.js");
+    settingsValidate();
+});
+settings
+    .command("init")
+    .description("Write a documented starter settings.json (default: project scope)")
+    .option("--scope <scope>", "user | project | local (default: project)")
+    .action(async (opts) => {
+    const { settingsInit } = await import("./commands/settings.js");
+    settingsInit(opts.scope);
+});
+// ── agent: named agent definitions ────────────────────────────────────────────
+const agent = program
+    .command("agent")
+    .description("Manage named agent definitions (run one with `oxagen --agent <name> \"…\"`)");
+agent
+    .command("list")
+    .description("List available agents")
+    .action(async () => {
+    const { agentList } = await import("./commands/agent.js");
+    agentList();
+});
+agent
+    .command("show")
+    .description("Show an agent's definition and system prompt")
+    .argument("<name>", "Agent name")
+    .action(async (name) => {
+    const { agentShow } = await import("./commands/agent.js");
+    agentShow(name);
+});
+agent
+    .command("new")
+    .description("Scaffold a new agent at .oxagen/agents/<name>.md")
+    .argument("<name>", "Agent name")
+    .action(async (name) => {
+    const { agentNew } = await import("./commands/agent.js");
+    agentNew(name);
+});
+// ── command: user-defined slash commands ──────────────────────────────────────
+const command = program
+    .command("command")
+    .description("Manage user-defined slash commands (invoke as `/name` in the REPL)");
+command
+    .command("list")
+    .description("List available slash commands")
+    .action(async () => {
+    const { commandList } = await import("./commands/command.js");
+    commandList();
+});
+command
+    .command("show")
+    .description("Show a slash command's template")
+    .argument("<name>", "Command name")
+    .action(async (name) => {
+    const { commandShow } = await import("./commands/command.js");
+    commandShow(name);
+});
+command
+    .command("new")
+    .description("Scaffold a new slash command at .oxagen/commands/<name>.md")
+    .argument("<name>", "Command name")
+    .action(async (name) => {
+    const { commandNew } = await import("./commands/command.js");
+    commandNew(name);
+});
+command
+    .command("run")
+    .description("Expand a slash command's template with args and run it as a turn")
+    .argument("<name>", "Command name")
+    .argument("[args...]", "Arguments substituted into the template")
+    .action(async (name, args) => {
+    const { commandRun } = await import("./commands/command.js");
+    await commandRun(name, args ?? []);
+});
+// ── rules: workspace rules the agent must follow ──────────────────────────────
+const rules = program
+    .command("rules")
+    .description("Manage workspace rules the agent is told about and hard-blocked from violating");
+rules
+    .command("list")
+    .description("List rules (and which are hard-enforced)")
+    .action(async () => {
+    const { rulesList } = await import("./commands/rules.js");
+    rulesList();
+});
+rules
+    .command("show")
+    .description("Show a rule's text and guard")
+    .argument("<name>", "Rule name")
+    .action(async (name) => {
+    const { rulesShow } = await import("./commands/rules.js");
+    rulesShow(name);
+});
+rules
+    .command("new")
+    .description("Scaffold a new rule at .oxagen/rules/<name>.md")
+    .argument("<name>", "Rule name")
+    .action(async (name) => {
+    const { rulesNew } = await import("./commands/rules.js");
+    rulesNew(name);
+});
+rules
+    .command("check")
+    .description("Dry-run a proposed tool call against the guards (bash|edit|write|read)")
+    .argument("<tool>", "bash | edit | write | read")
+    .argument("<subject>", "The command (bash) or path (edit/write/read) to test")
+    .action(async (tool, subject) => {
+    const { rulesCheck } = await import("./commands/rules.js");
+    rulesCheck(tool, subject);
+});
+// ── mcp: external MCP servers ─────────────────────────────────────────────────
+const collect = (val, prev) => prev.concat([val]);
+const mcp = program
+    .command("mcp")
+    .description("Manage external MCP servers the agent loop connects to");
+mcp
+    .command("add")
+    .description("Add an MCP server (stdio via --command, or http/sse/websocket via --url)")
+    .argument("<name>", "Server name (used in tool names: mcp__<name>__<tool>)")
+    .option("--command <command>", "stdio: the command to spawn (e.g. npx)")
+    .option("--arg <arg>", "stdio: a command argument (repeatable)", collect, [])
+    .option("--url <url>", "http/sse/websocket: the server URL")
+    .option("--transport <transport>", "streamable-http | sse | websocket (default streamable-http)")
+    .option("--auth <auth>", "none | bearer | header (default none)")
+    .option("--env-token <VAR>", "Env var holding the bearer token")
+    .option("--header <KEY=VALUE>", "Static header for header auth (repeatable)", collect, [])
+    .option("--scope <scope>", "user | project | local (default project)")
+    .action(async (name, opts) => {
+    const { mcpAdd } = await import("./commands/mcp.js");
+    mcpAdd(name, {
+        command: opts["command"],
+        arg: opts["arg"],
+        url: opts["url"],
+        transport: opts["transport"],
+        auth: opts["auth"],
+        envToken: opts["envToken"],
+        header: opts["header"],
+        scope: opts["scope"],
+    });
+});
+mcp
+    .command("list")
+    .description("List configured MCP servers")
+    .action(async () => {
+    const { mcpList } = await import("./commands/mcp.js");
+    mcpList();
+});
+mcp
+    .command("remove")
+    .description("Remove an MCP server")
+    .argument("<name>", "Server name")
+    .option("--scope <scope>", "Limit to a scope (default: auto-detect)")
+    .action(async (name, opts) => {
+    const { mcpRemove } = await import("./commands/mcp.js");
+    mcpRemove(name, opts.scope);
+});
+mcp
+    .command("enable")
+    .description("Enable a disabled MCP server")
+    .argument("<name>", "Server name")
+    .option("--scope <scope>", "Limit to a scope (default: auto-detect)")
+    .action(async (name, opts) => {
+    const { mcpSetEnabled } = await import("./commands/mcp.js");
+    mcpSetEnabled(name, true, opts.scope);
+});
+mcp
+    .command("disable")
+    .description("Disable an MCP server without removing it")
+    .argument("<name>", "Server name")
+    .option("--scope <scope>", "Limit to a scope (default: auto-detect)")
+    .action(async (name, opts) => {
+    const { mcpSetEnabled } = await import("./commands/mcp.js");
+    mcpSetEnabled(name, false, opts.scope);
+});
+mcp
+    .command("check")
+    .description("Connect to a server (or all enabled) and preview the tools it exposes")
+    .argument("[name]", "Server name (omit to check all enabled)")
+    .action(async (name) => {
+    const { mcpCheck } = await import("./commands/mcp.js");
+    await mcpCheck(name);
+});
 // ── env: workspace environments ───────────────────────────────────────────────
 const env = program.command("env").description("Manage workspace environments");
 env
@@ -264,6 +556,10 @@ secret
     await handleSecretExport(opts);
 });
 async function main() {
+    // Project settings.json (env, apiUrl, model) into the environment before any
+    // command runs — filling only unset vars, so the shell always wins.
+    const { applySettingsToEnv } = await import("./settings/runtime.js");
+    applySettingsToEnv();
     await program.parseAsync(process.argv);
 }
 void main();