create-academic-research 0.1.13 → 0.1.15

package/dist/src/stack.d.ts

@@ -12,6 +12,27 @@ export interface CapabilityPreset {
     skill_bundles: string[];
     mcp_servers: string[];
 }
+export type McpConnectionMode = "stdio-local" | "remote-curated" | "remote-custom" | "local-service" | "manual-local" | "manual";
+export interface McpServerMode {
+    connection_mode: McpConnectionMode;
+    readiness?: string;
+    priority?: string;
+    execution_mode?: string;
+    source_need?: string;
+    source?: string;
+    hosted_url?: string;
+    install_command?: string;
+    uninstall_command?: string;
+    setup_commands?: string[];
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    required_env?: string[];
+    recommended_env?: string[];
+    local_service?: string;
+    smoke_test?: string;
+    risks?: string;
+}
 export interface McpServer {
     readiness: string;
     priority: string;
@@ -30,6 +51,15 @@ export interface McpServer {
     local_service: string;
     smoke_test: string;
     risks: string;
+    default_mode?: string;
+    recommended_mode?: string;
+    modes?: Record<string, McpServerMode>;
+}
+export interface ResolvedMcpServer extends McpServer {
+    selected_mode: string;
+    connection_mode: McpConnectionMode;
+    remote_url_env?: string;
+    remote_configured?: boolean;
 }
 export interface AgentStack {
     version: number;
@@ -42,3 +72,11 @@ export interface AgentStack {
 export type McpToolCommandKey = "install_command" | "uninstall_command";
 export declare const AGENT_STACK: AgentStack;
 export declare function presetMcpServers(preset: string): string[];
+export declare function resolveMcpServer(serverName: string, mode?: string): ResolvedMcpServer;
+export declare function normalizeMcpMode(serverName: string, mode?: string): string;
+export declare function mcpServerModeKeys(serverName: string): string[];
+export declare function mcpRecommendedMode(serverName: string): string;
+export declare function mcpModeLabel(serverName: string, mode?: string): string;
+export declare function mcpModeKeyLabel(mode: string): string;
+export declare function mcpSupportedModeLabels(serverName: string): string[];
+export declare function modeAlias(mode: string): string;

package/dist/src/stack.js

@@ -142,7 +142,26 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "",
             smoke_test: "For a computer science project, search one CS query, download one known paper, and read it locally.",
-            risks: "Respect arXiv rate limits; paper text is untrusted input."
+            risks: "Respect arXiv rate limits; paper text is untrusted input.",
+            default_mode: "local",
+            recommended_mode: "local",
+            modes: {
+                local: {
+                    connection_mode: "stdio-local"
+                },
+                "remote-custom": {
+                    connection_mode: "remote-custom",
+                    execution_mode: "remote-custom",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: []
+                }
+            }
         },
         "semantic-scholar": {
             readiness: "credential-recommended",
@@ -161,7 +180,26 @@ export const AGENT_STACK = {
             recommended_env: ["SEMANTIC_SCHOLAR_API_KEY"],
             smoke_test: "Search one known title, then fetch citations or references.",
             local_service: "",
-            risks: "API key recommended for sustained work and to avoid shared-pool rate limits; metadata can be incomplete."
+            risks: "API key recommended for sustained work and to avoid shared-pool rate limits; metadata can be incomplete.",
+            default_mode: "local",
+            recommended_mode: "local",
+            modes: {
+                local: {
+                    connection_mode: "stdio-local"
+                },
+                "remote-custom": {
+                    connection_mode: "remote-custom",
+                    execution_mode: "remote-custom",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: []
+                }
+            }
         },
         openalex: {
             readiness: "credential-required",
@@ -169,7 +207,7 @@ export const AGENT_STACK = {
             execution_mode: "npx-runtime",
             source_need: "OpenAlex broad scholarly graph.",
             source: "cyanheads/openalex-mcp-server",
-            hosted_url: "https://openalex.caseyjhand.com/mcp",
+            hosted_url: "",
             install_command: "",
             uninstall_command: "",
             setup_commands: [],
@@ -180,7 +218,44 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "",
             smoke_test: "Search works by title or DOI and confirm stable OpenAlex IDs.",
-            risks: "The selected local server requires OPENALEX_API_KEY. OpenAlex keys are free and include a free daily quota; check current credit limits, smoke-test coverage, and inspect cost headers before high-volume work."
+            risks: "The selected local server requires OPENALEX_API_KEY. OpenAlex keys are free and include a free daily quota; check current credit limits, smoke-test coverage, and inspect cost headers before high-volume work.",
+            default_mode: "local",
+            recommended_mode: "remote",
+            modes: {
+                local: {
+                    connection_mode: "stdio-local"
+                },
+                remote: {
+                    connection_mode: "remote-curated",
+                    execution_mode: "remote-curated",
+                    hosted_url: "https://openalex.caseyjhand.com/mcp",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: [],
+                    smoke_test: "Connect the MCP client to the hosted streamable HTTP endpoint and run a read-only works search.",
+                    risks: "Hosted endpoint behavior, authentication, rate limits, and availability are controlled by the endpoint operator; verify current policy before sustained use."
+                },
+                "remote-custom": {
+                    connection_mode: "remote-custom",
+                    execution_mode: "remote-custom",
+                    hosted_url: "",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: [],
+                    smoke_test: "Connect the MCP client to the custom streamable HTTP endpoint and run a read-only works search.",
+                    risks: "Custom endpoint behavior, authentication, rate limits, and availability are controlled by the endpoint operator; verify current policy before sustained use."
+                }
+            }
         },
         crossref: {
             readiness: "manual",
@@ -199,7 +274,14 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "",
             smoke_test: "Resolve one DOI into publication metadata after choosing a maintained local server.",
-            risks: "Manual integration only; current zero-friction Crossref-only MCP candidates are less mature than arXiv, DBLP, PubMed, or OpenAlex."
+            risks: "Manual integration only; current zero-friction Crossref-only MCP candidates are less mature than arXiv, DBLP, PubMed, or OpenAlex.",
+            default_mode: "manual",
+            recommended_mode: "manual",
+            modes: {
+                manual: {
+                    connection_mode: "manual"
+                }
+            }
         },
         pubmed: {
             readiness: "domain-specific",
@@ -207,7 +289,7 @@ export const AGENT_STACK = {
             execution_mode: "npx-runtime",
             source_need: "PubMed and biomedical literature.",
             source: "cyanheads/pubmed-mcp-server",
-            hosted_url: "https://pubmed.caseyjhand.com/mcp",
+            hosted_url: "",
             install_command: "",
             uninstall_command: "",
             setup_commands: [],
@@ -218,7 +300,44 @@ export const AGENT_STACK = {
             recommended_env: ["NCBI_API_KEY", "NCBI_ADMIN_EMAIL"],
             local_service: "",
             smoke_test: "Search one PMID or title and fetch metadata.",
-            risks: "Domain-specific; observe NCBI rate limits. API key and contact email improve reliability."
+            risks: "Domain-specific; observe NCBI rate limits. API key and contact email improve reliability.",
+            default_mode: "local",
+            recommended_mode: "remote",
+            modes: {
+                local: {
+                    connection_mode: "stdio-local"
+                },
+                remote: {
+                    connection_mode: "remote-curated",
+                    execution_mode: "remote-curated",
+                    hosted_url: "https://pubmed.caseyjhand.com/mcp",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: [],
+                    smoke_test: "Connect the MCP client to the hosted streamable HTTP endpoint and run a read-only PubMed search.",
+                    risks: "Hosted endpoint behavior, authentication, NCBI policy handling, and availability are controlled by the endpoint operator; verify current policy before sustained use."
+                },
+                "remote-custom": {
+                    connection_mode: "remote-custom",
+                    execution_mode: "remote-custom",
+                    hosted_url: "",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: [],
+                    smoke_test: "Connect the MCP client to the custom streamable HTTP endpoint and run a read-only PubMed search.",
+                    risks: "Custom endpoint behavior, authentication, NCBI policy handling, and availability are controlled by the endpoint operator; verify current policy before sustained use."
+                }
+            }
         },
         dblp: {
             readiness: "low-friction-cs",
@@ -237,7 +356,26 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "",
             smoke_test: "Search one known CS paper title and export or inspect its DBLP BibTeX.",
-            risks: "CS-specific metadata source; use with arXiv/Semantic Scholar/OpenAlex for coverage beyond DBLP."
+            risks: "CS-specific metadata source; use with arXiv/Semantic Scholar/OpenAlex for coverage beyond DBLP.",
+            default_mode: "local",
+            recommended_mode: "local",
+            modes: {
+                local: {
+                    connection_mode: "stdio-local"
+                },
+                "remote-custom": {
+                    connection_mode: "remote-custom",
+                    execution_mode: "remote-custom",
+                    install_command: "",
+                    uninstall_command: "",
+                    setup_commands: [],
+                    command: "",
+                    args: [],
+                    env: {},
+                    required_env: [],
+                    recommended_env: []
+                }
+            }
         },
         zotero: {
             readiness: "local-service",
@@ -256,7 +394,14 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "Zotero desktop running with local API enabled; Zoty Bridge required for attachment and collection write operations.",
             smoke_test: "List collections, search one known item, and export BibTeX.",
-            risks: "Requires Zotero local API and bridge setup."
+            risks: "Requires Zotero local API and bridge setup.",
+            default_mode: "local",
+            recommended_mode: "local",
+            modes: {
+                local: {
+                    connection_mode: "local-service"
+                }
+            }
         },
         overleaf: {
             readiness: "manual-credentialed",
@@ -268,14 +413,21 @@ export const AGENT_STACK = {
             install_command: "",
             uninstall_command: "",
             setup_commands: [],
-            command: "",
+            command: ".academic-research/mcp/overleaf/run-overleaf-mcp.sh",
             args: [],
             env: {},
-            required_env: ["OVERLEAF_TOKEN"],
-            recommended_env: ["PROJECT_ID"],
+            required_env: ["OVERLEAF_TOKEN", "PROJECT_ID"],
+            recommended_env: [],
             local_service: "Local clone of the Overleaf MCP server configured with uv and an Overleaf project that supports Git sync.",
             smoke_test: "List projects or read one .tex file; do not write by default.",
-            risks: "Requires token and project setup; write/push access needs explicit approval."
+            risks: "Requires token and project setup; write/push access needs explicit approval.",
+            default_mode: "local",
+            recommended_mode: "local",
+            modes: {
+                local: {
+                    connection_mode: "manual-local"
+                }
+            }
         },
         "paper-search": {
             readiness: "fallback",
@@ -297,7 +449,14 @@ export const AGENT_STACK = {
             ],
             local_service: "Manual review required before enabling; configure only permitted sources.",
             smoke_test: "Search one harmless query with a source allow-list and verify provenance for each result.",
-            risks: "Powerful aggregator with optional restricted-source workflows; keep Sci-Hub or questionable download features disabled unless explicitly accepted."
+            risks: "Powerful aggregator with optional restricted-source workflows; keep Sci-Hub or questionable download features disabled unless explicitly accepted.",
+            default_mode: "manual",
+            recommended_mode: "manual",
+            modes: {
+                manual: {
+                    connection_mode: "manual"
+                }
+            }
         }
     }
 };
@@ -307,3 +466,90 @@ export function presetMcpServers(preset) {
         throw new Error(`unknown capability preset: ${preset}`);
     return [...config.mcp_servers];
 }
+export function resolveMcpServer(serverName, mode) {
+    const server = AGENT_STACK.mcp_servers[serverName];
+    if (!server)
+        throw new Error(`unknown MCP server: ${serverName}`);
+    const selectedMode = normalizeMcpMode(serverName, mode);
+    const variant = server.modes?.[selectedMode];
+    return {
+        ...server,
+        ...variant,
+        selected_mode: selectedMode,
+        connection_mode: variant?.connection_mode ?? defaultConnectionMode(server.execution_mode)
+    };
+}
+export function normalizeMcpMode(serverName, mode) {
+    const server = AGENT_STACK.mcp_servers[serverName];
+    if (!server)
+        throw new Error(`unknown MCP server: ${serverName}`);
+    const defaultMode = server.default_mode ?? "local";
+    if (!mode)
+        return defaultMode;
+    const normalized = modeAlias(mode);
+    if (server.modes?.[normalized])
+        return normalized;
+    if (!server.modes && normalized === defaultMode)
+        return defaultMode;
+    throw new Error(`${serverName} does not support MCP mode ${mode}. Supported modes: ${mcpServerModeKeys(serverName).join(", ")}`);
+}
+export function mcpServerModeKeys(serverName) {
+    const server = AGENT_STACK.mcp_servers[serverName];
+    if (!server)
+        throw new Error(`unknown MCP server: ${serverName}`);
+    return Object.keys(server.modes ?? { [server.default_mode ?? "local"]: { connection_mode: defaultConnectionMode(server.execution_mode) } });
+}
+export function mcpRecommendedMode(serverName) {
+    const server = AGENT_STACK.mcp_servers[serverName];
+    if (!server)
+        throw new Error(`unknown MCP server: ${serverName}`);
+    return normalizeMcpMode(serverName, server.recommended_mode ?? server.default_mode);
+}
+export function mcpModeLabel(serverName, mode) {
+    const server = resolveMcpServer(serverName, mode);
+    if (server.selected_mode === "remote-custom")
+        return "custom remote";
+    if (server.connection_mode === "remote-curated")
+        return "remote";
+    if (server.connection_mode === "remote-custom")
+        return "custom remote";
+    if (server.connection_mode === "local-service")
+        return "requires local app";
+    if (server.connection_mode === "manual-local")
+        return "manual setup";
+    if (server.connection_mode === "manual")
+        return "manual setup";
+    return "local";
+}
+export function mcpModeKeyLabel(mode) {
+    if (mode === "remote-custom")
+        return "custom remote";
+    if (mode === "remote" || mode === "remote-curated" || mode === "http-remote")
+        return "remote";
+    if (mode === "local-service")
+        return "requires local app";
+    if (mode === "manual-local" || mode === "manual")
+        return "manual setup";
+    return "local";
+}
+export function mcpSupportedModeLabels(serverName) {
+    return mcpServerModeKeys(serverName).map((mode) => mcpModeLabel(serverName, mode));
+}
+export function modeAlias(mode) {
+    if (mode === "stdio-local" || mode === "manual-local" || mode === "local-service")
+        return "local";
+    if (mode === "http-remote" || mode === "remote-curated" || mode === "curated-remote")
+        return "remote";
+    if (mode === "custom-remote")
+        return "remote-custom";
+    return mode;
+}
+function defaultConnectionMode(executionMode) {
+    if (executionMode === "uvx-runtime" || executionMode === "npx-runtime")
+        return "stdio-local";
+    if (executionMode === "local-service")
+        return "local-service";
+    if (executionMode === "manual-local")
+        return "manual-local";
+    return "manual";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Scaffold agent-ready academic research repositories with SOTA, source ledgers, wiki memory, MCP setup, and project-local skills.",
   "type": "module",
   "license": "MIT",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
+    "build": "npm run clean && tsc && node scripts/chmod-bins.mjs",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test",
     "lint": "npm run typecheck && node scripts/validate.mjs",

package/template/README.md

@@ -31,6 +31,7 @@ source .venv/bin/activate
 python -m pip install --upgrade pip
 python -m pip install -e ".[dev]"
 npm run doctor
+npm run update
 ```
 
 ## Core Folders
@@ -60,11 +61,17 @@ npm run skills:install -- --preset enhanced
 npm run skills:install -- source-ingestion sota-literature-review
 npm run skills:list
 npm run skills:status
+npm run update
 npm run setup
 npm run mcp:dotenv
 npm run mcp:list
+npm run mcp:modes
+npm run mcp:status
 npm run mcp:env -- openalex semantic-scholar zotero
+npm run mcp:enable -- openalex --mode remote
 npm run mcp:enable -- arxiv dblp
+npm run mcp:setup -- overleaf --mode local --env-file .env.local
+npm run mcp:client:add -- overleaf --agent codex --dry-run
 npm run mcp:commands -- arxiv
 npm run mcp:install -- arxiv
 npm run mcp:smoke -- --env-file .env.local
@@ -73,13 +80,30 @@ npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
 `skills list` reports installed project-local skills. `skills presets` reports
-available install presets. `mcp enable` changes project records. `mcp commands`
+available install presets. `mcp enable` changes selected project records and
+can record explicit modes such as `--mode remote`. Use `mcp modes` to see
+which integrations support local, remote, custom remote, local-app, or manual
+setup paths. `mcp status` separates selected records from setup, snippet,
+client registration, and probe readiness; add `--verbose` for technical fields.
+`mcp commands`
 prints finite external install commands without running them. `mcp env` prints
 env vars, hosted endpoints, local prerequisites, and setup commands before you
 enable optional servers. `mcp install` runs only finite tool installation
 commands; runtime-only `uvx`/`npx` MCP servers may have no install step and are
 started later by the MCP client.
 
+`npm run update` always uses `create-academic-research@latest` so older
+projects can preview scaffold migrations with one command. It is a dry-run
+unless you pass `-- --apply`; safe managed files are tracked in
+`.academic-research/managed-files.json` and locally edited files are skipped
+instead of overwritten. If this project was created before the latest update
+script existed, run:
+
+```bash
+npm exec --yes --package=create-academic-research@latest -- academic-research update --root .
+npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply
+```
+
 `.env.example` is the committed MCP environment reference. Regenerate it with
 `npm run mcp:dotenv`. Copy it to `.env.local`, your shell profile, or your MCP
 client secret store when secrets are needed. Filled `.env` files are ignored by
@@ -87,11 +111,20 @@ git. `mcp doctor` checks the current process environment unless you explicitly
 pass `--env-file .env.local`.
 
 `setup` prints the current project capability state, installed skill counts,
-enabled MCP records, and the next onboarding commands without changing files.
+selected MCP records, and the next onboarding commands without changing files.
 `mcp smoke` performs a non-launching MCP readiness check: it reports required
 env vars, local/manual setup, and whether client runtime commands such as `uvx`
-or `npx` are available. `mcp probe` is opt-in and starts selected MCP servers
-for a real stdio JSON-RPC handshake.
+or `npx` are available. `mcp probe` is opt-in: local stdio servers get a real
+JSON-RPC handshake, while remote endpoints are reported as configured without a
+network probe.
+
+Overleaf setup creates a local wrapper under `.academic-research/mcp/` that
+parses `.env.local` safely at runtime. The wrapper path and client/probe
+observations are recorded in `docs/agent/capability-lock.json`; project-local
+skill install/update/remove observations are recorded there too.
+`configs/capabilities.yaml` is intended state, while the capability lock is
+observed setup state. Token values are not stored there or in generated
+snippets.
 
 `default` installs the companion academic research skill package and keeps the
 MCP records focused on low-friction arXiv discovery. `literature` and `full`

package/template/_gitignore

@@ -55,6 +55,7 @@ artifacts/cache/**
 !artifacts/cache/
 !artifacts/cache/.gitkeep
 docs/agent/generated/*.local.json
+.academic-research/mcp/
 .env
 .env.*
 !.env.example

package/template/docs/agent/mcp-client-setup.md

@@ -33,6 +33,7 @@ Do not commit filled `.env`, `.env.local`, tokens, cookies, or browser sessions.
 environment unless you explicitly pass `--env-file .env.local`.
 
 ```bash
+npm run mcp:status
 npm run mcp:doctor -- --env-file .env.local
 npm run mcp:smoke -- --env-file .env.local
 npm run mcp:probe -- arxiv --timeout-ms 5000
@@ -54,14 +55,53 @@ client has its own secret store, prefer that store for API keys and tokens. If
 the client inherits shell environment variables, start it from a shell where the
 required variables are already exported.
 
+Codex registration can be automated for servers with a generated command or
+hosted URL:
+
+```bash
+npm run mcp:client:add -- overleaf --agent codex
+npm run mcp:client:remove -- overleaf --agent codex
+```
+
+Use `--dry-run` to print the exact `codex mcp add` or `codex mcp remove`
+command without changing Codex config. Secrets are not written to Codex config;
+credentialed local integrations should use a wrapper that loads `.env.local` at
+runtime. Overleaf client registration is intentionally blocked until
+`npm run mcp:setup -- overleaf --mode local --env-file .env.local` has created
+the wrapper and recorded non-secret setup facts.
+
+Custom remote endpoints may use a stored URL or a URL env var name. Bearer token
+support stores only the token env var name. Codex automatic registration
+supports stored URL mode because Codex has `--url`:
+
+```bash
+npm run mcp:enable -- openalex --mode remote-custom --url https://example.com/mcp --bearer-token-env-var OPENALEX_MCP_TOKEN
+```
+
+If the endpoint URL is kept in an env var with `--url-env`, automatic Codex
+registration is not available because the Codex CLI currently has no
+`--url-env` option. Either re-enable the server with `--url <url>` if the
+endpoint URL may be stored in Codex config, or manually register it from a shell
+where the env var is set:
+
+```bash
+codex mcp add openalex --url "$OPENALEX_MCP_URL"
+```
+
+Claude Code, Cursor, and other clients may still require manual registration.
+Use `npm run mcp:status` to see whether the selected server has a generated
+snippet, a supported client registration path, and the next setup action.
+
 ## Workflow
 
 1. Enable only the MCP servers needed for the current research task.
 2. Inspect prerequisites with `npm run mcp:env -- <server>`.
 3. Put required secrets in the MCP client secret store, shell, or `.env.local`.
 4. Run `npm run mcp:smoke -- --env-file .env.local`.
-5. Run `npm run mcp:probe -- <server>` only when you want to start
+5. Run `npm run mcp:status`.
+6. Register the selected server with the active client, or load the generated
+   snippet manually.
+7. Run `npm run mcp:probe -- <server>` only when you want to start
    the server and verify a real stdio handshake.
-6. Load the generated snippet in the MCP client.
-7. Treat MCP output as retrieval metadata until it is ingested into repository
+8. Treat MCP output as retrieval metadata until it is ingested into repository
    source records.

package/template/docs/agent/mcp-setup.md

@@ -10,3 +10,63 @@ with `npm run mcp:dotenv`.
 Use `npm run mcp:doctor -- --env-file .env.local` when you want the CLI to read
 an explicit local env file. Use `npm run mcp:probe -- <server>` only when you
 want to start a selected MCP server and verify a real stdio handshake.
+
+Use `npm run mcp:modes` to see what each integration supports. Use
+`npm run mcp:status` to distinguish selected project records from operational
+readiness. Default status uses friendly labels such as ready, not selected,
+setup needed, missing env, probe needed, probe failed, local, remote, requires
+local app, and manual setup.
+Use `npm run mcp:status -- --verbose` when you need technical mode names,
+snippet state, client registration state, and probe details.
+
+`configs/capabilities.yaml` records intended project capability state.
+`docs/agent/capability-lock.json` records non-secret observed setup facts for
+MCP setup/client/probe actions and project-local skill operations. The scaffold
+manifest at `.academic-research/managed-files.json` records non-secret
+checksums used by `npm run update` to avoid overwriting local edits.
+
+Mode labels:
+
+- local: your machine runs the MCP server when the client needs it.
+- remote: your client connects to an existing hosted MCP endpoint.
+- custom remote: you provide the endpoint.
+- requires local app: another app must be running, such as Zotero Desktop.
+- manual setup: guided setup is required before client registration.
+
+OpenAlex and PubMed support explicit local and remote modes:
+
+```bash
+npm run mcp:enable -- openalex --mode remote
+npm run mcp:enable -- pubmed --mode local
+```
+
+Advanced custom remote endpoints are non-secret project facts. Store only the
+URL or the env var name that contains the URL. Store token env var names, never
+token values:
+
+```bash
+npm run mcp:enable -- openalex --mode remote-custom --url https://example.com/mcp
+npm run mcp:enable -- openalex --mode remote-custom --url-env OPENALEX_MCP_URL --bearer-token-env-var OPENALEX_MCP_TOKEN
+```
+
+Codex automatic registration supports stored URL mode with `--url`. If the URL
+is kept in an env var with `--url-env`, automatic Codex registration is not
+available because the Codex CLI currently has no `--url-env` option. Manually
+register from a shell where the env var is set, or re-enable with `--url <url>`
+if the endpoint URL may be stored in Codex config.
+
+`mcp smoke` checks custom remote URL env vars without launching a local server.
+`mcp probe` does not perform network probes for remote endpoints; it reports a
+remote configured status when the required endpoint configuration is present.
+If you use `--mode remote-custom` without `--url` or `--url-env`, smoke and
+probe report `missing-remote-url`.
+
+Overleaf is a manual-local integration. Keep secrets in `.env.local`, then run
+the setup command to create a local wrapper and non-secret capability lock:
+
+```bash
+npm run mcp:env -- overleaf --dotenv
+npm run mcp:setup -- overleaf --mode local --env-file .env.local
+npm run mcp:client:add -- overleaf --agent codex --dry-run
+npm run mcp:probe -- overleaf --env-file .env.local
+```