@topogram/cli 0.3.64 → 0.3.65

package/src/new-project.js

@@ -1,2279 +1,8 @@
 // @ts-check
 
-import fs from "node:fs";
-import childProcess from "node:child_process";
-import crypto from "node:crypto";
-import os from "node:os";
-import path from "node:path";
-
-import { defaultGeneratorPolicy, writeGeneratorPolicy } from "./generator-policy.js";
-import { assertSafeNpmSpec, localNpmrcEnv } from "./npm-safety.js";
-import { writeTemplateTrustRecord } from "./template-trust.js";
-import { githubRepoSlug } from "./topogram-config.js";
-
-const CLI_PACKAGE_NAME = "@topogram/cli";
-const DEFAULT_TEMPLATE_NAME = "hello-web";
-const TEMPLATE_MANIFEST = "topogram-template.json";
-const TEMPLATE_FILES_MANIFEST = ".topogram-template-files.json";
-const TEMPLATE_POLICY_FILE = "topogram.template-policy.json";
-const MAX_TEXT_DIFF_BYTES = 256 * 1024;
-
-const GENERATOR_LABELS = new Map([
-  ["topogram/express", "Express"],
-  ["topogram/hono", "Hono"],
-  ["topogram/postgres", "Postgres"],
-  ["topogram/react", "React"],
-  ["topogram/sqlite", "SQLite"],
-  ["topogram/sveltekit", "SvelteKit"],
-  ["topogram/vanilla-web", "Vanilla HTML/CSS/JS"]
-]);
-
-const SURFACE_ORDER = new Map([
-  ["web_surface", 10],
-  ["api_service", 20],
-  ["database", 30],
-  ["ios_surface", 40],
-  ["android_surface", 50]
-]);
-
-/**
- * @param {string} templateId
- * @param {string} relativePath
- * @returns {string}
- */
-function unsupportedTemplateSymlinkMessage(templateId, relativePath) {
-  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied topogram/ and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram new or topogram template check.`;
-}
-
-/**
- * @typedef {Object} CreateNewProjectOptions
- * @property {string} targetPath
- * @property {string} [templateName]
- * @property {string} engineRoot
- * @property {string} templatesRoot
- * @property {CatalogTemplateProvenance|null} [templateProvenance]
- */
-
-/**
- * @typedef {Object} TemplateUpdatePlanOptions
- * @property {string} projectRoot
- * @property {Record<string, any>} projectConfig
- * @property {string|null} [templateName]
- * @property {string} templatesRoot
- */
-
-/**
- * @typedef {TemplateUpdatePlanOptions & { filePath: string, action: "accept-current"|"accept-candidate"|"delete-current" }} TemplateUpdateFileActionOptions
- */
-
-/**
- * @typedef {Object} TemplateOwnedFileRecord
- * @property {string} path
- * @property {string} sha256
- * @property {number} size
- */
-
-/**
- * @typedef {Object} TemplateManifest
- * @property {string} id
- * @property {string} version
- * @property {string} kind
- * @property {string} topogramVersion
- * @property {boolean} [includesExecutableImplementation]
- * @property {string} [description]
- * @property {Record<string, string>} [starterScripts]
- */
-
-/**
- * @typedef {Object} TemplateTopologySummary
- * @property {string[]} surfaces
- * @property {string[]} generators
- * @property {string} stack
- */
-
-/**
- * @typedef {Object} TemplatePolicy
- * @property {string} version
- * @property {Array<"local"|"package">} allowedSources
- * @property {string[]} allowedTemplateIds
- * @property {string[]} [allowedPackageScopes]
- * @property {"allow"|"warn"|"deny"} executableImplementation
- * @property {Record<string, string>} [pinnedVersions]
- */
-
-/**
- * @typedef {Object} TemplatePolicyInfo
- * @property {string} path
- * @property {TemplatePolicy|null} policy
- * @property {boolean} exists
- * @property {TemplateUpdateDiagnostic[]} diagnostics
- */
-
-/**
- * @typedef {Object} TemplateUpdateDiagnostic
- * @property {string} code
- * @property {"error"|"warning"} severity
- * @property {string} message
- * @property {string|null} path
- * @property {string|null} suggestedFix
- * @property {string|null} step
- */
-
-/**
- * @typedef {Object} ResolvedTemplate
- * @property {string} requested
- * @property {string} root
- * @property {TemplateManifest} manifest
- * @property {"local"|"package"} source
- * @property {string|null} packageSpec
- */
-
-/**
- * @typedef {Object} CatalogTemplateProvenance
- * @property {string} id
- * @property {string} source
- * @property {string} package
- * @property {string} version
- * @property {string} packageSpec
- * @property {boolean} [includesExecutableImplementation]
- */
-
-/**
- * @param {string} projectRoot
- * @returns {string}
- */
-function packageNameFromPath(projectRoot) {
-  const baseName = path.basename(path.resolve(projectRoot)).toLowerCase();
-  const normalized = baseName
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/^[._-]+/, "")
-    .replace(/[._-]+$/, "");
-  return normalized || "topogram-app";
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} engineRoot
- * @returns {string}
- */
-function fileDependencyForEngine(projectRoot, engineRoot) {
-  const relative = path.relative(projectRoot, engineRoot).replace(/\\/g, "/");
-  if (!relative || relative.startsWith("..")) {
-    return `file:${engineRoot}`;
-  }
-  return `file:./${relative}`;
-}
-
-/**
- * @param {string} engineRoot
- * @returns {{ name: string, version: string }}
- */
-function readCliPackageMetadata(engineRoot) {
-  const packagePath = path.join(engineRoot, "package.json");
-  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-  return {
-    name: typeof pkg.name === "string" ? pkg.name : CLI_PACKAGE_NAME,
-    version: typeof pkg.version === "string" ? pkg.version : "0.0.0"
-  };
-}
-
-/**
- * @param {string} engineRoot
- * @returns {boolean}
- */
-function isSourceCheckoutEngine(engineRoot) {
-  return fs.existsSync(path.join(engineRoot, "tests", "active"));
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} engineRoot
- * @returns {{ name: string, spec: string }}
- */
-function cliDependencyForProject(projectRoot, engineRoot) {
-  const metadata = readCliPackageMetadata(engineRoot);
-  const overrideSpec = process.env.TOPOGRAM_CLI_PACKAGE_SPEC || "";
-  if (overrideSpec) {
-    return { name: metadata.name, spec: overrideSpec };
-  }
-  if (isSourceCheckoutEngine(engineRoot)) {
-    return { name: metadata.name, spec: fileDependencyForEngine(projectRoot, engineRoot) };
-  }
-  return { name: metadata.name, spec: metadata.version };
-}
-
-/**
- * @param {string} projectRoot
- * @param {{ name: string, spec: string }} cliDependency
- * @returns {void}
- */
-function writeProjectNpmConfig(projectRoot, cliDependency) {
-  void projectRoot;
-  void cliDependency;
-}
-
-/**
- * @param {string} templateRoot
- * @returns {Record<string, string>}
- */
-function generatorDependenciesForTemplate(templateRoot) {
-  const packagePath = path.join(templateRoot, "package.json");
-  if (!fs.existsSync(packagePath)) {
-    return {};
-  }
-  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-  const explicit = pkg.topogramGeneratorDependencies &&
-    typeof pkg.topogramGeneratorDependencies === "object" &&
-    !Array.isArray(pkg.topogramGeneratorDependencies)
-    ? pkg.topogramGeneratorDependencies
-    : {};
-  const dependencies = {
-    ...(pkg.dependencies || {}),
-    ...(pkg.devDependencies || {}),
-    ...explicit
-  };
-  return Object.fromEntries(Object.entries(dependencies).filter(([name, spec]) =>
-    typeof name === "string" &&
-    (name.includes("topogram-generator") || name.startsWith("@topogram/generator-")) &&
-    typeof spec === "string" &&
-    spec.length > 0
-  ));
-}
-
-/**
- * @param {string} parent
- * @param {string} child
- * @returns {boolean}
- */
-function isSameOrInside(parent, child) {
-  const relative = path.relative(parent, child);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-/**
- * @param {string} value
- * @returns {boolean}
- */
-function isLocalTemplateSpec(value) {
-  return value === "." ||
-    value.startsWith("./") ||
-    value.startsWith("../") ||
-    path.isAbsolute(value);
-}
-
-/**
- * @param {string} spec
- * @returns {string}
- */
-export function packageNameFromSpec(spec) {
-  if (spec.startsWith("@")) {
-    const segments = spec.split("/");
-    if (segments.length < 2) {
-      throw new Error(`Invalid scoped template package spec '${spec}'.`);
-    }
-    const scope = segments[0];
-    const nameAndVersion = segments[1];
-    const versionIndex = nameAndVersion.indexOf("@");
-    const name = versionIndex >= 0 ? nameAndVersion.slice(0, versionIndex) : nameAndVersion;
-    return `${scope}/${name}`;
-  }
-  const versionIndex = spec.indexOf("@");
-  return versionIndex >= 0 ? spec.slice(0, versionIndex) : spec;
-}
-
-/**
- * @param {string|null|undefined} spec
- * @returns {string|null}
- */
-export function packageScopeFromSpec(spec) {
-  if (!spec) {
-    return null;
-  }
-  const packageName = packageNameFromSpec(spec);
-  return packageName.startsWith("@") ? packageName.split("/")[0] : null;
-}
-
-/**
- * @param {unknown} value
- * @returns {TemplateManifest}
- */
-function validateTemplateManifest(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${TEMPLATE_MANIFEST} must contain a JSON object.`);
-  }
-  const manifest = /** @type {Record<string, unknown>} */ (value);
-  for (const field of ["id", "version", "kind", "topogramVersion"]) {
-    if (typeof manifest[field] !== "string" || !manifest[field]) {
-      throw new Error(`${TEMPLATE_MANIFEST} is missing required string field '${field}'.`);
-    }
-  }
-  if (manifest.kind !== "starter") {
-    throw new Error(`${TEMPLATE_MANIFEST} kind must be 'starter'.`);
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(manifest, "includesExecutableImplementation") &&
-    typeof manifest.includesExecutableImplementation !== "boolean"
-  ) {
-    throw new Error(`${TEMPLATE_MANIFEST} field 'includesExecutableImplementation' must be a boolean.`);
-  }
-  if (Object.prototype.hasOwnProperty.call(manifest, "starterScripts")) {
-    if (!manifest.starterScripts || typeof manifest.starterScripts !== "object" || Array.isArray(manifest.starterScripts)) {
-      throw new Error(`${TEMPLATE_MANIFEST} field 'starterScripts' must be an object of package.json script names to commands.`);
-    }
-    for (const [scriptName, command] of Object.entries(manifest.starterScripts)) {
-      if (typeof scriptName !== "string" || !scriptName.trim() || scriptName.startsWith("-") || scriptName.includes("\n")) {
-        throw new Error(`${TEMPLATE_MANIFEST} starterScripts contains an invalid script name.`);
-      }
-      if (typeof command !== "string" || !command.trim()) {
-        throw new Error(`${TEMPLATE_MANIFEST} starterScripts.${scriptName} must be a non-empty string.`);
-      }
-    }
-  }
-  return /** @type {TemplateManifest} */ (manifest);
-}
-
-/**
- * @param {string} templateRoot
- * @returns {TemplateManifest}
- */
-function readTemplateManifest(templateRoot) {
-  const manifestPath = path.join(templateRoot, TEMPLATE_MANIFEST);
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`Template at '${templateRoot}' is missing ${TEMPLATE_MANIFEST}.`);
-  }
-  return validateTemplateManifest(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
-}
-
-/**
- * @param {string} root
- * @param {string} currentDir
- * @param {string} label
- * @param {string} templateId
- * @returns {void}
- */
-function assertTemplateTreeHasNoSymlinks(root, currentDir, label, templateId) {
-  const rootStat = fs.lstatSync(currentDir);
-  const relativeRoot = path.relative(root, currentDir).replace(/\\/g, "/") || label;
-  if (rootStat.isSymbolicLink()) {
-    throw new Error(unsupportedTemplateSymlinkMessage(templateId, relativeRoot));
-  }
-  if (!rootStat.isDirectory()) {
-    return;
-  }
-  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
-    const entryPath = path.join(currentDir, entry.name);
-    const relativePath = path.relative(root, entryPath).replace(/\\/g, "/");
-    if (entry.isSymbolicLink()) {
-      throw new Error(unsupportedTemplateSymlinkMessage(templateId, relativePath));
-    }
-    if (entry.isDirectory()) {
-      assertTemplateTreeHasNoSymlinks(root, entryPath, label, templateId);
-    }
-  }
-}
-
-/**
- * @param {string} templateRoot
- * @returns {TemplateManifest}
- */
-function validateTemplateRoot(templateRoot) {
-  const manifest = readTemplateManifest(templateRoot);
-  const topogramRoot = path.join(templateRoot, "topogram");
-  const projectConfigPath = path.join(templateRoot, "topogram.project.json");
-  if (fs.existsSync(topogramRoot) && fs.lstatSync(topogramRoot).isSymbolicLink()) {
-    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram"));
-  }
-  if (fs.existsSync(projectConfigPath) && fs.lstatSync(projectConfigPath).isSymbolicLink()) {
-    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram.project.json"));
-  }
-  if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
-    throw new Error(`Template '${manifest.id}' is missing topogram/.`);
-  }
-  if (!fs.existsSync(projectConfigPath) || !fs.statSync(projectConfigPath).isFile()) {
-    throw new Error(`Template '${manifest.id}' is missing topogram.project.json.`);
-  }
-  assertTemplateTreeHasNoSymlinks(templateRoot, topogramRoot, "topogram", manifest.id);
-  if (manifest.includesExecutableImplementation) {
-    const implementationRoot = path.join(templateRoot, "implementation");
-    if (fs.existsSync(implementationRoot) && fs.lstatSync(implementationRoot).isSymbolicLink()) {
-      throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "implementation"));
-    }
-    if (!fs.existsSync(implementationRoot) || !fs.statSync(implementationRoot).isDirectory()) {
-      throw new Error(
-        `Template '${manifest.id}' declares executable implementation code but is missing implementation/.`
-      );
-    }
-    assertTemplateTreeHasNoSymlinks(templateRoot, implementationRoot, "implementation", manifest.id);
-  } else {
-    const implementationRoot = path.join(templateRoot, "implementation");
-    if (fs.existsSync(implementationRoot) && fs.statSync(implementationRoot).isDirectory()) {
-      throw new Error(
-        `Template '${manifest.id}' contains implementation/ but ${TEMPLATE_MANIFEST} does not declare includesExecutableImplementation: true.`
-      );
-    }
-  }
-  return manifest;
-}
-
-/**
- * @param {string} generatorId
- * @returns {string}
- */
-function generatorLabel(generatorId) {
-  return GENERATOR_LABELS.get(generatorId) || generatorId.replace(/^topogram\//, "");
-}
-
-/**
- * @param {string} templateRoot
- * @returns {TemplateTopologySummary}
- */
-function summarizeTemplateTopology(templateRoot) {
-  const projectConfigPath = path.join(templateRoot, "topogram.project.json");
-  const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, "utf8"));
-  const rawRuntimes = /** @type {any[]} */ (
-    Array.isArray(projectConfig.topology?.runtimes) ? projectConfig.topology.runtimes : []
-  );
-  /** @type {Array<Record<string, any>>} */
-  const runtimes = [];
-  for (const runtime of rawRuntimes) {
-    if (runtime && typeof runtime === "object" && typeof runtime.kind === "string") {
-      runtimes.push(/** @type {Record<string, any>} */ (runtime));
-    }
-  }
-  const sortedRuntimes = [...runtimes].sort((a, b) => {
-    const aOrder = SURFACE_ORDER.get(a.kind) ?? 100;
-    const bOrder = SURFACE_ORDER.get(b.kind) ?? 100;
-    return aOrder - bOrder;
-  });
-  const surfaces = [...new Set(sortedRuntimes.map((runtime) => String(runtime.kind)))];
-  const generators = [
-    ...new Set(
-      sortedRuntimes
-        .map((runtime) => runtime.generator?.id)
-        .filter((generatorId) => typeof generatorId === "string")
-        .map((generatorId) => String(generatorId))
-    )
-  ];
-  return {
-    surfaces,
-    generators,
-    stack: generators.map(generatorLabel).join(" + ")
-  };
-}
-
-/**
- * @param {string} templateSpec
- * @returns {string}
- */
-export function installPackageSpec(templateSpec) {
-  assertSafeNpmSpec(templateSpec);
-  const installRoot = fs.mkdtempSync(path.join(os.tmpdir(), "topogram-template-"));
-  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
-  const result = childProcess.spawnSync(
-    npmBin,
-    [
-      "install",
-      "--prefix",
-      installRoot,
-      "--ignore-scripts",
-      "--no-audit",
-      "--no-fund",
-      "--package-lock=false",
-      "--",
-      templateSpec
-    ],
-    {
-      encoding: "utf8",
-      env: {
-        ...process.env,
-        ...localNpmrcEnv(process.cwd()),
-        PATH: process.env.PATH || ""
-      }
-    }
-  );
-  if (result.status !== 0) {
-    throw new Error(formatPackageInstallError(templateSpec, result));
-  }
-  const packageRoot = path.join(installRoot, "node_modules", packageNameFromSpec(templateSpec));
-  if (fs.existsSync(packageRoot)) {
-    return packageRoot;
-  }
-  return findInstalledTemplatePackageRoot(installRoot, templateSpec);
-}
-
-/**
- * @param {string} templateSpec
- * @param {any} result
- * @returns {string}
- */
-function formatPackageInstallError(templateSpec, result) {
-  const output = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
-  const normalized = output.toLowerCase();
-  const npmrcHint = "Ensure npm can access the registry required by this template package. Topogram ignores project .npmrc files unless TOPOGRAM_ALLOW_LOCAL_NPMRC=1 or --allow-local-npmrc is used.";
-  const packageAccessHint = "For private package registries, configure a token with package read access.";
-  const authHint = "For private template packages, configure npm auth for the package registry before installing.";
-  const doctorHint = "Run `topogram doctor` to check Node.js, npm, package, and catalog access.";
-  if (result.error?.code === "ENOENT") {
-    return [
-      `Failed to install template package '${templateSpec}': npm was not found.`,
-      "Install Node.js/npm and retry."
-    ].join("\n");
-  }
-  if (/\b(e401|eneedauth)\b/.test(normalized) || normalized.includes("unauthenticated") || normalized.includes("authentication required")) {
-    return [
-      `Authentication is required to install template package '${templateSpec}'.`,
-      authHint,
-      npmrcHint,
-      packageAccessHint,
-      doctorHint,
-      output
-    ].filter(Boolean).join("\n");
-  }
-  if (/\be403\b/.test(normalized) || normalized.includes("forbidden") || normalized.includes("permission")) {
-    return [
-      `Package access was denied while installing template package '${templateSpec}'.`,
-      authHint,
-      packageAccessHint,
-      doctorHint,
-      output
-    ].filter(Boolean).join("\n");
-  }
-  if (/\b(e404|404)\b/.test(normalized) || normalized.includes("not found")) {
-    return [
-      `Template package '${templateSpec}' was not found, or the current token does not have access to it.`,
-      "Check the package name/version and registry access.",
-      packageAccessHint,
-      doctorHint,
-      output
-    ].filter(Boolean).join("\n");
-  }
-  if (/\beintegrity\b/.test(normalized) || normalized.includes("integrity checksum failed")) {
-    return [
-      `Package integrity failed while installing template package '${templateSpec}'.`,
-      "Refresh package-lock.json from the published registry tarball instead of a local npm pack tarball.",
-      output
-    ].filter(Boolean).join("\n");
-  }
-  return `Failed to install template package '${templateSpec}'.\n${output || "unknown error"}`.trim();
-}
-
-/**
- * @param {string} installRoot
- * @param {string} templateSpec
- * @returns {string}
- */
-function findInstalledTemplatePackageRoot(installRoot, templateSpec) {
-  const nodeModules = path.join(installRoot, "node_modules");
-  if (!fs.existsSync(nodeModules)) {
-    throw new Error(`Template package '${templateSpec}' did not create node_modules.`);
-  }
-  /** @type {string[]} */
-  const candidates = [];
-  for (const entry of fs.readdirSync(nodeModules)) {
-    if (entry === ".bin") {
-      continue;
-    }
-    const entryPath = path.join(nodeModules, entry);
-    if (entry.startsWith("@")) {
-      for (const scopedEntry of fs.readdirSync(entryPath)) {
-        candidates.push(path.join(entryPath, scopedEntry));
-      }
-      continue;
-    }
-    candidates.push(entryPath);
-  }
-  const templateRoots = candidates.filter((candidate) =>
-    fs.existsSync(path.join(candidate, TEMPLATE_MANIFEST))
-  );
-  if (templateRoots.length === 1) {
-    return templateRoots[0];
-  }
-  if (templateRoots.length > 1) {
-    throw new Error(`Template package '${templateSpec}' installed multiple template manifests.`);
-  }
-  throw new Error(`Template package '${templateSpec}' did not install a package with ${TEMPLATE_MANIFEST}.`);
-}
-
-/**
- * @param {string} templateName
- * @param {string} templatesRoot
- * @returns {ResolvedTemplate}
- */
-export function resolveTemplate(templateName, templatesRoot) {
-  void templatesRoot;
-
-  if (isLocalTemplateSpec(templateName)) {
-    const templateRoot = path.resolve(templateName);
-    if (!fs.existsSync(templateRoot)) {
-      throw new Error(`Local template path '${templateName}' does not exist.`);
-    }
-    if (!fs.statSync(templateRoot).isDirectory()) {
-      const packageTemplateRoot = installPackageSpec(templateName);
-      return {
-        requested: templateName,
-        root: packageTemplateRoot,
-        manifest: validateTemplateRoot(packageTemplateRoot),
-        source: "package",
-        packageSpec: templateName
-      };
-    }
-    return {
-      requested: templateName,
-      root: templateRoot,
-      manifest: validateTemplateRoot(templateRoot),
-      source: "local",
-      packageSpec: null
-    };
-  }
-
-  const templateRoot = installPackageSpec(templateName);
-  if (!fs.existsSync(templateRoot)) {
-    throw new Error(`Template package '${templateName}' did not install to '${templateRoot}'.`);
-  }
-  return {
-    requested: templateName,
-    root: templateRoot,
-    manifest: validateTemplateRoot(templateRoot),
-    source: "package",
-    packageSpec: templateName
-  };
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} engineRoot
- * @returns {void}
- */
-function assertProjectOutsideEngine(projectRoot, engineRoot) {
-  if (isSameOrInside(path.resolve(engineRoot), path.resolve(projectRoot))) {
-    throw new Error(
-      `Refusing to create a generated project inside the engine directory. Use a path outside engine, for example '../${path.basename(projectRoot)}'.`
-    );
-  }
-}
-
-/**
- * @param {string} projectRoot
- * @returns {void}
- */
-function ensureCreatableProjectRoot(projectRoot) {
-  if (!fs.existsSync(projectRoot)) {
-    fs.mkdirSync(projectRoot, { recursive: true });
-    return;
-  }
-  if (!fs.statSync(projectRoot).isDirectory()) {
-    throw new Error(`Cannot create project at '${projectRoot}' because it is not a directory.`);
-  }
-  /** @type {string[]} */
-  const dirEntries = fs.readdirSync(projectRoot);
-  const entries = dirEntries.filter((entry) => entry !== ".DS_Store");
-  if (entries.length > 0) {
-    throw new Error(`Refusing to create a Topogram project in non-empty directory '${projectRoot}'.`);
-  }
-}
-
-/**
- * @param {string} templateRoot
- * @param {string} projectRoot
- * @returns {void}
- */
-function copyTopogramWorkspace(templateRoot, projectRoot) {
-  const topogramRoot = path.join(projectRoot, "topogram");
-  fs.cpSync(path.join(templateRoot, "topogram"), topogramRoot, { recursive: true });
-
-  fs.cpSync(
-    path.join(templateRoot, "topogram.project.json"),
-    path.join(projectRoot, "topogram.project.json")
-  );
-  const implementationRoot = path.join(templateRoot, "implementation");
-  if (fs.existsSync(implementationRoot)) {
-    fs.cpSync(
-      implementationRoot,
-      path.join(projectRoot, "implementation"),
-      { recursive: true }
-    );
-  }
-}
-
-/**
- * @param {string} projectRoot
- * @param {ResolvedTemplate} template
- * @param {CatalogTemplateProvenance|null} [templateProvenance]
- * @returns {Record<string, any>}
- */
-function writeProjectTemplateMetadata(projectRoot, template, templateProvenance = null) {
-  const projectConfigPath = path.join(projectRoot, "topogram.project.json");
-  const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, "utf8"));
-  projectConfig.template = projectTemplateMetadata(template, templateProvenance);
-  fs.writeFileSync(projectConfigPath, `${stableJsonStringify(projectConfig)}\n`, "utf8");
-  return projectConfig;
-}
-
-/**
- * @param {ResolvedTemplate} template
- * @param {CatalogTemplateProvenance|null} [templateProvenance]
- * @returns {{ id: string, version: string, source: string, requested: string, sourceSpec: string, sourceRoot: string|null, includesExecutableImplementation: boolean, catalog?: CatalogTemplateProvenance }}
- */
-function projectTemplateMetadata(template, templateProvenance = null) {
-  /** @type {{ id: string, version: string, source: string, requested: string, sourceSpec: string, sourceRoot: string|null, includesExecutableImplementation: boolean, catalog?: CatalogTemplateProvenance }} */
-  const metadata = {
-    id: template.manifest.id,
-    version: template.manifest.version,
-    source: template.source,
-    requested: templateProvenance?.id || template.requested,
-    sourceSpec: template.packageSpec || template.requested,
-    sourceRoot: template.source === "local" ? template.root : null,
-    includesExecutableImplementation: Boolean(template.manifest.includesExecutableImplementation)
-  };
-  if (templateProvenance) {
-    metadata.catalog = templateProvenance;
-  }
-  return metadata;
-}
-
-/**
- * @param {Record<string, any>} input
- * @returns {TemplateUpdateDiagnostic}
- */
-function templateUpdateDiagnostic(input) {
-  return {
-    code: String(input.code || "template_update_failed"),
-    severity: input.severity === "warning" ? "warning" : "error",
-    message: String(input.message || "Template update failed."),
-    path: typeof input.path === "string" ? input.path : null,
-    suggestedFix: typeof input.suggestedFix === "string" ? input.suggestedFix : null,
-    step: typeof input.step === "string" ? input.step : null
-  };
-}
-
-/**
- * @param {unknown} value
- * @param {string} policyPath
- * @returns {TemplatePolicy}
- */
-function validateTemplatePolicy(value, policyPath) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${TEMPLATE_POLICY_FILE} must contain a JSON object.`);
-  }
-  const policy = /** @type {Record<string, unknown>} */ (value);
-  const version = typeof policy.version === "string" && policy.version ? policy.version : "0.1";
-  const allowedSources = Array.isArray(policy.allowedSources) ? policy.allowedSources : ["local", "package"];
-  const invalidSource = allowedSources.find((source) => !["local", "package"].includes(String(source)));
-  if (invalidSource) {
-    throw new Error(`${policyPath} has invalid allowedSources value '${String(invalidSource)}'.`);
-  }
-  const allowedTemplateIds = Array.isArray(policy.allowedTemplateIds)
-    ? policy.allowedTemplateIds.map(String).filter(Boolean)
-    : [];
-  const allowedPackageScopes = Array.isArray(policy.allowedPackageScopes)
-    ? policy.allowedPackageScopes.map(String).filter(Boolean)
-    : [];
-  const executableImplementation = policy.executableImplementation === "deny" || policy.executableImplementation === "warn"
-    ? policy.executableImplementation
-    : "allow";
-  const pinnedVersions = policy.pinnedVersions && typeof policy.pinnedVersions === "object" && !Array.isArray(policy.pinnedVersions)
-    ? Object.fromEntries(Object.entries(policy.pinnedVersions).filter(([, pin]) => typeof pin === "string"))
-    : {};
-  return {
-    version,
-    allowedSources: /** @type {Array<"local"|"package">} */ (allowedSources),
-    allowedTemplateIds,
-    allowedPackageScopes,
-    executableImplementation,
-    pinnedVersions
-  };
-}
-
-/**
- * @param {string} projectRoot
- * @returns {TemplatePolicyInfo}
- */
-export function loadTemplatePolicy(projectRoot) {
-  const policyPath = path.join(projectRoot, TEMPLATE_POLICY_FILE);
-  if (!fs.existsSync(policyPath)) {
-    return {
-      path: policyPath,
-      policy: null,
-      exists: false,
-      diagnostics: []
-    };
-  }
-  try {
-    return {
-      path: policyPath,
-      policy: validateTemplatePolicy(JSON.parse(fs.readFileSync(policyPath, "utf8")), policyPath),
-      exists: true,
-      diagnostics: []
-    };
-  } catch (error) {
-    return {
-      path: policyPath,
-      policy: null,
-      exists: true,
-      diagnostics: [templateUpdateDiagnostic({
-        code: "template_policy_invalid",
-        message: error instanceof Error ? error.message : String(error),
-        path: policyPath,
-        suggestedFix: "Fix topogram.template-policy.json or regenerate it with `topogram template policy init`.",
-        step: "policy"
-      })]
-    };
-  }
-}
-
-/**
- * @param {ResolvedTemplate} template
- * @returns {TemplatePolicy}
- */
-function defaultTemplatePolicyForTemplate(template) {
-  const allowedPackageScopes = [];
-  const idScope = template.source === "package"
-    ? packageScopeFromSpec(template.packageSpec || template.requested)
-    : null;
-  if (template.source === "package" && idScope) {
-    allowedPackageScopes.push(idScope);
-  }
-  return {
-    version: "0.1",
-    allowedSources: ["local", "package"],
-    allowedTemplateIds: [template.manifest.id],
-    allowedPackageScopes,
-    executableImplementation: "allow",
-    pinnedVersions: {}
-  };
-}
-
-/**
- * @param {string} projectRoot
- * @param {TemplatePolicy} policy
- * @returns {TemplatePolicy}
- */
-export function writeTemplatePolicy(projectRoot, policy) {
-  fs.writeFileSync(path.join(projectRoot, TEMPLATE_POLICY_FILE), `${stableJsonStringify(policy)}\n`, "utf8");
-  return policy;
-}
-
-/**
- * @param {string} projectRoot
- * @param {Record<string, any>} projectConfig
- * @returns {TemplatePolicy}
- */
-export function writeTemplatePolicyForProject(projectRoot, projectConfig) {
-  const current = currentTemplateMetadata(projectConfig);
-  /** @type {string[]} */
-  const allowedPackageScopes = [];
-  if (current.source === "package") {
-    const currentScope = packageScopeFromSpec(current.sourceSpec) ||
-      (current.id?.startsWith("@") ? current.id.split("/")[0] : null);
-    if (currentScope) {
-      allowedPackageScopes.push(currentScope);
-    }
-  }
-  return writeTemplatePolicy(projectRoot, {
-    version: "0.1",
-    allowedSources: ["local", "package"],
-    allowedTemplateIds: current.id ? [current.id] : [],
-    allowedPackageScopes,
-    executableImplementation: "allow",
-    pinnedVersions: {}
-  });
-}
-
-/**
- * @param {TemplatePolicyInfo} policyInfo
- * @param {ResolvedTemplate} template
- * @param {string} step
- * @returns {TemplateUpdateDiagnostic[]}
- */
-export function templatePolicyDiagnosticsForTemplate(policyInfo, template, step) {
-  if (policyInfo.diagnostics.length > 0) {
-    return policyInfo.diagnostics;
-  }
-  if (!policyInfo.policy) {
-    return [];
-  }
-  const policy = policyInfo.policy;
-  /** @type {TemplateUpdateDiagnostic[]} */
-  const diagnostics = [];
-  if (policy.allowedSources.length > 0 && !policy.allowedSources.includes(template.source)) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_source_denied",
-      message: `Template source '${template.source}' is not allowed by ${TEMPLATE_POLICY_FILE}.`,
-      path: policyInfo.path,
-      suggestedFix: `Run \`topogram template policy init\` to reset from the current project, or add '${template.source}' to allowedSources after review.`,
-      step
-    }));
-  }
-  if (policy.allowedTemplateIds.length > 0 && !policy.allowedTemplateIds.includes(template.manifest.id)) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_id_denied",
-      message: `Template '${template.manifest.id}' is not allowed by ${TEMPLATE_POLICY_FILE}.`,
-      path: policyInfo.path,
-      suggestedFix: `Run \`topogram template policy pin ${template.manifest.id}@${template.manifest.version}\` after review, or choose an allowed template.`,
-      step
-    }));
-  }
-  if (template.source === "package" && policy.allowedPackageScopes && policy.allowedPackageScopes.length > 0) {
-    const scope = packageScopeFromSpec(template.packageSpec || template.requested) ||
-      (template.manifest.id.startsWith("@") ? template.manifest.id.split("/")[0] : null);
-    if (!scope || !policy.allowedPackageScopes.includes(scope)) {
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_package_scope_denied",
-        message: `Template package scope '${scope || "(unscoped)"}' is not allowed by ${TEMPLATE_POLICY_FILE}.`,
-        path: policyInfo.path,
-        suggestedFix: `Add '${scope || "(unscoped)"}' to allowedPackageScopes after review, or choose a package from an allowed scope.`,
-        step
-      }));
-    }
-  }
-  const pinnedVersion = policy.pinnedVersions?.[template.manifest.id];
-  if (pinnedVersion && pinnedVersion !== template.manifest.version) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_version_mismatch",
-      message: `Template '${template.manifest.id}' is pinned to version '${pinnedVersion}', but candidate version is '${template.manifest.version}'.`,
-      path: policyInfo.path,
-      suggestedFix: `Run \`topogram template policy pin ${template.manifest.id}@${template.manifest.version}\` after review, or use version '${pinnedVersion}'.`,
-      step
-    }));
-  }
-  if (template.manifest.includesExecutableImplementation) {
-    if (policy.executableImplementation === "deny") {
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_executable_denied",
-        message: `Template '${template.manifest.id}' includes executable implementation code, which is denied by ${TEMPLATE_POLICY_FILE}.`,
-        path: policyInfo.path,
-        suggestedFix: "Use a non-executable template, or set executableImplementation to 'allow' after reviewing implementation/.",
-        step
-      }));
-    } else if (policy.executableImplementation === "warn") {
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_executable_warning",
-        severity: "warning",
-        message: `Template '${template.manifest.id}' includes executable implementation code.`,
-        path: policyInfo.path,
-        suggestedFix: "Review implementation/ before running topogram generate.",
-        step
-      }));
-    }
-  }
-  return diagnostics;
-}
-
-/**
- * @param {string} projectRoot
- * @param {ResolvedTemplate} template
- * @param {string} step
- * @returns {TemplateUpdateDiagnostic[]}
- */
-function templatePolicyDiagnosticsForProject(projectRoot, template, step) {
-  return templatePolicyDiagnosticsForTemplate(loadTemplatePolicy(projectRoot), template, step);
-}
-
-/**
- * @param {TemplateUpdateDiagnostic[]} diagnostics
- * @returns {string[]}
- */
-function issueMessagesFromDiagnostics(diagnostics) {
-  return diagnostics
-    .filter((diagnostic) => diagnostic.severity === "error")
-    .map((diagnostic) => diagnostic.message);
-}
-
-/**
- * @param {Record<string, any>} projectConfig
- * @returns {{ id: string|null, version: string|null, source: string|null, sourceSpec: string|null, requested: string|null }}
- */
-function currentTemplateMetadata(projectConfig) {
-  const currentTemplate = projectConfig.template || {};
-  return {
-    id: typeof currentTemplate.id === "string" ? currentTemplate.id : null,
-    version: typeof currentTemplate.version === "string" ? currentTemplate.version : null,
-    source: typeof currentTemplate.source === "string" ? currentTemplate.source : null,
-    sourceSpec: typeof currentTemplate.sourceSpec === "string" ? currentTemplate.sourceSpec : null,
-    requested: typeof currentTemplate.requested === "string" ? currentTemplate.requested : null
-  };
-}
-
-/**
- * @param {string} filePath
- * @returns {string}
- */
-function normalizeTemplateUpdateActionPath(filePath) {
-  const normalized = path.posix.normalize(filePath.replace(/\\/g, "/"));
-  if (
-    !filePath ||
-    path.isAbsolute(filePath) ||
-    normalized === "." ||
-    normalized.startsWith("../") ||
-    normalized === ".."
-  ) {
-    throw new Error(`Template update action requires a relative template-owned file path: ${filePath || "(missing)"}`);
-  }
-  return normalized;
-}
-
-/**
- * @param {any} bytes
- * @returns {boolean}
- */
-function isLikelyText(bytes) {
-  if (bytes.includes(0)) {
-    return false;
-  }
-  const length = Math.min(bytes.length, 4096);
-  let suspicious = 0;
-  for (let index = 0; index < length; index += 1) {
-    const byte = bytes[index];
-    if (byte === 9 || byte === 10 || byte === 13) {
-      continue;
-    }
-    if (byte < 32 || byte === 127) {
-      suspicious += 1;
-    }
-  }
-  return length === 0 || suspicious / length < 0.02;
-}
-
-/**
- * @param {string} text
- * @returns {string[]}
- */
-function linesForDiff(text) {
-  const lines = text.split("\n");
-  if (lines.at(-1) === "") {
-    lines.pop();
-  }
-  return lines;
-}
-
-/**
- * @param {string[]} before
- * @param {string[]} after
- * @returns {Array<{ type: "same"|"added"|"removed", text: string }>}
- */
-function diffLines(before, after) {
-  const rows = before.length;
-  const columns = after.length;
-  /** @type {number[][]} */
-  const table = Array.from({ length: rows + 1 }, () => Array(columns + 1).fill(0));
-  for (let row = rows - 1; row >= 0; row -= 1) {
-    for (let column = columns - 1; column >= 0; column -= 1) {
-      table[row][column] = before[row] === after[column]
-        ? table[row + 1][column + 1] + 1
-        : Math.max(table[row + 1][column], table[row][column + 1]);
-    }
-  }
-  /** @type {Array<{ type: "same"|"added"|"removed", text: string }>} */
-  const changes = [];
-  let row = 0;
-  let column = 0;
-  while (row < rows && column < columns) {
-    if (before[row] === after[column]) {
-      changes.push({ type: "same", text: before[row] });
-      row += 1;
-      column += 1;
-    } else if (table[row + 1][column] >= table[row][column + 1]) {
-      changes.push({ type: "removed", text: before[row] });
-      row += 1;
-    } else {
-      changes.push({ type: "added", text: after[column] });
-      column += 1;
-    }
-  }
-  while (row < rows) {
-    changes.push({ type: "removed", text: before[row] });
-    row += 1;
-  }
-  while (column < columns) {
-    changes.push({ type: "added", text: after[column] });
-    column += 1;
-  }
-  return changes;
-}
-
-/**
- * @param {string} relativePath
- * @param {string|null} beforeText
- * @param {string|null} afterText
- * @returns {string|null}
- */
-function unifiedTextDiff(relativePath, beforeText, afterText) {
-  if (beforeText === null && afterText === null) {
-    return null;
-  }
-  const beforeLines = beforeText === null ? [] : linesForDiff(beforeText);
-  const afterLines = afterText === null ? [] : linesForDiff(afterText);
-  const changes = diffLines(beforeLines, afterLines);
-  const lines = [
-    `--- current/${relativePath}`,
-    `+++ candidate/${relativePath}`,
-    `@@ -1,${beforeLines.length} +1,${afterLines.length} @@`
-  ];
-  for (const change of changes) {
-    const prefix = change.type === "added" ? "+" : change.type === "removed" ? "-" : " ";
-    lines.push(`${prefix}${change.text}`);
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-/**
- * @param {string} value
- * @returns {number}
- */
-function utf8ByteLength(value) {
-  let length = 0;
-  for (const char of value) {
-    const codePoint = char.codePointAt(0) || 0;
-    if (codePoint <= 0x7f) {
-      length += 1;
-    } else if (codePoint <= 0x7ff) {
-      length += 2;
-    } else if (codePoint <= 0xffff) {
-      length += 3;
-    } else {
-      length += 4;
-    }
-  }
-  return length;
-}
-
-/**
- * @param {any} value
- * @returns {any}
- */
-function sortJsonValue(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJsonValue);
-  }
-  if (value && typeof value === "object") {
-    /** @type {Record<string, any>} */
-    const sorted = {};
-    for (const key of Object.keys(value).sort((left, right) => left.localeCompare(right))) {
-      sorted[key] = sortJsonValue(value[key]);
-    }
-    return sorted;
-  }
-  return value;
-}
-
-/**
- * @param {any} value
- * @returns {string}
- */
-function stableJsonStringify(value) {
-  return JSON.stringify(sortJsonValue(value), null, 2);
-}
-
-/**
- * @param {string} root
- * @param {string} currentDir
- * @param {string[]} files
- * @returns {void}
- */
-function collectFiles(root, currentDir, files) {
-  if (!fs.existsSync(currentDir)) {
-    return;
-  }
-  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
-    if (entry.name === ".DS_Store" || entry.name === "node_modules" || entry.name === ".tmp") {
-      continue;
-    }
-    const entryPath = path.join(currentDir, entry.name);
-    if (entry.isSymbolicLink()) {
-      throw new Error(`Template-owned files cannot include symlink '${path.relative(root, entryPath).replace(/\\/g, "/")}'. Template-owned files must be real files so Topogram can hash the exact content being trusted. Replace the symlink with a real file, then run topogram trust status, topogram trust diff, and topogram trust template after review.`);
-    }
-    if (entry.isDirectory()) {
-      collectFiles(root, entryPath, files);
-      continue;
-    }
-    if (entry.isFile()) {
-      files.push(path.relative(root, entryPath).replace(/\\/g, "/"));
-    }
-  }
-}
-
-/**
- * @param {string|null} absolutePath
- * @param {string|null} content
- * @returns {{ sha256: string, size: number, text: string|null, binary: boolean, diffOmitted: boolean }|null}
- */
-function fileSnapshot(absolutePath, content = null) {
-  if (!absolutePath && content === null) {
-    return null;
-  }
-  if (content !== null) {
-    return {
-      sha256: crypto.createHash("sha256").update(content, "utf8").digest("hex"),
-      size: utf8ByteLength(content),
-      text: content,
-      binary: false,
-      diffOmitted: false
-    };
-  }
-  const bytes = fs.readFileSync(absolutePath || "");
-  const sha256 = crypto.createHash("sha256").update(bytes).digest("hex");
-  if (bytes.length > MAX_TEXT_DIFF_BYTES) {
-    return { sha256, size: bytes.length, text: null, binary: false, diffOmitted: true };
-  }
-  if (!isLikelyText(bytes)) {
-    return { sha256, size: bytes.length, text: null, binary: true, diffOmitted: false };
-  }
-  return { sha256, size: bytes.length, text: bytes.toString("utf8"), binary: false, diffOmitted: false };
-}
-
-/**
- * @param {{ absolutePath: string|null, content: string|null }} file
- * @returns {{ sha256: string, size: number }}
- */
-function fileHash(file) {
-  const snapshot = fileSnapshot(file.absolutePath, file.content);
-  if (!snapshot) {
-    throw new Error("Cannot hash missing template-owned file.");
-  }
-  return {
-    sha256: snapshot.sha256,
-    size: snapshot.size
-  };
-}
-
-/**
- * @param {ResolvedTemplate} template
- * @param {Record<string, any>|null} [currentProjectConfig]
- * @returns {Map<string, { path: string, content: string|null, absolutePath: string|null }>}
- */
-function candidateTemplateFiles(template, currentProjectConfig = null) {
-  const files = new Map();
-  for (const rootName of ["topogram", "implementation"]) {
-    const root = path.join(template.root, rootName);
-    if (!fs.existsSync(root)) {
-      continue;
-    }
-    /** @type {string[]} */
-    const relativeFiles = [];
-    collectFiles(template.root, root, relativeFiles);
-    for (const relativePath of relativeFiles) {
-      files.set(relativePath, {
-        path: relativePath,
-        content: null,
-        absolutePath: path.join(template.root, relativePath)
-      });
-    }
-  }
-  const candidateProjectConfig = JSON.parse(fs.readFileSync(path.join(template.root, "topogram.project.json"), "utf8"));
-  candidateProjectConfig.template = candidateProjectTemplateMetadata(template, currentProjectConfig);
-  files.set("topogram.project.json", {
-    path: "topogram.project.json",
-    content: `${stableJsonStringify(candidateProjectConfig)}\n`,
-    absolutePath: null
-  });
-  return files;
-}
-
-/**
- * @param {ResolvedTemplate} template
- * @param {Record<string, any>|null} currentProjectConfig
- * @returns {ReturnType<typeof projectTemplateMetadata>}
- */
-function candidateProjectTemplateMetadata(template, currentProjectConfig) {
-  const metadata = projectTemplateMetadata(template);
-  const currentTemplate = currentProjectConfig?.template || null;
-  if (!currentTemplate || currentTemplate.id !== metadata.id) {
-    return metadata;
-  }
-  if (typeof currentTemplate.requested === "string" && currentTemplate.requested) {
-    metadata.requested = currentTemplate.requested;
-  }
-  if (currentTemplate.catalog && typeof currentTemplate.catalog === "object") {
-    metadata.catalog = {
-      ...currentTemplate.catalog,
-      package: typeof currentTemplate.catalog.package === "string"
-        ? currentTemplate.catalog.package
-        : metadata.id,
-      version: metadata.version,
-      packageSpec: metadata.sourceSpec
-    };
-  }
-  return metadata;
-}
-
-/**
- * @param {string} projectRoot
- * @param {boolean} includeImplementation
- * @param {Record<string, any>} projectConfig
- * @returns {Map<string, { path: string, absolutePath: string|null, content: string|null }>}
- */
-function currentTemplateOwnedFiles(projectRoot, includeImplementation, projectConfig) {
-  const files = new Map();
-  for (const rootName of includeImplementation ? ["topogram", "implementation"] : ["topogram"]) {
-    const root = path.join(projectRoot, rootName);
-    if (!fs.existsSync(root)) {
-      continue;
-    }
-    /** @type {string[]} */
-    const relativeFiles = [];
-    collectFiles(projectRoot, root, relativeFiles);
-    for (const relativePath of relativeFiles) {
-      files.set(relativePath, {
-        path: relativePath,
-        absolutePath: path.join(projectRoot, relativePath),
-        content: null
-      });
-    }
-  }
-  const projectConfigPath = path.join(projectRoot, "topogram.project.json");
-  if (fs.existsSync(projectConfigPath)) {
-    files.set("topogram.project.json", {
-      path: "topogram.project.json",
-      absolutePath: projectConfigPath,
-      content: null
-    });
-  }
-  return files;
-}
-
-/**
- * @param {Record<string, any>} projectConfig
- * @returns {boolean}
- */
-function includesTemplateImplementation(projectConfig) {
-  const template = projectConfig.template || {};
-  return Boolean(
-    projectConfig.implementation ||
-    template.includesExecutableImplementation
-  );
-}
-
-/**
- * @param {string} projectRoot
- * @param {Record<string, any>} projectConfig
- * @returns {Map<string, TemplateOwnedFileRecord>}
- */
-function currentTemplateOwnedFileHashes(projectRoot, projectConfig) {
-  const files = currentTemplateOwnedFiles(projectRoot, includesTemplateImplementation(projectConfig), projectConfig);
-  return new Map([...files.entries()].map(([relativePath, file]) => {
-    const hash = fileHash(file);
-    return [relativePath, { path: relativePath, ...hash }];
-  }));
-}
-
-/**
- * @param {string} projectRoot
- * @returns {{ version: string, template: Record<string, any>, files: TemplateOwnedFileRecord[] }|null}
- */
-function readTemplateFilesManifest(projectRoot) {
-  const manifestPath = path.join(projectRoot, TEMPLATE_FILES_MANIFEST);
-  if (!fs.existsSync(manifestPath)) {
-    return null;
-  }
-  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-}
-
-/**
- * @param {string} projectRoot
- * @param {Record<string, any>} projectConfig
- * @returns {{ version: string, template: Record<string, any>, files: TemplateOwnedFileRecord[] }}
- */
-export function writeTemplateFilesManifest(projectRoot, projectConfig) {
-  const fileRecords = [...currentTemplateOwnedFileHashes(projectRoot, projectConfig).values()]
-    .sort((left, right) => left.path.localeCompare(right.path));
-  const manifest = {
-    version: "0.1",
-    template: {
-      id: projectConfig.template?.id || null,
-      version: projectConfig.template?.version || null,
-      source: projectConfig.template?.source || null,
-      sourceSpec: projectConfig.template?.sourceSpec || null,
-      requested: projectConfig.template?.requested || null,
-      catalog: projectConfig.template?.catalog || null
-    },
-    files: fileRecords
-  };
-  fs.writeFileSync(path.join(projectRoot, TEMPLATE_FILES_MANIFEST), `${stableJsonStringify(manifest)}\n`, "utf8");
-  return manifest;
-}
-
-/**
- * @param {string} projectRoot
- * @param {{ version: string, template: Record<string, any>, files: TemplateOwnedFileRecord[] }} manifest
- * @returns {void}
- */
-function writeTemplateFilesManifestData(projectRoot, manifest) {
-  const sortedManifest = {
-    ...manifest,
-    files: [...manifest.files].sort((left, right) => left.path.localeCompare(right.path))
-  };
-  fs.writeFileSync(path.join(projectRoot, TEMPLATE_FILES_MANIFEST), `${stableJsonStringify(sortedManifest)}\n`, "utf8");
-}
-
-/**
- * @param {string} projectRoot
- * @param {{ version: string, template: Record<string, any>, files: TemplateOwnedFileRecord[] }} manifest
- * @param {string} relativePath
- * @param {TemplateOwnedFileRecord|null} record
- * @returns {void}
- */
-function updateTemplateFilesManifestRecord(projectRoot, manifest, relativePath, record) {
-  const byPath = new Map(manifest.files.map((file) => [file.path, file]));
-  if (record) {
-    byPath.set(relativePath, record);
-  } else {
-    byPath.delete(relativePath);
-  }
-  writeTemplateFilesManifestData(projectRoot, {
-    ...manifest,
-    files: [...byPath.values()]
-  });
-}
-
-/**
- * @param {TemplateUpdatePlanOptions} options
- * @returns {{ ok: boolean, mode: "plan", writes: false, current: { id: string|null, version: string|null, source: string|null, sourceSpec: string|null, requested: string|null }, candidate: { id: string, version: string, source: string, sourceSpec: string, requested: string }, compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: { added: number, changed: number, currentOnly: number, unchanged: number }, files: Array<{ path: string, kind: "added"|"changed"|"current-only"|"unchanged", current: { sha256: string, size: number }|null, candidate: { sha256: string, size: number }|null, binary: boolean, diffOmitted: boolean, unifiedDiff: string|null }> }}
- */
-export function buildTemplateUpdatePlan({
-  projectRoot,
-  projectConfig,
-  templateName = null,
-  templatesRoot
-}) {
-  const currentTemplate = projectConfig.template || {};
-  const templateSpec = templateName || currentTemplate.sourceSpec || currentTemplate.requested || currentTemplate.id;
-  if (!templateSpec || typeof templateSpec !== "string") {
-    throw new Error("Cannot plan template update because topogram.project.json has no template source spec.");
-  }
-  const candidateTemplate = resolveTemplate(templateSpec, templatesRoot);
-  const candidateMetadata = projectTemplateMetadata(candidateTemplate);
-  /** @type {TemplateUpdateDiagnostic[]} */
-  const diagnostics = templatePolicyDiagnosticsForProject(projectRoot, candidateTemplate, "policy");
-  if (currentTemplate.id && currentTemplate.id !== candidateMetadata.id) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_id_mismatch",
-      message: `Candidate template id '${candidateMetadata.id}' does not match current template id '${currentTemplate.id}'.`,
-      path: path.join(projectRoot, "topogram.project.json"),
-      suggestedFix: "Use a template with the same id, or create a new project from the other template.",
-      step: "resolve-candidate"
-    }));
-  }
-  const candidateFiles = candidateTemplateFiles(candidateTemplate, projectConfig);
-  const currentFiles = currentTemplateOwnedFiles(
-    projectRoot,
-    Boolean(includesTemplateImplementation(projectConfig) || candidateMetadata.includesExecutableImplementation),
-    projectConfig
-  );
-  const allPaths = new Set([...candidateFiles.keys(), ...currentFiles.keys()]);
-  /** @type {Array<{ path: string, kind: "added"|"changed"|"current-only"|"unchanged", current: { sha256: string, size: number }|null, candidate: { sha256: string, size: number }|null, binary: boolean, diffOmitted: boolean, unifiedDiff: string|null }>} */
-  const files = [];
-
-  for (const relativePath of [...allPaths].sort((a, b) => a.localeCompare(b))) {
-    const candidateFile = candidateFiles.get(relativePath) || null;
-    const currentFile = currentFiles.get(relativePath) || null;
-    const candidateSnapshot = candidateFile
-      ? fileSnapshot(candidateFile.absolutePath, candidateFile.content)
-      : null;
-    const currentSnapshot = currentFile
-      ? fileSnapshot(currentFile.absolutePath, currentFile.content)
-      : null;
-    let kind = /** @type {"added"|"changed"|"current-only"|"unchanged"} */ ("unchanged");
-    if (!currentSnapshot && candidateSnapshot) {
-      kind = "added";
-    } else if (currentSnapshot && !candidateSnapshot) {
-      kind = "current-only";
-    } else if (currentSnapshot && candidateSnapshot && (
-      currentSnapshot.sha256 !== candidateSnapshot.sha256 ||
-      currentSnapshot.size !== candidateSnapshot.size
-    )) {
-      kind = "changed";
-    }
-    const binary = Boolean(currentSnapshot?.binary || candidateSnapshot?.binary);
-    const diffOmitted = binary || Boolean(currentSnapshot?.diffOmitted || candidateSnapshot?.diffOmitted);
-    files.push({
-      path: relativePath,
-      kind,
-      current: currentSnapshot ? { sha256: currentSnapshot.sha256, size: currentSnapshot.size } : null,
-      candidate: candidateSnapshot ? { sha256: candidateSnapshot.sha256, size: candidateSnapshot.size } : null,
-      binary,
-      diffOmitted,
-      unifiedDiff: diffOmitted
-        ? null
-        : unifiedTextDiff(relativePath, currentSnapshot?.text || null, candidateSnapshot?.text || null)
-    });
-  }
-  const visibleFiles = files.filter((file) => file.kind !== "unchanged");
-  const summary = {
-    added: visibleFiles.filter((file) => file.kind === "added").length,
-    changed: visibleFiles.filter((file) => file.kind === "changed").length,
-    currentOnly: visibleFiles.filter((file) => file.kind === "current-only").length,
-    unchanged: files.filter((file) => file.kind === "unchanged").length
-  };
-  const issues = issueMessagesFromDiagnostics(diagnostics);
-  return {
-    ok: issues.length === 0,
-    mode: "plan",
-    writes: false,
-    current: currentTemplateMetadata(projectConfig),
-    candidate: {
-      id: candidateMetadata.id,
-      version: candidateMetadata.version,
-      source: candidateMetadata.source,
-      sourceSpec: candidateMetadata.sourceSpec,
-      requested: candidateMetadata.requested
-    },
-    compatible: issues.length === 0,
-    issues,
-    diagnostics,
-    summary,
-    files: visibleFiles
-  };
-}
-
-/**
- * @param {TemplateUpdatePlanOptions} options
- * @returns {{ ok: boolean, mode: "check", writes: false, current: ReturnType<typeof buildTemplateUpdatePlan>["current"], candidate: ReturnType<typeof buildTemplateUpdatePlan>["candidate"], compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: ReturnType<typeof buildTemplateUpdatePlan>["summary"], files: ReturnType<typeof buildTemplateUpdatePlan>["files"] }}
- */
-export function buildTemplateUpdateCheck(options) {
-  const plan = buildTemplateUpdatePlan(options);
-  const diagnostics = [...plan.diagnostics];
-  if (plan.ok && plan.files.length > 0) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_update_available",
-      message: `Template update has ${plan.files.length} template-owned file change(s).`,
-      path: options.projectRoot,
-      suggestedFix: "Run `topogram template update --plan` to review, then `topogram template update --apply` after approval.",
-      step: "check"
-    }));
-  }
-  const issues = issueMessagesFromDiagnostics(diagnostics);
-  return {
-    ...plan,
-    ok: issues.length === 0,
-    mode: "check",
-    writes: false,
-    issues,
-    diagnostics
-  };
-}
-
-/**
- * @param {TemplateUpdatePlanOptions} options
- * @param {ReturnType<typeof buildTemplateUpdatePlan>} plan
- * @param {"apply"|"status"} mode
- * @returns {{ diagnostics: TemplateUpdateDiagnostic[], issues: string[], skipped: Array<{ path: string, kind: "current-only", reason: string }>, conflicts: Array<{ path: string, reason: string }> }}
- */
-function analyzeTemplateUpdateApplication(options, plan, mode) {
-  /** @type {Array<{ path: string, kind: "current-only", reason: string }>} */
-  const skipped = [];
-  /** @type {Array<{ path: string, reason: string }>} */
-  const conflicts = [];
-  /** @type {TemplateUpdateDiagnostic[]} */
-  const diagnostics = [...plan.diagnostics];
-  if (!plan.ok) {
-    return {
-      diagnostics,
-      issues: issueMessagesFromDiagnostics(diagnostics),
-      skipped,
-      conflicts
-    };
-  }
-
-  const baselineManifest = readTemplateFilesManifest(options.projectRoot);
-  if (!baselineManifest) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_baseline_missing",
-      message: `Cannot apply template update because ${TEMPLATE_FILES_MANIFEST} is missing. Review current template-owned files, then run 'topogram trust template' to record the baseline before applying template updates.`,
-      path: path.join(options.projectRoot, TEMPLATE_FILES_MANIFEST),
-      suggestedFix: "Review current template-owned files, then run `topogram trust template` to record the baseline before applying template updates.",
-      step: "baseline"
-    }));
-  }
-  const baselineByPath = new Map((baselineManifest?.files || []).map((file) => [file.path, file]));
-  const currentHashes = currentTemplateOwnedFileHashes(options.projectRoot, options.projectConfig);
-  for (const file of plan.files) {
-    if (file.kind === "current-only") {
-      skipped.push({
-        path: file.path,
-        kind: "current-only",
-        reason: "Deletes are not applied by template update --apply in this milestone."
-      });
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_current_only_skipped",
-        severity: "warning",
-        message: `Current-only file '${file.path}' needs manual delete review. Deletes are not applied by template update --apply in this milestone.`,
-        path: path.join(options.projectRoot, file.path),
-        suggestedFix: "Delete the file manually after review if it should be removed from this project.",
-        step: mode
-      }));
-      continue;
-    }
-    if (file.kind !== "added" && file.kind !== "changed") {
-      continue;
-    }
-    const baseline = baselineByPath.get(file.path) || null;
-    const currentHash = currentHashes.get(file.path) || null;
-    if (!fileMatchesBaseline(baseline, currentHash)) {
-      const reason = baseline
-        ? "Current file differs from the last trusted template-owned baseline."
-        : "Current file is not part of the trusted template-owned baseline.";
-      conflicts.push({
-        path: file.path,
-        reason
-      });
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_update_conflict",
-        message: `Template update conflict in '${file.path}': ${reason}`,
-        path: path.join(options.projectRoot, file.path),
-        suggestedFix: "Review local edits; keep them manually or refresh the baseline with `topogram trust template` after review.",
-        step: "conflict-check"
-      }));
-    }
-  }
-  return {
-    diagnostics,
-    issues: issueMessagesFromDiagnostics(diagnostics),
-    skipped,
-    conflicts
-  };
-}
-
-/**
- * @param {TemplateUpdatePlanOptions} options
- * @returns {{ ok: boolean, mode: "status", writes: false, current: ReturnType<typeof buildTemplateUpdatePlan>["current"], candidate: ReturnType<typeof buildTemplateUpdatePlan>["candidate"], compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: ReturnType<typeof buildTemplateUpdatePlan>["summary"], applied: Array<{ path: string, kind: "added"|"changed" }>, skipped: Array<{ path: string, kind: "current-only", reason: string }>, conflicts: Array<{ path: string, reason: string }>, files: ReturnType<typeof buildTemplateUpdatePlan>["files"] }}
- */
-export function buildTemplateUpdateStatus(options) {
-  const plan = buildTemplateUpdatePlan(options);
-  const analysis = analyzeTemplateUpdateApplication(options, plan, "status");
-  const diagnostics = [...analysis.diagnostics];
-  if (plan.ok && plan.files.length > 0) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_update_available",
-      message: `Template update has ${plan.files.length} template-owned file change(s).`,
-      path: options.projectRoot,
-      suggestedFix: "Run `topogram template update --plan` to review, then `topogram template update --apply` after approval.",
-      step: "status"
-    }));
-  }
-  const issues = issueMessagesFromDiagnostics(diagnostics);
-  return {
-    ...plan,
-    ok: issues.length === 0,
-    mode: "status",
-    writes: false,
-    issues,
-    diagnostics,
-    applied: [],
-    skipped: analysis.skipped,
-    conflicts: analysis.conflicts
-  };
-}
-
-/**
- * @param {{ absolutePath: string|null, content: string|null }} candidateFile
- * @param {string} destinationPath
- * @returns {void}
- */
-function writeCandidateFile(candidateFile, destinationPath) {
-  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-  if (candidateFile.content !== null) {
-    fs.writeFileSync(destinationPath, candidateFile.content, "utf8");
-    return;
-  }
-  if (!candidateFile.absolutePath) {
-    throw new Error(`Cannot apply template file without content or source path: ${destinationPath}`);
-  }
-  fs.cpSync(candidateFile.absolutePath, destinationPath);
-}
-
-/**
- * @param {TemplateOwnedFileRecord|null} baseline
- * @param {{ sha256: string, size: number }|null} currentHash
- * @returns {boolean}
- */
-function fileMatchesBaseline(baseline, currentHash) {
-  if (!baseline && !currentHash) {
-    return true;
-  }
-  if (!baseline || !currentHash) {
-    return false;
-  }
-  return baseline.sha256 === currentHash.sha256 && baseline.size === currentHash.size;
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} action
- * @returns {TemplateUpdateDiagnostic}
- */
-function templateBaselineMissingDiagnostic(projectRoot, action) {
-  return templateUpdateDiagnostic({
-    code: "template_baseline_missing",
-    message: `Cannot ${action} because ${TEMPLATE_FILES_MANIFEST} is missing. Review current template-owned files, then run 'topogram trust template' to record the baseline before applying template updates.`,
-    path: path.join(projectRoot, TEMPLATE_FILES_MANIFEST),
-    suggestedFix: "Review current template-owned files, then run `topogram trust template` to record the baseline before applying template updates.",
-    step: "baseline"
-  });
-}
-
-/**
- * @param {TemplateUpdateDiagnostic[]} diagnostics
- * @param {ReturnType<typeof buildTemplateUpdatePlan>|null} plan
- * @param {TemplateUpdateFileActionOptions["action"]} action
- * @param {string} relativePath
- * @param {Array<{ path: string, kind: "added"|"changed" }>} applied
- * @param {Array<{ path: string, kind: "accepted-current" }>} accepted
- * @param {Array<{ path: string, kind: "current-only" }>} deleted
- * @param {Array<{ path: string, reason: string }>} conflicts
- * @param {ReturnType<typeof currentTemplateMetadata>} [current]
- * @returns {{ ok: boolean, mode: TemplateUpdateFileActionOptions["action"], writes: boolean, current: ReturnType<typeof currentTemplateMetadata>, candidate: ReturnType<typeof buildTemplateUpdatePlan>["candidate"]|null, compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: ReturnType<typeof buildTemplateUpdatePlan>["summary"], applied: Array<{ path: string, kind: "added"|"changed" }>, accepted: Array<{ path: string, kind: "accepted-current" }>, deleted: Array<{ path: string, kind: "current-only" }>, skipped: Array<{ path: string, kind: "current-only", reason: string }>, conflicts: Array<{ path: string, reason: string }>, files: ReturnType<typeof buildTemplateUpdatePlan>["files"], action: TemplateUpdateFileActionOptions["action"], path: string }}
- */
-function templateUpdateFileActionResult(diagnostics, plan, action, relativePath, applied, accepted, deleted, conflicts, current = { id: null, version: null, source: null, sourceSpec: null, requested: null }) {
-  const issues = issueMessagesFromDiagnostics(diagnostics);
-  return {
-    ...(plan || {}),
-    ok: issues.length === 0,
-    mode: action,
-    writes: applied.length > 0 || accepted.length > 0 || deleted.length > 0,
-    current: plan?.current || current,
-    candidate: plan?.candidate || null,
-    compatible: plan?.compatible || issues.length === 0,
-    issues,
-    diagnostics,
-    summary: plan?.summary || { added: 0, changed: 0, currentOnly: 0, unchanged: 0 },
-    applied,
-    accepted,
-    deleted,
-    skipped: [],
-    conflicts,
-    files: plan?.files || [],
-    action,
-    path: relativePath
-  };
-}
-
-/**
- * @param {TemplateUpdateFileActionOptions} options
- * @returns {{ ok: boolean, mode: "accept-current"|"accept-candidate"|"delete-current", writes: boolean, current: ReturnType<typeof currentTemplateMetadata>, candidate: ReturnType<typeof buildTemplateUpdatePlan>["candidate"]|null, compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: ReturnType<typeof buildTemplateUpdatePlan>["summary"], applied: Array<{ path: string, kind: "added"|"changed" }>, accepted: Array<{ path: string, kind: "accepted-current" }>, deleted: Array<{ path: string, kind: "current-only" }>, skipped: Array<{ path: string, kind: "current-only", reason: string }>, conflicts: Array<{ path: string, reason: string }>, files: ReturnType<typeof buildTemplateUpdatePlan>["files"], action: "accept-current"|"accept-candidate"|"delete-current", path: string }}
- */
-export function applyTemplateUpdateFileAction(options) {
-  const relativePath = normalizeTemplateUpdateActionPath(options.filePath);
-  /** @type {TemplateUpdateDiagnostic[]} */
-  const diagnostics = [];
-  /** @type {Array<{ path: string, kind: "added"|"changed" }>} */
-  const applied = [];
-  /** @type {Array<{ path: string, kind: "accepted-current" }>} */
-  const accepted = [];
-  /** @type {Array<{ path: string, kind: "current-only" }>} */
-  const deleted = [];
-  /** @type {Array<{ path: string, reason: string }>} */
-  const conflicts = [];
-  const baselineManifest = readTemplateFilesManifest(options.projectRoot);
-  const current = currentTemplateMetadata(options.projectConfig);
-  if (!baselineManifest) {
-    diagnostics.push(templateBaselineMissingDiagnostic(options.projectRoot, options.action));
-    return templateUpdateFileActionResult(diagnostics, null, options.action, relativePath, applied, accepted, deleted, conflicts, current);
-  }
-
-  if (options.action === "accept-current") {
-    const currentHashes = currentTemplateOwnedFileHashes(options.projectRoot, options.projectConfig);
-    const currentHash = currentHashes.get(relativePath) || null;
-    if (!currentHash) {
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_file_not_current",
-        message: `Cannot accept current file '${relativePath}' because it is not a current template-owned file.`,
-        path: path.join(options.projectRoot, relativePath),
-        suggestedFix: "Pass a file under topogram/, topogram.project.json, or trusted implementation/.",
-        step: "accept-current"
-      }));
-      return templateUpdateFileActionResult(diagnostics, null, options.action, relativePath, applied, accepted, deleted, conflicts, current);
-    }
-    updateTemplateFilesManifestRecord(options.projectRoot, baselineManifest, relativePath, currentHash);
-    accepted.push({ path: relativePath, kind: "accepted-current" });
-    return templateUpdateFileActionResult(diagnostics, null, options.action, relativePath, applied, accepted, deleted, conflicts, current);
-  }
-
-  const plan = buildTemplateUpdatePlan(options);
-  diagnostics.push(...plan.diagnostics);
-  if (!plan.ok) {
-    return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-  }
-  const file = plan.files.find((item) => item.path === relativePath) || null;
-  if (!file) {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_file_unchanged",
-      message: `Template-owned file '${relativePath}' has no candidate update action.`,
-      path: path.join(options.projectRoot, relativePath),
-      suggestedFix: "Run `topogram template update --status` to see files that need adoption.",
-      step: options.action
-    }));
-    return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-  }
-
-  const baselineByPath = new Map(baselineManifest.files.map((record) => [record.path, record]));
-  const currentHashes = currentTemplateOwnedFileHashes(options.projectRoot, options.projectConfig);
-  const baseline = baselineByPath.get(relativePath) || null;
-  const currentHash = currentHashes.get(relativePath) || null;
-
-  if (options.action === "delete-current") {
-    if (file.kind !== "current-only") {
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_delete_not_current_only",
-        message: `Cannot delete '${relativePath}' because it is not a current-only template-owned file.`,
-        path: path.join(options.projectRoot, relativePath),
-        suggestedFix: "Use delete-current only for files the candidate template removed.",
-        step: "delete-current"
-      }));
-      return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-    }
-    if (!fileMatchesBaseline(baseline, currentHash)) {
-      const reason = baseline
-        ? "Current file differs from the last trusted template-owned baseline."
-        : "Current file is not part of the trusted template-owned baseline.";
-      conflicts.push({ path: relativePath, reason });
-      diagnostics.push(templateUpdateDiagnostic({
-        code: "template_update_conflict",
-        message: `Template delete conflict in '${relativePath}': ${reason}`,
-        path: path.join(options.projectRoot, relativePath),
-        suggestedFix: "Review local edits before deleting, or accept current as the new baseline.",
-        step: "delete-current"
-      }));
-      return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-    }
-    fs.rmSync(path.join(options.projectRoot, relativePath));
-    updateTemplateFilesManifestRecord(options.projectRoot, baselineManifest, relativePath, null);
-    deleted.push({ path: relativePath, kind: "current-only" });
-    return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-  }
-
-  if (file.kind !== "added" && file.kind !== "changed") {
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_candidate_not_applicable",
-      message: `Cannot accept candidate for '${relativePath}' because the candidate has no added or changed file.`,
-      path: path.join(options.projectRoot, relativePath),
-      suggestedFix: "Use accept-candidate only for added or changed candidate files.",
-      step: "accept-candidate"
-    }));
-    return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-  }
-  if (file.kind === "changed" && !fileMatchesBaseline(baseline, currentHash)) {
-    const reason = baseline
-      ? "Current file differs from the last trusted template-owned baseline."
-      : "Current file is not part of the trusted template-owned baseline.";
-    conflicts.push({ path: relativePath, reason });
-    diagnostics.push(templateUpdateDiagnostic({
-      code: "template_update_conflict",
-      message: `Template candidate conflict in '${relativePath}': ${reason}`,
-      path: path.join(options.projectRoot, relativePath),
-      suggestedFix: "Review local edits before accepting the candidate file.",
-      step: "accept-candidate"
-    }));
-    return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-  }
-  const currentTemplate = options.projectConfig.template || {};
-  const templateSpec = options.templateName || currentTemplate.sourceSpec || currentTemplate.requested || currentTemplate.id;
-  const candidateTemplate = resolveTemplate(templateSpec, options.templatesRoot);
-  const candidateFile = candidateTemplateFiles(candidateTemplate, options.projectConfig).get(relativePath);
-  if (!candidateFile) {
-    throw new Error(`Cannot accept missing candidate template file: ${relativePath}`);
-  }
-  writeCandidateFile(candidateFile, path.join(options.projectRoot, relativePath));
-  const nextHash = fileHash({
-    absolutePath: path.join(options.projectRoot, relativePath),
-    content: null
-  });
-  updateTemplateFilesManifestRecord(options.projectRoot, baselineManifest, relativePath, {
-    path: relativePath,
-    sha256: nextHash.sha256,
-    size: nextHash.size
-  });
-  applied.push({ path: relativePath, kind: file.kind });
-  return templateUpdateFileActionResult(diagnostics, plan, options.action, relativePath, applied, accepted, deleted, conflicts);
-}
-
-/**
- * @param {TemplateUpdatePlanOptions} options
- * @returns {{ ok: boolean, mode: "apply", writes: boolean, current: ReturnType<typeof buildTemplateUpdatePlan>["current"], candidate: ReturnType<typeof buildTemplateUpdatePlan>["candidate"], compatible: boolean, issues: string[], diagnostics: TemplateUpdateDiagnostic[], summary: ReturnType<typeof buildTemplateUpdatePlan>["summary"], applied: Array<{ path: string, kind: "added"|"changed" }>, skipped: Array<{ path: string, kind: "current-only", reason: string }>, conflicts: Array<{ path: string, reason: string }>, files: ReturnType<typeof buildTemplateUpdatePlan>["files"] }}
- */
-export function applyTemplateUpdate(options) {
-  const plan = buildTemplateUpdatePlan(options);
-  /** @type {Array<{ path: string, kind: "added"|"changed" }>} */
-  const applied = [];
-  const analysis = analyzeTemplateUpdateApplication(options, plan, "apply");
-  const { diagnostics, issues, skipped, conflicts } = analysis;
-  if (!plan.ok || issues.length > 0) {
-    return {
-      ...plan,
-      ok: false,
-      mode: "apply",
-      writes: false,
-      applied,
-      skipped,
-      conflicts,
-      issues,
-      diagnostics
-    };
-  }
-
-  const currentTemplate = options.projectConfig.template || {};
-  const templateSpec = options.templateName || currentTemplate.sourceSpec || currentTemplate.requested || currentTemplate.id;
-  const candidateTemplate = resolveTemplate(templateSpec, options.templatesRoot);
-  const candidateFiles = candidateTemplateFiles(candidateTemplate, options.projectConfig);
-  for (const file of plan.files) {
-    if (file.kind !== "added" && file.kind !== "changed") {
-      continue;
-    }
-    const candidateFile = candidateFiles.get(file.path);
-    if (!candidateFile) {
-      throw new Error(`Cannot apply missing candidate template file: ${file.path}`);
-    }
-    writeCandidateFile(candidateFile, path.join(options.projectRoot, file.path));
-    applied.push({ path: file.path, kind: file.kind });
-  }
-
-  if (applied.length > 0) {
-    const nextProjectConfig = JSON.parse(fs.readFileSync(path.join(options.projectRoot, "topogram.project.json"), "utf8"));
-    writeTemplateFilesManifest(options.projectRoot, nextProjectConfig);
-    if (nextProjectConfig.implementation) {
-      writeTemplateTrustRecord(options.projectRoot, nextProjectConfig);
-    }
-  }
-  return {
-    ...plan,
-    ok: true,
-    mode: "apply",
-    writes: applied.length > 0,
-    issues,
-    diagnostics,
-    applied,
-    skipped,
-    conflicts
-  };
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} engineRoot
- * @param {ResolvedTemplate} template
- * @returns {void}
- */
-function writeProjectPackage(projectRoot, engineRoot, template) {
-  const cliDependency = cliDependencyForProject(projectRoot, engineRoot);
-  const generatorDependencies = generatorDependenciesForTemplate(template.root);
-  const starterScripts = template.manifest.starterScripts || {};
-  const pkg = {
-    name: packageNameFromPath(projectRoot),
-    private: true,
-    type: "module",
-    scripts: {
-      explain: "node ./scripts/explain.mjs",
-      doctor: "topogram doctor",
-      "agent:brief": "topogram agent brief --json",
-      "source:status": "topogram source status --local",
-      "source:status:remote": "topogram source status --remote",
-      check: "topogram check",
-      "check:json": "topogram check --json",
-      "query:list": "topogram query list --json",
-      "query:show": "topogram query show",
-      generate: "topogram generate",
-      "template:explain": "topogram template explain",
-      "template:status": "topogram template status",
-      "template:detach": "topogram template detach",
-      "template:detach:dry-run": "topogram template detach --dry-run",
-      "template:policy:check": "topogram template policy check",
-      "template:policy:explain": "topogram template policy explain",
-      "generator:policy:status": "topogram generator policy status",
-      "generator:policy:check": "topogram generator policy check",
-      "generator:policy:explain": "topogram generator policy explain",
-      "template:update:status": "topogram template update --status",
-      "template:update:recommend": "topogram template update --recommend",
-      "template:update:plan": "topogram template update --plan",
-      "template:update:check": "topogram template update --check",
-      "template:update:apply": "topogram template update --apply",
-      "trust:status": "topogram trust status",
-      "trust:diff": "topogram trust diff",
-      verify: "npm run app:compile",
-      bootstrap: "npm run app:bootstrap",
-      dev: "npm run app:dev",
-      "app:bootstrap": "npm --prefix ./app run bootstrap",
-      "app:dev": "npm --prefix ./app run dev",
-      "app:compile": "npm --prefix ./app run compile",
-      "app:smoke": "npm --prefix ./app run smoke",
-      "app:runtime-check": "npm --prefix ./app run runtime-check",
-      "app:check": "npm run app:compile",
-      "app:probe": "npm run app:smoke && npm run app:runtime-check",
-      "app:runtime": "npm --prefix ./app run runtime",
-      ...starterScripts
-    },
-    devDependencies: {
-      [cliDependency.name]: cliDependency.spec,
-      ...generatorDependencies
-    }
-  };
-  fs.writeFileSync(path.join(projectRoot, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
-  writeProjectNpmConfig(projectRoot, cliDependency);
-}
-
-/**
- * @param {string} projectRoot
- * @returns {void}
- */
-function writeExplainScript(projectRoot) {
-  const scriptDir = path.join(projectRoot, "scripts");
-  fs.mkdirSync(scriptDir, { recursive: true });
-  const script = `const message = \`
-Topogram app workflow
-
-1. Edit:
-   topogram/
-   topogram.project.json
-
-2. Start with project guidance:
-   npm run agent:brief
-
-3. Validate:
-   npm run doctor
-   npm run source:status
-   npm run template:explain
-   npm run check
-
-4. Regenerate:
-   npm run generate
-
-5. Verify generated app:
-   npm run verify
-
-6. Run locally:
-   npm run bootstrap
-   npm run dev
-
-7. Probe the running app from another terminal:
-   npm run app:probe
-
-Or run self-contained local runtime verification:
-   npm run app:runtime
-
-Useful inspection:
-   npm run agent:brief
-   npm run check:json
-   topogram emit ui-widget-contract ./topogram --json
-   topogram emit widget-conformance-report ./topogram --json
-   npm run doctor
-   npm run source:status
-   npm run source:status:remote
-   npm run template:explain
-   npm run template:status
-   npm run template:detach:dry-run
-   npm run template:policy:check
-   npm run template:policy:explain
-   npm run generator:policy:status
-   npm run generator:policy:check
-   npm run generator:policy:explain
-   npm run template:update:status
-   npm run template:update:recommend
-   npm run template:update:plan
-   npm run template:update:check
-   npm run template:update:apply
-   npm run trust:status
-   npm run trust:diff
-\`;
-
-console.log(message.trimEnd());
-`;
-  fs.writeFileSync(path.join(scriptDir, "explain.mjs"), script, "utf8");
-}
-
-/**
- * @param {string} projectRoot
- * @param {Record<string, any>} projectConfig
- * @returns {void}
- */
-function writeProjectReadme(projectRoot, projectConfig) {
-  const template = projectConfig.template || {};
-  const templateName = template.id || "unknown";
-  const workflowCommands = [
-    "npm install",
-    "npm run explain",
-    "npm run agent:brief",
-    "npm run doctor",
-    "npm run source:status",
-    "npm run template:explain",
-    "npm run check",
-    "npm run template:policy:check",
-    "npm run generator:policy:status",
-    "npm run generator:policy:check",
-    ...(template.includesExecutableImplementation ? [
-      "npm run template:policy:explain",
-      "npm run trust:status"
-    ] : []),
-    "npm run generate",
-    "npm run verify"
-  ];
-  const provenanceLines = [];
-  provenanceLines.push(`- Template: \`${templateName}@${template.version || "unknown"}\``);
-  provenanceLines.push(`- Source: \`${template.source || "unknown"}\``);
-  if (template.sourceSpec) {
-    provenanceLines.push(`- Source spec: \`${template.sourceSpec}\``);
-  }
-  if (template.catalog) {
-    provenanceLines.push(`- Catalog: \`${template.catalog.id}\` from \`${template.catalog.source}\``);
-    provenanceLines.push(`- Package: \`${template.catalog.packageSpec}\``);
-  }
-  provenanceLines.push(`- Executable implementation: \`${template.includesExecutableImplementation ? "yes" : "no"}\``);
-  const readme = `# ${packageNameFromPath(projectRoot)}
-
-Generated by \`topogram new\`.
-
-## Template
-
-${provenanceLines.join("\n")}
-
-## Workflow
-
-\`\`\`bash
-${workflowCommands.join("\n")}
-\`\`\`
-
-Edit \`topogram/\` and \`topogram.project.json\`, then regenerate with \`npm run generate\`.
-Generated app code is written to \`app/\`.
-Use \`topogram emit <target>\` to inspect contracts, reports, snapshots, and other artifacts without regenerating the app.
-Agents should start with \`AGENTS.md\` and \`npm run agent:brief\`. The direct \`topogram agent brief --json\` command is the canonical machine-readable first-run guidance.
-${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram new` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
-`;
-  fs.writeFileSync(path.join(projectRoot, "README.md"), readme, "utf8");
-}
-
-/**
- * @param {string} projectRoot
- * @param {Record<string, any>} projectConfig
- * @returns {void}
- */
-function writeAgentsGuide(projectRoot, projectConfig) {
-  const template = projectConfig.template || {};
-  const hasImplementation = Boolean(projectConfig.implementation || template.includesExecutableImplementation);
-  const guide = `# Agent Guide
-
-Start here before editing this Topogram project.
-
-## First Read
-
-1. \`AGENTS.md\`
-2. \`README.md\`
-3. \`topogram.project.json\`
-4. \`topogram.template-policy.json\`
-5. \`topogram.generator-policy.json\`
-${hasImplementation ? "6. `.topogram-template-trust.json`\n7. `implementation/`\n8. Focused `topogram query ...` output\n" : "6. Focused `topogram query ...` output\n"}
-Machine-readable source:
-
-\`\`\`bash
-topogram agent brief --json
-\`\`\`
-
-Local shortcut:
-
-\`\`\`bash
-npm run agent:brief
-\`\`\`
-
-Reference: https://github.com/${githubRepoSlug(null)}/blob/main/docs/agent-first-run.md
-
-## First Commands
-
-\`\`\`bash
-npm run agent:brief
-npm run doctor
-npm run source:status
-npm run template:explain
-npm run generator:policy:check
-${hasImplementation ? "npm run trust:status\n" : ""}npm run check
-npm run query:list
-npm run query:show -- widget-behavior
-\`\`\`
-
-## Edit Rules
-
-- Edit \`topogram/**\` and \`topogram.project.json\` first.
-- Review policy files before editing \`topogram.template-policy.json\` or \`topogram.generator-policy.json\`.
-- Do not make lasting edits under generated-owned \`app/**\`; use \`npm run generate\` to replace generated output.
-- If an output is changed to maintained ownership, agents may edit that app code directly after reading focused query packets.
-
-## UI And Widgets
-
-- \`ui_contract\` owns screens, regions, widget bindings, behavior, visibility, and semantic design tokens.
-- Web/iOS/Android surfaces realize the shared UI contract; they do not own widget placement.
-- Use \`topogram widget check --json\`, \`topogram widget behavior --json\`, and focused \`topogram query ...\` packets after UI edits.
-
-## Template And Trust
-
-- Local edits to template-derived Topogram files are project-owned.
-- Use \`npm run source:status\` and \`npm run template:update:recommend\` before applying template updates.
-${hasImplementation ? "- This project has executable `implementation/` code. `topogram new` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
-## Import And Adoption
-
-- If \`.topogram-import.json\` exists, run \`topogram import check .\`, \`topogram import plan .\`, \`topogram import adopt --list .\`, and \`topogram import history . --verify\`.
-- Imported Topogram files are project-owned after adoption; source hashes record trusted import evidence at the time of import.
-
-## Verification Gates
-
-\`\`\`bash
-npm run check
-npm run generate
-npm run verify
-\`\`\`
-`;
-  fs.writeFileSync(path.join(projectRoot, "AGENTS.md"), guide, "utf8");
-}
-
-/**
- * @param {CreateNewProjectOptions} options
- * @returns {{ projectRoot: string, templateName: string, template: Record<string, any>, topogramPath: string, appPath: string, warnings: string[] }}
- */
-export function createNewProject({
-  targetPath,
-  templateName = DEFAULT_TEMPLATE_NAME,
-  engineRoot,
-  templatesRoot,
-  templateProvenance = null
-}) {
-  if (!targetPath) {
-    throw new Error("topogram new requires <path>.");
-  }
-  const projectRoot = path.resolve(targetPath);
-  assertProjectOutsideEngine(projectRoot, engineRoot);
-  const template = resolveTemplate(templateName, templatesRoot);
-  if (
-    templateProvenance &&
-    typeof templateProvenance.includesExecutableImplementation === "boolean" &&
-    templateProvenance.includesExecutableImplementation !== Boolean(template.manifest.includesExecutableImplementation)
-  ) {
-    throw new Error(
-      `Catalog entry '${templateProvenance.id}' declares includesExecutableImplementation: ${templateProvenance.includesExecutableImplementation}, ` +
-        `but template package '${template.packageSpec || template.requested}' declares includesExecutableImplementation: ${Boolean(template.manifest.includesExecutableImplementation)}.`
-    );
-  }
-
-  ensureCreatableProjectRoot(projectRoot);
-  copyTopogramWorkspace(template.root, projectRoot);
-  const projectConfig = writeProjectTemplateMetadata(projectRoot, template, templateProvenance);
-  writeProjectPackage(projectRoot, engineRoot, template);
-  writeExplainScript(projectRoot);
-  writeProjectReadme(projectRoot, projectConfig);
-  writeAgentsGuide(projectRoot, projectConfig);
-  writeTemplateFilesManifest(projectRoot, projectConfig);
-  writeTemplatePolicy(projectRoot, defaultTemplatePolicyForTemplate(template));
-  writeGeneratorPolicy(projectRoot, defaultGeneratorPolicy());
-
-  const warnings = [];
-  if (template.manifest.includesExecutableImplementation) {
-    writeTemplateTrustRecord(projectRoot, projectConfig);
-    warnings.push(
-      `Template '${template.manifest.id}' copied implementation/ code into this project. ` +
-        "topogram new did not execute it, but topogram generate may load it later. " +
-        "Recorded local trust in .topogram-template-trust.json."
-    );
-  }
-
-  return {
-    projectRoot,
-    templateName: template.manifest.id,
-    template: projectConfig.template,
-    topogramPath: path.join(projectRoot, "topogram"),
-    appPath: path.join(projectRoot, "app"),
-    warnings
-  };
-}
+export { packageNameFromSpec, packageScopeFromSpec } from "./new-project/package-spec.js";
+export { installPackageSpec, resolveTemplate } from "./new-project/template-resolution.js";
+export { loadTemplatePolicy, templatePolicyDiagnosticsForTemplate, writeTemplatePolicy, writeTemplatePolicyForProject } from "./new-project/template-policy.js";
+export { writeTemplateFilesManifest } from "./new-project/template-snapshots.js";
+export { applyTemplateUpdate, applyTemplateUpdateFileAction, buildTemplateUpdateCheck, buildTemplateUpdatePlan, buildTemplateUpdateStatus } from "./new-project/template-updates.js";
+export { createNewProject } from "./new-project/create.js";