create-academic-research 0.1.13 → 0.1.15

package/dist/src/capabilities.js

@@ -1,11 +1,14 @@
-import { appendFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { appendFile, chmod, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { assertKnownAgentTarget, AUTO_AGENT, DEFAULT_AGENT, normalizeAgentTarget, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { defaultRunner } from "./runner.js";
-import { AGENT_STACK, presetMcpServers } from "./stack.js";
+import { AGENT_STACK, mcpModeLabel, mcpRecommendedMode, mcpServerModeKeys, mcpSupportedModeLabels, normalizeMcpMode, presetMcpServers, resolveMcpServer } from "./stack.js";
 import { formatMcpDotenv, listMcpEnvironmentEntries } from "./mcp-env.js";
 import { probeMcpServerList } from "./mcp-probe.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 export { formatMcpDotenv, listMcpEnvironmentEntries };
 export { mergeMcpEnvironment, readMcpEnvironmentFile } from "./mcp-env.js";
 export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
@@ -21,13 +24,16 @@ export async function readCapabilities(root) {
     }
 }
 export async function writeCapabilities(root, state) {
+    const mcpServers = [...(state.mcp_servers ?? [])];
     const next = {
         agent: assertKnownAgentTarget(state.agent),
         preset: state.preset ?? "default",
         scope: "project-local",
-        mcp_servers: [...(state.mcp_servers ?? [])]
+        mcp_servers: mcpServers,
+        mcp_server_modes: normalizeMcpServerModeMap(state.mcp_server_modes ?? {}, mcpServers),
+        mcp_server_remote: normalizeMcpServerRemoteMap(state.mcp_server_remote ?? {}, mcpServers, state.mcp_server_modes ?? {})
     };
-    await writeFile(join(root, "configs/capabilities.yaml"), YAML.stringify(next), "utf8");
+    await writeFile(join(root, "configs/capabilities.yaml"), YAML.stringify(serializeCapabilityState(next)), "utf8");
     await writeCapabilityProfile(root, next);
     await writeMcpSetup(root, next);
     await writeMcpSnippet(root, next);
@@ -42,7 +48,9 @@ export async function initializeCapabilities(root, options = {}) {
     await writeCapabilities(root, {
         agent: options.agent,
         preset,
-        mcp_servers: mcpServers
+        mcp_servers: mcpServers,
+        mcp_server_modes: {},
+        mcp_server_remote: {}
     });
 }
 export async function buildSkillInstallCommands(root, preset = "default", options = {}) {
@@ -96,6 +104,7 @@ export async function installSkills(root, preset = "default", options = {}, runn
             preset
         });
     }
+    await recordSkillPresetLock(root, preset, agent, "install");
     return { ok: true, count: commands.length };
 }
 export async function installSkillIds(root, skills, options = {}, runner = defaultRunner) {
@@ -112,6 +121,7 @@ export async function installSkillIds(root, skills, options = {}, runner = defau
             agent
         });
     }
+    await recordExplicitSkillLock(root, selectedSkills, agent, "install");
     return { ok: true, count: commands.length, skills: selectedSkills };
 }
 export async function listInstalledSkills(root) {
@@ -162,20 +172,37 @@ export async function removeSkills(root, skills, runner = defaultRunner) {
         "-y"
     ], { cwd: root });
     await removeSkillsFromLock(root, skills);
+    await recordRemovedSkillLock(root, skills);
     return { ok: true, count: skills.length };
 }
 export async function updateSkills(root, runner = defaultRunner) {
     await runner.run(["npm", "exec", "--yes", "--package", "skills", "--", "skills", "update", "--project", "-y"], { cwd: root });
+    await recordSkillUpdateLock(root);
     return { ok: true };
 }
 export async function enableMcpServers(root, servers, options = {}) {
     assertKnownMcpServers(servers);
     const state = await readCapabilities(root);
     const selected = dedupe([...(state.mcp_servers ?? []), ...servers]);
+    const mcpServerModes = { ...(state.mcp_server_modes ?? {}) };
+    const mcpServerRemote = { ...(state.mcp_server_remote ?? {}) };
+    for (const server of servers) {
+        const mode = normalizeMcpMode(server, options.mode ?? state.mcp_server_modes?.[server]);
+        if (options.mode)
+            mcpServerModes[server] = mode;
+        if (mode === "remote-custom") {
+            mcpServerRemote[server] = normalizeRemoteConfig(server, options.remote ?? state.mcp_server_remote?.[server]);
+        }
+        else {
+            delete mcpServerRemote[server];
+        }
+    }
     await writeCapabilities(root, {
         ...state,
         agent: assertKnownAgentTarget(options.agent ?? state.agent),
-        mcp_servers: selected
+        mcp_servers: selected,
+        mcp_server_modes: mcpServerModes,
+        mcp_server_remote: mcpServerRemote
     });
     return { ok: true, servers: selected };
 }
@@ -184,50 +211,74 @@ export async function disableMcpServers(root, servers, options = {}) {
     const state = await readCapabilities(root);
     const blocked = new Set(servers);
     const selected = (state.mcp_servers ?? []).filter((server) => !blocked.has(server));
+    const mcpServerModes = { ...(state.mcp_server_modes ?? {}) };
+    const mcpServerRemote = { ...(state.mcp_server_remote ?? {}) };
+    for (const server of servers)
+        delete mcpServerModes[server];
+    for (const server of servers)
+        delete mcpServerRemote[server];
     await writeCapabilities(root, {
         ...state,
         agent: assertKnownAgentTarget(options.agent ?? state.agent),
-        mcp_servers: selected
+        mcp_servers: selected,
+        mcp_server_modes: mcpServerModes,
+        mcp_server_remote: mcpServerRemote
     });
     return { ok: true, servers: selected };
 }
-export function mcpToolCommands(servers, key = "install_command") {
+export function mcpToolCommands(servers, key = "install_command", modes = {}) {
     assertKnownMcpServers(servers);
     const commands = [];
     for (const server of servers) {
-        const rawCommand = AGENT_STACK.mcp_servers[server]?.[key];
+        const rawCommand = resolveMcpServer(server, modes[server])?.[key];
         if (rawCommand)
             commands.push(splitCommand(rawCommand));
     }
     return commands;
 }
-export function mcpToolCommandTexts(servers, key = "install_command") {
+export function mcpToolCommandTexts(servers, key = "install_command", modes = {}) {
     assertKnownMcpServers(servers);
     const commands = [];
     for (const server of servers) {
-        const rawCommand = AGENT_STACK.mcp_servers[server]?.[key];
+        const rawCommand = resolveMcpServer(server, modes[server])?.[key];
         if (rawCommand)
             commands.push(rawCommand);
     }
     return commands;
 }
 export async function installMcpTools(root, servers, runner = defaultRunner) {
-    const selected = servers.length > 0 ? servers : (await readCapabilities(root)).mcp_servers ?? [];
+    const state = await readCapabilities(root);
+    const selected = servers.length > 0 ? servers : state.mcp_servers ?? [];
     assertKnownMcpServers(selected);
-    const commands = mcpToolCommands(selected, "install_command");
+    const modes = selectedMcpServerModes(state, selected);
+    const skipped = [];
+    const commands = mcpToolCommands(selected, "install_command", modes);
     for (const command of commands) {
         await runner.run(command, { cwd: root });
     }
-    return { ok: true, count: commands.length };
+    for (const serverName of selected) {
+        const server = resolveMcpServer(serverName, modes[serverName]);
+        if (!server.install_command)
+            skipped.push(mcpInstallSkip(serverName, server));
+    }
+    return { ok: true, count: commands.length, skipped };
 }
 export async function uninstallMcpTools(root, servers, runner = defaultRunner) {
-    const selected = servers.length > 0 ? servers : (await readCapabilities(root)).mcp_servers ?? [];
+    const state = await readCapabilities(root);
+    const selected = servers.length > 0 ? servers : state.mcp_servers ?? [];
     assertKnownMcpServers(selected);
-    const commands = mcpToolCommands(selected, "uninstall_command");
+    const modes = selectedMcpServerModes(state, selected);
+    const skipped = [];
+    const commands = mcpToolCommands(selected, "uninstall_command", modes);
     for (const command of commands) {
         await runner.run(command, { cwd: root });
     }
-    return { ok: true, count: commands.length };
+    for (const serverName of selected) {
+        const server = resolveMcpServer(serverName, modes[serverName]);
+        if (!server.uninstall_command)
+            skipped.push(mcpUninstallSkip(serverName, server));
+    }
+    return { ok: true, count: commands.length, skipped };
 }
 export async function doctorMcpServers(root, options = {}) {
     const errors = [];
@@ -246,6 +297,7 @@ export async function doctorMcpServers(root, options = {}) {
         };
     }
     const enabled = state.mcp_servers ?? [];
+    const modes = selectedMcpServerModes(state, enabled);
     const unknown = enabled.filter((server) => !AGENT_STACK.mcp_servers[server]);
     if (unknown.length > 0) {
         errors.push(`unknown MCP server in capabilities: ${unknown.join(", ")}`);
@@ -260,7 +312,7 @@ export async function doctorMcpServers(root, options = {}) {
         }
     }
     catch (error) {
-        const hasGeneratedServer = enabled.some((server) => AGENT_STACK.mcp_servers[server]?.command);
+        const hasGeneratedServer = enabled.some((server) => isSnippetCapable(resolveMcpServerForState(state, server, modes[server])));
         if (hasGeneratedServer && isMissingFileError(error)) {
             errors.push(`missing generated MCP snippet: ${snippetPath}`);
         }
@@ -270,7 +322,7 @@ export async function doctorMcpServers(root, options = {}) {
         }
     }
     for (const name of enabled) {
-        const server = AGENT_STACK.mcp_servers[name];
+        const server = resolveMcpServerForState(state, name, modes[name]);
         if (!server)
             continue;
         for (const envName of server.required_env) {
@@ -286,7 +338,13 @@ export async function doctorMcpServers(root, options = {}) {
         if (server.local_service) {
             warnings.push(`${name}: requires local service: ${server.local_service}`);
         }
-        if (!server.command) {
+        if (server.connection_mode === "manual-local") {
+            const lock = await readCapabilityLock(root);
+            if (lock.mcp[name]?.setup?.status !== "ready") {
+                warnings.push(`${name}: local setup not complete; run npm run mcp:setup -- ${name} --mode local --env-file .env.local`);
+            }
+        }
+        if (!isSnippetCapable(server)) {
             warnings.push(`${name}: manual setup only; no generated client command`);
             continue;
         }
@@ -300,28 +358,64 @@ export async function probeMcpServers(root, servers, options = {}) {
     const selected = servers.length > 0 ? servers : (await readCapabilities(root)).mcp_servers ?? [];
     const env = options.env ?? process.env;
     const timeoutMs = options.timeoutMs ?? 5000;
-    return probeMcpServerList(root, selected, env, timeoutMs, options.clientVersion);
+    const state = await readCapabilities(root);
+    const modes = Object.fromEntries(selected.map((serverName) => [
+        serverName,
+        normalizeMcpMode(serverName, options.mode ?? state.mcp_server_modes?.[serverName])
+    ]));
+    const resolvedServers = Object.fromEntries(selected.map((serverName) => [serverName, resolveMcpServerForState(state, serverName, modes[serverName])]));
+    const result = await probeMcpServerList(root, selected, env, timeoutMs, options.clientVersion, modes, resolvedServers);
+    await updateCapabilityLock(root, (lock) => {
+        for (const item of result.results) {
+            const server = resolveMcpServerForState(state, item.server, modes[item.server]);
+            const entry = ensureLockMcpEntry(lock, item.server, server);
+            entry.probe = { status: item.status, detail: item.detail, updated_at: nowIso() };
+        }
+    });
+    return result;
 }
 async function writeMcpSnippet(root, state) {
+    const snippet = renderMcpSnippet(state);
+    const outputDir = join(root, "docs/agent/generated");
+    await mkdir(outputDir, { recursive: true });
+    await removeInactiveMcpSnippets(outputDir, snippet.fileName);
+    await writeFile(join(outputDir, snippet.fileName), snippet.content, "utf8");
+}
+export function renderMcpSnippet(state) {
     const servers = {};
+    const modes = selectedMcpServerModes(state, state.mcp_servers ?? []);
     for (const name of state.mcp_servers ?? []) {
-        const server = AGENT_STACK.mcp_servers[name];
-        if (!server?.command)
+        const server = resolveMcpServerForState(state, name, modes[name]);
+        if (server.connection_mode === "remote-curated" && server.hosted_url) {
+            servers[name] = { url: server.hosted_url, type: "streamable-http" };
             continue;
-        servers[name] = {
-            command: server.command,
-            args: server.args
-        };
+        }
+        if (server.connection_mode === "remote-custom") {
+            const remote = state.mcp_server_remote?.[name];
+            if (remote?.url)
+                servers[name] = { url: remote.url, type: remote.transport };
+            if (remote?.url_env)
+                servers[name] = { urlEnv: remote.url_env, type: remote.transport };
+            if (remote?.bearer_token_env_var && servers[name]) {
+                servers[name].bearerTokenEnvVar = remote.bearer_token_env_var;
+            }
+            continue;
+        }
+        if (!server.command)
+            continue;
+        servers[name] = { command: server.command, args: server.args };
         if (Object.keys(server.env).length > 0)
             servers[name].env = server.env;
     }
-    const outputDir = join(root, "docs/agent/generated");
-    const outputFile = mcpSnippetFileName(state.agent);
-    await mkdir(outputDir, { recursive: true });
-    await removeInactiveMcpSnippets(outputDir, outputFile);
-    await writeFile(join(outputDir, outputFile), `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`, "utf8");
+    return {
+        fileName: mcpSnippetFileName(state.agent),
+        content: `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`
+    };
 }
 async function writeCapabilityProfile(root, state) {
+    await writeFile(join(root, "docs/agent/capability-profile.md"), renderCapabilityProfile(state), "utf8");
+}
+export function renderCapabilityProfile(state) {
     const lines = [
         "# Agent Capability Profile",
         "",
@@ -345,22 +439,29 @@ async function writeCapabilityProfile(root, state) {
         lines.push("- No MCP servers enabled.");
     }
     else {
+        const modes = selectedMcpServerModes(state, state.mcp_servers);
         for (const name of state.mcp_servers) {
-            const server = AGENT_STACK.mcp_servers[name];
-            const status = server?.command ? server.execution_mode : "manual setup";
+            const server = resolveMcpServerForState(state, name, modes[name]);
+            const status = mcpModeLabel(name, modes[name]);
             lines.push(`- \`${name}\` (${status}): ${server?.smoke_test ?? "Smoke-test before use."}`);
         }
     }
-    lines.push("", "## Rules", "", "- Skill installation is project-local by default.", "- Agent target `universal` installs one shared project-local `.agents/skills` copy.", "- MCP enable/disable changes project records; install/uninstall changes external tools.", "- Keep API keys, tokens, cookies, and browser sessions out of git.", "- Cite repository source records, not raw MCP output alone.", "");
-    await writeFile(join(root, "docs/agent/capability-profile.md"), lines.join("\n"), "utf8");
+    lines.push("", "## Rules", "", "- Skill installation is project-local by default.", "- Agent target `universal` installs one shared project-local `.agents/skills` copy.", "- MCP enable/disable changes selected project records; setup/install/client/probe commands change operational state.", "- Keep API keys, tokens, cookies, and browser sessions out of git.", "- Cite repository source records, not raw MCP output alone.", "");
+    return lines.join("\n");
 }
 async function writeMcpSetup(root, state) {
+    await mkdir(join(root, "docs/agent"), { recursive: true });
+    await writeFile(join(root, "docs/agent/mcp-setup.md"), renderMcpSetup(state), "utf8");
+}
+export function renderMcpSetup(state) {
     const enabled = new Set(state.mcp_servers ?? []);
+    const modes = selectedMcpServerModes(state, state.mcp_servers ?? []);
     const lines = [
         "# MCP Setup",
         "",
         "This file is generated from the project-local academic research capability stack.",
         "MCP records are configuration snippets and setup guidance; the active MCP client must load the generated snippet before these servers become live tools.",
+        "Default CLI output uses plain mode labels: local, remote, custom remote, requires local app, and manual setup. Use `npm run mcp:status -- --verbose` for technical transport details.",
         "",
         "## Enabled MCP Servers",
         ""
@@ -370,22 +471,22 @@ async function writeMcpSetup(root, state) {
     }
     else {
         for (const name of state.mcp_servers) {
-            const server = AGENT_STACK.mcp_servers[name];
+            const server = resolveMcpServerForState(state, name, modes[name]);
             if (!server)
                 continue;
-            lines.push(`- \`${name}\` (${server.readiness}, ${server.priority}): ${server.source_need}`, `  - Source: \`${server.source}\``, `  - Execution mode: \`${server.execution_mode}\``, ...(server.hosted_url ? [`  - Hosted endpoint: <${server.hosted_url}>`] : []), `  - Runtime: ${formatRuntime(server.command, server.args)}`, `  - Install command: ${server.install_command ? `\`${server.install_command}\`` : "none; runtime-only or manual setup"}`, ...server.setup_commands.map((command) => `  - Setup command: \`${command}\``), `  - Smoke test: ${server.smoke_test}`, `  - Risks: ${server.risks}`);
+            lines.push(`- \`${name}\` (${server.readiness}, ${server.priority}): ${server.source_need}`, `  - Source: \`${server.source}\``, `  - Selected mode: \`${mcpModeLabel(name, modes[name])}\``, `  - Technical mode: \`${server.connection_mode}\``, `  - Execution mode: \`${server.execution_mode}\``, ...(server.hosted_url ? [`  - Hosted endpoint: <${server.hosted_url}>`] : []), `  - Runtime: ${formatRuntime(server.command, server.args)}`, `  - Install command: ${server.install_command ? `\`${server.install_command}\`` : "none; runtime-only or manual setup"}`, ...server.setup_commands.map((command) => `  - Setup command: \`${command}\``), `  - Smoke test: ${server.smoke_test}`, `  - Risks: ${server.risks}`);
             appendMcpPrerequisiteLines(lines, server.required_env, server.recommended_env, server.local_service);
         }
     }
     lines.push("", "## Available MCP Catalog", "");
     for (const [name, server] of Object.entries(AGENT_STACK.mcp_servers)) {
         const status = enabled.has(name) ? "enabled" : "available";
-        lines.push(`- \`${name}\` (${status}, ${server.readiness}, ${server.priority}): ${server.source_need}`, `  - Source: \`${server.source}\``, `  - Execution mode: \`${server.execution_mode}\``, ...(server.hosted_url ? [`  - Hosted endpoint: <${server.hosted_url}>`] : []), ...server.setup_commands.map((command) => `  - Setup command: \`${command}\``));
-        appendMcpPrerequisiteLines(lines, server.required_env, server.recommended_env, server.local_service);
+        const resolved = enabled.has(name) ? resolveMcpServerForState(state, name, modes[name]) : resolveMcpServer(name, mcpRecommendedMode(name));
+        lines.push(`- \`${name}\` (${status}, ${resolved.readiness}, ${resolved.priority}): ${resolved.source_need}`, `  - Source: \`${resolved.source}\``, `  - Recommended mode: \`${mcpModeLabel(name, mcpRecommendedMode(name))}\``, `  - Default mode: \`${mcpModeLabel(name)}\``, ...(server.modes ? [`  - Supported modes: ${mcpSupportedModeLabels(name).join(", ")}`] : []), `  - Execution mode: \`${resolved.execution_mode}\``, ...(resolved.hosted_url ? [`  - Hosted endpoint: <${resolved.hosted_url}>`] : []), ...mcpModeEndpointLines(name), ...resolved.setup_commands.map((command) => `  - Setup command: \`${command}\``));
+        appendMcpPrerequisiteLines(lines, resolved.required_env, resolved.recommended_env, resolved.local_service);
     }
-    lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `npm run mcp:env -- --dotenv --all`.", "- Regenerate a dotenv-style reference with `npm run mcp:dotenv`.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- Keep secrets in your shell, MCP client secret store, or local untracked files; do not commit tokens or API keys.", "- Prefer the smallest enabled MCP set that covers the current research question.", "- Treat MCP output as retrieval metadata. Promote claims into repository source records only after source ingestion and citation audit.", "- Run `npm run mcp:doctor` after changing MCP records or environment variables.", "- Run `npm run mcp:probe -- <server>` only when you intentionally want to start selected MCP server processes.", "");
-    await mkdir(join(root, "docs/agent"), { recursive: true });
-    await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
+    lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `npm run mcp:env -- --dotenv --all`.", "- Regenerate a dotenv-style reference with `npm run mcp:dotenv`.", "- Discover supported modes with `npm run mcp:modes` or `npm run mcp:modes -- openalex`.", "- Inspect selected-vs-ready lifecycle state with `npm run mcp:status`.", "- Select explicit modes with `npm run mcp:enable -- <server> --mode local` or `--mode remote` where supported.", "- Select a custom remote endpoint with `npm run mcp:enable -- <server> --mode remote-custom --url https://example.com/mcp`; use `--url-env <NAME>` for private URLs.", "- Codex automatic registration supports custom remote `--url`; if you use `--url-env`, register manually because Codex CLI has no `--url-env` option.", "- Explicit `--mode remote-custom` still needs `--url` or `--url-env`; otherwise smoke/probe report `missing-remote-url`.", "- Run manual setup with `npm run mcp:setup -- <server> --mode local --env-file .env.local`.", "- Register supported clients with `npm run mcp:client:add -- <server> --agent codex`; use `--dry-run` to print the command first.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- Keep secrets in your shell, MCP client secret store, or local untracked files; do not commit tokens or API keys.", "- Non-secret observed setup facts are recorded in `docs/agent/capability-lock.json` when setup, client registration, or probes run.", "- Prefer the smallest enabled MCP set that covers the current research question.", "- Treat MCP output as retrieval metadata. Promote claims into repository source records only after source ingestion and citation audit.", "- Run `npm run mcp:doctor` after changing MCP records or environment variables.", "- Run `npm run mcp:probe -- <server>` only when you intentionally want to start selected local stdio MCP server processes; remote endpoints report configured status without a network probe.", "");
+    return lines.join("\n");
 }
 async function appendCapabilityLog(root, state) {
     const logPath = join(root, "wiki/log.md");
@@ -399,6 +500,41 @@ function dedupe(values) {
 function envHasValue(env, name) {
     return typeof env[name] === "string" && env[name] !== "";
 }
+function normalizeRemoteConfig(server, config) {
+    if (!config || (!config.url && !config.url_env)) {
+        throw new Error(`${server}: remote-custom requires --url or --url-env`);
+    }
+    if (config.url && config.url_env) {
+        throw new Error(`${server}: remote-custom accepts either --url or --url-env, not both`);
+    }
+    const result = { transport: "streamable-http" };
+    if (config.url) {
+        try {
+            const parsed = new URL(config.url);
+            if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+                throw new Error("expected http or https URL");
+            }
+        }
+        catch (error) {
+            throw new Error(`${server}: invalid remote MCP URL: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        result.url = config.url;
+    }
+    if (config.url_env) {
+        assertEnvVarName(config.url_env, `${server}: invalid URL env var name`);
+        result.url_env = config.url_env;
+    }
+    if (config.bearer_token_env_var) {
+        assertEnvVarName(config.bearer_token_env_var, `${server}: invalid bearer token env var name`);
+        result.bearer_token_env_var = config.bearer_token_env_var;
+    }
+    return result;
+}
+function assertEnvVarName(name, message) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`${message}: ${name}`);
+    }
+}
 function renderSkillCommand(command, agent) {
     const normalized = assertKnownAgentTarget(agent);
     const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;
@@ -455,11 +591,788 @@ function appendMcpPrerequisiteLines(lines, requiredEnv, recommendedEnv, localSer
     if (localService)
         lines.push(`  - Local prerequisite: ${localService}`);
 }
+function mcpModeEndpointLines(serverName) {
+    const lines = [];
+    for (const mode of mcpServerModeKeys(serverName)) {
+        const server = resolveMcpServer(serverName, mode);
+        if (server.hosted_url)
+            lines.push(`  - Hosted endpoint: <${server.hosted_url}>`);
+    }
+    return lines;
+}
 function formatRuntime(command, args) {
     if (!command)
         return "manual setup";
     return `\`${[command, ...args].join(" ")}\``;
 }
+export async function getMcpLifecycleStatus(root, options = {}) {
+    const state = await readCapabilities(root);
+    const lock = await readCapabilityLock(root);
+    const env = options.env ?? process.env;
+    const generatedServers = await readGeneratedMcpServers(root, state);
+    const selected = new Set(state.mcp_servers ?? []);
+    const rows = [];
+    for (const id of Object.keys(AGENT_STACK.mcp_servers)) {
+        const modeKey = selected.has(id) ? selectedMcpServerModes(state, [id])[id] : mcpRecommendedMode(id);
+        const server = selected.has(id) ? resolveMcpServerForState(state, id, modeKey) : resolveMcpServer(id, modeKey);
+        const envStatus = selected.has(id) ? lifecycleEnvStatus(server, env) : "n/a";
+        const install = selected.has(id) ? lifecycleInstallStatus(root, id, server, lock) : "n/a";
+        const snippet = selected.has(id)
+            ? generatedServers.has(id)
+                ? "available"
+                : isSnippetCapable(server)
+                    ? "missing"
+                    : "none"
+            : "none";
+        const client = lifecycleClientStatus(id, server, selected.has(id), state.agent, lock);
+        const probe = selected.has(id) ? lock.mcp[id]?.probe?.status ?? "unknown" : "n/a";
+        rows.push({
+            id,
+            selected: selected.has(id),
+            mode: mcpModeLabel(id, modeKey),
+            mode_key: modeKey,
+            connection_mode: server.connection_mode,
+            state: lifecycleState(selected.has(id), envStatus, install, snippet, client, probe),
+            env: envStatus,
+            install,
+            snippet,
+            client,
+            probe,
+            next: lifecycleNextAction(id, server, selected.has(id), envStatus, install, snippet, client, probe)
+        });
+    }
+    return { servers: rows };
+}
+export async function readCapabilityLock(root) {
+    try {
+        const parsed = JSON.parse(await readFile(capabilityLockPath(root), "utf8"));
+        const record = typeof parsed === "object" && parsed !== null ? parsed : {};
+        return {
+            version: typeof record.version === "number" ? record.version : 1,
+            generator: normalizeCapabilityLockGenerator(record.generator),
+            mcp: typeof record.mcp === "object" && record.mcp !== null ? record.mcp : {},
+            skills: normalizeCapabilityLockSkills(record.skills)
+        };
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return defaultCapabilityLock();
+        throw error;
+    }
+}
+export async function setupMcpServer(root, serverName, options = {}, runner = defaultRunner) {
+    assertKnownMcpServers([serverName]);
+    const mode = normalizeMcpMode(serverName, options.mode);
+    const server = resolveMcpServer(serverName, mode);
+    if (serverName !== "overleaf") {
+        const commands = server.setup_commands.length > 0 ? server.setup_commands : [];
+        return {
+            ok: true,
+            server: serverName,
+            mode,
+            commands,
+            created: [],
+            warnings: commands.length === 0 ? [`${serverName}: no finite setup command is defined`] : [],
+            errors: [],
+            next: commands.length > 0 ? commands : [`run npm run mcp:status`]
+        };
+    }
+    const env = options.env ?? process.env;
+    const required = ["OVERLEAF_TOKEN", "PROJECT_ID"];
+    const missing = required.filter((name) => !envHasValue(env, name));
+    const paths = overleafPaths(root);
+    const commands = [
+        `git clone --depth 1 https://github.com/YounesBensafia/overleaf-mcp-server.git ${paths.relativeServer}`,
+        `cd ${paths.relativeServer} && uv sync`,
+        `write wrapper ${paths.relativeWrapper}`
+    ];
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            server: serverName,
+            mode,
+            commands,
+            created: [],
+            warnings: [],
+            errors: [`overleaf: missing required environment variable(s): ${missing.join(", ")}`],
+            next: [`fill ${missing.join(", ")} in ${options.envFile ?? ".env.local"}`]
+        };
+    }
+    if (options.dryRun) {
+        return {
+            ok: true,
+            server: serverName,
+            mode,
+            commands,
+            created: [],
+            warnings: [],
+            errors: [],
+            next: [`run npm run mcp:setup -- overleaf --mode local --env-file ${options.envFile ?? ".env.local"}`]
+        };
+    }
+    await mkdir(paths.wrapperDir, { recursive: true });
+    if (!existsSync(paths.serverDir)) {
+        await runner.run(["git", "clone", "--depth", "1", "https://github.com/YounesBensafia/overleaf-mcp-server.git", paths.serverDir], {
+            cwd: root
+        });
+    }
+    await runner.run(["uv", "sync"], { cwd: paths.serverDir });
+    await writeFile(paths.wrapper, renderOverleafWrapper(), "utf8");
+    await writeFile(paths.launcher, renderOverleafLauncher(), "utf8");
+    await chmod(paths.wrapper, 0o755);
+    await chmod(paths.launcher, 0o755);
+    await updateCapabilityLock(root, (lock) => {
+        const entry = ensureLockMcpEntry(lock, "overleaf", server);
+        entry.setup = {
+            status: "ready",
+            server_path: paths.relativeServer,
+            wrapper_path: paths.relativeWrapper,
+            env_file: options.envFile ? toPosix(relative(root, resolve(root, options.envFile))) : ".env.local",
+            updated_at: nowIso()
+        };
+    });
+    return {
+        ok: true,
+        server: serverName,
+        mode,
+        commands,
+        created: [paths.relativeWrapper, paths.relativeLauncher],
+        warnings: [],
+        errors: [],
+        next: [
+            "npm run mcp:client:add -- overleaf --agent codex",
+            "npm run mcp:probe -- overleaf --env-file .env.local"
+        ]
+    };
+}
+export async function clientAddMcpServer(root, serverName, options = {}, runner = defaultRunner) {
+    return clientMcpServer(root, serverName, "add", options, runner);
+}
+export async function clientRemoveMcpServer(root, serverName, options = {}, runner = defaultRunner) {
+    return clientMcpServer(root, serverName, "remove", options, runner);
+}
+async function clientMcpServer(root, serverName, action, options, runner) {
+    assertKnownMcpServers([serverName]);
+    const state = await readCapabilities(root);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
+    const mode = normalizeMcpMode(serverName, options.mode ?? state.mcp_server_modes[serverName]);
+    const server = resolveMcpServerForState(state, serverName, mode);
+    if (agent !== "codex") {
+        return {
+            ok: false,
+            server: serverName,
+            agent,
+            command: [],
+            instructions: [`${agent} client registration is manual; load docs/agent/generated/${mcpSnippetFileName(agent)} in the client.`]
+        };
+    }
+    const command = action === "remove"
+        ? ["codex", "mcp", "remove", serverName]
+        : codexAddCommand(root, serverName, server, state);
+    if (action === "add") {
+        const readiness = await clientRegistrationReadiness(root, serverName, server, mode, state);
+        if (!readiness.ready) {
+            return {
+                ok: false,
+                server: serverName,
+                agent,
+                command,
+                instructions: readiness.instructions
+            };
+        }
+    }
+    if (!options.dryRun) {
+        try {
+            await runner.run(command, { cwd: root });
+            await updateCapabilityLock(root, (lock) => {
+                const entry = ensureLockMcpEntry(lock, serverName, server);
+                entry.clients = entry.clients ?? {};
+                entry.clients.codex = { status: action === "add" ? "registered" : "removed", updated_at: nowIso() };
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                server: serverName,
+                agent,
+                command,
+                instructions: [
+                    `Codex CLI registration failed: ${error instanceof Error ? error.message : String(error)}`,
+                    `Run manually: ${command.join(" ")}`
+                ]
+            };
+        }
+    }
+    return {
+        ok: true,
+        server: serverName,
+        agent,
+        command,
+        instructions: options.dryRun ? [`Dry run only; no client config was changed.`] : []
+    };
+}
+function serializeCapabilityState(state) {
+    const serialized = {
+        agent: state.agent,
+        preset: state.preset,
+        scope: state.scope,
+        mcp_servers: state.mcp_servers
+    };
+    if (Object.keys(state.mcp_server_modes).length > 0)
+        serialized.mcp_server_modes = state.mcp_server_modes;
+    if (Object.keys(state.mcp_server_remote).length > 0)
+        serialized.mcp_server_remote = state.mcp_server_remote;
+    return serialized;
+}
+function normalizeMcpServerModeMap(modes, servers) {
+    const selected = new Set(servers);
+    const result = {};
+    for (const [server, mode] of Object.entries(modes)) {
+        if (selected.has(server))
+            result[server] = normalizeMcpMode(server, mode);
+    }
+    return result;
+}
+function normalizeMcpServerRemoteMap(remote, servers, modes) {
+    const selected = new Set(servers);
+    const result = {};
+    for (const [server, config] of Object.entries(remote)) {
+        if (!selected.has(server))
+            continue;
+        const mode = normalizeMcpMode(server, modes[server]);
+        if (mode === "remote-custom")
+            result[server] = normalizeRemoteConfig(server, config);
+    }
+    return result;
+}
+function selectedMcpServerModes(state, servers) {
+    const modes = {};
+    for (const server of servers) {
+        modes[server] = normalizeMcpMode(server, state.mcp_server_modes?.[server]);
+    }
+    return modes;
+}
+export function resolveMcpServerForState(state, serverName, mode) {
+    const server = resolveMcpServer(serverName, mode ?? state.mcp_server_modes?.[serverName]);
+    if (server.selected_mode !== "remote-custom")
+        return server;
+    const remote = state.mcp_server_remote?.[serverName];
+    const remoteConfigured = Boolean(remote?.url || remote?.url_env);
+    return {
+        ...server,
+        hosted_url: remote?.url ?? "",
+        remote_url_env: remote?.url_env,
+        remote_configured: remoteConfigured,
+        required_env: remote?.url_env ? [...server.required_env, remote.url_env] : server.required_env,
+        recommended_env: remote?.bearer_token_env_var
+            ? [...server.recommended_env, remote.bearer_token_env_var]
+            : server.recommended_env
+    };
+}
+async function readGeneratedMcpServers(root, state) {
+    const generated = new Set();
+    try {
+        const rawSnippet = await readFile(join(root, "docs", "agent", "generated", mcpSnippetFileName(state.agent)), "utf8");
+        const snippet = JSON.parse(rawSnippet);
+        for (const name of Object.keys(snippet.mcpServers ?? {}))
+            generated.add(name);
+    }
+    catch {
+        return generated;
+    }
+    return generated;
+}
+function lifecycleEnvStatus(server, env) {
+    if (server.required_env.some((name) => !envHasValue(env, name)))
+        return "missing-required";
+    if (server.recommended_env.some((name) => !envHasValue(env, name)))
+        return "missing-recommended";
+    return "ok";
+}
+function lifecycleState(selected, envStatus, install, snippet, client, probe) {
+    if (!selected)
+        return "not selected";
+    if (envStatus === "missing-required")
+        return "missing env";
+    if (install === "setup needed" || install === "requires local app" || install === "manual setup")
+        return install;
+    if (snippet === "missing")
+        return "setup needed";
+    if (client.endsWith(":not-added"))
+        return "setup needed";
+    if (probe === "unknown")
+        return "probe needed";
+    if (!isSuccessfulProbeStatus(probe))
+        return "probe failed";
+    return "ready";
+}
+function lifecycleInstallStatus(root, serverName, server, lock) {
+    if (server.connection_mode === "remote-curated" || server.connection_mode === "remote-custom")
+        return "remote";
+    if (server.connection_mode === "manual-local") {
+        const entry = lock.mcp[serverName];
+        const setup = entry?.setup;
+        if (setup?.status === "ready" &&
+            entry?.selected_mode === server.selected_mode &&
+            entry?.connection_mode === server.connection_mode &&
+            setup.wrapper_path &&
+            existsSync(join(root, setup.wrapper_path))) {
+            return "ready";
+        }
+        return "setup needed";
+    }
+    if (server.connection_mode === "local-service")
+        return "requires local app";
+    if (server.install_command)
+        return "finite-installer";
+    if (server.command)
+        return "runtime-only";
+    return "manual setup";
+}
+function lifecycleClientStatus(serverName, server, selected, agent, lock) {
+    if (!selected)
+        return "none";
+    if (!isSnippetCapable(server))
+        return "unsupported";
+    const normalizedAgent = assertKnownAgentTarget(agent);
+    if (normalizedAgent === "universal")
+        return "snippet";
+    if (normalizedAgent === "codex") {
+        const status = lock.mcp[serverName]?.clients?.codex?.status;
+        return status === "registered" ? "codex:registered" : "codex:not-added";
+    }
+    if (normalizedAgent === "claude-code" || normalizedAgent === "cursor")
+        return `${normalizedAgent}:manual`;
+    return "unknown";
+}
+function lifecycleNextAction(serverName, server, selected, envStatus, install, snippet, client, probe) {
+    if (!selected) {
+        const recommended = mcpRecommendedMode(serverName);
+        const alternatives = mcpServerModeKeys(serverName).filter((mode) => mode !== recommended);
+        const altText = alternatives.length > 0
+            ? `, alternative: ${alternatives.map((mode) => mcpModeKeyLabelForAction(mode)).join(", ")}`
+            : "";
+        return `enable ${serverName}, recommended: ${mcpModeKeyLabelForAction(recommended)}${altText}`;
+    }
+    if (envStatus === "missing-required") {
+        if (server.connection_mode === "manual-local") {
+            return `fill ${server.required_env.join(", ")} in .env.local; then run npm run mcp:setup -- ${serverName} --mode local --env-file .env.local`;
+        }
+        return `fill ${server.required_env.join(", ")} in .env.local`;
+    }
+    if (install === "setup needed" && server.connection_mode === "manual-local") {
+        return `run npm run mcp:setup -- ${serverName} --mode local --env-file .env.local`;
+    }
+    if (install === "requires local app") {
+        return server.setup_commands[0] ?? `start local service for ${serverName}`;
+    }
+    if (snippet === "missing")
+        return "run npm run update -- --apply";
+    if (client.endsWith(":not-added"))
+        return `run npm run mcp:client:add -- ${serverName} --agent codex`;
+    if (!isSuccessfulProbeStatus(probe))
+        return `run npm run mcp:probe -- ${serverName} --env-file .env.local`;
+    return "ready";
+}
+function isSuccessfulProbeStatus(probe) {
+    return probe === "ok" || probe === "remote-configured";
+}
+function mcpModeKeyLabelForAction(mode) {
+    if (mode === "remote-custom")
+        return "custom remote";
+    if (mode === "remote")
+        return "remote";
+    if (mode === "manual")
+        return "manual setup";
+    return "local";
+}
+function mcpInstallSkip(serverName, server) {
+    if (server.connection_mode === "manual-local") {
+        return {
+            server: serverName,
+            reason: "manual setup",
+            next: `run npm run mcp:setup -- ${serverName} --mode local --env-file .env.local`
+        };
+    }
+    if (server.connection_mode === "remote-curated" || server.connection_mode === "remote-custom") {
+        return { server: serverName, reason: "remote", next: "no local installer; register the hosted endpoint with the MCP client" };
+    }
+    if (server.connection_mode === "local-service") {
+        return {
+            server: serverName,
+            reason: "requires local app",
+            next: server.setup_commands[0] ? `run ${server.setup_commands[0]}` : "satisfy the local service prerequisite"
+        };
+    }
+    if (server.command) {
+        return { server: serverName, reason: "runtime-only", next: "the MCP client launches it on demand" };
+    }
+    return { server: serverName, reason: "manual", next: "follow docs/agent/mcp-setup.md" };
+}
+function mcpUninstallSkip(serverName, server) {
+    const skipped = mcpInstallSkip(serverName, server);
+    return { ...skipped, next: skipped.reason === "runtime-only" ? "no persistent tool was installed" : skipped.next };
+}
+function isSnippetCapable(server) {
+    return Boolean(server.command ||
+        (server.connection_mode === "remote-curated" && server.hosted_url) ||
+        server.connection_mode === "remote-custom");
+}
+function capabilityLockPath(root) {
+    return join(root, "docs", "agent", "capability-lock.json");
+}
+async function updateCapabilityLock(root, update) {
+    const lock = await readCapabilityLock(root);
+    lock.generator = {
+        name: "create-academic-research",
+        version: await currentPackageVersion(),
+        updated_at: nowIso()
+    };
+    update(lock);
+    await mkdir(dirname(capabilityLockPath(root)), { recursive: true });
+    await writeFile(capabilityLockPath(root), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+function defaultCapabilityLock() {
+    return {
+        version: 1,
+        generator: { name: "create-academic-research" },
+        mcp: {},
+        skills: { sources: {}, skills: {} }
+    };
+}
+function normalizeCapabilityLockGenerator(value) {
+    const record = typeof value === "object" && value !== null ? value : {};
+    return {
+        name: "create-academic-research",
+        ...(typeof record.version === "string" ? { version: record.version } : {}),
+        ...(typeof record.updated_at === "string" ? { updated_at: record.updated_at } : {})
+    };
+}
+function normalizeCapabilityLockSkills(value) {
+    const record = typeof value === "object" && value !== null ? value : {};
+    return {
+        ...(typeof record.preset === "string" ? { preset: record.preset } : {}),
+        ...(typeof record.agent === "string" ? { agent: record.agent } : {}),
+        ...(Array.isArray(record.explicit_skill_ids)
+            ? { explicit_skill_ids: record.explicit_skill_ids.filter((item) => typeof item === "string") }
+            : {}),
+        ...(record.last_action === "install" || record.last_action === "update" || record.last_action === "remove"
+            ? { last_action: record.last_action }
+            : {}),
+        ...(record.status === "ready" || record.status === "updated" || record.status === "removed"
+            ? { status: record.status }
+            : {}),
+        ...(typeof record.updated_at === "string" ? { updated_at: record.updated_at } : {}),
+        sources: normalizeCapabilityLockEntryMap(record.sources),
+        skills: normalizeCapabilityLockEntryMap(record.skills)
+    };
+}
+function normalizeCapabilityLockEntryMap(value) {
+    if (typeof value !== "object" || value === null)
+        return {};
+    const result = {};
+    for (const [name, rawEntry] of Object.entries(value)) {
+        if (typeof rawEntry !== "object" || rawEntry === null)
+            continue;
+        const entry = rawEntry;
+        if (typeof entry.source !== "string")
+            continue;
+        result[name] = {
+            source: entry.source,
+            ...(Array.isArray(entry.skill_ids)
+                ? { skill_ids: entry.skill_ids.filter((item) => typeof item === "string") }
+                : {}),
+            action: entry.action === "update" || entry.action === "remove" ? entry.action : "install",
+            status: entry.status === "updated" || entry.status === "removed" ? entry.status : "ready",
+            ...(typeof entry.updated_at === "string" ? { updated_at: entry.updated_at } : {}),
+            ...(typeof entry.root === "string" ? { root: entry.root } : {}),
+            ...(typeof entry.path === "string" ? { path: entry.path } : {})
+        };
+    }
+    return result;
+}
+function ensureLockMcpEntry(lock, serverName, server) {
+    const entry = lock.mcp[serverName] ?? {};
+    entry.selected_mode = server.selected_mode;
+    entry.connection_mode = server.connection_mode;
+    lock.mcp[serverName] = entry;
+    return entry;
+}
+function overleafPaths(root) {
+    const relativeBase = ".academic-research/mcp/overleaf";
+    const wrapperDir = join(root, relativeBase);
+    return {
+        wrapperDir,
+        serverDir: join(wrapperDir, "server"),
+        wrapper: join(wrapperDir, "run-overleaf-mcp.sh"),
+        launcher: join(wrapperDir, "run-overleaf-mcp.mjs"),
+        relativeServer: `${relativeBase}/server`,
+        relativeWrapper: `${relativeBase}/run-overleaf-mcp.sh`,
+        relativeLauncher: `${relativeBase}/run-overleaf-mcp.mjs`
+    };
+}
+function renderOverleafWrapper() {
+    return [
+        "#!/bin/sh",
+        "set -eu",
+        "WRAPPER_DIR=$(CDPATH= cd -- \"$(dirname -- \"$0\")\" && pwd)",
+        "# .env.local is parsed by the Node launcher; this shell wrapper never evaluates it.",
+        "exec node \"$WRAPPER_DIR/run-overleaf-mcp.mjs\"",
+        ""
+    ].join("\n");
+}
+function renderOverleafLauncher() {
+    return [
+        "#!/usr/bin/env node",
+        "import { existsSync, readFileSync } from 'node:fs';",
+        "import { dirname, join, resolve } from 'node:path';",
+        "import { fileURLToPath } from 'node:url';",
+        "import { spawn } from 'node:child_process';",
+        "",
+        "const wrapperDir = dirname(fileURLToPath(import.meta.url));",
+        "const projectRoot = resolve(wrapperDir, '../../..');",
+        "const serverDir = process.env.OVERLEAF_MCP_SERVER_PATH || join(projectRoot, '.academic-research/mcp/overleaf/server');",
+        "const envFile = process.env.ACADEMIC_RESEARCH_MCP_ENV_FILE || join(projectRoot, '.env.local');",
+        "const env = { ...process.env };",
+        "if (existsSync(envFile)) {",
+        "  for (const [name, value] of Object.entries(parseDotenv(readFileSync(envFile, 'utf8'), envFile))) {",
+        "    if (value || !(name in env)) env[name] = value;",
+        "  }",
+        "}",
+        "env.PYTHONPATH = env.PYTHONPATH || '.';",
+        "const child = spawn('uv', ['run', 'src/main.py'], { cwd: serverDir, env, stdio: 'inherit' });",
+        "child.on('error', (error) => {",
+        "  console.error(`Failed to launch Overleaf MCP server: ${error.message}`);",
+        "  process.exitCode = 1;",
+        "});",
+        "child.on('exit', (code, signal) => {",
+        "  if (signal) process.kill(process.pid, signal);",
+        "  process.exit(code ?? 1);",
+        "});",
+        "",
+        "function parseDotenv(raw, path) {",
+        "  const env = {};",
+        "  const lines = raw.split(/\\r?\\n/);",
+        "  for (const [index, line] of lines.entries()) {",
+        "    let text = line.trim();",
+        "    if (!text || text.startsWith('#')) continue;",
+        "    if (text.startsWith('export ')) text = text.slice('export '.length).trimStart();",
+        "    const equals = text.indexOf('=');",
+        "    if (equals === -1) throw new Error(`${path}:${index + 1}: expected KEY=value`);",
+        "    const key = text.slice(0, equals).trim();",
+        "    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {",
+        "      throw new Error(`${path}:${index + 1}: invalid environment variable name: ${key}`);",
+        "    }",
+        "    env[key] = parseDotenvValue(text.slice(equals + 1).trim(), path, index + 1);",
+        "  }",
+        "  return env;",
+        "}",
+        "",
+        "function parseDotenvValue(value, path, line) {",
+        "  if (!value) return '';",
+        "  const quote = value[0];",
+        "  if (quote === \"'\" || quote === '\"') {",
+        "    if (!value.endsWith(quote) || value.length === 1) throw new Error(`${path}:${line}: unterminated quoted value`);",
+        "    const unquoted = value.slice(1, -1);",
+        "    if (quote === \"'\") return unquoted;",
+        "    return unquoted",
+        "      .replaceAll('\\\\n', '\\n')",
+        "      .replaceAll('\\\\r', '\\r')",
+        "      .replaceAll('\\\\t', '\\t')",
+        "      .replaceAll('\\\\\"', '\"')",
+        "      .replaceAll('\\\\\\\\', '\\\\');",
+        "  }",
+        "  return value.replace(/\\s+#.*$/, '').trimEnd();",
+        "}",
+        ""
+    ].join("\n");
+}
+async function clientRegistrationReadiness(root, serverName, server, mode, state) {
+    const remote = state.mcp_server_remote?.[serverName];
+    if (server.connection_mode === "remote-custom" && remote?.url_env) {
+        return {
+            ready: false,
+            instructions: [
+                "Codex CLI does not support URL env vars for remote MCP endpoints.",
+                `Either re-enable this server with \`npm run mcp:enable -- ${serverName} --mode remote-custom --url <url>\` if the endpoint URL may be stored in Codex config, or register it manually with \`codex mcp add ${serverName} --url "$${remote.url_env}"\` from a shell where the env var is set.`
+            ]
+        };
+    }
+    if (serverName !== "overleaf")
+        return { ready: true, instructions: [] };
+    const lock = await readCapabilityLock(root);
+    const setup = lock.mcp.overleaf?.setup;
+    const wrapperPath = setup?.wrapper_path ? join(root, setup.wrapper_path) : "";
+    const ready = setup?.status === "ready" &&
+        lock.mcp.overleaf?.selected_mode === mode &&
+        lock.mcp.overleaf?.connection_mode === server.connection_mode &&
+        Boolean(wrapperPath) &&
+        existsSync(wrapperPath);
+    if (ready)
+        return { ready: true, instructions: [] };
+    return {
+        ready: false,
+        instructions: [
+            "Overleaf setup is not ready. Next: npm run mcp:setup -- overleaf --mode local --env-file .env.local"
+        ]
+    };
+}
+function codexAddCommand(root, serverName, server, state) {
+    if ((server.connection_mode === "remote-curated" || server.connection_mode === "remote-custom") && server.hosted_url) {
+        const command = ["codex", "mcp", "add", serverName, "--url", server.hosted_url];
+        const tokenEnv = state.mcp_server_remote?.[serverName]?.bearer_token_env_var;
+        if (tokenEnv)
+            command.push("--bearer-token-env-var", tokenEnv);
+        return command;
+    }
+    if (server.connection_mode === "remote-custom" && state.mcp_server_remote?.[serverName]?.url_env) {
+        return [];
+    }
+    if (!server.command)
+        throw new Error(`${serverName} does not have a command or hosted URL for client registration`);
+    const command = commandForClient(root, server.command);
+    return ["codex", "mcp", "add", serverName, "--", command, ...server.args];
+}
+function commandForClient(root, command) {
+    if (!command.includes("/") && !command.includes("\\"))
+        return command;
+    return isAbsolute(command) ? command : join(root, command);
+}
+async function recordSkillPresetLock(root, preset, agent, action) {
+    const selected = AGENT_STACK.presets[preset];
+    if (!selected)
+        return;
+    await updateCapabilityLock(root, (lock) => {
+        lock.skills.preset = preset;
+        lock.skills.agent = agent;
+        delete lock.skills.explicit_skill_ids;
+        lock.skills.last_action = action;
+        lock.skills.status = "ready";
+        lock.skills.updated_at = nowIso();
+        for (const bundleName of selected.skill_bundles) {
+            for (const source of skillSourcesForBundle(bundleName)) {
+                lock.skills.sources[source.key] = {
+                    source: source.source,
+                    skill_ids: source.skillIds,
+                    action,
+                    status: "ready",
+                    updated_at: nowIso()
+                };
+            }
+        }
+    });
+}
+async function recordExplicitSkillLock(root, skills, agent, action) {
+    await updateCapabilityLock(root, (lock) => {
+        lock.skills.agent = agent;
+        lock.skills.explicit_skill_ids = skills;
+        lock.skills.last_action = action;
+        lock.skills.status = "ready";
+        lock.skills.updated_at = nowIso();
+        for (const skill of skills) {
+            const source = skillSourceForId(skill);
+            if (!source)
+                continue;
+            lock.skills.skills[skill] = {
+                source,
+                action,
+                status: "ready",
+                updated_at: nowIso()
+            };
+        }
+    });
+}
+async function recordSkillUpdateLock(root) {
+    await updateCapabilityLock(root, (lock) => {
+        lock.skills.last_action = "update";
+        lock.skills.status = "updated";
+        lock.skills.updated_at = nowIso();
+        for (const entry of Object.values(lock.skills.sources)) {
+            entry.action = "update";
+            entry.status = "updated";
+            entry.updated_at = nowIso();
+        }
+        for (const entry of Object.values(lock.skills.skills)) {
+            entry.action = "update";
+            entry.status = "updated";
+            entry.updated_at = nowIso();
+        }
+    });
+}
+async function recordRemovedSkillLock(root, skills) {
+    await updateCapabilityLock(root, (lock) => {
+        lock.skills.last_action = "remove";
+        lock.skills.status = "removed";
+        lock.skills.updated_at = nowIso();
+        for (const skill of normalizeSkillIds(skills)) {
+            const source = skillSourceForId(skill) ?? lock.skills.skills[skill]?.source ?? "unknown";
+            lock.skills.skills[skill] = {
+                source,
+                action: "remove",
+                status: "removed",
+                updated_at: nowIso()
+            };
+        }
+    });
+}
+function skillSourcesForBundle(bundleName) {
+    const bundle = AGENT_STACK.skill_bundles[bundleName];
+    if (!bundle)
+        return [];
+    const selections = new Map();
+    for (const command of bundle.commands) {
+        const match = /\bskills\s+add\s+(\S+)/.exec(command);
+        const source = match?.[1];
+        if (!source)
+            continue;
+        const knownSource = skillSourceEntryForSource(source);
+        const key = knownSource?.key ?? bundleName;
+        const skillIds = skillIdsForBundleCommand(command, source);
+        const existing = selections.get(key);
+        selections.set(key, {
+            key,
+            source,
+            skillIds: [...new Set([...(existing?.skillIds ?? []), ...skillIds])]
+        });
+    }
+    return [...selections.values()];
+}
+function skillSourceEntryForSource(source) {
+    for (const [key, entry] of Object.entries(AGENT_STACK.skill_sources)) {
+        if (entry.source === source)
+            return { key, skills: entry.skills };
+    }
+    return undefined;
+}
+function skillIdsForBundleCommand(command, source) {
+    const known = skillSourceEntryForSource(source);
+    const tokens = splitCommand(command);
+    const skillFlag = tokens.indexOf("--skill");
+    if (skillFlag === -1)
+        return known?.skills ?? [];
+    const selected = [];
+    for (let index = skillFlag + 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.startsWith("-"))
+            break;
+        if (token === "*")
+            return known?.skills ?? [];
+        selected.push(token);
+    }
+    return selected.length > 0 ? selected : known?.skills ?? [];
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+async function currentPackageVersion() {
+    try {
+        const parsed = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function readCapabilitiesFile(root) {
     const path = join(root, "configs/capabilities.yaml");
     return normalizeCapabilityState(YAML.parse(await readFile(path, "utf8")));
@@ -500,17 +1413,49 @@ function splitCommand(command) {
 }
 function normalizeCapabilityState(value) {
     const record = typeof value === "object" && value !== null ? value : {};
+    const servers = Array.isArray(record.mcp_servers)
+        ? record.mcp_servers.filter((item) => typeof item === "string")
+        : [];
+    const modeRecord = typeof record.mcp_server_modes === "object" && record.mcp_server_modes !== null
+        ? record.mcp_server_modes
+        : {};
+    const mcpServerModes = {};
+    for (const [server, mode] of Object.entries(modeRecord)) {
+        if (typeof mode === "string" && servers.includes(server)) {
+            mcpServerModes[server] = normalizeMcpMode(server, mode);
+        }
+    }
+    const remoteRecord = typeof record.mcp_server_remote === "object" && record.mcp_server_remote !== null
+        ? record.mcp_server_remote
+        : {};
+    const mcpServerRemote = {};
+    for (const [server, config] of Object.entries(remoteRecord)) {
+        if (!servers.includes(server))
+            continue;
+        if (normalizeMcpMode(server, mcpServerModes[server]) !== "remote-custom")
+            continue;
+        if (typeof config === "object" && config !== null) {
+            mcpServerRemote[server] = normalizeRemoteConfig(server, config);
+        }
+    }
     return {
         agent: assertKnownAgentTarget(typeof record.agent === "string" ? record.agent : undefined),
         preset: typeof record.preset === "string" ? record.preset : "default",
         scope: "project-local",
-        mcp_servers: Array.isArray(record.mcp_servers)
-            ? record.mcp_servers.filter((item) => typeof item === "string")
-            : []
+        mcp_servers: servers,
+        mcp_server_modes: mcpServerModes,
+        mcp_server_remote: mcpServerRemote
     };
 }
 function defaultCapabilities() {
-    return { agent: DEFAULT_AGENT, preset: "default", scope: "project-local", mcp_servers: [] };
+    return {
+        agent: DEFAULT_AGENT,
+        preset: "default",
+        scope: "project-local",
+        mcp_servers: [],
+        mcp_server_modes: {},
+        mcp_server_remote: {}
+    };
 }
 function isMissingFileError(error) {
     return (typeof error === "object" &&