create-academic-research 0.1.7 → 0.1.9

package/README.md

@@ -93,6 +93,7 @@ npx academic-research agents list
 npx academic-research skills presets
 npx academic-research skills install --preset default
 npx academic-research skills install --preset enhanced
+npx academic-research skills install source-ingestion sota-literature-review
 npx academic-research skills list
 npx academic-research skills status
 npx academic-research skills remove source-ingestion
@@ -103,6 +104,7 @@ 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 env --dotenv --all > .env.example
 npx academic-research mcp enable arxiv dblp
 npx academic-research mcp disable arxiv
 npx academic-research mcp install arxiv
@@ -122,7 +124,7 @@ Skills are project-local by default.
 | Command | Meaning |
 |---|---|
 | `skills presets` | List available capability presets. |
-| `skills install` | Install project-local skills for the selected preset and project agent. This does not change MCP records. |
+| `skills install` | Install project-local skills by preset, or selected skill ids such as `source-ingestion`. This does not change MCP records. |
 | `skills list` | List skills found in project-local skill loader directories. |
 | `skills status` | Show configured project preset, agent, scope, skill roots, unique skill ids, and installed copies. |
 | `skills remove` / `skills uninstall` | Remove selected project-local skills. |
@@ -136,7 +138,7 @@ 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 env` | Print required/recommended env vars, hosted endpoints, local prerequisites, and setup commands for selected servers. Use `--dotenv --all` to regenerate `.env.example`. |
 | `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. |
@@ -184,11 +186,17 @@ 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.
+selected local adapter; OpenAlex keys are free and include a free daily quota,
+but high-volume work should check current credit limits. 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 projects include a committed `.env.example` with empty MCP variables
+and ignore filled `.env` or `.env.local` files. `mcp doctor` checks the current
+process environment or client-provided secrets; it does not load `.env.local`
+automatically.
 
 Generated MCP snippets are project documentation and client-ready config, not
 live tools by themselves. Your MCP client must load the generated snippet, and
@@ -215,8 +223,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.7 -m "v0.1.7"
-git push origin main v0.1.7
+git tag -a v0.1.9 -m "v0.1.9"
+git push origin main v0.1.9
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/capabilities.d.ts

@@ -16,6 +16,7 @@ export interface InitializeCapabilitiesOptions {
 export interface CapabilityCommandResult {
     ok: true;
     count?: number;
+    skills?: string[];
     servers?: string[];
 }
 export interface InstalledSkill {
@@ -29,14 +30,23 @@ export interface McpDoctorResult {
     warnings: string[];
     enabled: string[];
 }
+export interface McpEnvironmentEntry {
+    server: string;
+    kind: "required" | "recommended" | "default";
+    name: string;
+    value: string;
+}
 interface SkillInstallOptions {
     agent?: string;
 }
 export declare function readCapabilities(root: string): Promise<CapabilityState>;
 export declare function writeCapabilities(root: string, state: Partial<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[][]>;
+export declare function buildExplicitSkillInstallCommands(root: string, skills: string[], options?: SkillInstallOptions): Promise<string[][]>;
 export declare function installSkills(root: string, preset?: string, options?: SkillInstallOptions, runner?: Runner): Promise<CapabilityCommandResult>;
+export declare function installSkillIds(root: string, skills: string[], options?: SkillInstallOptions, runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function listInstalledSkills(root: string): Promise<InstalledSkill[]>;
 export declare function removeSkills(root: string, skills: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function updateSkills(root: string, runner?: Runner): Promise<CapabilityCommandResult>;
@@ -48,6 +58,14 @@ export declare function disableMcpServers(root: string, servers: string[], optio
 }): Promise<CapabilityCommandResult>;
 export declare function mcpToolCommands(servers: string[], key?: McpToolCommandKey): string[][];
 export declare function mcpToolCommandTexts(servers: string[], key?: McpToolCommandKey): string[];
+export declare function listMcpEnvironmentEntries(servers: string[], options?: {
+    requiredOnly?: boolean;
+    recommendedOnly?: boolean;
+}): McpEnvironmentEntry[];
+export declare function formatMcpDotenv(servers: string[], options?: {
+    requiredOnly?: boolean;
+    recommendedOnly?: boolean;
+}): string;
 export declare function installMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function uninstallMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function doctorMcpServers(root: string): Promise<McpDoctorResult>;

package/dist/src/capabilities.js

@@ -29,6 +29,9 @@ export async function writeCapabilities(root, state) {
     await writeMcpSnippet(root, next);
     await appendCapabilityLog(root, next);
 }
+export async function writeMcpEnvironmentExample(root) {
+    await writeFile(join(root, ".env.example"), formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers)), "utf8");
+}
 export async function initializeCapabilities(root, options = {}) {
     const preset = options.preset ?? "default";
     const mcpServers = options.mcpServers ?? presetMcpServers(preset);
@@ -60,6 +63,21 @@ export async function buildSkillInstallCommands(root, preset = "default", option
     }
     return commands;
 }
+export async function buildExplicitSkillInstallCommands(root, skills, options = {}) {
+    const selectedSkills = normalizeSkillIds(skills);
+    const state = await readCapabilities(root);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
+    const skillsBySource = new Map();
+    for (const skill of selectedSkills) {
+        const source = skillSourceForId(skill);
+        if (!source)
+            throw new Error(`unknown skill id: ${skill}`);
+        const sourceSkills = skillsBySource.get(source) ?? [];
+        sourceSkills.push(skill);
+        skillsBySource.set(source, sourceSkills);
+    }
+    return [...skillsBySource.entries()].map(([source, sourceSkills]) => skillAddCommand(source, sourceSkills, agent));
+}
 export async function installSkills(root, preset = "default", options = {}, runner = defaultRunner) {
     const state = await readCapabilities(root);
     const agent = assertKnownAgentTarget(options.agent ?? state.agent);
@@ -76,6 +94,22 @@ export async function installSkills(root, preset = "default", options = {}, runn
     }
     return { ok: true, count: commands.length };
 }
+export async function installSkillIds(root, skills, options = {}, runner = defaultRunner) {
+    const state = await readCapabilities(root);
+    const agent = assertKnownAgentTarget(options.agent ?? state.agent);
+    const selectedSkills = normalizeSkillIds(skills);
+    const commands = await buildExplicitSkillInstallCommands(root, selectedSkills, options);
+    for (const command of commands) {
+        await runner.run(command, { cwd: root });
+    }
+    if (state.agent !== agent) {
+        await writeCapabilities(root, {
+            ...state,
+            agent
+        });
+    }
+    return { ok: true, count: commands.length, skills: selectedSkills };
+}
 export async function listInstalledSkills(root) {
     const roots = await discoverProjectSkillRoots(root);
     const skills = [];
@@ -173,6 +207,50 @@ export function mcpToolCommandTexts(servers, key = "install_command") {
     }
     return commands;
 }
+export function listMcpEnvironmentEntries(servers, options = {}) {
+    assertKnownMcpServers(servers);
+    const entries = [];
+    for (const serverName of servers) {
+        const server = AGENT_STACK.mcp_servers[serverName];
+        if (!options.recommendedOnly) {
+            for (const envName of server.required_env) {
+                entries.push({ server: serverName, kind: "required", name: envName, value: "" });
+            }
+        }
+        if (!options.requiredOnly) {
+            for (const envName of server.recommended_env) {
+                entries.push({ server: serverName, kind: "recommended", name: envName, value: "" });
+            }
+            for (const [envName, value] of Object.entries(server.env)) {
+                entries.push({ server: serverName, kind: "default", name: envName, value });
+            }
+        }
+    }
+    return dedupeMcpEnvironmentEntries(entries);
+}
+export function formatMcpDotenv(servers, options = {}) {
+    const entries = listMcpEnvironmentEntries(servers, options);
+    const lines = [
+        "# Academic research MCP environment example.",
+        "# Copy to .env.local, your shell profile, or your MCP client secret store.",
+        "# Do not commit filled secrets. Empty values mean optional or user-supplied.",
+        ""
+    ];
+    let previousServer = "";
+    for (const entry of entries) {
+        if (entry.server !== previousServer) {
+            if (previousServer)
+                lines.push("");
+            lines.push(`# ${entry.server} environment`);
+            previousServer = entry.server;
+        }
+        lines.push(`${entry.name}=${dotenvValue(entry.value)}`);
+    }
+    if (entries.length === 0) {
+        lines.push("# No environment variables are required for the selected MCP servers.");
+    }
+    return `${lines.join("\n")}\n`;
+}
 export async function installMcpTools(root, servers, runner = defaultRunner) {
     const selected = servers.length > 0 ? servers : (await readCapabilities(root)).mcp_servers ?? [];
     assertKnownMcpServers(selected);
@@ -287,6 +365,7 @@ async function writeCapabilityProfile(root, state) {
         "## Skills",
         "",
         `- Install with: \`academic-research skills install --preset ${state.preset ?? "default"}\``,
+        "- Install selected skills with: `academic-research skills install <skill-id> [...]`",
         "- List installed with: `academic-research skills list`",
         "- List presets with: `academic-research skills presets`",
         "- Remove with: `academic-research skills remove <skill>`",
@@ -337,7 +416,7 @@ async function writeMcpSetup(root, state) {
         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.", "");
+    lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Regenerate a dotenv-style reference with `npx academic-research mcp env --dotenv --all`.", "- 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");
 }
@@ -350,11 +429,71 @@ async function appendCapabilityLog(root, state) {
 function dedupe(values) {
     return [...new Set(values)];
 }
+function dedupeMcpEnvironmentEntries(entries) {
+    const priority = { required: 0, default: 1, recommended: 2 };
+    const byName = new Map();
+    for (const entry of entries) {
+        const previous = byName.get(entry.name);
+        if (!previous || priority[entry.kind] < priority[previous.kind]) {
+            byName.set(entry.name, entry);
+        }
+    }
+    return [...byName.values()];
+}
+function dotenvValue(value) {
+    if (!value)
+        return "";
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
 function renderSkillCommand(command, agent) {
     const normalized = assertKnownAgentTarget(agent);
     const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;
     return command.replaceAll("{agent_flag}", agentFlag).replaceAll("{agent}", normalized);
 }
+function skillAddCommand(source, skills, agent) {
+    return [
+        "npm",
+        "exec",
+        "--yes",
+        "--package",
+        "skills",
+        "--",
+        "skills",
+        "add",
+        source,
+        ...skillAgentArgs(agent),
+        "--skill",
+        ...skills,
+        "--copy",
+        "-y"
+    ];
+}
+function skillAgentArgs(agent) {
+    const normalized = assertKnownAgentTarget(agent);
+    return normalized === AUTO_AGENT ? [] : ["--agent", normalized];
+}
+function normalizeSkillIds(skills) {
+    if (skills.length === 0)
+        throw new Error("no skills selected");
+    const result = [];
+    for (const skill of skills) {
+        if (!/^[a-z0-9][a-z0-9._-]*$/.test(skill)) {
+            throw new Error(`invalid skill id: ${skill}`);
+        }
+        if (!result.includes(skill))
+            result.push(skill);
+    }
+    return result;
+}
+function skillSourceForId(skill) {
+    for (const source of Object.values(AGENT_STACK.skill_sources)) {
+        if (source.skills.includes(skill))
+            return source.source;
+    }
+    return undefined;
+}
 function appendMcpPrerequisiteLines(lines, requiredEnv, recommendedEnv, localService) {
     if (requiredEnv.length > 0)
         lines.push(`  - Requires env: ${requiredEnv.map((name) => `\`${name}\``).join(", ")}`);

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { assertKnownMcpServers, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, installMcpTools, installSkills, listInstalledSkills, mcpToolCommandTexts, readCapabilities, removeSkills, uninstallMcpTools, updateSkills } from "./capabilities.js";
+import { assertKnownMcpServers, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, 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";
@@ -9,11 +9,19 @@ import { formatAgentAliasLines, formatAgentTargetList, formatSupportedAgentTarge
 import { packageify, slugify, titleFromSlug } from "./names.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const packageVersion = readPackageVersion();
-const CREATE_FLAGS = flagSchema(["yes", "help", "version", "install-skills", "no-install-skills", "install-mcp-tools"], ["title", "slug", "package", "preset", "profile", "agent"]);
+const CREATE_FLAGS = flagSchema([
+    "yes",
+    "help",
+    "version",
+    "install-skills",
+    "no-install-skills",
+    "install-mcp-tools",
+    "no-install-mcp-tools"
+], ["title", "slug", "package", "preset", "profile", "agent"]);
 const ROOT_FLAGS = flagSchema(["help"], ["root"]);
 const RENAME_FLAGS = flagSchema(["help"], ["root", "title", "slug", "package"]);
 const SKILLS_FLAGS = flagSchema(["help"], ["root", "preset", "agent"]);
-const MCP_FLAGS = flagSchema(["help"], ["root", "agent"]);
+const MCP_FLAGS = flagSchema(["help", "all", "dotenv", "required", "recommended"], ["root", "agent"]);
 export async function main(argv = process.argv.slice(2), mode = "create") {
     try {
         if (mode === "create")
@@ -43,6 +51,9 @@ async function createMain(argv) {
     if (flagBool(parsed.flags, "install-skills") && flagBool(parsed.flags, "no-install-skills")) {
         throw new Error("cannot use --install-skills and --no-install-skills together");
     }
+    if (flagBool(parsed.flags, "install-mcp-tools") && flagBool(parsed.flags, "no-install-mcp-tools")) {
+        throw new Error("cannot use --install-mcp-tools and --no-install-mcp-tools together");
+    }
     if (parsed.positionals.length > 1) {
         throw new Error(`unexpected argument: ${parsed.positionals[1]}`);
     }
@@ -60,7 +71,9 @@ async function createMain(argv) {
     const installSkillsLock = flagBool(parsed.flags, "install-skills") || flagBool(parsed.flags, "no-install-skills")
         ? defaults.installSkills
         : undefined;
-    const installMcpToolsLock = flagBool(parsed.flags, "install-mcp-tools") ? true : undefined;
+    const installMcpToolsLock = flagBool(parsed.flags, "install-mcp-tools") || flagBool(parsed.flags, "no-install-mcp-tools")
+        ? defaults.installMcpTools
+        : undefined;
     const answers = interactive
         ? await askInteractiveCreateOptions(defaults, {
             installSkills: installSkillsLock,
@@ -158,6 +171,7 @@ async function setupCommand(argv) {
     console.log("academic-research skills status");
     console.log("academic-research mcp list");
     console.log("academic-research mcp env");
+    console.log("academic-research mcp env --dotenv --all");
     console.log("academic-research mcp smoke");
     console.log("academic-research doctor");
     return project.ok ? 0 : 1;
@@ -240,8 +254,18 @@ async function skillsCommand(argv) {
     if (subcommand === "install") {
         assertOnlyOptions(parsed.flags, "skills install", ["root", "preset", "agent"]);
         const root = resolve(flagString(parsed.flags, "root") ?? ".");
-        assertNoArguments(parsed.positionals, "skills install");
-        const preset = flagString(parsed.flags, "preset") ?? "default";
+        const explicitSkills = parsed.positionals;
+        const explicitPreset = flagString(parsed.flags, "preset");
+        if (explicitSkills.length > 0) {
+            if (explicitPreset)
+                throw new Error("skills install does not accept --preset when skill ids are provided");
+            const result = await installSkillIds(root, explicitSkills, {
+                agent: flagString(parsed.flags, "agent")
+            });
+            console.log(`Installed ${result.skills?.length ?? explicitSkills.length} skill(s) with ${result.count ?? 0} command(s).`);
+            return 0;
+        }
+        const preset = explicitPreset ?? "default";
         const result = await installSkills(root, preset, {
             agent: flagString(parsed.flags, "agent")
         });
@@ -316,12 +340,27 @@ async function mcpCommand(argv) {
         return 0;
     }
     if (subcommand === "env") {
-        assertOnlyOptions(parsed.flags, "mcp env", ["root"]);
+        assertOnlyOptions(parsed.flags, "mcp env", ["root", "all", "dotenv", "required", "recommended"]);
         const root = resolve(flagString(parsed.flags, "root") ?? ".");
-        const selected = parsed.positionals.length > 0 ? parsed.positionals : (await readCapabilities(root)).mcp_servers;
+        if (flagBool(parsed.flags, "required") && flagBool(parsed.flags, "recommended")) {
+            throw new Error("mcp env cannot use --required and --recommended together");
+        }
+        const selected = flagBool(parsed.flags, "all")
+            ? Object.keys(AGENT_STACK.mcp_servers)
+            : parsed.positionals.length > 0
+                ? parsed.positionals
+                : (await readCapabilities(root)).mcp_servers;
         assertKnownMcpServers(selected);
+        const filters = {
+            requiredOnly: flagBool(parsed.flags, "required"),
+            recommendedOnly: flagBool(parsed.flags, "recommended")
+        };
+        if (flagBool(parsed.flags, "dotenv")) {
+            process.stdout.write(formatMcpDotenv(selected, filters));
+            return 0;
+        }
         console.log("id\ttype\tvalue");
-        printMcpEnvironment(selected);
+        printMcpEnvironment(selected, filters);
         return 0;
     }
     if (subcommand === "enable") {
@@ -496,6 +535,7 @@ export function formatInteractiveCreateGuide() {
         "  MCP installers are optional and run only finite installer commands.",
         "  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.",
+        "  Use `academic-research mcp env --dotenv --all` to regenerate a committed env example.",
         ""
     ].join("\n");
 }
@@ -516,6 +556,7 @@ function printCreateHelp() {
         "  --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.",
+        "  --no-install-mcp-tools    Skip finite external MCP install commands.",
         "  -h, --help               Show this help.",
         "  -v, --version            Show package version."
     ].join("\n"));
@@ -568,13 +609,17 @@ function printAgentsHelp() {
 }
 function printSkillsHelp() {
     console.log([
-        "Usage: academic-research skills <list|status|presets|install|remove|uninstall|update> [options]",
+        "Usage: academic-research skills <list|status|presets|install|remove|uninstall|update> [skill-id...] [options]",
         "",
         "Manage project-local skill installs for a generated research repository.",
         "",
+        "Examples:",
+        "  academic-research skills install --preset default",
+        "  academic-research skills install source-ingestion sota-literature-review",
+        "",
         "Options:",
         "  --root <path>            Project root for list, status, install, remove, uninstall, update.",
-        "  --preset <name>          Capability preset for install.",
+        "  --preset <name>          Capability preset for install when no skill ids are provided.",
         "  --agent <id>             Agent selector for install. Default: project capability agent.",
         "  -h, --help               Show this help."
     ].join("\n"));
@@ -585,9 +630,18 @@ function printMcpHelp() {
         "",
         "Manage MCP records, readiness checks, and finite external MCP tool installs.",
         "",
+        "Examples:",
+        "  academic-research mcp env openalex semantic-scholar",
+        "  academic-research mcp env --dotenv --all > .env.example",
+        "  academic-research mcp smoke",
+        "",
         "Options:",
         "  --root <path>            Project root for project-state commands.",
         "  --agent <id>             Agent for enable/disable generated snippets.",
+        "  --all                    Select all catalog MCP servers for mcp env.",
+        "  --dotenv                Print mcp env as dotenv content.",
+        "  --required              Print only required env vars for mcp env.",
+        "  --recommended           Print only recommended/default env vars for mcp env.",
         "  -h, --help               Show this help."
     ].join("\n"));
 }
@@ -617,29 +671,34 @@ function printMcpSmokeDiagnostics(servers) {
     }
     return failed;
 }
-function printMcpEnvironment(servers) {
+function printMcpEnvironment(servers, options = {}) {
+    const grouped = new Map();
+    for (const entry of listMcpEnvironmentEntries(servers, options)) {
+        const entries = grouped.get(entry.server) ?? [];
+        entries.push(entry);
+        grouped.set(entry.server, entries);
+    }
     for (const name of servers) {
         const server = AGENT_STACK.mcp_servers[name];
+        const entries = grouped.get(name) ?? [];
         let wroteLine = false;
-        for (const envName of server.required_env) {
-            console.log(`${name}\trequired\t${envName}`);
+        for (const entry of entries) {
+            console.log(`${name}\t${entry.kind}\t${entry.name}${entry.value ? `=${entry.value}` : ""}`);
             wroteLine = true;
         }
-        for (const envName of server.recommended_env) {
-            console.log(`${name}\trecommended\t${envName}`);
-            wroteLine = true;
-        }
-        if (server.hosted_url) {
+        if (!options.requiredOnly && !options.recommendedOnly && server.hosted_url) {
             console.log(`${name}\thosted-endpoint\t${server.hosted_url}`);
             wroteLine = true;
         }
-        if (server.local_service) {
+        if (!options.requiredOnly && !options.recommendedOnly && 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 (!options.requiredOnly && !options.recommendedOnly) {
+            for (const command of server.setup_commands) {
+                console.log(`${name}\tsetup-command\t${command}`);
+                wroteLine = true;
+            }
         }
         if (!wroteLine)
             console.log(`${name}\tnone\t-`);

package/dist/src/project.js

@@ -2,7 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 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 { DEFAULT_AGENT, initializeCapabilities, installSkills, 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";
@@ -100,6 +100,7 @@ export async function createProject(options) {
     await personalizeProject(target, { title, slug, packageName, profile: options.profile ?? "academic-general" });
     await writeGeneratedPackageJson(target, { slug });
     await writeAgentStack(target);
+    await writeMcpEnvironmentExample(target);
     await initializeCapabilities(target, { preset, agent });
     if (options.installSkills) {
         await installSkills(target, preset);
@@ -129,6 +130,7 @@ export async function doctorProject(root) {
     const errors = [];
     const required = [
         "README.md",
+        ".env.example",
         "package.json",
         "pyproject.toml",
         "AGENTS.md",
@@ -137,6 +139,7 @@ export async function doctorProject(root) {
         "configs/capabilities.yaml",
         "docs/agent/capability-profile.md",
         "docs/agent/mcp-setup.md",
+        "docs/agent/mcp-client-setup.md",
         "docs/agent/generated",
         "scripts/README.md",
         "sources/source-ledger.csv",
@@ -214,7 +217,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.7";
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ?? existingSpec ?? "0.1.9";
     data.name = slug;
     data.devDependencies = {
         ...(data.devDependencies ?? {}),

package/dist/src/stack.d.ts

@@ -2,6 +2,11 @@ export interface SkillBundle {
     description: string;
     commands: string[];
 }
+export interface SkillSource {
+    description: string;
+    source: string;
+    skills: string[];
+}
 export interface CapabilityPreset {
     description: string;
     skill_bundles: string[];
@@ -30,6 +35,7 @@ export interface AgentStack {
     version: number;
     description: string;
     skill_bundles: Record<string, SkillBundle>;
+    skill_sources: Record<string, SkillSource>;
     presets: Record<string, CapabilityPreset>;
     mcp_servers: Record<string, McpServer>;
 }

package/dist/src/stack.js

@@ -22,6 +22,76 @@ export const AGENT_STACK = {
             ]
         }
     },
+    skill_sources: {
+        academic_research: {
+            description: "Academic research skills maintained by this project.",
+            source: "VincenzoImp/academic-research-skills",
+            skills: [
+                "academic-mcp-tooling",
+                "adversarial-peer-review",
+                "artifact-open-science",
+                "citation-bibliography-tooling",
+                "citation-claim-audit",
+                "cs-methodology-evaluation",
+                "cs-venue-strategy",
+                "document-conversion",
+                "ethics-data-governance",
+                "experiment-logbook",
+                "paper-writing-review",
+                "rebuttal-revision-strategy",
+                "repo-migration",
+                "research-data-analysis",
+                "research-design-positioning",
+                "research-project-maintenance",
+                "research-project-router",
+                "research-repo-reproduction",
+                "research-ui-prototyping",
+                "skill-evaluation",
+                "sota-literature-review",
+                "source-ingestion",
+                "systematic-review-prisma"
+            ]
+        },
+        superpowers: {
+            description: "General agent engineering skills from Superpowers.",
+            source: "obra/superpowers",
+            skills: [
+                "brainstorming",
+                "dispatching-parallel-agents",
+                "executing-plans",
+                "finishing-a-development-branch",
+                "receiving-code-review",
+                "requesting-code-review",
+                "subagent-driven-development",
+                "systematic-debugging",
+                "test-driven-development",
+                "using-git-worktrees",
+                "using-superpowers",
+                "verification-before-completion",
+                "writing-plans",
+                "writing-skills"
+            ]
+        },
+        anthropics: {
+            description: "Document, frontend, testing, MCP, and skill-authoring helpers.",
+            source: "anthropics/skills",
+            skills: [
+                "docx",
+                "frontend-design",
+                "mcp-builder",
+                "pdf",
+                "pptx",
+                "skill-creator",
+                "webapp-testing",
+                "xlsx"
+            ]
+        },
+        docling: {
+            description: "Document conversion helper from the Beagle collection.",
+            source: "existential-birds/beagle",
+            skills: ["docling"]
+        }
+    },
     presets: {
         minimal: {
             description: "Academic research skills only, no MCP records.",
@@ -110,7 +180,7 @@ export const AGENT_STACK = {
             recommended_env: [],
             local_service: "",
             smoke_test: "Search works by title or DOI and confirm stable OpenAlex IDs.",
-            risks: "The selected local server requires OPENALEX_API_KEY. OpenAlex keys are free for normal academic use with daily free usage; smoke-test coverage and cost headers before high-volume work."
+            risks: "The selected local server requires OPENALEX_API_KEY. OpenAlex keys are free and include a free daily quota; check current credit limits, smoke-test coverage, and inspect cost headers before high-volume work."
         },
         crossref: {
             readiness: "manual",

package/package.json

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

package/template/.env.example

@@ -0,0 +1,23 @@
+# Academic research MCP environment example.
+# Copy to .env.local, your shell profile, or your MCP client secret store.
+# Do not commit filled secrets. Empty values mean optional or user-supplied.
+
+# semantic-scholar environment
+SEMANTIC_SCHOLAR_API_KEY=
+
+# openalex environment
+OPENALEX_API_KEY=
+
+# pubmed environment
+NCBI_API_KEY=
+NCBI_ADMIN_EMAIL=
+MCP_TRANSPORT_TYPE=stdio
+MCP_LOG_LEVEL=warning
+
+# overleaf environment
+OVERLEAF_TOKEN=
+PROJECT_ID=
+
+# paper-search environment
+PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=
+PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=

package/template/AGENTS.md

@@ -11,6 +11,8 @@ scholarly record.
 - Tie claims to sources, datasets, experiment records, or decision records.
 - Update durable records when project knowledge changes.
 - Keep large data, generated caches, credentials, and private review material out of git.
+- Keep `.env.example` as a public reference only; never commit filled `.env`,
+  `.env.local`, API keys, tokens, cookies, or browser sessions.
 
 ## First Read
 

package/template/README.md

@@ -57,11 +57,13 @@ 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 install source-ingestion sota-literature-review
 npx academic-research skills list
 npx academic-research skills status
 npx academic-research setup
 npx academic-research mcp list
 npx academic-research mcp env openalex semantic-scholar zotero
+npx academic-research mcp env --dotenv --all > .env.example
 npx academic-research mcp enable arxiv dblp
 npx academic-research mcp commands arxiv
 npx academic-research mcp install arxiv
@@ -77,6 +79,11 @@ 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.
 
+`.env.example` is the committed MCP environment reference. Copy it to
+`.env.local`, your shell profile, or your MCP client secret store when secrets
+are needed. Filled `.env` files are ignored by git. `mcp doctor` checks the
+current process environment; it does not automatically load `.env.local`.
+
 `setup` prints the current project capability state, installed skill counts,
 enabled MCP records, and the next onboarding commands without changing files.
 `mcp smoke` performs a non-launching MCP readiness check: it reports required

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

@@ -0,0 +1,43 @@
+# MCP Client Setup
+
+Generated MCP snippets live in `docs/agent/generated/`. They are client-ready
+configuration fragments, not live tools by themselves. The active MCP client
+must load the generated snippet and must receive any required environment
+variables from the shell, a local untracked env file, or the client's secret
+store.
+
+## Files
+
+- `docs/agent/generated/mcp.json`: generic/default generated snippet.
+- `docs/agent/generated/<agent>-mcp.json`: generated when a specific agent is
+  selected.
+- `.env.example`: committed reference for MCP environment variables.
+- `.env.local`: recommended local untracked file for filled secrets.
+
+## Environment
+
+Regenerate the committed reference from the current MCP catalog with:
+
+```bash
+npx academic-research mcp env --dotenv --all > .env.example
+```
+
+Create a private local file when needed:
+
+```bash
+cp .env.example .env.local
+```
+
+Do not commit filled `.env`, `.env.local`, tokens, cookies, or browser sessions.
+`mcp doctor` checks the current process environment; it does not automatically
+load `.env.local`.
+
+## Workflow
+
+1. Enable only the MCP servers needed for the current research task.
+2. Inspect prerequisites with `npx academic-research mcp env <server>`.
+3. Put required secrets in the MCP client secret store, shell, or `.env.local`.
+4. Run `npx academic-research mcp smoke` before wiring the client.
+5. Load the generated snippet in the MCP client.
+6. Treat MCP output as retrieval metadata until it is ingested into repository
+   source records.

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

@@ -2,3 +2,7 @@
 
 Record active MCP servers, install commands, auth requirements, smoke tests,
 and known risks here.
+
+Use `.env.example` as the committed environment reference. Put filled values in
+`.env.local`, the shell, or the MCP client secret store. Regenerate the example
+with `npx academic-research mcp env --dotenv --all > .env.example`.

package/template/package.json

@@ -11,10 +11,11 @@
     "mcp:list": "academic-research mcp list",
     "mcp:commands": "academic-research mcp commands",
     "mcp:env": "academic-research mcp env",
+    "mcp:dotenv": "academic-research mcp env --dotenv --all",
     "mcp:smoke": "academic-research mcp smoke",
     "mcp:doctor": "academic-research mcp doctor"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.7"
+    "create-academic-research": "0.1.9"
   }
 }