create-academic-research 0.1.13 → 0.1.14

package/README.md

@@ -114,6 +114,7 @@ Inside a generated project:
 
 ```bash
 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
@@ -147,6 +148,13 @@ For direct one-off invocation without the generated package scripts, use
 
 ## 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.

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",
         "",
@@ -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",
@@ -384,8 +397,7 @@ async function writeMcpSetup(root, state) {
         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 `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.", "");
-    await mkdir(join(root, "docs/agent"), { recursive: true });
-    await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
+    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"]);
@@ -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,6 +221,8 @@ 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(`npm run skills:install -- --preset ${state.preset}`);
@@ -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,25 +327,41 @@ 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.scripts = {
-        ...(data.scripts ?? {}),
-        ...generatedLifecycleScripts(packageSpec)
-    };
-    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);
 }
 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`,
@@ -271,10 +396,13 @@ function lifecyclePackageSpec(packageSpec) {
     }
     return `create-academic-research@${packageSpec}`;
 }
-async function writeGeneratedGitignore(root) {
+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);
     }
 }
@@ -285,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.13",
+  "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

@@ -31,6 +31,7 @@ source .venv/bin/activate
 python -m pip install --upgrade pip
 python -m pip install -e ".[dev]"
 npm run doctor
+npm run update
 ```
 
 ## Core Folders
@@ -60,6 +61,7 @@ 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

package/template/docs/getting-started.md

@@ -7,12 +7,14 @@ Use this path for the first working session in a new research repository.
 ```bash
 npm install
 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
 

package/template/package.json

@@ -4,6 +4,7 @@
   "type": "module",
   "scripts": {
     "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",
@@ -29,6 +30,6 @@
     "mcp:probe": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp probe"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.13"
+    "create-academic-research": "0.1.14"
   }
 }