canopycms 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -5,9 +5,9 @@ packages release together, at one version.
 
 ## This build
 
-Version `0.3.3`, built from [`bb13b42`](https://github.com/safeinsights/canopycms/tree/bb13b429fb8deec72bbcf7f566ffa60304c5d690).
+Version `0.4.0`, built from [`184d5c6`](https://github.com/safeinsights/canopycms/tree/184d5c62b8158d1fdcfbd85430f17f90aceec00c).
 
-Its entries are [0.3.3](#033), under **Released**.
+Its entries are [0.4.0](#040), 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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/.changeset/README.md) until a stable release
+every entry written since is a file in [`.changeset/`](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/.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,32 @@ entries under **Released**.
 
 ## Released
 
+### 0.4.0
+
+#### Link-only references to json/yaml entries leave out the body — **behaviour change (resolved data and types)**
+
+<!-- changeset: link-only-references-omit-data-body -->
+
+_First in 0.4.0._
+
+**What changed.** A reference field without `includeBody: true` now resolves a json or yaml
+target without that target's `isBody` field, as it already resolved an md/mdx target without its
+body. A long body is no longer copied into every entry that merely links to it. A field that is
+only named `body`, with no `isBody`, is ordinary data and still resolves. The live-preview resolve
+endpoint and the AI export's `referenceLink` target follow the same rule, and `referenceLink`
+now receives a json/yaml target's `isBody` field as `context.body`. Live preview resolves every
+reference link-only, so an `includeBody: true` reference to a json/yaml target now previews
+without its body, as one to an md/mdx target already did.
+
+With `resolvedSchema`, the target's `isBody` field is now optional in the resolved type unless
+the reference sets `includeBody: true`. This applies to md/mdx targets too, which already
+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).
+
 ### 0.3.3
 
 #### Bare URLs in a markdown body survive a save
@@ -471,7 +497,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#live-preview)).
+   [Live Preview](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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).
@@ -486,7 +512,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#live-preview).
+[Live Preview](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -568,7 +594,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#ai-content-configuration).
+shows [the recipe](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#ai-content-configuration).
 
 **Now deletable.** An `exclude.where` that re-read the `noindex` flag by hand.
 
@@ -590,7 +616,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#mdx-content-cannot-run-code).
+[MDX content cannot run code](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -727,7 +753,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#definecanopyconfig-options)).
+  ([reference](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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.
@@ -751,7 +777,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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`.
 
@@ -789,7 +815,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -843,10 +869,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#worker-down-alarm).
+  [Worker-down alarm](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -857,7 +883,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#the-worker-instance).
+[The worker instance](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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.
@@ -923,7 +949,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#the-worker-instance)).
+([details](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#the-worker-instance)).
 
 #### The worker follows a rebased or deleted GitHub branch
 
@@ -945,7 +971,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#rolling-the-worker-from-ci)). The gate refuses a stack without the
+([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
 `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`.
 
@@ -962,8 +988,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#installing-the-units-by-hand)). After the first deploy, run the
-[checklist](https://github.com/safeinsights/canopycms/blob/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#first-deploy-checklist).
+([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).
 
 #### `canopycms-cdk`: `CanopyCmsService.attachTo`, and editor response headers — **behaviour change if you frame the CMS**
 
@@ -974,7 +1000,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1150,7 +1176,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#ai-content-configuration).
+[AI Content Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#ai-content-configuration).
 
 **Now deletable.** A `fieldTransforms` entry that re-renders a reference field only to drop or
 change its link.
@@ -1225,7 +1251,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#drafts-and-unpublishing) section covers long-lived branches and
+and Unpublishing](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#drafts-and-unpublishing) section covers long-lived branches and
 unpublishing.
 
 #### The editor calls the content drawer "All content"
@@ -1537,7 +1563,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#stamping-a-publication-date).
+`{ name: 'publishedAt', type: 'datetime', stampOnPublish: true }`. See [Stamping a publication date](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#stamping-a-publication-date).
 
 **Now deletable.** A build step or hook that writes a missing publication date into new entries.
 
@@ -1584,7 +1610,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#editor-customization).
+[Your root layout](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1695,7 +1721,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/packages/canopycms-auth-clerk/README.md#clerk-components-on-your-own-pages).
+[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).
 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
@@ -1736,12 +1762,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#repository-secrets-and-variables)); a stack scaffolded earlier
+([why the prefix](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#security-model)).
+key are public material ([Security Model](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1753,7 +1779,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/ARCHITECTURE.md#why-one-github-app-per-site-not-one-shared-across-an-organisation)).
+([why](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1766,7 +1792,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#register-it-with-canopycms-init-github-app)).
+   ([details](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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`,
@@ -1777,7 +1803,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#authenticating-as-a-github-app).
+[Authenticating as a GitHub App](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#authenticating-as-a-github-app).
 
 ```bash
 canopycms init-github-app create -- \
@@ -1825,7 +1851,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#rotating-a-secret).
+[Rotating a secret](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1879,12 +1905,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#dual-build-support)).
+   ([Dual Build Support](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#where-the-image-is-built)).
 
 **To adopt.**
 
@@ -1913,7 +1939,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#media-configuration) for the
+uploads can be same-origin. See [Media Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -1938,7 +1964,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#cross-account-asset-bucket).
+pass. See [Cross-account asset bucket](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#cross-account-asset-bucket).
 
 **To adopt.** Optional:
 
@@ -2048,7 +2074,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/docs/deploying-to-aws.md#security-model)).
+`clerkMiddleware` ([Security Model](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/docs/deploying-to-aws.md#security-model)).
 
 #### `readByUrlPath` answers only where `listEntries` publishes — **breaking (routing)**
 
@@ -2147,7 +2173,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#media-configuration)). Two traps:
+is mounted" in [Media Configuration](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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.
@@ -2306,7 +2332,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#sitemap-and-seo-metadata). Every routable entry type is in
+[Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -2363,7 +2389,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#public-read-on-server-deployments)).
+([Public read on server deployments](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/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
@@ -2416,7 +2442,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#block-component-registries) and
+[Block Component Registries](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#block-component-registries) and
 `apps/example1/app/components/PostView.tsx`.
 
 ```ts
@@ -2438,7 +2464,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
+([Reusable Field Fragments](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
 identity helper for them.
 
 ```ts
@@ -2457,7 +2483,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/README.md#shared--referenced-blocks).
+(0.0.64). See [Shared / Referenced Blocks](https://github.com/safeinsights/canopycms/blob/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#shared--referenced-blocks).
 
 **Now deletable.** A second `read()` in page code to unwrap a shared block's reference.
 
@@ -2479,7 +2505,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/bb13b429fb8deec72bbcf7f566ffa60304c5d690/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/184d5c62b8158d1fdcfbd85430f17f90aceec00c/README.md#convention-why-key-the-registry-by-entry-type-name) says when to keep them.
 
 **To adopt.**
 

package/dist/ai/generate.js

@@ -9,6 +9,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { minimatch } from 'minimatch';
 import { isDataOnlyFormat } from '../utils/format.js';
+import { findExplicitBodyFieldName, linkOnlyReferenceData } from '../utils/body-field.js';
 import { extractEntryTypeFromFilename, extractIdFromFilename, } from '../content-id-index.js';
 import { hasTraversalSequence } from '../paths/index.js';
 import { getErrorMessage, isNodeError } from '../utils/error.js';
@@ -76,19 +77,24 @@ export async function generateAIContent(options) {
             pendingById.set(pending.contentId, pending);
     }
     // The target as `resolveReferenceTarget` would give it, built from this export's own read, so
-    // an entry outside the export set is never offered and a target cannot change mid-run
+    // an entry outside the export set is never offered and a target cannot change mid-run. A
+    // json/yaml target's `isBody` field is its body here, as an md/mdx target's body is
     const subjectOf = (id) => {
         const pending = pendingById.get(id);
         if (!pending || !exported.has(id))
             return undefined;
-        const { slug } = pending.entry;
-        const target = buildResolvedReference(structuredClone(pending.storedData), {
+        const { format } = pending;
+        const { slug, fields } = pending.entry;
+        const storedData = structuredClone(pending.storedData);
+        const target = buildResolvedReference(linkOnlyReferenceData(storedData, format, fields), {
             id,
             slug,
             collection: pending.collectionPath,
             urlPath: computeEntryUrl(pending.collectionPath, slug, contentRoot),
         });
-        return { target, body: pending.body };
+        const dataBodyField = isDataOnlyFormat(format) ? findExplicitBodyFieldName(fields) : undefined;
+        const dataBody = dataBodyField === undefined ? undefined : storedData[dataBodyField];
+        return { target, body: pending.body ?? (typeof dataBody === 'string' ? dataBody : undefined) };
     };
     const linkFor = config?.referenceLink
         ? await decideReferenceLinks(config.referenceLink, allPending, subjectOf, entryLinkUrl)
@@ -254,6 +260,7 @@ async function collectEntries(read, collection, cleanPath) {
                 entry: aiEntry,
                 body,
                 storedData,
+                format: doc.format,
                 linkedIds: [],
                 contentId: extractIdFromFilename(path.basename(listEntry.relativePath)),
                 absolutePath: doc.absolutePath,

package/dist/ai/types.d.ts

@@ -208,8 +208,9 @@ export type EntryTransforms = Record<string, EntryTransformFn>;
 /** What {@link AIReferenceLinkFn} knows about a target beyond its data. */
 export interface AIReferenceLinkContext {
     /**
-     * The target's MD/MDX body as stored, `undefined` for a data-only entry. It only informs this
-     * decision: none of it reaches the entries that link to the target.
+     * The target's body as stored: an md/mdx entry's body, or a json/yaml entry's `isBody` field,
+     * which the target leaves out as a link-only reference does. `undefined` when it has none. It
+     * only informs this decision: none of it reaches the entries that link to the target.
      */
     body: string | undefined;
     /**

package/dist/cli/cli.js

@@ -4552,16 +4552,26 @@ function flattenGroupFields(fields) {
   return result;
 }
 function findBodyFieldName(fields) {
+  return findExplicitBodyFieldName(fields) ?? "body";
+}
+function findExplicitBodyFieldName(fields) {
   for (const field of flattenGroupFields(fields)) {
     if ("isBody" in field && field.isBody)
       return field.name;
   }
-  return "body";
+  return void 0;
+}
+function linkOnlyReferenceData(data, format, fields) {
+  const bodyFieldName = isDataOnlyFormat(format) && fields ? findExplicitBodyFieldName(fields) : void 0;
+  if (bodyFieldName === void 0 || !(bodyFieldName in data))
+    return data;
+  const { [bodyFieldName]: _body, ...rest } = data;
+  return rest;
 }
 function extractSeoFields(entryData, opts = {}) {
   const names = { ...DEFAULT_SEO_FIELD_NAMES, ...opts.fields };
-  const entry = asRecord(entryData);
-  const source = opts.group ? asRecord(entry?.[opts.group]) : entry;
+  const entry = asRecord2(entryData);
+  const source = opts.group ? asRecord2(entry?.[opts.group]) : entry;
   return {
     title: asText(source?.[names.title]) ?? asText(opts.fallbackTitle),
     description: asText(source?.[names.description]) ?? asText(opts.fallbackDescription),
@@ -6285,14 +6295,18 @@ async function generateAIContent(options) {
     const pending = pendingById.get(id);
     if (!pending || !exported.has(id))
       return void 0;
-    const { slug } = pending.entry;
-    const target = buildResolvedReference(structuredClone(pending.storedData), {
+    const { format } = pending;
+    const { slug, fields } = pending.entry;
+    const storedData = structuredClone(pending.storedData);
+    const target = buildResolvedReference(linkOnlyReferenceData(storedData, format, fields), {
       id,
       slug,
       collection: pending.collectionPath,
       urlPath: computeEntryUrl(pending.collectionPath, slug, contentRoot)
     });
-    return { target, body: pending.body };
+    const dataBodyField = isDataOnlyFormat(format) ? findExplicitBodyFieldName(fields) : void 0;
+    const dataBody = dataBodyField === void 0 ? void 0 : storedData[dataBodyField];
+    return { target, body: pending.body ?? (typeof dataBody === "string" ? dataBody : void 0) };
   };
   const linkFor = config?.referenceLink ? await decideReferenceLinks(config.referenceLink, allPending, subjectOf, entryLinkUrl) : void 0;
   const bodyLinkUrl = linkFor ? (location) => {
@@ -6434,6 +6448,7 @@ async function collectEntries(read, collection, cleanPath) {
         entry: aiEntry,
         body,
         storedData,
+        format: doc.format,
         linkedIds: [],
         contentId: extractIdFromFilename(path13.basename(listEntry.relativePath)),
         absolutePath: doc.absolutePath,
@@ -7770,7 +7785,7 @@ async function generateAIContentCLI(options) {
   console.log(`  Output: ${result.outputDir}
 `);
 }
-var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned2, init_mode_env, forEachReferenceField, init_validation, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, DEFAULT_SEO_FIELD_NAMES, asRecord, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned4, SchemaUnavailableError, BASE58_PATTERN, CONTENT_ID_PATTERN, PHYSICAL_SEGMENT_PATTERN, isValidId, EMPTY_LOGICAL_PATH, ContentIdIndex, parseTypedFilename, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, getFormatExtension, isDataOnlyFormat, asRecord2, RESERVED_SETTINGS_BRANCH_PREFIX, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, log10, normalizePath, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
+var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned2, init_mode_env, forEachReferenceField, init_validation, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, getFormatExtension, isDataOnlyFormat, asRecord, DEFAULT_SEO_FIELD_NAMES, asRecord2, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned4, SchemaUnavailableError, BASE58_PATTERN, CONTENT_ID_PATTERN, PHYSICAL_SEGMENT_PATTERN, isValidId, EMPTY_LOGICAL_PATH, ContentIdIndex, parseTypedFilename, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, RESERVED_SETTINGS_BRANCH_PREFIX, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, log10, normalizePath, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
 var init_generate_ai_content = __esm({
   "dist/cli/generate-ai-content.js"() {
     "use strict";
@@ -9216,6 +9231,17 @@ var init_generate_ai_content = __esm({
     });
     CONTENT_WRITE_LOCK_STALE_MS = 3e4;
     heldRoots = new AsyncLocalStorage();
+    getFormatExtension = (format) => {
+      if (format === "md")
+        return ".md";
+      if (format === "mdx")
+        return ".mdx";
+      if (format === "yaml")
+        return ".yaml";
+      return ".json";
+    };
+    isDataOnlyFormat = (format) => format === "json" || format === "yaml";
+    asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
     init_item_keys();
     DEFAULT_SEO_FIELD_NAMES = {
       title: "metaTitle",
@@ -9226,7 +9252,7 @@ var init_generate_ai_content = __esm({
       noindex: "noindex",
       twitterCard: "twitterCard"
     };
-    asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+    asRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
     asText = (value) => {
       if (typeof value !== "string")
         return void 0;
@@ -9238,7 +9264,7 @@ var init_generate_ai_content = __esm({
       const text3 = asText(value);
       if (text3)
         return text3;
-      return asText(asRecord(value)?.src);
+      return asText(asRecord2(value)?.src);
     };
     asOgType = (value) => {
       const text3 = asText(value);
@@ -9939,17 +9965,6 @@ var init_generate_ai_content = __esm({
     RESOURCE = "content-index";
     init_error3();
     init_error3();
-    getFormatExtension = (format) => {
-      if (format === "md")
-        return ".md";
-      if (format === "mdx")
-        return ".mdx";
-      if (format === "yaml")
-        return ".yaml";
-      return ".json";
-    };
-    isDataOnlyFormat = (format) => format === "json" || format === "yaml";
-    asRecord2 = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
     init_normalize();
     init_operating_mode();
     RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
@@ -10448,7 +10463,7 @@ var init_generate_ai_content = __esm({
           fields = entryTypeConfig?.schema || [];
         }
         if (format === "json") {
-          const data = asRecord2(JSON.parse(raw));
+          const data = asRecord(JSON.parse(raw));
           doc = {
             collection: schemaItem.logicalPath,
             collectionName: schemaItem.name,
@@ -10458,7 +10473,7 @@ var init_generate_ai_content = __esm({
             absolutePath
           };
         } else if (format === "yaml") {
-          const data = asRecord2(yamlParse(raw));
+          const data = asRecord(yamlParse(raw));
           doc = {
             collection: schemaItem.logicalPath,
             collectionName: schemaItem.name,
@@ -11061,10 +11076,11 @@ var init_generate_ai_content = __esm({
        * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
        * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
        * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
-       * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
-       * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
-       * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
-       * cloned once per referencing entry.
+       * EFS/NFS this targets the syscall the memo removes dominates both. A target resolves
+       * without its body (an md/mdx target to its frontmatter, a json/yaml one without its `isBody`
+       * field) unless the field sets `includeBody`, which is why `includeBody` is opt-in per
+       * field: an embedded body sits inside the memoized object and is cloned once per referencing
+       * entry.
        */
       resolveSingleReference(id, idIndex, includeBody, cache, access) {
         if (!cache)
@@ -11159,7 +11175,8 @@ var init_generate_ai_content = __esm({
             }));
           }
           const bodyForEmbed = includeBody && "body" in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : void 0;
-          return buildResolvedReference(doc.data, meta, bodyForEmbed);
+          const data = includeBody ? doc.data : linkOnlyReferenceData(doc.data, doc.format, this.entryTypeOf(location.collection, location.relativePath)?.schema);
+          return buildResolvedReference(data, meta, bodyForEmbed);
         } catch (error) {
           if (isNodeError3(error) && error.code === "ENOENT")
             return STALE_LOOKUP;
@@ -13182,10 +13199,10 @@ var init_generate_ai_content = __esm({
       try {
         const raw = await fs20.readFile(filePath, "utf8");
         if (format === "json") {
-          return asRecord2(JSON.parse(raw));
+          return asRecord(JSON.parse(raw));
         }
         if (format === "yaml") {
-          return asRecord2(yamlParse2(raw));
+          return asRecord(yamlParse2(raw));
         }
         const parsed = matter3(raw);
         const data = { ...parsed.data ?? {} };

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

@@ -2912,13 +2912,36 @@ function flattenGroupFields(fields) {
   return result;
 }
 
+// dist/utils/format.js
+var getFormatExtension = (format) => {
+  if (format === "md")
+    return ".md";
+  if (format === "mdx")
+    return ".mdx";
+  if (format === "yaml")
+    return ".yaml";
+  return ".json";
+};
+var isDataOnlyFormat = (format) => format === "json" || format === "yaml";
+var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+
 // dist/utils/body-field.js
 function findBodyFieldName(fields) {
+  return findExplicitBodyFieldName(fields) ?? "body";
+}
+function findExplicitBodyFieldName(fields) {
   for (const field of flattenGroupFields(fields)) {
     if ("isBody" in field && field.isBody)
       return field.name;
   }
-  return "body";
+  return void 0;
+}
+function linkOnlyReferenceData(data, format, fields) {
+  const bodyFieldName = isDataOnlyFormat(format) && fields ? findExplicitBodyFieldName(fields) : void 0;
+  if (bodyFieldName === void 0 || !(bodyFieldName in data))
+    return data;
+  const { [bodyFieldName]: _body, ...rest } = data;
+  return rest;
 }
 
 // dist/content-store.js
@@ -2934,7 +2957,7 @@ var DEFAULT_SEO_FIELD_NAMES = {
   noindex: "noindex",
   twitterCard: "twitterCard"
 };
-var asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+var asRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 var asText = (value) => {
   if (typeof value !== "string")
     return void 0;
@@ -2946,7 +2969,7 @@ var asImageUrl = (value) => {
   const text = asText(value);
   if (text)
     return text;
-  return asText(asRecord(value)?.src);
+  return asText(asRecord2(value)?.src);
 };
 var asOgType = (value) => {
   const text = asText(value);
@@ -2958,8 +2981,8 @@ var asTwitterCard = (value) => {
 };
 function extractSeoFields(entryData, opts = {}) {
   const names = { ...DEFAULT_SEO_FIELD_NAMES, ...opts.fields };
-  const entry = asRecord(entryData);
-  const source = opts.group ? asRecord(entry?.[opts.group]) : entry;
+  const entry = asRecord2(entryData);
+  const source = opts.group ? asRecord2(entry?.[opts.group]) : entry;
   return {
     title: asText(source?.[names.title]) ?? asText(opts.fallbackTitle),
     description: asText(source?.[names.description]) ?? asText(opts.fallbackDescription),
@@ -4459,19 +4482,6 @@ async function readFileWithMtimeIfExists(filePath) {
   }
 }
 
-// dist/utils/format.js
-var getFormatExtension = (format) => {
-  if (format === "md")
-    return ".md";
-  if (format === "mdx")
-    return ".mdx";
-  if (format === "yaml")
-    return ".yaml";
-  return ".json";
-};
-var isDataOnlyFormat = (format) => format === "json" || format === "yaml";
-var asRecord2 = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
-
 // dist/paths/index.js
 init_normalize();
 
@@ -5085,7 +5095,7 @@ var ContentStore = class {
       fields = entryTypeConfig?.schema || [];
     }
     if (format === "json") {
-      const data = asRecord2(JSON.parse(raw));
+      const data = asRecord(JSON.parse(raw));
       doc = {
         collection: schemaItem.logicalPath,
         collectionName: schemaItem.name,
@@ -5095,7 +5105,7 @@ var ContentStore = class {
         absolutePath
       };
     } else if (format === "yaml") {
-      const data = asRecord2(yamlParse(raw));
+      const data = asRecord(yamlParse(raw));
       doc = {
         collection: schemaItem.logicalPath,
         collectionName: schemaItem.name,
@@ -5698,10 +5708,11 @@ var ContentStore = class {
    * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
    * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
    * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
-   * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
-   * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
-   * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
-   * cloned once per referencing entry.
+   * EFS/NFS this targets the syscall the memo removes dominates both. A target resolves
+   * without its body (an md/mdx target to its frontmatter, a json/yaml one without its `isBody`
+   * field) unless the field sets `includeBody`, which is why `includeBody` is opt-in per
+   * field: an embedded body sits inside the memoized object and is cloned once per referencing
+   * entry.
    */
   resolveSingleReference(id, idIndex, includeBody, cache, access) {
     if (!cache)
@@ -5796,7 +5807,8 @@ var ContentStore = class {
         }));
       }
       const bodyForEmbed = includeBody && "body" in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : void 0;
-      return buildResolvedReference(doc.data, meta, bodyForEmbed);
+      const data = includeBody ? doc.data : linkOnlyReferenceData(doc.data, doc.format, this.entryTypeOf(location.collection, location.relativePath)?.schema);
+      return buildResolvedReference(data, meta, bodyForEmbed);
     } catch (error) {
       if (isNodeError(error) && error.code === "ENOENT")
         return STALE_LOOKUP;
@@ -6752,14 +6764,18 @@ async function generateAIContent(options) {
     const pending = pendingById.get(id);
     if (!pending || !exported.has(id))
       return void 0;
-    const { slug } = pending.entry;
-    const target = buildResolvedReference(structuredClone(pending.storedData), {
+    const { format } = pending;
+    const { slug, fields } = pending.entry;
+    const storedData = structuredClone(pending.storedData);
+    const target = buildResolvedReference(linkOnlyReferenceData(storedData, format, fields), {
       id,
       slug,
       collection: pending.collectionPath,
       urlPath: computeEntryUrl(pending.collectionPath, slug, contentRoot)
     });
-    return { target, body: pending.body };
+    const dataBodyField = isDataOnlyFormat(format) ? findExplicitBodyFieldName(fields) : void 0;
+    const dataBody = dataBodyField === void 0 ? void 0 : storedData[dataBodyField];
+    return { target, body: pending.body ?? (typeof dataBody === "string" ? dataBody : void 0) };
   };
   const linkFor = config?.referenceLink ? await decideReferenceLinks(config.referenceLink, allPending, subjectOf, entryLinkUrl) : void 0;
   const bodyLinkUrl = linkFor ? (location) => {
@@ -6901,6 +6917,7 @@ async function collectEntries(read, collection, cleanPath) {
         entry: aiEntry,
         body,
         storedData,
+        format: doc.format,
         linkedIds: [],
         contentId: extractIdFromFilename(path13.basename(listEntry.relativePath)),
         absolutePath: doc.absolutePath,
@@ -9794,10 +9811,10 @@ var readEntryData = async (filePath, format, bodyFieldName = "body") => {
   try {
     const raw = await fs20.readFile(filePath, "utf8");
     if (format === "json") {
-      return asRecord2(JSON.parse(raw));
+      return asRecord(JSON.parse(raw));
     }
     if (format === "yaml") {
-      return asRecord2(yamlParse2(raw));
+      return asRecord(yamlParse2(raw));
     }
     const parsed = matter3(raw);
     const data = { ...parsed.data ?? {} };

package/dist/config/types.d.ts

@@ -45,10 +45,11 @@ interface BaseFieldConfig {
     /** Mark this field as the display title for entries using this schema. At most one field per schema. */
     isTitle?: boolean;
     /**
-     * Mark this field as the body content for md/mdx entries.
-     * The field must be type 'markdown' or 'mdx'. At most one per schema.
-     * When present, the file's markdown content is mapped to this field,
-     * making TypeFromEntrySchema include it without manual `& { body: string }`.
+     * Mark this field as the entry's body. The field must be type 'markdown' or 'mdx'. At most one
+     * per schema. On an md/mdx entry, the file's markdown content is mapped to this field, making
+     * TypeFromEntrySchema include it without manual `& { body: string }`. On a json/yaml entry, it
+     * is the prose a link-only reference omits. Either way a reference carries it only with
+     * `includeBody: true`.
      */
     isBody?: boolean;
 }
@@ -117,7 +118,9 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
     options?: ReferenceOption[];
     /**
      * Include the referenced entry's body in the resolved value, under that entry type's own
-     * body field name (`isBody: true`, else `body`). Defaults to `false`.
+     * body field name (`isBody: true`, else `body`). Defaults to `false`. The body is an md/mdx
+     * target's markdown content, or a json/yaml target's `isBody` field; a json/yaml field merely
+     * named `body` is ordinary data and always resolves.
      *
      * This is the embed-vs-link distinction, declared where it is actually known. A reference
      * that **embeds** its target — a shared call-to-action block rendered inline — needs the
@@ -131,9 +134,6 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
      * contains both kinds: a page with a shared CTA *and* a related-posts list cannot be served
      * by a single call-level setting, and a call-level flag would mean the same field resolved
      * to different shapes in different places.
-     *
-     * Only affects formats that HAVE a separate body — md and mdx. A json/yaml target's whole
-     * document is already its data, so this is a no-op there.
      */
     includeBody?: boolean;
 }

package/dist/content-store.d.ts

@@ -557,10 +557,11 @@ export declare class ContentStore {
      * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
      * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
      * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
-     * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
-     * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
-     * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
-     * cloned once per referencing entry.
+     * EFS/NFS this targets the syscall the memo removes dominates both. A target resolves
+     * without its body (an md/mdx target to its frontmatter, a json/yaml one without its `isBody`
+     * field) unless the field sets `includeBody`, which is why `includeBody` is opt-in per
+     * field: an embedded body sits inside the memoized object and is cloned once per referencing
+     * entry.
      */
     private resolveSingleReference;
     /**

package/dist/content-store.js

@@ -20,7 +20,7 @@ import { serializeFrontmatter, serializeYaml } from './utils/content-serialize.j
 import { serializeJson } from './utils/json-source-splice.js';
 import { withLock } from './utils/async-mutex.js';
 import { assertContentWriteLockHeld, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from './utils/content-write-lock.js';
-import { findBodyFieldName } from './utils/body-field.js';
+import { findBodyFieldName, linkOnlyReferenceData } from './utils/body-field.js';
 import { withItemKeys } from './item-keys.js';
 import { buildMissingReference, buildResolvedReference, buildRestrictedReference, } from './entry-schema.js';
 import { warnDanglingReference } from './dangling-reference-log.js';
@@ -1611,10 +1611,11 @@ export class ContentStore {
      * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
      * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
      * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
-     * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
-     * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
-     * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
-     * cloned once per referencing entry.
+     * EFS/NFS this targets the syscall the memo removes dominates both. A target resolves
+     * without its body (an md/mdx target to its frontmatter, a json/yaml one without its `isBody`
+     * field) unless the field sets `includeBody`, which is why `includeBody` is opt-in per
+     * field: an embedded body sits inside the memoized object and is cloned once per referencing
+     * entry.
      */
     resolveSingleReference(id, idIndex, includeBody, cache, access) {
         if (!cache)
@@ -1738,9 +1739,13 @@ export class ContentStore {
             //
             // `'body' in doc` narrows the ContentDocument union to its markdown variant, so
             // `doc.body`/`doc.bodyFieldName` are reachable at all -- a type guard, not a redundant
-            // runtime check. Only a field that asked to EMBED its target passes a body at all.
+            // runtime check. Only a field that asked to EMBED its target passes a body at all, and
+            // only such a field keeps a json/yaml target's `isBody` field.
             const bodyForEmbed = includeBody && 'body' in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : undefined;
-            return buildResolvedReference(doc.data, meta, bodyForEmbed);
+            const data = includeBody
+                ? doc.data
+                : linkOnlyReferenceData(doc.data, doc.format, this.entryTypeOf(location.collection, location.relativePath)?.schema);
+            return buildResolvedReference(data, meta, bodyForEmbed);
         }
         catch (error) {
             // Index hit but the file is gone — the typical symptom of an external

package/dist/entry-schema.d.ts

@@ -48,7 +48,10 @@ type InferableField = {
     entryTypes?: readonly string[];
     /** For reference fields: collection paths to scope the search. */
     collections?: readonly string[];
-    /** For reference fields: resolve the target's body too. See ReferenceFieldConfig.includeBody. */
+    /**
+     * For reference fields: resolve the target's body too. Without it the `resolvedSchema`'s
+     * `isBody` field is optional in the resolved type. See ReferenceFieldConfig.includeBody.
+     */
     includeBody?: boolean;
 };
 /**
@@ -79,7 +82,9 @@ export interface ResolvedReferenceMeta {
 }
 /**
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
- * embed it, then the reserved metadata.
+ * embed it, then the reserved metadata. A link-only reference carries no body for any format:
+ * an md/mdx target passes none here, and a json/yaml target's `data` arrives without its
+ * `isBody` field (`linkOnlyReferenceData`), so both formats resolve alike.
  *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
@@ -272,7 +277,7 @@ type FieldValue<F extends InferableField> = F extends {
 } ? ScalarValue<F, SelectValue<F>> : F extends {
     type: 'reference';
     resolvedSchema: infer S;
-} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta & {
+} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>, F['includeBody'] extends true ? false : true> & ResolvedReferenceMeta & {
     unavailable?: undefined;
 }) | UnavailableReference | null> : F extends {
     type: 'reference';
@@ -298,11 +303,16 @@ type FieldValue<F extends InferableField> = F extends {
  *
  * Works with any structurally compatible array; importing FieldConfig is not required.
  */
-type InferContentShape<Fields extends readonly InferableField[]> = Simplify<{
-    [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? never : F['name']]: FieldValue<F>;
+type InferContentShape<Fields extends readonly InferableField[], BodyOptional extends boolean = false> = Simplify<{
+    [F in FlattenInlineGroups<Fields>[number] as IsOptionalKey<F, BodyOptional> extends true ? never : F['name']]: FieldValue<F>;
 } & {
-    [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? F['name'] : never]?: FieldValue<F>;
+    [F in FlattenInlineGroups<Fields>[number] as IsOptionalKey<F, BodyOptional> extends true ? F['name'] : never]?: FieldValue<F>;
 }>;
+/**
+ * Whether InferContentShape gives a field `?:`: an explicit `required: false`, or, with
+ * `BodyOptional` (a reference target resolved without `includeBody`), the `isBody` field.
+ */
+type IsOptionalKey<F extends InferableField, BodyOptional extends boolean> = F['required'] extends false ? true : BodyOptional extends true ? F['isBody'] extends true ? true : false : false;
 /** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export declare const defineEntrySchema: <const T extends readonly InferableField[]>(fields: T) => T;
 /** Content shape derived from a `defineEntrySchema` result. */

package/dist/entry-schema.js

@@ -12,7 +12,9 @@ import { DEFAULT_SEO_FIELD_NAMES } from './static/seo.js';
 export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
 /**
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
- * embed it, then the reserved metadata.
+ * embed it, then the reserved metadata. A link-only reference carries no body for any format:
+ * an md/mdx target passes none here, and a json/yaml target's `data` arrives without its
+ * `isBody` field (`linkOnlyReferenceData`), so both formats resolve alike.
  *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from

package/dist/utils/body-field.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config/index.js';
+import type { ContentFormat, FieldConfig } from '../config/index.js';
 /**
  * Count top-level fields marked `isBody: true`. Does NOT recurse into objects — `isBody` maps
  * to the file's markdown content, which exists only at the top level.
@@ -6,6 +6,14 @@ import type { FieldConfig } from '../config/index.js';
 export declare function countBodyFields(fields: readonly FieldConfig[]): number;
 /** Name of the `isBody: true` field, or `'body'`; maps the file's markdown onto a data field. */
 export declare function findBodyFieldName(fields: readonly FieldConfig[]): string;
+/** Name of the `isBody: true` field, or `undefined`: no `'body'` fallback. */
+export declare function findExplicitBodyFieldName(fields: readonly FieldConfig[]): string | undefined;
+/**
+ * The data a link-only reference (one without `includeBody: true`) carries for its target. A
+ * json/yaml entry's `isBody` field is its prose, so it is left out, as an md/mdx target's body
+ * is. Only an explicit `isBody` counts: a field merely named `body` is ordinary data.
+ */
+export declare function linkOnlyReferenceData(data: Record<string, unknown>, format: ContentFormat, fields: readonly FieldConfig[] | undefined): Record<string, unknown>;
 /**
  * Find an isBody field whose NAME is reserved by reference resolution.
  *

package/dist/utils/body-field.js

@@ -1,4 +1,5 @@
 import { flattenGroupFields } from './flatten-group-fields.js';
+import { isDataOnlyFormat } from './format.js';
 const BODY_FIELD_TYPES = new Set(['markdown', 'mdx']);
 /**
  * Count top-level fields marked `isBody: true`. Does NOT recurse into objects — `isBody` maps
@@ -14,11 +15,27 @@ export function countBodyFields(fields) {
 }
 /** Name of the `isBody: true` field, or `'body'`; maps the file's markdown onto a data field. */
 export function findBodyFieldName(fields) {
+    return findExplicitBodyFieldName(fields) ?? 'body';
+}
+/** Name of the `isBody: true` field, or `undefined`: no `'body'` fallback. */
+export function findExplicitBodyFieldName(fields) {
     for (const field of flattenGroupFields(fields)) {
         if ('isBody' in field && field.isBody)
             return field.name;
     }
-    return 'body';
+    return undefined;
+}
+/**
+ * The data a link-only reference (one without `includeBody: true`) carries for its target. A
+ * json/yaml entry's `isBody` field is its prose, so it is left out, as an md/mdx target's body
+ * is. Only an explicit `isBody` counts: a field merely named `body` is ordinary data.
+ */
+export function linkOnlyReferenceData(data, format, fields) {
+    const bodyFieldName = isDataOnlyFormat(format) && fields ? findExplicitBodyFieldName(fields) : undefined;
+    if (bodyFieldName === undefined || !(bodyFieldName in data))
+        return data;
+    const { [bodyFieldName]: _body, ...rest } = data;
+    return rest;
 }
 /**
  * Find an isBody field whose NAME is reserved by reference resolution.

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.3.3";
+export declare const CANOPYCMS_VERSION = "0.4.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.3.3';
+export const CANOPYCMS_VERSION = '0.4.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {