create-academic-research 0.1.12 → 0.1.14

package/README.md

@@ -55,7 +55,7 @@ The generated repository is agent-neutral. By default the wizard records
 `agent: universal`, installs one shared project-local `.agents/skills` copy,
 and writes generic MCP snippets. Use `--agent <id>` only when you want to force
 a specific target recognized by the `skills` CLI. Run
-`npx academic-research agents list` inside a generated project to see every
+`npm run agents:list` inside a generated project to see every
 supported target and alias.
 
 ## When To Use It
@@ -113,37 +113,48 @@ npx create-academic-research@latest my-project --yes --no-install-skills
 Inside a generated project:
 
 ```bash
-npx academic-research doctor
-npx academic-research setup
-npx academic-research rename --title "New Title" --slug new-title --package new_title
-npx academic-research agents list
-npx academic-research skills presets
-npx academic-research skills install --preset default
-npx academic-research skills install --preset enhanced
-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
-npx academic-research skills uninstall source-ingestion
-npx academic-research skills update
-npx academic-research mcp list
-npx academic-research mcp enabled
-npx academic-research mcp available
-npx academic-research mcp commands arxiv
-npx academic-research mcp env openalex semantic-scholar zotero
-npx academic-research mcp 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 --env-file .env.local
-npx academic-research mcp doctor --env-file .env.local
-npx academic-research mcp probe arxiv --timeout-ms 5000
+npm run doctor
+npm run update
+npm run setup
+npm run rename -- --title "New Title" --slug new-title --package new_title
+npm run agents:list
+npm run skills:presets
+npm run skills:install
+npm run skills:install -- --preset enhanced
+npm run skills:install -- source-ingestion sota-literature-review
+npm run skills:list
+npm run skills:status
+npm run skills:remove -- source-ingestion
+npm run skills:uninstall -- source-ingestion
+npm run skills:update
+npm run mcp:list
+npm run mcp:enabled
+npm run mcp:available
+npm run mcp:commands -- arxiv
+npm run mcp:env -- openalex semantic-scholar zotero
+npm run mcp:env -- --dotenv --all > .env.example
+npm run mcp:dotenv
+npm run mcp:enable -- arxiv dblp
+npm run mcp:disable -- arxiv
+npm run mcp:install -- arxiv
+npm run mcp:uninstall -- arxiv
+npm run mcp:smoke -- --env-file .env.local
+npm run mcp:doctor -- --env-file .env.local
+npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
+For direct one-off invocation without the generated package scripts, use
+`npx --yes --package create-academic-research@latest academic-research <command>`.
+
 ## Command Model
 
+`academic-research update` is a dry-run by default. It reports managed project
+files that would change and writes them only with `--apply`.
+
+`academic-research init` initializes an existing repository without overwriting
+existing files. It adds the research contract, merges lifecycle package scripts,
+and preserves existing README, `.gitignore`, and custom package scripts.
+
 `academic-research setup` is a non-destructive onboarding status command. It
 prints the active preset, agent, skill counts, enabled MCP records, and next
 commands without changing files.
@@ -189,7 +200,7 @@ Those skills are portable `SKILL.md` instructions, but they require an
 agent/runtime that can load skills or include the relevant instructions in
 context. They are not automatic capabilities of every raw model API.
 Use `--agent <id>` for explicit setup with any id from
-`academic-research agents list`. The shorthand `--agent claude` is normalized
+`npm run agents:list`. The shorthand `--agent claude` is normalized
 to the supported `claude-code` target.
 Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
 it to every agent it detects on the machine.
@@ -208,9 +219,9 @@ Preset intent:
 MCP defaults are intentionally conservative. Semantic Scholar, OpenAlex,
 Zotero, Overleaf, Crossref, and fallback aggregators are useful, but they need
 API keys, local apps, manual setup, or source-policy review. Enable them with
-`npx academic-research mcp enable <server>` after reading
-`docs/agent/mcp-setup.md`, use `npx academic-research mcp env <server>` to see
-runtime prerequisites, then run `npx academic-research mcp doctor`.
+`npm run mcp:enable -- <server>` after reading
+`docs/agent/mcp-setup.md`, use `npm run mcp:env -- <server>` to see runtime
+prerequisites, then run `npm run mcp:doctor`.
 
 The MCP catalog distinguishes local runtime adapters from hosted endpoints and
 manual integrations. arXiv and DBLP are low-friction local `uvx` runtimes.
@@ -225,8 +236,8 @@ 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
+`npm run mcp:dotenv`. `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
@@ -256,8 +267,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.12 -m "v0.1.12"
-git push origin main v0.1.12
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin main vX.Y.Z
 ```
 
 Once the GitHub repository is public, the release workflow validates the tag

package/dist/src/agents.js

@@ -79,7 +79,7 @@ export function assertKnownAgentTarget(agent) {
         throw new Error([
             `unknown agent target: ${value}`,
             `Use ${DEFAULT_AGENT}, ${AUTO_AGENT}, or one supported skills.sh agent id.`,
-            "List targets with: npx -p create-academic-research academic-research agents list",
+            "List targets with: npx --yes --package create-academic-research@latest academic-research agents list",
             `Supported ids: ${specificAgentTargets().join(", ")}`,
             `Aliases: ${formatAgentAliasesInline()}`
         ].join("\n"));

package/dist/src/capabilities.d.ts

@@ -43,6 +43,10 @@ export interface McpProbeOptions {
     timeoutMs?: number;
     clientVersion?: string;
 }
+export interface RenderedMcpSnippet {
+    fileName: string;
+    content: string;
+}
 interface SkillInstallOptions {
     agent?: string;
 }
@@ -69,4 +73,7 @@ export declare function installMcpTools(root: string, servers: string[], runner?
 export declare function uninstallMcpTools(root: string, servers: string[], runner?: Runner): Promise<CapabilityCommandResult>;
 export declare function doctorMcpServers(root: string, options?: McpDoctorOptions): Promise<McpDoctorResult>;
 export declare function probeMcpServers(root: string, servers: string[], options?: McpProbeOptions): Promise<ProbeResult>;
+export declare function renderMcpSnippet(state: CapabilityState): RenderedMcpSnippet;
+export declare function renderCapabilityProfile(state: CapabilityState): string;
+export declare function renderMcpSetup(state: CapabilityState): string;
 export declare function assertKnownMcpServers(servers: string[]): void;

package/dist/src/capabilities.js

@@ -303,6 +303,13 @@ export async function probeMcpServers(root, servers, options = {}) {
     return probeMcpServerList(root, selected, env, timeoutMs, options.clientVersion);
 }
 async function writeMcpSnippet(root, state) {
+    const snippet = renderMcpSnippet(state);
+    const outputDir = join(root, "docs/agent/generated");
+    await mkdir(outputDir, { recursive: true });
+    await removeInactiveMcpSnippets(outputDir, snippet.fileName);
+    await writeFile(join(outputDir, snippet.fileName), snippet.content, "utf8");
+}
+export function renderMcpSnippet(state) {
     const servers = {};
     for (const name of state.mcp_servers ?? []) {
         const server = AGENT_STACK.mcp_servers[name];
@@ -315,13 +322,15 @@ async function writeMcpSnippet(root, state) {
         if (Object.keys(server.env).length > 0)
             servers[name].env = server.env;
     }
-    const outputDir = join(root, "docs/agent/generated");
-    const outputFile = mcpSnippetFileName(state.agent);
-    await mkdir(outputDir, { recursive: true });
-    await removeInactiveMcpSnippets(outputDir, outputFile);
-    await writeFile(join(outputDir, outputFile), `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`, "utf8");
+    return {
+        fileName: mcpSnippetFileName(state.agent),
+        content: `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`
+    };
 }
 async function writeCapabilityProfile(root, state) {
+    await writeFile(join(root, "docs/agent/capability-profile.md"), renderCapabilityProfile(state), "utf8");
+}
+export function renderCapabilityProfile(state) {
     const lines = [
         "# Agent Capability Profile",
         "",
@@ -331,12 +340,12 @@ 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>`",
-        "- Update with: `academic-research skills update`",
+        `- Install with: \`npm run skills:install -- --preset ${state.preset ?? "default"}\``,
+        "- Install selected skills with: `npm run skills:install -- <skill-id> [...]`",
+        "- List installed with: `npm run skills:list`",
+        "- List presets with: `npm run skills:presets`",
+        "- Remove with: `npm run skills:remove -- <skill>`",
+        "- Update with: `npm run skills:update`",
         "",
         "## MCP Servers",
         ""
@@ -352,9 +361,13 @@ async function writeCapabilityProfile(root, state) {
         }
     }
     lines.push("", "## Rules", "", "- Skill installation is project-local by default.", "- Agent target `universal` installs one shared project-local `.agents/skills` copy.", "- MCP enable/disable changes project records; install/uninstall changes external tools.", "- Keep API keys, tokens, cookies, and browser sessions out of git.", "- Cite repository source records, not raw MCP output alone.", "");
-    await writeFile(join(root, "docs/agent/capability-profile.md"), lines.join("\n"), "utf8");
+    return lines.join("\n");
 }
 async function writeMcpSetup(root, state) {
+    await mkdir(join(root, "docs/agent"), { recursive: true });
+    await writeFile(join(root, "docs/agent/mcp-setup.md"), renderMcpSetup(state), "utf8");
+}
+export function renderMcpSetup(state) {
     const enabled = new Set(state.mcp_servers ?? []);
     const lines = [
         "# MCP Setup",
@@ -383,9 +396,8 @@ 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", "", "- 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");
+    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 `npm run mcp:env -- --dotenv --all`.", "- Regenerate a dotenv-style reference with `npm run mcp:dotenv`.", "- 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 `npm run mcp:doctor` after changing MCP records or environment variables.", "- Run `npm run mcp:probe -- <server>` only when you intentionally want to start selected MCP server processes.", "");
+    return lines.join("\n");
 }
 async function appendCapabilityLog(root, state) {
     const logPath = join(root, "wiki/log.md");

package/dist/src/cli.js

@@ -2,7 +2,7 @@ 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, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, removeSkills, uninstallMcpTools, updateSkills } from "./capabilities.js";
-import { createProject, doctorProject, renameProject } from "./project.js";
+import { createProject, doctorProject, initProject, renameProject, updateProject } from "./project.js";
 import { askCreateOptions } from "./prompts.js";
 import { AGENT_STACK, presetMcpServers } from "./stack.js";
 import { formatAgentAliasLines, formatAgentTargetList, formatSupportedAgentTargetLines } from "./agents.js";
@@ -19,6 +19,8 @@ const CREATE_FLAGS = flagSchema([
     "no-install-mcp-tools"
 ], ["title", "slug", "package", "preset", "profile", "agent"]);
 const ROOT_FLAGS = flagSchema(["help"], ["root"]);
+const UPDATE_FLAGS = flagSchema(["help", "dry-run", "apply"], ["root"]);
+const INIT_FLAGS = flagSchema(["help", "install-skills"], ["root", "title", "slug", "package", "preset", "profile", "agent"]);
 const RENAME_FLAGS = flagSchema(["help"], ["root", "title", "slug", "package"]);
 const SKILLS_FLAGS = flagSchema(["help"], ["root", "preset", "agent"]);
 const MCP_FLAGS = flagSchema(["help", "all", "dotenv", "required", "recommended"], ["root", "agent", "env-file", "write", "timeout-ms"]);
@@ -94,7 +96,7 @@ async function createMain(argv) {
         await installMcpTools(result.root, presetMcpServers(answers.preset));
     }
     console.log(`Created ${result.slug} at ${result.root}`);
-    console.log("Next: cd into the project and run `npx academic-research doctor`.");
+    console.log("Next: cd into the project and run `npm run doctor`.");
     return 0;
 }
 async function askInteractiveCreateOptions(defaults, locks) {
@@ -113,6 +115,10 @@ async function lifecycleMain(argv) {
     }
     if (command === "doctor")
         return doctorCommand(argv.slice(1));
+    if (command === "update")
+        return updateCommand(argv.slice(1));
+    if (command === "init")
+        return initCommand(argv.slice(1));
     if (command === "setup")
         return setupCommand(argv.slice(1));
     if (command === "rename")
@@ -136,10 +142,60 @@ async function doctorCommand(argv) {
     const result = await doctorProject(root);
     for (const error of result.errors)
         console.error(`ERROR: ${error}`);
+    for (const warning of result.warnings)
+        console.warn(`WARN: ${warning}`);
     if (result.ok)
         console.log(`OK: ${root}`);
     return result.ok ? 0 : 1;
 }
+async function updateCommand(argv) {
+    const parsed = parseFlags(argv, UPDATE_FLAGS);
+    if (flagBool(parsed.flags, "help")) {
+        printUpdateHelp();
+        return 0;
+    }
+    assertNoArguments(parsed.positionals, "update");
+    if (flagBool(parsed.flags, "dry-run") && flagBool(parsed.flags, "apply")) {
+        throw new Error("update cannot use --dry-run and --apply together");
+    }
+    const root = resolve(flagString(parsed.flags, "root") ?? ".");
+    const apply = flagBool(parsed.flags, "apply");
+    const result = await updateProject(root, { apply });
+    console.log(`${apply ? "UPDATED" : "DRY-RUN"}: ${root}`);
+    if (result.changes.length === 0) {
+        console.log("No managed file changes.");
+    }
+    else {
+        for (const change of result.changes)
+            console.log(`${change.action}\t${change.path}`);
+    }
+    if (!apply && result.changes.length > 0) {
+        console.log("Run `npm run update -- --apply` from a generated project to write these managed changes.");
+    }
+    return 0;
+}
+async function initCommand(argv) {
+    const parsed = parseFlags(argv, INIT_FLAGS);
+    if (flagBool(parsed.flags, "help")) {
+        printInitHelp();
+        return 0;
+    }
+    assertNoArguments(parsed.positionals, "init");
+    const root = resolve(flagString(parsed.flags, "root") ?? ".");
+    const result = await initProject({
+        target: root,
+        title: flagString(parsed.flags, "title"),
+        slug: flagString(parsed.flags, "slug"),
+        packageName: flagString(parsed.flags, "package"),
+        profile: flagString(parsed.flags, "profile") ?? "academic-general",
+        preset: flagString(parsed.flags, "preset") ?? "default",
+        agent: flagString(parsed.flags, "agent") ?? DEFAULT_AGENT,
+        installSkills: flagBool(parsed.flags, "install-skills")
+    });
+    console.log(`Initialized ${result.slug} at ${result.root}`);
+    console.log("Next: run `npm run doctor`.");
+    return 0;
+}
 async function setupCommand(argv) {
     const parsed = parseFlags(argv, ROOT_FLAGS);
     if (flagBool(parsed.flags, "help")) {
@@ -165,16 +221,18 @@ async function setupCommand(argv) {
         for (const error of project.errors)
             console.error(`ERROR: ${error}`);
     }
+    for (const warning of project.warnings)
+        console.warn(`WARN: ${warning}`);
     console.log("");
     console.log("Next Commands");
-    console.log(`academic-research skills install --preset ${state.preset}`);
-    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");
+    console.log(`npm run skills:install -- --preset ${state.preset}`);
+    console.log("npm run skills:status");
+    console.log("npm run mcp:list");
+    console.log("npm run mcp:env");
+    console.log("npm run mcp:dotenv");
+    console.log("npm run mcp:smoke");
+    console.log("npm run mcp:probe -- arxiv");
+    console.log("npm run doctor");
     return project.ok ? 0 : 1;
 }
 async function renameCommand(argv) {
@@ -579,10 +637,10 @@ export function formatInteractiveCreateGuide() {
         "  default enables only low-friction arXiv; credentialed/local services are opt-in.",
         "  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.",
+        "  Use `npm run mcp:env -- <server>` to inspect env vars and local prerequisites.",
+        "  Use `npm run mcp:env -- --dotenv --all` to print a committed env example.",
+        "  Use `npm run mcp:dotenv` to regenerate a committed env example.",
+        "  Use `npm run mcp:doctor -- --env-file .env.local` to check explicit local secrets.",
         ""
     ].join("\n");
 }
@@ -619,7 +677,7 @@ function printMissingTargetHelp() {
 }
 function printLifecycleHelp() {
     console.log([
-        "Usage: academic-research <doctor|setup|rename|agents|skills|mcp>",
+        "Usage: academic-research <doctor|update|init|setup|rename|agents|skills|mcp>",
         "",
         "Manage a generated academic research repository after creation.",
         "",
@@ -628,6 +686,37 @@ function printLifecycleHelp() {
         "  -v, --version            Show package version."
     ].join("\n"));
 }
+function printUpdateHelp() {
+    console.log([
+        "Usage: academic-research update [options]",
+        "",
+        "Preview or apply non-destructive updates to managed project files.",
+        "",
+        "Options:",
+        "  --root <path>            Project root. Default: current directory.",
+        "  --dry-run                Preview managed changes without writing. Default.",
+        "  --apply                  Write managed changes.",
+        "  -h, --help               Show this help."
+    ].join("\n"));
+}
+function printInitHelp() {
+    console.log([
+        "Usage: academic-research init [options]",
+        "",
+        "Initialize an existing repository without overwriting existing files.",
+        "",
+        "Options:",
+        "  --root <path>            Project root. Default: current directory.",
+        "  --title <name>           Project title. Default: title-cased directory name.",
+        "  --slug <name>            Repository/package slug. Default: normalized directory name.",
+        "  --package <name>         Python package name. Default: normalized directory name.",
+        "  --preset <name>          Capability preset: minimal, default, enhanced, literature, writing, full.",
+        "  --profile <name>         Project profile metadata. Default: academic-general.",
+        "  --agent <id>             Agent target: universal, auto, or a supported skills.sh id.",
+        "  --install-skills         Install project-local skills after initialization.",
+        "  -h, --help               Show this help."
+    ].join("\n"));
+}
 function printSetupHelp() {
     console.log([
         "Usage: academic-research setup [options]",

package/dist/src/project.d.ts

@@ -13,6 +13,11 @@ export interface RenameProjectOptions {
     slug?: string;
     packageName?: string;
 }
+export interface InitProjectOptions extends CreateProjectOptions {
+}
+export interface UpdateProjectOptions {
+    apply?: boolean;
+}
 export interface ProjectResult {
     root: string;
     title: string;
@@ -22,7 +27,19 @@ export interface ProjectResult {
 export interface DoctorResult {
     ok: boolean;
     errors: string[];
+    warnings: string[];
+}
+export interface ProjectFileChange {
+    path: string;
+    action: "create" | "update";
+}
+export interface UpdateProjectResult {
+    root: string;
+    applied: boolean;
+    changes: ProjectFileChange[];
 }
 export declare function createProject(options: CreateProjectOptions): Promise<ProjectResult>;
+export declare function initProject(options: InitProjectOptions): Promise<ProjectResult>;
 export declare function renameProject(root: string, options: RenameProjectOptions): Promise<ProjectResult>;
+export declare function updateProject(root: string, options?: UpdateProjectOptions): Promise<UpdateProjectResult>;
 export declare function doctorProject(root: string): Promise<DoctorResult>;

package/dist/src/project.js

@@ -1,8 +1,8 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
-import { DEFAULT_AGENT, initializeCapabilities, installSkills, writeMcpEnvironmentExample } from "./capabilities.js";
+import { DEFAULT_AGENT, formatMcpDotenv, initializeCapabilities, installSkills, readCapabilities, renderCapabilityProfile, renderMcpSetup, renderMcpSnippet, 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";
@@ -90,11 +90,8 @@ export async function createProject(options) {
     const title = options.title ?? titleFromSlug(options.slug ?? basename(target));
     const slug = slugify(options.slug ?? title);
     const packageName = packageify(options.packageName ?? slug);
-    const preset = options.preset ?? "default";
+    const preset = assertKnownPreset(options.preset ?? "default");
     const agent = assertKnownAgentTarget(options.agent ?? DEFAULT_AGENT);
-    if (!AGENT_STACK.presets[preset]) {
-        throw new Error(`unknown capability preset: ${preset}. Expected one of: ${Object.keys(AGENT_STACK.presets).join(", ")}`);
-    }
     await mkdir(dirname(target), { recursive: true });
     await copyDirectory(templateRoot, target);
     await writeGeneratedGitignore(target);
@@ -108,6 +105,38 @@ export async function createProject(options) {
     }
     return { root: target, title, slug, packageName };
 }
+export async function initProject(options) {
+    const target = resolve(options.target);
+    const title = options.title ?? titleFromSlug(options.slug ?? basename(target));
+    const slug = slugify(options.slug ?? title);
+    const packageName = packageify(options.packageName ?? slug);
+    const preset = assertKnownPreset(options.preset ?? "default");
+    const agent = assertKnownAgentTarget(options.agent ?? DEFAULT_AGENT);
+    await mkdir(target, { recursive: true });
+    const created = await copyDirectoryMissing(templateRoot, target);
+    await writeGeneratedGitignore(target, { overwrite: false });
+    const project = await personalizeInitializedProject(target, {
+        title,
+        slug,
+        packageName,
+        profile: options.profile ?? "academic-general"
+    }, created);
+    await writeGeneratedPackageJson(target, { slug: project.slug });
+    if (created.has("configs/agent-stack.yaml"))
+        await writeAgentStack(target);
+    if (created.has(".env.example"))
+        await writeMcpEnvironmentExample(target);
+    if (created.has("configs/capabilities.yaml")) {
+        await initializeCapabilities(target, { preset, agent });
+    }
+    else {
+        await updateManagedCapabilityFiles(target, { apply: true, changes: [] });
+    }
+    if (options.installSkills) {
+        await installSkills(target, preset, { agent });
+    }
+    return project;
+}
 export async function renameProject(root, options) {
     const target = resolve(root);
     const configPath = join(target, "configs/default.yaml");
@@ -126,9 +155,23 @@ export async function renameProject(root, options) {
     await writeGeneratedPackageJson(target, { slug, preserveExistingSpec: true });
     return { root: target, title, slug, packageName };
 }
+export async function updateProject(root, options = {}) {
+    const target = resolve(root);
+    const config = await readProjectConfig(target);
+    const changes = [];
+    await updateGeneratedPackageJson(target, config.project.slug, { apply: options.apply === true, changes });
+    await stageTextWrite(target, ".env.example", formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers)), { apply: options.apply === true, changes });
+    await stageTextWrite(target, "configs/agent-stack.yaml", YAML.stringify(AGENT_STACK), {
+        apply: options.apply === true,
+        changes
+    });
+    await updateManagedCapabilityFiles(target, { apply: options.apply === true, changes });
+    return { root: target, applied: options.apply === true, changes };
+}
 export async function doctorProject(root) {
     const target = resolve(root);
     const errors = [];
+    const warnings = [];
     const required = [
         "README.md",
         ".gitignore",
@@ -175,16 +218,82 @@ export async function doctorProject(root) {
     }
     if (await exists(join(target, "configs/capabilities.yaml"))) {
         try {
-            YAML.parse(await readFile(join(target, "configs/capabilities.yaml"), "utf8"));
+            const state = await readCapabilities(target);
+            const unknown = state.mcp_servers.filter((server) => !AGENT_STACK.mcp_servers[server]);
+            if (unknown.length > 0)
+                errors.push(`unknown MCP server in configs/capabilities.yaml: ${unknown.join(", ")}`);
+            const snippet = renderMcpSnippet(state);
+            const commandServers = state.mcp_servers.filter((server) => AGENT_STACK.mcp_servers[server]?.command);
+            if (commandServers.length > 0) {
+                try {
+                    const raw = await readFile(join(target, "docs/agent/generated", snippet.fileName), "utf8");
+                    const generated = JSON.parse(raw);
+                    for (const server of commandServers) {
+                        if (!Object.hasOwn(generated.mcpServers ?? {}, server)) {
+                            errors.push(`${server}: enabled but missing from generated MCP snippet`);
+                        }
+                    }
+                }
+                catch (error) {
+                    errors.push(`invalid generated MCP snippet: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            await validateManagedCapabilityDrift(target, state, warnings);
         }
         catch (error) {
             errors.push(`invalid configs/capabilities.yaml: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    await validatePackageContract(target, errors, warnings);
+    await validateManagedTextDrift(target, warnings);
+    await validateStaleCommandReferences(target, warnings);
     for (const [relative, requiredColumns] of Object.entries(REQUIRED_CSV_COLUMNS)) {
         await validateCsvHeader(target, relative, requiredColumns, errors);
     }
-    return { ok: errors.length === 0, errors };
+    return { ok: errors.length === 0, errors, warnings };
+}
+async function personalizeInitializedProject(root, { title, slug, packageName, profile }, created) {
+    const configPath = join(root, "configs/default.yaml");
+    let config = await readProjectConfig(root);
+    if (created.has("configs/default.yaml")) {
+        config.project = {
+            ...config.project,
+            slug,
+            title,
+            profile,
+            package: packageName
+        };
+        await writeFile(configPath, YAML.stringify(config), "utf8");
+    }
+    config = await readProjectConfig(root);
+    const project = config.project;
+    if (created.has("pyproject.toml")) {
+        const pyprojectPath = join(root, "pyproject.toml");
+        const pyproject = await readFile(pyprojectPath, "utf8");
+        await writeFile(pyprojectPath, pyproject.replace(/^name = ".*"$/m, `name = "${project.slug}"`), "utf8");
+    }
+    if (created.has("README.md")) {
+        const readmePath = join(root, "README.md");
+        const readme = await readFile(readmePath, "utf8");
+        await writeFile(readmePath, readme.replace(/^# .*/m, `# ${project.title}`), "utf8");
+    }
+    await moveInitializedPythonPackage(root, project.package, created);
+    return { root, title: project.title, slug: project.slug, packageName: project.package };
+}
+async function moveInitializedPythonPackage(root, packageName, created) {
+    const previous = join(root, "src", "project_package");
+    const next = join(root, "src", packageName);
+    if (previous !== next && (await exists(previous)) && !(await exists(next))) {
+        await movePath(previous, next);
+        return;
+    }
+    await mkdir(dirname(join(next, "__init__.py")), { recursive: true });
+    if (!(await exists(join(next, "__init__.py")))) {
+        await writeFile(join(next, "__init__.py"), "\"\"\"Project package.\"\"\"\n", "utf8");
+    }
+    if (previous !== next && created.has("src/project_package/__init__.py")) {
+        await rm(join(previous, "__init__.py"), { force: true });
+    }
 }
 async function personalizeProject(root, { title, slug, packageName, profile, previousPackage = "project_package" }) {
     const configPath = join(root, "configs/default.yaml");
@@ -218,21 +327,82 @@ async function personalizeProject(root, { title, slug, packageName, profile, pre
 async function writeGeneratedPackageJson(root, { slug, preserveExistingSpec = false }) {
     const path = join(root, "package.json");
     const data = await readJson(path);
+    const packageSpec = await generatedPackageSpec(data, preserveExistingSpec);
+    await writeJson(path, generatedPackageJson(data, slug, packageSpec));
+}
+async function updateGeneratedPackageJson(root, slug, options) {
+    const path = join(root, "package.json");
+    const data = await readJson(path);
+    const packageSpec = await generatedPackageSpec(data, false);
+    const next = `${JSON.stringify(generatedPackageJson(data, slug, packageSpec), null, 2)}\n`;
+    await stageTextWrite(root, "package.json", next, options);
+}
+async function generatedPackageSpec(data, preserveExistingSpec) {
     const existingSpec = data.devDependencies?.["create-academic-research"];
-    const packageSpec = process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ??
+    return (process.env.CREATE_ACADEMIC_RESEARCH_PACKAGE_SPEC ??
         (preserveExistingSpec ? existingSpec : undefined) ??
-        await currentPackageVersion();
-    data.name = slug;
-    data.devDependencies = {
-        ...(data.devDependencies ?? {}),
-        "create-academic-research": packageSpec
+        (await currentPackageVersion()));
+}
+function generatedPackageJson(data, slug, packageSpec) {
+    return {
+        ...data,
+        name: slug,
+        scripts: {
+            ...(data.scripts ?? {}),
+            ...generatedLifecycleScripts(packageSpec)
+        },
+        devDependencies: {
+            ...(data.devDependencies ?? {}),
+            "create-academic-research": packageSpec
+        }
     };
-    await writeJson(path, data);
 }
-async function writeGeneratedGitignore(root) {
+function generatedLifecycleScripts(packageSpec) {
+    const command = `npm exec --yes --package=${lifecyclePackageSpec(packageSpec)} -- academic-research`;
+    return {
+        doctor: `${command} doctor`,
+        update: `${command} update`,
+        setup: `${command} setup`,
+        rename: `${command} rename`,
+        "agents:list": `${command} agents list`,
+        "skills:install": `${command} skills install`,
+        "skills:list": `${command} skills list`,
+        "skills:status": `${command} skills status`,
+        "skills:presets": `${command} skills presets`,
+        "skills:remove": `${command} skills remove`,
+        "skills:uninstall": `${command} skills uninstall`,
+        "skills:update": `${command} skills update`,
+        "mcp:list": `${command} mcp list`,
+        "mcp:enabled": `${command} mcp enabled`,
+        "mcp:available": `${command} mcp available`,
+        "mcp:commands": `${command} mcp commands`,
+        "mcp:env": `${command} mcp env`,
+        "mcp:dotenv": `${command} mcp env --write .env.example --all`,
+        "mcp:enable": `${command} mcp enable`,
+        "mcp:disable": `${command} mcp disable`,
+        "mcp:install": `${command} mcp install`,
+        "mcp:uninstall": `${command} mcp uninstall`,
+        "mcp:smoke": `${command} mcp smoke`,
+        "mcp:doctor": `${command} mcp doctor`,
+        "mcp:probe": `${command} mcp probe`
+    };
+}
+function lifecyclePackageSpec(packageSpec) {
+    if (packageSpec === "create-academic-research" || packageSpec.startsWith("create-academic-research@")) {
+        return packageSpec;
+    }
+    if (/^(file:|github:|git[+:]|https?:)/.test(packageSpec) || packageSpec.includes("/")) {
+        return packageSpec;
+    }
+    return `create-academic-research@${packageSpec}`;
+}
+async function writeGeneratedGitignore(root, options = {}) {
     const source = join(root, "_gitignore");
     if (await exists(source)) {
-        await writeFile(join(root, ".gitignore"), await readFile(source, "utf8"), "utf8");
+        const target = join(root, ".gitignore");
+        if (options.overwrite !== false || !(await exists(target))) {
+            await writeFile(target, await readFile(source, "utf8"), "utf8");
+        }
         await rm(source);
     }
 }
@@ -243,9 +413,179 @@ async function currentPackageVersion() {
     }
     return packageJson.version;
 }
+async function readProjectConfig(root) {
+    return YAML.parse(await readFile(join(root, "configs/default.yaml"), "utf8"));
+}
+async function updateManagedCapabilityFiles(root, options) {
+    const state = await readCapabilities(root);
+    await stageTextWrite(root, "docs/agent/capability-profile.md", renderCapabilityProfile(state), options);
+    await stageTextWrite(root, "docs/agent/mcp-setup.md", renderMcpSetup(state), options);
+    const snippet = renderMcpSnippet(state);
+    await stageTextWrite(root, join("docs/agent/generated", snippet.fileName), snippet.content, options);
+}
+async function stageTextWrite(root, relativePath, content, options) {
+    const path = join(root, relativePath);
+    let current;
+    try {
+        current = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+    if (current === content)
+        return;
+    options.changes.push({ path: toPosix(relativePath), action: current === undefined ? "create" : "update" });
+    if (!options.apply)
+        return;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+async function copyDirectoryMissing(source, target) {
+    const created = new Set();
+    async function copyChildren(sourceDir, targetDir) {
+        await mkdir(targetDir, { recursive: true });
+        const entries = await readdir(sourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === "node_modules" || entry.name === "__pycache__")
+                continue;
+            const sourcePath = join(sourceDir, entry.name);
+            const targetPath = join(targetDir, entry.name);
+            if (entry.isDirectory()) {
+                await copyChildren(sourcePath, targetPath);
+                continue;
+            }
+            if (await exists(targetPath))
+                continue;
+            await mkdir(dirname(targetPath), { recursive: true });
+            await copyFile(sourcePath, targetPath);
+            created.add(toPosix(relative(target, targetPath)));
+        }
+    }
+    await copyChildren(source, target);
+    return created;
+}
 async function writeAgentStack(root) {
     await writeFile(join(root, "configs/agent-stack.yaml"), YAML.stringify(AGENT_STACK), "utf8");
 }
+async function validatePackageContract(root, errors, warnings) {
+    const path = join(root, "package.json");
+    if (!(await exists(path)))
+        return;
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        errors.push(`invalid package.json: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    const packageSpec = data.devDependencies?.["create-academic-research"] ?? (await currentPackageVersion());
+    const expectedScripts = generatedLifecycleScripts(packageSpec);
+    for (const [name, expected] of Object.entries(expectedScripts)) {
+        const actual = data.scripts?.[name];
+        if (!actual) {
+            warnings.push(`package.json missing lifecycle script: ${name}`);
+            continue;
+        }
+        if (isStaleLifecycleCommand(actual)) {
+            errors.push(`package.json script ${name} uses stale academic-research invocation`);
+            continue;
+        }
+        if (actual !== expected) {
+            warnings.push(`package.json script ${name} differs from the current managed command`);
+        }
+    }
+    const current = await currentPackageVersion();
+    if (isOlderSimpleVersion(packageSpec, current)) {
+        warnings.push(`create-academic-research ${packageSpec} is older than ${current}; run npm run update -- --apply`);
+    }
+}
+async function validateManagedTextDrift(root, warnings) {
+    const expectedEnv = formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers));
+    await warnIfTextDrift(root, ".env.example", expectedEnv, ".env.example is not current", warnings);
+    await warnIfTextDrift(root, "configs/agent-stack.yaml", YAML.stringify(AGENT_STACK), "configs/agent-stack.yaml is not current", warnings);
+}
+async function validateManagedCapabilityDrift(root, state, warnings) {
+    await warnIfTextDrift(root, "docs/agent/capability-profile.md", renderCapabilityProfile(state), "docs/agent/capability-profile.md is not current", warnings);
+    await warnIfTextDrift(root, "docs/agent/mcp-setup.md", renderMcpSetup(state), "docs/agent/mcp-setup.md is not current", warnings);
+    const snippet = renderMcpSnippet(state);
+    await warnIfTextDrift(root, join("docs/agent/generated", snippet.fileName), snippet.content, `docs/agent/generated/${snippet.fileName} is not current`, warnings);
+}
+async function warnIfTextDrift(root, relativePath, expected, warning, warnings) {
+    try {
+        const actual = await readFile(join(root, relativePath), "utf8");
+        if (actual !== expected)
+            warnings.push(warning);
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+}
+async function validateStaleCommandReferences(root, warnings) {
+    const docs = [
+        "README.md",
+        "docs/getting-started.md",
+        "docs/agent/capability-profile.md",
+        "docs/agent/mcp-client-setup.md",
+        "docs/agent/mcp-setup.md",
+        "scripts/README.md"
+    ];
+    for (const relativePath of docs) {
+        try {
+            const text = await readFile(join(root, relativePath), "utf8");
+            if (containsStaleCommandReference(text)) {
+                warnings.push(`stale command reference in ${relativePath}; prefer project npm scripts`);
+            }
+        }
+        catch (error) {
+            if (!isMissingFileError(error))
+                throw error;
+        }
+    }
+}
+function containsStaleCommandReference(text) {
+    return (/\bnpx\s+academic-research\b/.test(text) ||
+        /(^|[`(>\s])academic-research\s+(doctor|setup|rename|agents|skills|mcp)\b/.test(text));
+}
+function isStaleLifecycleCommand(command) {
+    return /^academic-research\s+/.test(command) || /\bnpx\s+academic-research\b/.test(command);
+}
+function isOlderSimpleVersion(left, right) {
+    const leftParts = parseSimpleVersion(left);
+    const rightParts = parseSimpleVersion(right);
+    if (!leftParts || !rightParts)
+        return false;
+    for (let index = 0; index < rightParts.length; index += 1) {
+        if (leftParts[index] < rightParts[index])
+            return true;
+        if (leftParts[index] > rightParts[index])
+            return false;
+    }
+    return false;
+}
+function parseSimpleVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+    if (!match)
+        return undefined;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function assertKnownPreset(preset) {
+    if (!AGENT_STACK.presets[preset]) {
+        throw new Error(`unknown capability preset: ${preset}. Expected one of: ${Object.keys(AGENT_STACK.presets).join(", ")}`);
+    }
+    return preset;
+}
+function isMissingFileError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function toPosix(value) {
+    return value.split(/[\\/]/).join("/");
+}
 async function validateCsvHeader(root, relative, requiredColumns, errors) {
     const path = join(root, relative);
     if (!(await exists(path)))

package/package.json

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

package/template/README.md

@@ -30,7 +30,8 @@ python3.11 -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip
 python -m pip install -e ".[dev]"
-npx academic-research doctor
+npm run doctor
+npm run update
 ```
 
 ## Core Folders
@@ -53,23 +54,24 @@ npx academic-research doctor
 Project-local skills and MCP records are managed with:
 
 ```bash
-npx academic-research skills presets
-npx academic-research agents list
-npx academic-research skills install --preset default
-npx academic-research skills install --preset enhanced
-npx academic-research skills 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 --env-file .env.local
-npx academic-research mcp doctor --env-file .env.local
-npx academic-research mcp probe arxiv --timeout-ms 5000
+npm run skills:presets
+npm run agents:list
+npm run skills:install
+npm run skills:install -- --preset enhanced
+npm run skills:install -- source-ingestion sota-literature-review
+npm run skills:list
+npm run skills:status
+npm run update
+npm run setup
+npm run mcp:dotenv
+npm run mcp:list
+npm run mcp:env -- openalex semantic-scholar zotero
+npm run mcp:enable -- arxiv dblp
+npm run mcp:commands -- arxiv
+npm run mcp:install -- arxiv
+npm run mcp:smoke -- --env-file .env.local
+npm run mcp:doctor -- --env-file .env.local
+npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
 `skills list` reports installed project-local skills. `skills presets` reports
@@ -81,10 +83,10 @@ 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`.
+`npm run mcp:dotenv`. 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.

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

@@ -19,7 +19,7 @@ store.
 Regenerate the committed reference from the current MCP catalog with:
 
 ```bash
-npx academic-research mcp env --write .env.example --all
+npm run mcp:dotenv
 ```
 
 Create a private local file when needed:
@@ -33,9 +33,9 @@ Do not commit filled `.env`, `.env.local`, tokens, cookies, or browser sessions.
 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
+npm run mcp:doctor -- --env-file .env.local
+npm run mcp:smoke -- --env-file .env.local
+npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
 ## Client Notes
@@ -57,10 +57,10 @@ 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>`.
+2. Inspect prerequisites with `npm run 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
+4. Run `npm run mcp:smoke -- --env-file .env.local`.
+5. Run `npm run 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

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

@@ -5,9 +5,8 @@ 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`.
+with `npm run mcp:dotenv`.
 
-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.
+Use `npm run mcp:doctor -- --env-file .env.local` when you want the CLI to read
+an explicit local env file. Use `npm run 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

@@ -6,28 +6,30 @@ Use this path for the first working session in a new research repository.
 
 ```bash
 npm install
-npx academic-research doctor
-npx academic-research setup
+npm run doctor
+npm run update
+npm run 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.
+`doctor` checks required files and structural contracts. `update` is a dry-run
+unless you pass `-- --apply`. `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
+npm run skills:install
+npm run 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
+npm run skills:install -- --preset enhanced
 ```
 
 ## 3. Prepare MCP Environment
@@ -36,18 +38,18 @@ 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
+npm run mcp:dotenv
 cp .env.example .env.local
-npx academic-research mcp env openalex semantic-scholar zotero
-npx academic-research mcp doctor --env-file .env.local
+npm run mcp:env -- openalex semantic-scholar zotero
+npm run 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
+npm run mcp:smoke -- --env-file .env.local
+npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
 ## 4. Start Source Work

package/template/package.json

@@ -3,20 +3,33 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "doctor": "academic-research doctor",
-    "setup": "academic-research setup",
-    "skills:install": "academic-research skills install --preset default",
-    "skills:list": "academic-research skills list",
-    "skills:presets": "academic-research skills presets",
-    "mcp:list": "academic-research mcp list",
-    "mcp:commands": "academic-research mcp commands",
-    "mcp:env": "academic-research mcp env",
-    "mcp:dotenv": "academic-research mcp env --write .env.example --all",
-    "mcp:smoke": "academic-research mcp smoke",
-    "mcp:doctor": "academic-research mcp doctor",
-    "mcp:probe": "academic-research mcp probe"
+    "doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research doctor",
+    "update": "npm exec --yes --package=create-academic-research@latest -- academic-research update",
+    "setup": "npm exec --yes --package=create-academic-research@latest -- academic-research setup",
+    "rename": "npm exec --yes --package=create-academic-research@latest -- academic-research rename",
+    "agents:list": "npm exec --yes --package=create-academic-research@latest -- academic-research agents list",
+    "skills:install": "npm exec --yes --package=create-academic-research@latest -- academic-research skills install",
+    "skills:list": "npm exec --yes --package=create-academic-research@latest -- academic-research skills list",
+    "skills:status": "npm exec --yes --package=create-academic-research@latest -- academic-research skills status",
+    "skills:presets": "npm exec --yes --package=create-academic-research@latest -- academic-research skills presets",
+    "skills:remove": "npm exec --yes --package=create-academic-research@latest -- academic-research skills remove",
+    "skills:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research skills uninstall",
+    "skills:update": "npm exec --yes --package=create-academic-research@latest -- academic-research skills update",
+    "mcp:list": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp list",
+    "mcp:enabled": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enabled",
+    "mcp:available": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp available",
+    "mcp:commands": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp commands",
+    "mcp:env": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env",
+    "mcp:dotenv": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env --write .env.example --all",
+    "mcp:enable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enable",
+    "mcp:disable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp disable",
+    "mcp:install": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp install",
+    "mcp:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp uninstall",
+    "mcp:smoke": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp smoke",
+    "mcp:doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp doctor",
+    "mcp:probe": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp probe"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.12"
+    "create-academic-research": "0.1.14"
   }
 }