canopycms 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,9 +5,9 @@ packages release together, at one version.
 
 ## This build
 
-Version `0.4.0`, built from [`184d5c6`](https://github.com/safeinsights/canopycms/tree/184d5c62b8158d1fdcfbd85430f17f90aceec00c).
+Version `0.6.0`, built from [`83be4af`](https://github.com/safeinsights/canopycms/tree/83be4af22312c30e8b89a5f14a7eb51d2af2944e).
 
-Its entries are [0.4.0](#040), under **Released**.
+Its entries are [0.6.0](#060), under **Released**.
 
 If you upgraded from a build on another branch, compare the `<!-- changeset: … -->` slugs in your previous build's `CHANGELOG.md` (`npm pack canopycms@<old>` fetches it) with this one's: entries whose slug your old file lacks are new to you.
 
@@ -24,7 +24,7 @@ Each entry has up to three parts:
 `node_modules/canopycms/CHANGELOG.md`, assembled for that build: its **This build** section lists
 what is new since the previous int on the same branch, or on a stable release links its entries, and its links point at the commit the build
 came from. The copy in the repository holds released history and the entries from before changesets;
-every entry written since is a file in [`.changeset/`](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/.changeset/README.md) until a stable release
+every entry written since is a file in [`.changeset/`](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/.changeset/README.md) until a stable release
 moves it here.
 
 **Find your starting point.** From a stable pin, start at the first version under **Released**
@@ -62,6 +62,42 @@ entries under **Released**.
 
 ## Released
 
+### 0.6.0
+
+#### Clerk organizations-as-groups is a deployment setting, and survives a Clerk instance without Organizations — **behaviour change**
+
+<!-- changeset: clerk-orgs-as-groups -->
+
+_First in 0.6.0._
+
+**What changed.** `CanopyCmsService` takes `clerkOrganizationsAsGroups` (default `true`, unchanged), which the worker honours; in a deployment it, not the plugin's `useOrganizationsAsGroups`, decides the groups. When Clerk refuses the organization list with a 403 (Organizations disabled), the refresh now writes users with no groups and logs a warning, instead of failing whole; any other failure still keeps the last snapshot. Memberships are fetched instance-wide rather than per user. The scaffolds write `false` explicitly: `useOrganizationsAsGroups` in `canopycms init`'s `canopy.ts`, and `clerkOrganizationsAsGroups` in `canopycms init-deploy aws`'s CDK stack.
+
+**To adopt.** On a Clerk instance without Organizations, set `clerkOrganizationsAsGroups: false` on `CanopyCmsService` and `useOrganizationsAsGroups: false` in `createClerkAuthPlugin`. See [Deploying to AWS](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md).
+
+### 0.5.0
+
+#### Reorderable list references, and `maxItems` on list fields — **behaviour change: a build fails on a list over its cap**
+
+<!-- changeset: reference-list-reorder-and-max-items -->
+
+_First in 0.5.0._
+
+**What changed.** A `type: 'reference', list: true` field now edits as rows in stored order, like an `object` list: drag a row or use its "…" menu to move or remove it, open a row to swap its entry in place, and pick from Add under the rows to append. Neither control offers an entry the list already holds. Any `list: true` field, and any `block` field, takes `maxItems`. The editor stops adding at the cap and says why, a save over it is refused, and a production build fails on an entry over it, naming the entry, field, count and cap. Adding `maxItems` to a list that already holds more therefore fails the build until an editor removes the extra items. `maxItems` on a field that holds no items is refused when the entry schema registry is created.
+
+**To adopt.** Set `maxItems: 3` on the list field in its entry schema. See [Field Types](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#field-types).
+
+#### SEO field location moves into config; reference pickers mark hidden entries and take a sort order — **breaking: `createNextCanopyContext({ seo })` and `AIContentConfig.seo` are removed**
+
+<!-- changeset: seo-config-hidden-picks-option-sort -->
+
+_First in 0.5.0._
+
+**What changed.** `defineCanopyConfig` takes `seo: { group?, fields? }`, the one place every surface reads an entry's `noindex` flag: the sitemap and `entryToMetadata` that `createNextCanopyContext` returns, AI content and the editor's reference picker. A per-call `seo`/`group`/`fields` still overrides it. The free `generateContentSitemap` takes `seo` as an argument and refuses to run without it when the config sets one; `createNextCanopyContext` and the AI content config refuse a leftover `seo`. A reference picker now badges an entry hidden from search as "Hidden from search", and picking one adds a note naming the setting on that entry's form, since a page listing only indexed entries won't show it. A reference field takes `optionSort`: `'label'` (the default), `'collection'`, or `{ field, direction }`. Point `field` at an ISO date, since strings compare as text.
+
+**To adopt.** Move `seo` from `createNextCanopyContext({ seo })` and from `defineAIContentConfig({ seo })` into `defineCanopyConfig({ seo })`. See [Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#sitemap-and-seo-metadata) and [How References Work in the Editor](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#how-references-work-in-the-editor).
+
+**Now deletable.** A shared `seo` constant passed separately to the Next context and the AI content config.
+
 ### 0.4.0
 
 #### Link-only references to json/yaml entries leave out the body — **behaviour change (resolved data and types)**
@@ -86,7 +122,7 @@ resolved without it.
 **To adopt.** Where a reference renders its target's prose, set `includeBody: true` on that
 reference field. Code that reads the body from a link-only reference's resolved type now sees
 `string | undefined`; either set `includeBody: true` or handle the missing value. See
-[Resolving References in a Listing](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#resolving-references-in-a-listing).
+[Resolving References in a Listing](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#resolving-references-in-a-listing).
 
 ### 0.3.3
 
@@ -497,7 +533,7 @@ URL.
 2. For a branch preview: wrap views with `withCanopyPreview` in a `'use client'` module, add
    `app/preview/[[...path]]/page.server.tsx`, set `editor.previewPrefix: '/preview'`, and serve that
    route with `frame-ancestors 'self'`, not `X-Frame-Options: DENY` (see
-   [Live Preview](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#live-preview)).
+   [Live Preview](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#live-preview)).
 3. A test reading view content from the route's server HTML must load the page in a browser.
    Server output rendered during a preview request carries the signed-in asset prefix; keep it out
    of cross-request caches (`unstable_cache`, module memos).
@@ -512,7 +548,7 @@ kept site styles ahead of Mantine's in the preview.
 server components. A string path marks the form's spelling (`'a.0.b'` marks `a[0].b`), and an empty
 path marks nothing. The editor counts and logs marks naming no field. `createEntrySchemaRegistry`
 refuses a field name that is empty, all digits or contains `.`, `[` or `]`. See
-[Live Preview](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#live-preview).
+[Live Preview](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#live-preview).
 
 **To adopt.** Fix each path that stops compiling; the error lists valid ones. Rewrite computed paths
 as literal segments, or type that component's prop as plain `FieldProps`. Pass `fieldProps` as
@@ -594,7 +630,7 @@ or a failed render) renders as its plain text, with no URL; any other form of th
 fields are nested or renamed, pass the AI config's `seo` the same object you pass
 `createNextCanopyContext({ seo })`, so the sitemap and AI content read the flag from the same
 place. A field that links to a hidden section by plain URL needs a field transform; the README
-shows [the recipe](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#ai-content-configuration).
+shows [the recipe](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#ai-content-configuration).
 
 **Now deletable.** An `exclude.where` that re-read the `noindex` flag by hand.
 
@@ -616,7 +652,7 @@ A `markdown` field with `renderAs: 'mdx'` is checked as MDX, and `mdxAllow` narr
 field or site-wide. New: field options `renderAs`, `mdxAllow`; config key `mdxAllow`; type
 `MdxAllowlist`. (int.110) A component prop allowance can be `'string'` (or
 `{ type: 'string', maxLength }`): a quoted value only, never bare or `{…}`. See
-[MDX content cannot run code](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#mdx-content-cannot-run-code).
+[MDX content cannot run code](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#mdx-content-cannot-run-code).
 
 **To adopt.** Set `renderAs: 'mdx'` on each `markdown` field your site compiles as MDX, and
 `mdxAllow` to what your renderer takes. Set `executable: true` only on a field whose editors you
@@ -753,7 +789,7 @@ a format check.
 
 - (int.93) Submit commits gain an `Edited-by: Name (id)` trailer; PR bodies gain a section that
   re-submits replace, keeping human text. Options: `gitEditedByTrailers`, `gitCoAuthoredByTrailers`
-  ([reference](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#definecanopyconfig-options)).
+  ([reference](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#definecanopyconfig-options)).
 - (int.110) Submit-commit trailers name every user who saved since the last submit commit, and
   the PR-body section every user who edited the branch, not only the submitter; settings commits
   (permissions, groups) carry the acting user's trailer.
@@ -777,7 +813,7 @@ saves only push the branch, and no failing PR task lands in System health.
 that entry type goes unavailable: the editor says so, and its entries answer 503 with
 `code: 'SCHEMA_UNAVAILABLE'`. Builds, static deploys and `generate-ai-content` still fail. The
 worker holds the base branch for up to 30 minutes while that lasts; see
-[New schemas wait for the editor deploy](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#new-schemas-wait-for-the-editor-deploy).
+[New schemas wait for the editor deploy](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#new-schemas-wait-for-the-editor-deploy).
 Public types gain optional `unavailable` on `EntryTypeConfig` and `FlatSchemaItem`, optional
 `ApiResponse.code`, and a required `SchemaResolutionResult.issues`.
 
@@ -815,7 +851,7 @@ hang until the drain heartbeat lets termination continue. Its in-flight task is
 new stack needs no steps.
 
 **What changed.** (int.109) Detailed in
-[The worker instance](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#the-worker-instance): IMDSv2 with a hop limit of 1; the
+[The worker instance](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#the-worker-instance): IMDSv2 with a hop limit of 1; the
 bundle is one file whose sha256 user data checks, readable as that one object; a file-system policy
 refusing clients without TLS or IAM, replacing the worker's
 `AmazonElasticFileSystemClientReadWriteAccess`; an encrypted gp3 root volume; a boot-time upgrade to
@@ -869,10 +905,10 @@ failure and exits non-zero on `selfStopped`, with a code outside `RestartPrevent
   with its hash, as `worker/dist/index.js` and `index.js.sha256`. The default, `'asset'`, is
   unchanged.
 - `CanopyCmsService` alarms when the worker logs no git sync for 30 minutes. See
-  [Worker-down alarm](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#worker-down-alarm).
+  [Worker-down alarm](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#worker-down-alarm).
 
 **To adopt.** Optional. For parameter-only change sets, see
-[Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#rolling-the-worker-from-ci). For the alarm, pass
+[Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#rolling-the-worker-from-ci). For the alarm, pass
 `alarmTopic`.
 
 **Now deletable.** A manual `cdk deploy` after each canopycms bump whose only purpose is moving the
@@ -883,7 +919,7 @@ worker, and a hand-built alarm on the worker log group.
 **What changed.** (int.112) The boot's `dnf upgrade` could be OOM-killed on every retry. A 1 GiB
 swap file now goes on first; an upgrade that still fails starts the worker unpatched and notifies
 `alarmTopic` if set; a retried step names itself when it gives up. See
-[The worker instance](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#the-worker-instance).
+[The worker instance](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#the-worker-instance).
 
 **To adopt.** Deploy, which replaces the worker instance. The bundle needs none of this, so it is
 not Template first and the worker contract stays at 1.
@@ -949,7 +985,7 @@ and operations may reuse GitHub fetches under 30 seconds old.
 
 **To adopt.** Nothing. Seeding `remote.git` stages a copy of the repository beside the gateway's
 mirror, so the root volume needs room for two
-([details](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#the-worker-instance)).
+([details](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#the-worker-instance)).
 
 #### The worker follows a rebased or deleted GitHub branch
 
@@ -971,7 +1007,7 @@ changes the template too (the fallback bundle's key and hash), so only the contr
 bundle-only roll is safe.
 
 **To adopt.** Parameter mode: gate bundle-only rolls on the contract
-([recipe](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#rolling-the-worker-from-ci)). The gate refuses a stack without the
+([recipe](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#rolling-the-worker-from-ci)). The gate refuses a stack without the
 `WorkerContract` output, so `cdk deploy` the template once, which adds it. A hand-installed unit
 copies its `Environment=CANOPYCMS_WORKER_CONTRACT=` line from `worker/canopy-worker.service`.
 
@@ -988,8 +1024,8 @@ units from the bundle's contract: 2 gets the split, an older bundle the single u
 template, then roll the bundle; on an older template it stops with `template too old for this
 bundle`. Inspect EFS only through `sudo /opt/canopy-worker/canopy-inspect <command>`, never from a root shell. A hand install
 takes `worker/`'s three units and `gateway.env.example`
-([steps](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#installing-the-units-by-hand)). After the first deploy, run the
-[checklist](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#first-deploy-checklist).
+([steps](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#installing-the-units-by-hand)). After the first deploy, run the
+[checklist](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#first-deploy-checklist).
 
 #### `canopycms-cdk`: `CanopyCmsService.attachTo`, and editor response headers — **behaviour change if you frame the CMS**
 
@@ -1000,7 +1036,7 @@ response headers policy. `CanopyCmsDistribution` sends the same headers: `frame-
 `X-Frame-Options: SAMEORIGIN`, `nosniff`, HSTS and `X-Robots-Tag: noindex`. Unless your app sends
 its own framing headers, no other origin can frame the editor or any page the CMS domain serves. Every such page is
 marked `noindex`. The editor's default preview is same-origin and unaffected. See
-[Serving the editor from a distribution you already own](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#serving-the-editor-from-a-distribution-you-already-own).
+[Serving the editor from a distribution you already own](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#serving-the-editor-from-a-distribution-you-already-own).
 
 **To adopt.** If you wired the Function URL into your own distribution by hand, delete those
 behaviors and call `attachTo`, passing your CMS build's `assetPrefix` as `editorAssetPrefix` and a
@@ -1176,7 +1212,7 @@ one the exclusions leave out. A throw or any other return is logged and treated
 **To adopt.** If your site's routes, sitemap or bylines decide that some entries have no page,
 apply the same rule here, for example `referenceLink: (target, { body }) =>
 !body?.trim() ? false : undefined` in `defineAIContentConfig` from `canopycms/ai`. See
-[AI Content Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#ai-content-configuration).
+[AI Content Configuration](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#ai-content-configuration).
 
 **Now deletable.** A `fieldTransforms` entry that re-renders a reference field only to drop or
 change its link.
@@ -1251,7 +1287,7 @@ _First in int.115._
 entry the base branch also changed, the "updated on the base branch" notice and the branch's
 conflict count now stay until the branch merges, so a reviewer still sees which entries replaced a
 base change. They used to clear on the next sync, about five minutes later. README's new [Drafts
-and Unpublishing](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#drafts-and-unpublishing) section covers long-lived branches and
+and Unpublishing](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#drafts-and-unpublishing) section covers long-lived branches and
 unpublishing.
 
 #### The editor calls the content drawer "All content"
@@ -1563,7 +1599,7 @@ editor carries an unsaved draft of a stamped entry onto its stamped version.
 The flag is refused off a top-level `datetime`, on `list: true`, and with `required: true`.
 
 **To adopt.** Add `stampOnPublish: true` to the date field your site sorts or labels by, such as
-`{ name: 'publishedAt', type: 'datetime', stampOnPublish: true }`. See [Stamping a publication date](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#stamping-a-publication-date).
+`{ name: 'publishedAt', type: 'datetime', stampOnPublish: true }`. See [Stamping a publication date](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#stamping-a-publication-date).
 
 **Now deletable.** A build step or hook that writes a missing publication date into new entries.
 
@@ -1610,7 +1646,7 @@ preview/form divider is now keyboard-resizable within the same 15–85% the spli
 stored at, and `react-split-pane` is no longer a dependency.
 `EditorPanes`, `EditorPanesProps`, the `PaneLayout` type and the `SPLIT_PERCENT_*` and `DEFAULT_*_SPLIT_PERCENT` constants are
 no longer exported from `canopycms/client`. See
-[Your root layout](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#editor-customization).
+[Your root layout](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#editor-customization).
 
 **To adopt.** Nothing, unless you import `EditorPanes` or those constants: render `CanopyEditor`
 instead, which lays out its own panes. Hiding your site chrome on the editor route is now
@@ -1721,7 +1757,7 @@ never ended. `canopycms-auth-clerk` skips it while the editor is mounted, and ex
 **To adopt.** Nothing for the editor, if your edit page uses `useClerkAuthConfig()` or
 `ClerkSignIn`. If your CMS build renders `<SignIn>`, `UserButton` or `OrganizationSwitcher` on your
 own pages, mount the hook as in
-[Clerk components on your own pages](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/packages/canopycms-auth-clerk/README.md#clerk-components-on-your-own-pages).
+[Clerk components on your own pages](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/packages/canopycms-auth-clerk/README.md#clerk-components-on-your-own-pages).
 Your own Server Actions in the CMS build still 403 behind OAC.
 
 **Now deletable.** Any local patch of `window.__internal_onBeforeSetActive` (or 6.x's
@@ -1762,12 +1798,12 @@ fast naming the ARN, the field and the keys present, never a value.
 **To adopt.** Nothing, unless one of those secrets holds a JSON document: then set the matching
 prop. The scaffolded stack fills them from the repository _variables_
 `CANOPY_GITHUB_TOKEN_SECRET_JSON_FIELD` and `CLERK_SECRET_KEY_SECRET_JSON_FIELD`
-([why the prefix](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#repository-secrets-and-variables)); a stack scaffolded earlier
+([why the prefix](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#repository-secrets-and-variables)); a stack scaffolded earlier
 adds the props to `infrastructure/bin/app.ts` and `infrastructure/lib/cms-stack.ts` and the two `env`
 lines to `.github/workflows/deploy-cms.yml`, or re-runs the generator and diffs. `cdk synth` refuses a `…JsonField` prop without its `…SecretArn`, and an ARN carrying the ECS `:KEY::` suffix
 (also in `secretsArns`). Don't use CDK's `secretValueFromJson`: it resolves the plaintext into the deployed
 resource's configuration, readable by anyone who can describe it. Only `CLERK_SECRET_KEY` goes through Secrets Manager; `CLERK_JWT_KEY` and the publishable
-key are public material ([Security Model](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#security-model)).
+key are public material ([Security Model](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#security-model)).
 
 **Now deletable.** A wrapper that fetches the secret, parses it and re-exports one field into the
 worker's environment, such as a `jq` step in user data or a wrapper entrypoint around
@@ -1779,7 +1815,7 @@ worker's environment, such as a `jq` step in user data or a wrapper entrypoint a
 `githubToken` is not deprecated and stays the documented default; `canopycms` neither depends on
 nor imports `@octokit/auth-app`. Register one App per site, not one shared across repositories:
 anyone holding an App's key can mint a token for any of its installations
-([why](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/ARCHITECTURE.md#why-one-github-app-per-site-not-one-shared-across-an-organisation)).
+([why](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/ARCHITECTURE.md#why-one-github-app-per-site-not-one-shared-across-an-organisation)).
 
 **To adopt with `canopycms-cdk`** (existing stacks need no edit). `CanopyCmsServiceProps` takes
 `githubAppId`, `githubAppInstallationId`, `githubAppPrivateKeySecretArn` and
@@ -1792,7 +1828,7 @@ anyone holding an App's key can mint a token for any of its installations
    `verify` checks an existing installation's permissions: run it, since an App missing a
    permission only shows up later, as `sync-failed`. `create` needs an interactive terminal and
    never edits an existing JSON secret (create one and point the JSON-field prop at it)
-   ([details](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#register-it-with-canopycms-init-github-app)).
+   ([details](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#register-it-with-canopycms-init-github-app)).
 2. Set the three props and **remove `githubTokenSecretArn`** (with its JSON field). A partial set
    of the three is refused at synth, and so is an App alongside a token.
 3. In the generated workflow, store them as `CANOPY_GITHUB_APP_ID`,
@@ -1803,7 +1839,7 @@ anyone holding an App's key can mint a token for any of its installations
 
 The private key is ARN-only; passing the key itself is refused at synth. Its ARN joins the worker's
 IAM policy automatically, so you need not add it to `secretsArns`. See
-[Authenticating as a GitHub App](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#authenticating-as-a-github-app).
+[Authenticating as a GitHub App](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#authenticating-as-a-github-app).
 
 ```bash
 canopycms init-github-app create -- \
@@ -1851,7 +1887,7 @@ downloads the `.pem` from the App's settings page.
 
 **What changed.** The worker re-reads a Secrets Manager secret (the GitHub token or the Clerk secret
 key) when the operation using it fails. Timings, costs and the store-before-revoke order are in
-[Rotating a secret](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#rotating-a-secret).
+[Rotating a secret](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#rotating-a-secret).
 
 **To adopt.** Nothing for credentials from `*_SECRET_ARN`, which is every scaffolded deployment. A
 GitHub App private key is still read only at boot: store the new key, replace the instance, and
@@ -1905,12 +1941,12 @@ also check the bucket policy for its grant.
 5. `withCanopy()` adds sharp's libvips to Next's file tracing (not for a static export) and, on
    Next 16 and later, sets `turbopack: {}` when your config has neither `turbopack` nor your own
    `webpack` and it can read your Next version. A webpack build still fails its image transforms
-   ([Dual Build Support](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#dual-build-support)).
+   ([Dual Build Support](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#dual-build-support)).
 
 **Breaking:** a stack setting `platform` on `fromImageAsset` without `architecture` gets an arm64
 function while `platform` still decides the image, so `Platform.LINUX_AMD64` builds an image the
 function cannot run. A stack setting neither moves to arm64 with a matching image, built under QEMU
-on an x86 host ([Where the image is built](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#where-the-image-is-built)).
+on an x86 host ([Where the image is built](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#where-the-image-is-built)).
 
 **To adopt.**
 
@@ -1939,7 +1975,7 @@ reason; `platform` on `fromImageAsset`; and, with `withCanopy()`, a hand-written
 
 **What changed.** `media.uploadUrl` (s3 adapter; an absolute http(s) URL or a site-relative path)
 replaces the `url` that `beginUpload()` returns, leaving the presign's `fields` untouched, so
-uploads can be same-origin. See [Media Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#media-configuration) for the
+uploads can be same-origin. See [Media Configuration](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#media-configuration) for the
 CloudFront behavior it expects.
 
 **To adopt.** Optional. Set it from an environment variable: a site-relative value works only where
@@ -1964,7 +2000,7 @@ needs `lazyPublicTransforms: true`) let you pass a deterministically named role,
 bucket's stack computes `arn:aws:iam::<account>:role/<name>` from literals instead of a
 `Fn::GetStackOutput` reference only the CDK CLI resolves. The constructs re-attach
 `AWSLambdaBasicExecutionRole` (and the VPC policy) that `lambda.Function` drops from a role you
-pass. See [Cross-account asset bucket](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#cross-account-asset-bucket).
+pass. See [Cross-account asset bucket](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#cross-account-asset-bucket).
 
 **To adopt.** Optional:
 
@@ -2074,7 +2110,7 @@ public JWKS PEM, used only to verify signatures.
 to variables (Settings → Secrets and variables → Actions → Variables); `bin/app.ts` refuses the
 deploy at synth while it is unset. Check that `bin/app.ts` passes `CLERK_SECRET_KEY` as
 `clerkSecretKeySecretArn` (read by the worker), never in the Lambda's `environment`, unless you keep
-`clerkMiddleware` ([Security Model](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#security-model)).
+`clerkMiddleware` ([Security Model](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/docs/deploying-to-aws.md#security-model)).
 
 #### `readByUrlPath` answers only where `listEntries` publishes — **breaking (routing)**
 
@@ -2173,7 +2209,7 @@ basePath: process.env.NEXT_PUBLIC_BASE_PATH,
 Then pass `baseUrl` to `assetUrl` only if Next serves `/assets` (local adapter, `next dev`, S3 with
 no distribution): `assetUrl(image, { width: 960, baseUrl: BASE_PATH })`. Assets on CloudFront via
 `AssetSupport` stay at the distribution root; pass no `baseUrl` (mount table under "Where `/assets`
-is mounted" in [Media Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#media-configuration)). Two traps:
+is mounted" in [Media Configuration](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#media-configuration)). Two traps:
 
 - Don't pass a deployment `basePath` to `contentStaticParams({ basePath })`; that option filters by
   a nested route prefix and emits zero params, building green.
@@ -2332,7 +2368,7 @@ Under `exactOptionalPropertyTypes: true`, omit keys instead of assigning `undefi
 `withTrailingSlash` and `isAbsoluteUrl` from `canopycms/server`; `defineSeoFieldGroup()` from
 `canopycms`; `generateContentSitemap` and `entryToMetadata` from `canopycms-next`, bound on
 `createNextCanopyContext`'s result. See
-[Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#sitemap-and-seo-metadata). Every routable entry type is in
+[Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#sitemap-and-seo-metadata). Every routable entry type is in
 the sitemap unless `exclude`d or `noindex`; one `noindex` predicate drives both robots metadata and
 sitemap exclusion. `trailingSlash` is never inferred. `lastModified` defaults to `updatedAt`, a
 filesystem mtime. An empty SEO field counts as unset. `siteUrl` must be absolute, colliding URLs are
@@ -2389,7 +2425,7 @@ underscore-prefixed files are skipped.
 
 **What changed.** New scaffolds write `defaultBranchAccess: 'deny'` and
 `defaultPathAccess: { read: 'allow' }`
-([Public read on server deployments](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#public-read-on-server-deployments)).
+([Public read on server deployments](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#public-read-on-server-deployments)).
 
 **To adopt.** An older scaffold's `defaultBranchAccess: 'allow'` is wider than recommended;
 consider `'deny'`. If you deleted `defaultPathAccess: { read: 'allow' }`, anonymous visitors get no content until you
@@ -2442,7 +2478,7 @@ re-checked an entry's type (a `switch` on `meta.entryType` can merge them into o
 **What changed.** `BlockComponentRegistry<Blocks>` (types only, from `canopycms`; `BlockValueOf<Blocks, 'hero'>`
 gives one template's value type) requires exactly
 one component per block template name when written as an object literal. See
-[Block Component Registries](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#block-component-registries) and
+[Block Component Registries](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#block-component-registries) and
 `apps/example1/app/components/PostView.tsx`.
 
 ```ts
@@ -2464,7 +2500,7 @@ templates against the schema.
 
 **What changed.** Spreading a `const` field array into several schemas, and nesting
 `defineInlineFieldGroup()` inside a block template, are documented
-([Reusable Field Fragments](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
+([Reusable Field Fragments](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
 identity helper for them.
 
 ```ts
@@ -2483,7 +2519,7 @@ field by composing from the same `const` field object.
 A block template holding a `reference` field is a shared block; `read()`/`readByUrlPath()` resolve
 it, and listings do with
 [`resolveReferences`](#listings-resolve-references-and-a-resolved-reference-carries-urlpath-and-optionally-its-body-16--breaking-type-level)
-(0.0.64). See [Shared / Referenced Blocks](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#shared--referenced-blocks).
+(0.0.64). See [Shared / Referenced Blocks](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#shared--referenced-blocks).
 
 **Now deletable.** A second `read()` in page code to unwrap a shared block's reference.
 
@@ -2505,7 +2541,7 @@ Not retro-documented, apart from these:
 
 #### The registry is keyed by entry-type name (0.0.42)
 
-**What changed.** `createEntrySchemaRegistry` keys are the entry-type names that `.collection.json` files name in `entry.schema`, and `EntryTypesFromRegistry` derives the typed entry-type map from them. Schema-variable keys (`{ postSchema }`) still work but derive nothing; [README's registry convention](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#convention-why-key-the-registry-by-entry-type-name) says when to keep them.
+**What changed.** `createEntrySchemaRegistry` keys are the entry-type names that `.collection.json` files name in `entry.schema`, and `EntryTypesFromRegistry` derives the typed entry-type map from them. Schema-variable keys (`{ postSchema }`) still work but derive nothing; [README's registry convention](https://github.com/safeinsights/canopycms/blob/83be4af22312c30e8b89a5f14a7eb51d2af2944e/README.md#convention-why-key-the-registry-by-entry-type-name) says when to keep them.
 
 **To adopt.**
 

package/dist/ai/generate.d.ts

@@ -8,6 +8,7 @@
 import type { ContentStore } from '../content-store.js';
 import type { FlatSchemaItem } from '../config/index.js';
 import { type EntryLinkUrlResolver } from '../entry-link-resolver.js';
+import { type SeoFieldLocation } from '../static/seo.js';
 import type { AIContentConfig, AIManifest } from './types.js';
 export interface GenerateOptions {
     store: ContentStore;
@@ -17,6 +18,8 @@ export interface GenerateOptions {
     config?: AIContentConfig;
     /** Custom URL resolver for entry links. */
     entryLinkUrl?: EntryLinkUrlResolver;
+    /** Where entries keep their SEO fields: `CanopyConfig.seo`. Drives the `noindex` read. */
+    seo?: SeoFieldLocation;
     /**
      * ISO-8601 timestamp to record as the manifest's `generated`. Defaults to now.
      *

package/dist/ai/generate.js

@@ -18,7 +18,7 @@ import { entryToMarkdown, frontmatterTitle } from './json-to-markdown.js';
 import { createReferenceRendering, createReferenceTargetResolver, decideReferenceLinks, maskUnexportedTargets, resolveReferenceFields, } from './references.js';
 import { resolveEntryLinksInText } from '../entry-link-resolver.js';
 import { computeEntryUrl } from '../utils/entry-url.js';
-import { DEFAULT_SEO_FIELD_NAMES, isNoindexEntry } from '../static/seo.js';
+import { isNoindexEntry } from '../static/seo.js';
 /**
  * Generate all AI content from the content store.
  *
@@ -32,7 +32,7 @@ import { DEFAULT_SEO_FIELD_NAMES, isNoindexEntry } from '../static/seo.js';
  * rendered, in rounds that repeat while a render fails (see the loop below).
  */
 export async function generateAIContent(options) {
-    const { store, flatSchema, contentRoot, config, entryLinkUrl, generatedAt, buildId } = options;
+    const { store, flatSchema, contentRoot, config, entryLinkUrl, seo, generatedAt, buildId } = options;
     assertValidNoindexConfig(config);
     assertValidReferenceLink(config);
     const files = new Map();
@@ -43,6 +43,7 @@ export async function generateAIContent(options) {
         config,
         idIndex,
         entryLinkUrl,
+        seo,
         resolveTarget: createReferenceTargetResolver(store),
     };
     const collections = flatSchema.filter((item) => item.type === 'collection');
@@ -225,7 +226,7 @@ async function collectCollection(read, collection, flatSchema) {
 }
 /** Read, resolve and filter the entries directly in `collection` (not its subcollections). */
 async function collectEntries(read, collection, cleanPath) {
-    const { store, contentRoot, config, idIndex, entryLinkUrl, resolveTarget } = read;
+    const { store, contentRoot, config, idIndex, entryLinkUrl, seo, resolveTarget } = read;
     const skipNoindex = config?.exclude?.noindex !== false;
     const pending = [];
     const listed = await store.getCollectionEntryPaths(collection.logicalPath);
@@ -245,7 +246,7 @@ async function collectEntries(read, collection, cleanPath) {
                 resolveReferences: false,
             });
             // AI content advertises an entry, so `noindex` leaves it out here as it does the sitemap.
-            if (skipNoindex && isNoindexEntry(doc.data, config?.seo))
+            if (skipNoindex && isNoindexEntry(doc.data, seo))
                 continue;
             const storedData = doc.data;
             doc.data = await resolveReferenceFields(doc.data, entryTypeConfig.schema, resolveTarget);
@@ -317,37 +318,19 @@ function assertValidReferenceLink(config) {
     }
 }
 /**
- * Refuse an `exclude.noindex` or `seo` the noindex gate would misread. A non-boolean
- * `noindex: 'false'` would leave the gate on while the adopter believes it is off, and a
- * misshapen `seo` reads the flag from a field no entry sets, so every noindex entry ships.
+ * Refuse a non-boolean `exclude.noindex`: `noindex: 'false'` would leave the gate on while the
+ * adopter believes it is off. Refuse `seo` too: the location is `CanopyConfig.seo`, and an AI
+ * config loaded without type checking would otherwise drop it silently and ship every noindex
+ * entry. `CanopyConfig.seo`'s shape is checked by the config schema.
  */
 function assertValidNoindexConfig(config) {
     const noindex = config?.exclude?.noindex;
     if (noindex !== undefined && typeof noindex !== 'boolean') {
         throw new Error(`AI content config: exclude.noindex must be a boolean, got ${typeof noindex}`);
     }
-    const seo = config?.seo;
-    if (seo === undefined)
-        return;
-    if (typeof seo !== 'object' || seo === null || Array.isArray(seo)) {
-        throw new Error('AI content config: seo must be an object of { group?, fields? }');
-    }
-    const { group, fields } = seo;
-    if (group !== undefined && typeof group !== 'string') {
-        throw new Error('AI content config: seo.group must be a string');
-    }
-    if (fields === undefined)
-        return;
-    if (typeof fields !== 'object' ||
-        fields === null ||
-        Array.isArray(fields) ||
-        Object.values(fields).some((name) => typeof name !== 'string')) {
-        throw new Error('AI content config: seo.fields must map SEO fields to field-name strings');
-    }
-    // An unknown key (`noIndex`) would leave the gate reading the default field name
-    const unknown = Object.keys(fields).filter((key) => !(key in DEFAULT_SEO_FIELD_NAMES));
-    if (unknown.length > 0) {
-        throw new Error(`AI content config: unknown seo.fields key(s): ${unknown.join(', ')}`);
+    if (config && 'seo' in config) {
+        throw new Error('AI content config: seo is not an AI content option. Set it once as seo in defineCanopyConfig, ' +
+            'where the sitemap, page metadata and AI content all read it.');
     }
 }
 function stripContentRoot(logicalPath, contentRoot) {

package/dist/ai/handler.js

@@ -43,6 +43,7 @@ export function createAIContentHandler(options) {
             contentRoot: contentRootName,
             config: aiConfig,
             entryLinkUrl: config.entryLinkUrl,
+            seo: config.seo,
         });
         cachedResult = result;
         return result;

package/dist/ai/types.d.ts

@@ -6,7 +6,6 @@
  */
 import type { FieldConfig } from '../config/index.js';
 import type { MissingReference, ResolvedReferenceMeta } from '../entry-schema.js';
-import type { SeoFieldLocation } from '../static/seo.js';
 /** A reference whose target this export shows: the target's own data plus where it lives. */
 export type AIResolvedReference = Record<string, unknown> & ResolvedReferenceMeta & {
     unavailable?: undefined;
@@ -62,9 +61,9 @@ export interface ExcludeConfig {
     /** Custom predicate — return true to exclude the entry */
     where?: (entry: AIEntryMeta) => boolean;
     /**
-     * Leave out entries marked `noindex`, read through `isNoindexEntry` at
-     * {@link AIContentConfig.seo}, the predicate the sitemap and robots metadata use. Default
-     * `true`; `false` exports them.
+     * Leave out entries marked `noindex`, read through `isNoindexEntry` at `config.seo`, the
+     * predicate and location the sitemap and robots metadata use. Default `true`; `false` exports
+     * them.
      */
     noindex?: boolean;
 }
@@ -247,11 +246,6 @@ export interface AIContentConfig {
     mountPath?: string;
     /** Opt-out exclusions — content to skip */
     exclude?: ExcludeConfig;
-    /**
-     * Where entries keep their SEO fields, when not the flat defaults. Drives the `noindex` read,
-     * so pass the same object as `createNextCanopyContext({ seo })`, or the two can disagree.
-     */
-    seo?: SeoFieldLocation;
     /** Custom bundles — filtered content subsets */
     bundles?: BundleConfig[];
     /** Per-entry-type, per-field markdown overrides */

package/dist/api/reference-options.d.ts

@@ -1,11 +1,8 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
+import { type ReferenceOption } from '../reference-resolver.js';
 export type ReferenceOptionsResponse = ApiResponse<{
-    options: Array<{
-        id: string;
-        label: string;
-        collection: string;
-    }>;
+    options: ReferenceOption[];
 }>;
 /**
  * Exported routes for router registration

package/dist/api/reference-options.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ContentStore } from '../content-store.js';
 import { defineEndpoint } from './route-builder.js';
 import { ReferenceResolver } from '../reference-resolver.js';
+import { referenceSortFieldSchema } from '../config/schemas/field.js';
 import { parseLogicalPath } from '../paths/index.js';
 import { branchNameSchema } from './validators.js';
 const getReferenceOptionsParamsSchema = z.object({
@@ -16,9 +17,18 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
         entryTypes: z.string().optional(),
         displayField: z.string().optional(),
         search: z.string().optional(),
+        sort: z.enum(['label', 'collection', 'field']).optional(),
+        sortField: referenceSortFieldSchema.optional(),
+        sortDir: z.enum(['asc', 'desc']).optional(),
     })
         .refine((data) => data.collections || data.entryTypes, {
         message: 'At least one of "collections" or "entryTypes" query parameters is required',
+    })
+        .refine((data) => (data.sort === 'field') === (data.sortField !== undefined), {
+        message: '"sortField" is required with sort=field, and only allowed with it',
+    })
+        .refine((data) => data.sortDir === undefined || data.sort === 'field', {
+        message: '"sortDir" is only allowed with sort=field',
     });
     const queryResult = querySchema.safeParse(req.query ?? {});
     if (!queryResult.success) {
@@ -32,6 +42,13 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
     const entryTypesParam = queryResult.data.entryTypes;
     const displayField = queryResult.data.displayField || 'title';
     const search = queryResult.data.search;
+    // The refinements above pair sortField with sort=field, so sortField alone decides.
+    const { sort: sortParam, sortField, sortDir } = queryResult.data;
+    const sort = sortField !== undefined
+        ? { field: sortField, direction: sortDir }
+        : sortParam === 'field'
+            ? undefined
+            : sortParam;
     const flatSchema = branchContext.flatSchema;
     const store = new ContentStore(branchContext.branchRoot, flatSchema, {
         contentRootName: ctx.services.config.contentRoot || 'content',
@@ -70,7 +87,7 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
     // for an option the caller isn't allowed to see.
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
     const resolver = new ReferenceResolver(store, idIndex);
-    const options = await resolver.loadReferenceOptions(collections, displayField, search, entryTypes, (logicalPath) => checkAccess(logicalPath, 'read').allowed);
+    const options = await resolver.loadReferenceOptions(collections, displayField, search, entryTypes, (logicalPath) => checkAccess(logicalPath, 'read').allowed, { seo: ctx.services.config.seo, sort });
     return {
         ok: true,
         status: 200,
@@ -81,7 +98,9 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
  * Get reference options for a field
  * GET /:branch/reference-options
  * Query params: collections (comma-separated, optional), entryTypes (comma-separated, optional),
- *   displayField, search. At least one of collections or entryTypes is required.
+ *   displayField, search. At least one of collections or entryTypes is required. `sort` is
+ *   label (default), collection or field; field takes `sortField` (a dotted path) and `sortDir`
+ *   (asc, the default, or desc). See `ReferenceOptionSort`.
  */
 const getReferenceOptions = defineEndpoint({
     namespace: 'content',