canopycms 0.0.67-int.90 → 0.0.67

package/dist/content-tree.d.ts

@@ -1,55 +1,38 @@
 /**
- * Content tree builder for adopters.
+ * Content tree builder for adopters: walks the schema + filesystem and returns a tree of
+ * content nodes for navigation, sitemaps, search indexes, breadcrumbs.
  *
- * Walks the schema + filesystem and returns a tree of content nodes that
- * adopters can use for navigation, sitemaps, search indexes, breadcrumbs, etc.
- *
- * Nodes carry Canopy's structural facts (logicalPath, contentId, collection
- * metadata, entry metadata). Display concerns like labels are left to the
- * adopter via the `extract` callback.
+ * Nodes carry Canopy's structural facts (logicalPath, contentId, collection metadata, entry
+ * metadata); display concerns like labels are left to the adopter's `extract` callback.
  */
 import type { FlatSchemaItem, ContentFormat } from './config/index.js';
 /**
- * Adopter-supplied registry mapping entry type names (as they appear in
- * filenames: `partner.index.yaml` → `'partner'`) to their data shapes.
+ * Adopter-supplied registry mapping entry type names (as they appear in filenames:
+ * `partner.index.yaml` → `'partner'`) to their data shapes.
  *
- * Pair with `TypeFromEntrySchema<typeof yourSchema>` to derive shapes from
- * schemas you've already defined — no redeclaration needed.
+ * Pair with `TypeFromEntrySchema<typeof yourSchema>` to derive shapes from schemas you have
+ * already defined — no redeclaration needed.
  *
  * @example
  * ```ts
- * import { defineEntrySchema, type TypeFromEntrySchema } from 'canopycms'
- *
- * const partnerSchema = defineEntrySchema([
- *   { name: 'name', type: 'string', isTitle: true },
- *   { name: 'tagline', type: 'string' },
- * ])
- * const docSchema = defineEntrySchema([
- *   { name: 'title', type: 'string' },
- * ])
- *
+ * const partnerSchema = defineEntrySchema([{ name: 'name', type: 'string', isTitle: true }])
  * interface MyEntries {
  *   partner: TypeFromEntrySchema<typeof partnerSchema>
- *   doc: TypeFromEntrySchema<typeof docSchema>
  * }
  *
- * const canopy = await getCanopyForBuild()
  * await canopy.buildContentTree<NavFields, MyEntries>({
- *   extract: (data, meta) => {
- *     if (meta.kind === 'collection' && meta.indexEntry?.entryType === 'partner') {
- *       // meta.indexEntry.data is narrowed to PartnerContent
- *       return { name: meta.indexEntry.data.name }
- *     }
- *     return { name: '' }
- *   },
+ *   // meta.indexEntry.data is narrowed to the partner shape
+ *   extract: (data, meta) =>
+ *     meta.kind === 'collection' && meta.indexEntry?.entryType === 'partner'
+ *       ? { name: meta.indexEntry.data.name }
+ *       : { name: '' },
  * })
  * ```
  */
 export type EntryTypeMap = Record<string, object>;
 /**
- * Default TEntryTypes when an adopter hasn't supplied one.
- * The index signature preserves the loose shape — `meta.indexEntry.data`
- * stays `Record<string, unknown>`, useful for unstructured access without
+ * Default TEntryTypes when an adopter hasn't supplied one. The index signature keeps
+ * `meta.indexEntry.data` as `Record<string, unknown>`, useful for unstructured access without
  * opting in to the discriminated-union pattern. Exported so callers wrapping
  * `buildContentTree` (e.g. CanopyBuildContext) share the same default.
  */
@@ -68,15 +51,14 @@ export interface ContentTreeExtractMeta<TEntryTypes = DefaultEntryTypes> {
     /** Content format — present when kind is 'entry'. */
     format?: ContentFormat;
     /**
-     * The entry with slug 'index' inside a collection, when present.
-     * Represents the collection's "identity" under the directory-as-page pattern
-     * (e.g., a partner's metadata for /data-catalog/<partner>/, a section landing
-     * for /docs/<section>/). Only populated when kind === 'collection' AND the
-     * collection contains an entry with slug 'index'. Undefined for collections
-     * at the maxDepth cap (entries aren't loaded there).
+     * The entry with slug 'index' inside a collection, when present — the collection's
+     * "identity" under the directory-as-page pattern (a partner's metadata for
+     * /data-catalog/<partner>/, a section landing for /docs/<section>/). Populated only when
+     * kind === 'collection' AND such an entry exists; undefined for collections at the maxDepth
+     * cap, where entries are not loaded.
      *
-     * When TEntryTypes is supplied, this becomes a discriminated union: narrow
-     * on `indexEntry.entryType` and `data` is typed accordingly.
+     * With TEntryTypes supplied this is a discriminated union: narrow on `indexEntry.entryType`
+     * and `data` is typed accordingly.
      */
     indexEntry?: {
         [K in keyof TEntryTypes & string]: {
@@ -119,24 +101,18 @@ export interface BuildContentTreeOptions<T = unknown, TEntryTypes = DefaultEntry
     /** Starting collection path. Defaults to content root. */
     rootPath?: string;
     /**
-     * Extract typed custom fields from each node's raw data.
-     * For entries: data is frontmatter + body (md/mdx) or parsed JSON.
-     * For collections: data is `{ name, label }` from the schema.
-     *
-     * Supply TEntryTypes to get narrowed access to `meta.indexEntry.data`
-     * via discriminated-union narrowing on `meta.indexEntry.entryType`.
+     * Extract typed custom fields from each node's raw data. For entries, data is frontmatter +
+     * body (md/mdx) or the parsed object; for collections it is `{ name, label }` from the
+     * schema. Supply TEntryTypes for narrowed access to `meta.indexEntry.data`.
      *
-     * Note: extract should be a pure mapping. It may be invoked on entry nodes
-     * that `filter` later removes (the tree-walk extracts then filters), so any
-     * side effects (logging, counters, populating an external index) will see
-     * those rejected nodes too.
+     * Must be a pure mapping: it may be invoked on entry nodes that `filter` later removes (the
+     * tree-walk extracts, then filters), so side effects see those rejected nodes too.
      */
     extract?: (data: Record<string, unknown>, meta: ContentTreeExtractMeta<TEntryTypes>) => T;
     /**
-     * Filter: return false to exclude a node and its descendants.
-     * Runs after extract, so `fields` is available. Rejecting a collection
-     * short-circuits descendant traversal (no recursion into child collections
-     * or entry reads beneath the rejected node).
+     * Return false to exclude a node and its descendants. Runs after extract, so `fields` is
+     * available. Rejecting a collection short-circuits descendant traversal — no recursion into
+     * child collections, no entry reads beneath it.
      */
     filter?: (node: ContentTreeNode<T>) => boolean;
     /**
@@ -144,20 +120,11 @@ export interface BuildContentTreeOptions<T = unknown, TEntryTypes = DefaultEntry
      * with it. To extend rather than replace the default behavior, call the exported
      * `defaultBuildPath(logicalPath, contentRootName, kind)` from inside your
      * function and post-process its result (see `canopycms/server`).
-     *
-     * Default behavior (`defaultBuildPath`):
-     * - Strips the `{contentRootName}/` prefix from `logicalPath`.
-     * - For entries: collapses an `index` slug to its parent collection's path
-     *   (`content/guides/index` → `/guides`, not `/guides/index`); a collection
-     *   literally named `index` is unaffected (only entries collapse).
-     * - Lowercases the entire result.
-     * - Prepends `/`; the content root's own index collapses to `/`.
      */
     buildPath?: (logicalPath: LogicalPath, kind: 'collection' | 'entry') => string;
     /**
-     * Custom sort for children at each level.
-     * When provided, replaces the default sort (order array → alphabetical).
-     * Runs after extract + filter, so `fields` is available.
+     * Custom sort for children at each level; replaces the default (order array → alphabetical)
+     * entirely. Runs after extract + filter, so `fields` is available.
      */
     sort?: (a: ContentTreeNode<T>, b: ContentTreeNode<T>) => number;
     /** Max depth to traverse. Default: unlimited. */
@@ -167,34 +134,25 @@ export interface BuildContentTreeOptions<T = unknown, TEntryTypes = DefaultEntry
      * `read()`/`readByUrlPath()` do. Applies to both entry nodes and the `meta.indexEntry`
      * handed to a collection's `extract`. Off leaves them as the bare id string, or `null`.
      *
-     * Same flag, same default (`false`) and same reasoning as `listEntries`' option — see
-     * `ListEntriesOptions.resolveReferences` in content-listing.ts for why the default is
-     * opt-in rather than matching `read()`, what it costs, and why path ACLs are not applied
-     * to the resolved targets.
+     * Same flag, same default (`false`) and same reasoning as
+     * `ListEntriesOptions.resolveReferences` in content-listing.ts — see it for why the default
+     * is opt-in, what it costs, and why path ACLs are not applied to the resolved targets.
      */
     resolveReferences?: boolean;
 }
 /**
- * Default path builder: strips the content root prefix, lowercases, and prepends /.
- * All URL paths are lowercased unconditionally for consistency with slug normalization.
- * Adopters with case-sensitive slugs (e.g., "API-Reference") will get lowercased URLs.
- *
- * Index entries (slug 'index', any case) are collapsed to their parent collection path,
- * matching the URL convention used by readByUrlPath and listEntries.
+ * Default path builder: strips the content root prefix, collapses index entries, lowercases,
+ * prepends `/`. Lowercasing is unconditional, for consistency with slug normalization, so an
+ * adopter with case-sensitive slugs ("API-Reference") gets lowercased URLs. Index entries
+ * (slug 'index', any case) collapse to their parent collection path, matching the convention
+ * readByUrlPath and listEntries use.
  *
- * Exported (also re-exported from `canopycms/server`) so adopters who want to
- * EXTEND this behavior rather than replace it can call it from inside their own
- * `buildPath` and post-process the result, instead of reimplementing the
- * content-root-strip / index-collapse / lowercase logic verbatim.
+ * Exported (and re-exported from `canopycms/server`) so adopters who want to EXTEND this
+ * rather than replace it can call it from inside their own `buildPath` and post-process the
+ * result, instead of reimplementing strip / collapse / lowercase verbatim.
  */
 export declare const defaultBuildPath: (logicalPath: LogicalPath, contentRootName: string, kind: "collection" | "entry") => string;
 /**
  * Build a content tree from a flattened schema and the filesystem.
- *
- * @param branchRoot - Absolute path to the branch workspace root
- * @param flatSchema - Flattened schema items (from flattenSchema)
- * @param contentRootName - The content root name (e.g. "content")
- * @param options - Tree-building options
- * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export declare function buildContentTree<T = unknown, TEntryTypes = DefaultEntryTypes>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: BuildContentTreeOptions<T, TEntryTypes>, visibility?: ContentVisibilityOptions): Promise<ContentTreeNode<T>[]>;

package/dist/content-tree.js

@@ -1,18 +1,12 @@
 /**
- * Content tree builder for adopters.
+ * Content tree builder for adopters: walks the schema + filesystem and returns a tree of
+ * content nodes for navigation, sitemaps, search indexes, breadcrumbs.
  *
- * Walks the schema + filesystem and returns a tree of content nodes that
- * adopters can use for navigation, sitemaps, search indexes, breadcrumbs, etc.
- *
- * Nodes carry Canopy's structural facts (logicalPath, contentId, collection
- * metadata, entry metadata). Display concerns like labels are left to the
- * adopter via the `extract` callback.
+ * Nodes carry Canopy's structural facts (logicalPath, contentId, collection metadata, entry
+ * metadata); display concerns like labels are left to the adopter's `extract` callback.
  */
 import { isIndexSlug } from './utils/entry-url.js';
 import { createReferenceResolver, listCollectionEntries, resolveCollectionItemReferences, sortByOrder, } from './content-listing.js';
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
 /** Group flat schema items by parentPath for O(1) child lookup. */
 const groupByParent = (flat) => {
     const map = new Map();
@@ -27,28 +21,24 @@ const groupByParent = (flat) => {
     return map;
 };
 /**
- * Default path builder: strips the content root prefix, lowercases, and prepends /.
- * All URL paths are lowercased unconditionally for consistency with slug normalization.
- * Adopters with case-sensitive slugs (e.g., "API-Reference") will get lowercased URLs.
- *
- * Index entries (slug 'index', any case) are collapsed to their parent collection path,
- * matching the URL convention used by readByUrlPath and listEntries.
+ * Default path builder: strips the content root prefix, collapses index entries, lowercases,
+ * prepends `/`. Lowercasing is unconditional, for consistency with slug normalization, so an
+ * adopter with case-sensitive slugs ("API-Reference") gets lowercased URLs. Index entries
+ * (slug 'index', any case) collapse to their parent collection path, matching the convention
+ * readByUrlPath and listEntries use.
  *
- * Exported (also re-exported from `canopycms/server`) so adopters who want to
- * EXTEND this behavior rather than replace it can call it from inside their own
- * `buildPath` and post-process the result, instead of reimplementing the
- * content-root-strip / index-collapse / lowercase logic verbatim.
+ * Exported (and re-exported from `canopycms/server`) so adopters who want to EXTEND this
+ * rather than replace it can call it from inside their own `buildPath` and post-process the
+ * result, instead of reimplementing strip / collapse / lowercase verbatim.
  */
 export const defaultBuildPath = (logicalPath, contentRootName, kind) => {
     const prefix = contentRootName ? `${contentRootName}/` : '';
     const stripped = prefix && logicalPath.startsWith(prefix) ? logicalPath.slice(prefix.length) : logicalPath;
-    // Collapse index entries: content/guides/index → /guides (not /guides/index)
-    // Only for entries — a collection named "index" should keep its path.
-    //
-    // The index test runs on the LAST SEGMENT through the shared `isIndexSlug`, so it is
-    // case-insensitive and agrees with `computeEntryUrl`. A string `endsWith('/index')` test
-    // did not: for an adopter-supplied `content/docs/Index` this said `/docs/index` while
-    // `computeEntryUrl` said `/docs`, and `/docs/index` is the one that does NOT round-trip.
+    // Collapse index entries: content/guides/index → /guides. Entries only — a collection named
+    // "index" keeps its path. The test runs on the LAST SEGMENT through the shared
+    // `isIndexSlug`, so it is case-insensitive and agrees with `computeEntryUrl`; a string
+    // `endsWith('/index')` test disagreed for an adopter-supplied `content/docs/Index`, and
+    // `/docs/index` is the answer that does NOT round-trip.
     const lastSlash = stripped.lastIndexOf('/');
     const lastSegment = lastSlash === -1 ? stripped : stripped.slice(lastSlash + 1);
     const collapsed = kind === 'entry' && isIndexSlug(lastSegment)
@@ -59,17 +49,8 @@ export const defaultBuildPath = (logicalPath, contentRootName, kind) => {
     const urlPath = collapsed ? `/${collapsed}` : '/';
     return urlPath.toLowerCase();
 };
-// ---------------------------------------------------------------------------
-// Core builder
-// ---------------------------------------------------------------------------
 /**
  * Build a content tree from a flattened schema and the filesystem.
- *
- * @param branchRoot - Absolute path to the branch workspace root
- * @param flatSchema - Flattened schema items (from flattenSchema)
- * @param contentRootName - The content root name (e.g. "content")
- * @param options - Tree-building options
- * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export async function buildContentTree(branchRoot, flatSchema, contentRootName, options, visibility) {
     const childrenByParent = groupByParent(flatSchema);
@@ -98,7 +79,6 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
         // reason the ACL filter lives here. A denied entry is filtered above and never resolved.
         return resolver ? resolveCollectionItemReferences(visible, collection, resolver) : visible;
     };
-    // Find the starting collection(s)
     const rootPath = options?.rootPath ?? contentRootName;
     const rootCollection = flatSchema.find((item) => item.type === 'collection' && item.logicalPath === rootPath);
     if (!rootCollection)
@@ -131,20 +111,16 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
                 return null;
             return node;
         }
-        // Load this collection's entries first (needed for indexEntry detection).
-        // We deliberately do NOT parallelize the child-collection recursion here:
-        // if `filter` rejects this collection, returning early short-circuits all
-        // descendant I/O — preserving the pre-existing "filter prunes whole subtree"
-        // optimization that the directory-as-page reorder would otherwise lose.
+        // Load this collection's entries first (needed for indexEntry detection). The
+        // child-collection recursion deliberately does NOT run in parallel with it: if `filter`
+        // rejects this collection, returning early short-circuits all descendant I/O.
         const entries = await listVisibleEntries(collection);
-        // Surface the 'index' entry (when present) to extract via meta.
-        // 'index' is the same magic slug Canopy uses in defaultBuildPath to collapse
-        // /foo/index URLs to /foo/, keeping conventions consistent. If a collection
-        // contains multiple slug==='index' entries (only possible via hand-edited or
-        // merged content — the write path forbids it), the first by filename order
-        // wins.
-        // The cast bridges runtime string keys to the parametric discriminated union;
-        // the adopter narrows on `indexEntry.entryType` to get the typed `data`.
+        // Surface the 'index' entry (when present) to extract via meta. 'index' is the same magic
+        // slug defaultBuildPath collapses /foo/index to /foo with. If a collection contains
+        // several slug==='index' entries (only reachable via hand-edited or merged content -- the
+        // write path forbids it), the first by filename order wins. The cast bridges runtime
+        // string keys to the parametric discriminated union; the adopter narrows on
+        // `indexEntry.entryType` to get the typed `data`.
         const idx = entries.find((e) => e.slug === 'index');
         const indexEntry = (idx ? { entryType: idx.entryType, format: idx.format, data: idx.data } : undefined);
         if (extract) {
@@ -156,10 +132,8 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
         }
         if (filter && !filter(node))
             return null;
-        // Now recurse into child collections (after filter has had a chance to prune)
         const childCollections = childrenByParent.get(collection.logicalPath) ?? [];
         const childCollectionNodes = await Promise.all(childCollections.map((child) => buildNode(child, depth + 1)));
-        // Build entry nodes
         const entryNodes = [];
         for (const entry of entries) {
             const entryNode = buildEntryNode(entry, buildPath, extract);
@@ -167,7 +141,6 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
                 continue;
             entryNodes.push(entryNode);
         }
-        // Combine and interleave by order array (or custom sort)
         const allChildren = interleaveChildren(childCollectionNodes.filter((n) => n !== null), entryNodes, collection.order, customSort);
         // Prune empty collections (no children after filtering)
         if (allChildren.length === 0)
@@ -177,7 +150,6 @@ export async function buildContentTree(branchRoot, flatSchema, contentRootName,
     };
     // Start from root's children (don't include the root collection itself)
     const topLevelCollections = childrenByParent.get(rootCollection.logicalPath) ?? [];
-    // Also get entries directly in the root collection
     const [collectionNodes, rootEntries] = await Promise.all([
         Promise.all(topLevelCollections.map((child) => buildNode(child, 1))),
         listVisibleEntries(rootCollection),

package/dist/context.d.ts

@@ -7,13 +7,13 @@
  * layer where authorization is applied, so a read that bypasses it bypasses
  * path ACLs.
  *
- * PHASE-AWARE: at build time (`isBuildMode`) or for a static deployment
- * (`isDeployedStatic`) it authorizes as `STATIC_DEPLOY_USER` instead of a real
- * user (WHO), and it reads the working tree at `process.cwd()` instead of a
- * branch workspace (WHERE: `readsFromCheckout`, applied inside
+ * PHASE-AWARE: at build time (`isBuildMode`) or on a static deployment
+ * (`isDeployedStatic`) it authorizes as `STATIC_DEPLOY_USER` rather than a real
+ * user (WHO) and reads the working tree at `process.cwd()` rather than a branch
+ * workspace (WHERE: `readsFromCheckout`, applied inside
  * `loadOrCreateBranchContext`), so a `branch` passed to a read selects nothing.
- * Only request-time reads on a server deployment resolve a branch workspace --
- * in dev mode, the clone under `.canopy-dev/content-branches/`.
+ * Only request-time reads on a server deployment resolve a branch workspace —
+ * in dev, the clone under `.canopy-dev/content-branches/`.
  *
  * The Next.js adapter wraps this in React `cache()` for per-request memoization
  * (`canopycms-next/src/context-wrapper.ts`).
@@ -28,60 +28,60 @@ import { type ListEntriesOptions, type ListEntriesItem } from './content-listing
 export interface CanopyContextOptions {
     services: CanopyServices;
     /**
-     * Extract the current user from framework-specific context.
-     * Should call authResultToCanopyUser() to apply bootstrap admin groups.
-     *
-     * Framework adapters provide this (e.g., from Next.js headers, Express req, etc.)
+     * Extract the current user from framework-specific context — supplied by the
+     * framework adapter, and must call authResultToCanopyUser() so bootstrap
+     * admin groups are applied.
      */
     extractUser: () => Promise<CanopyUser>;
 }
 /**
- * Build-time context.
- *
- * Obtained via getCanopyForBuild(); reads the filesystem directly as a synthetic admin
- * (STATIC_DEPLOY_USER) and bypasses all branch/path ACLs. Safe for static generation
- * (generateStaticParams, sitemap, build-time page rendering); it must NOT be used to serve
- * content at request time on a production `server` deployment. (Framework adapters throw on the
- * read helpers there; `services` remains a raw, unguarded escape hatch.) For request-scoped,
- * ACL-enforced access use getCanopy() (CanopyContext) instead.
+ * Build-time context, from getCanopyForBuild(): reads the filesystem directly
+ * as a synthetic admin (STATIC_DEPLOY_USER), bypassing all branch and path
+ * ACLs. Use it for static generation — generateStaticParams, sitemap,
+ * build-time page rendering — and never to serve content at request time on a
+ * production `server` deployment; request-time, ACL-enforced access is
+ * getCanopy() (CanopyContext). Framework adapters throw on the read helpers
+ * there, though `services` stays a raw, unguarded escape hatch.
  *
- * Includes read/readByUrlPath so build-time code can resolve a single entry by path/URL without
- * scanning the whole collection.
+ * It carries read/readByUrlPath so build-time code can resolve a single entry
+ * by path or URL without scanning the whole collection.
  */
 export interface CanopyBuildContext {
     /**
-     * Build a content tree from the schema and filesystem entries.
+     * Build a content tree from the schema and filesystem entries. Supply
+     * TEntryTypes (entry type name → data shape, typically via
+     * `TypeFromEntrySchema<typeof yourSchema>`) for narrowed access to
+     * `meta.indexEntry.data` inside `extract`.
      *
-     * Supply TEntryTypes (a map of entry type name → data shape, typically
-     * derived via `TypeFromEntrySchema<typeof yourSchema>`) to get narrowed
-     * access to `meta.indexEntry.data` inside the `extract` callback.
-     *
-     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the current user
-     * cannot `read` are omitted — from the emitted nodes AND from the `meta.indexEntry`
-     * handed to `extract`. Collections whose children are all filtered out are pruned.
-     * On the build context, and on static deployments, nothing is filtered (synthetic admin).
+     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the user
+     * cannot `read` are omitted from the emitted nodes AND from the
+     * `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.
      */
     buildContentTree: <T = unknown, TEntryTypes = DefaultEntryTypes>(options?: BuildContentTreeOptions<T, TEntryTypes>) => Promise<ContentTreeNode<T>[]>;
     /**
-     * List all content entries as a flat array.
+     * Every content entry as a flat array.
      *
-     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the current user
-     * cannot `read` are omitted before `extract` runs. On the build context, and on static
-     * deployments, nothing is filtered (synthetic admin).
+     * Path ACLs: on the request-scoped context (`getCanopy()`), entries the user
+     * 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 — it always lists
-     * `defaultActiveBranch ?? defaultBaseBranch ?? 'main'`. In `dev` that tracks the git HEAD
-     * via `refreshActiveBranch()`; in `prod` that refresh is a no-op, so this always reads the
-     * base branch. See `.claude/future-tasks/context-listing-branch-pinning.md`.
+     * 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`.
      */
     listEntries: <T = Record<string, unknown>>(options?: ListEntriesOptions<T>) => Promise<ListEntriesItem<T>[]>;
     /**
-     * Content reader (auth context applied automatically — admin at build time).
+     * Content reader, with the auth context applied automatically (admin at build
+     * time).
      *
-     * `meta.physicalPath` is the absolute filesystem path to the resolved entry file.
-     * It is **server-only** — do not serialize it to the client or embed it in public
-     * output, as it reveals the deployment's filesystem layout (home dir / EFS mount /
-     * branch name). Intended for build-time reads of colocated artifacts, e.g.
+     * `meta.physicalPath` is the resolved entry file's absolute path, and is
+     * **server-only**: never serialize it to the client or embed it in public
+     * output, since it reveals the deployment's filesystem layout (home dir, EFS
+     * mount, branch name). It is for build-time reads of colocated artifacts, e.g.
      * `fs.readFile(path.join(path.dirname(result.meta.physicalPath), 'profile.json'))`.
      */
     read: <T = unknown>(input: {
@@ -95,56 +95,33 @@ export interface CanopyBuildContext {
         meta: ContentReadMeta;
     }>;
     /**
-     * Read content by URL path, resolving the collection/entry split automatically.
-     *
-     * Tries direct entry match first (last segment = slug, rest = collection path),
-     * then falls back to index entry (full path = collection, slug = 'index'). Both attempts
-     * require the collection part to be a real collection — see below.
-     * Root path '/' resolves to the content root's index entry.
+     * Read content by URL path, resolving the collection/entry split itself: a
+     * direct entry match first (last segment = slug, rest = collection path),
+     * then the index entry (full path = collection, slug = 'index'). Both need a
+     * real collection for the collection part; root '/' is the content root's
+     * index entry.
      *
-     * Resolves ONLY what `listEntries` publishes — `readByUrlPath(item.urlPath)` reaches the entry,
-     * and no other spelling does. Three shapes that used to resolve are therefore null now:
-     * `/x/index` (the literal spelling of an index entry's collapsed URL, in any case),
-     * `/<collection>/<entryTypeName>` and `/<collection>/<entryTypeName>/<slug>` (an entry-type
-     * path is not a collection, so it is not part of any published URL), and an entry whose
-     * on-disk type token its collection does not declare (`listEntries` skips those too). A
-     * collection literally named `index` is unaffected — the index fallback resolves it.
+     * Resolves ONLY what `listEntries` publishes — `readByUrlPath(item.urlPath)`
+     * reaches the entry and no other spelling does; a collection literally named
+     * `index` still resolves, via the index fallback. `read({ entryPath })` is
+     * deliberately NOT narrowed this way: a schema path is a different question
+     * from a published URL, and reaches a singleton whose slug nobody knows.
      *
-     * `read({ entryPath: 'content/home' })` is deliberately NOT narrowed: addressing an entry
-     * structurally, by its schema path, is a different question from addressing it by its
-     * published URL, and it is the only way to reach a singleton without knowing its slug.
+     * Null when nothing matches — a collection URL with no index entry (use
+     * buildContentTree), a non-entry path like `/favicon.ico` the slug validator
+     * rejects, or a path the user may not read, so a FORBIDDEN denial renders as
+     * a 404 via `notFound()` rather than a 500. Strict `read()` still throws.
      *
-     * Returns null if no content matches the path — including collection URLs that have no
-     * index entry (use buildContentTree for those) and non-entry/invalid paths such as
-     * `/favicon.ico` or Next internals (the slug validator rejects them, treated as a miss).
-     * Also returns null for paths the current user is not permitted to read (a FORBIDDEN
-     * denial renders as a 404 via `notFound()` instead of a 500); the strict `read()` API
-     * still throws on permission errors.
-     *
-     * The result's `meta.physicalPath` is the absolute filesystem path to the resolved
-     * entry file. It is **server-only** — do not serialize it to the client or embed it
-     * in public output, as it reveals the deployment's filesystem layout (home dir / EFS
-     * mount / branch name). Intended for build-time reads of colocated artifacts.
-     *
-     * `meta.entryType` and `meta.entryId` are also resolved for free (path resolution
-     * already derives them) — useful for entry-type-based dispatch in a single
-     * catch-all route without a separate `listEntries` lookup or filename parse. See
-     * `ContentReadMeta` (content-reader.ts) before branching on `entryType` for a legacy
-     * file: `entryId === undefined` signals that `entryType` is a fallback, not a read.
+     * `meta.physicalPath` is **server-only**, for the reason given on `read`.
+     * `meta.entryType`/`entryId` come free with path resolution, so one catch-all
+     * route can dispatch on entry type with no extra lookup; check
+     * `ContentReadMeta` first — `entryId === undefined` marks `entryType` a
+     * fallback, not a read.
      *
      * @example
      * ```ts
-     * // URL /docs/guides/getting-started → reads content/docs/guides + slug "getting-started"
-     * // URL /docs/guides → reads content/docs/guides + slug "index"
-     * // URL / → reads content root + slug "index"
-     * const result = await canopy.readByUrlPath<DocContent>('/docs/guides/getting-started')
-     * if (result) {
-     *   const { data, path } = result
-     *   switch (result.meta.entryType) {
-     *     case 'home': return <HomePage data={data} />
-     *     default: return <DocView data={data} />
-     *   }
-     * }
+     * const result = await canopy.readByUrlPath<DocContent>('/docs/guides/intro')
+     * if (result?.meta.entryType === 'home') return <HomePage data={result.data} />
      * ```
      */
     readByUrlPath: <T = unknown>(urlPath: string, options?: {
@@ -163,15 +140,11 @@ export interface CanopyContext extends CanopyBuildContext {
     user: CanopyUser;
 }
 /**
- * Create a Canopy context that manages auth + content reading.
- * Framework-agnostic - the adapter provides the extractUser function.
- *
- * User extractor should apply bootstrap admin groups (via authResultToCanopyUser).
+ * Create a Canopy context managing auth + content reading. Framework-agnostic:
+ * the adapter supplies extractUser.
  *
- * NOTE: This function is synchronous because in practice, services are always
- * provided pre-created (async) by the framework adapter. The fallback path
- * that creates services from config cannot work correctly since createCanopyServices
- * is now async. Always pass services, not config.
+ * Synchronous, and takes pre-created `services` rather than config — building
+ * services is async, so there is no working fallback path from config here.
  */
 export declare function createCanopyContext(options: CanopyContextOptions): {
     getContext: () => Promise<CanopyContext>;