canopycms 0.0.63 → 0.0.64

package/dist/cli/generate-ai-content.js

@@ -8,12 +8,27 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// dist/utils/logger.js
+function canopyLogWarn(...args) {
+  active.warn(...args);
+}
+function canopyLogError(...args) {
+  active.error(...args);
+}
+var active;
+var init_logger = __esm({
+  "dist/utils/logger.js"() {
+    "use strict";
+    active = console;
+  }
+});
+
 // dist/paths/normalize.js
-function normalizeFilesystemPath(path20) {
-  return path20.split(/[\\/]+/).filter(Boolean).join("/");
+function normalizeFilesystemPath(path21) {
+  return path21.split(/[\\/]+/).filter(Boolean).join("/");
 }
-function hasTraversalSequence(path20) {
-  const normalized = normalizeFilesystemPath(path20);
+function hasTraversalSequence(path21) {
+  const normalized = normalizeFilesystemPath(path21);
   return normalized.includes("..");
 }
 function createLogicalPath(...segments) {
@@ -23,14 +38,14 @@ function createLogicalPath(...segments) {
   }
   return normalized;
 }
-function trimSlashes(path20) {
+function trimSlashes(path21) {
   let start = 0;
-  let end = path20.length;
-  while (start < end && path20[start] === "/")
+  let end = path21.length;
+  while (start < end && path21[start] === "/")
     start++;
-  while (end > start && path20[end - 1] === "/")
+  while (end > start && path21[end - 1] === "/")
     end--;
-  return path20.slice(start, end);
+  return path21.slice(start, end);
 }
 var init_normalize = __esm({
   "dist/paths/normalize.js"() {
@@ -38,21 +53,6 @@ var init_normalize = __esm({
   }
 });
 
-// dist/utils/logger.js
-function canopyLogWarn(...args) {
-  active.warn(...args);
-}
-function canopyLogError(...args) {
-  active.error(...args);
-}
-var active;
-var init_logger = __esm({
-  "dist/utils/logger.js"() {
-    "use strict";
-    active = console;
-  }
-});
-
 // dist/paths/types.js
 var ROOT_COLLECTION_ID;
 var init_types = __esm({
@@ -239,7 +239,12 @@ var init_field = __esm({
       collections: z2.array(z2.string().min(1)).min(1).optional(),
       entryTypes: z2.array(z2.string().min(1)).min(1).optional(),
       displayField: z2.string().min(1).optional(),
-      options: z2.array(referenceOptionSchema).optional()
+      options: z2.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: z2.boolean().optional()
     });
     fieldHolder = [z2.never()];
     blockSchema = z2.object({
@@ -349,7 +354,7 @@ var init_media = __esm({
 
 // dist/config/schemas/config.js
 import { z as z5 } from "zod";
-var defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE;
+var defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, basePathSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE;
 var init_config = __esm({
   "dist/config/schemas/config.js"() {
     "use strict";
@@ -373,6 +378,9 @@ var init_config = __esm({
     deployedAsSchema = z5.enum(["static", "server"]).default("server");
     contentRootSchema = relativePathSchema.default("content");
     sourceRootSchema = z5.string().min(1).optional();
+    basePathSchema = z5.string().transform((value) => value.trim()).refine((value) => value.length > 0, {
+      message: "basePath must not be empty or only whitespace"
+    }).optional();
     deploymentNameSchema = z5.string().default("prod");
     devContentSyncSchema = z5.enum(["off", "warn"]).default("warn");
     devConfigSchema = z5.object({
@@ -435,6 +443,7 @@ var init_config = __esm({
       deploymentName: deploymentNameSchema.optional(),
       contentRoot: contentRootSchema.default("content"),
       sourceRoot: sourceRootSchema.optional(),
+      basePath: basePathSchema,
       editor: editorConfigSchema.optional(),
       authPlugin: z5.custom().optional(),
       entryLinkUrl: z5.custom().optional(),
@@ -672,7 +681,7 @@ var init_config2 = __esm({
 });
 
 // dist/operating-mode/client-unsafe-strategy.js
-import path8 from "node:path";
+import path9 from "node:path";
 function operatingStrategy(mode) {
   const cached = strategyCache.get(mode);
   if (cached)
@@ -710,32 +719,32 @@ var init_client_unsafe_strategy = __esm({
       // - shouldCommit(), shouldPush()
       // Add client-unsafe methods (use Node.js APIs)
       getWorkspaceRoot(_sourceRoot) {
-        return path8.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE);
+        return path9.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE);
       }
       getContentRoot(contentRoot, sourceRoot) {
-        return path8.resolve(sourceRoot ?? process.cwd(), contentRoot);
+        return path9.resolve(sourceRoot ?? process.cwd(), contentRoot);
       }
       getContentBranchesRoot(sourceRoot) {
-        return path8.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+        return path9.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
       }
       getContentBranchRoot(branchName, sourceRoot) {
-        return path8.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+        return path9.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
       }
       getGitExcludePattern() {
         return ".canopy-meta/";
       }
       getPermissionsFilePath(root) {
-        return path8.join(root, this.getPermissionsFileName());
+        return path9.join(root, this.getPermissionsFileName());
       }
       getGroupsFilePath(root) {
-        return path8.join(root, this.getGroupsFileName());
+        return path9.join(root, this.getGroupsFileName());
       }
       getRemoteUrlConfig() {
         return {
           shouldAutoInitLocal: false,
           defaultRemotePath: "",
           envVarName: "CANOPYCMS_REMOTE_URL",
-          autoDetectRemotePath: path8.join(this.getWorkspaceRoot(), "remote.git")
+          autoDetectRemotePath: path9.join(this.getWorkspaceRoot(), "remote.git")
         };
       }
       requiresExistingRepo() {
@@ -747,7 +756,7 @@ var init_client_unsafe_strategy = __esm({
         return `canopycms-settings-${resolveDeploymentName(config, "prod")}`;
       }
       getSettingsRoot(sourceRoot) {
-        return path8.join(this.getWorkspaceRoot(sourceRoot), "settings");
+        return path9.join(this.getWorkspaceRoot(sourceRoot), "settings");
       }
       usesSeparateSettingsBranch() {
         return true;
@@ -764,25 +773,25 @@ var init_client_unsafe_strategy = __esm({
     DevStrategy = class extends DevClientSafeStrategy {
       // Inherits client-safe methods from DevClientSafeStrategy
       getWorkspaceRoot(sourceRoot) {
-        return path8.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
+        return path9.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
       }
       getContentRoot(contentRoot, sourceRoot) {
-        return path8.resolve(sourceRoot ?? process.cwd(), contentRoot);
+        return path9.resolve(sourceRoot ?? process.cwd(), contentRoot);
       }
       getContentBranchesRoot(sourceRoot) {
-        return path8.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
+        return path9.join(this.getWorkspaceRoot(sourceRoot), "content-branches");
       }
       getContentBranchRoot(branchName, sourceRoot) {
-        return path8.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
+        return path9.resolve(this.getContentBranchesRoot(sourceRoot), branchName);
       }
       getGitExcludePattern() {
         return ".canopy-meta/";
       }
       getPermissionsFilePath(root) {
-        return path8.join(root, this.getPermissionsFileName());
+        return path9.join(root, this.getPermissionsFileName());
       }
       getGroupsFilePath(root) {
-        return path8.join(root, this.getGroupsFileName());
+        return path9.join(root, this.getGroupsFileName());
       }
       getRemoteUrlConfig() {
         return {
@@ -800,7 +809,7 @@ var init_client_unsafe_strategy = __esm({
         return `canopycms-settings-${resolveDeploymentName(config, "local")}`;
       }
       getSettingsRoot(sourceRoot) {
-        return path8.join(this.getWorkspaceRoot(sourceRoot), "settings");
+        return path9.join(this.getWorkspaceRoot(sourceRoot), "settings");
       }
       usesSeparateSettingsBranch() {
         return true;
@@ -839,18 +848,38 @@ var init_operating_mode = __esm({
 });
 
 // dist/cli/generate-ai-content.js
-import path19 from "node:path";
+import path20 from "node:path";
 import { createJiti } from "jiti";
 
 // dist/build/generate-ai-content.js
-import fs16 from "node:fs/promises";
-import path18 from "node:path";
+import fs17 from "node:fs/promises";
+import path19 from "node:path";
+
+// dist/utils/error.js
+function getErrorMessage(err) {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return String(err);
+}
+function isNodeError(err) {
+  return err instanceof Error && "code" in err;
+}
+function isNotFoundError(err) {
+  return isNodeError(err) && err.code === "ENOENT";
+}
+function isFileExistsError(err) {
+  return isNodeError(err) && err.code === "EEXIST";
+}
 
 // dist/content-store.js
-import fs9 from "node:fs/promises";
-import path10 from "node:path";
-import matter from "gray-matter";
-import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import fs10 from "node:fs/promises";
+import path11 from "node:path";
+import matter2 from "gray-matter";
+import { parse as yamlParse } from "yaml";
 
 // dist/utils/atomic-write.js
 import fs from "node:fs/promises";
@@ -869,6 +898,207 @@ async function atomicWriteFile(filePath, content) {
   }
 }
 
+// dist/utils/content-serialize.js
+import matter from "gray-matter";
+import { isCollection, isMap, isNode, isScalar, isSeq, parseDocument, stringify as yamlStringify } from "yaml";
+
+// dist/validation/block-structural-keys.js
+var BLOCK_DISCRIMINATOR_KEYS = ["template", "_type"];
+var BLOCK_STRUCTURAL_KEYS = new Set(BLOCK_DISCRIMINATOR_KEYS);
+function isBlockStructuralKey(key) {
+  return BLOCK_STRUCTURAL_KEYS.has(key);
+}
+
+// dist/utils/content-serialize.js
+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);
+}
+var EVIDENCE_MAX_DEPTH = 6;
+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
+      }
+    }
+  });
+}
+
 // dist/utils/async-mutex.js
 var locks = /* @__PURE__ */ new Map();
 async function withLock(key, fn) {
@@ -890,46 +1120,66 @@ async function withLock(key, fn) {
 
 // dist/utils/content-write-lock.js
 import path3 from "node:path";
-
-// dist/utils/error.js
-function getErrorMessage(err) {
-  if (err instanceof Error) {
-    return err.message;
-  }
-  if (typeof err === "string") {
-    return err;
-  }
-  return String(err);
-}
-function isNodeError(err) {
-  return err instanceof Error && "code" in err;
-}
-function isNotFoundError(err) {
-  return isNodeError(err) && err.code === "ENOENT";
-}
-function isFileExistsError(err) {
-  return isNodeError(err) && err.code === "EEXIST";
-}
+init_logger();
 
 // dist/utils/provisioning-lock.js
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
 import lockfile from "proper-lockfile";
-async function acquireProvisioningLock(lockTargetDir2, lockName) {
+init_logger();
+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;
+        }
+        canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err));
+      } catch {
+        try {
+          process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw
+`);
+        } catch {
+        }
+      }
+    }
+  };
+}
+function releaseIgnoringAlreadyReleased(release, lockPath) {
+  return async () => {
+    try {
+      await release();
+    } catch (err) {
+      if (isNodeError(err) && err.code === "ERELEASED") {
+        canopyLogWarn(`[canopy] Lock at ${lockPath} was already released (compromised mid-hold, or released twice); nothing to release`);
+        return;
+      }
+      throw err;
+    }
+  };
+}
+async function acquireProvisioningLock(lockTargetDir2, lockName, onCompromised) {
   await fs2.mkdir(lockTargetDir2, { recursive: true });
-  return lockfile.lock(lockTargetDir2, {
-    lockfilePath: path2.join(lockTargetDir2, lockName),
-    retries: { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true },
-    stale: 3e4
-  });
+  const lockPath = path2.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 fs2.mkdir(lockTargetDir2, { recursive: true });
-  return lockfile.lock(lockTargetDir2, {
-    lockfilePath: path2.join(lockTargetDir2, lockName),
-    retries: 0,
-    stale: 3e4
-  });
+  const lockPath = path2.join(lockTargetDir2, lockName);
+  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+  return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 
 // dist/utils/content-write-lock.js
@@ -948,14 +1198,14 @@ function lockTargetDir(branchRoot) {
 var sleep = (ms) => new Promise((resolve2) => {
   setTimeout(resolve2, ms);
 });
-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 (!isNodeError(err) || err.code !== "ELOCKED")
         throw err;
@@ -968,12 +1218,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;
+    canopyLogWarn(`[canopy] Content-write lock compromised mid-hold for ${branchRoot}:`, getErrorMessage(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;
 }
 
 // dist/utils/flatten-group-fields.js
@@ -998,6 +1257,105 @@ function findBodyFieldName(fields) {
   return "body";
 }
 
+// dist/static/seo.js
+var DEFAULT_SEO_FIELD_NAMES = {
+  title: "metaTitle",
+  description: "metaDescription",
+  ogImage: "ogImage",
+  ogType: "ogType",
+  canonical: "canonical",
+  noindex: "noindex",
+  twitterCard: "twitterCard"
+};
+
+// dist/entry-schema.js
+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;
+}
+var 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
+  }
+];
+
+// dist/utils/entry-url.js
+init_normalize();
+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 path21 = segments.length > 0 ? `/${segments.join("/")}` : "/";
+  return path21.toLowerCase();
+}
+
+// dist/url-collision.js
+import fs4 from "node:fs/promises";
+import path5 from "node:path";
+
 // dist/content-id-index.js
 import fs3 from "node:fs/promises";
 import path4 from "node:path";
@@ -1013,6 +1371,37 @@ var PHYSICAL_SEGMENT_PATTERN = new RegExp(`\\.${BASE58_PATTERN}{12}(?:\\.[a-z]+)
 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 };
+}
 
 // dist/id.js
 function generateId() {
@@ -1357,13 +1746,13 @@ function extractIdFromFilename(filename) {
   return null;
 }
 async function resolveCollectionPath(root, logicalPath) {
-  const fs17 = await import("node:fs/promises");
-  const path20 = await import("node:path");
+  const fs18 = await import("node:fs/promises");
+  const path21 = await import("node:path");
   const segments = logicalPath.split("/").filter(Boolean);
   let currentPath = root;
   for (const segment of segments) {
     try {
-      const entries = await fs17.readdir(currentPath, { withFileTypes: true });
+      const entries = await fs18.readdir(currentPath, { withFileTypes: true });
       const matchingDir = entries.find((entry) => {
         if (!entry.isDirectory())
           return false;
@@ -1371,7 +1760,7 @@ async function resolveCollectionPath(root, logicalPath) {
         return logicalName === segment.toLowerCase();
       });
       if (matchingDir) {
-        currentPath = path20.join(currentPath, matchingDir.name);
+        currentPath = path21.join(currentPath, matchingDir.name);
       } else {
         return null;
       }
@@ -1421,8 +1810,99 @@ function extractSlugFromFilename(filename, entryTypeName) {
   return filename.toLowerCase();
 }
 
+// dist/utils/typed-filename.js
+var 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
+  };
+};
+
+// dist/url-collision.js
+var CONTENT_EXTENSIONS = [".md", ".mdx", ".json", ".yaml"];
+async function readDirSafe(dir) {
+  try {
+    return await fs4.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isNotFoundError(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 path5.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 path5.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 path5.join(dir, entry.name);
+  }
+  return null;
+}
+async function findUrlPathClaimant(opts) {
+  const { collectionDir, slug, contentRoot } = opts;
+  if (isIndexSlug(slug)) {
+    const resolvedRoot = path5.resolve(contentRoot);
+    if (path5.resolve(collectionDir) === resolvedRoot)
+      return null;
+    const parentDir = path5.dirname(collectionDir);
+    const ownName = extractSlugFromFilename(path5.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;
+}
+
 // dist/content-index-registry.js
-import path5 from "node:path";
+import path6 from "node:path";
 var registry = /* @__PURE__ */ new Map();
 var finalization = new FinalizationRegistry(({ rootKey, ref }) => {
   const refs = registry.get(rootKey);
@@ -1433,7 +1913,7 @@ var finalization = new FinalizationRegistry(({ rootKey, ref }) => {
     registry.delete(rootKey);
 });
 function registerContentIndexForInvalidation(root, target) {
-  const rootKey = path5.resolve(root);
+  const rootKey = path6.resolve(root);
   let refs = registry.get(rootKey);
   if (!refs) {
     refs = /* @__PURE__ */ new Set();
@@ -1444,8 +1924,8 @@ function registerContentIndexForInvalidation(root, target) {
   finalization.register(target, { rootKey, ref });
 }
 function invalidateContentIndexesForRoot(root) {
-  const rootKey = path5.resolve(root);
-  const prefix = rootKey + path5.sep;
+  const rootKey = path6.resolve(root);
+  const prefix = rootKey + path6.sep;
   for (const [storeRoot, refs] of registry) {
     if (storeRoot !== rootKey && !storeRoot.startsWith(prefix))
       continue;
@@ -1463,8 +1943,8 @@ function invalidateContentIndexesForRoot(root) {
 }
 
 // dist/resource-generation.js
-import fs4 from "node:fs/promises";
-import path6 from "node:path";
+import fs5 from "node:fs/promises";
+import path7 from "node:path";
 import { randomUUID } from "node:crypto";
 
 // dist/utils/debug.js
@@ -1573,7 +2053,7 @@ var testLogger = createDebugLogger({
 var log = createDebugLogger({ prefix: "ResourceGeneration" });
 var META_DIR2 = ".canopy-meta";
 function resourceGenerationPath(root, resource) {
-  return path6.resolve(root, META_DIR2, `${resource}.generation`);
+  return path7.resolve(root, META_DIR2, `${resource}.generation`);
 }
 async function bumpResourceGeneration(root, resource, options) {
   const token = randomUUID();
@@ -1591,7 +2071,7 @@ async function bumpResourceGeneration(root, resource, options) {
 }
 async function readResourceGeneration(root, resource) {
   try {
-    const token = await fs4.readFile(resourceGenerationPath(root, resource), "utf-8");
+    const token = await fs5.readFile(resourceGenerationPath(root, resource), "utf-8");
     return { ok: true, token };
   } catch (err) {
     if (isNodeError(err) && err.code === "ENOENT")
@@ -1607,11 +2087,11 @@ function isGenerationCurrent(snapshotToken, read) {
 }
 
 // dist/branch-schema-cache.js
-import fs6 from "node:fs/promises";
-import path7 from "node:path";
+import fs7 from "node:fs/promises";
+import path8 from "node:path";
 
 // dist/schema/meta-loader.js
-import { promises as fs5 } from "fs";
+import { promises as fs6 } from "fs";
 import { join } from "pathe";
 import { z } from "zod";
 import chokidar from "chokidar";
@@ -1648,7 +2128,7 @@ function stripEmbeddedIdFromName(name) {
 async function scanForCollectionMeta(baseDir, relativePath = "") {
   const collections = [];
   try {
-    const entries = await fs5.readdir(baseDir, { withFileTypes: true });
+    const entries = await fs6.readdir(baseDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
@@ -1659,8 +2139,8 @@ async function scanForCollectionMeta(baseDir, relativePath = "") {
       const absolutePath = join(baseDir, folderName);
       const metaPath = join(absolutePath, ".collection.json");
       try {
-        await fs5.access(metaPath);
-        const content = await fs5.readFile(metaPath, "utf-8");
+        await fs6.access(metaPath);
+        const content = await fs6.readFile(metaPath, "utf-8");
         const parsed = JSON.parse(content);
         const meta = collectionMetaSchema.parse(parsed);
         collections.push({
@@ -1692,7 +2172,7 @@ async function loadCollectionMetaFiles(contentRoot) {
   let root = null;
   const rootMetaPath = join(contentRoot, ".collection.json");
   try {
-    await fs5.access(rootMetaPath);
+    await fs6.access(rootMetaPath);
   } catch (err) {
     if (err.code === "ENOENT") {
     } else {
@@ -1700,7 +2180,7 @@ async function loadCollectionMetaFiles(contentRoot) {
     }
   }
   try {
-    const content = await fs5.readFile(rootMetaPath, "utf-8");
+    const content = await fs6.readFile(rootMetaPath, "utf-8");
     const parsed = JSON.parse(content);
     root = rootCollectionMetaSchema.parse(parsed);
   } catch (err) {
@@ -1887,16 +2367,16 @@ var SCHEMA_GENERATION_RESOURCE = "schema";
 async function isStaleByMtime(dir, cachedAt) {
   let entries;
   try {
-    entries = await fs6.readdir(dir, { recursive: true, encoding: "utf-8" });
+    entries = await fs7.readdir(dir, { recursive: true, encoding: "utf-8" });
   } catch {
     return true;
   }
   for (const entry of entries) {
     if (!entry.endsWith(".collection.json"))
       continue;
-    const full = path7.join(dir, entry);
+    const full = path8.join(dir, entry);
     try {
-      const stat = await fs6.stat(full);
+      const stat = await fs7.stat(full);
       if (stat.mtimeMs > cachedAt.getTime())
         return true;
     } catch {
@@ -1920,7 +2400,7 @@ var BranchSchemaCache = class {
    * the project root, regardless of which entrypoint produced the cwd branchRoot.
    */
   skipDiskCache(branchRoot) {
-    return isBuildMode() || path7.resolve(branchRoot) === path7.resolve(process.cwd());
+    return isBuildMode() || path8.resolve(branchRoot) === path8.resolve(process.cwd());
   }
   /**
    * Get schema for a branch (loads from cache or resolves fresh).
@@ -1946,14 +2426,14 @@ var BranchSchemaCache = class {
    * Load schema from cache or resolve fresh if cache is missing or stale.
    */
   async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
-    const contentRoot = path7.join(branchRoot, contentRootName);
+    const contentRoot = path8.join(branchRoot, contentRootName);
     const skipDiskCache = this.skipDiskCache(branchRoot);
     if (!skipDiskCache) {
-      const cacheDir = path7.join(branchRoot, ".canopy-meta");
-      const cachePath = path7.join(cacheDir, "schema-cache.json");
+      const cacheDir = path8.join(branchRoot, ".canopy-meta");
+      const cachePath = path8.join(cacheDir, "schema-cache.json");
       let cacheData = null;
       try {
-        const cacheContent = await fs6.readFile(cachePath, "utf-8");
+        const cacheContent = await fs7.readFile(cachePath, "utf-8");
         cacheData = JSON.parse(cacheContent);
       } catch {
         cacheData = null;
@@ -1990,7 +2470,7 @@ var BranchSchemaCache = class {
    */
   async resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, options) {
     const { skipDiskCache } = options;
-    const contentRoot = path7.join(branchRoot, contentRootName);
+    const contentRoot = path8.join(branchRoot, contentRootName);
     const read = skipDiskCache ? null : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
     const result = await this.resolveFresh(contentRoot, entrySchemaRegistry);
     if (!isValidSchema(result.schema)) {
@@ -2003,9 +2483,9 @@ var BranchSchemaCache = class {
     }
     const flatSchema = flattenSchema(result.schema, contentRootName);
     if (!skipDiskCache) {
-      const cacheDir = path7.join(branchRoot, ".canopy-meta");
-      const cachePath = path7.join(cacheDir, "schema-cache.json");
-      await fs6.unlink(path7.join(cacheDir, "schema-cache.stale")).catch(() => {
+      const cacheDir = path8.join(branchRoot, ".canopy-meta");
+      const cachePath = path8.join(cacheDir, "schema-cache.json");
+      await fs7.unlink(path8.join(cacheDir, "schema-cache.stale")).catch(() => {
       });
       if (read && read.ok) {
         const newCache = {
@@ -2015,13 +2495,13 @@ var BranchSchemaCache = class {
           cachedAt: (/* @__PURE__ */ new Date()).toISOString(),
           generation: read.token
         };
-        await fs6.mkdir(cacheDir, { recursive: true });
-        const tmpPath = path7.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-        await fs6.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
+        await fs7.mkdir(cacheDir, { recursive: true });
+        const tmpPath = path8.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
+        await fs7.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
         try {
-          await fs6.rename(tmpPath, cachePath);
+          await fs7.rename(tmpPath, cachePath);
         } catch (err) {
-          await fs6.unlink(tmpPath).catch(() => {
+          await fs7.unlink(tmpPath).catch(() => {
           });
           throw err;
         }
@@ -2093,10 +2573,10 @@ async function invalidateBranchContentCaches(root) {
 }
 
 // dist/utils/fs.js
-import fs7 from "node:fs/promises";
+import fs8 from "node:fs/promises";
 async function filePathExists(filePath) {
   try {
-    await fs7.stat(filePath);
+    await fs8.stat(filePath);
     return true;
   } catch (err) {
     if (isNotFoundError(err))
@@ -2104,6 +2584,15 @@ async function filePathExists(filePath) {
     throw err;
   }
 }
+async function readFileIfExists(filePath) {
+  try {
+    return await fs8.readFile(filePath, "utf8");
+  } catch (err) {
+    if (isNotFoundError(err))
+      return void 0;
+    throw err;
+  }
+}
 
 // dist/utils/format.js
 var getFormatExtension = (format) => {
@@ -2142,8 +2631,8 @@ function validateAndNormalizePath(root, target) {
 
 // dist/paths/branch.js
 init_operating_mode();
-import fs8 from "node:fs/promises";
-import path9 from "node:path";
+import fs9 from "node:fs/promises";
+import path10 from "node:path";
 
 // dist/paths/branch-name.js
 function sanitizeBranchName(branchName) {
@@ -2166,11 +2655,11 @@ function resolveBranchPath(options) {
   const safeBranch = sanitizeBranchName(options.branchName);
   const strategy = operatingStrategy(options.mode);
   const baseRoot = resolveContentBranchesRoot(options.mode, options.basePathOverride);
-  const normalizedBase = path9.resolve(baseRoot);
-  const baseWithSep = normalizedBase.endsWith(path9.sep) ? normalizedBase : `${normalizedBase}${path9.sep}`;
+  const normalizedBase = path10.resolve(baseRoot);
+  const baseWithSep = normalizedBase.endsWith(path10.sep) ? normalizedBase : `${normalizedBase}${path10.sep}`;
   const branchRoot = strategy.getContentBranchRoot(safeBranch, options.basePathOverride);
   const withinBase = (target) => {
-    const resolved = path9.resolve(target);
+    const resolved = path10.resolve(target);
     return resolved === normalizedBase || resolved.startsWith(baseWithSep);
   };
   if (!withinBase(branchRoot)) {
@@ -2180,7 +2669,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;
 }
 
@@ -2226,6 +2715,13 @@ var DuplicateContentIdError = class extends ContentConflictError {
     this.paths = sorted;
   }
 };
+var UrlPathConflictError = class extends ContentConflictError {
+  constructor(message, conflictingPath) {
+    super(message);
+    this.name = "UrlPathConflictError";
+    this.conflictingPath = conflictingPath;
+  }
+};
 function getDefaultEntryType(entries) {
   if (!entries || entries.length === 0)
     return void 0;
@@ -2242,6 +2738,7 @@ function validateSlug(slug) {
 var DEFAULT_INDEX_FRESHNESS_INTERVAL_MS = 1e3;
 var FORCED_REFRESH_MIN_INTERVAL_MS = 5e3;
 var STALE_LOOKUP = Symbol("stale-index-lookup");
+var createReferenceResolveCache = () => /* @__PURE__ */ new Map();
 var ContentStore = class {
   constructor(root, flatSchema, options = {}) {
     this.indexGeneration = 0;
@@ -2250,7 +2747,7 @@ var ContentStore = class {
     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;
@@ -2398,7 +2895,7 @@ var ContentStore = class {
   async findEntryPathsById(dir, id) {
     let entries;
     try {
-      entries = await fs9.readdir(dir, { withFileTypes: true });
+      entries = await fs10.readdir(dir, { withFileTypes: true });
     } catch (err) {
       if (isNodeError(err) && err.code === "ENOENT")
         return [];
@@ -2409,7 +2906,7 @@ var ContentStore = class {
       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();
@@ -2421,11 +2918,11 @@ var ContentStore = class {
   getSchemaItems() {
     return this.schemaIndex.values();
   }
-  assertSchemaItem(path20) {
-    const normalized = normalizeFilesystemPath(path20);
+  assertSchemaItem(path21) {
+    const normalized = normalizeFilesystemPath(path21);
     const item = this.schemaIndex.get(normalized);
     if (!item) {
-      throw new ContentStoreError(`Unknown schema item: ${path20}`, "NO_SCHEMA_ITEM");
+      throw new ContentStoreError(`Unknown schema item: ${path21}`, "NO_SCHEMA_ITEM");
     }
     return item;
   }
@@ -2492,6 +2989,26 @@ var ContentStore = class {
       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}
@@ -2508,7 +3025,7 @@ var ContentStore = class {
    * @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);
@@ -2541,7 +3058,7 @@ var ContentStore = class {
       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");
@@ -2551,7 +3068,7 @@ var ContentStore = class {
       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;
@@ -2577,14 +3094,14 @@ var ContentStore = class {
         }
         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
@@ -2620,8 +3137,8 @@ var ContentStore = class {
   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;
@@ -2660,7 +3177,7 @@ var ContentStore = class {
         absolutePath
       };
     } else {
-      const parsed = matter(raw);
+      const parsed = matter2(raw);
       doc = {
         collection: schemaItem.logicalPath,
         collectionName: schemaItem.name,
@@ -2723,7 +3240,7 @@ var ContentStore = class {
             const indexedPath = guardIndex.findById(id)?.relativePath ?? null;
             if (indexedPath && indexedPath !== relativePath) {
               const quarantined = guardIndex.getDuplicateFor(id);
-              const bothOnDisk = await filePathExists(absolutePath) && await filePathExists(path10.join(this.root, indexedPath));
+              const bothOnDisk = await filePathExists(absolutePath) && await filePathExists(path11.join(this.root, indexedPath));
               if (quarantined || bothOnDisk) {
                 throw new DuplicateContentIdError(id, [
                   indexedPath,
@@ -2734,10 +3251,18 @@ var ContentStore = class {
               }
             }
           }
-          await fs9.mkdir(path10.dirname(absolutePath), { recursive: true });
+          if (!await filePathExists(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");
               }
@@ -2754,7 +3279,7 @@ var ContentStore = class {
             }
           }
           if (existingId && !await filePathExists(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);
             }
@@ -2764,14 +3289,15 @@ var ContentStore = class {
               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 atomicWriteFile(absolutePath, content);
           const liveIndex = this._idIndex;
@@ -2780,7 +3306,7 @@ var ContentStore = class {
             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 {
@@ -2793,13 +3319,13 @@ var ContentStore = class {
             }
           }
           if (staleOldAbsPath) {
-            await fs9.unlink(staleOldAbsPath).catch((err) => {
+            await fs10.unlink(staleOldAbsPath).catch((err) => {
               if (!isNodeError(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,
@@ -2877,7 +3403,7 @@ var ContentStore = class {
     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 (isNodeError(err) && err.code === "ENOENT")
@@ -2916,7 +3442,7 @@ var ContentStore = class {
     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;
   }
   /**
@@ -2940,7 +3466,7 @@ var ContentStore = class {
     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);
@@ -2956,7 +3482,7 @@ var ContentStore = class {
             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) {
@@ -2992,6 +3518,10 @@ var ContentStore = class {
     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");
@@ -3018,7 +3548,7 @@ var ContentStore = class {
           }
           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");
@@ -3027,10 +3557,10 @@ var ContentStore = class {
           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;
@@ -3043,16 +3573,17 @@ var ContentStore = class {
             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 (isNodeError(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) {
@@ -3124,34 +3655,57 @@ var ContentStore = class {
     }
     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;
@@ -3164,7 +3718,7 @@ var ContentStore = class {
             return block;
           return {
             ...b,
-            value: await this.resolveReferencesInData(b.value, template.fields)
+            value: await this.resolveReferencesInData(b.value, template.fields, cache)
           };
         }));
       }
@@ -3172,7 +3726,56 @@ var ContentStore = class {
     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.
    *
@@ -3186,16 +3789,21 @@ var ContentStore = class {
    * 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)
@@ -3206,12 +3814,13 @@ var ContentStore = class {
       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 (isNodeError(error) && error.code === "ENOENT")
         return STALE_LOOKUP;
@@ -3222,8 +3831,8 @@ var ContentStore = class {
 };
 
 // dist/ai/generate.js
-import path11 from "node:path";
-import fs10 from "node:fs/promises";
+import path12 from "node:path";
+import fs11 from "node:fs/promises";
 import { minimatch } from "minimatch";
 
 // dist/ai/strip-mdx.js
@@ -3505,7 +4114,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);
   }
@@ -3770,30 +4379,14 @@ 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;
 }
 
-// dist/utils/entry-url.js
-init_normalize();
-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 path20 = segments.length > 0 ? `/${segments.join("/")}` : "/";
-  return path20.toLowerCase();
-}
-
 // dist/entry-link-resolver.js
 var log2 = createDebugLogger({ prefix: "EntryLinks" });
 var BASE58_CHAR = "[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]";
@@ -3966,7 +4559,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))
@@ -3984,7 +4577,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);
@@ -4035,7 +4628,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))
@@ -4053,7 +4646,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);
@@ -4101,19 +4694,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 (isNodeError(err) && (err.code === "ENOENT" || err.code === "ENOTDIR"))
         return null;
@@ -4127,7 +4720,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);
@@ -4164,15 +4757,15 @@ function matchesBundleFilter(entry, filter, contentRoot) {
 }
 
 // dist/branch-workspace.js
-import path16 from "node:path";
+import path17 from "node:path";
 
 // dist/branch-metadata.js
-import fs13 from "node:fs/promises";
-import path14 from "node:path";
+import fs14 from "node:fs/promises";
+import path15 from "node:path";
 
 // dist/branch-registry.js
-import fs11 from "node:fs/promises";
-import path12 from "node:path";
+import fs12 from "node:fs/promises";
+import path13 from "node:path";
 init_logger();
 var log3 = createDebugLogger({ prefix: "BranchRegistry" });
 var REGISTRY_FILE = "branches.json";
@@ -4185,10 +4778,10 @@ var BranchRegistry = class {
   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
@@ -4197,7 +4790,7 @@ var BranchRegistry = class {
   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 (isNotFoundError(err)) {
@@ -4286,7 +4879,7 @@ var BranchRegistry = class {
   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;
@@ -4297,12 +4890,12 @@ var BranchRegistry = class {
       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;
     }
@@ -4316,12 +4909,12 @@ var BranchRegistry = class {
   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);
@@ -4348,8 +4941,8 @@ var BranchRegistry = class {
 };
 
 // dist/utils/occ-json-write.js
-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";
 var log4 = createDebugLogger({ prefix: "OccJsonWrite" });
@@ -4365,29 +4958,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 (isFileExistsError(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;
@@ -4395,16 +4988,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;
   }
@@ -4430,8 +5023,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++) {
@@ -4494,8 +5087,8 @@ var BranchMetadataCorruptError = class extends Error {
 };
 var 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;
   }
@@ -4504,10 +5097,10 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
    * 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 (isNotFoundError(err)) {
@@ -4528,7 +5121,7 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
   }
   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 };
@@ -4590,7 +5183,7 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
    */
   async save(incoming) {
     try {
-      await fs13.stat(this.branchRoot);
+      await fs14.stat(this.branchRoot);
     } catch (err) {
       if (isNotFoundError(err)) {
         throw new BranchMetadataConflictError("Branch no longer exists");
@@ -4678,8 +5271,8 @@ var loadBranchContext = async (options) => {
 init_operating_mode();
 
 // dist/git-manager.js
-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";
 
 // dist/utils/git.js
@@ -4739,11 +5332,11 @@ function gitChildEnv(overrides) {
 var remoteInitLocks = /* @__PURE__ */ new Map();
 var GITHUB_TRACKING_REF_PREFIX = "refs/remotes/github/";
 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 (!isNotFoundError(err))
       throw err;
@@ -4755,7 +5348,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 });
 }
 var GitConflictError = class extends Error {
@@ -4776,12 +5369,12 @@ var GitRemoteRefMissingError = class extends Error {
 };
 var 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", {
@@ -4823,11 +5416,11 @@ var GitManager = class _GitManager {
           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 (!isNotFoundError(err))
@@ -5079,7 +5672,7 @@ var GitManager = class _GitManager {
    */
   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}`);
       }
@@ -5157,7 +5750,7 @@ var GitManager = class _GitManager {
     }
     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
@@ -5170,8 +5763,8 @@ var GitManager = class _GitManager {
     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,
@@ -5199,7 +5792,7 @@ var GitManager = class _GitManager {
   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 {
@@ -5221,19 +5814,19 @@ var GitManager = class _GitManager {
     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 (!isNotFoundError(cleanupErr))
@@ -5260,7 +5853,7 @@ var GitManager = class _GitManager {
       }
       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);
@@ -5611,9 +6204,9 @@ var GitManager = class _GitManager {
     } 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"]);
@@ -5642,7 +6235,7 @@ var BranchWorkspaceManager = class {
             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,
@@ -5683,7 +6276,7 @@ var BranchWorkspaceManager = class {
     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,
@@ -5767,9 +6360,9 @@ async function resolveBranchRoot(config) {
 }
 
 // dist/content-listing.js
-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";
 var log7 = createDebugLogger({ prefix: "ContentListing" });
 var normalizePath = (root, target) => {
@@ -5781,15 +6374,15 @@ var normalizePath = (root, target) => {
 };
 var 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;
     }
@@ -5801,30 +6394,19 @@ var readEntryData = async (filePath, format, bodyFieldName = "body") => {
     return {};
   }
 };
-var 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();
+var createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+  store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
+  cache: createReferenceResolveCache()
+});
+var 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)
   };
-};
+}));
 async function listEntries(branchRoot, flatSchema, contentRootName, options, visibility) {
   const rootPath = options?.rootPath ?? contentRootName;
   const extract = options?.extract;
@@ -5833,10 +6415,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}`);
@@ -5850,8 +6434,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,
@@ -5913,7 +6496,7 @@ var listCollectionEntries = async (root, collection, onSkip) => {
   normalizePath(root, collectionRoot);
   let dirents;
   try {
-    dirents = await fs15.readdir(collectionRoot, { withFileTypes: true });
+    dirents = await fs16.readdir(collectionRoot, { withFileTypes: true });
   } catch (err) {
     if (isNotFoundError(err))
       return [];
@@ -5921,7 +6504,7 @@ var listCollectionEntries = async (root, collection, onSkip) => {
   }
   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) {
@@ -5936,7 +6519,7 @@ var listCollectionEntries = async (root, collection, onSkip) => {
     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 = {
@@ -5974,7 +6557,7 @@ function isValidCropRect(x, y, w, h) {
 }
 
 // dist/validation/field-traversal.js
-function isPlainRecord(value) {
+function isPlainRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveBlockItem(blockField, item) {
@@ -5984,21 +6567,21 @@ 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 };
 }
 
 // dist/validation/entry-validator.js
 var KNOWN_FIELD_TYPES = new Set(fieldTypes);
 var STRING_FIELD_TYPES = /* @__PURE__ */ new Set(["string", "markdown", "mdx", "code"]);
-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") {
@@ -6006,79 +6589,79 @@ function isValidImageCropValue(value) {
   }
   return isValidCropRect(x, y, w, h);
 }
-function validateImageValue(field, value, path20) {
-  if (!isPlainRecord2(value)) {
-    return [{ fieldPath: path20, message: "Expected an image object with { src, alt }" }];
+function validateImageValue(field, value, path21) {
+  if (!isPlainRecord3(value)) {
+    return [{ fieldPath: path21, message: "Expected an image object with { src, alt }" }];
   }
   const errors = [];
   if (typeof value.src !== "string" || value.src.trim() === "") {
-    errors.push({ fieldPath: `${path20}.src`, message: "Image src is required" });
+    errors.push({ fieldPath: `${path21}.src`, message: "Image src is required" });
   }
   if (typeof value.alt !== "string") {
-    errors.push({ fieldPath: `${path20}.alt`, message: "Image alt text is required" });
+    errors.push({ fieldPath: `${path21}.alt`, message: "Image alt text is required" });
   } else if (value.alt.trim() === "" && field.altOptional !== true) {
-    errors.push({ fieldPath: `${path20}.alt`, message: "Image alt text is required" });
+    errors.push({ fieldPath: `${path21}.alt`, message: "Image alt text is required" });
   }
   if (value.width !== void 0 && !isPositiveInt(value.width)) {
-    errors.push({ fieldPath: `${path20}.width`, message: "Image width must be a positive integer" });
+    errors.push({ fieldPath: `${path21}.width`, message: "Image width must be a positive integer" });
   }
   if (value.height !== void 0 && !isPositiveInt(value.height)) {
     errors.push({
-      fieldPath: `${path20}.height`,
+      fieldPath: `${path21}.height`,
       message: "Image height must be a positive integer"
     });
   }
   if (value.crop !== void 0 && !isValidImageCropValue(value.crop)) {
-    errors.push({ fieldPath: `${path20}.crop`, message: "Invalid image crop rect" });
+    errors.push({ fieldPath: `${path21}.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;
 }
 var selectOptionValues = (field) => (field.options ?? []).map((opt) => typeof opt === "string" ? opt : opt.value);
-function validateScalar(field, value, path20) {
+function validateScalar(field, value, path21) {
   switch (field.type) {
     case "number":
       if (typeof value !== "number" || !Number.isFinite(value)) {
-        return [{ fieldPath: path20, message: "Expected a number" }];
+        return [{ fieldPath: path21, message: "Expected a number" }];
       }
       return [];
     case "boolean":
       if (typeof value !== "boolean") {
-        return [{ fieldPath: path20, message: "Expected true or false" }];
+        return [{ fieldPath: path21, message: "Expected true or false" }];
       }
       return [];
     case "datetime":
       if (typeof value !== "string" || value !== "" && Number.isNaN(Date.parse(value))) {
-        return [{ fieldPath: path20, message: "Expected a valid date/time string" }];
+        return [{ fieldPath: path21, message: "Expected a valid date/time string" }];
       }
       return [];
     case "select": {
       if (typeof value !== "string") {
-        return [{ fieldPath: path20, message: "Expected a selection" }];
+        return [{ fieldPath: path21, message: "Expected a selection" }];
       }
       const options = selectOptionValues(field);
       if (value !== "" && !options.includes(value)) {
-        return [{ fieldPath: path20, message: `Must be one of: ${options.join(", ")}` }];
+        return [{ fieldPath: path21, message: `Must be one of: ${options.join(", ")}` }];
       }
       return [];
     }
     case "reference":
       if (referenceValueId(value) === void 0) {
-        return [{ fieldPath: path20, message: "Expected a reference id" }];
+        return [{ fieldPath: path21, message: "Expected a reference id" }];
       }
       return [];
     case "image":
-      return validateImageValue(field, value, path20);
+      return validateImageValue(field, value, path21);
     default:
       if (STRING_FIELD_TYPES.has(field.type)) {
         if (typeof value !== "string") {
-          return [{ fieldPath: path20, message: "Expected text" }];
+          return [{ fieldPath: path21, message: "Expected text" }];
         }
       }
       return [];
@@ -6101,12 +6684,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
       errors.push(...validateEntryData(field.fields, data, pathPrefix));
       continue;
     }
-    const path20 = pathPrefix ? `${pathPrefix}.${field.name}` : field.name;
+    const path21 = 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: path20, message });
+      errors.push({ fieldPath: path21, message });
       continue;
     }
     if (value === void 0 || value === null)
@@ -6114,12 +6697,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
     if (field.type === "block") {
       const blockField = field;
       if (!Array.isArray(value)) {
-        errors.push({ fieldPath: path20, message: "Expected a list of blocks" });
+        errors.push({ fieldPath: path21, message: "Expected a list of blocks" });
         continue;
       }
       value.forEach((item, index) => {
-        const itemPath = `${path20}[${index}]`;
-        if (!isPlainRecord2(item)) {
+        const itemPath = `${path21}[${index}]`;
+        if (!isPlainRecord3(item)) {
           errors.push({ fieldPath: itemPath, message: "Expected a block object" });
           return;
         }
@@ -6140,12 +6723,12 @@ function validateEntryData(fields, data, pathPrefix = "") {
       const objectField = field;
       if (objectField.list) {
         if (!Array.isArray(value)) {
-          errors.push({ fieldPath: path20, message: "Expected a list of items" });
+          errors.push({ fieldPath: path21, message: "Expected a list of items" });
           continue;
         }
         value.forEach((item, index) => {
-          const itemPath = `${path20}[${index}]`;
-          if (!isPlainRecord2(item)) {
+          const itemPath = `${path21}[${index}]`;
+          if (!isPlainRecord3(item)) {
             errors.push({ fieldPath: itemPath, message: "Expected an object" });
             return;
           }
@@ -6153,28 +6736,28 @@ function validateEntryData(fields, data, pathPrefix = "") {
             errors.push(...validateEntryData(objectField.fields, item, itemPath));
           }
         });
-      } else if (!isPlainRecord2(value)) {
-        errors.push({ fieldPath: path20, message: "Expected an object" });
+      } else if (!isPlainRecord3(value)) {
+        errors.push({ fieldPath: path21, message: "Expected an object" });
       } else if (objectField.fields) {
-        errors.push(...validateEntryData(objectField.fields, value, path20));
+        errors.push(...validateEntryData(objectField.fields, value, path21));
       }
       continue;
     }
     if ("list" in field && field.list) {
       if (!Array.isArray(value)) {
-        errors.push({ fieldPath: path20, message: "Expected a list of values" });
+        errors.push({ fieldPath: path21, message: "Expected a list of values" });
         continue;
       }
       value.forEach((item, index) => {
-        errors.push(...validateScalar(field, item, `${path20}[${index}]`));
+        errors.push(...validateScalar(field, item, `${path21}[${index}]`));
       });
       continue;
     }
     if (Array.isArray(value) && KNOWN_FIELD_TYPES.has(field.type)) {
-      errors.push({ fieldPath: path20, message: "Expected a single value, not a list" });
+      errors.push({ fieldPath: path21, message: "Expected a single value, not a list" });
       continue;
     }
-    errors.push(...validateScalar(field, value, path20));
+    errors.push(...validateScalar(field, value, path21));
   }
   return errors;
 }
@@ -6222,6 +6805,38 @@ These are likely abandoned create-scaffolds (empty entries left behind when a cr
 }
 
 // dist/build/generate-ai-content.js
+var GENERATED_RECORD_FILENAME = ".canopy-generated.json";
+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, _testFlatSchema } = options;
   const contentRootName = config.contentRoot || "content";
@@ -6244,18 +6859,40 @@ async function generateAIContentFiles(options) {
     config: aiConfig,
     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 (!isNodeError(err) || err.code !== "ENOENT")
+        throw err;
+    }
+    await removeEmptyDirsUpward(path19.dirname(absolutePath), absoluteOutputDir);
+  }
+  await writeGeneratedRecord(absoluteOutputDir, currentFiles);
+  return { fileCount, removedCount, outputDir: absoluteOutputDir };
 }
 
 // dist/cli/generate-ai-content.js
@@ -6263,7 +6900,7 @@ var jiti = createJiti(import.meta.url);
 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);
@@ -6274,7 +6911,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);
@@ -6285,7 +6922,7 @@ async function generateAIContentCLI(options) {
   let aiConfig;
   if (configPath) {
     try {
-      const aiConfigModule = await jiti.import(path19.resolve(configPath));
+      const aiConfigModule = await jiti.import(path20.resolve(configPath));
       aiConfig = aiConfigModule.aiContentConfig ?? aiConfigModule.default ?? aiConfigModule.config;
     } catch (err) {
       console.error(`Could not load AI config from ${configPath}`);
@@ -6302,7 +6939,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({
@@ -6313,6 +6950,9 @@ 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}
 `);
 }