create-academic-research 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Release notes are generated from merged commits and pull requests in GitHub
+Releases:
+
+https://github.com/VincenzoImp/create-academic-research/releases
+
+This file intentionally does not duplicate release entries, so the repository
+has one authoritative changelog source.

package/README.md

@@ -104,12 +104,15 @@ 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 env --write .env.example --all
 npx academic-research mcp enable arxiv dblp
 npx academic-research mcp disable arxiv
 npx academic-research mcp install arxiv
 npx academic-research mcp uninstall arxiv
-npx academic-research mcp smoke
-npx academic-research mcp doctor
+npx academic-research mcp smoke --env-file .env.local
+npx academic-research mcp doctor --env-file .env.local
+npx academic-research mcp probe arxiv --timeout-ms 5000
 ```
 
 ## Command Model
@@ -137,13 +140,14 @@ 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 print dotenv content or `--write .env.example --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. |
 | `mcp uninstall` | Run the external uninstall command when one exists. |
 | `mcp smoke` | Print non-launching readiness diagnostics for enabled or selected MCP servers. |
-| `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. |
+| `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. Pass `--env-file .env.local` to read explicit local secrets. |
+| `mcp probe` | Opt-in runtime check that starts selected MCP servers and performs a stdio JSON-RPC handshake. |
 
 ## Companion Skills
 
@@ -185,11 +189,18 @@ 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. Regenerate the example with
+`mcp env --write .env.example --all`. `mcp doctor`, `mcp smoke`, and
+`mcp probe` check the current process environment unless you explicitly pass
+`--env-file .env.local`.
 
 Generated MCP snippets are project documentation and client-ready config, not
 live tools by themselves. Your MCP client must load the generated snippet, and
@@ -199,6 +210,8 @@ tool install; it deliberately does not launch stdio MCP servers.
 Use `mcp smoke` for a non-launching readiness pass before wiring a client: it
 checks required env vars, manual/local-service status, and whether runtime
 commands are visible on `PATH`.
+Use `mcp probe` only when you intentionally want to start selected MCP server
+processes and verify a real stdio JSON-RPC handshake.
 
 ## Validate This Package
 
@@ -216,8 +229,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.8 -m "v0.1.8"
-git push origin main v0.1.8
+git tag -a v0.1.10 -m "v0.1.10"
+git push origin main v0.1.10
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/capabilities.d.ts

@@ -1,6 +1,11 @@
 import { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS } from "./agents.js";
 import { type Runner } from "./runner.js";
 import { type McpToolCommandKey } from "./stack.js";
+import { formatMcpDotenv, listMcpEnvironmentEntries } from "./mcp-env.js";
+import { type McpProbeResult as ProbeResult } from "./mcp-probe.js";
+export { formatMcpDotenv, listMcpEnvironmentEntries };
+export { mergeMcpEnvironment, readMcpEnvironmentFile, type McpEnvironmentEntry } from "./mcp-env.js";
+export { type McpProbeResult, type McpProbeServerResult, type McpProbeStatus } from "./mcp-probe.js";
 export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export interface CapabilityState {
     agent: string;
@@ -30,11 +35,20 @@ export interface McpDoctorResult {
     warnings: string[];
     enabled: string[];
 }
+export interface McpDoctorOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export interface McpProbeOptions {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    clientVersion?: 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[][]>;
@@ -53,5 +67,6 @@ export declare function mcpToolCommands(servers: string[], key?: McpToolCommandK
 export declare function mcpToolCommandTexts(servers: string[], key?: McpToolCommandKey): 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>;
+export declare function doctorMcpServers(root: string, options?: McpDoctorOptions): Promise<McpDoctorResult>;
+export declare function probeMcpServers(root: string, servers: string[], options?: McpProbeOptions): Promise<ProbeResult>;
 export declare function assertKnownMcpServers(servers: string[]): void;

package/dist/src/capabilities.js

@@ -4,6 +4,10 @@ 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";
+import { formatMcpDotenv, listMcpEnvironmentEntries } from "./mcp-env.js";
+import { probeMcpServerList } from "./mcp-probe.js";
+export { formatMcpDotenv, listMcpEnvironmentEntries };
+export { mergeMcpEnvironment, readMcpEnvironmentFile } from "./mcp-env.js";
 export { DEFAULT_AGENT, SUPPORTED_SKILL_AGENT_TARGETS };
 export async function readCapabilities(root) {
     try {
@@ -29,6 +33,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);
@@ -222,9 +229,10 @@ export async function uninstallMcpTools(root, servers, runner = defaultRunner) {
     }
     return { ok: true, count: commands.length };
 }
-export async function doctorMcpServers(root) {
+export async function doctorMcpServers(root, options = {}) {
     const errors = [];
     const warnings = [];
+    const env = options.env ?? process.env;
     let state;
     try {
         state = await readCapabilitiesFile(root);
@@ -266,12 +274,12 @@ export async function doctorMcpServers(root) {
         if (!server)
             continue;
         for (const envName of server.required_env) {
-            if (!process.env[envName]) {
+            if (!envHasValue(env, envName)) {
                 errors.push(`${name}: missing required environment variable: ${envName}`);
             }
         }
         for (const envName of server.recommended_env) {
-            if (!process.env[envName]) {
+            if (!envHasValue(env, envName)) {
                 warnings.push(`${name}: recommended environment variable not set: ${envName}`);
             }
         }
@@ -288,6 +296,12 @@ export async function doctorMcpServers(root) {
     }
     return { ok: errors.length === 0, errors, warnings, enabled };
 }
+export async function probeMcpServers(root, servers, options = {}) {
+    const selected = servers.length > 0 ? servers : (await readCapabilities(root)).mcp_servers ?? [];
+    const env = options.env ?? process.env;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    return probeMcpServerList(root, selected, env, timeoutMs, options.clientVersion);
+}
 async function writeMcpSnippet(root, state) {
     const servers = {};
     for (const name of state.mcp_servers ?? []) {
@@ -369,7 +383,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.", "- Print a dotenv-style reference with `npx academic-research mcp env --dotenv --all`.", "- Regenerate a dotenv-style reference with `npx academic-research mcp env --write .env.example --all`.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- 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.", "- Run `npx academic-research mcp probe <server>` only when you intentionally want to start selected MCP server processes.", "");
     await mkdir(join(root, "docs/agent"), { recursive: true });
     await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
 }
@@ -382,6 +396,9 @@ async function appendCapabilityLog(root, state) {
 function dedupe(values) {
     return [...new Set(values)];
 }
+function envHasValue(env, name) {
+    return typeof env[name] === "string" && env[name] !== "";
+}
 function renderSkillCommand(command, agent) {
     const normalized = assertKnownAgentTarget(agent);
     const agentFlag = normalized === AUTO_AGENT ? "" : `--agent '${normalized}'`;

package/dist/src/cli.js

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } 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, installSkillIds, installSkills, listInstalledSkills, mcpToolCommandTexts, readCapabilities, removeSkills, uninstallMcpTools, updateSkills } from "./capabilities.js";
+import { assertKnownMcpServers, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, 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";
@@ -21,7 +21,7 @@ const CREATE_FLAGS = flagSchema([
 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", "env-file", "write", "timeout-ms"]);
 export async function main(argv = process.argv.slice(2), mode = "create") {
     try {
         if (mode === "create")
@@ -171,7 +171,9 @@ 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 --write .env.example --all");
     console.log("academic-research mcp smoke");
+    console.log("academic-research mcp probe arxiv");
     console.log("academic-research doctor");
     return project.ok ? 0 : 1;
 }
@@ -339,12 +341,34 @@ 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", "write"]);
         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")
+        };
+        const writePath = flagString(parsed.flags, "write");
+        if (writePath) {
+            const outputPath = resolve(root, writePath);
+            writeFileSync(outputPath, formatMcpDotenv(selected, filters), "utf8");
+            console.log(`Wrote MCP dotenv environment reference: ${outputPath}`);
+            return 0;
+        }
+        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") {
@@ -378,15 +402,16 @@ async function mcpCommand(argv) {
         return 0;
     }
     if (subcommand === "smoke") {
-        assertOnlyOptions(parsed.flags, "mcp smoke", ["root"]);
+        assertOnlyOptions(parsed.flags, "mcp smoke", ["root", "env-file"]);
         const root = resolve(flagString(parsed.flags, "root") ?? ".");
+        const env = await mcpCommandEnvironment(root, parsed.flags);
         const state = await readCapabilities(root);
         const explicitSelection = parsed.positionals.length > 0;
         const selected = explicitSelection ? parsed.positionals : state.mcp_servers;
         assertKnownMcpServers(selected);
-        const failed = printMcpSmokeDiagnostics(selected);
+        const failed = printMcpSmokeDiagnostics(selected, env);
         if (!explicitSelection) {
-            const result = await doctorMcpServers(root);
+            const result = await doctorMcpServers(root, { env });
             for (const error of result.errors)
                 console.error(`ERROR: ${error}`);
             for (const warning of result.warnings)
@@ -396,10 +421,11 @@ async function mcpCommand(argv) {
         return failed ? 1 : 0;
     }
     if (subcommand === "doctor") {
-        assertOnlyOptions(parsed.flags, "mcp doctor", ["root"]);
+        assertOnlyOptions(parsed.flags, "mcp doctor", ["root", "env-file"]);
         const root = resolve(flagString(parsed.flags, "root") ?? ".");
         assertNoArguments(parsed.positionals, "mcp doctor");
-        const result = await doctorMcpServers(root);
+        const env = await mcpCommandEnvironment(root, parsed.flags);
+        const result = await doctorMcpServers(root, { env });
         for (const error of result.errors)
             console.error(`ERROR: ${error}`);
         for (const warning of result.warnings)
@@ -408,6 +434,23 @@ async function mcpCommand(argv) {
             console.log(`OK: ${result.enabled.length} MCP server(s) enabled.`);
         return result.ok ? 0 : 1;
     }
+    if (subcommand === "probe") {
+        assertOnlyOptions(parsed.flags, "mcp probe", ["root", "all", "env-file", "timeout-ms"]);
+        const root = resolve(flagString(parsed.flags, "root") ?? ".");
+        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 timeoutMs = parseTimeoutMs(flagString(parsed.flags, "timeout-ms"));
+        const env = await mcpCommandEnvironment(root, parsed.flags);
+        const result = await probeMcpServers(root, selected, { env, timeoutMs, clientVersion: packageVersion });
+        console.log("id\tstatus\tdetail");
+        for (const item of result.results)
+            console.log(`${item.server}\t${item.status}\t${item.detail}`);
+        return result.ok ? 0 : 1;
+    }
     throw new Error(`unknown mcp command: ${subcommand}`);
 }
 function parseFlags(argv, schema) {
@@ -492,6 +535,24 @@ function assertOnlyOptions(flags, command, allowedOptions) {
         throw new Error(`${command} does not accept ${unexpected.map((name) => `--${name}`).join(", ")}`);
     }
 }
+async function mcpCommandEnvironment(root, flags) {
+    const envFile = flagString(flags, "env-file");
+    if (!envFile)
+        return process.env;
+    const fileEnv = await readMcpEnvironmentFile(resolve(root, envFile));
+    return mergeMcpEnvironment(process.env, fileEnv);
+}
+function parseTimeoutMs(value) {
+    if (value === undefined)
+        return 5000;
+    if (!/^[0-9]+$/.test(value))
+        throw new Error(`--timeout-ms must be a positive integer, got: ${value}`);
+    const timeoutMs = Number(value);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 120000) {
+        throw new Error("--timeout-ms must be between 100 and 120000");
+    }
+    return timeoutMs;
+}
 export function formatInteractiveCreateGuide() {
     const presetLines = Object.entries(AGENT_STACK.presets).map(([name, preset]) => `  ${name.padEnd(10)} ${preset.description}`);
     return [
@@ -519,6 +580,9 @@ 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 print a committed env example.",
+        "  Use `academic-research mcp env --write .env.example --all` to regenerate a committed env example.",
+        "  Use `academic-research mcp doctor --env-file .env.local` to check explicit local secrets.",
         ""
     ].join("\n");
 }
@@ -609,22 +673,37 @@ function printSkillsHelp() {
 }
 function printMcpHelp() {
     console.log([
-        "Usage: academic-research mcp <list|enabled|available|commands|env|enable|disable|install|uninstall|smoke|doctor> [servers...]",
+        "Usage: academic-research mcp <list|enabled|available|commands|env|enable|disable|install|uninstall|smoke|doctor|probe> [servers...]",
         "",
         "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 env --write .env.example --all",
+        "  academic-research mcp doctor --env-file .env.local",
+        "  academic-research mcp smoke",
+        "  academic-research mcp probe arxiv --timeout-ms 5000",
+        "",
         "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.",
+        "  --write <path>           Write mcp env dotenv content to a file.",
+        "  --env-file <path>        Read local env values for mcp smoke, doctor, and probe.",
+        "  --timeout-ms <ms>        Per-server probe timeout. Default: 5000.",
+        "  --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"));
 }
-function printMcpSmokeDiagnostics(servers) {
+function printMcpSmokeDiagnostics(servers, env = process.env) {
     let failed = false;
     console.log("id\tstatus\truntime\tcheck");
     for (const name of servers) {
         const server = AGENT_STACK.mcp_servers[name];
-        const missingRequired = server.required_env.filter((envName) => !process.env[envName]);
+        const missingRequired = server.required_env.filter((envName) => !env[envName]);
         if (missingRequired.length > 0)
             failed = true;
         const runtime = server.command ? [server.command, ...server.args].join(" ") : "manual setup";
@@ -632,7 +711,7 @@ function printMcpSmokeDiagnostics(servers) {
         if (missingRequired.length > 0) {
             status = `missing-required-env:${missingRequired.join(",")}`;
         }
-        else if (server.command && commandExists(server.command)) {
+        else if (server.command && commandExists(server.command, env)) {
             status = "runtime-found";
         }
         else if (server.command) {
@@ -645,42 +724,47 @@ 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}`);
-            wroteLine = true;
-        }
-        for (const envName of server.recommended_env) {
-            console.log(`${name}\trecommended\t${envName}`);
+        for (const entry of entries) {
+            console.log(`${name}\t${entry.kind}\t${entry.name}${entry.value ? `=${entry.value}` : ""}`);
             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-`);
     }
 }
-function commandExists(command) {
+function commandExists(command, env = process.env) {
     if (!command)
         return false;
     if (command.includes("/") || command.includes("\\"))
         return existsSync(command);
-    const pathValue = process.env.PATH ?? "";
+    const pathValue = env.PATH ?? "";
     const extensions = process.platform === "win32"
-        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+        ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
         : [""];
     for (const directory of pathValue.split(delimiter).filter(Boolean)) {
         for (const extension of extensions) {

package/dist/src/mcp-env.d.ts

@@ -0,0 +1,16 @@
+export interface McpEnvironmentEntry {
+    server: string;
+    kind: "required" | "recommended" | "default";
+    name: string;
+    value: 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 readMcpEnvironmentFile(path: string): Promise<Record<string, string>>;
+export declare function mergeMcpEnvironment(baseEnv?: NodeJS.ProcessEnv, fileEnv?: Record<string, string>): NodeJS.ProcessEnv;

package/dist/src/mcp-env.js

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import { AGENT_STACK } from "./stack.js";
+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 readMcpEnvironmentFile(path) {
+    return parseDotenv(await readFile(path, "utf8"), path);
+}
+export function mergeMcpEnvironment(baseEnv = process.env, fileEnv = {}) {
+    const merged = { ...baseEnv };
+    for (const [name, value] of Object.entries(fileEnv)) {
+        if (value || !(name in merged))
+            merged[name] = value;
+    }
+    return merged;
+}
+function assertKnownMcpServers(servers) {
+    const unknown = servers.filter((server) => !AGENT_STACK.mcp_servers[server]);
+    if (unknown.length > 0) {
+        throw new Error(`unknown MCP server: ${unknown.join(", ")}`);
+    }
+}
+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 parseDotenv(raw, path) {
+    const env = {};
+    const lines = raw.split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        let text = line.trim();
+        if (!text || text.startsWith("#"))
+            continue;
+        if (text.startsWith("export "))
+            text = text.slice("export ".length).trimStart();
+        const equals = text.indexOf("=");
+        if (equals === -1) {
+            throw new Error(`${path}:${index + 1}: expected KEY=value`);
+        }
+        const key = text.slice(0, equals).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new Error(`${path}:${index + 1}: invalid environment variable name: ${key}`);
+        }
+        env[key] = parseDotenvValue(text.slice(equals + 1).trim(), path, index + 1);
+    }
+    return env;
+}
+function parseDotenvValue(value, path, line) {
+    if (!value)
+        return "";
+    const quote = value[0];
+    if (quote === "'" || quote === '"') {
+        if (!value.endsWith(quote) || value.length === 1) {
+            throw new Error(`${path}:${line}: unterminated quoted value`);
+        }
+        const unquoted = value.slice(1, -1);
+        if (quote === "'")
+            return unquoted;
+        return unquoted
+            .replaceAll("\\n", "\n")
+            .replaceAll("\\r", "\r")
+            .replaceAll("\\t", "\t")
+            .replaceAll('\\"', '"')
+            .replaceAll("\\\\", "\\");
+    }
+    return value.replace(/\s+#.*$/, "").trimEnd();
+}

package/dist/src/mcp-probe.d.ts

@@ -0,0 +1,11 @@
+export type McpProbeStatus = "ok" | "manual" | "missing-env" | "runtime-missing" | "startup-failed" | "protocol-error" | "timeout";
+export interface McpProbeServerResult {
+    server: string;
+    status: McpProbeStatus;
+    detail: string;
+}
+export interface McpProbeResult {
+    ok: boolean;
+    results: McpProbeServerResult[];
+}
+export declare function probeMcpServerList(root: string, servers: string[], env: NodeJS.ProcessEnv, timeoutMs: number, clientVersion?: string): Promise<McpProbeResult>;

package/dist/src/mcp-probe.js

@@ -0,0 +1,177 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { AGENT_STACK } from "./stack.js";
+export async function probeMcpServerList(root, servers, env, timeoutMs, clientVersion = "unknown") {
+    assertKnownMcpServers(servers);
+    const results = [];
+    for (const name of servers) {
+        const server = AGENT_STACK.mcp_servers[name];
+        const missingRequired = server.required_env.filter((envName) => !envHasValue(env, envName));
+        if (missingRequired.length > 0) {
+            results.push({ server: name, status: "missing-env", detail: missingRequired.join(",") });
+            continue;
+        }
+        if (!server.command) {
+            results.push({ server: name, status: "manual", detail: server.local_service || "manual setup only" });
+            continue;
+        }
+        if (!commandExists(server.command, env)) {
+            results.push({ server: name, status: "runtime-missing", detail: server.command });
+            continue;
+        }
+        results.push(await probeMcpServerProcess(root, name, server.command, server.args, { ...server.env, ...env }, timeoutMs, clientVersion));
+    }
+    return { ok: results.every((result) => result.status === "ok"), results };
+}
+function assertKnownMcpServers(servers) {
+    const unknown = servers.filter((server) => !AGENT_STACK.mcp_servers[server]);
+    if (unknown.length > 0) {
+        throw new Error(`unknown MCP server: ${unknown.join(", ")}`);
+    }
+}
+function envHasValue(env, name) {
+    return typeof env[name] === "string" && env[name] !== "";
+}
+function commandExists(command, env = process.env) {
+    if (!command)
+        return false;
+    if (command.includes("/") || command.includes("\\"))
+        return existsSync(command);
+    const pathValue = env.PATH ?? "";
+    const extensions = process.platform === "win32"
+        ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+        : [""];
+    for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const hasExtension = extension && command.toLowerCase().endsWith(extension.toLowerCase());
+            const candidate = join(directory, hasExtension ? command : `${command}${extension}`);
+            if (existsSync(candidate))
+                return true;
+        }
+    }
+    return false;
+}
+async function probeMcpServerProcess(root, server, command, args, env, timeoutMs, clientVersion) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let stderr = "";
+        let stdout = Buffer.alloc(0);
+        const child = spawn(command, args, {
+            cwd: root,
+            env,
+            stdio: ["pipe", "pipe", "pipe"]
+        });
+        const timer = setTimeout(() => finish("timeout", `${timeoutMs}ms`), timeoutMs);
+        function finish(status, detail) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.kill();
+            resolve({ server, status, detail: detail || "-" });
+        }
+        child.on("error", (error) => {
+            finish(error.code === "ENOENT" ? "runtime-missing" : "startup-failed", error.message);
+        });
+        child.on("close", (code) => {
+            if (!settled)
+                finish("startup-failed", stderr.trim() || `process exited with code ${code ?? "unknown"}`);
+        });
+        child.stdin.on("error", (error) => {
+            finish("startup-failed", error.message);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.stdout.on("data", (chunk) => {
+            stdout = Buffer.concat([stdout, chunk]);
+            try {
+                for (const message of drainMcpMessages()) {
+                    handleMcpProbeMessage(message);
+                }
+            }
+            catch (error) {
+                finish("protocol-error", error instanceof Error ? error.message : String(error));
+            }
+        });
+        try {
+            child.stdin.write(encodeMcpMessage({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: {},
+                    clientInfo: { name: "academic-research-cli", version: clientVersion }
+                }
+            }));
+        }
+        catch (error) {
+            finish("startup-failed", error instanceof Error ? error.message : String(error));
+        }
+        function handleMcpProbeMessage(message) {
+            if (message.id === 1) {
+                if (message.error) {
+                    finish("protocol-error", formatJsonRpcError(message.error));
+                    return;
+                }
+                child.stdin.write(encodeMcpMessage({
+                    jsonrpc: "2.0",
+                    method: "notifications/initialized",
+                    params: {}
+                }));
+                child.stdin.write(encodeMcpMessage({
+                    jsonrpc: "2.0",
+                    id: 2,
+                    method: "tools/list",
+                    params: {}
+                }));
+            }
+            else if (message.id === 2) {
+                if (message.error) {
+                    finish("protocol-error", formatJsonRpcError(message.error));
+                    return;
+                }
+                const result = typeof message.result === "object" && message.result !== null
+                    ? message.result
+                    : {};
+                const toolCount = Array.isArray(result.tools) ? result.tools.length : "unknown";
+                finish("ok", `tools=${toolCount}`);
+            }
+        }
+        function drainMcpMessages() {
+            const messages = [];
+            while (true) {
+                const separator = stdout.indexOf("\r\n\r\n");
+                if (separator === -1)
+                    return messages;
+                const header = stdout.slice(0, separator).toString("utf8");
+                const match = /Content-Length:\s*(\d+)/i.exec(header);
+                if (!match)
+                    throw new Error("missing Content-Length header");
+                const length = Number(match[1]);
+                const bodyStart = separator + 4;
+                const bodyEnd = bodyStart + length;
+                if (stdout.length < bodyEnd)
+                    return messages;
+                const body = stdout.slice(bodyStart, bodyEnd).toString("utf8");
+                stdout = stdout.slice(bodyEnd);
+                const parsed = JSON.parse(body);
+                if (typeof parsed !== "object" || parsed === null)
+                    throw new Error("MCP response is not an object");
+                messages.push(parsed);
+            }
+        }
+    });
+}
+function encodeMcpMessage(message) {
+    const body = JSON.stringify(message);
+    return `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+}
+function formatJsonRpcError(error) {
+    if (typeof error === "object" && error !== null && "message" in error) {
+        return String(error.message);
+    }
+    return JSON.stringify(error);
+}

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);
@@ -121,7 +122,7 @@ export async function renameProject(root, options) {
         profile: config.project.profile,
         previousPackage
     });
-    await writeGeneratedPackageJson(target, { slug });
+    await writeGeneratedPackageJson(target, { slug, preserveExistingSpec: true });
     return { root: target, title, slug, packageName };
 }
 export async function doctorProject(root) {
@@ -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",
@@ -210,11 +213,13 @@ async function personalizeProject(root, { title, slug, packageName, profile, pre
         }
     }
 }
-async function writeGeneratedPackageJson(root, { slug }) {
+async function writeGeneratedPackageJson(root, { slug, preserveExistingSpec = false }) {
     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.8";
+    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ??
+        (preserveExistingSpec ? existingSpec : undefined) ??
+        await currentPackageVersion();
     data.name = slug;
     data.devDependencies = {
         ...(data.devDependencies ?? {}),
@@ -222,6 +227,13 @@ async function writeGeneratedPackageJson(root, { slug }) {
     };
     await writeJson(path, data);
 }
+async function currentPackageVersion() {
+    const packageJson = await readJson(join(packageRoot, "package.json"));
+    if (!packageJson.version) {
+        throw new Error("package.json missing version");
+    }
+    return packageJson.version;
+}
 async function writeAgentStack(root) {
     await writeFile(join(root, "configs/agent-stack.yaml"), YAML.stringify(AGENT_STACK), "utf8");
 }

package/dist/src/stack.js

@@ -180,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.8",
+  "version": "0.1.10",
   "description": "Create and manage agent-ready academic research repositories.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "dist",
     "template",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md"
   ],

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

@@ -61,13 +61,15 @@ 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 env --write .env.example --all
 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 smoke
-npx academic-research mcp doctor
+npx academic-research mcp smoke --env-file .env.local
+npx academic-research mcp doctor --env-file .env.local
+npx academic-research mcp probe arxiv --timeout-ms 5000
 ```
 
 `skills list` reports installed project-local skills. `skills presets` reports
@@ -78,11 +80,18 @@ 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. Regenerate it with
+`mcp env --write .env.example --all`. 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
+unless you explicitly pass `--env-file .env.local`.
+
 `setup` prints the current project capability state, installed skill counts,
 enabled MCP records, and the next onboarding commands without changing files.
 `mcp smoke` performs a non-launching MCP readiness check: it reports required
 env vars, local/manual setup, and whether client runtime commands such as `uvx`
-or `npx` are available.
+or `npx` are available. `mcp probe` is opt-in and starts selected MCP servers
+for a real stdio JSON-RPC handshake.
 
 `default` installs the companion academic research skill package and keeps the
 MCP records focused on low-friction arXiv discovery. `literature` and `full`
@@ -90,3 +99,5 @@ 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`.
+
+See `docs/getting-started.md` for the recommended first session workflow.

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

@@ -0,0 +1,67 @@
+# 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 --write .env.example --all
+```
+
+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`, `mcp smoke`, and `mcp probe` check the current process
+environment unless you explicitly pass `--env-file .env.local`.
+
+```bash
+npx academic-research mcp doctor --env-file .env.local
+npx academic-research mcp smoke --env-file .env.local
+npx academic-research mcp probe arxiv --timeout-ms 5000
+```
+
+## Client Notes
+
+For Codex, Claude Code, Cursor, or another MCP client, load the generated
+snippet that matches the active agent target:
+
+- `docs/agent/generated/mcp.json` for the universal/default target.
+- `docs/agent/generated/codex-mcp.json` when the project was created with
+  `--agent codex`.
+- `docs/agent/generated/claude-code-mcp.json` when using Claude Code.
+- `docs/agent/generated/cursor-mcp.json` when using Cursor.
+
+The generated snippet is project documentation until the client loads it. If a
+client has its own secret store, prefer that store for API keys and tokens. If
+the client inherits shell environment variables, start it from a shell where the
+required variables are already exported.
+
+## 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 --env-file .env.local`.
+5. Run `npx academic-research mcp probe <server>` only when you want to start
+   the server and verify a real stdio handshake.
+6. Load the generated snippet in the MCP client.
+7. Treat MCP output as retrieval metadata until it is ingested into repository
+   source records.

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

@@ -2,3 +2,12 @@
 
 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 --write .env.example --all`.
+
+Use `npx academic-research mcp doctor --env-file .env.local` when you want the
+CLI to read an explicit local env file. Use `npx academic-research mcp probe
+<server>` only when you want to start a selected MCP server and verify a real
+stdio handshake.

package/template/docs/getting-started.md

@@ -0,0 +1,86 @@
+# Getting Started
+
+Use this path for the first working session in a new research repository.
+
+## 1. Check The Repository
+
+```bash
+npm install
+npx academic-research doctor
+npx academic-research setup
+```
+
+`doctor` checks required files and structural contracts. `setup` prints the
+active skill preset, installed skill count, enabled MCP records, and next
+commands without changing files.
+
+## 2. Install Project-Local Skills
+
+Install the default academic research skill package:
+
+```bash
+npx academic-research skills install --preset default
+npx academic-research skills status
+```
+
+Use `enhanced` only when the project also needs complementary development,
+document, frontend, testing, and conversion skills:
+
+```bash
+npx academic-research skills install --preset enhanced
+```
+
+## 3. Prepare MCP Environment
+
+Keep `.env.example` committed and empty of real secrets. Put filled values in
+`.env.local`, your shell, or your MCP client secret store.
+
+```bash
+npx academic-research mcp env --write .env.example --all
+cp .env.example .env.local
+npx academic-research mcp env openalex semantic-scholar zotero
+npx academic-research mcp doctor --env-file .env.local
+```
+
+`mcp smoke` is a non-launching readiness check. `mcp probe` is opt-in and starts
+MCP processes for a real stdio handshake.
+
+```bash
+npx academic-research mcp smoke --env-file .env.local
+npx academic-research mcp probe arxiv --timeout-ms 5000
+```
+
+## 4. Start Source Work
+
+Put source originals and metadata in the source layer before synthesis.
+
+```text
+sources/pdfs/       native PDFs
+sources/markdown/   derived Markdown
+sources/metadata/   downloaded metadata or query exports
+sources/bib/        BibTeX and citation audits
+```
+
+Update `sources/source-ledger.csv` whenever a paper, report, dataset, or web
+source becomes evidence for the project.
+
+## 5. Build The First SOTA Pass
+
+Use `sota/search-strategy.md` to record search terms, databases, dates, and
+inclusion criteria. Put screened sources in `sota/literature-matrix.csv`, then
+summarize stable conclusions in `sota/synthesis.md`.
+
+Do not treat MCP output as final evidence until the relevant source has been
+ingested, deduplicated, and tied to a source record.
+
+## 6. Keep Durable Memory Current
+
+Update the wiki when project knowledge changes:
+
+- `wiki/log.md`: chronological actions and decisions.
+- `wiki/index.md`: navigation index.
+- `wiki/synthesis.md`: current project-level interpretation.
+- `wiki/open_questions.md`: unresolved questions.
+- `wiki/contradictions.md`: conflicting sources, claims, or runs.
+
+Prefer small, source-linked updates over long ungrounded summaries.

package/template/package.json

@@ -11,10 +11,12 @@
     "mcp:list": "academic-research mcp list",
     "mcp:commands": "academic-research mcp commands",
     "mcp:env": "academic-research mcp env",
+    "mcp:dotenv": "academic-research mcp env --write .env.example --all",
     "mcp:smoke": "academic-research mcp smoke",
-    "mcp:doctor": "academic-research mcp doctor"
+    "mcp:doctor": "academic-research mcp doctor",
+    "mcp:probe": "academic-research mcp probe"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.8"
+    "create-academic-research": "0.1.10"
   }
 }