create-academic-research 0.1.16 → 0.1.18

package/README.md

@@ -41,7 +41,7 @@ npx --yes github:VincenzoImp/create-academic-research my-project
 | Sources | PDFs, derived Markdown, metadata, BibTeX, conversion ledger, source ledger. |
 | Literature Review | Search strategy, screening decisions, literature matrix, SOTA synthesis, gaps, PRISMA flow. |
 | Agent Memory | `AGENTS.md`, capability profile, MCP setup docs, generated MCP snippets, wiki index/log/templates. |
-| Reproducibility | Python package scaffold, tests, experiment registry, output folders, artifact checklist. |
+| Reproducibility | Python package scaffold, tests, experiment registry, autonomous campaign ledgers, output folders, artifact checklist. |
 | Skills | Project-local installation flow for `VincenzoImp/academic-research-skills`. |
 | MCP | Conservative default records for scholarly discovery plus documented optional integrations. |
 
@@ -115,7 +115,9 @@ 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 workflow:literature
 npm run rename -- --title "New Title" --slug new-title --package new_title
 npm run agents:list
 npm run skills:presets
@@ -173,13 +175,32 @@ Safe migrations are tracked in `.academic-research/managed-files.json`. The
 manifest stores non-secret checksums for generator-owned files. If a file was
 edited locally, update reports `skip` instead of overwriting it.
 
+### Migration 0.1.17 -> 0.1.18
+
+Projects created with `0.1.17` can migrate in place:
+
+```bash
+npm run update
+npm run update -- --apply
+npm run doctor
+```
+
+The migration adds the project-quality contract, badge evidence ledger, SOTA
+reading and citation-chasing ledgers, paper synthesis folders, linear reading
+copies, autonomous experiment campaign files, claim-audit and reproduction
+templates, and `workflow:literature`. Locally edited managed files are skipped;
+new research record templates are created as user-owned where the project is
+expected to fill them over time.
+
 `academic-research init` initializes an existing repository without overwriting
 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 +226,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. |
@@ -213,6 +234,11 @@ MCP commands are split by side-effect:
 | `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. Pass `--env-file .env.local` to read explicit local secrets. |
 | `mcp probe` | Opt-in runtime check. Local stdio servers get a JSON-RPC handshake; remote endpoints are reported as configured without a network probe. |
 
+Workflow commands are scenario-level shortcuts over skills and MCP records.
+Use `npm run workflow:literature` when starting a serious SOTA, survey, or
+related-work pass: it selects a practical literature stack with arXiv, DBLP,
+Semantic Scholar, and OpenAlex remote graph search, then prints the next checks.
+
 ## Companion Skills
 
 The generated project works best with:
@@ -266,6 +292,17 @@ a generated safe dotenv-loading wrapper after `mcp setup`.
 Crossref and broad paper-search aggregators are kept as fallback/manual entries
 until a project explicitly needs them.
 
+For SOTA work, the recommended low-friction path is:
+
+```bash
+npm run workflow:literature
+npm run skills:install -- --preset literature
+npm run mcp:status
+npm run mcp:smoke -- --env-file .env.local
+```
+
+Then use `$sota-literature-review` with a declared review scale and seed set.
+
 Codex automatic registration supports custom remote endpoints when the URL is
 stored in project config with `--url`. If the endpoint URL is kept private via
 `--url-env`, Codex automatic registration is not available because the Codex CLI

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

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { assertKnownMcpServers, clientAddMcpServer, clientRemoveMcpServer, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, getMcpLifecycleStatus, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, removeSkills, resolveMcpServerForState, setupMcpServer, uninstallMcpTools, updateSkills } from "./capabilities.js";
+import { assertKnownMcpServers, clientAddMcpServer, clientRemoveMcpServer, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, getMcpLifecycleStatus, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, removeSkills, resolveMcpServerForState, setupMcpServer, uninstallMcpTools, updateSkills, writeCapabilities } from "./capabilities.js";
 import { createProject, doctorProject, initProject, renameProject, updateProject } from "./project.js";
 import { askCreateOptions } from "./prompts.js";
 import { AGENT_STACK, mcpModeLabel, mcpRecommendedMode, mcpServerModeKeys, mcpSupportedModeLabels, presetMcpServers, resolveMcpServer } from "./stack.js";
@@ -19,6 +19,8 @@ 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 WORKFLOW_FLAGS = flagSchema(["help"], ["root", "agent", "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"]);
@@ -129,6 +131,8 @@ async function lifecycleMain(argv) {
         return skillsCommand(argv.slice(1));
     if (command === "mcp")
         return mcpCommand(argv.slice(1));
+    if (command === "workflow")
+        return workflowCommand(argv.slice(1));
     printLifecycleHelp();
     return command === "help" ? 0 : 1;
 }
@@ -173,6 +177,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 +208,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 +231,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}`);
@@ -598,6 +627,49 @@ async function mcpCommand(argv) {
     }
     throw new Error(`unknown mcp command: ${subcommand}`);
 }
+async function workflowCommand(argv) {
+    const subcommand = argv[0] ?? "help";
+    const parsed = parseFlags(argv.slice(1), WORKFLOW_FLAGS);
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || flagBool(parsed.flags, "help")) {
+        printWorkflowHelp();
+        return 0;
+    }
+    if (subcommand !== "literature")
+        throw new Error(`unknown workflow command: ${subcommand}`);
+    assertNoArguments(parsed.positionals, "workflow literature");
+    const root = resolve(flagString(parsed.flags, "root") ?? ".");
+    const state = await readCapabilities(root);
+    const agent = flagString(parsed.flags, "agent") ?? state.agent;
+    const literatureServers = ["arxiv", "dblp", "semantic-scholar", "openalex"];
+    await writeCapabilities(root, {
+        ...state,
+        agent,
+        preset: "literature",
+        mcp_servers: literatureServers,
+        mcp_server_modes: {
+            ...state.mcp_server_modes,
+            openalex: "remote"
+        },
+        mcp_server_remote: state.mcp_server_remote
+    });
+    const env = await mcpCommandEnvironment(root, parsed.flags);
+    const lifecycle = await getMcpLifecycleStatus(root, { env });
+    const selected = lifecycle.servers.filter((server) => server.selected);
+    console.log("Literature Workflow");
+    console.log(`root\t${root}`);
+    console.log("preset\tliterature");
+    console.log(`mcp_selected\t${literatureServers.join(",")}`);
+    for (const item of selected) {
+        console.log(`mcp\t${item.id}\t${item.mode}\t${item.state}\t${friendlyNext(item.next)}`);
+    }
+    console.log("");
+    console.log("Next Commands");
+    console.log("npm run skills:install -- --preset literature");
+    console.log("npm run mcp:status");
+    console.log("npm run mcp:smoke -- --env-file .env.local");
+    console.log("Use $sota-literature-review with a declared scale, seed set, and citation-chasing budget.");
+    return 0;
+}
 async function mcpClientCommand(parsed) {
     const action = parsed.positionals[0];
     const server = parsed.positionals[1];
@@ -649,6 +721,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))];
 }
@@ -899,7 +993,7 @@ function printMissingTargetHelp() {
 }
 function printLifecycleHelp() {
     console.log([
-        "Usage: academic-research <doctor|update|init|setup|rename|agents|skills|mcp>",
+        "Usage: academic-research <doctor|update|init|setup|rename|agents|skills|mcp|workflow>",
         "",
         "Manage a generated academic research repository after creation.",
         "",
@@ -908,6 +1002,22 @@ function printLifecycleHelp() {
         "  -v, --version            Show package version."
     ].join("\n"));
 }
+function printWorkflowHelp() {
+    console.log([
+        "Usage: academic-research workflow <literature> [options]",
+        "",
+        "Prepare scenario-level research workflows without manually stitching every skill and MCP command.",
+        "",
+        "Workflows:",
+        "  literature                Configure the practical SOTA stack for arXiv, DBLP, Semantic Scholar citation graph, and OpenAlex graph search.",
+        "",
+        "Options:",
+        "  --root <path>             Project root. Default: current directory.",
+        "  --agent <id>              Agent target for generated MCP snippets.",
+        "  --env-file <path>         Read local env values for readiness reporting.",
+        "  -h, --help                Show this help."
+    ].join("\n"));
+}
 function printUpdateHelp() {
     console.log([
         "Usage: academic-research update [options]",
@@ -943,10 +1053,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"));
 }