canopycms 0.0.67-int.90 → 0.0.67

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

@@ -478,18 +478,18 @@ var init_config = __esm({
       onAccountClick: z6.function().returns(z6.void()).optional(),
       onLogoutClick: z6.function().returns(z6.void()).optional(),
       // Optional: custom account component (e.g., Clerk's UserButton)
-      AccountComponent: z6.custom().optional()
+      AccountComponent: z6.custom().optional(),
+      // Optional: provider sign-in UI for signed-out users (see EditorSignInProps)
+      SignInComponent: z6.custom().optional()
     });
     CanopyConfigSchema = z6.object({
       media: mediaSchema.optional(),
-      // No outer .optional() here: defaultBranchAccessSchema/defaultPathAccessSchema already
-      // have .default('deny'), so the field is optional on input but always resolves to
-      // 'allow'/'deny' (never undefined) on output. An outer .optional() would short-circuit
-      // before the inner default runs, defeating the fail-closed default (SCH-M1).
-      // defaultPathAccessSchema's union keeps the same rule: the .default('deny') sits on the
-      // OUTER union, not inside defaultPathAccessLevelsSchema, so an omitted top-level field
-      // still resolves to 'deny' and an omitted level inside the object form stays undefined
-      // (resolved to 'deny' at read time by resolveDefaultPathAccess).
+      // No outer .optional(): both schemas already .default('deny'), so the field is optional on
+      // input but always resolves to 'allow'/'deny' (never undefined) on output — an outer
+      // .optional() would short-circuit before the inner default runs, defeating the fail-closed
+      // default (SCH-M1). defaultPathAccessSchema's .default('deny') sits on the OUTER union, not
+      // inside defaultPathAccessLevelsSchema, so an omitted level in the object form stays
+      // undefined (resolved to 'deny' at read time by resolveDefaultPathAccess).
       defaultBranchAccess: defaultBranchAccessSchema,
       defaultPathAccess: defaultPathAccessSchema,
       // .optional() deliberately defeats defaultBaseBranchSchema's .default('main'):
@@ -513,16 +513,11 @@ var init_config = __esm({
       allowNetworkRemoteInProd: z6.boolean().optional(),
       settingsBranch: z6.string().optional(),
       autoCreateSettingsPR: z6.boolean().optional(),
-      // Deliberately `deploymentNameSchema.optional()`, NOT `deploymentNameSchema` alone.
-      // deploymentNameSchema.default('prod') would make `parse(undefined)` resolve to
-      // the literal 'prod' instead of staying `undefined` — collapsing the
-      // env > config > modeDefault precedence chain that resolveDeploymentName
-      // (operating-mode/deployment-name.ts) implements: config would then always
-      // "win" over modeDefault (masking dev's real default of 'local'), and the env
-      // var would just be racing config's baked-in 'prod' instead of a true absence.
-      // `.optional()` here is what keeps an omitted deploymentName reaching
-      // resolveDeploymentName as `undefined`, so it can fall through to modeDefault.
-      // Do not "fix" this by removing `.optional()`.
+      // `.optional()`, NOT bare `deploymentNameSchema`: its own `.default('prod')` would make
+      // `parse(undefined)` resolve to 'prod' instead of staying `undefined`, collapsing the
+      // env > config > modeDefault precedence chain `resolveDeploymentName`
+      // (operating-mode/deployment-name.ts) implements — config would always "win" over
+      // modeDefault, masking dev's real default of 'local'. Do not remove `.optional()`.
       deploymentName: deploymentNameSchema.optional(),
       contentRoot: contentRootSchema.default("content"),
       sourceRoot: sourceRootSchema.optional(),
@@ -632,7 +627,6 @@ var init_client_safe_strategy = __esm({
       constructor() {
         this.mode = "prod";
       }
-      // UI Feature Flags
       supportsBranching() {
         return true;
       }
@@ -645,7 +639,6 @@ var init_client_safe_strategy = __esm({
       supportsPullRequests() {
         return true;
       }
-      // Simple Data
       getPermissionsFileName() {
         return "permissions.json";
       }
@@ -663,7 +656,6 @@ var init_client_safe_strategy = __esm({
       constructor() {
         this.mode = "dev";
       }
-      // UI Feature Flags
       supportsBranching() {
         return true;
       }
@@ -676,7 +668,6 @@ var init_client_safe_strategy = __esm({
       supportsPullRequests() {
         return false;
       }
-      // Simple Data
       getPermissionsFileName() {
         return "permissions.json";
       }
@@ -796,11 +787,6 @@ var init_client_unsafe_strategy = __esm({
     init_deployment_name();
     init_config2();
     ProdStrategy = class extends ProdClientSafeStrategy {
-      // All client-safe methods inherited automatically from ProdClientSafeStrategy:
-      // - mode, supportsBranching(), supportsStatusBadge(), supportsComments()
-      // - supportsPullRequests(), getPermissionsFileName(), getGroupsFileName()
-      // - shouldCommit(), shouldPush()
-      // Add client-unsafe methods (use Node.js APIs)
       getWorkspaceRoot(_sourceRoot) {
         return path9.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE);
       }
@@ -854,7 +840,6 @@ var init_client_unsafe_strategy = __esm({
       }
     };
     DevStrategy = class extends DevClientSafeStrategy {
-      // Inherits client-safe methods from DevClientSafeStrategy
       getWorkspaceRoot(sourceRoot) {
         return path9.resolve(sourceRoot ?? process.cwd(), ".canopy-dev");
       }
@@ -910,8 +895,6 @@ var init_client_unsafe_strategy = __esm({
 // dist/operating-mode/index.js
 var operating_mode_exports = {};
 __export(operating_mode_exports, {
-  BROWSER_MODE_ENV_VAR: () => BROWSER_MODE_ENV_VAR,
-  SERVER_MODE_ENV_VAR: () => SERVER_MODE_ENV_VAR,
   clearClientStrategyCache: () => clearClientStrategyCache,
   clearStrategyCache: () => clearStrategyCache,
   clientOperatingStrategy: () => clientOperatingStrategy,
@@ -1216,12 +1199,11 @@ function provisioningLockOptions(lockPath, retries, onCompromised) {
     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.
+    // proper-lockfile invokes this from inside its refresh timer, so ANY throw escaping here is
+    // an uncaught exception that kills the process. 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 a console write into a
+    // throw.
     onCompromised: (err) => {
       try {
         if (onCompromised) {
@@ -1513,9 +1495,9 @@ var ContentIdIndex = class {
     this.root = path4.resolve(root);
   }
   /**
-   * Build index by scanning filenames recursively. Duplicate embedded IDs
-   * are quarantined, not thrown on -- see the class doc comment's
-   * "Duplicate-ID quarantine" section and {@link getDuplicateIds}.
+   * Build the index by scanning filenames recursively. Duplicate embedded IDs
+   * are quarantined, not thrown on — see the class doc and
+   * {@link getDuplicateIds}.
    */
   async buildFromFilenames(startPath = "") {
     await this.scanDirectory(startPath);
@@ -1531,7 +1513,7 @@ var ContentIdIndex = class {
       this.byCollection.get(location.collection).add(id);
     }
   }
-  /** Remove a location from all three indexes -- used when a lexicographically-earlier duplicate displaces it. */
+  /** Remove a location from all three indexes, when an earlier duplicate displaces it. */
   evictLocation(location) {
     this.idToLocation.delete(location.id);
     this.pathToId.delete(location.relativePath);
@@ -1544,7 +1526,7 @@ var ContentIdIndex = class {
       }
     }
   }
-  /** Record a quarantined duplicate path for admin-facing health reporting (see getDuplicateIds). */
+  /** Record a quarantined duplicate path for health reporting (see getDuplicateIds). */
   recordDuplicate(id, droppedPath) {
     let dropped = this.duplicateIds.get(id);
     if (!dropped) {
@@ -1606,11 +1588,9 @@ var ContentIdIndex = class {
     }
   }
   /**
-   * IDs discovered on more than one file during the last buildFromFilenames
-   * scan. Empty unless the content tree currently has a duplicate-ID pair
-   * (see the class doc comment). Consumed by branch-health.ts's admin scan
-   * and by the repair-content-duplicates admin action
-   * (api/admin-branch-health.ts).
+   * IDs the last buildFromFilenames scan found on more than one file; empty
+   * otherwise. Consumed by branch-health.ts's admin scan and by the
+   * repair-content-duplicates action (api/admin-branch-health.ts).
    */
   getDuplicateIds() {
     const result = [];
@@ -1622,11 +1602,10 @@ var ContentIdIndex = class {
     return result;
   }
   /**
-   * The quarantine record for ONE id, or null when that id is not
-   * duplicated. The O(1) counterpart to {@link getDuplicateIds} for the
-   * write path, which has to ask this question on every save whose resolved
-   * path disagrees with the index (ContentStore.write()'s duplicate-ID
-   * guard) and must not pay for materializing the whole list.
+   * The quarantine record for ONE id, or null when that id is not duplicated.
+   * The O(1) counterpart to {@link getDuplicateIds}, for ContentStore.write()'s
+   * duplicate-ID guard: it asks on every save whose resolved path disagrees
+   * with the index, so it must not pay to materialize the whole list.
    */
   getDuplicateFor(id) {
     const dropped = this.duplicateIds.get(id);
@@ -1641,33 +1620,19 @@ var ContentIdIndex = class {
       droppedPaths: Array.from(dropped).sort()
     };
   }
-  /**
-   * Forward lookup: ID → location (O(1))
-   */
+  /** Forward lookup: ID → location (O(1)). */
   findById(id) {
     return this.idToLocation.get(id) || null;
   }
-  /**
-   * Reverse lookup: path → ID (O(1))
-   */
+  /** Reverse lookup: path → ID (O(1)). */
   findByPath(relativePath) {
     return this.pathToId.get(relativePath) || null;
   }
-  /**
-   * Get all ID locations in the index.
-   * Useful for validation and checking references.
-   */
+  /** Every ID location in the index, for validation and reference checking. */
   getAllLocations() {
     return Array.from(this.idToLocation.values());
   }
-  /**
-   * Get all entries in a collection by collection path.
-   *
-   * Performance: O(1) + O(m) where m is the number of entries in the collection.
-   *
-   * @param collectionPath - The collection path (e.g., "content/posts")
-   * @returns Array of IdLocation objects for entries in the collection
-   */
+  /** Entries in one collection: O(1) + O(entries in it). */
   getEntriesInCollection(collectionPath) {
     const idSet = this.byCollection.get(collectionPath);
     if (!idSet) {
@@ -1683,14 +1648,9 @@ var ContentIdIndex = class {
     return locations;
   }
   /**
-   * Get all entries in a collection and its subcollections (tree traversal).
-   * For example, getEntriesInCollectionTree("content/data-catalog") returns entries
-   * in "content/data-catalog", "content/data-catalog/openstax", etc.
-   *
-   * Performance: O(k * m) where k is number of matching collections and m is avg entries per collection.
-   *
-   * @param collectionPath - The root collection path to search
-   * @returns Array of IdLocation objects for entries in the collection tree
+   * Entries in a collection and every subcollection: "content/docs" returns
+   * "content/docs", "content/docs/api", and so on. O(matching collections ×
+   * entries each).
    */
   getEntriesInCollectionTree(collectionPath) {
     const locations = [];
@@ -1713,7 +1673,6 @@ var ContentIdIndex = class {
    *
    * Performance: O(n) where n is total number of entries.
    *
-   * @returns Array of all IdLocation objects that are entries
    */
   getAllEntryLocations() {
     const locations = [];
@@ -1728,9 +1687,8 @@ var ContentIdIndex = class {
     return locations;
   }
   /**
-   * Add a new entry or collection to the index.
-   * Note: This only updates the in-memory index. The file with embedded ID
-   * must already exist on disk (created by ContentStore).
+   * Add an entry or collection. In-memory only: the file with the embedded ID
+   * must already exist on disk, created by ContentStore. Throws on collision.
    */
   add(location) {
     const id = extractIdFromFilename(path4.basename(location.relativePath));
@@ -1758,8 +1716,8 @@ var ContentIdIndex = class {
     }
   }
   /**
-   * Remove an entry or collection from the index by ID.
-   * Note: This only updates the in-memory index. The file must be deleted separately.
+   * Remove an entry or collection by ID. In-memory only: the caller deletes the
+   * file separately.
    */
   remove(id) {
     const location = this.idToLocation.get(id);
@@ -1778,8 +1736,8 @@ var ContentIdIndex = class {
     this.pathToId.delete(location.relativePath);
   }
   /**
-   * Update the path for an existing ID (e.g., after file rename/move).
-   * This is used to keep the index in sync when files are renamed.
+   * Repoint an existing ID at a new path; keeps the index in step with a
+   * rename or move. Throws when the ID is unknown.
    */
   updatePath(id, newRelativePath) {
     const location = this.idToLocation.get(id);
@@ -2053,15 +2011,11 @@ var DebugLogger = class {
     return LOG_LEVELS[level] >= LOG_LEVELS[minLevel];
   }
   /**
-   * The ISO-8601 timestamp leads the line BARE - not wrapped in brackets as it
-   * once was. `CANOPYCMS_DEBUG=true` can be set on the EC2 worker, whose stdout
-   * appends to /var/log/canopy-worker/worker.log; the CloudWatch agent's
-   * `multi_line_start_pattern` matches the timestamp at the START of a line
-   * (see worker/log.ts's INVARIANT and cms-service.ts's agent config), so a
-   * leading `[` meant every debug line was silently folded into the previous
-   * event instead of starting its own. The bracketed `[prefix:category]` and
-   * `[level]` fields still follow, so the human-readable shape is unchanged
-   * apart from those two characters.
+   * The ISO-8601 timestamp leads the line BARE, never bracketed. `CANOPYCMS_DEBUG=true` can
+   * be set on the EC2 worker, whose stdout appends to /var/log/canopy-worker/worker.log, and
+   * the CloudWatch agent's `multi_line_start_pattern` matches a timestamp at the START of a
+   * line (see worker/log.ts's INVARIANT and cms-service.ts's agent config): any leading
+   * character folds the line into the previous event instead of starting its own.
    */
   formatMessage(level, category, message) {
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -2094,15 +2048,9 @@ var DebugLogger = class {
       throw new Error(errorMsg);
     }
   }
-  /**
-   * Start timing an operation
-   */
   time(label) {
     this.timers.set(label, Date.now());
   }
-  /**
-   * End timing an operation and log the duration
-   */
   timeEnd(category, label) {
     const start = this.timers.get(label);
     if (start === void 0) {
@@ -2114,9 +2062,6 @@ var DebugLogger = class {
     this.debug(category, `${label} completed`, { durationMs: duration });
     return duration;
   }
-  /**
-   * Wrap an async function with automatic timing
-   */
   async timed(category, label, fn) {
     this.time(label);
     try {
@@ -2232,7 +2177,6 @@ async function scanForCollectionMeta(baseDir, relativePath = "") {
         collections.push({
           ...meta,
           path: folderPath,
-          // Path derived from folder name
           contentId: collectionContentId
         });
         const nestedCollections = await scanForCollectionMeta(absolutePath, folderPath);
@@ -2482,38 +2426,26 @@ var BranchSchemaCache = class {
   /**
    * Whether to skip the on-disk cache for this branchRoot.
    *
-   * branchRoot equals the project root (process.cwd()) only in the synthetic
-   * contexts used by static deployments and build phases — real branch roots are
-   * always nested under the workspace (.canopy-dev/content-branches/<name> in dev,
-   * <workspaceRoot>/content-branches/<name> in prod). Never write .canopy-meta/ at
-   * the project root, regardless of which entrypoint produced the cwd branchRoot.
+   * Never write `.canopy-meta/` at the project root, whichever entrypoint
+   * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
+   * synthetic contexts static deployments and build phases use; a real branch
+   * root is always nested under the workspace.
    */
   skipDiskCache(branchRoot) {
     return isBuildMode() || path8.resolve(branchRoot) === path8.resolve(process.cwd());
   }
-  /**
-   * Get schema for a branch (loads from cache or resolves fresh).
-   *
-   * @param branchRoot - Root directory of the branch (e.g., .canopy-dev/content-branches/main)
-   * @param entrySchemaRegistry - Map of schema names to field definitions
-   * @param contentRootName - Name of content directory (e.g., "content") from config
-   * @returns Resolved schema tree and flattened schema
-   */
+  /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
   async getSchema(branchRoot, entrySchemaRegistry, contentRootName = "content") {
     return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName);
   }
   /**
-   * Resolve the schema from disk. Wrapped in a protected method (rather than
-   * calling the imported resolveSchema directly) so tests can subclass and
-   * override with a deferred/blocking implementation to simulate cross-process
+   * Resolve the schema from disk. Protected rather than a direct resolveSchema
+   * call so tests can subclass and block it to simulate cross-process
    * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
    */
   async resolveFresh(contentRoot, entrySchemaRegistry) {
     return resolveSchema(contentRoot, entrySchemaRegistry);
   }
-  /**
-   * Load schema from cache or resolve fresh if cache is missing or stale.
-   */
   async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
     const contentRoot = path8.join(branchRoot, contentRootName);
     const skipDiskCache = this.skipDiskCache(branchRoot);
@@ -2599,23 +2531,13 @@ var BranchSchemaCache = class {
     return { schema: result.schema, flatSchema };
   }
   /**
-   * Resolve the schema fresh from disk and persist it, SKIPPING the cache
-   * read entirely -- unlike {@link getSchema}, which can short-circuit
-   * through a cache HIT. That distinction matters for eager re-resolve after
-   * invalidation (see {@link invalidate}'s doc comment and
-   * `SchemaOps.invalidateSchemaCache()` in schema/schema-store.ts, the sole
-   * intended caller): the whole point of an eager re-resolve is to guarantee
-   * ONE scan that is coherent with the mutation this host just made. A plain
-   * `getSchema()` call right after `invalidate()` is NOT that guarantee --
-   * `getSchema()`'s cache-read fast path (`loadFromCacheOrResolve`) can still
-   * return a snapshot written by a DIFFERENT, concurrent host: if that
-   * foreign host's own eager re-resolve raced this one and embedded the
-   * (now-current) marker token over ITS OWN stale-NFS-cache scan (the
-   * window-E case this class's doc comment describes), this host's
-   * `getSchema()` would happily accept that foreign snapshot as "current"
-   * and skip the one scan this call was specifically trying to guarantee.
-   * `resolveAndPersist()` never reads the cache file at all, so it cannot be
-   * short-circuited that way.
+   * Resolve fresh from disk and persist, SKIPPING the cache read entirely.
+   * That is what makes it, and not {@link getSchema}, the right call for the
+   * eager re-resolve in `SchemaOps.invalidateSchemaCache()` (its sole intended
+   * caller): an eager re-resolve exists to guarantee ONE scan coherent with the
+   * mutation this host just made, and getSchema()'s cache-read fast path can
+   * instead return a snapshot a concurrent host wrote — possibly one embedding
+   * the now-current token over ITS own stale-NFS scan — skipping that scan.
    */
   async resolveAndPersist(branchRoot, entrySchemaRegistry, contentRootName = "content") {
     const skipDiskCache = this.skipDiskCache(branchRoot);
@@ -2624,20 +2546,12 @@ var BranchSchemaCache = class {
     });
   }
   /**
-   * Invalidate cache for a branch by bumping the cross-process generation
-   * marker (resource-generation.ts). Every process sharing this branchRoot
-   * will re-resolve at its next read.
+   * Invalidate a branch's cache by bumping the marker; every process sharing
+   * this branchRoot re-resolves at its next read. The bump must succeed —
+   * swallowing that failure leaves the schema cache stale indefinitely, and
+   * unlike BranchRegistry there is no get-miss backstop for a resolved schema.
    *
-   * The bump must succeed: a swallowed failure here would leave the schema
-   * cache stale indefinitely with no bounding backstop (unlike
-   * BranchRegistry, there is no get-miss backstop for a resolved schema).
-   *
-   * No eager regeneration here (unlike BranchRegistry.invalidate()): this
-   * method isn't given the entrySchemaRegistry/contentRootName resolveSchema
-   * needs. See the class doc comment for why the mutating request's own
-   * follow-up schema read closes the same window-E gap instead.
-   *
-   * @param branchRoot - Root directory of the branch
+   * No eager re-resolve here; it lives in SchemaOps (see the class doc).
    */
   async invalidate(branchRoot) {
     if (this.skipDiskCache(branchRoot))
@@ -2790,13 +2704,10 @@ var DuplicateContentIdError = class extends ContentConflictError {
   constructor(contentId, paths) {
     const sorted = Array.from(new Set(paths)).sort();
     super(
-      // Names the STATE, not an action. The repair-content-duplicates
-      // endpoint exists but nothing in the editor renders it, so telling an
-      // editor "an admin can run X" sent them to an admin who could neither
-      // run X nor see that the branch was affected. Say what is true; the
-      // admin panel's read-only duplicate list (SystemHealthPanel) is the
-      // diagnosis half, and the repair UI is tracked in
-      // .claude/future-tasks/duplicate-content-id-repair-ui.md.
+      // Names the STATE, not an action: the repair-content-duplicates endpoint
+      // exists but nothing in the editor renders it, and the admin panel's
+      // duplicate list (SystemHealthPanel) is the diagnosis half only. The repair
+      // UI is tracked in .claude/future-tasks/duplicate-content-id-repair-ui.md.
       `Content ID ${contentId} is on more than one file (${sorted.map((p) => `"${p}"`).join(" and ")}), so this save was refused rather than risk overwriting or deleting the wrong one. An administrator needs to resolve the duplicate on the server before this entry can be saved.`
     );
     this.name = "DuplicateContentIdError";
@@ -2846,20 +2757,16 @@ var ContentStore = class {
   }
   /**
    * [SYNC-C1] Run a working-tree mutation under the branch's cross-host
-   * content-write lock (utils/content-write-lock.ts), on top of the
-   * in-process locks the callee takes for itself.
+   * content-write lock (utils/content-write-lock.ts), on top of the in-process
+   * locks the callee takes for itself. The in-process mutex serializes writers
+   * inside ONE process and says nothing about the EC2 worker rebasing this same
+   * tree on shared EFS, which destroys an in-flight save.
    *
-   * The in-process mutex serializes writers inside ONE process; it says
-   * nothing about the EC2 worker rebasing this same tree on shared EFS, which
-   * destroys an in-flight save (`checkout --theirs` overwrites it and the
-   * rebase then reports success; `rebase --abort` hard-resets it). This is the
-   * layer that actually excludes the two.
+   * Reads deliberately do NOT take it: an extra EFS round-trip per read is not an
+   * acceptable cost, and a rebase cannot destroy a read.
    *
-   * Reads deliberately do NOT take it -- an extra EFS round-trip per read is
-   * not an acceptable cost, and reads cannot be destroyed by a rebase.
-   *
-   * Acquisition order is always content lock -> `withLock`, never the reverse,
-   * so the two cannot deadlock.
+   * Acquisition order is always content lock -> `withLock`, never the reverse, so
+   * the two cannot deadlock.
    */
   async withContentWriteExclusion(fn) {
     try {
@@ -2875,20 +2782,18 @@ var ContentStore = class {
    *
    * Called (via content-index-registry) after in-process operations that change the
    * working tree underneath this store — git checkout/merge/rebase, the worker's
-   * rebase loop, and sync-core's content replacement. Without this, ID→path lookups
-   * keep resolving to pre-mutation paths and saves can target moved/deleted files.
-   *
-   * Cheap: only bumps a generation counter; the rebuild happens lazily.
+   * rebase loop, sync-core's content replacement. Without it, ID→path lookups keep
+   * resolving to pre-mutation paths and saves can target moved/deleted files.
+   * Cheap: bumps a generation counter, the rebuild is lazy.
    */
   invalidateIndex() {
     this.indexGeneration++;
   }
   /**
-   * Get the ID index, ensuring it's loaded and current first.
-   * Loads lazily on first access and rebuilds after invalidateIndex(); repeated
-   * accesses with no intervening invalidation reuse the already-built index,
-   * except for a throttled probe of the on-disk generation marker that detects
-   * mutations made by OTHER processes sharing this root (e.g. on EFS).
+   * The ID index, rebuilt first if stale. Loads lazily, rebuilds after
+   * invalidateIndex(), and otherwise reuses the built index apart from a throttled
+   * probe of the on-disk generation marker, which detects mutations by OTHER
+   * processes sharing this root (e.g. on EFS).
    */
   async idIndex() {
     if (this.loadedIndexGeneration === this.indexGeneration && this.shouldProbeDiskGeneration()) {
@@ -2936,14 +2841,12 @@ var ContentStore = class {
     return true;
   }
   /**
-   * After one of this store's own successful mutations: publish the change to
-   * other processes (bump the on-disk marker) and adopt the written token,
-   * since the in-memory index was already updated incrementally — avoiding a
-   * pointless self-rescan on the next probe. Adoption is skipped unless the
-   * index is quiescent and `updatedIndex` is still the live instance: if a
-   * rebuild raced with the mutation, its scan may predate our file change, so
-   * we leave the recorded token older and let the next probe observe our bump
-   * and trigger the healing rebuild.
+   * After one of this store's own successful mutations: publish it to other
+   * processes (bump the on-disk marker) and adopt the written token, since the
+   * in-memory index was already updated incrementally. Adoption is skipped unless
+   * the index is quiescent and `updatedIndex` is still the live instance: a rebuild
+   * that raced the mutation may have scanned before our file change, so leaving the
+   * recorded token older lets the next probe observe our bump and heal.
    */
   async recordOwnMutation(updatedIndex) {
     const token = await bumpContentIndexGeneration(this.root);
@@ -2952,16 +2855,14 @@ var ContentStore = class {
     }
   }
   /**
-   * Backstop for the residual staleness windows of the cross-process marker
-   * (NFS attribute caching, probe throttle, self-adoption — see
-   * content-index-generation.ts): force one rebuild in response to a
-   * suspicious lookup (an ID miss, or an index hit whose file is gone), but
-   * throttle how often a caller can force one. Time-boxed so genuinely
-   * dangling IDs cost at most one rescan per window. Returns true if a
-   * refresh was performed by THIS call; callers that lose the throttle race
-   * still benefit — idIndex() dedupes concurrent builds, so a caller that won
-   * the race rebuilds the index for everyone, and callers should still retry
-   * their lookup against the live index regardless of this return value.
+   * Backstop for the residual staleness windows of the cross-process marker (NFS
+   * attribute caching, probe throttle, self-adoption — see
+   * content-index-generation.ts): force one rebuild in response to a suspicious
+   * lookup (an ID miss, or an index hit whose file is gone), throttled so a
+   * genuinely dangling ID costs at most one rescan per window. Returns true only if
+   * THIS call refreshed; a caller that loses the throttle race must still retry its
+   * lookup, since idIndex() dedupes concurrent builds and the winner rebuilds for
+   * everyone.
    */
   async refreshIndexForSuspiciousLookup() {
     const now = Date.now();
@@ -2973,13 +2874,12 @@ var ContentStore = class {
     return true;
   }
   /**
-   * Every file in `dir` whose filename embeds `id`, as root-relative paths
-   * (empty when there is no such file, or no such dir).
+   * Every file in `dir` whose filename embeds `id`, as root-relative paths (empty
+   * when there is no such file, or no such dir).
    *
-   * [F1] Returns ALL matches, not the first: more than one match is a
-   * duplicate-ID pair, and callers must be able to tell that apart from a
-   * clean single hit rather than silently picking whichever one `readdir()`
-   * happened to yield first.
+   * [F1] Returns ALL matches, not the first: more than one match is a duplicate-ID
+   * pair, and callers must be able to tell that apart from a clean single hit rather
+   * than silently picking whichever one `readdir()` happened to yield first.
    */
   async findEntryPathsById(dir, id) {
     let entries;
@@ -3000,10 +2900,6 @@ var ContentStore = class {
     }
     return matches.sort();
   }
-  /**
-   * Get all schema items for iteration.
-   * Used internally by ReferenceResolver for path matching.
-   */
   getSchemaItems() {
     return this.schemaIndex.values();
   }
@@ -3019,17 +2915,16 @@ var ContentStore = class {
    * Is this path a COLLECTION schema item?
    *
    * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
-   * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
-   * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
-   * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
-   * first-wins and would not.
+   * point: a caller that gates on this cannot disagree with what `buildPaths` will then do,
+   * because the Map is last-wins where a subcollection's path collides with a parent's
+   * entry-type name. A `find` over the flat schema LIST is first-wins and would not.
    *
-   * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
-   * with subcollections and no entries of its own is legal, and mirroring that stricter test here
-   * would reject something `buildPaths` accepts.
+   * Type-only, deliberately: `resolvePath` additionally requires `entries`, but a collection
+   * with subcollections and no entries of its own is legal, and testing for that here would
+   * reject something `buildPaths` accepts.
    *
    * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
-   * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+   * `urlAddressableOnly`.
    */
   isCollectionPath(collectionPath) {
     return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === "collection";
@@ -3037,23 +2932,20 @@ var ContentStore = class {
   /**
    * Does this collection declare `entryTypeName` in its `entries` config?
    *
-   * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
-   * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
-   * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
-   * was renamed out of the schema stays findable and therefore still editable, renameable and
-   * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+   * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries`
+   * decides whether a file on disk is one of the collection's entries at all. `buildPaths`'
+   * own directory scan deliberately does NOT check this -- it matches on slug alone, so an
+   * entry whose type was renamed out of the schema stays findable and therefore editable,
+   * renameable and deletable. Only URL resolution consults this, so what enumeration hides is
+   * not served.
    *
-   * Returns FALSE when the collection declares no `entries` at all, which is stricter than
-   * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
-   * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
-   * outright for a collection with no `entries`. A collections-only container therefore publishes
-   * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
-   * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
-   * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
-   * or by retrofit, and it is invisible to the sitemap and to static params either way.
+   * Returns FALSE when the collection declares no `entries` at all -- stricter than
+   * `parseTypedFilename`'s own guard, and deliberately so: the enumerating surface is
+   * `listCollectionEntries`, which returns `[]` outright for such a collection, so a URL read
+   * resolving a file sitting in one would answer where nothing is advertised.
    *
-   * Returns true for a path that is not a collection at all, because that is rule 1's question,
-   * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+   * Returns true for a path that is not a collection at all, because that is rule 1's
+   * question, and under `urlAddressableOnly` rule 1 has already rejected it.
    */
   declaresEntryType(collectionPath, entryTypeName) {
     const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
@@ -3071,25 +2963,20 @@ var ContentStore = class {
     return item;
   }
   /**
-   * Lock key for an existing entry, addressed by its permanent content ID
-   * (stable across renames -- the whole point of this locking scheme; see
-   * .claude/future-tasks/resolved/content-store-lock-key.md). Namespaced by store
-   * root: the same content ID exists in every clone of a branch, and one
-   * process can hold ContentStore instances on several clones (dev
-   * workspace roots, prod branch clones) at once, so the root prefix keeps
-   * the keyspace scoped per-store. It also keeps this ID keyspace disjoint
-   * from other modules' raw-path-keyed locks sharing the same withLock()
-   * map (comment-store, branch-metadata, etc).
+   * Lock key for an existing entry, addressed by its permanent content ID --
+   * stable across renames, which is the whole point of this locking scheme.
+   * Namespaced by store root: the same content ID exists in every clone of a
+   * branch and one process can hold stores on several clones at once, so the
+   * prefix scopes the keyspace per store and keeps it disjoint from other
+   * modules' raw-path-keyed locks sharing the same withLock() map.
    */
   idLockKey(id) {
     return `${this.root}:id:${id}`;
   }
   /**
-   * Stable collection+slug identifier for lock-key namespacing. Mirrors the
-   * schemaItem resolution buildPaths() performs for entry-type delegation:
-   * an entry-type item delegates to its parent collection with the slug
-   * defaulting to the entry type's own name (see buildPaths()'s
-   * `schemaItem.type === 'entry-type'` branch).
+   * Stable collection+slug identifier for lock-key namespacing. Mirrors
+   * buildPaths()' entry-type delegation: an entry-type item delegates to its
+   * parent collection with the slug defaulting to the entry type's own name.
    */
   collectionSlugKey(schemaItem, slug) {
     if (schemaItem.type === "entry-type") {
@@ -3099,27 +2986,24 @@ var ContentStore = class {
   }
   /**
    * Lock key for a not-yet-existing entry (a create). Serializes concurrent
-   * same-slug creates WITHIN this process: the second call's in-lock
-   * buildPaths() re-resolution will find the first call's just-written file
-   * and fold in as an edit (see write()). A concurrent create racing from a
-   * DIFFERENT process is NOT covered by this in-process mutex -- accepted
-   * per the epic's design review: each writer mints its own fresh ID and
-   * writes its own distinct filename, so both writes succeed and the result
-   * is two same-slug files with different IDs (a slug-uniqueness violation
-   * surfaced on the next listing/lookup), never a duplicate-ID collision
-   * that would poison index rebuilds.
+   * same-slug creates WITHIN this process: the second call's in-lock buildPaths()
+   * re-resolution finds the first call's just-written file and folds in as an edit.
+   *
+   * A create racing from a DIFFERENT process is NOT covered by this in-process
+   * mutex, and that is accepted: each writer mints its own fresh ID and filename, so
+   * both writes succeed and the result is two same-slug files with different IDs (a
+   * slug-uniqueness violation surfaced on the next listing/lookup), never a
+   * duplicate-ID collision that would poison index rebuilds.
    */
   createLockKey(schemaItem, slug) {
     return `${this.root}:create:${this.collectionSlugKey(schemaItem, slug)}`;
   }
   /**
-   * Lock key for a write()/delete() pre-pass classification. Existing
-   * entries lock on their content ID (idLockKey()). Legacy entries with no
-   * embedded ID (pre-ID-era filenames -- renameEntry() already refuses to
-   * touch these, via its four-part filename check, so there is no rename
-   * race to guard against for them) fall back to the physical path, matching
-   * this store's original locking behavior for that narrow case. Not-yet-
-   * existing entries lock on a per-slug create-key (createLockKey()).
+   * Lock key for a write()/delete() pre-pass classification: an existing entry
+   * locks on its content ID (idLockKey()), a not-yet-existing one on a per-slug
+   * create-key (createLockKey()). An entry with no embedded ID falls back to its
+   * physical path -- renameEntry() refuses to touch those (its four-part filename
+   * check), so they have no rename race to guard against.
    */
   entryLockKey(schemaItem, slug, prePass) {
     if (!prePass.existed)
@@ -3130,9 +3014,6 @@ var ContentStore = class {
    * 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({
@@ -3147,19 +3028,15 @@ var ContentStore = class {
     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}
+   * Build absolute and relative paths for an entry, filename pattern
+   * `{type}.{slug}.{id}.{ext}`. `options.existingId` addresses a known entry; without it a
+   * new ID is generated. `options.entryTypeName` picks among a collection's entry types,
+   * defaulting to its default one.
    *
-   * SECURITY BOUNDARY: This method prevents path traversal attacks by:
-   * 1. Validating that resolved paths stay within the content root
-   * 2. Checking slugs for malicious patterns (via validateSlug)
-   * 3. Using path.resolve to normalize paths before validation
-   *
-   * This validation is performed BEFORE file I/O in resolveDocumentPath(),
-   * ensuring permission checks happen before any file system access.
-   *
-   * @param options.existingId - Optional ID to use (for edits). If not provided, generates new ID.
-   * @param options.entryTypeName - For collections with multiple entry types, specify which one to use. Defaults to the default entry type.
+   * SECURITY BOUNDARY against path traversal: resolved paths must stay inside the content
+   * root, slugs go through `validateSlug`, and everything is `path.resolve`d before those
+   * checks. All of it runs BEFORE any file I/O in resolveDocumentPath(), so permission checks
+   * happen before filesystem access.
    */
   async buildPaths(schemaItem, slug, options = {}) {
     const rootWithSep = this.root.endsWith(path11.sep) ? this.root : `${this.root}${path11.sep}`;
@@ -3246,10 +3123,7 @@ var ContentStore = class {
     }
     throw new ContentStoreError("Invalid schema item type", "VALIDATION");
   }
-  /**
-   * Path resolution: resolves a URL path to a schema item
-   * - Try as collection + slug (last segment = slug)
-   */
+  /** Resolve path segments to a collection schema item plus the trailing slug. */
   resolvePath(pathSegments) {
     if (pathSegments.length === 0) {
       throw new ContentStoreError("Empty path", "VALIDATION");
@@ -3319,15 +3193,11 @@ var ContentStore = class {
         collection: schemaItem.logicalPath,
         collectionName: schemaItem.name,
         format,
-        // Copy, never the object gray-matter hands back: its cache is
-        // process-global and keyed by file content, so every caller parsing the
-        // same bytes gets the SAME `data` instance (the hazard content-listing.ts
-        // documents at length). Assigning it straight into `doc.data` was safe
-        // only by accident -- `resolveReferencesInData` spreads its input, so the
-        // shared object got replaced a few lines down. But that only happens when
-        // resolution runs: with `resolveReferences: false` the caller was handed
-        // the shared instance itself, and one mutation would poison every later
-        // parse of those bytes.
+        // Copy, never the object gray-matter hands back: its cache is process-global and
+        // keyed by file content, so every caller parsing the same bytes gets the SAME `data`
+        // instance (the hazard content-listing.ts documents at length). With
+        // `resolveReferences: false` the caller would otherwise be handed that shared
+        // instance, and one mutation would poison every later parse of those bytes.
         data: { ...parsed.data ?? {} },
         body: parsed.content,
         bodyFieldName: findBodyFieldName(fields),
@@ -3532,7 +3402,6 @@ var ContentStore = class {
     }
   }
   /**
-   * Get the ID for an entry given its collection and slug.
    * Returns null if no ID exists yet.
    */
   async getIdForEntry(collectionPath, slug) {
@@ -3558,20 +3427,16 @@ var ContentStore = class {
     }
   }
   /**
-   * Resolve the actual on-disk entry type of an existing collection entry, by
-   * inspecting its filename directly. Entry filenames embed their type
-   * (`{type}.{slug}.{id}.{ext}`) and it is immutable after creation — see the
-   * existing-file lookup in buildPaths(), which this mirrors. Returns
-   * undefined if no entry exists yet at this slug.
+   * The on-disk entry type of an existing collection entry, read from its filename
+   * (`{type}.{slug}.{id}.{ext}`), which is immutable after creation -- mirroring the
+   * existing-file lookup in buildPaths(). Undefined if no entry exists yet at this slug.
    *
-   * Used at the API write boundary (api/content.ts) to validate an existing
-   * entry's payload against ITS real schema rather than a caller-supplied (or
-   * omitted/spoofed) `entryType` param — ContentStore.write() preserves the
-   * on-disk type regardless of what's requested, so validation must agree
-   * with what will actually be written (post-review M2).
+   * The API write boundary (api/content.ts) validates an existing entry's payload against ITS
+   * real schema rather than a caller-supplied (or omitted, or spoofed) `entryType` param:
+   * ContentStore.write() preserves the on-disk type regardless of what is requested, so
+   * validation must agree with what will actually be written.
    *
-   * Cheap: one buildPaths() resolution plus a stat, no file content is read —
-   * same cost class as documentExists().
+   * Cheap: one buildPaths() resolution plus a stat, no file content is read.
    */
   async getExistingEntryType(collectionPath, slug = "") {
     const schemaItem = this.assertCollection(collectionPath);
@@ -3579,9 +3444,9 @@ var ContentStore = class {
     return await filePathExists(absolutePath) ? entryTypeName : void 0;
   }
   /**
-   * Count existing entries of a given entry type in a collection, by filename
-   * (entry filenames embed their type: `{type}.{slug}.{id}.{ext}`). Used to
-   * enforce `EntryTypeConfig.maxItems` server-side at the create boundary.
+   * Count existing entries of a given entry type in a collection, by filename (entry
+   * filenames embed their type: `{type}.{slug}.{id}.{ext}`). Enforces
+   * `EntryTypeConfig.maxItems` server-side at the create boundary.
    */
   async countEntriesOfType(collectionPath, entryTypeName) {
     this.assertCollection(collectionPath);
@@ -3592,21 +3457,15 @@ var ContentStore = class {
     return entries.filter((entry) => !entry.isDirectory() && extractEntryTypeFromFilename(entry.name) === entryTypeName).length;
   }
   /**
-   * Test-only seam: awaited right after the pre-pass buildPaths() resolves
-   * in delete() and renameEntry(), before the lock key is used to acquire
-   * anything. No-op in production. A test subclass can override this to
-   * inject a controlled pause in that exact window, letting a test
-   * deterministically run OTHER mutations (which don't hold this call's
-   * not-yet-acquired lock) to completion before this call proceeds to
-   * acquire its (possibly now-stale) lock key -- see the "Deterministic
-   * interleavings" testing pattern in docs/concurrency.md and
-   * branch-registry.test.ts's `BlockingRegistry` for the same idiom.
+   * Test-only seam: awaited right after the pre-pass buildPaths() resolves in delete() and
+   * renameEntry(), while neither has yet acquired a lock. No-op in production. A test subclass
+   * overrides it to pause in that exact window and run OTHER mutations to completion, making
+   * the stale-lock-key path deterministic -- see the "Deterministic interleavings" testing
+   * pattern in docs/concurrency.md and branch-registry.test.ts's `BlockingRegistry`.
    */
   async afterPrePassForTesting() {
   }
-  /**
-   * Delete an entry and remove it from the index.
-   */
+  /** Delete an entry and remove it from the index. */
   async delete(collectionPath, slug) {
     await this.idIndex();
     const collection = this.assertCollection(collectionPath);
@@ -3646,12 +3505,6 @@ var ContentStore = class {
   /**
    * Rename an entry by changing its slug (middle segment of filename).
    * Entry filename pattern: {entryTypeName}.{slug}.{id}.{ext}
-   *
-   * @param collectionPath - Logical path to the collection
-   * @param currentSlug - Current slug of the entry
-   * @param newSlug - New slug (must be unique within collection)
-   * @returns Object with new logical path
-   * @throws ContentStoreError if entry doesn't exist, new slug conflicts, or validation fails
    */
   async renameEntry(collectionPath, currentSlug, newSlug) {
     await this.idIndex();
@@ -3744,27 +3597,18 @@ var ContentStore = class {
       throw new ContentConflictError();
     });
   }
-  /**
-   * List all entries in a collection tree (including subcollections).
-   * For example, passing 'content/data-catalog' returns entries from
-   * 'content/data-catalog', 'content/data-catalog/partner-a', etc.
-   * Returns array of entry metadata (relativePath, collection, slug).
-   * Returns empty array if the collection doesn't exist.
-   */
   /**
    * Resolve a schema collection referenced by name or logical path.
    *
-   * Accepts either a full logical path ("content/authors") or a bare
-   * collection name ("authors") — the contract reference fields use for
-   * `collections: [...]` (see README). This is the single normalization
-   * point shared by reference-option loading and reference validation so
-   * the dropdown and the write boundary can never disagree.
+   * Accepts a full logical path ("content/authors") or a bare collection name ("authors") --
+   * the contract reference fields use for `collections: [...]` (see README). The single
+   * normalization point shared by reference-option loading and reference validation, so the
+   * dropdown and the write boundary can never disagree.
    *
-   * CAVEAT: the bare-name fallback matches on the LAST path segment and
-   * returns the first hit in schema order — with two collections sharing a
-   * leaf name (e.g. content/blog/posts and content/news/posts), a bare
-   * 'posts' is ambiguous. Use the full logical path in schemas that nest
-   * same-named collections.
+   * CAVEAT: the bare-name fallback matches on the LAST path segment and returns the first hit
+   * in schema order, so with two collections sharing a leaf name (content/blog/posts,
+   * content/news/posts) a bare 'posts' is ambiguous. Use the full logical path in schemas that
+   * nest same-named collections.
    */
   resolveCollectionItem(collectionPath) {
     const normalized = normalizeFilesystemPath(collectionPath);
@@ -3782,6 +3626,11 @@ var ContentStore = class {
     }
     return item && item.type === "collection" ? item : void 0;
   }
+  /**
+   * Every entry in a collection tree, including subcollections: 'content/data-catalog'
+   * returns entries from it and from 'content/data-catalog/partner-a' and so on. Empty when
+   * the collection does not exist.
+   */
   async getCollectionEntryPaths(collectionPath) {
     const idIndex = await this.idIndex();
     const collection = this.resolveCollectionItem(collectionPath);
@@ -3804,29 +3653,21 @@ var ContentStore = class {
   /**
    * 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`.
+   * 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. Pass one {@link ReferenceResolveCache} across a whole batch so
+   * a target referenced by many entries is read once; omit `cache` for exactly `read()`'s
+   * unmemoized behavior.
    *
-   * 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.
+   * **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 -- pre-existing `read()` behavior,
+   * matched here on purpose so one rule covers both.
    */
   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, cache) {
     const resolved = { ...data };
     const idIndex = await this.idIndex();
@@ -3872,43 +3713,28 @@ var ContentStore = class {
     return resolved;
   }
   /**
-   * 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.
+   * 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, so `read()` behaves 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.
+   * 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` 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`.
+   * The uncached path is NOT the clean baseline it looks like: 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. Pre-existing `read()` behavior, deliberately out of scope
+   * here; 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.
+   * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
+   * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
+   * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
+   * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
+   * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
+   * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
+   * cloned once per referencing entry.
    */
   resolveSingleReference(id, idIndex, includeBody, cache) {
     if (!cache)
@@ -3922,24 +3748,17 @@ var ContentStore = class {
     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.
+   * Returns null if the reference is invalid or missing. Includes id, slug and collection.
    *
-   * Suspicious results (ID missing from the index, or an index hit whose file
-   * is gone) trigger one forced index refresh and a retry — self-healing for
-   * mutations by other processes inside the marker's residual windows. The
-   * forced refresh itself is throttled (see refreshIndexForSuspiciousLookup),
-   * but the retry against the live index always runs regardless of whether
-   * this call won the throttle race: when a `list: true` reference array is
-   * resolved via Promise.all, every miss shares the same stale snapshot, and
-   * 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 suspicious result (ID missing from the index, or an index hit whose file is gone)
+   * triggers one forced index refresh and a retry — self-healing for mutations by other
+   * processes inside the marker's residual windows. The forced refresh is itself throttled
+   * (see refreshIndexForSuspiciousLookup) but the retry against the live index always runs:
+   * every miss in a `list: true` Promise.all shares one stale snapshot, and idIndex() dedupes
+   * concurrent builds, so a sibling that wins the throttle heals the whole batch.
    *
-   * 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.
+   * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every distinct id
+   * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
    */
   async resolveSingleReferenceUncached(id, idIndex, includeBody) {
     const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody);
@@ -4987,15 +4806,12 @@ var BranchRegistry = class {
     return await this.regenerate();
   }
   /**
-   * Returns a single branch by name. Uses cache if available.
+   * Returns a single branch by name, from the cached snapshot when it is fresh.
    *
-   * Suspicious-miss backstop: if `name` isn't in the (possibly cached) list,
-   * that's a signal the snapshot may be stale in the specific direction where
-   * a branch that now exists is missing from it - force one fresh
-   * regeneration and re-search before giving up, throttled per instance so a
-   * genuinely-absent branch costs at most one extra scan per throttle window.
-   * This bounds durable window-E staleness for the "branch exists but
-   * snapshot predates it" direction; see the class doc comment.
+   * Suspicious-miss backstop: a `name` missing from the list is the signal that
+   * the snapshot may predate a branch that now exists, so force one fresh
+   * regeneration and re-search before giving up. Throttled per instance, so a
+   * genuinely-absent branch costs at most one extra scan per window.
    */
   async get(name) {
     const branches = await this.list();
@@ -5015,14 +4831,11 @@ var BranchRegistry = class {
     return true;
   }
   /**
-   * Marks the cache as stale for every process sharing this root by bumping
-   * the cross-process generation marker, then eager-regenerates on this host
-   * (see class doc comment for why). The bump must succeed: a swallowed
-   * failure here would leave the registry stale indefinitely with no
-   * bounding backstop, unlike a failed eager regen below, which only forgoes
-   * closing window (E) early - the bump alone already restored correctness
-   * for every future reader. A failed eager regen therefore must not fail the
-   * caller's save/delete.
+   * Marks the cache stale for every process sharing this root by bumping the
+   * marker, then eager-regenerates on this host. The bump must succeed —
+   * swallowing that failure leaves the registry stale indefinitely with no
+   * backstop. A failed eager regen must NOT fail the caller's save/delete: the
+   * bump alone already restored correctness for every future reader.
    */
   async invalidate() {
     await bumpResourceGeneration(this.root, RESOURCE2, { mustSucceed: true });
@@ -5040,9 +4853,8 @@ var BranchRegistry = class {
   /**
    * Scans branch directories and rebuilds the cache, deduping concurrent
    * callers on this instance to a single underlying scan. Never loops waiting
-   * for the snapshot's embedded token to match the marker - under a bump
-   * storm that could livelock; a caller that wants the very latest state
-   * after a concurrent bump should call list() again after this resolves.
+   * for the embedded token to match the marker — that livelocks under a bump
+   * storm; a caller wanting the very latest state calls list() again.
    */
   async regenerate() {
     if (this.regenInFlight)
@@ -5261,16 +5073,13 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
     this.baseRoot = baseRoot;
     this.settleMs = options?.settleMs;
   }
-  /**
-   * Load branch metadata without requiring baseRoot.
-   * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
-   */
+  /** Read-only load, needing no baseRoot: registry scanning, loadBranchContext. */
   static async loadOnly(branchRoot) {
     return readBranchMetadataFile(branchRoot);
   }
   /**
-   * Get a BranchMetadataFileManager instance configured for registry invalidation.
-   * Use this in API handlers to ensure registry cache is invalidated on updates.
+   * An instance wired for registry invalidation. API handlers use this, so the
+   * registry cache is invalidated on update.
    */
   static get(branchRoot, baseRoot, options) {
     return new _BranchMetadataFileManager(branchRoot, baseRoot, options);
@@ -5289,18 +5098,16 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
     }
   }
   /**
-   * Write branch.json via the shared OCC helper, with the schemaVersion
-   * default applied here (payload shaping stays branch-metadata's concern).
+   * Write branch.json via the shared OCC helper, applying the schemaVersion
+   * default here since payload shaping is branch-metadata's concern.
    *
-   * Throws the helper's raw {@link OccWriteConflictError} so the surrounding
-   * {@link withOccRetry} in save() recognizes and retries it; translation to
-   * the public `BranchMetadataConflictError` contract happens at the save()
-   * boundary, after retries are exhausted (translating earlier would make
-   * withOccRetry's default predicate miss it, since it only recognizes the
-   * raw error type).
+   * Throws the helper's raw {@link OccWriteConflictError}, which is what the
+   * surrounding {@link withOccRetry} in save() recognizes and retries;
+   * translating to the public `BranchMetadataConflictError` earlier than the
+   * save() boundary would make withOccRetry's predicate miss it.
    *
-   * branch-metadata historically writes WITH a trailing newline, unlike
-   * comment-store; `trailingNewline: true` preserves that.
+   * branch.json is written WITH a trailing newline (`trailingNewline: true`),
+   * unlike comments.json.
    */
   async write(meta, expectedVersion) {
     const payload = {
@@ -5314,28 +5121,22 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
     });
   }
   /**
-   * Run a save cycle under the full lock + OCC-retry stack described in the
-   * class doc comment. A conflict that survives every retry surfaces as the
-   * public `BranchMetadataConflictError`.
+   * Run a save cycle under the full lock + OCC-retry stack (class doc). A
+   * conflict surviving every retry surfaces as `BranchMetadataConflictError`.
    *
-   * Guards against a phantom-resurrection race with branch deletion: a
-   * caller's branchContext can be resolved BEFORE a concurrent
-   * deleteBranchHandler removes the branch directory, but this save() call
-   * only reaches here (and its own mkdir({recursive:true}) inside write())
-   * AFTER the removal. Without this check, that mkdir would silently
-   * recreate `.canopy-meta/` (and this save would recreate branch.json from
-   * defaults) inside a directory tree that no longer exists anywhere else --
-   * a registry entry with no clone behind it. Checking BEFORE the lock stack
-   * (rather than after) fails fast without paying for a lock acquisition on
-   * a doomed save.
+   * The stat guards a phantom-resurrection race with branch deletion: a
+   * caller's branchContext can resolve BEFORE a concurrent deleteBranchHandler
+   * removes the branch directory, while the save reaches here after it, and
+   * write()'s `mkdir({recursive:true})` would then recreate `.canopy-meta/` and
+   * branch.json from defaults inside a tree nothing else refers to — a registry
+   * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
+   * save fails fast instead of paying for a lock.
    *
-   * Residual window (accepted): a save that passes this check can still
-   * race a `rm` that starts moments later and is still mid-flight when this
-   * save's write lands, resurrecting the tree. Closing that fully would
-   * need a tombstone OUTSIDE the tree being removed -- the lockfile
-   * (`withOccFileLock`) this save takes next lives INSIDE `branchRoot`, so
-   * it cannot itself provide a wider guarantee than "the directory existed
-   * a moment ago."
+   * Accepted residual window: a save that passes the check can still race a
+   * `rm` that starts moments later and is mid-flight when the write lands.
+   * Closing that needs a tombstone OUTSIDE the tree being removed, and the
+   * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
+   * than "the directory existed a moment ago".
    */
   async save(incoming) {
     try {
@@ -5375,9 +5176,9 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
             createdAt: existing?.branch.createdAt ?? defaults.createdAt,
             // Fork point is recorded once at creation; later saves must not move it
             baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
-            // Always stamped fresh — the spreads above would otherwise let
-            // the existing (creation-time) value win forever, freezing the
-            // timestamp the editor's Branches panel sorts and displays by
+            // Always stamped fresh; the spreads above would otherwise let
+            // the creation-time value win forever, freezing the timestamp
+            // the editor's Branches panel sorts and displays by
             updatedAt: now
           }
         };
@@ -5395,9 +5196,7 @@ var BranchMetadataFileManager = class _BranchMetadataFileManager {
     await this.invalidateRegistry();
     return saved;
   }
-  /**
-   * Invalidates the registry cache so next list() call regenerates from branch.json files.
-   */
+  /** Invalidate the registry cache so the next list() regenerates. */
   async invalidateRegistry() {
     const registry2 = new BranchRegistry(this.baseRoot);
     await registry2.invalidate();
@@ -5543,17 +5342,11 @@ var GitManager = class _GitManager {
     log5.debug("git", "Clone complete");
   }
   /**
-   * Initializes a local bare git repository to simulate a remote for dev mode.
-   *
-   * This is idempotent - if the remote already exists, it will not be recreated.
-   *
-   * The remote is seeded with the current state of the baseBranch (e.g., 'main').
-   * When the remote already exists but is missing the requested baseBranch
-   * (dev-mode branch auto-detect makes this routine: any git branch created
-   * after the remote was first seeded), that branch is pushed from the source
-   * repo on demand. Branches that already exist in the remote are never
-   * updated here — the CMS pushes editor state into this remote, and a
-   * refresh from the source repo would clobber it.
+   * Initializes a local bare git repository to simulate a remote for dev mode,
+   * seeded with the current state of baseBranch. Idempotent: an existing remote
+   * is never recreated, and a branch already in it is never refreshed from the
+   * source repo — the CMS pushes editor state into this remote, so a refresh
+   * would clobber it. A baseBranch the remote lacks is pushed on demand.
    *
    * @throws Error if not a git repo, no commits, or baseBranch doesn't exist
    */
@@ -5654,39 +5447,28 @@ var GitManager = class _GitManager {
    * EITHER the local-heads namespace (`refs/heads/<branch>`) or the GitHub
    * tracking namespace (`GITHUB_TRACKING_REF_PREFIX<branch>`).
    *
-   * Originally checked `refs/heads/*` only, for dev-mode's
-   * `ensureLocalSimulatedRemote` (a simulated remote never gets a tracking
-   * namespace, so that caller only ever needed the local-heads check).
-   * Generalized/promoted to public for api/branch.ts's create-time collision
-   * guard, which also needs the tracking namespace: `syncGit()` fetches
-   * GitHub into `GITHUB_TRACKING_REF_PREFIX*` rather than `refs/heads/*`
-   * directly (see that constant's doc comment above), and
-   * `reconcileTrackedBranches()` (worker/git-sync.ts) only
-   * non-destructively brings `refs/heads/*` toward what's tracked there — so
-   * a branch that another CanopyCMS deployment sharing this repo (or a
-   * direct push to GitHub) just created can sit in the tracking namespace
-   * for a while before, or without ever, gaining a local head here. Checking
-   * `refs/heads/*` alone would miss exactly the two-deployments-one-repo
-   * collision that guard exists to catch.
+   * Both namespaces matter to api/branch.ts's create-time collision guard: a
+   * branch another CanopyCMS deployment sharing this repo (or a direct push to
+   * GitHub) just created sits in the tracking namespace before, or without
+   * ever, gaining a local head here (see GITHUB_TRACKING_REF_PREFIX above), so
+   * checking `refs/heads/*` alone would miss exactly the
+   * two-deployments-one-repo collision that guard exists to catch.
    *
    * Runs git with an explicit `--git-dir` instead of a cwd inside the repo:
    * environments with `safe.bareRepository=explicit` (sandboxed/CI git setups)
    * refuse cwd-based discovery of bare repos but expressly allow `--git-dir`.
-   * A single `for-each-ref` call checks both candidate refs at once (no
-   * exception-based control flow — `for-each-ref` exits 0 whether or not
-   * either ref exists, same reason the old implementation used `branch
-   * --list` instead of `rev-parse --verify --quiet`: simple-git only fails a
-   * task on stderr output, and `--quiet` suppresses exactly that).
-   * `--end-of-options` guards the ref-name positionals the same way
-   * `push` below does, since `branch` here can be a sanitized but otherwise
-   * caller-influenced string.
+   * A single `for-each-ref` call checks both candidate refs at once, without
+   * exception-based control flow — it exits 0 whether or not either ref
+   * exists, whereas `rev-parse --verify --quiet` suppresses the stderr output
+   * that is the only thing simple-git fails a task on. `--end-of-options`
+   * guards the ref-name positionals the same way `push` below does, since
+   * `branch` here is sanitized but otherwise caller-influenced.
    *
    * A failure here therefore means the remote itself is unreadable and is
    * surfaced, NOT treated as "branch absent" — that would route
    * `ensureLocalSimulatedRemote` to the push path against a repo it couldn't
    * even read, and would silently skip api/branch.ts's collision check
-   * instead of letting that caller distinguish "unreadable" from "absent"
-   * and decide what to do.
+   * instead of letting that caller distinguish "unreadable" from "absent".
    */
   static async bareRemoteHasBranch(remotePath, branch, options = {}) {
     let output;
@@ -5713,36 +5495,30 @@ var GitManager = class _GitManager {
    * Delete `refs/heads/<branch>` from a bare local mirror, if present. A
    * no-op (not an error) when the ref doesn't exist.
    *
-   * This is the "explicit path" for removing a deleted branch's local head
-   * that the sync loop deliberately is not (see GITHUB_TRACKING_REF_PREFIX's
-   * doc comment: reconcileTrackedBranches never deletes a head). Called by
-   * api/branch.ts's deleteBranchHandler: without it, a deleted branch's head
-   * lives in `remote.git` forever, and the ordinary create -> publish ->
-   * squash-merge -> delete -> reuse-the-name cycle then has the REUSED
-   * branch's first publish rejected non-fast-forward against the stale head
-   * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip
-   * is not an ancestor of the new branch) -- a permanent, misleading 409.
-   * Worse, a retried submit skips the local push (clean tree) and enqueues
-   * the worker push of the STALE head, resurrecting the deleted branch's
-   * content on GitHub as an apparent success.
+   * The explicit path for removing a deleted branch's local head, which the
+   * sync loop deliberately is not (reconcileTrackedBranches never deletes a
+   * head — see GITHUB_TRACKING_REF_PREFIX). Called by api/branch.ts's
+   * deleteBranchHandler: a head left in `remote.git` forever makes the
+   * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
+   * the reused branch's first publish non-fast-forward against the stale head
+   * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+   * not an ancestor of the new branch), and a retried submit then skips the
+   * local push on a clean tree and enqueues the worker push of the STALE head,
+   * resurrecting the deleted branch's content on GitHub as an apparent success.
    *
-   * Deliberately leaves the tracking ref (`GITHUB_TRACKING_REF_PREFIX<branch>`)
-   * alone: that namespace mirrors GitHub's view, and if the branch still
-   * exists on GitHub, the create-time collision check SHOULD keep reporting
-   * it until the remote side is actually gone.
+   * Leaves the tracking ref (`GITHUB_TRACKING_REF_PREFIX<branch>`) alone: that
+   * namespace mirrors GitHub's view, so while the branch still exists there the
+   * create-time collision check SHOULD keep reporting it.
    *
-   * Same `--git-dir` invocation style as bareRemoteHasBranch above (works
-   * under `safe.bareRepository=explicit`). The existence pre-check makes
-   * "absent" deterministic instead of parsing update-ref's locale-dependent
-   * failure text, and its captured SHA is passed to `update-ref -d` as the
-   * expected old value -- same pattern as reconcileTrackedBranches'
-   * guarded updates (worker/git-sync.ts): a concurrent Lambda push
-   * re-creating/moving this branch between the read and the delete makes
-   * update-ref throw (surfaced as the caller's best-effort warning) instead
-   * of silently deleting a commit that was just pushed. No
-   * `--end-of-options` on update-ref (older gits don't accept it there);
-   * the ref argument always begins with the literal `refs/heads/` prefix,
-   * so it can never parse as an option.
+   * Same `--git-dir` invocation style as bareRemoteHasBranch above (works under
+   * `safe.bareRepository=explicit`). The existence pre-check makes "absent"
+   * deterministic instead of parsing update-ref's locale-dependent failure
+   * text, and its captured SHA is passed to `update-ref -d` as the expected old
+   * value, so a concurrent push re-creating or moving this branch between the
+   * read and the delete makes update-ref throw instead of silently deleting a
+   * just-pushed commit. No `--end-of-options` on update-ref (older gits reject
+   * it there); the ref argument always begins with the literal `refs/heads/`
+   * prefix, so it can never parse as an option.
    */
   static async deleteBareRemoteHead(remotePath, branch) {
     const ref = `refs/heads/${branch}`;
@@ -5808,7 +5584,6 @@ var GitManager = class _GitManager {
     }
   }
   /**
-   * Find the git root directory
    * @returns Path to git root, or cwd if not in a git repo
    */
   static async findGitRoot() {
@@ -5822,8 +5597,6 @@ var GitManager = class _GitManager {
     return gitRoot;
   }
   /**
-   * Validate that a git repository exists at the given path
-   * @param repoPath - Path to check for .git directory
    * @throws Error if git repo doesn't exist
    */
   static async validateGitRepoExists(repoPath) {
@@ -5841,22 +5614,14 @@ var GitManager = class _GitManager {
   }
   /**
    * Guards prod mode against pointing git operations at a NETWORK remote
-   * (http(s)://, ssh://, git://, or scp-like `user@host:path`).
+   * (http(s)://, ssh://, git://, or scp-like `user@host:path`): the prod CMS
+   * Lambda has no internet access and would hang until timeout trying to
+   * clone/fetch/push one. Fires only for `mode === 'prod'`, and only for the
+   * three resolvable sources (explicit param, config, env var) — `file://`
+   * URLs, plain filesystem paths and `resolveRemoteUrl`'s auto-detect step
+   * (local by construction) are always allowed.
    *
-   * In the intended prod architecture the CMS Lambda has no internet access:
-   * all git network I/O happens on the EC2 worker against the EFS-local bare
-   * repo `{workspace}/remote.git`, which the Lambda reaches via auto-detect
-   * (see `resolveRemoteUrl`'s auto-detect step, which always yields a local
-   * path by construction — never checked here). A network URL supplied via
-   * any of the three resolvable sources (explicit param, config, env var) is
-   * almost always a misconfiguration: the internet-less Lambda would try to
-   * clone/fetch/push it directly and hang until timeout.
-   *
-   * Dev mode is never restricted here — this only fires for `mode === 'prod'`.
-   * `file://` URLs and plain filesystem paths are LOCAL and always allowed.
-   *
-   * @param source - Human-readable description of where `url` came from, used
-   *   only in the thrown error message (e.g. "config.defaultRemoteUrl").
+   * @param source - Where `url` came from, for the thrown error message only.
    */
   static assertRemoteUrlAllowedInMode(mode, url, source, allowNetworkRemoteInProd) {
     if (mode !== "prod")
@@ -5874,17 +5639,12 @@ var GitManager = class _GitManager {
    * 3. Environment variable (mode-specific)
    * 4. Auto-initialized local remote (for dev mode)
    *
-   * Uses strategy flags to determine behavior, GitManager executes the logic.
-   *
-   * In prod mode, a resolved network URL from any of the first three sources
-   * is rejected unless `options.allowNetworkRemoteInProd` is set — see
-   * `assertRemoteUrlAllowedInMode`. Auto-detect/auto-init (source 4) are never
-   * checked: they always yield a local filesystem path by construction.
-   *
-   * @param options.sourceRoot - Optional source directory for monorepos. When provided,
-   *   this directory (relative to git root) is used as the source for the simulated remote.
-   *   Defaults to process.cwd().
+   * In prod mode a resolved network URL from any of the first three sources is
+   * rejected unless `options.allowNetworkRemoteInProd` is set — see
+   * `assertRemoteUrlAllowedInMode`.
    *
+   * @param options.sourceRoot - Source directory for monorepos, relative to the
+   *   git root; the source for the simulated remote. Defaults to process.cwd().
    * @returns Remote URL or undefined if no remote is needed
    */
   static async resolveRemoteUrl(options) {
@@ -5936,14 +5696,12 @@ var GitManager = class _GitManager {
    *
    * Uses `rev-parse --git-dir` with `GIT_CEILING_DIRECTORIES` pinned to the
    * parent directory so a corrupt/missing `.git` can't make git silently
-   * traverse upward and report a false positive from an ancestor repo (the
-   * same protection `initializeWorkspace` relies on below).
+   * traverse upward and report a false positive from an ancestor repo.
    *
    * Shared by `initializeWorkspace` (clone-vs-reuse decision) and
    * `SettingsWorkspaceManager`'s rename guard (settings-workspace.ts), which
    * must know whether a settings workspace ALREADY exists before touching it —
-   * touching an existing orphan settings branch under a different name wipes
-   * permissions.json/groups.json (see that guard's doc comment).
+   * re-initializing one under a different name wipes permissions.json/groups.json.
    */
   static async repoExistsAt(workspacePath) {
     try {
@@ -5959,12 +5717,7 @@ var GitManager = class _GitManager {
    * Ensures a git workspace is initialized and ready for use.
    * Handles cloning, remote configuration, and branch checkout/creation.
    *
-   * This centralizes the common initialization sequence used by both BranchWorkspaceManager
-   * and SettingsWorkspaceManager.
-   *
    * Note: Does NOT configure git author - that should be done before commits, not during init.
-   *
-   * @returns Configured GitManager instance for the workspace
    */
   static async initializeWorkspace(options) {
     const baseBranch = await resolveBaseBranch({
@@ -6062,20 +5815,16 @@ var GitManager = class _GitManager {
   }
   /**
    * Mark ContentStore ID indexes AND the resolved-schema cache rooted at (or
-   * under) this repo as stale. Called after operations that mutate the
-   * working tree (checkout/merge/rebase) so ID→path lookups don't keep
-   * resolving to pre-mutation paths, and so a rebase/checkout that pulled in
-   * upstream `.collection.json` changes doesn't leave the schema cache
-   * pinned to the pre-mutation schema. Invoked in `finally` blocks because
-   * even failed merges/rebases may have touched the tree before aborting;
-   * over-invalidating is safe.
+   * under) this repo as stale, so ID→path lookups and `.collection.json`
+   * schemas don't stay pinned to the pre-mutation tree. Called in `finally`
+   * blocks around every working-tree mutation (checkout/merge/rebase) because
+   * even a failed merge may have touched the tree; over-invalidating is safe.
    *
-   * Covers both scopes: in-process stores/caches via their registries, and
-   * consumers in OTHER processes sharing the filesystem (worker vs Lambda on
-   * EFS) via the on-disk generation markers — unless this manager targets a
-   * settings workspace (skipIndexMarker), where only the free in-process
-   * content-index invalidation runs and NEITHER marker is bumped (settings
-   * workspaces have no schema cache of their own either).
+   * Covers in-process stores/caches via their registries and other processes
+   * sharing the filesystem (worker vs Lambda on EFS) via the on-disk generation
+   * markers — except on a settings workspace (skipIndexMarker), where only the
+   * free in-process content-index invalidation runs and NEITHER marker is
+   * bumped (such workspaces have no schema cache of their own either).
    */
   async invalidateContentIndexes() {
     if (this.skipIndexMarker) {
@@ -6224,27 +5973,21 @@ var GitManager = class _GitManager {
     ]);
   }
   /**
-   * Check whether the local branch has commits the remote mirror doesn't
-   * have -- i.e. whether push() would actually move the remote ref forward.
+   * Whether the local branch has commits the remote mirror doesn't -- i.e.
+   * whether push() would move the remote ref forward.
    *
-   * Exists so callers (submitBranch) can gate pushing on "is there anything
-   * new to send" rather than on "is the working tree dirty": committing
-   * cleans the tree, so a dirty-tree gate around commit+push skips the push
-   * entirely on a retry after a failed push, even though the just-created
-   * commit never reached the remote (see services.ts submitBranch).
+   * Callers (services.ts submitBranch) gate pushing on this rather than on "is
+   * the working tree dirty": committing cleans the tree, so a dirty-tree gate
+   * around commit+push skips the push entirely when retried after a failed
+   * push, even though the commit never reached the remote.
    *
-   * Workspaces are cloned `--single-branch`, so the remote-tracking ref for
-   * any branch other than the one cloned never exists locally -- same
-   * constraint pullBaseInner works around. This fetches the specific branch
-   * directly (bypassing the configured single-branch refspec, exactly like
-   * pullBaseInner) and pins the result to FETCH_HEAD's SHA immediately after
-   * the fetch that populated it, rather than trusting `<remote>/<branch>`:
-   * FETCH_HEAD is a shared mutable file that any other fetch in this clone
-   * can repoint before it's read.
+   * Fetches the specific branch directly and pins FETCH_HEAD's SHA immediately
+   * after, rather than trusting `<remote>/<branch>` -- the pullBaseInner
+   * constraint: single-branch clones have no remote-tracking ref for any other
+   * branch, and FETCH_HEAD is shared mutable state.
    *
-   * A branch that has never been pushed has no ref on the remote at all --
-   * `git fetch` then fails ("couldn't find remote ref"), which this treats
-   * as "ahead" (needs pushing) rather than an error.
+   * A branch never pushed has no ref on the remote, so `git fetch` fails
+   * ("couldn't find remote ref"); that counts as "ahead", not an error.
    */
   async hasUnpushedCommits(branch) {
     const target = branch ?? await this.git.revparse(["--abbrev-ref", "--end-of-options", "HEAD"]);
@@ -6293,51 +6036,31 @@ var GitManager = class _GitManager {
       await this.git.remote(["set-url", this.remote, remoteUrl]);
     }
   }
-  /**
-   * Check if working directory has uncommitted changes
-   */
   async hasUncommittedChanges() {
     const status = await this.status();
     return status.files.length > 0;
   }
-  /**
-   * Get list of uncommitted file paths
-   */
   async getUncommittedFiles() {
     const status = await this.status();
     return status.files.map((f) => f.path);
   }
-  /**
-   * Get remote URL for current repo
-   */
   async getRemoteUrl() {
     const remotes = await this.git.getRemotes(true);
     const remote = remotes.find((r) => r.name === this.remote);
     return remote?.refs.push || remote?.refs.fetch;
   }
   /**
-   * Add a pattern to .git/info/exclude to prevent it from being committed/pushed.
-   * This is used to exclude .canopy-meta/ from content branch workspaces.
-   *
-   * .git/info/exclude is a per-repository gitignore that never gets committed.
-   * Perfect for runtime metadata that should never leave the workspace.
-   *
-   * This is idempotent - if the pattern already exists, it won't be added again.
+   * Excludes `pattern` (e.g. `.canopy-meta/`) from this workspace's git, so it
+   * can never be committed or pushed. See {@link ensureGitExcludePattern}.
    */
   async ensureGitExclude(pattern) {
     await ensureGitExcludePattern(this.repoPath, pattern);
   }
   /**
-   * Create an orphan branch for settings (permissions/groups).
-   *
-   * Orphan branches have no shared history with other branches - they start fresh.
-   * This is perfect for deployment-specific settings that shouldn't pollute content history.
-   *
-   * The branch contains only settings files committed by explicit path
-   * (e.g. permissions.json, groups.json at the workspace root).
-   *
-   * @param branchName - Name of the orphan branch (e.g., 'canopycms-settings-prod')
-   * @param initialFiles - Files to commit to the new branch (e.g., { 'permissions.json': '{}', 'groups.json': '{}' })
+   * Create an orphan branch (no shared history) for settings, so
+   * deployment-specific settings never pollute content history. It holds only
+   * settings files committed by explicit path (permissions.json, groups.json at
+   * the workspace root).
    */
   async createOrphanSettingsBranch(branchName, initialFiles) {
     try {