create-academic-research 0.1.15 → 0.1.17

package/README.md

@@ -115,7 +115,8 @@ Inside a generated project:
 ```bash
 npm run doctor
 npm run update
-npm run setup
+npm run update -- --apply
+npm run setup -- --env-file .env.local
 npm run rename -- --title "New Title" --slug new-title --package new_title
 npm run agents:list
 npm run skills:presets
@@ -177,9 +178,11 @@ edited locally, update reports `skip` instead of overwriting it.
 existing files. It adds the research contract, merges lifecycle package scripts,
 and preserves existing README, `.gitignore`, and custom package scripts.
 
-`academic-research setup` is a non-destructive onboarding status command. It
+`academic-research setup` is the friendly post-update recovery command. It
 prints the active preset, agent, skill counts, selected MCP records, and next
-commands without changing files.
+commands. When you pass `--env-file .env.local`, it may complete safe
+project-local setup such as the Overleaf wrapper and generated MCP snippet. It
+does not register global MCP clients.
 
 Skills are project-local by default.
 
@@ -205,7 +208,7 @@ MCP commands are split by side-effect:
 | `mcp env` | Print required/recommended env vars, hosted endpoints, local prerequisites, and setup commands for selected servers. Use `--dotenv --all` to print dotenv content or `--write .env.example --all` to regenerate `.env.example`. |
 | `mcp enable` | Select an MCP server in project records and generated snippets. Use `--mode local`, `--mode remote`, or `--mode remote-custom --url <url>` where supported. |
 | `mcp disable` | Remove an MCP server from project records and generated snippets. |
-| `mcp setup` | Run or dry-run finite setup for manual-local integrations such as Overleaf. |
+| `mcp setup` | Run or dry-run finite project-local setup for manual-local integrations such as Overleaf, including wrapper and generated snippet refresh. |
 | `mcp client add` / `mcp client remove` | Register or remove supported MCP client entries, currently Codex, without writing secrets into client config. |
 | `mcp install` | Run finite external tool install commands for selected MCP servers. It must not launch stdio MCP servers. |
 | `mcp uninstall` | Run the external uninstall command when one exists. |

package/dist/src/capabilities.d.ts

@@ -166,6 +166,7 @@ interface SkillInstallOptions {
 }
 export declare function readCapabilities(root: string): Promise<CapabilityState>;
 export declare function writeCapabilities(root: string, state: Partial<CapabilityState>): Promise<void>;
+export declare function writeCapabilityGeneratedFiles(root: string, state: CapabilityState): Promise<void>;
 export declare function writeMcpEnvironmentExample(root: string): Promise<void>;
 export declare function initializeCapabilities(root: string, options?: InitializeCapabilitiesOptions): Promise<void>;
 export declare function buildSkillInstallCommands(root: string, preset?: string, options?: SkillInstallOptions): Promise<string[][]>;
@@ -198,4 +199,6 @@ export declare function setupMcpServer(root: string, serverName: string, options
 export declare function clientAddMcpServer(root: string, serverName: string, options?: McpClientOptions, runner?: Runner): Promise<McpClientResult>;
 export declare function clientRemoveMcpServer(root: string, serverName: string, options?: McpClientOptions, runner?: Runner): Promise<McpClientResult>;
 export declare function resolveMcpServerForState(state: CapabilityState, serverName: string, mode?: string): ResolvedMcpServer;
+export declare function mcpMissingGeneratedSnippetMessage(serverName: string, server: ResolvedMcpServer, env?: NodeJS.ProcessEnv): string;
+export declare function mcpLocalSetupGitignoreWarning(root: string): Promise<string | undefined>;
 export declare function assertKnownMcpServers(servers: string[]): void;

package/dist/src/capabilities.js

@@ -24,21 +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: 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(serializeCapabilityState(next)), "utf8");
-    await writeCapabilityProfile(root, next);
-    await writeMcpSetup(root, next);
-    await writeMcpSnippet(root, next);
+    const next = normalizeCapabilityWriteState(state);
+    await writeCapabilityConfig(root, next);
+    await writeCapabilityGeneratedFiles(root, next);
     await appendCapabilityLog(root, next);
 }
+export async function writeCapabilityGeneratedFiles(root, state) {
+    await writeCapabilityProfile(root, state);
+    await writeMcpSetup(root, state);
+    await writeMcpSnippet(root, state);
+}
 export async function writeMcpEnvironmentExample(root) {
     await writeFile(join(root, ".env.example"), formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers)), "utf8");
 }
@@ -321,6 +316,18 @@ export async function doctorMcpServers(root, options = {}) {
             errors.push(`invalid generated MCP snippet: ${snippetPath}: ${message}`);
         }
     }
+    const lock = await readCapabilityLock(root);
+    const hasManualLocal = enabled.some((name) => {
+        if (!AGENT_STACK.mcp_servers[name])
+            return false;
+        const server = resolveMcpServerForState(state, name, modes[name]);
+        return server.connection_mode === "manual-local";
+    });
+    if (hasManualLocal) {
+        const gitignoreWarning = await mcpLocalSetupGitignoreWarning(root);
+        if (gitignoreWarning)
+            warnings.push(gitignoreWarning);
+    }
     for (const name of enabled) {
         const server = resolveMcpServerForState(state, name, modes[name]);
         if (!server)
@@ -339,7 +346,6 @@ export async function doctorMcpServers(root, options = {}) {
             warnings.push(`${name}: requires local service: ${server.local_service}`);
         }
         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`);
             }
@@ -349,7 +355,14 @@ export async function doctorMcpServers(root, options = {}) {
             continue;
         }
         if (!generatedServers.has(name)) {
-            errors.push(`${name}: enabled but missing from generated MCP snippet`);
+            errors.push(mcpMissingGeneratedSnippetMessage(name, server, env));
+            continue;
+        }
+        if (state.agent === "codex" &&
+            server.connection_mode === "manual-local" &&
+            lock.mcp[name]?.setup?.status === "ready" &&
+            lock.mcp[name]?.clients?.codex?.status !== "registered") {
+            warnings.push(`${name} is setup locally but not registered in Codex\nNEXT: npm run mcp:client:add -- ${name} --agent codex`);
         }
     }
     return { ok: errors.length === 0, errors, warnings, enabled };
@@ -662,8 +675,15 @@ export async function readCapabilityLock(root) {
 }
 export async function setupMcpServer(root, serverName, options = {}, runner = defaultRunner) {
     assertKnownMcpServers([serverName]);
-    const mode = normalizeMcpMode(serverName, options.mode);
-    const server = resolveMcpServer(serverName, mode);
+    const state = await readCapabilities(root);
+    const mode = normalizeMcpMode(serverName, options.mode ?? state.mcp_server_modes?.[serverName]);
+    const nextState = normalizeCapabilityWriteState({
+        ...state,
+        mcp_servers: dedupe([...(state.mcp_servers ?? []), serverName]),
+        mcp_server_modes: { ...(state.mcp_server_modes ?? {}), [serverName]: mode },
+        mcp_server_remote: state.mcp_server_remote ?? {}
+    });
+    const server = resolveMcpServerForState(nextState, serverName, mode);
     if (serverName !== "overleaf") {
         const commands = server.setup_commands.length > 0 ? server.setup_commands : [];
         return {
@@ -686,6 +706,7 @@ export async function setupMcpServer(root, serverName, options = {}, runner = de
         `cd ${paths.relativeServer} && uv sync`,
         `write wrapper ${paths.relativeWrapper}`
     ];
+    const gitignoreWarning = await mcpLocalSetupGitignoreWarning(root);
     if (missing.length > 0) {
         return {
             ok: false,
@@ -693,7 +714,7 @@ export async function setupMcpServer(root, serverName, options = {}, runner = de
             mode,
             commands,
             created: [],
-            warnings: [],
+            warnings: gitignoreWarning ? [gitignoreWarning] : [],
             errors: [`overleaf: missing required environment variable(s): ${missing.join(", ")}`],
             next: [`fill ${missing.join(", ")} in ${options.envFile ?? ".env.local"}`]
         };
@@ -705,7 +726,7 @@ export async function setupMcpServer(root, serverName, options = {}, runner = de
             mode,
             commands,
             created: [],
-            warnings: [],
+            warnings: gitignoreWarning ? [gitignoreWarning] : [],
             errors: [],
             next: [`run npm run mcp:setup -- overleaf --mode local --env-file ${options.envFile ?? ".env.local"}`]
         };
@@ -727,17 +748,19 @@ export async function setupMcpServer(root, serverName, options = {}, runner = de
             status: "ready",
             server_path: paths.relativeServer,
             wrapper_path: paths.relativeWrapper,
-            env_file: options.envFile ? toPosix(relative(root, resolve(root, options.envFile))) : ".env.local",
+            env_file: mcpEnvFileRecord(root, options.envFile),
             updated_at: nowIso()
         };
     });
+    await writeCapabilityConfig(root, nextState);
+    await writeCapabilityGeneratedFiles(root, nextState);
     return {
         ok: true,
         server: serverName,
         mode,
         commands,
         created: [paths.relativeWrapper, paths.relativeLauncher],
-        warnings: [],
+        warnings: gitignoreWarning ? [gitignoreWarning] : [],
         errors: [],
         next: [
             "npm run mcp:client:add -- overleaf --agent codex",
@@ -824,6 +847,20 @@ function serializeCapabilityState(state) {
         serialized.mcp_server_remote = state.mcp_server_remote;
     return serialized;
 }
+function normalizeCapabilityWriteState(state) {
+    const mcpServers = [...(state.mcp_servers ?? [])];
+    return {
+        agent: assertKnownAgentTarget(state.agent),
+        preset: state.preset ?? "default",
+        scope: "project-local",
+        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 ?? {})
+    };
+}
+async function writeCapabilityConfig(root, state) {
+    await writeFile(join(root, "configs/capabilities.yaml"), YAML.stringify(serializeCapabilityState(state)), "utf8");
+}
 function normalizeMcpServerModeMap(modes, servers) {
     const selected = new Set(servers);
     const result = {};
@@ -986,6 +1023,19 @@ function mcpModeKeyLabelForAction(mode) {
         return "manual setup";
     return "local";
 }
+export function mcpMissingGeneratedSnippetMessage(serverName, server, env = process.env) {
+    const lines = [`${serverName}: enabled but missing from generated MCP snippet`];
+    if (server.connection_mode === "manual-local") {
+        lines.push(`NEXT: npm run mcp:setup -- ${serverName} --mode local --env-file .env.local`);
+        const missing = server.required_env.filter((name) => !envHasValue(env, name));
+        if (missing.length > 0)
+            lines.push(`Missing env vars: ${missing.join(", ")}`);
+    }
+    else {
+        lines.push("NEXT: npm run update -- --apply");
+    }
+    return lines.join("\n");
+}
 function mcpInstallSkip(serverName, server) {
     if (server.connection_mode === "manual-local") {
         return {
@@ -1098,6 +1148,41 @@ function ensureLockMcpEntry(lock, serverName, server) {
     lock.mcp[serverName] = entry;
     return entry;
 }
+export async function mcpLocalSetupGitignoreWarning(root) {
+    if (await mcpLocalSetupPathIsIgnored(root))
+        return undefined;
+    return [
+        ".academic-research/mcp/ is not ignored",
+        "NEXT: add .academic-research/mcp/ to .gitignore before committing local MCP server files"
+    ].join("\n");
+}
+async function mcpLocalSetupPathIsIgnored(root) {
+    try {
+        const gitignore = await readFile(join(root, ".gitignore"), "utf8");
+        return gitignore
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("#"))
+            .some((line) => {
+            const normalized = line.replaceAll("\\", "/").replace(/^\/+/, "");
+            return normalized === ".academic-research/mcp/" || normalized === ".academic-research/mcp";
+        });
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return false;
+        throw error;
+    }
+}
+function mcpEnvFileRecord(root, envFile) {
+    if (!envFile)
+        return ".env.local";
+    const resolved = resolve(root, envFile);
+    const relativePath = relative(root, resolved);
+    if (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+        return toPosix(relativePath);
+    return ".env.local";
+}
 function overleafPaths(root) {
     const relativeBase = ".academic-research/mcp/overleaf";
     const wrapperDir = join(root, relativeBase);

package/dist/src/cli.js

@@ -19,6 +19,7 @@ const CREATE_FLAGS = flagSchema([
     "no-install-mcp-tools"
 ], ["title", "slug", "package", "preset", "profile", "agent"]);
 const ROOT_FLAGS = flagSchema(["help"], ["root"]);
+const SETUP_FLAGS = flagSchema(["help"], ["root", "env-file"]);
 const UPDATE_FLAGS = flagSchema(["help", "dry-run", "apply"], ["root"]);
 const INIT_FLAGS = flagSchema(["help", "install-skills"], ["root", "title", "slug", "package", "preset", "profile", "agent"]);
 const RENAME_FLAGS = flagSchema(["help"], ["root", "title", "slug", "package"]);
@@ -173,6 +174,12 @@ async function updateCommand(argv) {
     if (!apply && result.changes.length > 0) {
         console.log("Run `npm run update -- --apply` from a generated project to write these managed changes.");
     }
+    if (apply && await projectLocalMcpSetupNeeded(root)) {
+        console.log("");
+        console.log("Next:");
+        console.log("1. Run npm run setup -- --env-file .env.local to complete project-local tool setup.");
+        console.log("2. Run npm run doctor to verify the project.");
+    }
     return 0;
 }
 async function initCommand(argv) {
@@ -198,13 +205,15 @@ async function initCommand(argv) {
     return 0;
 }
 async function setupCommand(argv) {
-    const parsed = parseFlags(argv, ROOT_FLAGS);
+    const parsed = parseFlags(argv, SETUP_FLAGS);
     if (flagBool(parsed.flags, "help")) {
         printSetupHelp();
         return 0;
     }
     assertNoArguments(parsed.positionals, "setup");
     const root = resolve(flagString(parsed.flags, "root") ?? ".");
+    const env = await mcpCommandEnvironment(root, parsed.flags);
+    const setupResults = await runProjectLocalMcpSetup(root, env, flagString(parsed.flags, "env-file"));
     const project = await doctorProject(root);
     const state = await readCapabilities(root);
     const skills = await listInstalledSkills(root);
@@ -219,13 +228,30 @@ async function setupCommand(argv) {
     console.log(`installed_skill_copies\t${skills.length}`);
     console.log(`mcp_enabled\t${state.mcp_servers.length > 0 ? state.mcp_servers.join(",") : "none"}`);
     console.log(`mcp_selected\t${state.mcp_servers.length > 0 ? state.mcp_servers.join(",") : "none"}`);
+    for (const result of setupResults) {
+        if (result.ok) {
+            console.log(`Completed project-local MCP setup: ${result.server}`);
+        }
+    }
     if (!project.ok) {
         for (const error of project.errors)
             console.error(`ERROR: ${error}`);
     }
-    for (const warning of project.warnings)
+    const setupWarnings = [];
+    for (const result of setupResults) {
+        for (const error of result.errors)
+            console.error(`ERROR: ${error}`);
+        setupWarnings.push(...result.warnings);
+        if (!result.ok && result.next.length > 0) {
+            console.log("");
+            console.log(`Next for ${result.server}`);
+            for (const command of result.next)
+                console.log(command);
+        }
+    }
+    for (const warning of dedupeStrings([...setupWarnings, ...project.warnings]))
         console.warn(`WARN: ${warning}`);
-    const lifecycle = await getMcpLifecycleStatus(root);
+    const lifecycle = await getMcpLifecycleStatus(root, { env });
     console.log("");
     console.log("Next Commands");
     console.log(`npm run skills:install -- --preset ${state.preset}`);
@@ -649,6 +675,28 @@ function setupNextCommands(item) {
     commands.push(item.next.replace(/^run /, ""));
     return dedupeStrings(commands);
 }
+async function runProjectLocalMcpSetup(root, env, envFile) {
+    const lifecycle = await getMcpLifecycleStatus(root, { env });
+    const results = [];
+    for (const item of lifecycle.servers) {
+        if (!item.selected || item.connection_mode !== "manual-local")
+            continue;
+        if (item.install === "ready" && item.snippet !== "missing")
+            continue;
+        results.push(await setupMcpServer(root, item.id, {
+            mode: item.mode_key,
+            envFile: envFile ?? ".env.local",
+            env
+        }));
+    }
+    return results;
+}
+async function projectLocalMcpSetupNeeded(root) {
+    const lifecycle = await getMcpLifecycleStatus(root);
+    return lifecycle.servers.some((item) => item.selected &&
+        item.connection_mode === "manual-local" &&
+        (item.install !== "ready" || item.snippet === "missing"));
+}
 function dedupeStrings(values) {
     return [...new Set(values.filter(Boolean))];
 }
@@ -943,10 +991,11 @@ function printSetupHelp() {
     console.log([
         "Usage: academic-research setup [options]",
         "",
-        "Print project onboarding status and next commands without changing files.",
+        "Print project onboarding status and complete safe project-local setup when possible.",
         "",
         "Options:",
         "  --root <path>            Project root. Default: current directory.",
+        "  --env-file <path>        Read local env values for guided project-local MCP setup.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }

package/dist/src/project.js

@@ -3,7 +3,7 @@ import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promi
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
-import { DEFAULT_AGENT, formatMcpDotenv, initializeCapabilities, installSkills, readCapabilities, renderCapabilityProfile, renderMcpSetup, renderMcpSnippet, resolveMcpServerForState, writeMcpEnvironmentExample } from "./capabilities.js";
+import { DEFAULT_AGENT, formatMcpDotenv, initializeCapabilities, installSkills, mcpLocalSetupGitignoreWarning, mcpMissingGeneratedSnippetMessage, readCapabilities, readCapabilityLock, renderCapabilityProfile, renderMcpSetup, renderMcpSnippet, resolveMcpServerForState, writeMcpEnvironmentExample } from "./capabilities.js";
 import { assertKnownAgentTarget } from "./agents.js";
 import { copyDirectory, exists, isNonEmptyDirectory, movePath, readJson, writeJson } from "./files.js";
 import { packageify, slugify, titleFromSlug } from "./names.js";
@@ -239,6 +239,18 @@ export async function doctorProject(root) {
             if (needsMcpEnvDoctor) {
                 warnings.push("MCP readiness may require local secrets; run npm run mcp:doctor -- --env-file .env.local");
             }
+            const lock = await readCapabilityLock(target);
+            const hasManualLocalMcp = state.mcp_servers.some((serverName) => {
+                if (!AGENT_STACK.mcp_servers[serverName])
+                    return false;
+                const server = resolveMcpServerForState(state, serverName, state.mcp_server_modes[serverName]);
+                return server.connection_mode === "manual-local";
+            });
+            if (hasManualLocalMcp) {
+                const gitignoreWarning = await mcpLocalSetupGitignoreWarning(target);
+                if (gitignoreWarning)
+                    warnings.push(gitignoreWarning);
+            }
             for (const serverName of state.mcp_servers) {
                 if (!AGENT_STACK.mcp_servers[serverName])
                     continue;
@@ -264,7 +276,16 @@ export async function doctorProject(root) {
                     const generated = JSON.parse(raw);
                     for (const server of snippetServers) {
                         if (!Object.hasOwn(generated.mcpServers ?? {}, server)) {
-                            errors.push(`${server}: enabled but missing from generated MCP snippet`);
+                            const resolved = resolveMcpServerForState(state, server, state.mcp_server_modes[server]);
+                            errors.push(mcpMissingGeneratedSnippetMessage(server, resolved, process.env));
+                            continue;
+                        }
+                        const resolved = resolveMcpServerForState(state, server, state.mcp_server_modes[server]);
+                        if (state.agent === "codex" &&
+                            resolved.connection_mode === "manual-local" &&
+                            lock.mcp[server]?.setup?.status === "ready" &&
+                            lock.mcp[server]?.clients?.codex?.status !== "registered") {
+                            warnings.push(`${server} is setup locally but not registered in Codex\nNEXT: npm run mcp:client:add -- ${server} --agent codex`);
                         }
                     }
                 }
@@ -606,17 +627,18 @@ async function stageManagedFiles(root, specs, manifest, options) {
             nextManifest.files[relativePath] = stableManagedRecord(existing, managedRecordCandidateForWrittenFile(spec));
             continue;
         }
-        options.changes.push({
-            path: relativePath,
-            action: "skip",
-            reason: manifest ? "local edits detected" : "unknown legacy content"
-        });
+        if (isUnchangedSkippedManagedRecord(existing, currentChecksum, generatedChecksum)) {
+            nextManifest.files[relativePath] = existing;
+            continue;
+        }
+        const reason = skippedManagedRecordReason(existing, manifest !== undefined, currentChecksum);
+        options.changes.push({ path: relativePath, action: "skip", reason });
         nextManifest.files[relativePath] = stableManagedRecord(existing, {
             path: relativePath,
             policy: spec.policy,
             generated_checksum: generatedChecksum,
             current_checksum: currentChecksum,
-            reason: manifest ? "local edits detected" : "unknown legacy content"
+            reason
         });
     }
     return nextManifest;
@@ -696,6 +718,16 @@ function stableManagedRecord(existing, candidate) {
         return existing;
     return { ...candidate, updated_at: nowIso() };
 }
+function isUnchangedSkippedManagedRecord(record, currentChecksum, generatedChecksum) {
+    return Boolean(record?.reason &&
+        record.current_checksum === currentChecksum &&
+        record.generated_checksum === generatedChecksum);
+}
+function skippedManagedRecordReason(existing, hasManifest, currentChecksum) {
+    if (existing?.reason && existing.current_checksum === currentChecksum)
+        return existing.reason;
+    return hasManifest ? "local edits detected" : "unknown legacy content";
+}
 function managedManifestSemanticallyEqual(left, right) {
     if (left.version !== right.version)
         return false;
@@ -835,6 +867,8 @@ async function validateManagedManifestDrift(root, warnings) {
             continue;
         const checksum = checksumText(current);
         const record = manifest?.files[relativePath];
+        if (isUnchangedSkippedManagedRecord(record, checksum, checksumText(spec.content)))
+            continue;
         if (canSafelyUpdateManagedFile(record, checksum)) {
             warnings.push(`${relativePath} is not current; run npm run update -- --apply`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Scaffold agent-ready academic research repositories with SOTA, source ledgers, wiki memory, MCP setup, and project-local skills.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -111,7 +111,10 @@ 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,
-selected MCP records, and the next onboarding commands without changing files.
+selected MCP records, and the next onboarding commands. With
+`-- --env-file .env.local`, it can complete safe project-local setup such as the
+Overleaf wrapper and generated MCP snippet. It does not register global MCP
+clients.
 `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: local stdio servers get a real

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

@@ -69,6 +69,9 @@ 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.
+After a legacy scaffold update, `npm run setup -- --env-file .env.local` can
+perform that project-local setup and refresh the generated snippet; global
+client registration remains explicit.
 
 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

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

@@ -70,3 +70,14 @@ 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
 ```
+
+After a scaffold update, the friendlier project setup command can run the same
+project-local Overleaf setup when the env file is present:
+
+```bash
+npm run setup -- --env-file .env.local
+```
+
+This may create ignored files under `.academic-research/mcp/` and refresh the
+generated MCP snippet. It does not run `codex mcp add`; client registration
+stays explicit.

package/template/docs/getting-started.md

@@ -8,7 +8,9 @@ Use this path for the first working session in a new research repository.
 npm install
 npm run doctor
 npm run update
-npm run setup
+npm run update -- --apply
+npm run setup -- --env-file .env.local
+npm run doctor
 ```
 
 `doctor` checks required files and structural contracts. `update` uses
@@ -16,7 +18,9 @@ npm run setup
 `-- --apply`. Safe scaffold files are tracked in
 `.academic-research/managed-files.json`; locally edited files are skipped
 instead of overwritten. `setup` prints the active skill preset, installed skill
-count, enabled MCP records, and next commands without changing files.
+count, enabled MCP records, and next commands. With `-- --env-file .env.local`,
+it can complete safe project-local MCP setup such as the Overleaf wrapper and
+generated snippet. It does not register global MCP clients.
 
 If an older project still has a pinned `update` script, run: