canopycms 0.0.67 → 0.0.68-int.93

package/dist/cli/github-app-manifest.d.ts

@@ -24,9 +24,10 @@ export type PermissionSet = Readonly<Record<string, PermissionLevel>>;
  * - `metadata: read` — implied by any repository permission; declared so
  *   this object states the whole surface, not just the non-automatic part.
  * Nothing else: no `issues`, `administration`, `actions`, or organisation
- * permissions. No `workflows` either, though GitHub may refuse to push
- * rebased history touching `.github/workflows/` — see
- * .claude/future-tasks/worker-push-refused-when-base-changes-workflows.md.
+ * permissions. No `workflows` either: GitHub refuses only workflow content it
+ * does not already hold, so rebasing onto a base that changed a workflow is
+ * accepted. Content that is new to GitHub fails the push task with the file
+ * named (`throwIfWorkflowRefusal` in worker/task-runner.ts).
  */
 export declare const CANOPY_APP_PERMISSIONS: PermissionSet;
 /**

package/dist/cli/github-app-manifest.js

@@ -22,9 +22,10 @@ const PERMISSION_LEVELS = ['read', 'write', 'admin'];
  * - `metadata: read` — implied by any repository permission; declared so
  *   this object states the whole surface, not just the non-automatic part.
  * Nothing else: no `issues`, `administration`, `actions`, or organisation
- * permissions. No `workflows` either, though GitHub may refuse to push
- * rebased history touching `.github/workflows/` — see
- * .claude/future-tasks/worker-push-refused-when-base-changes-workflows.md.
+ * permissions. No `workflows` either: GitHub refuses only workflow content it
+ * does not already hold, so rebasing onto a base that changed a workflow is
+ * accepted. Content that is new to GitHub fails the push task with the file
+ * named (`throwIfWorkflowRefusal` in worker/task-runner.ts).
  */
 export const CANOPY_APP_PERMISSIONS = {
     contents: 'write',

package/dist/cli/init.js

@@ -115,7 +115,8 @@ var init_field = __esm({
     });
     objectFieldSchema = fieldBaseSchema.extend({
       type: z.literal("object"),
-      fields: z.array(z.lazy(() => fieldHolder[0])).min(1)
+      fields: z.array(z.lazy(() => fieldHolder[0])).min(1),
+      itemTitleField: z.string().min(1).optional()
     });
     inlineGroupFieldSchema = z.object({
       type: z.literal("group"),
@@ -357,6 +358,9 @@ var init_config = __esm({
       defaultRemoteUrl: defaultRemoteUrlSchema.optional(),
       gitBotAuthorName: gitBotAuthorNameSchema,
       gitBotAuthorEmail: gitBotAuthorEmailSchema,
+      // Unset reads as on for Edited-by and off for Co-authored-by (services.ts submitBranch).
+      gitEditedByTrailers: z5.boolean().optional(),
+      gitCoAuthoredByTrailers: z5.boolean().optional(),
       githubTokenEnvVar: githubTokenEnvVarSchema.optional(),
       // Required by design (follow-up to SEC-C1): a prod deploy that omits `mode` must fail
       // validation loudly rather than silently running header-trusting dev auth semantics.
@@ -368,7 +372,6 @@ var init_config = __esm({
       // Default false/unset — the standard AWS Lambda+worker topology must leave this unset.
       allowNetworkRemoteInProd: z5.boolean().optional(),
       settingsBranch: z5.string().optional(),
-      autoCreateSettingsPR: z5.boolean().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`
@@ -889,6 +892,10 @@ var init_debug = __esm({
           throw new Error(errorMsg);
         }
       }
+      /**
+       * Keyed by label alone, so two overlapping timers with one label overwrite each other;
+       * anything that can run concurrently uses {@link timed}.
+       */
       time(label) {
         this.timers.set(label, Date.now());
       }
@@ -903,12 +910,16 @@ var init_debug = __esm({
         this.debug(category, `${label} completed`, { durationMs: duration });
         return duration;
       }
+      /**
+       * Log `<label> completed {durationMs}` once `fn` settles. The start time is local to the
+       * call, so concurrent spans with the same label on one logger never overwrite each other.
+       */
       async timed(category, label, fn) {
-        this.time(label);
+        const start = Date.now();
         try {
           return await fn();
         } finally {
-          this.timeEnd(category, label);
+          this.debug(category, `${label} completed`, { durationMs: Date.now() - start });
         }
       }
     };
@@ -1525,9 +1536,6 @@ var ProdStrategy = class extends ProdClientSafeStrategy {
       throw new Error("gitBotAuthorName and gitBotAuthorEmail are required in prod mode");
     }
   }
-  shouldCreateSettingsPR(config) {
-    return config.autoCreateSettingsPR ?? true;
-  }
 };
 var DevStrategy = class extends DevClientSafeStrategy {
   getWorkspaceRoot(sourceRoot) {
@@ -1574,9 +1582,6 @@ var DevStrategy = class extends DevClientSafeStrategy {
   }
   validateConfig(_config) {
   }
-  shouldCreateSettingsPR(_config) {
-    return false;
-  }
 };
 var strategyCache = /* @__PURE__ */ new Map();
 function operatingStrategy(mode) {

package/dist/cli/sync.js

@@ -17,6 +17,7 @@ import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import * as p from '@clack/prompts';
 import { filePathExists } from '../utils/fs.js';
+import { isCanopyInternalPath, stageAllExceptCanopyState } from '../utils/git.js';
 import { assertWithinDir, copyDir, listFilesRecursive, pushContentToWorkspace, safeReplaceDir, SYNC_BASE_TAG, } from '../sync-core.js';
 import { invalidateBranchContentCaches } from '../content-index-generation.js';
 import { ensureGitExcludePattern } from '../git-manager.js';
@@ -149,13 +150,14 @@ async function syncPush(options) {
         }
         return { fileCount: 0 };
     }
-    if (status.files.length > 0 && !options.force) {
-        p.log.warn(`Branch workspace has ${status.files.length} uncommitted change(s) that will be committed to history then overwritten:`);
-        for (const file of status.files.slice(0, 10)) {
+    const editorChanges = status.files.filter((f) => !isCanopyInternalPath(f.path));
+    if (editorChanges.length > 0 && !options.force) {
+        p.log.warn(`Branch workspace has ${editorChanges.length} uncommitted change(s) that will be committed to history then overwritten:`);
+        for (const file of editorChanges.slice(0, 10)) {
             p.log.warn(`  ${file.path}`);
         }
-        if (status.files.length > 10) {
-            p.log.warn(`  ... and ${status.files.length - 10} more`);
+        if (editorChanges.length > 10) {
+            p.log.warn(`  ... and ${editorChanges.length - 10} more`);
         }
         const confirm = await p.confirm({
             message: 'Continue? Editor changes will be preserved in git history.',
@@ -167,8 +169,8 @@ async function syncPush(options) {
         }
     }
     // Auto-commit uncommitted workspace changes to preserve in history
-    if (status.files.length > 0) {
-        await wsGit.add('-A');
+    if (editorChanges.length > 0) {
+        await stageAllExceptCanopyState(wsGit);
         await wsGit.commit('sync: save editor state before push');
         p.log.info('Committed editor changes to history before push');
     }
@@ -329,8 +331,8 @@ async function syncBoth(options) {
         return { pushed: 0, pulled: 0 };
     }
     // Auto-commit uncommitted workspace changes (preserves editor work for the merge)
-    if (status.files.length > 0) {
-        await wsGit.add('-A');
+    if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
+        await stageAllExceptCanopyState(wsGit);
         await wsGit.commit('sync: save editor state before merge');
         p.log.info('Committed editor changes before merge');
     }
@@ -365,9 +367,9 @@ async function syncBoth(options) {
             await wsGit.raw(['branch', '-D', incomingBranch]).catch(() => { });
             throw err;
         }
-        await wsGit.add('-A');
-        const incomingStatus = await wsGit.status();
-        if (incomingStatus.files.length === 0) {
+        await stageAllExceptCanopyState(wsGit);
+        const incomingFiles = (await wsGit.status()).files.filter((f) => !isCanopyInternalPath(f.path));
+        if (incomingFiles.length === 0) {
             await wsGit.checkout(currentBranch);
             await wsGit.raw(['branch', '-D', incomingBranch]);
             p.log.info('No working-tree changes to merge — pulling editor changes only');
@@ -410,7 +412,7 @@ async function syncBoth(options) {
         await wsGit.tag(['-f', SYNC_BASE_TAG]);
         p.log.success('Merged working-tree changes with editor changes');
         const pullResult = await syncPull({ ...options, branch: branchName, force: true });
-        return { pushed: incomingStatus.files.length, pulled: pullResult.fileCount };
+        return { pushed: incomingFiles.length, pulled: pullResult.fileCount };
     }
     finally {
         await invalidateBranchContentCaches(branchPath);

package/dist/config/schemas/config.d.ts

@@ -69,12 +69,13 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     defaultRemoteUrl: z.ZodOptional<z.ZodString>;
     gitBotAuthorName: z.ZodString;
     gitBotAuthorEmail: z.ZodString;
+    gitEditedByTrailers: z.ZodOptional<z.ZodBoolean>;
+    gitCoAuthoredByTrailers: z.ZodOptional<z.ZodBoolean>;
     githubTokenEnvVar: z.ZodOptional<z.ZodDefault<z.ZodString>>;
     mode: z.ZodEnum<["prod", "dev"]>;
     deployedAs: z.ZodDefault<z.ZodEnum<["static", "server"]>>;
     allowNetworkRemoteInProd: z.ZodOptional<z.ZodBoolean>;
     settingsBranch: z.ZodOptional<z.ZodString>;
-    autoCreateSettingsPR: z.ZodOptional<z.ZodBoolean>;
     deploymentName: z.ZodOptional<z.ZodDefault<z.ZodString>>;
     contentRoot: z.ZodDefault<z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>>>;
     sourceRoot: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -152,9 +153,10 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     defaultActiveBranch?: string | undefined;
     defaultRemoteName?: string | undefined;
     defaultRemoteUrl?: string | undefined;
+    gitEditedByTrailers?: boolean | undefined;
+    gitCoAuthoredByTrailers?: boolean | undefined;
     githubTokenEnvVar?: string | undefined;
     allowNetworkRemoteInProd?: boolean | undefined;
-    autoCreateSettingsPR?: boolean | undefined;
     deploymentName?: string | undefined;
     sourceRoot?: string | undefined;
     basePath?: string | undefined;
@@ -204,10 +206,11 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     defaultActiveBranch?: string | undefined;
     defaultRemoteName?: string | undefined;
     defaultRemoteUrl?: string | undefined;
+    gitEditedByTrailers?: boolean | undefined;
+    gitCoAuthoredByTrailers?: boolean | undefined;
     githubTokenEnvVar?: string | undefined;
     deployedAs?: "static" | "server" | undefined;
     allowNetworkRemoteInProd?: boolean | undefined;
-    autoCreateSettingsPR?: boolean | undefined;
     deploymentName?: string | undefined;
     contentRoot?: string | undefined;
     sourceRoot?: string | undefined;

package/dist/config/schemas/config.js

@@ -79,6 +79,9 @@ export const CanopyConfigSchema = z
     defaultRemoteUrl: defaultRemoteUrlSchema.optional(),
     gitBotAuthorName: gitBotAuthorNameSchema,
     gitBotAuthorEmail: gitBotAuthorEmailSchema,
+    // Unset reads as on for Edited-by and off for Co-authored-by (services.ts submitBranch).
+    gitEditedByTrailers: z.boolean().optional(),
+    gitCoAuthoredByTrailers: z.boolean().optional(),
     githubTokenEnvVar: githubTokenEnvVarSchema.optional(),
     // Required by design (follow-up to SEC-C1): a prod deploy that omits `mode` must fail
     // validation loudly rather than silently running header-trusting dev auth semantics.
@@ -89,7 +92,6 @@ export const CanopyConfigSchema = z
     // Default false/unset — the standard AWS Lambda+worker topology must leave this unset.
     allowNetworkRemoteInProd: z.boolean().optional(),
     settingsBranch: z.string().optional(),
-    autoCreateSettingsPR: z.boolean().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`

package/dist/config/schemas/field.js

@@ -81,6 +81,7 @@ const blockFieldSchema = fieldBaseSchema.extend({
 const objectFieldSchema = fieldBaseSchema.extend({
     type: z.literal('object'),
     fields: z.array(z.lazy(() => fieldHolder[0])).min(1),
+    itemTitleField: z.string().min(1).optional(),
 });
 // Inline group field: visual grouping only, no data nesting
 const inlineGroupFieldSchema = z.object({

package/dist/config/types.d.ts

@@ -132,6 +132,11 @@ export interface BlockFieldConfig extends BaseFieldConfig {
 export interface ObjectFieldConfig extends BaseFieldConfig {
     type: 'object';
     fields: FieldConfig[];
+    /**
+     * On a `list: true` object, a direct `string` or `number` child whose value titles each
+     * item's card; a blank or non-finite value falls back to "<label> #N".
+     */
+    itemTitleField?: string;
 }
 /**
  * Inline group field config: visually groups fields in the editor without creating
@@ -346,6 +351,8 @@ export interface CanopyConfig {
     defaultRemoteUrl?: DefaultRemoteUrl;
     gitBotAuthorName: GitBotAuthorName;
     gitBotAuthorEmail: GitBotAuthorEmail;
+    gitEditedByTrailers?: boolean;
+    gitCoAuthoredByTrailers?: boolean;
     githubTokenEnvVar?: GithubTokenEnvVar;
     mode: CanopyOperatingMode;
     /** How this build is deployed — see {@link CanopyConfigInput.deployedAs}. */
@@ -353,7 +360,6 @@ export interface CanopyConfig {
     /** Escape hatch for a prod host with real internet access — see {@link CanopyConfigInput.allowNetworkRemoteInProd}. */
     allowNetworkRemoteInProd?: boolean;
     settingsBranch?: string;
-    autoCreateSettingsPR?: boolean;
     deploymentName?: string;
     contentRoot: ContentRoot;
     sourceRoot?: SourceRoot;
@@ -382,6 +388,10 @@ export interface CanopyConfigInput {
     defaultRemoteUrl?: string;
     gitBotAuthorName: string;
     gitBotAuthorEmail: string;
+    /** Add `Edited-by: Name (user id)` for the submitter to submit commits. Default true. */
+    gitEditedByTrailers?: boolean;
+    /** Also add `Co-authored-by: Name <email>`. Default false: emails in public history are public. */
+    gitCoAuthoredByTrailers?: boolean;
     githubTokenEnvVar?: string;
     /**
      * Operating mode: 'prod' or 'dev'. Required — no default (SEC-C1). A prod deploy that
@@ -402,7 +412,6 @@ export interface CanopyConfigInput {
      */
     allowNetworkRemoteInProd?: boolean;
     settingsBranch?: string;
-    autoCreateSettingsPR?: boolean;
     deploymentName?: string;
     contentRoot?: string;
     sourceRoot?: string;

package/dist/config/validation.d.ts

@@ -25,6 +25,12 @@ export declare const ensureReferenceFieldsHaveScope: (fields: unknown) => void;
  * can run at config-validation and schema-load time, before any entry exists.
  */
 export declare const forEachReferenceField: (fields: unknown, visit: (field: Record<string, unknown>) => void) => void;
+/**
+ * Check that every `itemTitleField` sits on a `list: true` object and names a direct child
+ * of type `string` or `number`, the only values the card heading shows as typed (a reference
+ * would show its raw id, a select its stored value). Throws an error when it does not.
+ */
+export declare const ensureItemTitleFieldsExist: (fields: unknown) => void;
 /**
  * Validate that inline groups don't cause field name collisions within the same scope.
  * Because inline groups flatten their children into the parent scope, a field name used

package/dist/config/validation.js

@@ -77,6 +77,43 @@ export const forEachReferenceField = (fields, visit) => {
         }
     }
 };
+/**
+ * Check that every `itemTitleField` sits on a `list: true` object and names a direct child
+ * of type `string` or `number`, the only values the card heading shows as typed (a reference
+ * would show its raw id, a select its stored value). Throws an error when it does not.
+ */
+export const ensureItemTitleFieldsExist = (fields) => {
+    if (!Array.isArray(fields))
+        return;
+    for (const field of fields) {
+        const f = field;
+        if (f?.type === 'object') {
+            const children = Array.isArray(f.fields) ? f.fields : [];
+            if (f.itemTitleField !== undefined) {
+                const label = `Object field "${f.name ?? 'unknown'}" has itemTitleField "${String(f.itemTitleField)}"`;
+                if (f.list !== true) {
+                    throw new Error(`${label}, but itemTitleField applies only to list: true objects`);
+                }
+                const child = children.find((c) => c?.name === f.itemTitleField);
+                if (typeof f.itemTitleField !== 'string' || !child) {
+                    throw new Error(`${label}, which is not one of its child fields`);
+                }
+                if (child.type !== 'string' && child.type !== 'number') {
+                    throw new Error(`${label}, which must name a string or number field`);
+                }
+            }
+            ensureItemTitleFieldsExist(children);
+        }
+        else if (f?.type === 'group') {
+            ensureItemTitleFieldsExist(f.fields);
+        }
+        else if (f?.type === 'block' && Array.isArray(f.templates)) {
+            for (const template of f.templates) {
+                ensureItemTitleFieldsExist(template.fields);
+            }
+        }
+    }
+};
 /**
  * Validate that inline groups don't cause field name collisions within the same scope.
  * Because inline groups flatten their children into the parent scope, a field name used

package/dist/content-listing.d.ts

@@ -123,8 +123,8 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
  * unfiltered exactly as build-time callers want.
  */
 export interface ContentVisibilityOptions {
-    /** Return false to drop an entry. Receives the entry's branch-root-relative physical path. */
-    shouldInclude?: (physicalPath: PhysicalPath) => boolean;
+    /** Return false to drop an entry. Receives the entry's logical path (see `entryLogicalPath`). */
+    shouldInclude?: (logicalPath: LogicalPath) => boolean;
 }
 /** A collection node from the flattened schema. */
 export type CollectionSchemaItem = Extract<FlatSchemaItem, {

package/dist/content-listing.js

@@ -9,7 +9,7 @@ import { findBodyFieldName } from './utils/body-field.js';
 import { computeEntryUrl } from './utils/entry-url.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
 import { resolveCollectionPath } from './content-id-index.js';
-import { validateAndNormalizePath } from './paths/index.js';
+import { entryLogicalPath, validateAndNormalizePath } from './paths/index.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
@@ -139,7 +139,7 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
         : 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;
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
         // Resolve AFTER the visibility filter (a denied entry is never resolved, so its
         // references cost nothing and leak nothing) and BEFORE the mapping below, so
         // `extract` and `filter` both see resolved data — which is the entire point.
@@ -330,7 +330,7 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
             readEntryData(absolutePath, format, bodyField),
         ]);
         const item = {
-            logicalPath: `${collection.logicalPath}/${slug}`,
+            logicalPath: entryLogicalPath(collection.logicalPath, slug),
             contentId,
             slug,
             collectionPath: collection.logicalPath,

package/dist/content-reader.js

@@ -128,10 +128,10 @@ export const createContentReader = (options) => {
             throw new ContentStoreError(`Path is not a collection: ${entryPath}`, 'NO_SCHEMA_ITEM');
         }
         // Get the path WITHOUT reading the file
-        let relativePath;
+        let logicalPath;
         // Absolute filesystem path to the entry file. Surfaced on read() / readByUrlPath()
         // for server-side colocated-artifact reads (e.g. a sibling profile.json). Already
-        // computed here for permission checks; just carried through.
+        // computed here by path resolution; just carried through.
         let physicalPath;
         // Entry type + content ID come out of path resolution (buildPaths() derives both from the
         // schema item / filename), surfaced on read() / readByUrlPath() so callers can route or
@@ -140,7 +140,7 @@ export const createContentReader = (options) => {
         let entryId;
         try {
             const resolved = await store.resolveDocumentPath(entryPath, slug ?? '');
-            relativePath = resolved.relativePath;
+            logicalPath = resolved.logicalPath;
             physicalPath = resolved.absolutePath;
             // resolveDocumentPath() always sets entryTypeName for a valid schema item, so no
             // further fallback is needed here; `id` is the one field that can be legitimately
@@ -164,7 +164,7 @@ export const createContentReader = (options) => {
         // Check permissions BEFORE reading the file (security)
         const shouldCheckPermissions = !(isDeployedStatic(services.config) || isBuildMode());
         if (shouldCheckPermissions) {
-            const access = await services.checkContentAccess(context, branchRoot, relativePath, user, 'read');
+            const access = await services.checkContentAccess(context, branchRoot, logicalPath, user, 'read');
             if (!access.allowed) {
                 if (services.config.mode !== 'prod') {
                     const reasons = [];

package/dist/content-store.d.ts

@@ -347,6 +347,8 @@ export declare class ContentStore {
     resolveDocumentPath(schemaPath: LogicalPath, slug?: string): Promise<{
         absolutePath: string;
         relativePath: PhysicalPath;
+        /** The entry's logical path, the form path-permission rules match (`entryLogicalPath`). */
+        logicalPath: LogicalPath;
         id?: string;
         /**
          * Always populated for a valid schema item: the collection branch below resolves a name

package/dist/content-store.js

@@ -30,7 +30,7 @@ import { generateId } from './id.js';
 import { isNodeError } from './utils/error.js';
 import { filePathExists, readFileIfExists } from './utils/fs.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
-import { normalizeFilesystemPath, parseSlug, } from './paths/index.js';
+import { entryLogicalPath, normalizeFilesystemPath, parseSlug, } from './paths/index.js';
 /**
  * Acquire `keys` in canonical (sorted) order before running `fn`, ruling out AB-BA
  * deadlocks between callers with overlapping key sets. Only renameEntry() needs two
@@ -602,6 +602,7 @@ export class ContentStore {
             return {
                 absolutePath: resolved,
                 relativePath: path.relative(this.root, resolved),
+                logicalPath: entryLogicalPath(schemaItem.logicalPath, safeSlug),
                 id,
                 entryTypeName: finalEntryTypeName,
                 existed,

package/dist/content-tree.js

@@ -74,7 +74,7 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
         : null;
     const listVisibleEntries = async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection);
-        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+        const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
         // Resolved here rather than at the two node-building sites so BOTH inherit it — the same
         // reason the ACL filter lives here. A denied entry is filtered above and never resolved.
         return resolver ? resolveCollectionItemReferences(visible, collection, resolver) : visible;

package/dist/context.d.ts

@@ -58,8 +58,12 @@ export interface CanopyBuildContext {
      * `meta.indexEntry` handed to `extract`, and a collection whose children are
      * all filtered out is pruned. On the build context and on static deployments
      * nothing is filtered — the synthetic admin sees everything.
+     *
+     * Branch: the `branch` option behaves as on `listEntries`.
      */
-    buildContentTree: <T = unknown, TEntryTypes = DefaultEntryTypes>(options?: BuildContentTreeOptions<T, TEntryTypes>) => Promise<ContentTreeNode<T>[]>;
+    buildContentTree: <T = unknown, TEntryTypes = DefaultEntryTypes>(options?: BuildContentTreeOptions<T, TEntryTypes> & {
+        branch?: string;
+    }) => Promise<ContentTreeNode<T>[]>;
     /**
      * Every content entry as a flat array.
      *
@@ -67,13 +71,18 @@ export interface CanopyBuildContext {
      * cannot `read` are omitted before `extract` runs; on the build context and
      * static deployments nothing is filtered.
      *
-     * Branch: unlike `read`/`readByUrlPath` this takes no `branch` option, always
-     * listing `defaultActiveBranch ?? defaultBaseBranch ?? 'main'`. In `dev` that
-     * tracks git HEAD via `refreshActiveBranch()`; in `prod` the refresh is a
-     * no-op, so it always reads the base branch. See
-     * `.claude/future-tasks/context-listing-branch-pinning.md`.
+     * Branch: with no `branch` it lists the active branch
+     * (`defaultActiveBranch ?? defaultBaseBranch`): git HEAD in `dev` when that is
+     * unset, otherwise usually the base branch in `prod`. Pass the preview
+     * iframe's `?branch=` as `branch`, as for `read`, so an index page previewed
+     * on a content branch lists that branch. Any other branch must already exist
+     * and, on the request-scoped context, be readable by the user; otherwise, or
+     * for a non-string value, the result is empty. It selects nothing at build
+     * time or on static deployments.
      */
-    listEntries: <T = Record<string, unknown>>(options?: ListEntriesOptions<T>) => Promise<ListEntriesItem<T>[]>;
+    listEntries: <T = Record<string, unknown>>(options?: ListEntriesOptions<T> & {
+        branch?: string;
+    }) => Promise<ListEntriesItem<T>[]>;
     /**
      * Content reader, with the auth context applied automatically (admin at build
      * time).