create-academic-research 0.1.13 → 0.1.15

package/dist/src/project.js

@@ -1,8 +1,9 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+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, resolveMcpServerForState, 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 +91,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);
@@ -103,11 +101,45 @@ export async function createProject(options) {
     await writeAgentStack(target);
     await writeMcpEnvironmentExample(target);
     await initializeCapabilities(target, { preset, agent });
+    await writeManagedFileManifest(target);
     if (options.installSkills) {
         await installSkills(target, preset);
     }
     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: [] });
+    }
+    await writeManagedFileManifest(target);
+    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");
@@ -124,11 +156,25 @@ export async function renameProject(root, options) {
         previousPackage
     });
     await writeGeneratedPackageJson(target, { slug, preserveExistingSpec: true });
+    await writeManagedFileManifest(target);
     return { root: target, title, slug, packageName };
 }
+export async function updateProject(root, options = {}) {
+    const target = resolve(root);
+    const changes = [];
+    const manifest = await readManagedFileManifest(target);
+    const specs = await managedFileSpecs(target);
+    const nextManifest = await stageManagedFiles(target, specs, manifest, {
+        apply: options.apply === true,
+        changes
+    });
+    await stageManagedManifest(target, manifest, nextManifest, { 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 +221,112 @@ 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 needsMcpEnvDoctor = state.mcp_servers.some((serverName) => {
+                const server = AGENT_STACK.mcp_servers[serverName]
+                    ? resolveMcpServerForState(state, serverName, state.mcp_server_modes[serverName])
+                    : undefined;
+                return Boolean(server &&
+                    (server.required_env.length > 0 ||
+                        server.recommended_env.length > 0 ||
+                        server.local_service ||
+                        server.execution_mode === "manual-local" ||
+                        server.execution_mode === "local-service"));
+            });
+            if (needsMcpEnvDoctor) {
+                warnings.push("MCP readiness may require local secrets; run npm run mcp:doctor -- --env-file .env.local");
+            }
+            for (const serverName of state.mcp_servers) {
+                if (!AGENT_STACK.mcp_servers[serverName])
+                    continue;
+                const server = resolveMcpServerForState(state, serverName, state.mcp_server_modes[serverName]);
+                if (server.connection_mode === "remote-custom" &&
+                    server.remote_url_env &&
+                    !envHasValue(process.env, server.remote_url_env)) {
+                    errors.push(`${serverName}: missing required environment variable: ${server.remote_url_env}`);
+                }
+            }
+            const snippet = renderMcpSnippet(state);
+            const snippetServers = state.mcp_servers.filter((serverName) => {
+                if (!AGENT_STACK.mcp_servers[serverName])
+                    return false;
+                const server = resolveMcpServerForState(state, serverName, state.mcp_server_modes[serverName]);
+                return Boolean(server.command ||
+                    (server.connection_mode === "remote-curated" && server.hosted_url) ||
+                    (server.connection_mode === "remote-custom" && server.remote_configured));
+            });
+            if (snippetServers.length > 0) {
+                try {
+                    const raw = await readFile(join(target, "docs/agent/generated", snippet.fileName), "utf8");
+                    const generated = JSON.parse(raw);
+                    for (const server of snippetServers) {
+                        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)}`);
+                }
+            }
         }
         catch (error) {
             errors.push(`invalid configs/capabilities.yaml: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    await validatePackageContract(target, errors, warnings);
+    await validateManagedManifestDrift(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 +360,94 @@ 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 managedFileSpecs(root) {
+    const config = await readProjectConfig(root);
+    const packageJson = await readJson(join(root, "package.json"));
+    const packageSpec = await currentPackageVersion();
+    const state = await readCapabilities(root);
+    const snippet = renderMcpSnippet(state);
+    const currentReadme = await readOptionalText(join(root, "README.md"));
+    const currentDefaultConfig = await readOptionalText(join(root, "configs/default.yaml"));
+    const currentWikiLog = await readOptionalText(join(root, "wiki/log.md"));
+    return [
+        {
+            path: "README.md",
+            policy: "user-owned",
+            trackOnly: true,
+            content: currentReadme ?? ""
+        },
+        {
+            path: "configs/default.yaml",
+            policy: "user-owned",
+            trackOnly: true,
+            content: currentDefaultConfig ?? ""
+        },
+        {
+            path: "wiki/log.md",
+            policy: "append-only",
+            trackOnly: true,
+            content: currentWikiLog ?? ""
+        },
+        {
+            path: "package.json",
+            policy: "managed",
+            mergeSafe: true,
+            content: `${JSON.stringify(generatedPackageJson(packageJson, config.project.slug, packageSpec), null, 2)}\n`
+        },
+        { path: ".gitignore", policy: "managed", content: await templateText("_gitignore") },
+        { path: ".env.example", policy: "managed", content: formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers)) },
+        { path: "configs/agent-stack.yaml", policy: "managed", content: YAML.stringify(AGENT_STACK) },
+        { path: "docs/getting-started.md", policy: "managed", content: await templateText("docs/getting-started.md") },
+        {
+            path: "docs/agent/mcp-client-setup.md",
+            policy: "managed",
+            content: await templateText("docs/agent/mcp-client-setup.md")
+        },
+        { path: "scripts/README.md", policy: "managed", content: await templateText("scripts/README.md") },
+        { path: "docs/agent/capability-profile.md", policy: "generated", content: renderCapabilityProfile(state) },
+        { path: "docs/agent/mcp-setup.md", policy: "generated", content: renderMcpSetup(state) },
+        { path: join("docs/agent/generated", snippet.fileName), policy: "generated", content: snippet.content }
+    ];
+}
+async function templateText(relativePath) {
+    return readFile(join(templateRoot, relativePath), "utf8");
+}
+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`;
+    const latestCommand = "npm exec --yes --package=create-academic-research@latest -- academic-research";
     return {
         doctor: `${command} doctor`,
+        update: `${latestCommand} update`,
         setup: `${command} setup`,
         rename: `${command} rename`,
         "agents:list": `${command} agents list`,
@@ -248,6 +459,8 @@ function generatedLifecycleScripts(packageSpec) {
         "skills:uninstall": `${command} skills uninstall`,
         "skills:update": `${command} skills update`,
         "mcp:list": `${command} mcp list`,
+        "mcp:modes": `${command} mcp modes`,
+        "mcp:status": `${command} mcp status`,
         "mcp:enabled": `${command} mcp enabled`,
         "mcp:available": `${command} mcp available`,
         "mcp:commands": `${command} mcp commands`,
@@ -255,6 +468,9 @@ function generatedLifecycleScripts(packageSpec) {
         "mcp:dotenv": `${command} mcp env --write .env.example --all`,
         "mcp:enable": `${command} mcp enable`,
         "mcp:disable": `${command} mcp disable`,
+        "mcp:setup": `${command} mcp setup`,
+        "mcp:client:add": `${command} mcp client add`,
+        "mcp:client:remove": `${command} mcp client remove`,
         "mcp:install": `${command} mcp install`,
         "mcp:uninstall": `${command} mcp uninstall`,
         "mcp:smoke": `${command} mcp smoke`,
@@ -271,10 +487,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 +504,422 @@ 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 writeManagedFileManifest(root) {
+    const specs = await managedFileSpecs(root);
+    const manifest = emptyManagedFileManifest(await currentPackageVersion());
+    for (const spec of specs) {
+        manifest.files[toPosix(spec.path)] = managedRecordForWrittenFile(spec);
+    }
+    await mkdir(dirname(managedManifestPath(root)), { recursive: true });
+    await writeFile(managedManifestPath(root), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+async function readManagedFileManifest(root) {
+    try {
+        const parsed = JSON.parse(await readFile(managedManifestPath(root), "utf8"));
+        return normalizeManagedFileManifest(parsed);
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return undefined;
+        throw error;
+    }
+}
+async function stageManagedFiles(root, specs, manifest, options) {
+    const nextManifest = manifest
+        ? cloneManagedFileManifest(manifest)
+        : emptyManagedFileManifest(await currentPackageVersion());
+    nextManifest.generator = {
+        name: "create-academic-research",
+        version: await currentPackageVersion(),
+        updated_at: manifest?.generator.updated_at ?? nextManifest.generator.updated_at
+    };
+    for (const spec of specs) {
+        const relativePath = toPosix(spec.path);
+        const path = join(root, relativePath);
+        const current = await readOptionalText(path);
+        const currentChecksum = current === undefined ? undefined : checksumText(current);
+        const existing = manifest?.files[relativePath];
+        const generatedChecksum = checksumText(spec.content);
+        if (spec.trackOnly) {
+            if (current !== undefined) {
+                nextManifest.files[relativePath] = stableManagedRecord(existing, {
+                    path: relativePath,
+                    policy: spec.policy,
+                    generated_checksum: generatedChecksum,
+                    baseline_checksum: currentChecksum
+                });
+            }
+            continue;
+        }
+        if (current === spec.content) {
+            nextManifest.files[relativePath] = stableManagedRecord(existing, {
+                path: relativePath,
+                policy: spec.policy,
+                generated_checksum: generatedChecksum,
+                baseline_checksum: generatedChecksum
+            });
+            continue;
+        }
+        if (current === undefined) {
+            options.changes.push({ path: relativePath, action: "create" });
+            if (options.apply) {
+                await mkdir(dirname(path), { recursive: true });
+                await writeFile(path, spec.content, "utf8");
+            }
+            nextManifest.files[relativePath] = stableManagedRecord(existing, managedRecordCandidateForWrittenFile(spec));
+            continue;
+        }
+        if (spec.mergeSafe || canSafelyUpdateManagedFile(existing, currentChecksum)) {
+            options.changes.push({ path: relativePath, action: "update" });
+            if (options.apply) {
+                await mkdir(dirname(path), { recursive: true });
+                await writeFile(path, spec.content, "utf8");
+            }
+            nextManifest.files[relativePath] = stableManagedRecord(existing, managedRecordCandidateForWrittenFile(spec));
+            continue;
+        }
+        options.changes.push({
+            path: relativePath,
+            action: "skip",
+            reason: manifest ? "local edits detected" : "unknown legacy content"
+        });
+        nextManifest.files[relativePath] = stableManagedRecord(existing, {
+            path: relativePath,
+            policy: spec.policy,
+            generated_checksum: generatedChecksum,
+            current_checksum: currentChecksum,
+            reason: manifest ? "local edits detected" : "unknown legacy content"
+        });
+    }
+    return nextManifest;
+}
+async function stageManagedManifest(root, previous, next, options) {
+    if (previous && managedManifestSemanticallyEqual(previous, next))
+        return;
+    next.generator = {
+        name: "create-academic-research",
+        version: await currentPackageVersion(),
+        updated_at: nowIso()
+    };
+    const content = `${JSON.stringify(next, null, 2)}\n`;
+    const current = await readOptionalText(managedManifestPath(root));
+    options.changes.push({
+        path: ".academic-research/managed-files.json",
+        action: previous ? "update" : "create"
+    });
+    if (options.apply && current !== content) {
+        await mkdir(dirname(managedManifestPath(root)), { recursive: true });
+        await writeFile(managedManifestPath(root), content, "utf8");
+    }
+}
+function emptyManagedFileManifest(version) {
+    return {
+        version: 1,
+        generator: {
+            name: "create-academic-research",
+            version,
+            updated_at: nowIso()
+        },
+        files: {}
+    };
+}
+function normalizeManagedFileManifest(value) {
+    const record = typeof value === "object" && value !== null ? value : {};
+    const generator = typeof record.generator === "object" && record.generator !== null
+        ? record.generator
+        : {};
+    const files = typeof record.files === "object" && record.files !== null
+        ? record.files
+        : {};
+    return {
+        version: 1,
+        generator: {
+            name: "create-academic-research",
+            version: typeof generator.version === "string" ? generator.version : "unknown",
+            updated_at: typeof generator.updated_at === "string" ? generator.updated_at : nowIso()
+        },
+        files
+    };
+}
+function cloneManagedFileManifest(manifest) {
+    return {
+        version: 1,
+        generator: { ...manifest.generator },
+        files: Object.fromEntries(Object.entries(manifest.files).map(([path, record]) => [path, { ...record }]))
+    };
+}
+function managedRecordForWrittenFile(spec) {
+    return {
+        ...managedRecordCandidateForWrittenFile(spec),
+        updated_at: nowIso()
+    };
+}
+function managedRecordCandidateForWrittenFile(spec) {
+    const generatedChecksum = checksumText(spec.content);
+    return {
+        path: toPosix(spec.path),
+        policy: spec.policy,
+        generated_checksum: generatedChecksum,
+        baseline_checksum: generatedChecksum
+    };
+}
+function stableManagedRecord(existing, candidate) {
+    if (existing && managedRecordSemanticallyEqual(existing, candidate))
+        return existing;
+    return { ...candidate, updated_at: nowIso() };
+}
+function managedManifestSemanticallyEqual(left, right) {
+    if (left.version !== right.version)
+        return false;
+    if (left.generator.name !== right.generator.name)
+        return false;
+    if (left.generator.version !== right.generator.version)
+        return false;
+    const leftPaths = Object.keys(left.files).sort();
+    const rightPaths = Object.keys(right.files).sort();
+    if (leftPaths.length !== rightPaths.length)
+        return false;
+    for (let index = 0; index < leftPaths.length; index += 1) {
+        const path = leftPaths[index];
+        if (path !== rightPaths[index])
+            return false;
+        if (!managedRecordSemanticallyEqual(left.files[path], right.files[path]))
+            return false;
+    }
+    return true;
+}
+function managedRecordSemanticallyEqual(left, right) {
+    return (left.path === right.path &&
+        left.policy === right.policy &&
+        left.generated_checksum === right.generated_checksum &&
+        left.baseline_checksum === right.baseline_checksum &&
+        left.current_checksum === right.current_checksum &&
+        left.reason === right.reason);
+}
+function canSafelyUpdateManagedFile(record, currentChecksum) {
+    if (!record || !currentChecksum)
+        return false;
+    return currentChecksum === record.baseline_checksum || currentChecksum === record.generated_checksum;
+}
+async function readOptionalText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return undefined;
+        throw error;
+    }
+}
+function managedManifestPath(root) {
+    return join(root, ".academic-research", "managed-files.json");
+}
+function checksumText(value) {
+    return `sha256:${createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+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 or npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply`);
+    }
+}
+async function validateManagedManifestDrift(root, warnings) {
+    let specs;
+    try {
+        specs = await managedFileSpecs(root);
+    }
+    catch {
+        return;
+    }
+    const manifest = await readManagedFileManifest(root);
+    if (!manifest) {
+        warnings.push("managed-file manifest is missing; run npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply");
+    }
+    for (const spec of specs) {
+        if (spec.trackOnly)
+            continue;
+        if (spec.path === "package.json")
+            continue;
+        const relativePath = toPosix(spec.path);
+        const current = await readOptionalText(join(root, relativePath));
+        if (current === undefined) {
+            warnings.push(`${relativePath} is missing; run npm run update -- --apply`);
+            continue;
+        }
+        if (current === spec.content)
+            continue;
+        const checksum = checksumText(current);
+        const record = manifest?.files[relativePath];
+        if (canSafelyUpdateManagedFile(record, checksum)) {
+            warnings.push(`${relativePath} is not current; run npm run update -- --apply`);
+        }
+        else {
+            warnings.push(`${relativePath} has local edits; run npm run update to preview managed changes`);
+        }
+    }
+}
+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 envHasValue(env, name) {
+    return typeof env[name] === "string" && env[name] !== "";
+}
+function toPosix(value) {
+    return value.split(/[\\/]/).join("/");
+}
 async function validateCsvHeader(root, relative, requiredColumns, errors) {
     const path = join(root, relative);
     if (!(await exists(path)))