canopycms 0.0.63 → 0.0.64

package/dist/cli/cli.js

@@ -1047,7 +1047,7 @@ CanopyCMS worker run-once (mode: ${mode}, auth: ${authMode})
   }
   console.log("\nDone");
 }
-var __defProp2, __getOwnPropNames2, __esm2, __export2, active, init_logger, primitiveFieldTypes, fieldTypes, init_types, fieldBaseSchema, selectOptionSchema, referenceOptionSchema, primitiveFieldSchema, ASPECT_RATIO_RE, imageFieldSchema, selectFieldSchema, referenceFieldSchema, fieldHolder, blockSchema, blockFieldSchema, objectFieldSchema, inlineGroupFieldSchema, customFieldSchema, knownFieldSchema, fieldSchema, init_field, relativePathSchema, entryTypeSchema, collectionSchema, init_collection, mediaSchema, init_media, defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE, init_config, permissionTargetSchema, pathPermissionSchema, init_permissions, init_normalize, init_types2, init_flatten, init_mode_env, init_validation, init_helpers, init_config2, init_error2, init_fs2, templates_exports, __dirname, TEMPLATES_DIR, SCAFFOLD_STACK_NAME, init_templates, project_detect_exports, COMMANDS, MAX_WORKSPACE_DEPTH, CDK_DEPENDENCIES, init_project_detect, task_queue_config_exports, init_task_queue_config, LOG_LEVELS, DebugLogger, testLogger, init_debug, init_atomic_write, DEFAULT_MAX_RETRIES, nullLogger, init_task_queue, init_task_queue2, task_queue_exports, debugLogger, cmsTaskQueueLogger, init_task_queue3, ProdClientSafeStrategy, DevClientSafeStrategy, warned, VALID_DEPLOYMENT_NAME, isValidDeploymentName, ProdStrategy, DevStrategy, strategyCache;
+var __defProp2, __getOwnPropNames2, __esm2, __export2, active, init_logger, primitiveFieldTypes, fieldTypes, init_types, fieldBaseSchema, selectOptionSchema, referenceOptionSchema, primitiveFieldSchema, ASPECT_RATIO_RE, imageFieldSchema, selectFieldSchema, referenceFieldSchema, fieldHolder, blockSchema, blockFieldSchema, objectFieldSchema, inlineGroupFieldSchema, customFieldSchema, knownFieldSchema, fieldSchema, init_field, relativePathSchema, entryTypeSchema, collectionSchema, init_collection, mediaSchema, init_media, defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, basePathSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE, init_config, permissionTargetSchema, pathPermissionSchema, init_permissions, init_normalize, init_types2, init_flatten, init_mode_env, init_validation, init_helpers, init_config2, init_error2, init_fs2, templates_exports, __dirname, TEMPLATES_DIR, SCAFFOLD_STACK_NAME, init_templates, project_detect_exports, COMMANDS, MAX_WORKSPACE_DEPTH, CDK_DEPENDENCIES, init_project_detect, task_queue_config_exports, init_task_queue_config, LOG_LEVELS, DebugLogger, testLogger, init_debug, init_atomic_write, DEFAULT_MAX_RETRIES, nullLogger, init_task_queue, init_task_queue2, task_queue_exports, debugLogger, cmsTaskQueueLogger, init_task_queue3, ProdClientSafeStrategy, DevClientSafeStrategy, warned, VALID_DEPLOYMENT_NAME, isValidDeploymentName, ProdStrategy, DevStrategy, strategyCache;
 var init_init = __esm({
   "dist/cli/init.js"() {
     "use strict";
@@ -1134,7 +1134,12 @@ var init_init = __esm({
           collections: z.array(z.string().min(1)).min(1).optional(),
           entryTypes: z.array(z.string().min(1)).min(1).optional(),
           displayField: z.string().min(1).optional(),
-          options: z.array(referenceOptionSchema).optional()
+          options: z.array(referenceOptionSchema).optional(),
+          // Must be listed here, not just on ReferenceFieldConfig: zod strips unknown keys by
+          // default, so a consumer that adopts this schema's parse output would silently delete a
+          // runtime-consumed flag and the feature would no-op with no error. (`resolvedSchema` is
+          // absent on purpose — it is type-inference-only and stripping it changes no behavior.)
+          includeBody: z.boolean().optional()
         });
         fieldHolder = [z.never()];
         blockSchema = z.object({
@@ -1255,6 +1260,9 @@ var init_init = __esm({
         deployedAsSchema = z4.enum(["static", "server"]).default("server");
         contentRootSchema = relativePathSchema.default("content");
         sourceRootSchema = z4.string().min(1).optional();
+        basePathSchema = z4.string().transform((value) => value.trim()).refine((value) => value.length > 0, {
+          message: "basePath must not be empty or only whitespace"
+        }).optional();
         deploymentNameSchema = z4.string().default("prod");
         devContentSyncSchema = z4.enum(["off", "warn"]).default("warn");
         devConfigSchema = z4.object({
@@ -1317,6 +1325,7 @@ var init_init = __esm({
           deploymentName: deploymentNameSchema.optional(),
           contentRoot: contentRootSchema.default("content"),
           sourceRoot: sourceRootSchema.optional(),
+          basePath: basePathSchema,
           editor: editorConfigSchema.optional(),
           authPlugin: z4.custom().optional(),
           entryLinkUrl: z4.custom().optional(),
@@ -1480,6 +1489,7 @@ var init_init = __esm({
         };
         MAX_WORKSPACE_DEPTH = 8;
         CDK_DEPENDENCIES = [
+          "canopycms",
           "canopycms-cdk",
           "aws-cdk-lib",
           "constructs",
@@ -1844,63 +1854,73 @@ import { isAbsolute as isAbsolute2 } from "pathe";
 import { z as z42 } from "zod";
 import { z as z52 } from "zod";
 import { z as z6 } from "zod";
-import path82 from "node:path";
-import path19 from "node:path";
+import path9 from "node:path";
+import path20 from "node:path";
 import { createJiti as createJiti2 } from "jiti";
-import fs16 from "node:fs/promises";
-import path18 from "node:path";
-import fs9 from "node:fs/promises";
+import fs17 from "node:fs/promises";
+import path19 from "node:path";
+import fs10 from "node:fs/promises";
+import path11 from "node:path";
+import matter2 from "gray-matter";
+import { parse as yamlParse } from "yaml";
+import fs7 from "node:fs/promises";
 import path10 from "node:path";
 import matter from "gray-matter";
-import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import fs7 from "node:fs/promises";
-import path9 from "node:path";
+import { isCollection, isMap, isNode, isScalar, isSeq, parseDocument, stringify as yamlStringify } from "yaml";
 import path32 from "node:path";
 import fs23 from "node:fs/promises";
 import path22 from "node:path";
 import lockfile from "proper-lockfile";
+import fs42 from "node:fs/promises";
+import path52 from "node:path";
 import fs32 from "node:fs/promises";
 import path42 from "node:path";
 import { generate } from "short-uuid";
-import path52 from "node:path";
-import fs42 from "node:fs/promises";
 import path62 from "node:path";
-import { randomUUID } from "node:crypto";
-import fs62 from "node:fs/promises";
+import fs52 from "node:fs/promises";
 import path72 from "node:path";
-import { promises as fs52 } from "fs";
+import { randomUUID } from "node:crypto";
+import fs72 from "node:fs/promises";
+import path82 from "node:path";
+import { promises as fs62 } from "fs";
 import { join as join3 } from "pathe";
 import { z as z7 } from "zod";
 import chokidar from "chokidar";
-import fs72 from "node:fs/promises";
-import { sep, resolve, relative } from "node:path";
 import fs8 from "node:fs/promises";
-import path92 from "node:path";
-import path11 from "node:path";
-import fs10 from "node:fs/promises";
-import { minimatch } from "minimatch";
-import path16 from "node:path";
-import fs13 from "node:fs/promises";
-import path14 from "node:path";
-import fs11 from "node:fs/promises";
+import { sep, resolve, relative } from "node:path";
+import fs9 from "node:fs/promises";
+import path102 from "node:path";
 import path12 from "node:path";
+import fs11 from "node:fs/promises";
+import { minimatch } from "minimatch";
+import path17 from "node:path";
+import fs14 from "node:fs/promises";
+import path15 from "node:path";
 import fs12 from "node:fs/promises";
 import path13 from "node:path";
+import fs13 from "node:fs/promises";
+import path14 from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 import lockfile2 from "proper-lockfile";
-import fs14 from "node:fs/promises";
-import path15 from "node:path";
+import fs15 from "node:fs/promises";
+import path16 from "node:path";
 import { simpleGit as simpleGit2 } from "simple-git";
 import { simpleGit as simpleGit3 } from "simple-git";
-import fs15 from "node:fs/promises";
-import path17 from "node:path";
-import matter2 from "gray-matter";
+import fs16 from "node:fs/promises";
+import path18 from "node:path";
+import matter3 from "gray-matter";
 import { parse as yamlParse2 } from "yaml";
-function normalizeFilesystemPath(path202) {
-  return path202.split(/[\\/]+/).filter(Boolean).join("/");
+function canopyLogWarn2(...args) {
+  active2.warn(...args);
+}
+function canopyLogError(...args) {
+  active2.error(...args);
 }
-function hasTraversalSequence(path202) {
-  const normalized = normalizeFilesystemPath(path202);
+function normalizeFilesystemPath(path212) {
+  return path212.split(/[\\/]+/).filter(Boolean).join("/");
+}
+function hasTraversalSequence(path212) {
+  const normalized = normalizeFilesystemPath(path212);
   return normalized.includes("..");
 }
 function createLogicalPath(...segments) {
@@ -1910,20 +1930,14 @@ function createLogicalPath(...segments) {
   }
   return normalized;
 }
-function trimSlashes(path202) {
+function trimSlashes(path212) {
   let start = 0;
-  let end = path202.length;
-  while (start < end && path202[start] === "/")
+  let end = path212.length;
+  while (start < end && path212[start] === "/")
     start++;
-  while (end > start && path202[end - 1] === "/")
+  while (end > start && path212[end - 1] === "/")
     end--;
-  return path202.slice(start, end);
-}
-function canopyLogWarn2(...args) {
-  active2.warn(...args);
-}
-function canopyLogError(...args) {
-  active2.error(...args);
+  return path212.slice(start, end);
 }
 function readModeEnv() {
   if (typeof process === "undefined" || typeof process.env === "undefined")
@@ -2007,8 +2021,26 @@ function operatingStrategy2(mode) {
 function clearStrategyCache() {
   strategyCache2.clear();
 }
+function getErrorMessage3(err) {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return String(err);
+}
+function isNodeError3(err) {
+  return err instanceof Error && "code" in err;
+}
+function isNotFoundError3(err) {
+  return isNodeError3(err) && err.code === "ENOENT";
+}
+function isFileExistsError2(err) {
+  return isNodeError3(err) && err.code === "EEXIST";
+}
 async function atomicWriteFile2(filePath, content) {
-  const dir = path9.dirname(filePath);
+  const dir = path10.dirname(filePath);
   await fs7.mkdir(dir, { recursive: true });
   const tempPath = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
   await fs7.writeFile(tempPath, content, typeof content === "string" ? "utf-8" : void 0);
@@ -2020,6 +2052,196 @@ async function atomicWriteFile2(filePath, content) {
     throw err;
   }
 }
+function isBlockStructuralKey(key) {
+  return BLOCK_STRUCTURAL_KEYS.has(key);
+}
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function recordKeyOf(keyNode) {
+  if (!isScalar(keyNode))
+    return void 0;
+  const { value } = keyNode;
+  if (value === null || value === void 0)
+    return void 0;
+  if (typeof value === "object")
+    return void 0;
+  return String(value);
+}
+function carryComments(from, to) {
+  if (!isNode(from) || !isNode(to))
+    return;
+  const source = from;
+  const target = to;
+  if (source.commentBefore !== void 0)
+    target.commentBefore = source.commentBefore;
+  if (source.comment !== void 0)
+    target.comment = source.comment;
+  if (source.spaceBefore !== void 0)
+    target.spaceBefore = source.spaceBefore;
+}
+function identityKey(value) {
+  try {
+    return JSON.stringify(value) ?? "undefined";
+  } catch {
+    return void 0;
+  }
+}
+function nodePlainValue(node) {
+  if (!isNode(node))
+    return node;
+  try {
+    return node.toJSON();
+  } catch {
+    return void 0;
+  }
+}
+function nodeIdentityKey(node) {
+  const plain = nodePlainValue(node);
+  return plain === void 0 && isNode(node) ? void 0 : identityKey(plain);
+}
+function sharesFieldEvidence(existing, value, depth) {
+  for (const key of Object.keys(value)) {
+    if (isBlockStructuralKey(key))
+      continue;
+    if (!Object.prototype.hasOwnProperty.call(existing, key))
+      continue;
+    const before = existing[key];
+    const after = value[key];
+    if (depth < EVIDENCE_MAX_DEPTH && isPlainRecord(before) && isPlainRecord(after) && sharesFieldEvidence(before, after, depth + 1)) {
+      return true;
+    }
+    const beforeKey = identityKey(before);
+    if (beforeKey !== void 0 && beforeKey === identityKey(after))
+      return true;
+  }
+  return false;
+}
+function looksLikeSameItem(node, value) {
+  const existing = nodePlainValue(node);
+  if (!isPlainRecord(existing) || !isPlainRecord(value))
+    return true;
+  return sharesFieldEvidence(existing, value, 0);
+}
+function reconcileNode(doc, existing, value) {
+  if (isMap(existing) && isPlainRecord(value)) {
+    reconcileMap(doc, existing, value);
+    return existing;
+  }
+  if (isSeq(existing) && Array.isArray(value)) {
+    reconcileSeq(doc, existing, value);
+    return existing;
+  }
+  if (isScalar(existing) && Object.is(existing.value, value))
+    return existing;
+  const fresh = doc.createNode(value);
+  if (!isCollection(existing))
+    carryComments(existing, fresh);
+  return fresh;
+}
+function reconcileMap(doc, map, value) {
+  const wanted = new Set(Object.keys(value).filter((key) => value[key] !== void 0));
+  const seen = /* @__PURE__ */ new Set();
+  const retained = [];
+  for (const pair of map.items) {
+    const key = recordKeyOf(pair.key);
+    if (key === void 0 || !wanted.has(key) || seen.has(key))
+      continue;
+    seen.add(key);
+    pair.value = reconcileNode(doc, pair.value, value[key]);
+    retained.push(pair);
+  }
+  map.items = retained;
+  for (const key of Object.keys(value)) {
+    if (seen.has(key) || !wanted.has(key))
+      continue;
+    map.set(doc.createNode(key), doc.createNode(value[key]));
+  }
+}
+function reconcileSeq(doc, seq, value) {
+  const oldItems = seq.items;
+  const byIdentity = /* @__PURE__ */ new Map();
+  oldItems.forEach((node, index) => {
+    const key = nodeIdentityKey(node);
+    if (key === void 0)
+      return;
+    const bucket = byIdentity.get(key);
+    if (bucket)
+      bucket.push(index);
+    else
+      byIdentity.set(key, [index]);
+  });
+  const consumed = /* @__PURE__ */ new Set();
+  const matches = value.map((item) => {
+    const key = identityKey(item);
+    if (key === void 0)
+      return void 0;
+    const bucket = byIdentity.get(key);
+    while (bucket && bucket.length > 0) {
+      const index = bucket.shift();
+      if (index !== void 0 && !consumed.has(index)) {
+        consumed.add(index);
+        return index;
+      }
+    }
+    return void 0;
+  });
+  seq.items = value.map((item, index) => {
+    const matched = matches[index];
+    if (matched !== void 0)
+      return oldItems[matched];
+    const candidate = index < oldItems.length && !consumed.has(index) ? oldItems[index] : void 0;
+    const sameItem = candidate !== void 0 && looksLikeSameItem(candidate, item) ? candidate : void 0;
+    return reconcileNode(doc, sameItem, item);
+  });
+}
+function applyDataToDocument(doc, data) {
+  doc.contents = reconcileNode(doc, doc.contents, data);
+}
+function serializeYaml(data, existingRaw) {
+  if (existingRaw === void 0)
+    return yamlStringify(data);
+  const doc = parseDocument(existingRaw);
+  if (doc.errors.length > 0)
+    return yamlStringify(data);
+  applyDataToDocument(doc, data);
+  return doc.toString();
+}
+function extractRawFrontmatter(raw) {
+  let parsed;
+  try {
+    parsed = matter(raw, {});
+  } catch {
+    return void 0;
+  }
+  const frontmatter = parsed.matter;
+  if (typeof frontmatter !== "string" || frontmatter.trim() === "")
+    return void 0;
+  return frontmatter;
+}
+function serializeFrontmatter(body, data, existingRaw) {
+  if (existingRaw === void 0)
+    return matter.stringify(body, data);
+  const existingFrontmatter = extractRawFrontmatter(existingRaw);
+  if (existingFrontmatter === void 0)
+    return matter.stringify(body, data);
+  const doc = parseDocument(existingFrontmatter);
+  if (doc.errors.length > 0)
+    return matter.stringify(body, data);
+  applyDataToDocument(doc, data);
+  const reconciled = doc.toString();
+  return matter.stringify(body, data, {
+    engines: {
+      yaml: {
+        parse: () => ({}),
+        stringify: () => reconciled
+      }
+    }
+  });
+}
 async function withLock(key, fn) {
   const prev = locks.get(key) ?? Promise.resolve();
   let resolve2;
@@ -2036,51 +2258,71 @@ async function withLock(key, fn) {
       locks.delete(key);
   }
 }
-function getErrorMessage3(err) {
-  if (err instanceof Error) {
-    return err.message;
-  }
-  if (typeof err === "string") {
-    return err;
-  }
-  return String(err);
-}
-function isNodeError3(err) {
-  return err instanceof Error && "code" in err;
-}
-function isNotFoundError3(err) {
-  return isNodeError3(err) && err.code === "ENOENT";
+function provisioningLockOptions(lockPath, retries, onCompromised) {
+  return {
+    lockfilePath: lockPath,
+    realpath: false,
+    retries,
+    stale: 3e4,
+    // proper-lockfile invokes this from inside its refresh timer, so ANY throw
+    // escaping here is an uncaught exception that kills the process -- the very
+    // failure the handler exists to prevent. Call sites are told not to throw
+    // (see OnLockCompromised); this makes it structural rather than a
+    // convention, and also covers the LOGGER throwing: under `CI=true`,
+    // vitest's `onConsoleLog` turns any console write into a throw.
+    onCompromised: (err) => {
+      try {
+        if (onCompromised) {
+          onCompromised(err);
+          return;
+        }
+        canopyLogWarn2(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage3(err));
+      } catch {
+        try {
+          process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw
+`);
+        } catch {
+        }
+      }
+    }
+  };
 }
-function isFileExistsError2(err) {
-  return isNodeError3(err) && err.code === "EEXIST";
+function releaseIgnoringAlreadyReleased(release, lockPath) {
+  return async () => {
+    try {
+      await release();
+    } catch (err) {
+      if (isNodeError3(err) && err.code === "ERELEASED") {
+        canopyLogWarn2(`[canopy] Lock at ${lockPath} was already released (compromised mid-hold, or released twice); nothing to release`);
+        return;
+      }
+      throw err;
+    }
+  };
 }
-async function acquireProvisioningLock(lockTargetDir2, lockName) {
+async function acquireProvisioningLock(lockTargetDir2, lockName, onCompromised) {
   await fs23.mkdir(lockTargetDir2, { recursive: true });
-  return lockfile.lock(lockTargetDir2, {
-    lockfilePath: path22.join(lockTargetDir2, lockName),
-    retries: { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true },
-    stale: 3e4
-  });
+  const lockPath = path22.join(lockTargetDir2, lockName);
+  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+  return releaseIgnoringAlreadyReleased(release, lockPath);
 }
-async function tryAcquireProvisioningLock(lockTargetDir2, lockName) {
+async function tryAcquireProvisioningLock(lockTargetDir2, lockName, onCompromised) {
   await fs23.mkdir(lockTargetDir2, { recursive: true });
-  return lockfile.lock(lockTargetDir2, {
-    lockfilePath: path22.join(lockTargetDir2, lockName),
-    retries: 0,
-    stale: 3e4
-  });
+  const lockPath = path22.join(lockTargetDir2, lockName);
+  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+  return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 function lockTargetDir(branchRoot) {
   return path32.join(path32.resolve(branchRoot), META_DIR);
 }
-function tryAcquireContentWriteLock(branchRoot) {
-  return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME);
+function tryAcquireContentWriteLock(branchRoot, onCompromised) {
+  return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised);
 }
-async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
+async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, onCompromised) {
   const startedAt = Date.now();
   for (let attempt = 0; ; attempt++) {
     try {
-      return await tryAcquireContentWriteLock(branchRoot);
+      return await tryAcquireContentWriteLock(branchRoot, onCompromised);
     } catch (err) {
       if (!isNodeError3(err) || err.code !== "ELOCKED")
         throw err;
@@ -2093,12 +2335,21 @@ async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRIT
   }
 }
 async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
-  const release = await acquireContentWriteLock(branchRoot, waitMs);
+  let compromised = false;
+  const release = await acquireContentWriteLock(branchRoot, waitMs, (err) => {
+    compromised = true;
+    canopyLogWarn2(`[canopy] Content-write lock compromised mid-hold for ${branchRoot}:`, getErrorMessage3(err));
+  });
+  let result;
   try {
-    return await fn();
+    result = await fn();
   } finally {
     await release();
   }
+  if (compromised) {
+    throw new ContentWriteLockBusyError("This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.");
+  }
+  return result;
 }
 function flattenGroupFields(fields) {
   const result = [];
@@ -2118,9 +2369,68 @@ function findBodyFieldName(fields) {
   }
   return "body";
 }
+function buildResolvedReference(data, meta, body) {
+  const resolved = { ...data };
+  if (body && body.value)
+    resolved[body.fieldName] = body.value;
+  resolved.id = meta.id;
+  resolved.slug = meta.slug;
+  resolved.collection = meta.collection;
+  resolved.urlPath = meta.urlPath;
+  return resolved;
+}
+function isIndexSlug(slug) {
+  return slug?.toLowerCase() === "index";
+}
+function computeEntryUrl(collection, slug, contentRoot) {
+  const root = trimSlashes(contentRoot);
+  let stripped = collection;
+  if (root && collection.startsWith(`${root}/`)) {
+    stripped = collection.slice(root.length + 1);
+  } else if (collection === root) {
+    stripped = "";
+  }
+  const segments = stripped.split("/").filter(Boolean);
+  if (slug && !isIndexSlug(slug)) {
+    segments.push(slug);
+  }
+  const path212 = segments.length > 0 ? `/${segments.join("/")}` : "/";
+  return path212.toLowerCase();
+}
 function isValidContentId(id) {
   return CONTENT_ID_PATTERN.test(id);
 }
+function parseSlug(slug) {
+  if (!slug) {
+    return {
+      ok: false,
+      error: "Slug is required"
+    };
+  }
+  if (slug.length > 64) {
+    return { ok: false, error: "Slug too long (max 64 characters)" };
+  }
+  if (slug.includes("/") || slug.includes("\\")) {
+    return {
+      ok: false,
+      error: "Slug cannot contain path separators"
+    };
+  }
+  if (slug === "." || slug === "..") {
+    return {
+      ok: false,
+      error: "Slug cannot be a traversal sequence"
+    };
+  }
+  const normalized = slug.toLowerCase();
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
+    return {
+      ok: false,
+      error: "Slug must start with a letter or number and contain only lowercase letters, numbers, and hyphens"
+    };
+  }
+  return { ok: true, slug: normalized };
+}
 function generateId() {
   const full = generate();
   return full.substring(0, 12);
@@ -2148,13 +2458,13 @@ function extractIdFromFilename(filename) {
   return null;
 }
 async function resolveCollectionPath(root, logicalPath) {
-  const fs172 = await import("node:fs/promises");
-  const path202 = await import("node:path");
+  const fs182 = await import("node:fs/promises");
+  const path212 = await import("node:path");
   const segments = logicalPath.split("/").filter(Boolean);
   let currentPath = root;
   for (const segment of segments) {
     try {
-      const entries = await fs172.readdir(currentPath, { withFileTypes: true });
+      const entries = await fs182.readdir(currentPath, { withFileTypes: true });
       const matchingDir = entries.find((entry) => {
         if (!entry.isDirectory())
           return false;
@@ -2162,7 +2472,7 @@ async function resolveCollectionPath(root, logicalPath) {
         return logicalName === segment.toLowerCase();
       });
       if (matchingDir) {
-        currentPath = path202.join(currentPath, matchingDir.name);
+        currentPath = path212.join(currentPath, matchingDir.name);
       } else {
         return null;
       }
@@ -2211,8 +2521,70 @@ function extractSlugFromFilename(filename, entryTypeName) {
   }
   return filename.toLowerCase();
 }
+async function readDirSafe(dir) {
+  try {
+    return await fs42.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFoundError3(err))
+      return [];
+    throw err;
+  }
+}
+async function findChildCollectionDir(dir, name) {
+  const wanted = name.toLowerCase();
+  for (const entry of await readDirSafe(dir)) {
+    if (!entry.isDirectory())
+      continue;
+    if (extractSlugFromFilename(entry.name) === wanted)
+      return path52.join(dir, entry.name);
+  }
+  return null;
+}
+function entrySlugOf(filename) {
+  if (!CONTENT_EXTENSIONS.some((ext) => filename.endsWith(ext)))
+    return null;
+  return parseTypedFilename(filename)?.slug ?? null;
+}
+async function findIndexEntryIn(dir) {
+  for (const entry of await readDirSafe(dir)) {
+    if (entry.isDirectory())
+      continue;
+    if (isIndexSlug(entrySlugOf(entry.name) ?? void 0))
+      return path52.join(dir, entry.name);
+  }
+  return null;
+}
+async function findEntryBySlugIn(dir, slug) {
+  const wanted = slug.toLowerCase();
+  for (const entry of await readDirSafe(dir)) {
+    if (entry.isDirectory())
+      continue;
+    if (entrySlugOf(entry.name) === wanted)
+      return path52.join(dir, entry.name);
+  }
+  return null;
+}
+async function findUrlPathClaimant(opts) {
+  const { collectionDir, slug, contentRoot } = opts;
+  if (isIndexSlug(slug)) {
+    const resolvedRoot = path52.resolve(contentRoot);
+    if (path52.resolve(collectionDir) === resolvedRoot)
+      return null;
+    const parentDir = path52.dirname(collectionDir);
+    const ownName = extractSlugFromFilename(path52.basename(collectionDir));
+    if (isIndexSlug(ownName))
+      return null;
+    const claimant = await findEntryBySlugIn(parentDir, ownName);
+    return claimant ? { kind: "parent-entry", physicalPath: claimant, name: ownName } : null;
+  }
+  const childDir = await findChildCollectionDir(collectionDir, slug);
+  if (!childDir)
+    return null;
+  const indexEntry = await findIndexEntryIn(childDir);
+  return indexEntry ? { kind: "sibling-collection-index", physicalPath: indexEntry, name: slug } : null;
+}
 function registerContentIndexForInvalidation(root, target) {
-  const rootKey = path52.resolve(root);
+  const rootKey = path62.resolve(root);
   let refs = registry.get(rootKey);
   if (!refs) {
     refs = /* @__PURE__ */ new Set();
@@ -2223,8 +2595,8 @@ function registerContentIndexForInvalidation(root, target) {
   finalization.register(target, { rootKey, ref });
 }
 function invalidateContentIndexesForRoot(root) {
-  const rootKey = path52.resolve(root);
-  const prefix = rootKey + path52.sep;
+  const rootKey = path62.resolve(root);
+  const prefix = rootKey + path62.sep;
   for (const [storeRoot, refs] of registry) {
     if (storeRoot !== rootKey && !storeRoot.startsWith(prefix))
       continue;
@@ -2244,7 +2616,7 @@ function createDebugLogger2(options) {
   return new DebugLogger2(options);
 }
 function resourceGenerationPath(root, resource) {
-  return path62.resolve(root, META_DIR2, `${resource}.generation`);
+  return path72.resolve(root, META_DIR2, `${resource}.generation`);
 }
 async function bumpResourceGeneration(root, resource, options) {
   const token = randomUUID();
@@ -2262,7 +2634,7 @@ async function bumpResourceGeneration(root, resource, options) {
 }
 async function readResourceGeneration(root, resource) {
   try {
-    const token = await fs42.readFile(resourceGenerationPath(root, resource), "utf-8");
+    const token = await fs52.readFile(resourceGenerationPath(root, resource), "utf-8");
     return { ok: true, token };
   } catch (err) {
     if (isNodeError3(err) && err.code === "ENOENT")
@@ -2282,7 +2654,7 @@ function stripEmbeddedIdFromName(name) {
 async function scanForCollectionMeta(baseDir, relativePath = "") {
   const collections = [];
   try {
-    const entries = await fs52.readdir(baseDir, { withFileTypes: true });
+    const entries = await fs62.readdir(baseDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
@@ -2293,8 +2665,8 @@ async function scanForCollectionMeta(baseDir, relativePath = "") {
       const absolutePath = join3(baseDir, folderName);
       const metaPath = join3(absolutePath, ".collection.json");
       try {
-        await fs52.access(metaPath);
-        const content = await fs52.readFile(metaPath, "utf-8");
+        await fs62.access(metaPath);
+        const content = await fs62.readFile(metaPath, "utf-8");
         const parsed = JSON.parse(content);
         const meta = collectionMetaSchema.parse(parsed);
         collections.push({
@@ -2326,7 +2698,7 @@ async function loadCollectionMetaFiles(contentRoot) {
   let root = null;
   const rootMetaPath = join3(contentRoot, ".collection.json");
   try {
-    await fs52.access(rootMetaPath);
+    await fs62.access(rootMetaPath);
   } catch (err) {
     if (err.code === "ENOENT") {
     } else {
@@ -2334,7 +2706,7 @@ async function loadCollectionMetaFiles(contentRoot) {
     }
   }
   try {
-    const content = await fs52.readFile(rootMetaPath, "utf-8");
+    const content = await fs62.readFile(rootMetaPath, "utf-8");
     const parsed = JSON.parse(content);
     root = rootCollectionMetaSchema.parse(parsed);
   } catch (err) {
@@ -2424,16 +2796,16 @@ function isValidSchema(schema) {
 async function isStaleByMtime(dir, cachedAt) {
   let entries;
   try {
-    entries = await fs62.readdir(dir, { recursive: true, encoding: "utf-8" });
+    entries = await fs72.readdir(dir, { recursive: true, encoding: "utf-8" });
   } catch {
     return true;
   }
   for (const entry of entries) {
     if (!entry.endsWith(".collection.json"))
       continue;
-    const full = path72.join(dir, entry);
+    const full = path82.join(dir, entry);
     try {
-      const stat = await fs62.stat(full);
+      const stat = await fs72.stat(full);
       if (stat.mtimeMs > cachedAt.getTime())
         return true;
     } catch {
@@ -2456,7 +2828,7 @@ async function invalidateBranchContentCaches(root) {
 }
 async function filePathExists3(filePath) {
   try {
-    await fs72.stat(filePath);
+    await fs8.stat(filePath);
     return true;
   } catch (err) {
     if (isNotFoundError3(err))
@@ -2464,6 +2836,15 @@ async function filePathExists3(filePath) {
     throw err;
   }
 }
+async function readFileIfExists(filePath) {
+  try {
+    return await fs8.readFile(filePath, "utf8");
+  } catch (err) {
+    if (isNotFoundError3(err))
+      return void 0;
+    throw err;
+  }
+}
 function validateAndNormalizePath(root, target) {
   const resolvedRoot = resolve(root);
   const withSep = resolvedRoot.endsWith(sep) ? resolvedRoot : `${resolvedRoot}${sep}`;
@@ -2493,11 +2874,11 @@ function resolveBranchPath(options) {
   const safeBranch = sanitizeBranchName(options.branchName);
   const strategy = operatingStrategy2(options.mode);
   const baseRoot = resolveContentBranchesRoot(options.mode, options.basePathOverride);
-  const normalizedBase = path92.resolve(baseRoot);
-  const baseWithSep = normalizedBase.endsWith(path92.sep) ? normalizedBase : `${normalizedBase}${path92.sep}`;
+  const normalizedBase = path102.resolve(baseRoot);
+  const baseWithSep = normalizedBase.endsWith(path102.sep) ? normalizedBase : `${normalizedBase}${path102.sep}`;
   const branchRoot = strategy.getContentBranchRoot(safeBranch, options.basePathOverride);
   const withinBase = (target) => {
-    const resolved = path92.resolve(target);
+    const resolved = path102.resolve(target);
     return resolved === normalizedBase || resolved.startsWith(baseWithSep);
   };
   if (!withinBase(branchRoot)) {
@@ -2507,7 +2888,7 @@ function resolveBranchPath(options) {
 }
 async function ensureBranchRoot(options) {
   const result = resolveBranchPath(options);
-  await fs8.mkdir(result.branchRoot, { recursive: true });
+  await fs9.mkdir(result.branchRoot, { recursive: true });
   return result;
 }
 async function withLocks(keys, fn) {
@@ -2795,7 +3176,7 @@ function renderField(field, value, depth, entry, config) {
   const heading = "#".repeat(Math.min(depth, 6));
   const descriptionLine = "description" in field && field.description ? `
 
-*${field.description}*` : "";
+_${field.description}_` : "";
   if ("list" in field && field.list && Array.isArray(value)) {
     return renderListField(field, value, depth, label, heading, descriptionLine, entry, config);
   }
@@ -3051,26 +3432,13 @@ function formatInlineValue(field, value) {
   return String(value);
 }
 function yamlValue(value) {
+  if (value === "")
+    return '""';
   if (/[:#{}[\],&*?|>!%@`]/.test(value) || value.includes("\n")) {
     return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
   }
   return value;
 }
-function computeEntryUrl(collection, slug, contentRoot) {
-  const root = trimSlashes(contentRoot);
-  let stripped = collection;
-  if (root && collection.startsWith(`${root}/`)) {
-    stripped = collection.slice(root.length + 1);
-  } else if (collection === root) {
-    stripped = "";
-  }
-  const segments = stripped.split("/").filter(Boolean);
-  if (slug && slug !== "index") {
-    segments.push(slug);
-  }
-  const path202 = segments.length > 0 ? `/${segments.join("/")}` : "/";
-  return path202.toLowerCase();
-}
 function resolveEntryUrl(location, contentRoot) {
   return computeEntryUrl(location.collection ?? "", location.slug ?? "", contentRoot);
 }
@@ -3237,7 +3605,7 @@ async function processCollection(store, collection, flatSchema, contentRoot, con
   const listed = await store.getCollectionEntryPaths(collection.logicalPath);
   const directEntries = listed.filter((e) => e.collection === collection.logicalPath);
   for (const listEntry of directEntries) {
-    const entryTypeName = extractEntryTypeFromFilename(path11.basename(listEntry.relativePath));
+    const entryTypeName = extractEntryTypeFromFilename(path12.basename(listEntry.relativePath));
     if (!entryTypeName)
       continue;
     if (config?.exclude?.entryTypes?.includes(entryTypeName))
@@ -3255,7 +3623,7 @@ async function processCollection(store, collection, flatSchema, contentRoot, con
       }
       if (config?.exclude?.where?.(aiEntry))
         continue;
-      await runEntryTransform(aiEntry, doc.absolutePath, extractIdFromFilename(path11.basename(listEntry.relativePath)), config);
+      await runEntryTransform(aiEntry, doc.absolutePath, extractIdFromFilename(path12.basename(listEntry.relativePath)), config);
       entries.push(aiEntry);
       const entryFilePath = `${cleanPath}/${listEntry.slug}.md`;
       const entryMarkdown = entryToMarkdown(aiEntry, config);
@@ -3306,7 +3674,7 @@ async function processRootEntries(store, rootCollection, contentRoot, config, id
   const listed = await store.getCollectionEntryPaths(rootCollection.logicalPath);
   const directEntries = listed.filter((e) => e.collection === rootCollection.logicalPath);
   for (const listEntry of directEntries) {
-    const entryTypeName = extractEntryTypeFromFilename(path11.basename(listEntry.relativePath));
+    const entryTypeName = extractEntryTypeFromFilename(path12.basename(listEntry.relativePath));
     if (!entryTypeName)
       continue;
     if (config?.exclude?.entryTypes?.includes(entryTypeName))
@@ -3324,7 +3692,7 @@ async function processRootEntries(store, rootCollection, contentRoot, config, id
       }
       if (config?.exclude?.where?.(aiEntry))
         continue;
-      await runEntryTransform(aiEntry, doc.absolutePath, extractIdFromFilename(path11.basename(listEntry.relativePath)), config);
+      await runEntryTransform(aiEntry, doc.absolutePath, extractIdFromFilename(path12.basename(listEntry.relativePath)), config);
       entries.push(aiEntry);
       const entryFilePath = `${listEntry.slug}.md`;
       const entryMarkdown = entryToMarkdown(aiEntry, config);
@@ -3372,19 +3740,19 @@ function docToAIEntry(doc, slug, entryTypeName, entryTypeConfig, cleanCollection
   };
 }
 function makeReadSibling(dir) {
-  const resolvedDir = path11.resolve(dir);
+  const resolvedDir = path12.resolve(dir);
   return async (name) => {
-    if (!name || name.includes("/") || name.includes("\\") || path11.isAbsolute(name) || hasTraversalSequence(name)) {
+    if (!name || name.includes("/") || name.includes("\\") || path12.isAbsolute(name) || hasTraversalSequence(name)) {
       return null;
     }
-    const abs = path11.resolve(resolvedDir, name);
-    if (path11.dirname(abs) !== resolvedDir)
+    const abs = path12.resolve(resolvedDir, name);
+    if (path12.dirname(abs) !== resolvedDir)
       return null;
     try {
-      const stats = await fs10.lstat(abs);
+      const stats = await fs11.lstat(abs);
       if (!stats.isFile())
         return null;
-      return await fs10.readFile(abs, "utf8");
+      return await fs11.readFile(abs, "utf8");
     } catch (err) {
       if (isNodeError3(err) && (err.code === "ENOENT" || err.code === "ENOTDIR"))
         return null;
@@ -3398,7 +3766,7 @@ async function runEntryTransform(entry, absolutePath, contentId, config) {
     return;
   const ctx = {
     contentId: contentId ?? "",
-    readSibling: makeReadSibling(path11.dirname(absolutePath))
+    readSibling: makeReadSibling(path12.dirname(absolutePath))
   };
   try {
     const appended = await transform(entry, ctx);
@@ -3439,29 +3807,29 @@ async function writeOccJsonFile(filePath, payload, options) {
   const writeId = randomUUID2();
   const data = { ...payload, version: newVersion, writeId };
   const content = JSON.stringify(data, null, 2) + (trailingNewline ? "\n" : "");
-  const dir = path13.dirname(filePath);
-  await fs12.mkdir(dir, { recursive: true });
+  const dir = path14.dirname(filePath);
+  await fs13.mkdir(dir, { recursive: true });
   const tempPath = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  await fs12.writeFile(tempPath, content, "utf-8");
+  await fs13.writeFile(tempPath, content, "utf-8");
   if (expectedVersion === null) {
     try {
-      await fs12.link(tempPath, filePath);
+      await fs13.link(tempPath, filePath);
     } catch (err) {
-      await fs12.unlink(tempPath).catch(() => {
+      await fs13.unlink(tempPath).catch(() => {
       });
       if (isFileExistsError2(err)) {
         throw new OccWriteConflictError();
       }
       throw err;
     }
-    await fs12.unlink(tempPath).catch(() => {
+    await fs13.unlink(tempPath).catch(() => {
     });
     return { version: newVersion, writeId };
   }
   try {
     let currentVersion = null;
     try {
-      const current = JSON.parse(await fs12.readFile(filePath, "utf-8"));
+      const current = JSON.parse(await fs13.readFile(filePath, "utf-8"));
       currentVersion = current.version ?? 0;
     } catch {
       currentVersion = null;
@@ -3469,16 +3837,16 @@ async function writeOccJsonFile(filePath, payload, options) {
     if (currentVersion !== expectedVersion) {
       throw new OccWriteConflictError();
     }
-    await fs12.rename(tempPath, filePath);
+    await fs13.rename(tempPath, filePath);
     if (settleMs > 0) {
       await new Promise((resolve2) => setTimeout(resolve2, settleMs));
     }
-    const afterWrite = JSON.parse(await fs12.readFile(filePath, "utf-8"));
+    const afterWrite = JSON.parse(await fs13.readFile(filePath, "utf-8"));
     if (afterWrite.writeId !== writeId) {
       throw new OccWriteConflictError();
     }
   } catch (err) {
-    await fs12.unlink(tempPath).catch(() => {
+    await fs13.unlink(tempPath).catch(() => {
     });
     throw err;
   }
@@ -3504,8 +3872,8 @@ async function withOccRetry(operation, options) {
   throw new Error("Unreachable");
 }
 async function withOccFileLock(filePath, fn) {
-  const dir = path13.dirname(filePath);
-  await fs12.mkdir(dir, { recursive: true });
+  const dir = path14.dirname(filePath);
+  await fs13.mkdir(dir, { recursive: true });
   const MAX_ATTEMPTS = 14;
   let release = null;
   for (let attempt = 1; release === null; attempt++) {
@@ -3589,11 +3957,11 @@ function gitChildEnv(overrides) {
   return { ...env, ...FORCE_C_LOCALE, ...overrides };
 }
 async function ensureGitExcludePattern(repoPath, pattern) {
-  const excludePath = path15.join(repoPath, ".git", "info", "exclude");
-  await fs14.mkdir(path15.dirname(excludePath), { recursive: true });
+  const excludePath = path16.join(repoPath, ".git", "info", "exclude");
+  await fs15.mkdir(path16.dirname(excludePath), { recursive: true });
   let content = "";
   try {
-    content = await fs14.readFile(excludePath, "utf-8");
+    content = await fs15.readFile(excludePath, "utf-8");
   } catch (err) {
     if (!isNotFoundError3(err))
       throw err;
@@ -3605,7 +3973,7 @@ async function ensureGitExcludePattern(repoPath, pattern) {
   }
   const needsLeadingNewline = content.length > 0 && !content.endsWith("\n");
   const newContent = content + (needsLeadingNewline ? "\n" : "") + pattern + "\n";
-  await fs14.writeFile(excludePath, newContent, "utf-8");
+  await fs15.writeFile(excludePath, newContent, "utf-8");
   log5.debug("git", "Added pattern to .git/info/exclude", { pattern });
 }
 async function loadOrCreateBranchContext(options) {
@@ -3669,10 +4037,12 @@ async function listEntries(branchRoot, flatSchema, contentRootName, options, vis
   const collections = flatSchema.filter((item) => item.type === "collection" && item.entries !== void 0 && (item.logicalPath === rootPath || item.logicalPath.startsWith(`${rootPath}/`)));
   const shouldInclude = visibility?.shouldInclude;
   const skippedFiles = [];
+  const resolver = options?.resolveReferences ? createReferenceResolver(branchRoot, flatSchema, contentRootName) : null;
   const collectionResults = await Promise.all(collections.map(async (collection) => {
     const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
     const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
-    return visible.map((entry) => ({ entry, collection }));
+    const resolved = resolver ? await resolveCollectionItemReferences(visible, collection, resolver) : visible;
+    return resolved.map((entry) => ({ entry, collection }));
   }));
   if (isBuildMode() && skippedFiles.length > 0) {
     const lines = skippedFiles.map(({ filename, collectionPath }) => `  - ${collectionPath}/${filename}`);
@@ -3686,8 +4056,7 @@ Expected {type}.{slug}.{id}.{ext} with a known entry type (a name declared in th
     for (const { entry, collection } of results) {
       const pathWithoutRoot = entry.logicalPath.startsWith(contentPrefix) ? entry.logicalPath.slice(contentPrefix.length) : entry.logicalPath;
       const pathSegments = pathWithoutRoot.split("/").filter(Boolean);
-      const urlSegments = entry.slug === "index" ? pathSegments.slice(0, -1) : pathSegments;
-      const urlPath = urlSegments.length > 0 ? `/${urlSegments.join("/")}`.toLowerCase() : "/";
+      const urlPath = computeEntryUrl(entry.collectionPath, entry.slug, contentRootName);
       const raw = entry.data;
       const meta = {
         entryPath: entry.logicalPath,
@@ -3732,7 +4101,7 @@ function isValidCropRect(x, y, w, h) {
     return false;
   return true;
 }
-function isPlainRecord(value) {
+function isPlainRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveBlockItem(blockField, item) {
@@ -3742,17 +4111,17 @@ function resolveBlockItem(blockField, item) {
   const template = blockField.templates?.find((t) => t.name === templateName);
   if (!template?.fields)
     return void 0;
-  const data = isPlainRecord(item.value) ? item.value : item;
+  const data = isPlainRecord2(item.value) ? item.value : item;
   return { fields: template.fields, data };
 }
-function isPlainRecord2(value) {
+function isPlainRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPositiveInt(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 function isValidImageCropValue(value) {
-  if (!isPlainRecord2(value))
+  if (!isPlainRecord3(value))
     return false;
   const { x, y, w, h } = value;
   if (typeof x !== "number" || typeof y !== "number" || typeof w !== "number" || typeof h !== "number") {
@@ -3760,78 +4129,78 @@ function isValidImageCropValue(value) {
   }
   return isValidCropRect(x, y, w, h);
 }
-function validateImageValue(field, value, path202) {
-  if (!isPlainRecord2(value)) {
-    return [{ fieldPath: path202, message: "Expected an image object with { src, alt }" }];
+function validateImageValue(field, value, path212) {
+  if (!isPlainRecord3(value)) {
+    return [{ fieldPath: path212, message: "Expected an image object with { src, alt }" }];
   }
   const errors = [];
   if (typeof value.src !== "string" || value.src.trim() === "") {
-    errors.push({ fieldPath: `${path202}.src`, message: "Image src is required" });
+    errors.push({ fieldPath: `${path212}.src`, message: "Image src is required" });
   }
   if (typeof value.alt !== "string") {
-    errors.push({ fieldPath: `${path202}.alt`, message: "Image alt text is required" });
+    errors.push({ fieldPath: `${path212}.alt`, message: "Image alt text is required" });
   } else if (value.alt.trim() === "" && field.altOptional !== true) {
-    errors.push({ fieldPath: `${path202}.alt`, message: "Image alt text is required" });
+    errors.push({ fieldPath: `${path212}.alt`, message: "Image alt text is required" });
   }
   if (value.width !== void 0 && !isPositiveInt(value.width)) {
-    errors.push({ fieldPath: `${path202}.width`, message: "Image width must be a positive integer" });
+    errors.push({ fieldPath: `${path212}.width`, message: "Image width must be a positive integer" });
   }
   if (value.height !== void 0 && !isPositiveInt(value.height)) {
     errors.push({
-      fieldPath: `${path202}.height`,
+      fieldPath: `${path212}.height`,
       message: "Image height must be a positive integer"
     });
   }
   if (value.crop !== void 0 && !isValidImageCropValue(value.crop)) {
-    errors.push({ fieldPath: `${path202}.crop`, message: "Invalid image crop rect" });
+    errors.push({ fieldPath: `${path212}.crop`, message: "Invalid image crop rect" });
   }
   return errors;
 }
 function referenceValueId(value) {
   if (typeof value === "string")
     return value;
-  if (isPlainRecord2(value) && typeof value.id === "string")
+  if (isPlainRecord3(value) && typeof value.id === "string")
     return value.id;
   return void 0;
 }
-function validateScalar(field, value, path202) {
+function validateScalar(field, value, path212) {
   switch (field.type) {
     case "number":
       if (typeof value !== "number" || !Number.isFinite(value)) {
-        return [{ fieldPath: path202, message: "Expected a number" }];
+        return [{ fieldPath: path212, message: "Expected a number" }];
       }
       return [];
     case "boolean":
       if (typeof value !== "boolean") {
-        return [{ fieldPath: path202, message: "Expected true or false" }];
+        return [{ fieldPath: path212, message: "Expected true or false" }];
       }
       return [];
     case "datetime":
       if (typeof value !== "string" || value !== "" && Number.isNaN(Date.parse(value))) {
-        return [{ fieldPath: path202, message: "Expected a valid date/time string" }];
+        return [{ fieldPath: path212, message: "Expected a valid date/time string" }];
       }
       return [];
     case "select": {
       if (typeof value !== "string") {
-        return [{ fieldPath: path202, message: "Expected a selection" }];
+        return [{ fieldPath: path212, message: "Expected a selection" }];
       }
       const options = selectOptionValues(field);
       if (value !== "" && !options.includes(value)) {
-        return [{ fieldPath: path202, message: `Must be one of: ${options.join(", ")}` }];
+        return [{ fieldPath: path212, message: `Must be one of: ${options.join(", ")}` }];
       }
       return [];
     }
     case "reference":
       if (referenceValueId(value) === void 0) {
-        return [{ fieldPath: path202, message: "Expected a reference id" }];
+        return [{ fieldPath: path212, message: "Expected a reference id" }];
       }
       return [];
     case "image":
-      return validateImageValue(field, value, path202);
+      return validateImageValue(field, value, path212);
     default:
       if (STRING_FIELD_TYPES.has(field.type)) {
         if (typeof value !== "string") {
-          return [{ fieldPath: path202, message: "Expected text" }];
+          return [{ fieldPath: path212, message: "Expected text" }];
         }
       }
       return [];
@@ -3854,12 +4223,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
       errors.push(...validateEntryData(field.fields, data, pathPrefix));
       continue;
     }
-    const path202 = pathPrefix ? `${pathPrefix}.${field.name}` : field.name;
+    const path212 = pathPrefix ? `${pathPrefix}.${field.name}` : field.name;
     const value = data[field.name];
     const isRequired = "required" in field && field.required === true;
     if (isRequired && isEmptyForRequired(field, value)) {
       const message = Array.isArray(value) ? "At least one item is required" : "This field is required";
-      errors.push({ fieldPath: path202, message });
+      errors.push({ fieldPath: path212, message });
       continue;
     }
     if (value === void 0 || value === null)
@@ -3867,12 +4236,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
     if (field.type === "block") {
       const blockField = field;
       if (!Array.isArray(value)) {
-        errors.push({ fieldPath: path202, message: "Expected a list of blocks" });
+        errors.push({ fieldPath: path212, message: "Expected a list of blocks" });
         continue;
       }
       value.forEach((item, index) => {
-        const itemPath = `${path202}[${index}]`;
-        if (!isPlainRecord2(item)) {
+        const itemPath = `${path212}[${index}]`;
+        if (!isPlainRecord3(item)) {
           errors.push({ fieldPath: itemPath, message: "Expected a block object" });
           return;
         }
@@ -3893,12 +4262,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
       const objectField = field;
       if (objectField.list) {
         if (!Array.isArray(value)) {
-          errors.push({ fieldPath: path202, message: "Expected a list of items" });
+          errors.push({ fieldPath: path212, message: "Expected a list of items" });
           continue;
         }
         value.forEach((item, index) => {
-          const itemPath = `${path202}[${index}]`;
-          if (!isPlainRecord2(item)) {
+          const itemPath = `${path212}[${index}]`;
+          if (!isPlainRecord3(item)) {
             errors.push({ fieldPath: itemPath, message: "Expected an object" });
             return;
           }
@@ -3906,28 +4275,28 @@ function validateEntryData(fields, data, pathPrefix = "") {
             errors.push(...validateEntryData(objectField.fields, item, itemPath));
           }
         });
-      } else if (!isPlainRecord2(value)) {
-        errors.push({ fieldPath: path202, message: "Expected an object" });
+      } else if (!isPlainRecord3(value)) {
+        errors.push({ fieldPath: path212, message: "Expected an object" });
       } else if (objectField.fields) {
-        errors.push(...validateEntryData(objectField.fields, value, path202));
+        errors.push(...validateEntryData(objectField.fields, value, path212));
       }
       continue;
     }
     if ("list" in field && field.list) {
       if (!Array.isArray(value)) {
-        errors.push({ fieldPath: path202, message: "Expected a list of values" });
+        errors.push({ fieldPath: path212, message: "Expected a list of values" });
         continue;
       }
       value.forEach((item, index) => {
-        errors.push(...validateScalar(field, item, `${path202}[${index}]`));
+        errors.push(...validateScalar(field, item, `${path212}[${index}]`));
       });
       continue;
     }
     if (Array.isArray(value) && KNOWN_FIELD_TYPES.has(field.type)) {
-      errors.push({ fieldPath: path202, message: "Expected a single value, not a list" });
+      errors.push({ fieldPath: path212, message: "Expected a single value, not a list" });
       continue;
     }
-    errors.push(...validateScalar(field, value, path202));
+    errors.push(...validateScalar(field, value, path212));
   }
   return errors;
 }
@@ -3971,6 +4340,37 @@ function assertBuildEntriesValid(items, phaseLabel) {
 ${lines.join("\n")}
 These are likely abandoned create-scaffolds (empty entries left behind when a create was started but never finished). Finish editing the entry (fill in its required fields) or delete the abandoned draft, then rebuild.`);
 }
+async function readGeneratedRecord(outputDir) {
+  try {
+    const raw = await fs17.readFile(path19.join(outputDir, GENERATED_RECORD_FILENAME), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || !("files" in parsed))
+      return [];
+    const { files } = parsed;
+    if (!Array.isArray(files))
+      return [];
+    return files.filter((entry) => typeof entry === "string");
+  } catch {
+    return [];
+  }
+}
+async function writeGeneratedRecord(outputDir, files) {
+  const record = { files: [...files].sort() };
+  await fs17.mkdir(outputDir, { recursive: true });
+  await fs17.writeFile(path19.join(outputDir, GENERATED_RECORD_FILENAME), `${JSON.stringify(record, null, 2)}
+`, "utf-8");
+}
+async function removeEmptyDirsUpward(startDir, stopAt) {
+  let current = startDir;
+  while (current.startsWith(stopAt) && current !== stopAt) {
+    try {
+      await fs17.rmdir(current);
+    } catch {
+      return;
+    }
+    current = path19.dirname(current);
+  }
+}
 async function generateAIContentFiles(options) {
   const { config, entrySchemaRegistry, outputDir, aiConfig: aiConfig2, _testFlatSchema } = options;
   const contentRootName = config.contentRoot || "content";
@@ -3993,23 +4393,45 @@ async function generateAIContentFiles(options) {
     config: aiConfig2,
     entryLinkUrl: config.entryLinkUrl
   });
-  const absoluteOutputDir = path18.resolve(outputDir) + path18.sep;
-  let fileCount = 0;
-  for (const [filePath, content] of result.files) {
-    const absolutePath = path18.resolve(path18.join(absoluteOutputDir, filePath));
+  const absoluteOutputDir = path19.resolve(outputDir) + path19.sep;
+  const resolveOutputPath = (filePath) => {
+    const absolutePath = path19.resolve(path19.join(absoluteOutputDir, filePath));
     if (!absolutePath.startsWith(absoluteOutputDir)) {
       throw new Error(`Path traversal detected in AI content output: ${filePath}`);
     }
-    await fs16.mkdir(path18.dirname(absolutePath), { recursive: true });
-    await fs16.writeFile(absolutePath, content, "utf-8");
+    return absolutePath;
+  };
+  const previousFiles = await readGeneratedRecord(absoluteOutputDir);
+  const currentFiles = [...result.files.keys()];
+  await writeGeneratedRecord(absoluteOutputDir, [.../* @__PURE__ */ new Set([...previousFiles, ...currentFiles])]);
+  let fileCount = 0;
+  for (const [filePath, content] of result.files) {
+    const absolutePath = resolveOutputPath(filePath);
+    await fs17.mkdir(path19.dirname(absolutePath), { recursive: true });
+    await fs17.writeFile(absolutePath, content, "utf-8");
     fileCount++;
   }
-  return { fileCount, outputDir: absoluteOutputDir };
+  const currentSet = new Set(currentFiles);
+  const stale = previousFiles.filter((filePath) => !currentSet.has(filePath));
+  let removedCount = 0;
+  for (const filePath of stale) {
+    const absolutePath = resolveOutputPath(filePath);
+    try {
+      await fs17.unlink(absolutePath);
+      removedCount++;
+    } catch (err) {
+      if (!isNodeError3(err) || err.code !== "ENOENT")
+        throw err;
+    }
+    await removeEmptyDirsUpward(path19.dirname(absolutePath), absoluteOutputDir);
+  }
+  await writeGeneratedRecord(absoluteOutputDir, currentFiles);
+  return { fileCount, removedCount, outputDir: absoluteOutputDir };
 }
 async function generateAIContentCLI(options) {
   const { projectDir, outputDir = "public/ai", configPath, appDir = "app" } = options;
   console.log("\nCanopyCMS generate-ai-content\n");
-  const canopyConfigPath = path19.join(projectDir, "canopycms.config.ts");
+  const canopyConfigPath = path20.join(projectDir, "canopycms.config.ts");
   let canopyConfigModule;
   try {
     canopyConfigModule = await jiti.import(canopyConfigPath);
@@ -4020,7 +4442,7 @@ async function generateAIContentCLI(options) {
   }
   const configExport = canopyConfigModule.default ?? canopyConfigModule.config ?? canopyConfigModule;
   const serverConfig = typeof configExport === "object" && configExport !== null && "server" in configExport ? configExport.server : configExport;
-  const schemasPath = path19.join(projectDir, appDir, "schemas.ts");
+  const schemasPath = path20.join(projectDir, appDir, "schemas.ts");
   let entrySchemaRegistry = {};
   try {
     const schemasModule = await jiti.import(schemasPath);
@@ -4031,7 +4453,7 @@ async function generateAIContentCLI(options) {
   let aiConfig2;
   if (configPath) {
     try {
-      const aiConfigModule = await jiti.import(path19.resolve(configPath));
+      const aiConfigModule = await jiti.import(path20.resolve(configPath));
       aiConfig2 = aiConfigModule.aiContentConfig ?? aiConfigModule.default ?? aiConfigModule.config;
     } catch (err) {
       console.error(`Could not load AI config from ${configPath}`);
@@ -4048,7 +4470,7 @@ async function generateAIContentCLI(options) {
     console.error("Make sure canopycms.config.ts uses defineCanopyConfig().");
     process.exit(1);
   }
-  const resolvedOutput = path19.resolve(projectDir, outputDir);
+  const resolvedOutput = path20.resolve(projectDir, outputDir);
   console.log(`  Output: ${resolvedOutput}`);
   console.log(`  Mode: ${serverConfig.mode ?? "dev"}`);
   const result = await generateAIContentFiles({
@@ -4059,10 +4481,13 @@ async function generateAIContentCLI(options) {
   });
   console.log(`
   Generated ${result.fileCount} files`);
+  if (result.removedCount > 0) {
+    console.log(`  Removed ${result.removedCount} stale files from the previous run`);
+  }
   console.log(`  Output: ${result.outputDir}
 `);
 }
-var __defProp3, __getOwnPropNames3, __esm3, __export3, init_normalize2, active2, init_logger2, ROOT_COLLECTION_ID, init_types3, normalizePathValue, flattenSchema, init_flatten2, primitiveFieldTypes2, fieldTypes2, init_types22, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned2, init_mode_env2, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned22, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, permissionTargetSchema2, pathPermissionSchema2, init_permissions2, init_helpers2, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, locks, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep, BASE58_PATTERN, CONTENT_ID_PATTERN, PHYSICAL_SEGMENT_PATTERN, isValidId, EMPTY_LOGICAL_PATH, ContentIdIndex, registry, finalization, LOG_LEVELS2, DebugLogger2, testLogger2, log2, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, STATIC_DEPLOY_USER, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SCHEMA_GENERATION_RESOURCE, BranchSchemaCache, RESOURCE, getFormatExtension, isDataOnlyFormat, asRecord, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, BranchSyncingError, DuplicateContentIdError, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, FLAT_CELL_TYPES, log22, BASE58_CHAR, ENTRY_LINK_PATTERN, log3, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, BranchRegistry, log4, OccWriteConflictError, BRANCH_META_DIR, BRANCH_META_FILE, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataCorruptError, BranchMetadataFileManager, getBranchMetadataFileManager, loadBranchContext, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, log5, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, GitConflictError, GitRemoteRefMissingError, GitManager, log6, workspaceInitLocks, BranchWorkspaceManager, log7, normalizePath, readEntryData, parseTypedFilename, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, jiti;
+var __defProp3, __getOwnPropNames3, __esm3, __export3, active2, init_logger2, init_normalize2, ROOT_COLLECTION_ID, init_types3, normalizePathValue, flattenSchema, init_flatten2, primitiveFieldTypes2, fieldTypes2, init_types22, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned2, init_mode_env2, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned22, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, permissionTargetSchema2, pathPermissionSchema2, init_permissions2, init_helpers2, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, EVIDENCE_MAX_DEPTH, locks, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep, DEFAULT_SEO_FIELD_NAMES, SEO_GROUP_FIELDS, BASE58_PATTERN, CONTENT_ID_PATTERN, PHYSICAL_SEGMENT_PATTERN, isValidId, EMPTY_LOGICAL_PATH, ContentIdIndex, parseTypedFilename, CONTENT_EXTENSIONS, registry, finalization, LOG_LEVELS2, DebugLogger2, testLogger2, log2, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, STATIC_DEPLOY_USER, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SCHEMA_GENERATION_RESOURCE, BranchSchemaCache, RESOURCE, getFormatExtension, isDataOnlyFormat, asRecord, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, FLAT_CELL_TYPES, log22, BASE58_CHAR, ENTRY_LINK_PATTERN, log3, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, BranchRegistry, log4, OccWriteConflictError, BRANCH_META_DIR, BRANCH_META_FILE, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataCorruptError, BranchMetadataFileManager, getBranchMetadataFileManager, loadBranchContext, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, log5, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, GitConflictError, GitRemoteRefMissingError, GitManager, log6, workspaceInitLocks, BranchWorkspaceManager, log7, normalizePath, readEntryData, createReferenceResolver, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, jiti;
 var init_generate_ai_content = __esm({
   "dist/cli/generate-ai-content.js"() {
     "use strict";
@@ -4075,17 +4500,17 @@ var init_generate_ai_content = __esm({
       for (var name in all)
         __defProp3(target, name, { get: all[name], enumerable: true });
     };
-    init_normalize2 = __esm3({
-      "dist/paths/normalize.js"() {
-        "use strict";
-      }
-    });
     init_logger2 = __esm3({
       "dist/utils/logger.js"() {
         "use strict";
         active2 = console;
       }
     });
+    init_normalize2 = __esm3({
+      "dist/paths/normalize.js"() {
+        "use strict";
+      }
+    });
     init_types3 = __esm3({
       "dist/paths/types.js"() {
         "use strict";
@@ -4259,7 +4684,12 @@ var init_generate_ai_content = __esm({
           collections: z22.array(z22.string().min(1)).min(1).optional(),
           entryTypes: z22.array(z22.string().min(1)).min(1).optional(),
           displayField: z22.string().min(1).optional(),
-          options: z22.array(referenceOptionSchema2).optional()
+          options: z22.array(referenceOptionSchema2).optional(),
+          // Must be listed here, not just on ReferenceFieldConfig: zod strips unknown keys by
+          // default, so a consumer that adopts this schema's parse output would silently delete a
+          // runtime-consumed flag and the feature would no-op with no error. (`resolvedSchema` is
+          // absent on purpose — it is type-inference-only and stripping it changes no behavior.)
+          includeBody: z22.boolean().optional()
         });
         fieldHolder2 = [z22.never()];
         blockSchema2 = z22.object({
@@ -4380,6 +4810,9 @@ var init_generate_ai_content = __esm({
         deployedAsSchema2 = z52.enum(["static", "server"]).default("server");
         contentRootSchema2 = relativePathSchema2.default("content");
         sourceRootSchema2 = z52.string().min(1).optional();
+        basePathSchema2 = z52.string().transform((value) => value.trim()).refine((value) => value.length > 0, {
+          message: "basePath must not be empty or only whitespace"
+        }).optional();
         deploymentNameSchema2 = z52.string().default("prod");
         devContentSyncSchema2 = z52.enum(["off", "warn"]).default("warn");
         devConfigSchema2 = z52.object({
@@ -4442,6 +4875,7 @@ var init_generate_ai_content = __esm({
           deploymentName: deploymentNameSchema2.optional(),
           contentRoot: contentRootSchema2.default("content"),
           sourceRoot: sourceRootSchema2.optional(),
+          basePath: basePathSchema2,
           editor: editorConfigSchema2.optional(),
           authPlugin: z52.custom().optional(),
           entryLinkUrl: z52.custom().optional(),
@@ -4611,32 +5045,32 @@ var init_generate_ai_content = __esm({
           // - shouldCommit(), shouldPush()
           // Add client-unsafe methods (use Node.js APIs)
           getWorkspaceRoot(_sourceRoot) {
-            return path82.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE2);
+            return path9.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE2);
           }
           getContentRoot(contentRoot, sourceRoot) {
-            return path82.resolve(sourceRoot ?? process.cwd(), contentRoot);
+            return path9.resolve(sourceRoot ?? process.cwd(), contentRoot);
           }
           getContentBranchesRoot(sourceRoot) {
-            return path82.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+            return path9.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
           }
           getContentBranchRoot(branchName, sourceRoot) {
-            return path82.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+            return path9.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
           }
           getGitExcludePattern() {
             return ".canopy-meta/";
           }
           getPermissionsFilePath(root) {
-            return path82.join(root, this.getPermissionsFileName());
+            return path9.join(root, this.getPermissionsFileName());
           }
           getGroupsFilePath(root) {
-            return path82.join(root, this.getGroupsFileName());
+            return path9.join(root, this.getGroupsFileName());
           }
           getRemoteUrlConfig() {
             return {
               shouldAutoInitLocal: false,
               defaultRemotePath: "",
               envVarName: "CANOPYCMS_REMOTE_URL",
-              autoDetectRemotePath: path82.join(this.getWorkspaceRoot(), "remote.git")
+              autoDetectRemotePath: path9.join(this.getWorkspaceRoot(), "remote.git")
             };
           }
           requiresExistingRepo() {
@@ -4648,7 +5082,7 @@ var init_generate_ai_content = __esm({
             return `canopycms-settings-${resolveDeploymentName2(config, "prod")}`;
           }
           getSettingsRoot(sourceRoot) {
-            return path82.join(this.getWorkspaceRoot(sourceRoot), "settings");
+            return path9.join(this.getWorkspaceRoot(sourceRoot), "settings");
           }
           usesSeparateSettingsBranch() {
             return true;
@@ -4665,25 +5099,25 @@ var init_generate_ai_content = __esm({
         DevStrategy2 = class extends DevClientSafeStrategy2 {
           // Inherits client-safe methods from DevClientSafeStrategy
           getWorkspaceRoot(sourceRoot) {
-            return path82.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
+            return path9.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
           }
           getContentRoot(contentRoot, sourceRoot) {
-            return path82.resolve(sourceRoot ?? process.cwd(), contentRoot);
+            return path9.resolve(sourceRoot ?? process.cwd(), contentRoot);
           }
           getContentBranchesRoot(sourceRoot) {
-            return path82.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+            return path9.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
           }
           getContentBranchRoot(branchName, sourceRoot) {
-            return path82.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+            return path9.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
           }
           getGitExcludePattern() {
             return ".canopy-meta/";
           }
           getPermissionsFilePath(root) {
-            return path82.join(root, this.getPermissionsFileName());
+            return path9.join(root, this.getPermissionsFileName());
           }
           getGroupsFilePath(root) {
-            return path82.join(root, this.getGroupsFileName());
+            return path9.join(root, this.getGroupsFileName());
           }
           getRemoteUrlConfig() {
             return {
@@ -4701,7 +5135,7 @@ var init_generate_ai_content = __esm({
             return `canopycms-settings-${resolveDeploymentName2(config, "local")}`;
           }
           getSettingsRoot(sourceRoot) {
-            return path82.join(this.getWorkspaceRoot(sourceRoot), "settings");
+            return path9.join(this.getWorkspaceRoot(sourceRoot), "settings");
           }
           usesSeparateSettingsBranch() {
             return true;
@@ -4736,7 +5170,12 @@ var init_generate_ai_content = __esm({
         init_mode_env2();
       }
     });
+    BLOCK_DISCRIMINATOR_KEYS = ["template", "_type"];
+    BLOCK_STRUCTURAL_KEYS = new Set(BLOCK_DISCRIMINATOR_KEYS);
+    EVIDENCE_MAX_DEPTH = 6;
     locks = /* @__PURE__ */ new Map();
+    init_logger2();
+    init_logger2();
     META_DIR = ".canopy-meta";
     CONTENT_WRITE_LOCK_NAME = "content-write.lock";
     DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2e3;
@@ -4749,6 +5188,67 @@ var init_generate_ai_content = __esm({
     sleep = (ms) => new Promise((resolve2) => {
       setTimeout(resolve2, ms);
     });
+    DEFAULT_SEO_FIELD_NAMES = {
+      title: "metaTitle",
+      description: "metaDescription",
+      ogImage: "ogImage",
+      ogType: "ogType",
+      canonical: "canonical",
+      noindex: "noindex",
+      twitterCard: "twitterCard"
+    };
+    SEO_GROUP_FIELDS = [
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.title,
+        type: "string",
+        label: "Meta Title",
+        description: "Overrides the page title in search results and social cards.",
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.description,
+        type: "string",
+        label: "Meta Description",
+        description: "Summary shown under the title in search results.",
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.ogImage,
+        type: "string",
+        label: "Social Image URL",
+        description: "Image for social cards. Site-relative or absolute.",
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.ogType,
+        type: "select",
+        label: "OpenGraph Type",
+        options: ["website", "article", "profile"],
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.canonical,
+        type: "string",
+        label: "Canonical URL",
+        description: "Set only to point at a different canonical copy of this page.",
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.noindex,
+        type: "boolean",
+        label: "Hide from search engines",
+        description: "Marks the page noindex AND drops it from the sitemap.",
+        required: false
+      },
+      {
+        name: DEFAULT_SEO_FIELD_NAMES.twitterCard,
+        type: "select",
+        label: "Twitter Card",
+        options: ["summary", "summary_large_image"],
+        required: false
+      }
+    ];
+    init_normalize2();
     init_normalize2();
     BASE58_PATTERN = "[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]";
     CONTENT_ID_PATTERN = new RegExp(`^${BASE58_PATTERN}{12}$`);
@@ -5066,6 +5566,31 @@ var init_generate_ai_content = __esm({
         this.pathToId.set(newRelativePath, id);
       }
     };
+    parseTypedFilename = (filename, entryTypes) => {
+      if (filename.startsWith("."))
+        return null;
+      const lastDot = filename.lastIndexOf(".");
+      if (lastDot === -1)
+        return null;
+      const nameWithoutExt = filename.slice(0, lastDot);
+      const parts = nameWithoutExt.split(".");
+      if (parts.length < 3)
+        return null;
+      const potentialType = parts[0];
+      if (entryTypes && !entryTypes.some((e) => e.name === potentialType)) {
+        return null;
+      }
+      const id = parts[parts.length - 1];
+      if (!isValidId(id))
+        return null;
+      const slug = parts.slice(1, -1).join(".").toLowerCase();
+      return {
+        type: potentialType,
+        slug,
+        id
+      };
+    };
+    CONTENT_EXTENSIONS = [".md", ".mdx", ".json", ".yaml"];
     registry = /* @__PURE__ */ new Map();
     finalization = new FinalizationRegistry(({ rootKey, ref }) => {
       const refs = registry.get(rootKey);
@@ -5303,7 +5828,7 @@ var init_generate_ai_content = __esm({
        * the project root, regardless of which entrypoint produced the cwd branchRoot.
        */
       skipDiskCache(branchRoot) {
-        return isBuildMode() || path72.resolve(branchRoot) === path72.resolve(process.cwd());
+        return isBuildMode() || path82.resolve(branchRoot) === path82.resolve(process.cwd());
       }
       /**
        * Get schema for a branch (loads from cache or resolves fresh).
@@ -5329,14 +5854,14 @@ var init_generate_ai_content = __esm({
        * Load schema from cache or resolve fresh if cache is missing or stale.
        */
       async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
-        const contentRoot = path72.join(branchRoot, contentRootName);
+        const contentRoot = path82.join(branchRoot, contentRootName);
         const skipDiskCache = this.skipDiskCache(branchRoot);
         if (!skipDiskCache) {
-          const cacheDir = path72.join(branchRoot, ".canopy-meta");
-          const cachePath = path72.join(cacheDir, "schema-cache.json");
+          const cacheDir = path82.join(branchRoot, ".canopy-meta");
+          const cachePath = path82.join(cacheDir, "schema-cache.json");
           let cacheData = null;
           try {
-            const cacheContent = await fs62.readFile(cachePath, "utf-8");
+            const cacheContent = await fs72.readFile(cachePath, "utf-8");
             cacheData = JSON.parse(cacheContent);
           } catch {
             cacheData = null;
@@ -5373,7 +5898,7 @@ var init_generate_ai_content = __esm({
        */
       async resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, options) {
         const { skipDiskCache } = options;
-        const contentRoot = path72.join(branchRoot, contentRootName);
+        const contentRoot = path82.join(branchRoot, contentRootName);
         const read = skipDiskCache ? null : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
         const result = await this.resolveFresh(contentRoot, entrySchemaRegistry);
         if (!isValidSchema(result.schema)) {
@@ -5386,9 +5911,9 @@ var init_generate_ai_content = __esm({
         }
         const flatSchema = flattenSchema(result.schema, contentRootName);
         if (!skipDiskCache) {
-          const cacheDir = path72.join(branchRoot, ".canopy-meta");
-          const cachePath = path72.join(cacheDir, "schema-cache.json");
-          await fs62.unlink(path72.join(cacheDir, "schema-cache.stale")).catch(() => {
+          const cacheDir = path82.join(branchRoot, ".canopy-meta");
+          const cachePath = path82.join(cacheDir, "schema-cache.json");
+          await fs72.unlink(path82.join(cacheDir, "schema-cache.stale")).catch(() => {
           });
           if (read && read.ok) {
             const newCache = {
@@ -5398,13 +5923,13 @@ var init_generate_ai_content = __esm({
               cachedAt: (/* @__PURE__ */ new Date()).toISOString(),
               generation: read.token
             };
-            await fs62.mkdir(cacheDir, { recursive: true });
-            const tmpPath = path72.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-            await fs62.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
+            await fs72.mkdir(cacheDir, { recursive: true });
+            const tmpPath = path82.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
+            await fs72.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
             try {
-              await fs62.rename(tmpPath, cachePath);
+              await fs72.rename(tmpPath, cachePath);
             } catch (err) {
-              await fs62.unlink(tmpPath).catch(() => {
+              await fs72.unlink(tmpPath).catch(() => {
               });
               throw err;
             }
@@ -5514,9 +6039,17 @@ var init_generate_ai_content = __esm({
         this.paths = sorted;
       }
     };
+    UrlPathConflictError = class extends ContentConflictError {
+      constructor(message, conflictingPath) {
+        super(message);
+        this.name = "UrlPathConflictError";
+        this.conflictingPath = conflictingPath;
+      }
+    };
     DEFAULT_INDEX_FRESHNESS_INTERVAL_MS = 1e3;
     FORCED_REFRESH_MIN_INTERVAL_MS = 5e3;
     STALE_LOOKUP = Symbol("stale-index-lookup");
+    createReferenceResolveCache = () => /* @__PURE__ */ new Map();
     ContentStore = class {
       constructor(root, flatSchema, options = {}) {
         this.indexGeneration = 0;
@@ -5525,7 +6058,7 @@ var init_generate_ai_content = __esm({
         this.lastDiskProbeMs = 0;
         this.lastForcedRefreshMs = 0;
         this.indexBuild = null;
-        this.root = path10.resolve(root);
+        this.root = path11.resolve(root);
         this.contentRootName = options.contentRootName || "content";
         this.indexFreshnessIntervalMs = options.indexFreshnessIntervalMs ?? DEFAULT_INDEX_FRESHNESS_INTERVAL_MS;
         this.contentWriteLockWaitMs = options.contentWriteLockWaitMs ?? DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS;
@@ -5673,7 +6206,7 @@ var init_generate_ai_content = __esm({
       async findEntryPathsById(dir, id) {
         let entries;
         try {
-          entries = await fs9.readdir(dir, { withFileTypes: true });
+          entries = await fs10.readdir(dir, { withFileTypes: true });
         } catch (err) {
           if (isNodeError3(err) && err.code === "ENOENT")
             return [];
@@ -5684,7 +6217,7 @@ var init_generate_ai_content = __esm({
           if (entry.isDirectory())
             continue;
           if (extractIdFromFilename(entry.name) === id) {
-            matches.push(path10.relative(this.root, path10.join(dir, entry.name)));
+            matches.push(path11.relative(this.root, path11.join(dir, entry.name)));
           }
         }
         return matches.sort();
@@ -5696,11 +6229,11 @@ var init_generate_ai_content = __esm({
       getSchemaItems() {
         return this.schemaIndex.values();
       }
-      assertSchemaItem(path202) {
-        const normalized = normalizeFilesystemPath(path202);
+      assertSchemaItem(path212) {
+        const normalized = normalizeFilesystemPath(path212);
         const item = this.schemaIndex.get(normalized);
         if (!item) {
-          throw new ContentStoreError(`Unknown schema item: ${path202}`, "NO_SCHEMA_ITEM");
+          throw new ContentStoreError(`Unknown schema item: ${path212}`, "NO_SCHEMA_ITEM");
         }
         return item;
       }
@@ -5767,6 +6300,26 @@ var init_generate_ai_content = __esm({
           return this.createLockKey(schemaItem, slug);
         return prePass.id ? this.idLockKey(prePass.id) : prePass.absolutePath;
       }
+      /**
+       * Refuse a create/rename that would give a second entry a `urlPath` another entry already
+       * holds. See url-collision.ts for the two shapes that count, and the legitimate
+       * landing-page-beside-a-collection shape that deliberately does not.
+       *
+       * @param collectionDir Absolute physical directory the entry will live in.
+       * @param slug The entry's slug, as it will be written.
+       */
+      async assertUrlPathAvailable(collectionDir, slug) {
+        const claimant = await findUrlPathClaimant({
+          collectionDir,
+          slug,
+          contentRoot: path11.resolve(this.root, this.contentRootName)
+        });
+        if (!claimant)
+          return;
+        const relative2 = path11.relative(this.root, claimant.physicalPath);
+        const message = claimant.kind === "sibling-collection-index" ? `An entry with slug "${slug}" would share a URL with the index entry of the "${claimant.name}" collection beside it ("${relative2}"), and only one of them could be served there. Rename this entry, or remove that collection's index entry.` : `An index entry here would share a URL with the "${claimant.name}" entry in the parent collection ("${relative2}"), and only one of them could be served there. Rename that entry, or give this collection's landing page a different slug.`;
+        throw new UrlPathConflictError(message, claimant.physicalPath);
+      }
       /**
        * Build absolute and relative paths with security validation.
        * All entries use the unified filename pattern: {type}.{slug}.{id}.{ext}
@@ -5783,7 +6336,7 @@ var init_generate_ai_content = __esm({
        * @param options.entryTypeName - For collections with multiple entry types, specify which one to use. Defaults to the default entry type.
        */
       async buildPaths(schemaItem, slug, options = {}) {
-        const rootWithSep = this.root.endsWith(path10.sep) ? this.root : `${this.root}${path10.sep}`;
+        const rootWithSep = this.root.endsWith(path11.sep) ? this.root : `${this.root}${path11.sep}`;
         if (schemaItem.type === "entry-type") {
           const parentPath = schemaItem.parentPath || "";
           const parentCollection = this.schemaIndex.get(parentPath);
@@ -5816,7 +6369,7 @@ var init_generate_ai_content = __esm({
           const entryTypeName = entryTypeConfig?.name || "entry";
           let collectionRoot = await resolveCollectionPath(this.root, schemaItem.logicalPath);
           if (!collectionRoot) {
-            collectionRoot = path10.resolve(this.root, schemaItem.logicalPath);
+            collectionRoot = path11.resolve(this.root, schemaItem.logicalPath);
           }
           if (!collectionRoot.startsWith(rootWithSep)) {
             throw new ContentStoreError("Path traversal detected", "VALIDATION");
@@ -5826,7 +6379,7 @@ var init_generate_ai_content = __esm({
           let existingEntryType;
           let foundExisting = false;
           if (!id) {
-            const entries = await fs9.readdir(collectionRoot, { withFileTypes: true }).catch(() => []);
+            const entries = await fs10.readdir(collectionRoot, { withFileTypes: true }).catch(() => []);
             const existingFile = entries.find((entry) => {
               if (entry.isDirectory())
                 return false;
@@ -5852,14 +6405,14 @@ var init_generate_ai_content = __esm({
             }
             filename = `${finalEntryTypeName}.${safeSlug}.${id}${ext}`;
           }
-          const resolved = path10.resolve(collectionRoot, filename);
-          const collectionRootWithSep = collectionRoot.endsWith(path10.sep) ? collectionRoot : `${collectionRoot}${path10.sep}`;
+          const resolved = path11.resolve(collectionRoot, filename);
+          const collectionRootWithSep = collectionRoot.endsWith(path11.sep) ? collectionRoot : `${collectionRoot}${path11.sep}`;
           if (!resolved.startsWith(collectionRootWithSep)) {
             throw new ContentStoreError("Path traversal detected", "VALIDATION");
           }
           return {
             absolutePath: resolved,
-            relativePath: path10.relative(this.root, resolved),
+            relativePath: path11.relative(this.root, resolved),
             id,
             entryTypeName: finalEntryTypeName,
             existed
@@ -5895,8 +6448,8 @@ var init_generate_ai_content = __esm({
       async read(collectionPath, slug = "", options = {}) {
         const schemaItem = this.assertSchemaItem(collectionPath);
         const { absolutePath, relativePath, entryTypeName: resolvedEntryTypeName } = await this.buildPaths(schemaItem, slug);
-        const stat = await fs9.stat(absolutePath);
-        const raw = await fs9.readFile(absolutePath, "utf8");
+        const stat = await fs10.stat(absolutePath);
+        const raw = await fs10.readFile(absolutePath, "utf8");
         let doc;
         let format;
         let fields;
@@ -5935,7 +6488,7 @@ var init_generate_ai_content = __esm({
             absolutePath
           };
         } else {
-          const parsed = matter(raw);
+          const parsed = matter2(raw);
           doc = {
             collection: schemaItem.logicalPath,
             collectionName: schemaItem.name,
@@ -5998,7 +6551,7 @@ var init_generate_ai_content = __esm({
                 const indexedPath = guardIndex.findById(id)?.relativePath ?? null;
                 if (indexedPath && indexedPath !== relativePath) {
                   const quarantined = guardIndex.getDuplicateFor(id);
-                  const bothOnDisk = await filePathExists3(absolutePath) && await filePathExists3(path10.join(this.root, indexedPath));
+                  const bothOnDisk = await filePathExists3(absolutePath) && await filePathExists3(path11.join(this.root, indexedPath));
                   if (quarantined || bothOnDisk) {
                     throw new DuplicateContentIdError(id, [
                       indexedPath,
@@ -6009,10 +6562,18 @@ var init_generate_ai_content = __esm({
                   }
                 }
               }
-              await fs9.mkdir(path10.dirname(absolutePath), { recursive: true });
+              if (!await filePathExists3(absolutePath)) {
+                const chosenSlug = extractSlugFromFilename(path11.basename(absolutePath));
+                const routable = parseSlug(chosenSlug);
+                if (!routable.ok) {
+                  throw new ContentStoreError(`Cannot create entry "${chosenSlug}": ${routable.error}. An entry whose slug is not addressable as a URL segment would build and then 404 on every visit.`, "VALIDATION");
+                }
+                await this.assertUrlPathAvailable(path11.dirname(absolutePath), chosenSlug);
+              }
+              await fs10.mkdir(path11.dirname(absolutePath), { recursive: true });
               if (input.expectedVersion !== void 0) {
                 try {
-                  const existing = await fs9.stat(absolutePath);
+                  const existing = await fs10.stat(absolutePath);
                   if (input.expectedVersion === null) {
                     throw new ContentConflictError("An entry with this slug already exists");
                   }
@@ -6029,7 +6590,7 @@ var init_generate_ai_content = __esm({
                 }
               }
               if (existingId && !await filePathExists3(absolutePath)) {
-                const actualRelPaths = await this.findEntryPathsById(path10.dirname(absolutePath), existingId);
+                const actualRelPaths = await this.findEntryPathsById(path11.dirname(absolutePath), existingId);
                 if (actualRelPaths.length > 1) {
                   throw new DuplicateContentIdError(existingId, actualRelPaths);
                 }
@@ -6039,14 +6600,15 @@ var init_generate_ai_content = __esm({
                   throw new ContentConflictError();
                 }
               }
+              const existingRaw = input.format === "json" ? void 0 : await readFileIfExists(absolutePath);
               let content;
               if (input.format === "json") {
                 content = `${JSON.stringify(input.data ?? {}, null, 2)}
 `;
               } else if (input.format === "yaml") {
-                content = yamlStringify(input.data ?? {});
+                content = serializeYaml(input.data ?? {}, existingRaw);
               } else {
-                content = matter.stringify(input.body, input.data ?? {});
+                content = serializeFrontmatter(input.body, input.data ?? {}, existingRaw);
               }
               await atomicWriteFile2(absolutePath, content);
               const liveIndex = this._idIndex;
@@ -6055,7 +6617,7 @@ var init_generate_ai_content = __esm({
                 const existing = liveIndex.findById(id);
                 if (existing) {
                   if (existing.relativePath !== relativePath) {
-                    staleOldAbsPath = path10.join(this.root, existing.relativePath);
+                    staleOldAbsPath = path11.join(this.root, existing.relativePath);
                     liveIndex.updatePath(existing.id, relativePath);
                   }
                 } else {
@@ -6068,13 +6630,13 @@ var init_generate_ai_content = __esm({
                 }
               }
               if (staleOldAbsPath) {
-                await fs9.unlink(staleOldAbsPath).catch((err) => {
+                await fs10.unlink(staleOldAbsPath).catch((err) => {
                   if (!isNodeError3(err) || err.code !== "ENOENT")
                     throw err;
                 });
               }
               await this.recordOwnMutation(liveIndex);
-              const afterStat = await fs9.stat(absolutePath);
+              const afterStat = await fs10.stat(absolutePath);
               const base = {
                 collection: schemaItem.logicalPath,
                 collectionName: schemaItem.name,
@@ -6152,7 +6714,7 @@ var init_generate_ai_content = __esm({
         const schemaItem = this.assertSchemaItem(collectionPath);
         const { absolutePath } = await this.buildPaths(schemaItem, slug);
         try {
-          await fs9.access(absolutePath);
+          await fs10.access(absolutePath);
           return true;
         } catch (err) {
           if (isNodeError3(err) && err.code === "ENOENT")
@@ -6191,7 +6753,7 @@ var init_generate_ai_content = __esm({
         const collectionRoot = await resolveCollectionPath(this.root, collectionPath);
         if (!collectionRoot)
           return 0;
-        const entries = await fs9.readdir(collectionRoot, { withFileTypes: true }).catch(() => []);
+        const entries = await fs10.readdir(collectionRoot, { withFileTypes: true }).catch(() => []);
         return entries.filter((entry) => !entry.isDirectory() && extractEntryTypeFromFilename(entry.name) === entryTypeName).length;
       }
       /**
@@ -6215,7 +6777,7 @@ var init_generate_ai_content = __esm({
         const collection = this.assertCollection(collectionPath);
         const prePass = await this.buildPaths(collection, slug);
         if (!prePass.existed) {
-          await fs9.unlink(prePass.absolutePath);
+          await fs10.unlink(prePass.absolutePath);
           return;
         }
         let lockKey = this.entryLockKey(collection, slug, prePass);
@@ -6231,7 +6793,7 @@ var init_generate_ai_content = __esm({
                 return RETRY_KEY;
               }
               const { absolutePath, relativePath } = inLock;
-              await fs9.unlink(absolutePath);
+              await fs10.unlink(absolutePath);
               const liveIndex = this._idIndex;
               const id = liveIndex.findByPath(relativePath);
               if (id) {
@@ -6267,6 +6829,10 @@ var init_generate_ai_content = __esm({
         if (currentSlug === safeNewSlug) {
           return { newPath: `${collectionPath}/${currentSlug}` };
         }
+        const routable = parseSlug(safeNewSlug);
+        if (!routable.ok) {
+          throw new ContentStoreError(`Cannot rename to "${safeNewSlug}": ${routable.error}. An entry whose slug is not addressable as a URL segment would build and then 404 on every visit.`, "VALIDATION");
+        }
         const prePass = await this.buildPaths(collection, currentSlug);
         if (!prePass.existed) {
           throw new ContentStoreError(`Entry not found: ${currentSlug}`, "NOT_FOUND");
@@ -6293,7 +6859,7 @@ var init_generate_ai_content = __esm({
               }
               destLockKey = currentDestKey;
               const { absolutePath: currentPath, relativePath: currentRelPath } = inLock;
-              const currentFilename = path10.basename(currentPath);
+              const currentFilename = path11.basename(currentPath);
               const parts = currentFilename.split(".");
               if (parts.length < 4) {
                 throw new ContentStoreError(`Invalid entry filename format: ${currentFilename}`, "VALIDATION");
@@ -6302,10 +6868,10 @@ var init_generate_ai_content = __esm({
               const contentId = parts[parts.length - 2];
               const ext = `.${parts[parts.length - 1]}`;
               const newFilename = `${entryTypeName}.${safeNewSlug}.${contentId}${ext}`;
-              const parentDir = path10.dirname(currentPath);
-              const newPath = path10.join(parentDir, newFilename);
+              const parentDir = path11.dirname(currentPath);
+              const newPath = path11.join(parentDir, newFilename);
               try {
-                const entries = await fs9.readdir(parentDir, { withFileTypes: true });
+                const entries = await fs10.readdir(parentDir, { withFileTypes: true });
                 for (const entry of entries) {
                   if (entry.isDirectory())
                     continue;
@@ -6318,16 +6884,17 @@ var init_generate_ai_content = __esm({
                 if (err instanceof ContentStoreError)
                   throw err;
               }
+              await this.assertUrlPathAvailable(parentDir, safeNewSlug);
               try {
-                await fs9.link(currentPath, newPath);
+                await fs10.link(currentPath, newPath);
               } catch (err) {
                 if (isNodeError3(err) && err.code === "EEXIST") {
                   throw new ContentStoreError(`Entry with slug "${safeNewSlug}" already exists in collection "${collectionPath}"`, "VALIDATION");
                 }
                 throw err;
               }
-              await fs9.unlink(currentPath);
-              const newRelativePath = path10.relative(this.root, newPath);
+              await fs10.unlink(currentPath);
+              const newRelativePath = path11.relative(this.root, newPath);
               const liveIndex = this._idIndex;
               const entryId = liveIndex.findByPath(currentRelPath);
               if (entryId) {
@@ -6399,34 +6966,57 @@ var init_generate_ai_content = __esm({
         }
         return entries;
       }
+      /**
+       * Resolve every `reference` field in `data` against `fields`, returning a copy.
+       *
+       * This is what `read()` applies automatically (unless `resolveReferences: false`), exposed
+       * so BATCH surfaces can opt into the same resolution without duplicating the walk: the
+       * listing primitives in content-listing.ts and content-tree.ts read entry files straight
+       * off disk and never touch this store, so before this existed a `reference` field reached
+       * `listEntries()`/`buildContentTree()` callers as a bare id string or `null`.
+       *
+       * Pass one {@link ReferenceResolveCache} across a whole batch so a target referenced by
+       * many entries is read once rather than once per referencing entry. Omit `cache` and the
+       * behavior is exactly what `read()` has always done, unmemoized.
+       *
+       * **Path ACLs are not consulted for the targets.** Resolution goes through this store's
+       * own `read()`, below the per-entry permission check in content-reader.ts — so a resolved
+       * target may be an entry the caller could not `read()` directly. That is pre-existing
+       * `read()` behavior, matched here on purpose so one rule covers both; see the
+       * `resolveReferences` option in content-listing.ts for the note adopters see.
+       */
+      async resolveReferences(data, fields, cache) {
+        return this.resolveReferencesInData(data, fields, cache);
+      }
       /**
        * Recursively resolve reference fields in data.
        * This traverses objects, arrays, and blocks to find and resolve all reference fields.
        */
-      async resolveReferencesInData(data, fields) {
+      async resolveReferencesInData(data, fields, cache) {
         const resolved = { ...data };
         const idIndex = await this.idIndex();
         for (const field of fields) {
           if (field.type === "group") {
-            const groupResolved = await this.resolveReferencesInData(resolved, field.fields);
+            const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache);
             Object.assign(resolved, groupResolved);
             continue;
           }
           const value = data[field.name];
           if (field.type === "reference") {
+            const includeBody = field.includeBody === true;
             if (typeof value === "string" && value) {
-              resolved[field.name] = await this.resolveSingleReference(value, idIndex);
+              resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache);
             } else if (field.list && Array.isArray(value)) {
-              resolved[field.name] = await Promise.all(value.map((id) => typeof id === "string" ? this.resolveSingleReference(id, idIndex) : null));
+              resolved[field.name] = await Promise.all(value.map((id) => typeof id === "string" ? this.resolveSingleReference(id, idIndex, includeBody, cache) : null));
             }
           } else if (field.type === "object" && value) {
             const objectField = field;
             if (!objectField.fields)
               continue;
             if (objectField.list && Array.isArray(value)) {
-              resolved[field.name] = await Promise.all(value.map((item) => typeof item === "object" && item !== null ? this.resolveReferencesInData(item, objectField.fields) : item));
+              resolved[field.name] = await Promise.all(value.map((item) => typeof item === "object" && item !== null ? this.resolveReferencesInData(item, objectField.fields, cache) : item));
             } else if (typeof value === "object") {
-              resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields);
+              resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache);
             }
           } else if (field.type === "block" && Array.isArray(value)) {
             const blockField = field;
@@ -6439,7 +7029,7 @@ var init_generate_ai_content = __esm({
                 return block;
               return {
                 ...b,
-                value: await this.resolveReferencesInData(b.value, template.fields)
+                value: await this.resolveReferencesInData(b.value, template.fields, cache)
               };
             }));
           }
@@ -6447,7 +7037,56 @@ var init_generate_ai_content = __esm({
         return resolved;
       }
       /**
-       * Resolve a single reference ID to full entry data.
+       * Resolve a single reference ID to full entry data, memoized when a batch cache is
+       * supplied. Without a cache this is a straight pass-through to the uncached path, so
+       * `read()` behaves exactly as it always has.
+       *
+       * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo
+       * would hand one shared object to all 40 entries referencing the same block — a mutation
+       * in one caller's `extract` (truncating a body for a search index, deleting a field) would
+       * silently rewrite it for every sibling, and both `list: true` elements of `[id, id]` would
+       * be the same instance. The copy is what keeps the cache a pure performance optimization
+       * instead of a semantic change.
+       *
+       * Note the uncached path is NOT the clean baseline it looks like. For a json/yaml target it
+       * genuinely reparses fresh per occurrence, but for md/mdx gray-matter serves `data` from a
+       * process-global content-keyed cache, so `resolveSingleReferenceOnce`'s top-level spread
+       * severs exactly one level and NESTED frontmatter objects alias across occurrences, calls and
+       * requests. That is pre-existing `read()` behavior and out of scope here — deliberately, since
+       * touching it would change `read()` — but it means the cached path is the safer of the two,
+       * not a relaxation of a guarantee the uncached one provides. See
+       * `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+       *
+       * What the copy costs, measured rather than assumed (2000 occurrences of one target, local
+       * disk, so every read hits the page cache — the friendliest possible case for NOT caching):
+       * a snippet-sized target is ~63x cheaper to clone than to re-read-and-parse, while a 265KB
+       * JSON target is ~0.8x, i.e. cloning is marginally SLOWER than reparsing it. So the win is
+       * large in the case this exists for and roughly a wash at the pathological end, never a
+       * blow-up. Two things keep the bad end narrow: an md/mdx target resolves to its FRONTMATTER
+       * only *unless the field sets `includeBody`* (`read()` puts the body on `doc.body`, which
+       * `resolveSingleReferenceOnce` spreads in only for an embedding field), so by default body
+       * size is irrelevant no matter how long the document and only a genuinely huge JSON/YAML
+       * target reaches the wash. **`includeBody: true` is the case that CAN reach it on markdown**:
+       * the body then sits inside the memoized object and is cloned once per referencing entry, so
+       * a long document embedded by many pages pays that repeatedly — the reason `includeBody`
+       * exists as an opt-in per field rather than as resolution's default. And in the deployment this
+       * targets, content lives on EFS/NFS where the syscall the memo removes dominates parse and
+       * clone alike, which the local-disk numbers above understate badly. Correctness is the
+       * reason for the copy regardless; the numbers are here so nobody has to re-derive them
+       * before touching this.
+       */
+      resolveSingleReference(id, idIndex, includeBody, cache) {
+        if (!cache)
+          return this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+        const key = includeBody ? `${id}:body` : id;
+        let pending = cache.get(key);
+        if (!pending) {
+          pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+          cache.set(key, pending);
+        }
+        return pending.then((resolved) => resolved === null ? null : structuredClone(resolved));
+      }
+      /**
        * Returns null if the reference is invalid or missing.
        * Includes id, slug, and collection fields for debugging.
        *
@@ -6461,16 +7100,21 @@ var init_generate_ai_content = __esm({
        * idIndex() dedupes concurrent builds — so a sibling call that wins the
        * throttle and rebuilds heals every other miss in the same batch, not just
        * the first.
+       *
+       * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every
+       * distinct id still runs the full refresh-and-retry above. What a cache changes
+       * is only that repeats of the SAME id in one batch share that one attempt's
+       * outcome instead of each getting an independent throw of the dice.
        */
-      async resolveSingleReference(id, idIndex) {
-        const first = await this.resolveSingleReferenceOnce(id, idIndex);
+      async resolveSingleReferenceUncached(id, idIndex, includeBody) {
+        const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody);
         if (first !== STALE_LOOKUP)
           return first;
         await this.refreshIndexForSuspiciousLookup();
-        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex());
+        const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody);
         return second === STALE_LOOKUP ? null : second;
       }
-      async resolveSingleReferenceOnce(id, idIndex) {
+      async resolveSingleReferenceOnce(id, idIndex, includeBody) {
         try {
           const location = idIndex.findById(id);
           if (!location)
@@ -6481,12 +7125,13 @@ var init_generate_ai_content = __esm({
           const doc = await this.read(location.collection, location.slug, {
             resolveReferences: false
           });
-          return {
+          const bodyForEmbed = includeBody && "body" in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : void 0;
+          return buildResolvedReference(doc.data, {
             id,
             slug: location.slug,
             collection: location.collection,
-            ...doc.data
-          };
+            urlPath: computeEntryUrl(location.collection, location.slug, this.contentRootName)
+          }, bodyForEmbed);
         } catch (error) {
           if (isNodeError3(error) && error.code === "ENOENT")
             return STALE_LOOKUP;
@@ -6511,7 +7156,6 @@ var init_generate_ai_content = __esm({
       "reference",
       "image"
     ]);
-    init_normalize2();
     log22 = createDebugLogger2({ prefix: "EntryLinks" });
     BASE58_CHAR = "[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]";
     ENTRY_LINK_PATTERN = new RegExp(`entry:(${BASE58_CHAR}{12})(#[^\\s)>"']*)?`, "g");
@@ -6527,10 +7171,10 @@ var init_generate_ai_content = __esm({
       constructor(root) {
         this.regenInFlight = null;
         this.lastForcedRefreshMs = 0;
-        this.root = path12.resolve(root);
-        this.registryPath = path12.join(this.root, REGISTRY_FILE);
-        this.stalePath = path12.join(this.root, REGISTRY_STALE_FILE);
-        this.tempPath = path12.join(this.root, REGISTRY_TEMP_FILE);
+        this.root = path13.resolve(root);
+        this.registryPath = path13.join(this.root, REGISTRY_FILE);
+        this.stalePath = path13.join(this.root, REGISTRY_STALE_FILE);
+        this.tempPath = path13.join(this.root, REGISTRY_TEMP_FILE);
       }
       /**
        * Returns all branches. Uses the cached snapshot if its embedded generation
@@ -6539,7 +7183,7 @@ var init_generate_ai_content = __esm({
       async list() {
         let parsed;
         try {
-          const raw = await fs11.readFile(this.registryPath, "utf8");
+          const raw = await fs12.readFile(this.registryPath, "utf8");
           parsed = JSON.parse(raw);
         } catch (err) {
           if (isNotFoundError3(err)) {
@@ -6628,7 +7272,7 @@ var init_generate_ai_content = __esm({
       async performRegenerate() {
         const read = await readResourceGeneration(this.root, RESOURCE2);
         const branches = await this.scanBranchDirectories();
-        await fs11.unlink(this.stalePath).catch(() => {
+        await fs12.unlink(this.stalePath).catch(() => {
         });
         if (!read.ok) {
           return branches;
@@ -6639,12 +7283,12 @@ var init_generate_ai_content = __esm({
           generation: read.token
         };
         const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
-        await fs11.mkdir(this.root, { recursive: true });
-        await fs11.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+        await fs12.mkdir(this.root, { recursive: true });
+        await fs12.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
         try {
-          await fs11.rename(uniqueTempPath, this.registryPath);
+          await fs12.rename(uniqueTempPath, this.registryPath);
         } catch (err) {
-          await fs11.unlink(uniqueTempPath).catch(() => {
+          await fs12.unlink(uniqueTempPath).catch(() => {
           });
           throw err;
         }
@@ -6658,12 +7302,12 @@ var init_generate_ai_content = __esm({
       async scanBranchDirectories() {
         const branches = [];
         try {
-          const entries = await fs11.readdir(this.root, { withFileTypes: true });
+          const entries = await fs12.readdir(this.root, { withFileTypes: true });
           for (const entry of entries) {
             if (!entry.isDirectory() || entry.name.startsWith(".")) {
               continue;
             }
-            const branchRoot = path12.join(this.root, entry.name);
+            const branchRoot = path13.join(this.root, entry.name);
             let meta;
             try {
               meta = await BranchMetadataFileManager.loadOnly(branchRoot);
@@ -6714,8 +7358,8 @@ var init_generate_ai_content = __esm({
     };
     BranchMetadataFileManager = class _BranchMetadataFileManager {
       constructor(branchRoot, baseRoot, options) {
-        this.branchRoot = path14.resolve(branchRoot);
-        this.filePath = path14.join(this.branchRoot, BRANCH_META_DIR, BRANCH_META_FILE);
+        this.branchRoot = path15.resolve(branchRoot);
+        this.filePath = path15.join(this.branchRoot, BRANCH_META_DIR, BRANCH_META_FILE);
         this.baseRoot = baseRoot;
         this.settleMs = options?.settleMs;
       }
@@ -6724,10 +7368,10 @@ var init_generate_ai_content = __esm({
        * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
        */
       static async loadOnly(branchRoot) {
-        const resolvedRoot = path14.resolve(branchRoot);
-        const filePath = path14.join(resolvedRoot, BRANCH_META_DIR, BRANCH_META_FILE);
+        const resolvedRoot = path15.resolve(branchRoot);
+        const filePath = path15.join(resolvedRoot, BRANCH_META_DIR, BRANCH_META_FILE);
         try {
-          const raw = await fs13.readFile(filePath, "utf8");
+          const raw = await fs14.readFile(filePath, "utf8");
           return JSON.parse(raw);
         } catch (err) {
           if (isNotFoundError3(err)) {
@@ -6748,7 +7392,7 @@ var init_generate_ai_content = __esm({
       }
       async load() {
         try {
-          const raw = await fs13.readFile(this.filePath, "utf8");
+          const raw = await fs14.readFile(this.filePath, "utf8");
           const parsed = JSON.parse(raw);
           const version = parsed.version ?? 0;
           return { meta: parsed, version };
@@ -6810,7 +7454,7 @@ var init_generate_ai_content = __esm({
        */
       async save(incoming) {
         try {
-          await fs13.stat(this.branchRoot);
+          await fs14.stat(this.branchRoot);
         } catch (err) {
           if (isNotFoundError3(err)) {
             throw new BranchMetadataConflictError("Branch no longer exists");
@@ -6923,12 +7567,12 @@ var init_generate_ai_content = __esm({
     };
     GitManager = class _GitManager {
       constructor(options, gitOptions) {
-        this.repoPath = path15.resolve(options.repoPath);
+        this.repoPath = path16.resolve(options.repoPath);
         this.baseBranch = options.baseBranch ?? "main";
         this.remote = options.remote ?? "origin";
         this.skipIndexMarker = options.skipIndexMarker ?? false;
         this.git = simpleGit2({ baseDir: this.repoPath, ...gitOptions });
-        this.git.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path15.dirname(this.repoPath) }));
+        this.git.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path16.dirname(this.repoPath) }));
       }
       static async cloneRepo(remoteUrl, targetPath, baseBranch = "main") {
         log5.debug("git", "Cloning repository", {
@@ -6970,11 +7614,11 @@ var init_generate_ai_content = __esm({
               remotePath: options.remotePath,
               baseBranch: options.baseBranch
             });
-            const remoteParent = path15.dirname(options.remotePath);
+            const remoteParent = path16.dirname(options.remotePath);
             releaseLock = await acquireProvisioningLock(remoteParent, ".remote-init.lock");
             let remoteExists = false;
             try {
-              const stat = await fs14.stat(options.remotePath);
+              const stat = await fs15.stat(options.remotePath);
               remoteExists = stat.isDirectory();
             } catch (err) {
               if (!isNotFoundError3(err))
@@ -7226,7 +7870,7 @@ var init_generate_ai_content = __esm({
        */
       static async validateGitRepoExists(repoPath) {
         try {
-          const stat = await fs14.stat(path15.join(repoPath, ".git"));
+          const stat = await fs15.stat(path16.join(repoPath, ".git"));
           if (!stat.isDirectory()) {
             throw new Error(`Expected git repo at ${repoPath}`);
           }
@@ -7304,7 +7948,7 @@ var init_generate_ai_content = __esm({
         }
         if (config.autoDetectRemotePath) {
           try {
-            const stat = await fs14.stat(config.autoDetectRemotePath);
+            const stat = await fs15.stat(config.autoDetectRemotePath);
             if (stat.isDirectory()) {
               log5.debug("git", "Auto-detected local remote", {
                 path: config.autoDetectRemotePath
@@ -7317,8 +7961,8 @@ var init_generate_ai_content = __esm({
         if (config.shouldAutoInitLocal) {
           const gitRoot = await this.findGitRoot();
           const sourceRoot = options.sourceRoot;
-          const sourcePath = sourceRoot ? path15.resolve(gitRoot, sourceRoot) : gitRoot;
-          const localRemotePath = path15.join(sourcePath, config.defaultRemotePath);
+          const sourcePath = sourceRoot ? path16.resolve(gitRoot, sourceRoot) : gitRoot;
+          const localRemotePath = path16.join(sourcePath, config.defaultRemotePath);
           await this.ensureLocalSimulatedRemote({
             remotePath: localRemotePath,
             sourcePath: gitRoot,
@@ -7346,7 +7990,7 @@ var init_generate_ai_content = __esm({
       static async repoExistsAt(workspacePath) {
         try {
           const checkGit = simpleGit2({ baseDir: workspacePath });
-          checkGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path15.dirname(workspacePath) }));
+          checkGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path16.dirname(workspacePath) }));
           await checkGit.raw(["rev-parse", "--git-dir"]);
           return true;
         } catch {
@@ -7368,19 +8012,19 @@ var init_generate_ai_content = __esm({
         const baseBranch = await resolveBaseBranch({
           defaultBaseBranch: options.baseBranch,
           mode: options.mode,
-          detectFrom: options.sourceRoot ? path15.resolve(process.cwd(), options.sourceRoot) : process.cwd()
+          detectFrom: options.sourceRoot ? path16.resolve(process.cwd(), options.sourceRoot) : process.cwd()
         });
         const remoteName = options.remoteName ?? "origin";
         const repoExists = await _GitManager.repoExistsAt(options.workspacePath);
         if (!repoExists) {
-          const gitPath = path15.join(options.workspacePath, ".git");
+          const gitPath = path16.join(options.workspacePath, ".git");
           try {
-            const stat = await fs14.stat(gitPath);
+            const stat = await fs15.stat(gitPath);
             if (stat.isDirectory()) {
               log5.debug("git", "Removing corrupt .git directory", {
                 workspacePath: options.workspacePath
               });
-              await fs14.rm(gitPath, { recursive: true });
+              await fs15.rm(gitPath, { recursive: true });
             }
           } catch (cleanupErr) {
             if (!isNotFoundError3(cleanupErr))
@@ -7407,7 +8051,7 @@ var init_generate_ai_content = __esm({
           }
           justCloned = true;
           const freshGit = simpleGit2({ baseDir: options.workspacePath });
-          freshGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path15.dirname(options.workspacePath) }));
+          freshGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path16.dirname(options.workspacePath) }));
           await freshGit.addConfig("canopycms.managed", "true");
           await freshGit.addConfig("user.name", options.gitBotAuthorName);
           await freshGit.addConfig("user.email", options.gitBotAuthorEmail);
@@ -7758,9 +8402,9 @@ var init_generate_ai_content = __esm({
         } catch {
         }
         for (const [filePath, content] of Object.entries(initialFiles)) {
-          const absolutePath = path15.join(this.repoPath, filePath);
-          await fs14.mkdir(path15.dirname(absolutePath), { recursive: true });
-          await fs14.writeFile(absolutePath, content, "utf-8");
+          const absolutePath = path16.join(this.repoPath, filePath);
+          await fs15.mkdir(path16.dirname(absolutePath), { recursive: true });
+          await fs15.writeFile(absolutePath, content, "utf-8");
           await this.git.add(filePath);
         }
         await this.git.commit("Initialize settings branch", ["--allow-empty"]);
@@ -7787,7 +8431,7 @@ var init_generate_ai_content = __esm({
                 branchName: options.branchName,
                 mode: options.mode
               });
-              releaseLock = await acquireProvisioningLock(path16.dirname(options.branchRoot), `.${path16.basename(options.branchRoot)}.init.lock`);
+              releaseLock = await acquireProvisioningLock(path17.dirname(options.branchRoot), `.${path17.basename(options.branchRoot)}.init.lock`);
               await GitManager.initializeWorkspace({
                 workspacePath: options.branchRoot,
                 branchName: options.branchName,
@@ -7828,7 +8472,7 @@ var init_generate_ai_content = __esm({
         const baseBranch = await resolveBaseBranch({
           defaultBaseBranch: this.config.defaultBaseBranch,
           mode,
-          detectFrom: this.config.sourceRoot ? path16.resolve(process.cwd(), this.config.sourceRoot) : void 0
+          detectFrom: this.config.sourceRoot ? path17.resolve(process.cwd(), this.config.sourceRoot) : void 0
         });
         await this.ensureGitWorkspace({
           branchRoot,
@@ -7865,15 +8509,15 @@ var init_generate_ai_content = __esm({
     };
     readEntryData = async (filePath, format, bodyFieldName = "body") => {
       try {
-        const raw = await fs15.readFile(filePath, "utf8");
+        const raw = await fs16.readFile(filePath, "utf8");
         if (format === "json") {
           return asRecord(JSON.parse(raw));
         }
         if (format === "yaml") {
           return asRecord(yamlParse2(raw));
         }
-        const parsed = matter2(raw);
-        const data = parsed.data ?? {};
+        const parsed = matter3(raw);
+        const data = { ...parsed.data ?? {} };
         if (parsed.content) {
           data[bodyFieldName] = parsed.content;
         }
@@ -7885,30 +8529,19 @@ var init_generate_ai_content = __esm({
         return {};
       }
     };
-    parseTypedFilename = (filename, entryTypes) => {
-      if (filename.startsWith("."))
-        return null;
-      const lastDot = filename.lastIndexOf(".");
-      if (lastDot === -1)
-        return null;
-      const nameWithoutExt = filename.slice(0, lastDot);
-      const parts = nameWithoutExt.split(".");
-      if (parts.length < 3)
-        return null;
-      const potentialType = parts[0];
-      if (entryTypes && !entryTypes.some((e) => e.name === potentialType)) {
-        return null;
-      }
-      const id = parts[parts.length - 1];
-      if (!isValidId(id))
-        return null;
-      const slug = parts.slice(1, -1).join(".").toLowerCase();
+    createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+      store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
+      cache: createReferenceResolveCache()
+    });
+    resolveCollectionItemReferences = async (items, collection, resolver) => Promise.all(items.map(async (item) => {
+      const fields = collection.entries?.find((e) => e.name === item.entryType)?.schema;
+      if (!fields)
+        return item;
       return {
-        type: potentialType,
-        slug,
-        id
+        ...item,
+        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache)
       };
-    };
+    }));
     looksLikeMalformedEntry = (filename, entryTypes) => {
       if (filename.startsWith(".") || filename.startsWith("_"))
         return false;
@@ -7937,7 +8570,7 @@ var init_generate_ai_content = __esm({
       normalizePath(root, collectionRoot);
       let dirents;
       try {
-        dirents = await fs15.readdir(collectionRoot, { withFileTypes: true });
+        dirents = await fs16.readdir(collectionRoot, { withFileTypes: true });
       } catch (err) {
         if (isNotFoundError3(err))
           return [];
@@ -7945,7 +8578,7 @@ var init_generate_ai_content = __esm({
       }
       const files = dirents.filter((d) => d.isFile() && validExts.some((ext) => d.name.endsWith(ext)) && d.name !== ".collection.json").sort((a, b) => a.name.localeCompare(b.name));
       const entries = await Promise.all(files.map(async (file) => {
-        const absolutePath = path17.join(collectionRoot, file.name);
+        const absolutePath = path18.join(collectionRoot, file.name);
         const relativePath = normalizePath(root, absolutePath);
         const parsed = parseTypedFilename(file.name, entryTypes);
         if (!parsed) {
@@ -7960,7 +8593,7 @@ var init_generate_ai_content = __esm({
         const format = entryType?.format || "json";
         const bodyField = entryType?.schema ? findBodyFieldName(entryType.schema) : "body";
         const [stats, data] = await Promise.all([
-          fs15.stat(absolutePath),
+          fs16.stat(absolutePath),
           readEntryData(absolutePath, format, bodyField)
         ]);
         const item = {
@@ -7984,22 +8617,23 @@ var init_generate_ai_content = __esm({
     KNOWN_FIELD_TYPES = new Set(fieldTypes2);
     STRING_FIELD_TYPES = /* @__PURE__ */ new Set(["string", "markdown", "mdx", "code"]);
     selectOptionValues = (field) => (field.options ?? []).map((opt) => typeof opt === "string" ? opt : opt.value);
+    GENERATED_RECORD_FILENAME = ".canopy-generated.json";
     jiti = createJiti2(import.meta.url);
   }
 });
 
 // dist/utils/atomic-write.js
-import fs17 from "node:fs/promises";
-import path20 from "node:path";
+import fs18 from "node:fs/promises";
+import path21 from "node:path";
 async function atomicWriteFile3(filePath, content) {
-  const dir = path20.dirname(filePath);
-  await fs17.mkdir(dir, { recursive: true });
+  const dir = path21.dirname(filePath);
+  await fs18.mkdir(dir, { recursive: true });
   const tempPath = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  await fs17.writeFile(tempPath, content, typeof content === "string" ? "utf-8" : void 0);
+  await fs18.writeFile(tempPath, content, typeof content === "string" ? "utf-8" : void 0);
   try {
-    await fs17.rename(tempPath, filePath);
+    await fs18.rename(tempPath, filePath);
   } catch (err) {
-    await fs17.unlink(tempPath).catch(() => {
+    await fs18.unlink(tempPath).catch(() => {
     });
     throw err;
   }
@@ -8119,11 +8753,11 @@ var init_debug2 = __esm({
 });
 
 // dist/resource-generation.js
-import fs18 from "node:fs/promises";
-import path21 from "node:path";
+import fs19 from "node:fs/promises";
+import path23 from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
 function resourceGenerationPath2(root, resource) {
-  return path21.resolve(root, META_DIR3, `${resource}.generation`);
+  return path23.resolve(root, META_DIR3, `${resource}.generation`);
 }
 async function bumpResourceGeneration2(root, resource, options) {
   const token = randomUUID3();
@@ -8141,7 +8775,7 @@ async function bumpResourceGeneration2(root, resource, options) {
 }
 async function readResourceGeneration2(root, resource) {
   try {
-    const token = await fs18.readFile(resourceGenerationPath2(root, resource), "utf-8");
+    const token = await fs19.readFile(resourceGenerationPath2(root, resource), "utf-8");
     return { ok: true, token };
   } catch (err) {
     if (isNodeError(err) && err.code === "ENOENT")
@@ -8168,10 +8802,10 @@ var init_resource_generation = __esm({
 });
 
 // dist/content-index-registry.js
-import path23 from "node:path";
+import path24 from "node:path";
 function invalidateContentIndexesForRoot2(root) {
-  const rootKey = path23.resolve(root);
-  const prefix = rootKey + path23.sep;
+  const rootKey = path24.resolve(root);
+  const prefix = rootKey + path24.sep;
   for (const [storeRoot, refs] of registry2) {
     if (storeRoot !== rootKey && !storeRoot.startsWith(prefix))
       continue;
@@ -8229,7 +8863,7 @@ var init_normalize3 = __esm({
 function isValidContentId2(id) {
   return CONTENT_ID_PATTERN2.test(id);
 }
-function parseSlug(slug) {
+function parseSlug2(slug) {
   if (!slug) {
     return {
       ok: false,
@@ -8339,7 +8973,7 @@ var init_content_id_index = __esm({
 });
 
 // dist/schema/meta-loader.js
-import { promises as fs19 } from "fs";
+import { promises as fs20 } from "fs";
 import { join as join4 } from "pathe";
 import { z as z8 } from "zod";
 import chokidar2 from "chokidar";
@@ -8349,7 +8983,7 @@ function stripEmbeddedIdFromName2(name) {
 async function scanForCollectionMeta2(baseDir, relativePath = "") {
   const collections = [];
   try {
-    const entries = await fs19.readdir(baseDir, { withFileTypes: true });
+    const entries = await fs20.readdir(baseDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
@@ -8360,8 +8994,8 @@ async function scanForCollectionMeta2(baseDir, relativePath = "") {
       const absolutePath = join4(baseDir, folderName);
       const metaPath = join4(absolutePath, ".collection.json");
       try {
-        await fs19.access(metaPath);
-        const content = await fs19.readFile(metaPath, "utf-8");
+        await fs20.access(metaPath);
+        const content = await fs20.readFile(metaPath, "utf-8");
         const parsed = JSON.parse(content);
         const meta = collectionMetaSchema2.parse(parsed);
         collections.push({
@@ -8393,7 +9027,7 @@ async function loadCollectionMetaFiles2(contentRoot) {
   let root = null;
   const rootMetaPath = join4(contentRoot, ".collection.json");
   try {
-    await fs19.access(rootMetaPath);
+    await fs20.access(rootMetaPath);
   } catch (err) {
     if (err.code === "ENOENT") {
     } else {
@@ -8401,7 +9035,7 @@ async function loadCollectionMetaFiles2(contentRoot) {
     }
   }
   try {
-    const content = await fs19.readFile(rootMetaPath, "utf-8");
+    const content = await fs20.readFile(rootMetaPath, "utf-8");
     const parsed = JSON.parse(content);
     root = rootCollectionMetaSchema2.parse(parsed);
   } catch (err) {
@@ -8548,7 +9182,12 @@ var init_field3 = __esm({
       collections: z9.array(z9.string().min(1)).min(1).optional(),
       entryTypes: z9.array(z9.string().min(1)).min(1).optional(),
       displayField: z9.string().min(1).optional(),
-      options: z9.array(referenceOptionSchema3).optional()
+      options: z9.array(referenceOptionSchema3).optional(),
+      // Must be listed here, not just on ReferenceFieldConfig: zod strips unknown keys by
+      // default, so a consumer that adopts this schema's parse output would silently delete a
+      // runtime-consumed flag and the feature would no-op with no error. (`resolvedSchema` is
+      // absent on purpose — it is type-inference-only and stripping it changes no behavior.)
+      includeBody: z9.boolean().optional()
     });
     fieldHolder3 = [z9.never()];
     blockSchema3 = z9.object({
@@ -8658,7 +9297,7 @@ var init_media3 = __esm({
 
 // dist/config/schemas/config.js
 import { z as z12 } from "zod";
-var defaultBranchAccessSchema3, defaultPathAccessLevelSchema3, defaultPathAccessLevelsSchema3, defaultPathAccessSchema3, defaultBaseBranchSchema3, defaultRemoteNameSchema3, defaultRemoteUrlSchema3, gitBotAuthorNameSchema3, gitBotAuthorEmailSchema3, githubTokenEnvVarSchema3, operatingModeSchema3, deployedAsSchema3, contentRootSchema3, sourceRootSchema3, deploymentNameSchema3, devContentSyncSchema3, devConfigSchema3, editorConfigSchema3, CanopyConfigSchema3, DEFAULT_PROD_WORKSPACE3;
+var defaultBranchAccessSchema3, defaultPathAccessLevelSchema3, defaultPathAccessLevelsSchema3, defaultPathAccessSchema3, defaultBaseBranchSchema3, defaultRemoteNameSchema3, defaultRemoteUrlSchema3, gitBotAuthorNameSchema3, gitBotAuthorEmailSchema3, githubTokenEnvVarSchema3, operatingModeSchema3, deployedAsSchema3, contentRootSchema3, sourceRootSchema3, basePathSchema3, deploymentNameSchema3, devContentSyncSchema3, devConfigSchema3, editorConfigSchema3, CanopyConfigSchema3, DEFAULT_PROD_WORKSPACE3;
 var init_config4 = __esm({
   "dist/config/schemas/config.js"() {
     "use strict";
@@ -8682,6 +9321,9 @@ var init_config4 = __esm({
     deployedAsSchema3 = z12.enum(["static", "server"]).default("server");
     contentRootSchema3 = relativePathSchema3.default("content");
     sourceRootSchema3 = z12.string().min(1).optional();
+    basePathSchema3 = z12.string().transform((value) => value.trim()).refine((value) => value.length > 0, {
+      message: "basePath must not be empty or only whitespace"
+    }).optional();
     deploymentNameSchema3 = z12.string().default("prod");
     devContentSyncSchema3 = z12.enum(["off", "warn"]).default("warn");
     devConfigSchema3 = z12.object({
@@ -8744,6 +9386,7 @@ var init_config4 = __esm({
       deploymentName: deploymentNameSchema3.optional(),
       contentRoot: contentRootSchema3.default("content"),
       sourceRoot: sourceRootSchema3.optional(),
+      basePath: basePathSchema3,
       editor: editorConfigSchema3.optional(),
       authPlugin: z12.custom().optional(),
       entryLinkUrl: z12.custom().optional(),
@@ -8830,13 +9473,13 @@ var init_content_index_generation = __esm({
 });
 
 // dist/sync-core.js
-import fs20 from "node:fs/promises";
-import path24 from "node:path";
+import fs21 from "node:fs/promises";
+import path25 from "node:path";
 import { simpleGit as simpleGit4 } from "simple-git";
 function assertWithinDir(resolved, parent, label) {
-  const normalizedResolved = path24.resolve(resolved);
-  const normalizedParent = path24.resolve(parent);
-  if (!normalizedResolved.startsWith(normalizedParent + path24.sep) && normalizedResolved !== normalizedParent) {
+  const normalizedResolved = path25.resolve(resolved);
+  const normalizedParent = path25.resolve(parent);
+  if (!normalizedResolved.startsWith(normalizedParent + path25.sep) && normalizedResolved !== normalizedParent) {
     throw new Error(`${label} escapes the expected directory: ${resolved}`);
   }
 }
@@ -8844,19 +9487,19 @@ async function safeReplaceDir(oldDir, newDir) {
   const backupDir = `${oldDir}.sync-backup-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   const oldExists = await filePathExists(oldDir);
   if (oldExists) {
-    await fs20.rename(oldDir, backupDir);
+    await fs21.rename(oldDir, backupDir);
   }
   try {
-    await fs20.rename(newDir, oldDir);
+    await fs21.rename(newDir, oldDir);
   } catch (err) {
     if (oldExists) {
-      await fs20.rename(backupDir, oldDir).catch(() => {
+      await fs21.rename(backupDir, oldDir).catch(() => {
       });
     }
     throw err;
   }
   if (oldExists) {
-    await fs20.rm(backupDir, { recursive: true, force: true }).catch(() => {
+    await fs21.rm(backupDir, { recursive: true, force: true }).catch(() => {
     });
   }
 }
@@ -8864,7 +9507,7 @@ async function listFilesRecursive(dir, prefix = "") {
   const results = [];
   let entries;
   try {
-    entries = await fs20.readdir(dir, { withFileTypes: true });
+    entries = await fs21.readdir(dir, { withFileTypes: true });
   } catch {
     return results;
   }
@@ -8875,7 +9518,7 @@ async function listFilesRecursive(dir, prefix = "") {
       continue;
     const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
-      results.push(...await listFilesRecursive(path24.join(dir, entry.name), rel));
+      results.push(...await listFilesRecursive(path25.join(dir, entry.name), rel));
     } else {
       results.push(rel);
     }
@@ -8883,19 +9526,19 @@ async function listFilesRecursive(dir, prefix = "") {
   return results;
 }
 async function copyDir(src, dest) {
-  await fs20.mkdir(dest, { recursive: true });
-  const entries = await fs20.readdir(src, { withFileTypes: true });
+  await fs21.mkdir(dest, { recursive: true });
+  const entries = await fs21.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.name === ".git")
       continue;
     if (entry.isSymbolicLink())
       continue;
-    const srcPath = path24.join(src, entry.name);
-    const destPath = path24.join(dest, entry.name);
+    const srcPath = path25.join(src, entry.name);
+    const destPath = path25.join(dest, entry.name);
     if (entry.isDirectory()) {
       await copyDir(srcPath, destPath);
     } else {
-      await fs20.copyFile(srcPath, destPath);
+      await fs21.copyFile(srcPath, destPath);
     }
   }
 }
@@ -8904,14 +9547,14 @@ async function pushContentToWorkspace(options) {
   if (!await filePathExists(srcContentDir)) {
     return { fileCount: 0 };
   }
-  const wsContentDir = path24.join(branchPath, contentRoot);
+  const wsContentDir = path25.join(branchPath, contentRoot);
   assertWithinDir(wsContentDir, branchPath, "content-root");
   const tmpDir = `${wsContentDir}.sync-tmp-${Date.now()}`;
   try {
     await copyDir(srcContentDir, tmpDir);
     await safeReplaceDir(wsContentDir, tmpDir);
   } catch (err) {
-    await fs20.rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    await fs21.rm(tmpDir, { recursive: true, force: true }).catch(() => {
     });
     throw err;
   }
@@ -8955,19 +9598,21 @@ import lockfile3 from "proper-lockfile";
 var init_provisioning_lock = __esm({
   "dist/utils/provisioning-lock.js"() {
     "use strict";
+    init_error();
+    init_logger3();
   }
 });
 
 // dist/git-manager.js
-import fs21 from "node:fs/promises";
-import path25 from "node:path";
+import fs24 from "node:fs/promises";
+import path26 from "node:path";
 import { simpleGit as simpleGit6 } from "simple-git";
 async function ensureGitExcludePattern2(repoPath, pattern) {
-  const excludePath = path25.join(repoPath, ".git", "info", "exclude");
-  await fs21.mkdir(path25.dirname(excludePath), { recursive: true });
+  const excludePath = path26.join(repoPath, ".git", "info", "exclude");
+  await fs24.mkdir(path26.dirname(excludePath), { recursive: true });
   let content = "";
   try {
-    content = await fs21.readFile(excludePath, "utf-8");
+    content = await fs24.readFile(excludePath, "utf-8");
   } catch (err) {
     if (!isNotFoundError(err))
       throw err;
@@ -8979,7 +9624,7 @@ async function ensureGitExcludePattern2(repoPath, pattern) {
   }
   const needsLeadingNewline = content.length > 0 && !content.endsWith("\n");
   const newContent = content + (needsLeadingNewline ? "\n" : "") + pattern + "\n";
-  await fs21.writeFile(excludePath, newContent, "utf-8");
+  await fs24.writeFile(excludePath, newContent, "utf-8");
   log9.debug("git", "Added pattern to .git/info/exclude", { pattern });
 }
 var log9;
@@ -9136,7 +9781,7 @@ var init_config5 = __esm({
 });
 
 // dist/operating-mode/client-unsafe-strategy.js
-import path26 from "node:path";
+import path27 from "node:path";
 function operatingStrategy3(mode) {
   const cached = strategyCache3.get(mode);
   if (cached)
@@ -9171,32 +9816,32 @@ var init_client_unsafe_strategy2 = __esm({
       // - shouldCommit(), shouldPush()
       // Add client-unsafe methods (use Node.js APIs)
       getWorkspaceRoot(_sourceRoot) {
-        return path26.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE3);
+        return path27.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE3);
       }
       getContentRoot(contentRoot, sourceRoot) {
-        return path26.resolve(sourceRoot ?? process.cwd(), contentRoot);
+        return path27.resolve(sourceRoot ?? process.cwd(), contentRoot);
       }
       getContentBranchesRoot(sourceRoot) {
-        return path26.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+        return path27.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
       }
       getContentBranchRoot(branchName, sourceRoot) {
-        return path26.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+        return path27.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
       }
       getGitExcludePattern() {
         return ".canopy-meta/";
       }
       getPermissionsFilePath(root) {
-        return path26.join(root, this.getPermissionsFileName());
+        return path27.join(root, this.getPermissionsFileName());
       }
       getGroupsFilePath(root) {
-        return path26.join(root, this.getGroupsFileName());
+        return path27.join(root, this.getGroupsFileName());
       }
       getRemoteUrlConfig() {
         return {
           shouldAutoInitLocal: false,
           defaultRemotePath: "",
           envVarName: "CANOPYCMS_REMOTE_URL",
-          autoDetectRemotePath: path26.join(this.getWorkspaceRoot(), "remote.git")
+          autoDetectRemotePath: path27.join(this.getWorkspaceRoot(), "remote.git")
         };
       }
       requiresExistingRepo() {
@@ -9208,7 +9853,7 @@ var init_client_unsafe_strategy2 = __esm({
         return `canopycms-settings-${resolveDeploymentName3(config, "prod")}`;
       }
       getSettingsRoot(sourceRoot) {
-        return path26.join(this.getWorkspaceRoot(sourceRoot), "settings");
+        return path27.join(this.getWorkspaceRoot(sourceRoot), "settings");
       }
       usesSeparateSettingsBranch() {
         return true;
@@ -9225,25 +9870,25 @@ var init_client_unsafe_strategy2 = __esm({
     DevStrategy3 = class extends DevClientSafeStrategy3 {
       // Inherits client-safe methods from DevClientSafeStrategy
       getWorkspaceRoot(sourceRoot) {
-        return path26.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
+        return path27.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
       }
       getContentRoot(contentRoot, sourceRoot) {
-        return path26.resolve(sourceRoot ?? process.cwd(), contentRoot);
+        return path27.resolve(sourceRoot ?? process.cwd(), contentRoot);
       }
       getContentBranchesRoot(sourceRoot) {
-        return path26.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+        return path27.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
       }
       getContentBranchRoot(branchName, sourceRoot) {
-        return path26.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+        return path27.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
       }
       getGitExcludePattern() {
         return ".canopy-meta/";
       }
       getPermissionsFilePath(root) {
-        return path26.join(root, this.getPermissionsFileName());
+        return path27.join(root, this.getPermissionsFileName());
       }
       getGroupsFilePath(root) {
-        return path26.join(root, this.getGroupsFileName());
+        return path27.join(root, this.getGroupsFileName());
       }
       getRemoteUrlConfig() {
         return {
@@ -9261,7 +9906,7 @@ var init_client_unsafe_strategy2 = __esm({
         return `canopycms-settings-${resolveDeploymentName3(config, "local")}`;
       }
       getSettingsRoot(sourceRoot) {
-        return path26.join(this.getWorkspaceRoot(sourceRoot), "settings");
+        return path27.join(this.getWorkspaceRoot(sourceRoot), "settings");
       }
       usesSeparateSettingsBranch() {
         return true;
@@ -9293,8 +9938,8 @@ __export(sync_exports, {
   SyncError: () => SyncError,
   sync: () => sync
 });
-import fs24 from "node:fs/promises";
-import path27 from "node:path";
+import fs25 from "node:fs/promises";
+import path28 from "node:path";
 import { simpleGit as simpleGit7 } from "simple-git";
 import * as p2 from "@clack/prompts";
 async function detectCurrentBranch(projectDir) {
@@ -9307,7 +9952,7 @@ async function detectCurrentBranch(projectDir) {
 async function selectBranch(options, branchesDir) {
   let branches = [];
   if (await filePathExists(branchesDir)) {
-    const entries = await fs24.readdir(branchesDir, { withFileTypes: true });
+    const entries = await fs25.readdir(branchesDir, { withFileTypes: true });
     branches = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
   }
   let branchName = options.branch;
@@ -9335,11 +9980,11 @@ async function selectBranch(options, branchesDir) {
       branchName = result;
     }
   }
-  const branchPath = path27.join(branchesDir, branchName);
+  const branchPath = path28.join(branchesDir, branchName);
   assertWithinDir(branchPath, branchesDir, "--branch");
   if (!branches.includes(branchName)) {
     if (options.autoCreate) {
-      await fs24.mkdir(branchPath, { recursive: true });
+      await fs25.mkdir(branchPath, { recursive: true });
       const wsGit = simpleGit7({ baseDir: branchPath });
       await wsGit.init();
       await wsGit.checkoutLocalBranch(branchName);
@@ -9356,8 +10001,8 @@ async function selectBranch(options, branchesDir) {
 async function syncPush(options) {
   const { projectDir } = options;
   const contentRoot = options.contentRoot || "content";
-  const branchesDir = path27.join(projectDir, ".canopy-dev", "content-branches");
-  const srcContentDir = path27.join(projectDir, contentRoot);
+  const branchesDir = path28.join(projectDir, ".canopy-dev", "content-branches");
+  const srcContentDir = path28.join(projectDir, contentRoot);
   assertWithinDir(srcContentDir, projectDir, "--content-root");
   if (!await filePathExists(srcContentDir)) {
     throw new SyncError(`Content directory not found: ${contentRoot}/ (expected at ${srcContentDir})`);
@@ -9365,7 +10010,7 @@ async function syncPush(options) {
   const branchName = await selectBranch({ ...options, projectDir, autoCreate: true }, branchesDir);
   if (!branchName)
     return { fileCount: 0 };
-  const branchPath = path27.join(branchesDir, branchName);
+  const branchPath = path28.join(branchesDir, branchName);
   assertWithinDir(branchPath, branchesDir, "--branch");
   const wsGit = simpleGit7({ baseDir: branchPath });
   const status = await wsGit.status();
@@ -9423,19 +10068,19 @@ async function syncPush(options) {
 async function syncPull(options) {
   const { projectDir } = options;
   const contentRoot = options.contentRoot || "content";
-  const branchesDir = path27.join(projectDir, ".canopy-dev", "content-branches");
+  const branchesDir = path28.join(projectDir, ".canopy-dev", "content-branches");
   const branchName = await selectBranch({ ...options, projectDir }, branchesDir);
   if (!branchName)
     return { fileCount: 0 };
-  const branchPath = path27.join(branchesDir, branchName);
+  const branchPath = path28.join(branchesDir, branchName);
   assertWithinDir(branchPath, branchesDir, "--branch");
-  const branchContentDir = path27.join(branchPath, contentRoot);
+  const branchContentDir = path28.join(branchPath, contentRoot);
   assertWithinDir(branchContentDir, branchPath, "--content-root");
   if (!await filePathExists(branchContentDir)) {
     throw new SyncError(`Content directory not found in branch workspace: ${branchName}/${contentRoot}`);
   }
   p2.log.step(`Pulling content from branch: ${branchName}`);
-  const destContentDir = path27.join(projectDir, contentRoot);
+  const destContentDir = path28.join(projectDir, contentRoot);
   assertWithinDir(destContentDir, projectDir, "--content-root");
   const sourceGit = simpleGit7({ baseDir: projectDir });
   const status = await sourceGit.status();
@@ -9487,7 +10132,7 @@ async function syncPull(options) {
     await copyDir(branchContentDir, tmpDestDir);
     await safeReplaceDir(destContentDir, tmpDestDir);
   } catch (err) {
-    await fs24.rm(tmpDestDir, { recursive: true, force: true }).catch(() => {
+    await fs25.rm(tmpDestDir, { recursive: true, force: true }).catch(() => {
     });
     throw err;
   }
@@ -9511,8 +10156,8 @@ async function syncPull(options) {
 async function syncBoth(options) {
   const { projectDir } = options;
   const contentRoot = options.contentRoot || "content";
-  const branchesDir = path27.join(projectDir, ".canopy-dev", "content-branches");
-  const srcContentDir = path27.join(projectDir, contentRoot);
+  const branchesDir = path28.join(projectDir, ".canopy-dev", "content-branches");
+  const srcContentDir = path28.join(projectDir, contentRoot);
   assertWithinDir(srcContentDir, projectDir, "--content-root");
   if (!await filePathExists(srcContentDir)) {
     throw new SyncError(`Content directory not found: ${contentRoot}/ (expected at ${srcContentDir})`);
@@ -9520,7 +10165,7 @@ async function syncBoth(options) {
   const branchName = await selectBranch({ ...options, projectDir, autoCreate: true }, branchesDir);
   if (!branchName)
     return { pushed: 0, pulled: 0 };
-  const branchPath = path27.join(branchesDir, branchName);
+  const branchPath = path28.join(branchesDir, branchName);
   assertWithinDir(branchPath, branchesDir, "--branch");
   const wsGit = simpleGit7({ baseDir: branchPath });
   const status = await wsGit.status();
@@ -9555,14 +10200,14 @@ async function syncBoth(options) {
   try {
     const incomingBranch = `sync-incoming-${Date.now()}`;
     await wsGit.raw(["checkout", "-b", incomingBranch, baseRef]);
-    const wsContentDir = path27.join(branchPath, contentRoot);
+    const wsContentDir = path28.join(branchPath, contentRoot);
     assertWithinDir(wsContentDir, branchPath, "--content-root");
     const tmpDir = `${wsContentDir}.sync-tmp-${Date.now()}`;
     try {
       await copyDir(srcContentDir, tmpDir);
       await safeReplaceDir(wsContentDir, tmpDir);
     } catch (err) {
-      await fs24.rm(tmpDir, { recursive: true, force: true }).catch(() => {
+      await fs25.rm(tmpDir, { recursive: true, force: true }).catch(() => {
       });
       await wsGit.checkout(currentBranch);
       await wsGit.raw(["branch", "-D", incomingBranch]).catch(() => {
@@ -9619,11 +10264,11 @@ async function syncBoth(options) {
 }
 async function syncAbort(options) {
   const { projectDir } = options;
-  const branchesDir = path27.join(projectDir, ".canopy-dev", "content-branches");
+  const branchesDir = path28.join(projectDir, ".canopy-dev", "content-branches");
   const branchName = await selectBranch({ ...options, projectDir }, branchesDir);
   if (!branchName)
     return;
-  const branchPath = path27.join(branchesDir, branchName);
+  const branchPath = path28.join(branchesDir, branchName);
   assertWithinDir(branchPath, branchesDir, "--branch");
   const wsGit = simpleGit7({ baseDir: branchPath });
   const status = await wsGit.status();
@@ -9751,8 +10396,8 @@ var init_async_mutex = __esm({
 });
 
 // dist/utils/occ-json-write.js
-import fs25 from "node:fs/promises";
-import path28 from "node:path";
+import fs26 from "node:fs/promises";
+import path29 from "node:path";
 import { randomUUID as randomUUID4 } from "node:crypto";
 import lockfile4 from "proper-lockfile";
 async function writeOccJsonFile2(filePath, payload, options) {
@@ -9761,29 +10406,29 @@ async function writeOccJsonFile2(filePath, payload, options) {
   const writeId = randomUUID4();
   const data = { ...payload, version: newVersion, writeId };
   const content = JSON.stringify(data, null, 2) + (trailingNewline ? "\n" : "");
-  const dir = path28.dirname(filePath);
-  await fs25.mkdir(dir, { recursive: true });
+  const dir = path29.dirname(filePath);
+  await fs26.mkdir(dir, { recursive: true });
   const tempPath = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  await fs25.writeFile(tempPath, content, "utf-8");
+  await fs26.writeFile(tempPath, content, "utf-8");
   if (expectedVersion === null) {
     try {
-      await fs25.link(tempPath, filePath);
+      await fs26.link(tempPath, filePath);
     } catch (err) {
-      await fs25.unlink(tempPath).catch(() => {
+      await fs26.unlink(tempPath).catch(() => {
       });
       if (isFileExistsError(err)) {
         throw new OccWriteConflictError2();
       }
       throw err;
     }
-    await fs25.unlink(tempPath).catch(() => {
+    await fs26.unlink(tempPath).catch(() => {
     });
     return { version: newVersion, writeId };
   }
   try {
     let currentVersion = null;
     try {
-      const current = JSON.parse(await fs25.readFile(filePath, "utf-8"));
+      const current = JSON.parse(await fs26.readFile(filePath, "utf-8"));
       currentVersion = current.version ?? 0;
     } catch {
       currentVersion = null;
@@ -9791,16 +10436,16 @@ async function writeOccJsonFile2(filePath, payload, options) {
     if (currentVersion !== expectedVersion) {
       throw new OccWriteConflictError2();
     }
-    await fs25.rename(tempPath, filePath);
+    await fs26.rename(tempPath, filePath);
     if (settleMs > 0) {
       await new Promise((resolve2) => setTimeout(resolve2, settleMs));
     }
-    const afterWrite = JSON.parse(await fs25.readFile(filePath, "utf-8"));
+    const afterWrite = JSON.parse(await fs26.readFile(filePath, "utf-8"));
     if (afterWrite.writeId !== writeId) {
       throw new OccWriteConflictError2();
     }
   } catch (err) {
-    await fs25.unlink(tempPath).catch(() => {
+    await fs26.unlink(tempPath).catch(() => {
     });
     throw err;
   }
@@ -9826,8 +10471,8 @@ async function withOccRetry2(operation, options) {
   throw new Error("Unreachable");
 }
 async function withOccFileLock2(filePath, fn) {
-  const dir = path28.dirname(filePath);
-  await fs25.mkdir(dir, { recursive: true });
+  const dir = path29.dirname(filePath);
+  await fs26.mkdir(dir, { recursive: true });
   const MAX_ATTEMPTS = 14;
   let release = null;
   for (let attempt = 1; release === null; attempt++) {
@@ -9886,8 +10531,8 @@ var init_occ_json_write = __esm({
 });
 
 // dist/branch-registry.js
-import fs26 from "node:fs/promises";
-import path29 from "node:path";
+import fs27 from "node:fs/promises";
+import path30 from "node:path";
 var log12, REGISTRY_FILE2, REGISTRY_STALE_FILE2, REGISTRY_TEMP_FILE2, REGISTRY_VERSION2, RESOURCE4, GET_MISS_REFRESH_MIN_INTERVAL_MS2, BranchRegistry2;
 var init_branch_registry = __esm({
   "dist/branch-registry.js"() {
@@ -9908,10 +10553,10 @@ var init_branch_registry = __esm({
       constructor(root) {
         this.regenInFlight = null;
         this.lastForcedRefreshMs = 0;
-        this.root = path29.resolve(root);
-        this.registryPath = path29.join(this.root, REGISTRY_FILE2);
-        this.stalePath = path29.join(this.root, REGISTRY_STALE_FILE2);
-        this.tempPath = path29.join(this.root, REGISTRY_TEMP_FILE2);
+        this.root = path30.resolve(root);
+        this.registryPath = path30.join(this.root, REGISTRY_FILE2);
+        this.stalePath = path30.join(this.root, REGISTRY_STALE_FILE2);
+        this.tempPath = path30.join(this.root, REGISTRY_TEMP_FILE2);
       }
       /**
        * Returns all branches. Uses the cached snapshot if its embedded generation
@@ -9920,7 +10565,7 @@ var init_branch_registry = __esm({
       async list() {
         let parsed;
         try {
-          const raw = await fs26.readFile(this.registryPath, "utf8");
+          const raw = await fs27.readFile(this.registryPath, "utf8");
           parsed = JSON.parse(raw);
         } catch (err) {
           if (isNotFoundError(err)) {
@@ -10009,7 +10654,7 @@ var init_branch_registry = __esm({
       async performRegenerate() {
         const read = await readResourceGeneration2(this.root, RESOURCE4);
         const branches = await this.scanBranchDirectories();
-        await fs26.unlink(this.stalePath).catch(() => {
+        await fs27.unlink(this.stalePath).catch(() => {
         });
         if (!read.ok) {
           return branches;
@@ -10020,12 +10665,12 @@ var init_branch_registry = __esm({
           generation: read.token
         };
         const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
-        await fs26.mkdir(this.root, { recursive: true });
-        await fs26.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+        await fs27.mkdir(this.root, { recursive: true });
+        await fs27.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
         try {
-          await fs26.rename(uniqueTempPath, this.registryPath);
+          await fs27.rename(uniqueTempPath, this.registryPath);
         } catch (err) {
-          await fs26.unlink(uniqueTempPath).catch(() => {
+          await fs27.unlink(uniqueTempPath).catch(() => {
           });
           throw err;
         }
@@ -10039,12 +10684,12 @@ var init_branch_registry = __esm({
       async scanBranchDirectories() {
         const branches = [];
         try {
-          const entries = await fs26.readdir(this.root, { withFileTypes: true });
+          const entries = await fs27.readdir(this.root, { withFileTypes: true });
           for (const entry of entries) {
             if (!entry.isDirectory() || entry.name.startsWith(".")) {
               continue;
             }
-            const branchRoot = path29.join(this.root, entry.name);
+            const branchRoot = path30.join(this.root, entry.name);
             let meta;
             try {
               meta = await BranchMetadataFileManager2.loadOnly(branchRoot);
@@ -10073,8 +10718,8 @@ var init_branch_registry = __esm({
 });
 
 // dist/branch-metadata.js
-import fs27 from "node:fs/promises";
-import path30 from "node:path";
+import fs28 from "node:fs/promises";
+import path31 from "node:path";
 var BRANCH_META_DIR2, BRANCH_META_FILE2, CURRENT_SCHEMA_VERSION2, BranchMetadataConflictError2, BranchMetadataCorruptError2, BranchMetadataFileManager2;
 var init_branch_metadata = __esm({
   "dist/branch-metadata.js"() {
@@ -10103,8 +10748,8 @@ var init_branch_metadata = __esm({
     };
     BranchMetadataFileManager2 = class _BranchMetadataFileManager2 {
       constructor(branchRoot, baseRoot, options) {
-        this.branchRoot = path30.resolve(branchRoot);
-        this.filePath = path30.join(this.branchRoot, BRANCH_META_DIR2, BRANCH_META_FILE2);
+        this.branchRoot = path31.resolve(branchRoot);
+        this.filePath = path31.join(this.branchRoot, BRANCH_META_DIR2, BRANCH_META_FILE2);
         this.baseRoot = baseRoot;
         this.settleMs = options?.settleMs;
       }
@@ -10113,10 +10758,10 @@ var init_branch_metadata = __esm({
        * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
        */
       static async loadOnly(branchRoot) {
-        const resolvedRoot = path30.resolve(branchRoot);
-        const filePath = path30.join(resolvedRoot, BRANCH_META_DIR2, BRANCH_META_FILE2);
+        const resolvedRoot = path31.resolve(branchRoot);
+        const filePath = path31.join(resolvedRoot, BRANCH_META_DIR2, BRANCH_META_FILE2);
         try {
-          const raw = await fs27.readFile(filePath, "utf8");
+          const raw = await fs28.readFile(filePath, "utf8");
           return JSON.parse(raw);
         } catch (err) {
           if (isNotFoundError(err)) {
@@ -10137,7 +10782,7 @@ var init_branch_metadata = __esm({
       }
       async load() {
         try {
-          const raw = await fs27.readFile(this.filePath, "utf8");
+          const raw = await fs28.readFile(this.filePath, "utf8");
           const parsed = JSON.parse(raw);
           const version = parsed.version ?? 0;
           return { meta: parsed, version };
@@ -10199,7 +10844,7 @@ var init_branch_metadata = __esm({
        */
       async save(incoming) {
         try {
-          await fs27.stat(this.branchRoot);
+          await fs28.stat(this.branchRoot);
         } catch (err) {
           if (isNotFoundError(err)) {
             throw new BranchMetadataConflictError2("Branch no longer exists");
@@ -10274,8 +10919,8 @@ __export(migrate_exports, {
   migrate: () => migrate,
   slugifyName: () => slugifyName
 });
-import fs28 from "node:fs/promises";
-import path31 from "node:path";
+import fs29 from "node:fs/promises";
+import path33 from "node:path";
 import * as p3 from "@clack/prompts";
 function slugifyName(name) {
   const slug = name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
@@ -10283,7 +10928,7 @@ function slugifyName(name) {
 }
 function toValidSlug(name) {
   const slug = slugifyName(name);
-  const parsed = parseSlug(slug);
+  const parsed = parseSlug2(slug);
   if (!parsed.ok) {
     throw new MigrateError(`Cannot derive a valid slug from "${name}" (got "${slug}"): ${parsed.error}`);
   }
@@ -10300,7 +10945,7 @@ function stripDirIdSuffix(dirName) {
   return dirName;
 }
 async function planDirectory(dirPath, isRoot, ctx) {
-  const entries = await fs28.readdir(dirPath, { withFileTypes: true });
+  const entries = await fs29.readdir(dirPath, { withFileTypes: true });
   entries.sort((a, b) => a.name.localeCompare(b.name));
   const ops = [];
   let hasOwnFiles = false;
@@ -10309,7 +10954,7 @@ async function planDirectory(dirPath, isRoot, ctx) {
     if (entry.name.startsWith("."))
       continue;
     if (entry.isDirectory()) {
-      const subPath = path31.join(dirPath, entry.name);
+      const subPath = path33.join(dirPath, entry.name);
       const sub = await planDirectory(subPath, false, ctx);
       if (!sub.hasContent)
         continue;
@@ -10317,10 +10962,10 @@ async function planDirectory(dirPath, isRoot, ctx) {
       ops.push(...sub.ops);
       if (!extractIdFromFilename2(entry.name)) {
         const newName = `${toValidSlug(entry.name)}.${generateId2()}`;
-        ops.push({ kind: "rename", from: subPath, to: path31.join(dirPath, newName) });
+        ops.push({ kind: "rename", from: subPath, to: path33.join(dirPath, newName) });
       }
     } else if (entry.isFile()) {
-      const ext = path31.extname(entry.name).slice(1);
+      const ext = path33.extname(entry.name).slice(1);
       const matchesFormat = ext === ctx.format || ctx.format === "yaml" && ext === "yml";
       if (!matchesFormat)
         continue;
@@ -10331,17 +10976,17 @@ async function planDirectory(dirPath, isRoot, ctx) {
         const newName = `${ctx.entryType}.${toValidSlug(base)}.${generateId2()}.${ext}`;
         ops.push({
           kind: "rename",
-          from: path31.join(dirPath, entry.name),
-          to: path31.join(dirPath, newName)
+          from: path33.join(dirPath, entry.name),
+          to: path33.join(dirPath, newName)
         });
       }
     }
   }
   const needsMeta = isRoot ? hasOwnFiles : hasContent;
-  const metaPath = path31.join(dirPath, ".collection.json");
+  const metaPath = path33.join(dirPath, ".collection.json");
   if (needsMeta && !await filePathExists(metaPath)) {
     const entryTypeMeta = { name: ctx.entryType, format: ctx.format, schema: ctx.schema };
-    const meta = isRoot ? { entries: [entryTypeMeta] } : { name: toValidSlug(stripDirIdSuffix(path31.basename(dirPath))), entries: [entryTypeMeta] };
+    const meta = isRoot ? { entries: [entryTypeMeta] } : { name: toValidSlug(stripDirIdSuffix(path33.basename(dirPath))), entries: [entryTypeMeta] };
     ops.push({ kind: "write", filePath: metaPath, content: JSON.stringify(meta, null, 2) + "\n" });
   }
   return { ops, hasContent };
@@ -10350,7 +10995,7 @@ async function migrate(options) {
   const { projectDir } = options;
   const contentRoot = options.contentRoot || "content";
   p3.intro("CanopyCMS migrate");
-  const contentDir = path31.join(projectDir, contentRoot);
+  const contentDir = path33.join(projectDir, contentRoot);
   if (!await filePathExists(contentDir)) {
     throw new MigrateError(`Content directory not found: ${contentRoot}/ (expected at ${contentDir})`);
   }
@@ -10427,14 +11072,14 @@ async function migrate(options) {
   const applyOps = async () => {
     for (const op of ops) {
       if (op.kind === "rename") {
-        await fs28.rename(op.from, op.to);
+        await fs29.rename(op.from, op.to);
       } else {
-        await fs28.writeFile(op.filePath, op.content, "utf-8");
+        await fs29.writeFile(op.filePath, op.content, "utf-8");
       }
     }
   };
   if (isBranchClone) {
-    const lockPath = path31.join(projectDir, ".canopy-meta", "schema");
+    const lockPath = path33.join(projectDir, ".canopy-meta", "schema");
     try {
       await withLock2(lockPath, () => withOccFileLock2(lockPath, applyOps));
     } catch (err) {
@@ -10482,7 +11127,7 @@ var init_migrate = __esm({
         this.name = "MigrateError";
       }
     };
-    describeOp = (op, baseDir) => op.kind === "rename" ? `rename  ${path31.relative(baseDir, op.from)} \u2192 ${path31.basename(op.to)}` : `create  ${path31.relative(baseDir, op.filePath)}`;
+    describeOp = (op, baseDir) => op.kind === "rename" ? `rename  ${path33.relative(baseDir, op.from)} \u2192 ${path33.basename(op.to)}` : `create  ${path33.relative(baseDir, op.filePath)}`;
   }
 });