create-academic-research 0.1.4 → 0.1.6

package/README.md

@@ -35,9 +35,10 @@ adjacent interdisciplinary CS.
 
 The generated repository is agent-neutral. By default the wizard records
 `agent: universal`, installs one shared project-local `.agents/skills` copy,
-and writes generic MCP snippets. Use `--agent <name>` only when you want to
-force a specific target recognized by the `skills` CLI, such as `claude-code`,
-`codex`, `cursor`, `windsurf`, or another supported local loader.
+and writes generic MCP snippets. Use `--agent <id>` only when you want to force
+a specific target recognized by the `skills` CLI. Run
+`npx academic-research agents list` inside a generated project to see every
+supported target and alias.
 
 ## Default Experience
 
@@ -45,10 +46,12 @@ By default, the wizard:
 
 - creates the repository structure;
 - installs the project-local `VincenzoImp/academic-research-skills` package;
-- enables the scholarly MCP records for `arxiv`, `semantic-scholar`, and
-  `openalex`;
+- enables only the low-friction `arxiv` MCP record;
+- documents the wider MCP catalog, including Semantic Scholar, OpenAlex, DBLP,
+  PubMed, Zotero, Crossref, Overleaf, and fallback aggregators;
 - writes `configs/capabilities.yaml`;
 - writes `docs/agent/capability-profile.md`;
+- writes `docs/agent/mcp-setup.md`;
 - writes `docs/agent/generated/mcp.json` unless an explicit agent target is set;
 - appends the onboarding event to `wiki/log.md`;
 - does not install external MCP tools unless explicitly requested.
@@ -57,6 +60,12 @@ Use `--preset enhanced` when you also want the curated complementary external
 skill bundles for agent engineering, frontend work, testing, document formats,
 and PDF conversion.
 
+Research-specific skills are intentionally not pulled from external packages by
+default. The academic research workflow, literature review, citation audit,
+paper writing, peer review, rebuttal, and reproduction policies come from
+`VincenzoImp/academic-research-skills`. External skills installed by the wizard
+are complementary tooling only.
+
 ## Non-Interactive Create
 
 ```bash
@@ -76,6 +85,7 @@ Inside a generated project:
 ```bash
 npx academic-research doctor
 npx academic-research rename --title "New Title" --slug new-title --package new_title
+npx academic-research agents list
 npx academic-research skills presets
 npx academic-research skills install --preset default
 npx academic-research skills install --preset enhanced
@@ -88,6 +98,7 @@ npx academic-research mcp list
 npx academic-research mcp enabled
 npx academic-research mcp available
 npx academic-research mcp commands arxiv
+npx academic-research mcp env openalex semantic-scholar zotero
 npx academic-research mcp enable arxiv openalex
 npx academic-research mcp disable arxiv
 npx academic-research mcp install arxiv
@@ -116,11 +127,12 @@ MCP commands are split by side-effect:
 | `mcp enabled` | List only enabled MCP server ids. |
 | `mcp available` | List the local MCP catalog. |
 | `mcp commands` | Print finite external install commands without running them. Runtime-only `uvx`/`npx` servers may have no install command. |
+| `mcp env` | Print required/recommended env vars, hosted endpoints, local prerequisites, and setup commands for selected servers. |
 | `mcp enable` | Enable an MCP server in project records and generated snippets. |
 | `mcp disable` | Remove an MCP server from project records and generated snippets. |
 | `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. |
-| `mcp doctor` | Validate enabled MCP records and generated snippets. |
+| `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. |
 
 ## Companion Skills
 
@@ -134,8 +146,9 @@ The create wizard can install that project-local package automatically.
 Those skills are portable `SKILL.md` instructions, but they require an
 agent/runtime that can load skills or include the relevant instructions in
 context. They are not automatic capabilities of every raw model API.
-Use `--agent <agent>` for explicit setup, for example `--agent codex` or
-`--agent claude-code`.
+Use `--agent <id>` for explicit setup with any id from
+`academic-research agents list`. The shorthand `--agent claude` is normalized
+to the supported `claude-code` target.
 Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
 it to every agent it detects on the machine.
 
@@ -144,11 +157,34 @@ Preset intent:
 | Preset | Intent |
 |---|---|
 | `minimal` | Academic research skills only, no MCP records. |
-| `default` | Academic research skills plus core scholarly MCP records. |
+| `default` | Academic research skills plus the low-friction arXiv MCP record. |
 | `enhanced` | `default` plus curated external complementary skill bundles. |
-| `literature` | SOTA and systematic-review work with citation-library MCP records. |
-| `writing` | Paper-writing and Overleaf-oriented work. |
-| `full` | Broad optional connector and specialist setup. |
+| `literature` | SOTA and systematic-review work with arXiv plus DBLP for computer science bibliography. |
+| `writing` | Paper-writing work; Overleaf is documented as an opt-in credentialed integration. |
+| `full` | Broad setup with low-friction arXiv and DBLP records plus the full optional MCP catalog documented. |
+
+MCP defaults are intentionally conservative. Semantic Scholar, OpenAlex,
+Zotero, Overleaf, Crossref, and fallback aggregators are useful, but they need
+API keys, local apps, manual setup, or source-policy review. Enable them with
+`npx academic-research mcp enable <server>` after reading
+`docs/agent/mcp-setup.md`, use `npx academic-research mcp env <server>` to see
+runtime prerequisites, then run `npx academic-research mcp doctor`.
+
+The MCP catalog distinguishes local runtime adapters from hosted endpoints and
+manual integrations. arXiv and DBLP are low-friction local `uvx` runtimes.
+Semantic Scholar is useful for citation graphs but works best with
+`SEMANTIC_SCHOLAR_API_KEY`. OpenAlex requires `OPENALEX_API_KEY` for the
+selected local adapter; OpenAlex keys are free for normal academic use with
+daily free usage. PubMed is a biomedical-specific `npx` runtime and remains
+opt-in. Zotero needs the local Zotero desktop app and Zoty setup. Overleaf is
+manual and credentialed. Crossref and broad paper-search aggregators are kept
+as fallback/manual entries until a project explicitly needs them.
+
+Generated MCP snippets are project documentation and client-ready config, not
+live tools by themselves. Your MCP client must load the generated snippet, and
+the referenced commands must be available on your machine or runnable through
+`uvx`/`npx`. `mcp install` only runs finite setup commands such as the arXiv
+tool install; it deliberately does not launch stdio MCP servers.
 
 ## Validate This Package
 
@@ -166,8 +202,8 @@ Releases are tag-driven. Update `package.json` and `package-lock.json`, commit
 the change, create `vX.Y.Z`, and push the tag:
 
 ```bash
-git tag -a v0.1.4 -m "v0.1.4"
-git push origin main v0.1.4
+git tag -a v0.1.6 -m "v0.1.6"
+git push origin main v0.1.6
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/agents.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_AGENT = "universal";
+export declare const AUTO_AGENT = "auto";
+export declare const SUPPORTED_SKILL_AGENT_TARGETS: readonly ["adal", "aider-desk", "amp", "antigravity", "augment", "bob", "claude-code", "cline", "codearts-agent", "codebuddy", "codemaker", "codestudio", "codex", "command-code", "continue", "cortex", "crush", "cursor", "deepagents", "devin", "dexto", "droid", "firebender", "forgecode", "gemini-cli", "github-copilot", "goose", "hermes-agent", "iflow-cli", "junie", "kilo", "kimi-cli", "kiro-cli", "kode", "mcpjam", "mistral-vibe", "mux", "neovate", "openclaw", "opencode", "openhands", "pi", "pochi", "qoder", "qwen-code", "replit", "roo", "rovodev", "tabnine-cli", "trae", "trae-cn", "universal", "warp", "windsurf", "zencoder"];
+export declare const AGENT_TARGET_ALIASES: Record<string, string>;
+export declare function normalizeAgentTarget(agent: string | undefined): string;
+export declare function assertKnownAgentTarget(agent: string | undefined): string;
+export declare function formatAgentTargetList(): string;
+export declare function formatSupportedAgentTargetLines(indent?: string, width?: number): string[];
+export declare function formatAgentAliasLines(indent?: string): string[];

package/dist/src/agents.js

@@ -0,0 +1,126 @@
+export const DEFAULT_AGENT = "universal";
+export const AUTO_AGENT = "auto";
+export const SUPPORTED_SKILL_AGENT_TARGETS = [
+    "adal",
+    "aider-desk",
+    "amp",
+    "antigravity",
+    "augment",
+    "bob",
+    "claude-code",
+    "cline",
+    "codearts-agent",
+    "codebuddy",
+    "codemaker",
+    "codestudio",
+    "codex",
+    "command-code",
+    "continue",
+    "cortex",
+    "crush",
+    "cursor",
+    "deepagents",
+    "devin",
+    "dexto",
+    "droid",
+    "firebender",
+    "forgecode",
+    "gemini-cli",
+    "github-copilot",
+    "goose",
+    "hermes-agent",
+    "iflow-cli",
+    "junie",
+    "kilo",
+    "kimi-cli",
+    "kiro-cli",
+    "kode",
+    "mcpjam",
+    "mistral-vibe",
+    "mux",
+    "neovate",
+    "openclaw",
+    "opencode",
+    "openhands",
+    "pi",
+    "pochi",
+    "qoder",
+    "qwen-code",
+    "replit",
+    "roo",
+    "rovodev",
+    "tabnine-cli",
+    "trae",
+    "trae-cn",
+    "universal",
+    "warp",
+    "windsurf",
+    "zencoder"
+];
+export const AGENT_TARGET_ALIASES = {
+    claude: "claude-code",
+    claude_code: "claude-code"
+};
+const SUPPORTED_AGENT_TARGETS = new Set([
+    AUTO_AGENT,
+    ...SUPPORTED_SKILL_AGENT_TARGETS
+]);
+export function normalizeAgentTarget(agent) {
+    const value = agent?.trim();
+    if (!value)
+        return DEFAULT_AGENT;
+    const normalized = value.toLowerCase();
+    return AGENT_TARGET_ALIASES[normalized] ?? normalized;
+}
+export function assertKnownAgentTarget(agent) {
+    const normalized = normalizeAgentTarget(agent);
+    if (!SUPPORTED_AGENT_TARGETS.has(normalized)) {
+        const value = agent?.trim() || DEFAULT_AGENT;
+        throw new Error([
+            `unknown agent target: ${value}`,
+            `Use ${DEFAULT_AGENT}, ${AUTO_AGENT}, or one supported skills.sh agent id.`,
+            "List targets with: npx -p create-academic-research academic-research agents list",
+            `Supported ids: ${specificAgentTargets().join(", ")}`,
+            `Aliases: ${formatAgentAliasesInline()}`
+        ].join("\n"));
+    }
+    return normalized;
+}
+export function formatAgentTargetList() {
+    const lines = [
+        `${DEFAULT_AGENT}\tRecommended shared project-local .agents/skills copy`,
+        `${AUTO_AGENT}\tLet the skills CLI detect installed agents; may create multiple agent-specific copies`,
+        ...specificAgentTargets().map((agent) => `${agent}\tskills.sh agent id`),
+        ...Object.entries(AGENT_TARGET_ALIASES).map(([alias, target]) => `alias\t${alias}\t${target}`)
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function formatSupportedAgentTargetLines(indent = "  ", width = 100) {
+    const labels = specificAgentTargets();
+    const lines = [];
+    let current = indent;
+    for (const label of labels) {
+        const next = current === indent ? label : `, ${label}`;
+        if (current.length + next.length > width) {
+            lines.push(current);
+            current = `${indent}${label}`;
+        }
+        else {
+            current += next;
+        }
+    }
+    if (current.trim())
+        lines.push(current);
+    return lines;
+}
+export function formatAgentAliasLines(indent = "  ") {
+    return Object.entries(AGENT_TARGET_ALIASES).map(([alias, target]) => `${indent}${alias} -> ${target}`);
+}
+function formatAgentAliasesInline() {
+    return Object.entries(AGENT_TARGET_ALIASES)
+        .map(([alias, target]) => `${alias} -> ${target}`)
+        .join(", ");
+}
+function specificAgentTargets() {
+    return SUPPORTED_SKILL_AGENT_TARGETS.filter((agent) => agent !== DEFAULT_AGENT);
+}

package/dist/src/capabilities.d.ts

@@ -1,6 +1,7 @@
+import { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { type Runner } from "./runner.js";
 import { type McpToolCommandKey } from "./stack.js";
-export declare const DEFAULT_AGENT = "universal";
+export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export interface CapabilityState {
     agent: string;
     preset: string;
@@ -51,4 +52,3 @@ export declare function installMcpTools(root: string, servers: string[], runner?
 export declare function uninstallMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function doctorMcpServers(root: string): Promise<McpDoctorResult>;
 export declare function assertKnownMcpServers(servers: string[]): void;
-export {};

package/dist/src/capabilities.js

@@ -1,10 +1,10 @@
 import { appendFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 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";
-export const DEFAULT_AGENT = "universal";
-const AUTO_AGENT = "auto";
+export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export async function readCapabilities(root) {
     try {
         return readCapabilitiesFile(root);
@@ -18,13 +18,14 @@ export async function readCapabilities(root) {
 }
 export async function writeCapabilities(root, state) {
     const next = {
-        agent: normalizeAgent(state.agent),
+        agent: assertKnownAgentTarget(state.agent),
         preset: state.preset ?? "default",
         scope: "project-local",
         mcp_servers: [...(state.mcp_servers ?? [])]
     };
     await writeFile(join(root, "configs/capabilities.yaml"), YAML.stringify(next), "utf8");
     await writeCapabilityProfile(root, next);
+    await writeMcpSetup(root, next);
     await writeMcpSnippet(root, next);
     await appendCapabilityLog(root, next);
 }
@@ -42,7 +43,7 @@ export async function buildSkillInstallCommands(root, preset = "default", option
     if (!selected)
         throw new Error(`unknown skill preset: ${preset}`);
     const state = await readCapabilities(root);
-    const agent = normalizeAgent(options.agent ?? state.agent);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
     const commands = [];
     for (const bundleName of selected.skill_bundles) {
         const bundle = AGENT_STACK.skill_bundles[bundleName];
@@ -61,7 +62,7 @@ export async function buildSkillInstallCommands(root, preset = "default", option
 }
 export async function installSkills(root, preset = "default", options = {}, runner = defaultRunner) {
     const state = await readCapabilities(root);
-    const agent = normalizeAgent(options.agent ?? state.agent);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
     const commands = await buildSkillInstallCommands(root, preset, options);
     for (const command of commands) {
         await runner.run(command, { cwd: root });
@@ -135,7 +136,7 @@ export async function enableMcpServers(root, servers, options = {}) {
     const selected = dedupe([...(state.mcp_servers ?? []), ...servers]);
     await writeCapabilities(root, {
         ...state,
-        agent: options.agent ?? state.agent,
+        agent: assertKnownAgentTarget(options.agent ?? state.agent),
         mcp_servers: selected
     });
     return { ok: true, servers: selected };
@@ -147,7 +148,7 @@ export async function disableMcpServers(root, servers, options = {}) {
     const selected = (state.mcp_servers ?? []).filter((server) => !blocked.has(server));
     await writeCapabilities(root, {
         ...state,
-        agent: options.agent ?? state.agent,
+        agent: assertKnownAgentTarget(options.agent ?? state.agent),
         mcp_servers: selected
     });
     return { ok: true, servers: selected };
@@ -233,6 +234,19 @@ export async function doctorMcpServers(root) {
         const server = AGENT_STACK.mcp_servers[name];
         if (!server)
             continue;
+        for (const envName of server.required_env) {
+            if (!process.env[envName]) {
+                errors.push(`${name}: missing required environment variable: ${envName}`);
+            }
+        }
+        for (const envName of server.recommended_env) {
+            if (!process.env[envName]) {
+                warnings.push(`${name}: recommended environment variable not set: ${envName}`);
+            }
+        }
+        if (server.local_service) {
+            warnings.push(`${name}: requires local service: ${server.local_service}`);
+        }
         if (!server.command) {
             warnings.push(`${name}: manual setup only; no generated client command`);
             continue;
@@ -240,9 +254,6 @@ export async function doctorMcpServers(root) {
         if (!generatedServers.has(name)) {
             errors.push(`${name}: enabled but missing from generated MCP snippet`);
         }
-        if (!server.install_command) {
-            warnings.push(`${name}: no automated install command is defined`);
-        }
     }
     return { ok: errors.length === 0, errors, warnings, enabled };
 }
@@ -269,7 +280,7 @@ async function writeCapabilityProfile(root, state) {
     const lines = [
         "# Agent Capability Profile",
         "",
-        `- Agent target: \`${normalizeAgent(state.agent)}\``,
+        `- Agent target: \`${assertKnownAgentTarget(state.agent)}\``,
         `- Preset: \`${state.preset ?? "default"}\``,
         "- Scope: `project-local`",
         "",
@@ -290,13 +301,46 @@ async function writeCapabilityProfile(root, state) {
     else {
         for (const name of state.mcp_servers) {
             const server = AGENT_STACK.mcp_servers[name];
-            const status = server?.command ? "generated config" : "manual setup";
+            const status = server?.command ? server.execution_mode : "manual setup";
             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");
 }
+async function writeMcpSetup(root, state) {
+    const enabled = new Set(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.",
+        "",
+        "## Enabled MCP Servers",
+        ""
+    ];
+    if (enabled.size === 0) {
+        lines.push("- None.");
+    }
+    else {
+        for (const name of state.mcp_servers) {
+            const server = AGENT_STACK.mcp_servers[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}`);
+            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);
+    }
+    lines.push("", "## Operating Rules", "", "- 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 `npx academic-research mcp doctor` after changing MCP records or environment variables.", "");
+    await mkdir(join(root, "docs/agent"), { recursive: true });
+    await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
+}
 async function appendCapabilityLog(root, state) {
     const logPath = join(root, "wiki/log.md");
     const date = new Date().toISOString().slice(0, 10);
@@ -307,10 +351,24 @@ function dedupe(values) {
     return [...new Set(values)];
 }
 function renderSkillCommand(command, agent) {
-    const normalized = normalizeAgent(agent);
+    const normalized = assertKnownAgentTarget(agent);
     const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;
     return command.replaceAll("{agent_flag}", agentFlag).replaceAll("{agent}", normalized);
 }
+function appendMcpPrerequisiteLines(lines, requiredEnv, recommendedEnv, localService) {
+    if (requiredEnv.length > 0)
+        lines.push(`  - Requires env: ${requiredEnv.map((name) => `\`${name}\``).join(", ")}`);
+    if (recommendedEnv.length > 0) {
+        lines.push(`  - Recommended env: ${recommendedEnv.map((name) => `\`${name}\``).join(", ")}`);
+    }
+    if (localService)
+        lines.push(`  - Local prerequisite: ${localService}`);
+}
+function formatRuntime(command, args) {
+    if (!command)
+        return "manual setup";
+    return `\`${[command, ...args].join(" ")}\``;
+}
 async function readCapabilitiesFile(root) {
     const path = join(root, "configs/capabilities.yaml");
     return normalizeCapabilityState(YAML.parse(await readFile(path, "utf8")));
@@ -352,7 +410,7 @@ function splitCommand(command) {
 function normalizeCapabilityState(value) {
     const record = typeof value === "object" && value !== null ? value : {};
     return {
-        agent: normalizeAgent(typeof record.agent === "string" ? record.agent : undefined),
+        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)
@@ -397,12 +455,8 @@ async function removeSkillsFromLock(root, skills) {
         await writeFile(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     }
 }
-function normalizeAgent(agent) {
-    const value = agent?.trim();
-    return value ? value : DEFAULT_AGENT;
-}
 function mcpSnippetFileName(agent) {
-    const normalized = normalizeAgent(agent);
+    const normalized = normalizeAgentTarget(agent);
     return normalized === DEFAULT_AGENT || normalized === AUTO_AGENT ? "mcp.json" : `${normalized}-mcp.json`;
 }
 async function removeInactiveMcpSnippets(outputDir, activeFile) {

package/dist/src/cli.js

@@ -1,10 +1,11 @@
 import { readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, installMcpTools, installSkills, listInstalledSkills, mcpToolCommandTexts, readCapabilities, removeSkills, uninstallMcpTools, updateSkills } from "./capabilities.js";
+import { assertKnownMcpServers, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, installMcpTools, installSkills, listInstalledSkills, mcpToolCommandTexts, readCapabilities, removeSkills, uninstallMcpTools, updateSkills } from "./capabilities.js";
 import { createProject, doctorProject, renameProject } from "./project.js";
 import { askCreateOptions } from "./prompts.js";
 import { AGENT_STACK, presetMcpServers } from "./stack.js";
+import { formatAgentAliasLines, formatAgentTargetList, formatSupportedAgentTargetLines } from "./agents.js";
 import { packageify, slugify, titleFromSlug } from "./names.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const packageVersion = readPackageVersion();
@@ -101,6 +102,8 @@ async function lifecycleMain(argv) {
         return doctorCommand(argv.slice(1));
     if (command === "rename")
         return renameCommand(argv.slice(1));
+    if (command === "agents")
+        return agentsCommand(argv.slice(1));
     if (command === "skills")
         return skillsCommand(argv.slice(1));
     if (command === "mcp")
@@ -137,6 +140,21 @@ async function renameCommand(argv) {
     console.log(`Renamed project to ${result.slug}`);
     return 0;
 }
+async function agentsCommand(argv) {
+    const subcommand = argv[0] ?? "list";
+    const parsed = parseFlags(argv.slice(1), ROOT_FLAGS);
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || flagBool(parsed.flags, "help")) {
+        printAgentsHelp();
+        return 0;
+    }
+    if (subcommand === "list") {
+        assertOnlyOptions(parsed.flags, "agents list", []);
+        assertNoArguments(parsed.positionals, "agents list");
+        process.stdout.write(formatAgentTargetList());
+        return 0;
+    }
+    throw new Error(`unknown agents command: ${subcommand}`);
+}
 async function skillsCommand(argv) {
     const subcommand = argv[0] ?? "list";
     const parsed = parseFlags(argv.slice(1), SKILLS_FLAGS);
@@ -226,10 +244,10 @@ async function mcpCommand(argv) {
         assertNoArguments(parsed.positionals, "mcp list");
         const state = await readCapabilities(root);
         const enabled = new Set(state.mcp_servers ?? []);
+        console.log("status\tid\treadiness\texecution_mode\tdescription");
         for (const [name, server] of Object.entries(AGENT_STACK.mcp_servers)) {
             const status = enabled.has(name) ? "enabled" : "available";
-            const installer = mcpInstallMode(server.install_command, server.command);
-            console.log(`${status}\t${name}\t${server.source_need}\t${installer}`);
+            console.log(`${status}\t${name}\t${server.readiness}\t${server.execution_mode}\t${server.source_need}`);
         }
         return 0;
     }
@@ -245,9 +263,9 @@ async function mcpCommand(argv) {
     if (subcommand === "available") {
         assertOnlyOptions(parsed.flags, "mcp available", []);
         assertNoArguments(parsed.positionals, "mcp available");
+        console.log("id\treadiness\texecution_mode\tdescription");
         for (const [name, server] of Object.entries(AGENT_STACK.mcp_servers)) {
-            const installer = mcpInstallMode(server.install_command, server.command);
-            console.log(`${name}\t${server.source_need}\t${installer}`);
+            console.log(`${name}\t${server.readiness}\t${server.execution_mode}\t${server.source_need}`);
         }
         return 0;
     }
@@ -260,6 +278,15 @@ async function mcpCommand(argv) {
             console.log(command);
         return 0;
     }
+    if (subcommand === "env") {
+        assertOnlyOptions(parsed.flags, "mcp env", ["root"]);
+        const root = resolve(flagString(parsed.flags, "root") ?? ".");
+        const selected = parsed.positionals.length > 0 ? parsed.positionals : (await readCapabilities(root)).mcp_servers;
+        assertKnownMcpServers(selected);
+        console.log("id\ttype\tvalue");
+        printMcpEnvironment(selected);
+        return 0;
+    }
     if (subcommand === "enable") {
         assertOnlyOptions(parsed.flags, "mcp enable", ["root", "agent"]);
         const root = resolve(flagString(parsed.flags, "root") ?? ".");
@@ -387,11 +414,6 @@ function assertOnlyOptions(flags, command, allowedOptions) {
         throw new Error(`${command} does not accept ${unexpected.map((name) => `--${name}`).join(", ")}`);
     }
 }
-function mcpInstallMode(installCommand, runtimeCommand) {
-    if (installCommand)
-        return installCommand;
-    return runtimeCommand ? "runtime-only" : "manual";
-}
 export function formatInteractiveCreateGuide() {
     const presetLines = Object.entries(AGENT_STACK.presets).map(([name, preset]) => `  ${name.padEnd(10)} ${preset.description}`);
     return [
@@ -401,15 +423,24 @@ export function formatInteractiveCreateGuide() {
         ...presetLines,
         "",
         "Agent target:",
-        "  universal  Default. Installs one shared project-local .agents/skills copy.",
-        "  codex      Codex-specific project-local skill install.",
-        "  auto       Lets the upstream skills CLI detect agents; may install to multiple agent loaders.",
+        "  universal  Recommended. One shared project-local .agents/skills copy.",
+        "  auto       Let the skills CLI detect installed agents; may create multiple agent-specific copies.",
+        "  <id>       Any supported skills.sh agent id.",
+        "",
+        "Supported specific agent ids:",
+        ...formatSupportedAgentTargetLines(),
+        "",
+        "Aliases:",
+        ...formatAgentAliasLines(),
         "",
         "Skill and MCP behavior:",
         "  Skills are copied into the project, not installed globally.",
         "  MCP records are written into configs/capabilities.yaml and docs/agent/generated/.",
+        "  docs/agent/mcp-setup.md records enabled servers, optional catalog entries, env vars, and smoke tests.",
+        "  default enables only low-friction arXiv; credentialed/local services are opt-in.",
         "  MCP installers are optional and run only finite installer commands.",
-        "  runtime-only MCP servers are configured for the MCP client but have no install step.",
+        "  MCP execution modes are explicit: uvx-runtime, npx-runtime, local-service, manual, or fallback.",
+        "  Use `academic-research mcp env <server>` to inspect env vars and local prerequisites.",
         ""
     ].join("\n");
 }
@@ -426,7 +457,7 @@ function printCreateHelp() {
         "  --package <name>         Python package name. Default: normalized project name.",
         "  --preset <name>           Capability preset: minimal, default, enhanced, literature, writing, full.",
         "  --profile <name>          Project profile metadata. Default: academic-general.",
-        "  --agent <name>            Agent target. Default: universal.",
+        "  --agent <id>              Agent target: universal, auto, or a supported skills.sh id.",
         "  --install-skills          Install project-local skills without prompting.",
         "  --no-install-skills       Skip project-local skill installation.",
         "  --install-mcp-tools       Run finite external MCP install commands after creation.",
@@ -445,7 +476,7 @@ function printMissingTargetHelp() {
 }
 function printLifecycleHelp() {
     console.log([
-        "Usage: academic-research <doctor|rename|skills|mcp>",
+        "Usage: academic-research <doctor|rename|agents|skills|mcp>",
         "",
         "Manage a generated academic research repository after creation.",
         "",
@@ -454,6 +485,21 @@ function printLifecycleHelp() {
         "  -v, --version            Show package version."
     ].join("\n"));
 }
+function printAgentsHelp() {
+    console.log([
+        "Usage: academic-research agents <list>",
+        "",
+        "List supported project-local agent targets.",
+        "",
+        "Targets:",
+        "  universal                 Recommended shared project-local .agents/skills copy.",
+        "  auto                      Let the skills CLI detect installed agents.",
+        "  <id>                      A supported skills.sh agent id.",
+        "",
+        "Options:",
+        "  -h, --help                Show this help."
+    ].join("\n"));
+}
 function printSkillsHelp() {
     console.log([
         "Usage: academic-research skills <list|status|presets|install|remove|uninstall|update> [options]",
@@ -463,22 +509,50 @@ function printSkillsHelp() {
         "Options:",
         "  --root <path>            Project root for list, status, install, remove, uninstall, update.",
         "  --preset <name>          Capability preset for install.",
-        "  --agent <name>           Agent selector for install. Default: project capability agent.",
+        "  --agent <id>             Agent selector for install. Default: project capability agent.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }
 function printMcpHelp() {
     console.log([
-        "Usage: academic-research mcp <list|enabled|available|commands|enable|disable|install|uninstall|doctor> [servers...]",
+        "Usage: academic-research mcp <list|enabled|available|commands|env|enable|disable|install|uninstall|doctor> [servers...]",
         "",
         "Manage MCP records and finite external MCP tool installs.",
         "",
         "Options:",
         "  --root <path>            Project root for project-state commands.",
-        "  --agent <name>           Agent for enable/disable generated snippets.",
+        "  --agent <id>             Agent for enable/disable generated snippets.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }
+function printMcpEnvironment(servers) {
+    for (const name of servers) {
+        const server = AGENT_STACK.mcp_servers[name];
+        let wroteLine = false;
+        for (const envName of server.required_env) {
+            console.log(`${name}\trequired\t${envName}`);
+            wroteLine = true;
+        }
+        for (const envName of server.recommended_env) {
+            console.log(`${name}\trecommended\t${envName}`);
+            wroteLine = true;
+        }
+        if (server.hosted_url) {
+            console.log(`${name}\thosted-endpoint\t${server.hosted_url}`);
+            wroteLine = true;
+        }
+        if (server.local_service) {
+            console.log(`${name}\tlocal-service\t${server.local_service}`);
+            wroteLine = true;
+        }
+        for (const command of server.setup_commands) {
+            console.log(`${name}\tsetup-command\t${command}`);
+            wroteLine = true;
+        }
+        if (!wroteLine)
+            console.log(`${name}\tnone\t-`);
+    }
+}
 function readPackageVersion() {
     try {
         const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));

package/dist/src/project.js

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { DEFAULT_AGENT, initializeCapabilities, installSkills } 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";
 import { AGENT_STACK } from "./stack.js";
@@ -90,7 +91,7 @@ export async function createProject(options) {
     const slug = slugify(options.slug ?? title);
     const packageName = packageify(options.packageName ?? slug);
     const preset = options.preset ?? "default";
-    const agent = options.agent ?? DEFAULT_AGENT;
+    const agent = assertKnownAgentTarget(options.agent ?? DEFAULT_AGENT);
     if (!AGENT_STACK.presets[preset]) {
         throw new Error(`unknown capability preset: ${preset}. Expected one of: ${Object.keys(AGENT_STACK.presets).join(", ")}`);
     }
@@ -135,6 +136,7 @@ export async function doctorProject(root) {
         "configs/agent-stack.yaml",
         "configs/capabilities.yaml",
         "docs/agent/capability-profile.md",
+        "docs/agent/mcp-setup.md",
         "docs/agent/generated",
         "sources/source-ledger.csv",
         "sota/literature-matrix.csv",
@@ -205,7 +207,7 @@ async function writeGeneratedPackageJson(root, { slug }) {
     const path = join(root, "package.json");
     const data = await readJson(path);
     const existingSpec = data.devDependencies?.["create-academic-research"];
-    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "0.1.4";
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "0.1.6";
     data.name = slug;
     data.devDependencies = {
         ...(data.devDependencies ?? {}),

package/dist/src/prompts.js

@@ -9,7 +9,8 @@ export async function askCreateOptions(defaults, locks = {}) {
         const preset = await question(rl, "Capability preset", defaults.preset);
         const agent = await question(rl, "Agent target", defaults.agent);
         const installSkills = locks.installSkills ?? (await yesNo(rl, "Install project-local skills now", defaults.installSkills));
-        const installMcpTools = locks.installMcpTools ?? (await yesNo(rl, "Run external MCP installers now", defaults.installMcpTools));
+        const installMcpTools = locks.installMcpTools ??
+            (await yesNo(rl, "Run finite external MCP tool installers now", defaults.installMcpTools));
         return { title, slug, packageName, preset, agent, installSkills, installMcpTools };
     }
     finally {

package/dist/src/stack.d.ts

@@ -8,13 +8,21 @@ export interface CapabilityPreset {
     mcp_servers: string[];
 }
 export interface McpServer {
+    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;
 }

package/dist/src/stack.js

@@ -20,38 +20,6 @@ export const AGENT_STACK = {
             commands: [
                 "npm exec --yes --package skills -- skills add existential-birds/beagle {agent_flag} --skill docling --copy -y"
             ]
-        },
-        optional_connectors: {
-            description: "CLI-side literature connectors to use only when MCP servers are unavailable.",
-            commands: [
-                "npm exec --yes --package skills -- skills add davila7/claude-code-templates {agent_flag} --skill openalex-database --copy -y",
-                "npm exec --yes --package skills -- skills add agents365-ai/365-skills {agent_flag} --skill semanticscholar-skill --copy -y",
-                "npm exec --yes --package skills -- skills add fuzhiyu/researchprojecttemplate {agent_flag} --skill zotero-paper-reader --copy -y"
-            ]
-        },
-        optional_mechanical_specialists: {
-            description: "Narrow mechanical helpers that do not replace project-native governance.",
-            commands: [
-                "npm exec --yes --package skills -- skills add bahayonghang/academic-writing-skills {agent_flag} --skill latex-paper-en --copy -y",
-                [
-                    "npm exec --yes --package skills -- skills add lllllllama/ai-paper-reproduction-skill",
-                    "{agent_flag}",
-                    "--skill",
-                    [
-                        "ai-research-reproduction",
-                        "repo-intake-and-plan",
-                        "env-and-assets-bootstrap",
-                        "minimal-run-and-audit",
-                        "paper-context-resolver",
-                        "analyze-project",
-                        "safe-debug",
-                        "run-train",
-                        "explore-run",
-                        "explore-code"
-                    ].join(" "),
-                    "--copy -y"
-                ].join(" ")
-            ]
         }
     },
     presets: {
@@ -61,119 +29,205 @@ export const AGENT_STACK = {
             mcp_servers: []
         },
         default: {
-            description: "Clean academic research setup with core scholarly MCP records.",
+            description: "Clean academic research setup with the low-friction arXiv MCP record.",
             skill_bundles: ["academic_research"],
-            mcp_servers: ["arxiv", "semantic-scholar", "openalex"]
+            mcp_servers: ["arxiv"]
         },
         enhanced: {
             description: "Default academic setup plus complementary agent engineering, document, frontend, testing, and doc conversion skills.",
             skill_bundles: ["academic_research", "default_complementary", "docling"],
-            mcp_servers: ["arxiv", "semantic-scholar", "openalex"]
+            mcp_servers: ["arxiv"]
         },
         literature: {
-            description: "Literature-heavy SOTA, survey, scoping, or systematic review setup.",
+            description: "Literature-heavy SOTA, survey, scoping, or systematic review setup with CS bibliography support.",
             skill_bundles: ["academic_research", "default_complementary", "docling"],
-            mcp_servers: ["arxiv", "semantic-scholar", "openalex", "crossref", "zotero"]
+            mcp_servers: ["arxiv", "dblp"]
         },
         writing: {
-            description: "Paper-writing and Overleaf-oriented setup.",
-            skill_bundles: [
-                "academic_research",
-                "default_complementary",
-                "docling",
-                "optional_mechanical_specialists"
-            ],
-            mcp_servers: ["arxiv", "semantic-scholar", "crossref", "overleaf"]
+            description: "Paper-writing setup with Overleaf documented as an opt-in credentialed integration.",
+            skill_bundles: ["academic_research", "default_complementary", "docling"],
+            mcp_servers: ["arxiv"]
         },
         full: {
-            description: "Broad setup with optional connector and mechanical specialist skills.",
-            skill_bundles: [
-                "academic_research",
-                "default_complementary",
-                "docling",
-                "optional_connectors",
-                "optional_mechanical_specialists"
-            ],
-            mcp_servers: ["arxiv", "semantic-scholar", "openalex", "crossref", "pubmed", "zotero", "overleaf"]
+            description: "Broad setup with low-friction scholarly MCP records plus the full optional MCP catalog documented.",
+            skill_bundles: ["academic_research", "default_complementary", "docling"],
+            mcp_servers: ["arxiv", "dblp"]
         }
     },
     mcp_servers: {
         arxiv: {
+            readiness: "low-friction",
             priority: "default",
+            execution_mode: "uvx-runtime",
             source_need: "arXiv search, download, and local paper reading.",
+            source: "blazickjp/arxiv-mcp-server",
+            hosted_url: "",
             install_command: "uv tool install 'arxiv-mcp-server[pdf]'",
             uninstall_command: "uv tool uninstall arxiv-mcp-server",
-            command: "arxiv-mcp-server",
-            args: [],
+            setup_commands: [],
+            command: "uvx",
+            args: ["--from", "arxiv-mcp-server[pdf]", "arxiv-mcp-server"],
             env: {},
+            required_env: [],
+            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."
         },
         "semantic-scholar": {
-            priority: "default",
+            readiness: "credential-recommended",
+            priority: "optional",
+            execution_mode: "uvx-runtime",
             source_need: "Semantic Scholar papers, citations, authors, and recommendations.",
+            source: "akapet00/semantic-scholar-mcp",
+            hosted_url: "",
             install_command: "",
             uninstall_command: "",
+            setup_commands: [],
             command: "uvx",
             args: ["--from", "git+https://github.com/akapet00/semantic-scholar-mcp", "semantic-scholar-mcp"],
-            env: { SEMANTIC_SCHOLAR_API_KEY: "${SEMANTIC_SCHOLAR_API_KEY}" },
+            env: {},
+            required_env: [],
+            recommended_env: ["SEMANTIC_SCHOLAR_API_KEY"],
             smoke_test: "Search one known title, then fetch citations or references.",
-            risks: "API key recommended for sustained work; metadata can be incomplete."
+            local_service: "",
+            risks: "API key recommended for sustained work and to avoid shared-pool rate limits; metadata can be incomplete."
         },
         openalex: {
-            priority: "default",
+            readiness: "credential-required",
+            priority: "optional",
+            execution_mode: "npx-runtime",
             source_need: "OpenAlex broad scholarly graph.",
+            source: "cyanheads/openalex-mcp-server",
+            hosted_url: "https://openalex.caseyjhand.com/mcp",
             install_command: "",
             uninstall_command: "",
+            setup_commands: [],
             command: "npx",
-            args: ["-y", "@cyanheads/openalex-mcp-server"],
-            env: { OPENALEX_API_KEY: "${OPENALEX_API_KEY_OR_EMAIL}" },
+            args: ["-y", "@cyanheads/openalex-mcp-server@latest"],
+            env: {},
+            required_env: ["OPENALEX_API_KEY"],
+            recommended_env: [],
+            local_service: "",
             smoke_test: "Search works by title or DOI and confirm stable OpenAlex IDs.",
-            risks: "Smoke-test before relying on it for final coverage."
+            risks: "The selected local server requires OPENALEX_API_KEY. OpenAlex keys are free for normal academic use with daily free usage; smoke-test coverage and cost headers before high-volume work."
         },
         crossref: {
+            readiness: "manual",
             priority: "manual",
+            execution_mode: "manual",
             source_need: "DOI and publication metadata.",
+            source: "manual selection required; candidate: AiAgentKarl/crossref-academic-mcp-server",
+            hosted_url: "",
             install_command: "",
             uninstall_command: "",
+            setup_commands: [],
             command: "",
             args: [],
             env: {},
+            required_env: [],
+            recommended_env: [],
+            local_service: "",
             smoke_test: "Resolve one DOI into publication metadata after choosing a maintained local server.",
-            risks: "Manual integration only; do not generate placeholder paths."
+            risks: "Manual integration only; current zero-friction Crossref-only MCP candidates are less mature than arXiv, DBLP, PubMed, or OpenAlex."
         },
         pubmed: {
+            readiness: "domain-specific",
             priority: "domain-specific",
+            execution_mode: "npx-runtime",
             source_need: "PubMed and biomedical literature.",
+            source: "cyanheads/pubmed-mcp-server",
+            hosted_url: "https://pubmed.caseyjhand.com/mcp",
             install_command: "",
             uninstall_command: "",
+            setup_commands: [],
             command: "npx",
-            args: ["-y", "@cyanheads/pubmed-mcp-server"],
-            env: { NCBI_API_KEY: "${NCBI_API_KEY}" },
+            args: ["-y", "@cyanheads/pubmed-mcp-server@latest"],
+            env: { MCP_TRANSPORT_TYPE: "stdio", MCP_LOG_LEVEL: "warning" },
+            required_env: [],
+            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."
+            risks: "Domain-specific; observe NCBI rate limits. API key and contact email improve reliability."
+        },
+        dblp: {
+            readiness: "low-friction-cs",
+            priority: "cs",
+            execution_mode: "uvx-runtime",
+            source_need: "DBLP computer science bibliography, venues, authors, and BibTeX.",
+            source: "szeider/mcp-dblp",
+            hosted_url: "",
+            install_command: "",
+            uninstall_command: "",
+            setup_commands: [],
+            command: "uvx",
+            args: ["mcp-dblp"],
+            env: {},
+            required_env: [],
+            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."
         },
         zotero: {
+            readiness: "local-service",
             priority: "local-library",
+            execution_mode: "local-service",
             source_need: "Zotero local library and attachments.",
+            source: "eric-tramel/zoty",
+            hosted_url: "",
             install_command: "",
             uninstall_command: "",
+            setup_commands: ["uvx --refresh zoty setup", "uvx --refresh zoty doctor"],
             command: "uvx",
             args: ["zoty", "mcp"],
             env: {},
+            required_env: [],
+            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."
         },
         overleaf: {
+            readiness: "manual-credentialed",
             priority: "writing",
+            execution_mode: "manual-local",
             source_need: "Overleaf project sync.",
-            install_command: "uv tool install overleaf-mcp-server",
-            uninstall_command: "uv tool uninstall overleaf-mcp-server",
-            command: "overleaf-mcp",
-            args: ["serve"],
-            env: { OVERLEAF_TOKEN: "${OVERLEAF_TOKEN}" },
+            source: "YounesBensafia/overleaf-mcp-server",
+            hosted_url: "",
+            install_command: "",
+            uninstall_command: "",
+            setup_commands: [],
+            command: "",
+            args: [],
+            env: {},
+            required_env: ["OVERLEAF_TOKEN"],
+            recommended_env: ["PROJECT_ID"],
+            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 setup; write access needs explicit approval."
+            risks: "Requires token and project setup; write/push access needs explicit approval."
+        },
+        "paper-search": {
+            readiness: "fallback",
+            priority: "fallback",
+            execution_mode: "manual-fallback",
+            source_need: "Multi-source paper search and download fallback across many scholarly sources.",
+            source: "openags/paper-search-mcp",
+            hosted_url: "",
+            install_command: "",
+            uninstall_command: "",
+            setup_commands: [],
+            command: "",
+            args: [],
+            env: {},
+            required_env: [],
+            recommended_env: [
+                "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL",
+                "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY"
+            ],
+            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."
         }
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Create and manage agent-ready academic research repositories.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -53,23 +53,30 @@ Project-local skills and MCP records are managed with:
 
 ```bash
 npx academic-research skills presets
+npx academic-research agents list
 npx academic-research skills install --preset default
 npx academic-research skills install --preset enhanced
 npx academic-research skills list
 npx academic-research skills status
-npx academic-research mcp enable arxiv semantic-scholar openalex
 npx academic-research mcp list
+npx academic-research mcp env openalex semantic-scholar zotero
+npx academic-research mcp enable arxiv dblp
 npx academic-research mcp commands arxiv
 npx academic-research mcp install arxiv
+npx academic-research mcp doctor
 ```
 
 `skills list` reports installed project-local skills. `skills presets` reports
 available install presets. `mcp enable` changes project records. `mcp commands`
-prints finite external install commands without running them. `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.
+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.
 
 `default` installs the companion academic research skill package and keeps the
-MCP records focused on core scholarly discovery. `enhanced` adds complementary
-external skills for agent engineering, frontend work, testing, document
-formats, and PDF conversion.
+MCP records focused on low-friction arXiv discovery. `literature` and `full`
+add DBLP for computer science bibliography. Credentialed, local-service, or
+domain-specific MCP servers such as OpenAlex, Semantic Scholar, PubMed, Zotero,
+and Overleaf should be enabled only after reading `docs/agent/mcp-setup.md` and
+checking their prerequisites with `mcp env`.

package/template/package.json

@@ -9,9 +9,10 @@
     "skills:presets": "academic-research skills presets",
     "mcp:list": "academic-research mcp list",
     "mcp:commands": "academic-research mcp commands",
+    "mcp:env": "academic-research mcp env",
     "mcp:doctor": "academic-research mcp doctor"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.4"
+    "create-academic-research": "0.1.6"
   }
 }