@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/write-limits.md

@@ -1,217 +1,217 @@
----
-title: "Write limits"
-description: "What the server checks on a content write (lengths, patterns, uniqueness, references, body size) and what it does not."
----
-
-# Write limits: what the server checks on a content write
-
-Use this before you rely on a limit. "Exists" means the server refuses a bad value. "Does not
-exist" means the value is stored, so you are the check.
-
-## The write path
-
-Entry writes from the MCP and the Management API run `createEntry` / `updateEntry` in
-`src/lib/content/entry-write.ts`:
-
-1. Request schema (Zod). Failure: 400 with `{ errors }`, keyed by field, no `code`.
-2. Value normalisation (shapes below). Failure: a validation result with `errors`.
-3. Reference existence. Every entry id in a reference field is looked up in the workspace. A
-   missing one is refused: 400 `ref_missing`, with `errors` keyed by the field that holds it. A
-   target that exists but sits in the trash is stored, and the result carries a `warnings` line
-   starting `REFERENCE_NOT_FOUND:` that names the field. A reference loop is refused with 400
-   and `errors._base`.
-4. Per-field value checks against the model. Failure: a validation result with `errors`.
-5. Uniqueness, inside the insert transaction. Failure: `kind: "unique_conflict"` with `conflicts`.
-
-The batch route reports steps 2, 4 and 5 as `code: "UNIQUE_CONFLICT"` or `"VALIDATION"`.
-
-Rule: read `errors` by field key, fix exactly those fields, write again once.
-
-`update_content_entry` merges `data` into the stored value by top-level key: a field left out is
-kept, and a group or repeater you send still replaces that whole key. `merge: false` REPLACES the
-whole value object instead, deleting every optional field left out. Pass `ifMatch` (the
-`optimisticVersion` from `get_content_entry`) so a 409 tells you someone wrote since your read; a
-merge defaults to the version it read.
-
-## Value contract
-
-What to send. "Checked" means a bad value is refused; "yours" means the server stores what it gets.
-
-| Value | Send | Server |
-|---|---|---|
-| No value | Leave the key out. Never `null`, never `""` on an optional field | Yours. `null` skips every type check and is stored as written; `""` is stored as text. Both count as empty for `required` |
-| No value, SEO writers | Send only the keys you change | `null` or `""` CLEARS the stored key ([seo.md](seo.md) §1) |
-| Number | A JSON number: `29`, `39.99`. Never `"29"` | Checked: a string or a non-finite number is refused |
-| Money | A `number` field in major units (`39.99`, not `3999` unless the source API is in cents) plus a sibling `select` holding the ISO 4217 code. There is no money type | Number checked; unit and currency are yours |
-| Price label (`"$39/mo"`) | A separate text field, only when the page prints that exact string | Yours. Keep it in step with the number |
-| `date`, date only | `YYYY-MM-DD` | Checked: a real calendar day, no time part |
-| `date` with `includeTime: true`, `datetime` | ISO 8601 with seconds and an offset: `2026-10-14T09:00:00+05:30`, or `Z` for UTC | Time part checked. On a field with `timezone` in its config (`site`, `UTC` or an IANA name) a value without `Z` or an offset is refused. Without it the offset is accepted but not required, so a value without one is stored ambiguous: always send it |
-| `select` | One of the declared option values | Checked |
-| Plain text (`text`, `longtext`) | Words only. No tags, no entities, no markdown | Yours. Markup is stored and printed as written |
-| Formatted prose | A Portable Text array in a rich text field ([portable-text.md](portable-text.md)) | Top-level `_type` checked |
-| A list of things | A `repeater` or an `array`, never `<ul>` or line breaks in one string | Shape checked |
-| A link, a button, an image | Their own fields, never `<a>` or `<img>` in a string | Per field type |
-
-Booleans: send `false` explicitly when a condition (`showIf`) or the template reads the field.
-
-### Stable keys
-
-Keys are edit addresses: the canvas and co-editing point at them. Regenerating one
-orphans whatever pointed at it.
-
-| Where | Key | Rule |
-|---|---|---|
-| Portable Text block, span, markDef, table row and cell | `_key` | Matches `^[A-Za-z0-9-]{1,32}$` (no underscore, no dot: the address grammar splits on them), unique in the value. Write short meaningful keys (`intro`, `q-shipping`), never a position |
-| Repeater row | `_id` | Minted by the server on the first write when you send none. An `_id` you send is kept as is |
-| Entry, component, page | id and slug | Never recreate to change content: update in place |
-
-Rules:
-
-- To change a keyed value, read it, edit the items you mean to change, and send every other item
-  back with the key it came with.
-- A repeater row sent without `_id` on a later write gets a NEW one: the MCP and Management API
-  write path does not match rows to the stored ones. Always echo `_id` from the read.
-- On a re-run of a load, match each source item to its stored item by content and reuse that key.
-- `array` items (scalars) have no key. Their address is the index, so do not reorder them for style.
-
-## Dry run
-
-`create_content_entry`, `create_content_entries`, `create_content_model`, `add_field`,
-`compose_pages`, `create_redirect` and `import_redirects` take `dryRun: true`. The call runs every
-check a real one runs and writes nothing:
-no row, no ingested image, no webhook, no rebuild. The answer carries `dryRun: true` and, per item,
-`would-create` (`would-update` for a composed page) or the refusal a real run gives. A batch dry run
-also catches a slug repeated inside the batch; a repeated `unique` value shows only on the real run.
-
-Rule: dry-run a bulk write first, fix the failed rows, then send it again without `dryRun`.
-
-## Safe re-runs
-
-A load that stops halfway is run again. Write it so the second run changes nothing it already did.
-
-`create_content_entries` rows and `create_content_entry` take `externalKey` (1 to 255 characters):
-the item's id in the system it comes from. The key is unique per collection. Each keyed row answers:
-
-| Status | Meaning |
-|---|---|
-| `created` | No entry had the key. A new draft is stored under it |
-| `unchanged` | The entry exists and the row equals the one last sent. Nothing is written |
-| `updated` | The entry exists and the row differs. `data` replaces its draft; a published entry stays published with pending changes |
-| `failed` | The refusal a plain create or update gives (`FIELD_LOCKED`, a taken slug, a validation error), or the key repeated inside the batch |
-
-"Equals" compares a hash of the `slug` and `data` you send, not the stored values (image URLs are
-re-hosted on the way in), so send the same payload to get `unchanged`. With `dryRun: true` the
-statuses are `would-create`, `would-update`, `unchanged` and `failed`. Optional `source` (the source
-URL) and `runId` are kept with the entry. A row without `externalKey` always creates.
-
-`list_content_entries` takes `externalKey` (exact match) and its summaries carry the key, so a
-stopped run resumes by reading what is already stored. Only entries created with a key match.
-
-Rule: give every migrated row its source id as `externalKey`, then re-run the whole batch freely.
-Entries then need no local id map. Media, and a reference to an item not yet created, still do.
-
-What has no `externalKey` (models, components, pages, redirects, repeater rows, Portable Text):
-
-- Reuse stable identifiers: the same slug per entry, the same `_key` and `_id` per item (see Stable
-  keys), the same component id. Read the stored row and match by content before you mint anything.
-- Skip a write whose source did not change. Keep a content hash per source page and asset.
-- These answers mean "already done". Record them as success and move on:
-
-| Answer | From | Why it is success |
-|---|---|---|
-| `ALREADY_COMPONENTIZED` | `componentize_sections` | The group is already placed as a component; nothing is written |
-| `existing` on a row | `import_redirects` | The same rule is already stored |
-| 409 `slug_taken` on a row you created earlier in this load | entry or model create without `externalKey` | Switch to update for that row |
-| 409 `EXTERNAL_KEY_TAKEN` | a keyed entry create that raced another write | Send the row again: it matches that entry |
-
-- A `create_redirect` 409 means a rule for that source exists, identical or not: the tool does
-  not tell the two apart. Read it with `list_redirects` and decide. On a re-run use
-  `import_redirects`, which answers `existing` for a rule already stored as sent.
-- Batch writes report each row. One failed row does not stop the rest: record the failures, fix
-  them, re-run only those rows.
-- Before a bulk load, write ONE entry per collection, read it back, open its page, then load the
-  rest. A wrong shape costs one entry instead of hundreds.
-- Create reference targets before the entries that point at them, or the write is refused with
-  `ref_missing`.
-
-## Limits that exist
-
-| Limit | Behaviour |
-|---|---|
-| `maxLength` / `minLength` in text field config | Counted in characters. An empty value is left to `required` |
-| `pattern` in text field config | Tested against every non-empty value |
-| Numeric limit config (`maxLength`, `minLength`, `min`, `max`, `step`) on model save | A numeric string (`"60"`) is stored as a number; an impossible value (`"abc"`, a negative length, `step: 0`, `min` above `max`, a pattern that does not compile) is refused with `FIELD_CONFIG_INVALID`, naming the field and the fix |
-| Repeater `maxItems` | Enforced when a number |
-| `select` value | Must be one of the field's options |
-| Rich text top-level `_type` | A name nothing renders is refused, naming `_type` and `_key`. Top level only — a foreign mark keeps its text unmarked, a foreign inline child renders nothing |
-| Reference target | Each referenced entry id must exist in the workspace: 400 `ref_missing`, keyed by field. A reference chain that loops back to the entry is refused with 400 and `errors._base` |
-| Request body | 260 MB for the whole server |
-
-## Limits that do not exist (you hold them)
-
-| Missing check | Rule for the agent |
-|---|---|
-| Limit config saved as a string before the model-save check existed | Write every numeric config value as a JSON number; re-save a model you find with string limits |
-| Modular (block) field `blockSlugs`, `minItems`, `maxItems` | Check the block list against the field config yourself before writing |
-| A reference to a trashed entry (stored, with a warning) | Read `warnings` after the write; repoint or restore the target |
-| Markup inside plain text; a datetime with no offset; `null` on an optional field | Follow the value contract above |
-| Component `overrides` (any keys, any types; required props not enforced) | Write only declared prop keys with the declared type; fill every prop the component needs |
-| Size or depth of text, richtext and JSON values | Keep values to what the page renders; never paste whole documents into one field |
-| Publish re-validation (publish copies the draft to live) | Only publish a draft you wrote through the write path above |
-| Version restore re-validation (restore writes the stored snapshot) | After a restore, read the entry and write it back through `update_content_entry` so checks run |
-
-## Normaliser output shapes
-
-What you read back after a write:
-
-| Field | Stored shape |
-|---|---|
-| richtext | `{ format, value, html }` envelope |
-| image | `{ id, url, name, altText }`. An asset id or media URL resolves to its asset; a site-relative path resolves to the asset the build adopted; an external URL on a project-scoped write is fetched and stored as a new asset. Only when none of that works (fetch refused or failed, no project scope) is it kept as `{ url }` (plus `altText` if given) |
-| group / repeater (zoned) | Zone envelopes `{ nonRepeatable, repeatable }`, walked field by field |
-| repeater given a bare array | Wrapped as `{ repeatable: [...] }` |
-
-Rich text written as HTML or markdown may be stored in the older Lexical format depending on a
-server flag. Portable Text arrays are always stored as Portable Text
-([portable-text.md](portable-text.md)).
-
-A stored value of `{ html }` is the shape starter templates and `bcms-content.json` seed. Writes
-accept it and store the full envelope, so sending an entry's data back unchanged works. Do not
-write new rich text in that shape.
-
-## Other refusal codes that exist today
-
-| Area | Codes | Where described |
-|---|---|---|
-| Content sidebar structure | `NAV_SYSTEM_FOLDER`, `NAV_TYPE_MISMATCH`, `NAV_KIND_MISMATCH`, `NAV_PAGE_BOUND_MODEL`, `SCHEMA_ACCESS_REQUIRED` | the folder tool descriptions |
-| Hosting | `HEADLESS_NO_BUILD`, `HEADLESS_NEEDS_CUSTOM_HOST`, `HEADLESS_ARTIFACT_TARGET` | [frameworks.md](frameworks.md) |
-| Components | `COMPONENT_*` publish codes | [components.md](components.md) §4 |
-| Content models | `FIELD_CONFIG_INVALID` | this file |
-| Entries | `FIELD_LOCKED` (403: the write changes or omits a `readOnly: "developer"` field without schema access; carries `field` and `lockReason`), `EXTERNAL_KEY_TAKEN` (409) | [content-modeling.md](content-modeling.md) §4, Safe re-runs above |
-| Forms | `FORM_FIELD_INVALID`, `FORM_DEFINITION_INVALID`, `FORMS_WORKER_NOT_CONFIGURED`, `FORMS_WORKER_SECRET_UNSET`, `FORM_SUBMISSION_NOT_FOUND`, `FORM_SECRET_DASHBOARD_ONLY` | [forms-and-interactions.md](forms-and-interactions.md) |
-
-`SCHEMA_ACCESS_REQUIRED` (403): see the owner boundary in SKILL.md.
-
-## What each refusal means and what to do next
-
-| Answer | Meaning | Next step |
-|---|---|---|
-| 400 `{ errors }`, no code | A value failed the request schema or a field check | Fix exactly the named fields, write once more |
-| 400 `ref_missing` | A reference field names an entry id that is not in this workspace. `errors` is keyed by the field | Create or find the target first, then write the real id. Never invent an id |
-| 400 `FIELD_CONFIG_INVALID` | A model or component save carries an impossible setting: a limit that is not a number, `min` above `max`, `step: 0`, a pattern that does not compile, a prop `defaultValue` of the wrong type. The message names the field and the setting | Send a value that makes sense for that setting |
-| 400 `PROJECT_REQUIRED` | A delivery read with no project scope hit a slug that exists in more than one project of the workspace | Add `?projectId=` to the read, or use a project-scoped API key |
-| 409 `slug_taken` | The slug is in use. Entries: `slug` plus `suggestions`. Models: `code`, `suggestions` and `errors.slug` | Read the existing row first: on a re-run it is usually yours, so update it. Otherwise take one of `suggestions` |
-| 409 `EXTERNAL_KEY_TAKEN` | Another write created an entry with the same `externalKey` at the same moment | Send the row again: it matches that entry and answers `updated` or `unchanged` |
-| 403 `FIELD_LOCKED` | The write changes a `readOnly: "developer"` field and the caller has no schema access. Carries `field` and `lockReason` | Send the stored value back for that field, or ask an Admin or Developer to change it |
-| 403 `SCHEMA_ACCESS_REQUIRED` | A model save adds or removes a lock (`readOnly: "developer"`, `lockReason`) without schema access | Send the fields with their stored lock, or ask an Admin or Developer |
-| 409 `unique_conflict` | Another entry already holds this value in a unique field. `conflicts` names it | Match to that entry and update it; do not create a twin |
-| 409 `locale_conflict` | The translation group already has an entry in that locale. `errors` names `locale` or `translationOf` | Edit the existing translation |
-| 409 `Version conflict` (entries), `VERSION_CONFLICT` (sidebar, section zones) | Someone wrote since your read. The entry body carries `currentVersion` | Read again, re-apply your change to the fresh value, write with the new version |
-| 409 `stale-plan` | The site changed after the componentize plan was read; `digest` is the current one | `get_componentize_plan` again, re-confirm, resubmit with the new digest |
-| 409 `style-edits` | The conversion receipt lists changed classes or styles. `styleEdits` holds up to 40 tokens | Restore every token, rerun `npx @bettercms-ai/convert --verify-styles`, resubmit the receipt |
-| 400 `digest-mismatch` | The receipt was built for a different brief | Read the brief again and rebuild the receipt against it |
-| 422 `PRESENTATION_INVALID` | `update_project` got a `presentation` value the renderer cannot use. `error` names the key | Fix that key; other settings in the same call were not saved |
-| Warning `UNPROPPED_COPY` | A saved component holds copy no prop targets, so it is not editable. The line lists up to 8 leaves as `<blockType>#<blockId>.<path>` | Declare a prop with a matching `target` for each leaf. The save itself succeeded |
-| Warning `REFERENCE_NOT_FOUND` | A reference points at a trashed entry. Stored anyway | Repoint the field or restore the target |
-
-Component, form, hosting and sidebar codes: the table above.
+---
+title: "Write limits"
+description: "What the server checks on a content write (lengths, patterns, uniqueness, references, body size) and what it does not."
+---
+
+# Write limits: what the server checks on a content write
+
+Use this before you rely on a limit. "Exists" means the server refuses a bad value. "Does not
+exist" means the value is stored, so you are the check.
+
+## The write path
+
+Entry writes from the MCP and the Management API run `createEntry` / `updateEntry` in
+`src/lib/content/entry-write.ts`:
+
+1. Request schema (Zod). Failure: 400 with `{ errors }`, keyed by field, no `code`.
+2. Value normalisation (shapes below). Failure: a validation result with `errors`.
+3. Reference existence. Every entry id in a reference field is looked up in the workspace. A
+   missing one is refused: 400 `ref_missing`, with `errors` keyed by the field that holds it. A
+   target that exists but sits in the trash is stored, and the result carries a `warnings` line
+   starting `REFERENCE_NOT_FOUND:` that names the field. A reference loop is refused with 400
+   and `errors._base`.
+4. Per-field value checks against the model. Failure: a validation result with `errors`.
+5. Uniqueness, inside the insert transaction. Failure: `kind: "unique_conflict"` with `conflicts`.
+
+The batch route reports steps 2, 4 and 5 as `code: "UNIQUE_CONFLICT"` or `"VALIDATION"`.
+
+Rule: read `errors` by field key, fix exactly those fields, write again once.
+
+`update_content_entry` merges `data` into the stored value by top-level key: a field left out is
+kept, and a group or repeater you send still replaces that whole key. `merge: false` REPLACES the
+whole value object instead, deleting every optional field left out. Pass `ifMatch` (the
+`optimisticVersion` from `get_content_entry`) so a 409 tells you someone wrote since your read; a
+merge defaults to the version it read.
+
+## Value contract
+
+What to send. "Checked" means a bad value is refused; "yours" means the server stores what it gets.
+
+| Value | Send | Server |
+|---|---|---|
+| No value | Leave the key out. Never `null`, never `""` on an optional field | Yours. `null` skips every type check and is stored as written; `""` is stored as text. Both count as empty for `required` |
+| No value, SEO writers | Send only the keys you change | `null` or `""` CLEARS the stored key ([seo.md](seo.md) §1) |
+| Number | A JSON number: `29`, `39.99`. Never `"29"` | Checked: a string or a non-finite number is refused |
+| Money | A `number` field in major units (`39.99`, not `3999` unless the source API is in cents) plus a sibling `select` holding the ISO 4217 code. There is no money type | Number checked; unit and currency are yours |
+| Price label (`"$39/mo"`) | A separate text field, only when the page prints that exact string | Yours. Keep it in step with the number |
+| `date`, date only | `YYYY-MM-DD` | Checked: a real calendar day, no time part |
+| `date` with `includeTime: true`, `datetime` | ISO 8601 with seconds and an offset: `2026-10-14T09:00:00+05:30`, or `Z` for UTC | Time part checked. On a field with `timezone` in its config (`site`, `UTC` or an IANA name) a value without `Z` or an offset is refused. Without it the offset is accepted but not required, so a value without one is stored ambiguous: always send it |
+| `select` | One of the declared option values | Checked |
+| Plain text (`text`, `longtext`) | Words only. No tags, no entities, no markdown | Yours. Markup is stored and printed as written |
+| Formatted prose | A Portable Text array in a rich text field ([portable-text.md](portable-text.md)) | Top-level `_type` checked |
+| A list of things | A `repeater` or an `array`, never `<ul>` or line breaks in one string | Shape checked |
+| A link, a button, an image | Their own fields, never `<a>` or `<img>` in a string | Per field type |
+
+Booleans: send `false` explicitly when a condition (`showIf`) or the template reads the field.
+
+### Stable keys
+
+Keys are edit addresses: the canvas and co-editing point at them. Regenerating one
+orphans whatever pointed at it.
+
+| Where | Key | Rule |
+|---|---|---|
+| Portable Text block, span, markDef, table row and cell | `_key` | Matches `^[A-Za-z0-9-]{1,32}$` (no underscore, no dot: the address grammar splits on them), unique in the value. Write short meaningful keys (`intro`, `q-shipping`), never a position |
+| Repeater row | `_id` | Minted by the server on the first write when you send none. An `_id` you send is kept as is |
+| Entry, component, page | id and slug | Never recreate to change content: update in place |
+
+Rules:
+
+- To change a keyed value, read it, edit the items you mean to change, and send every other item
+  back with the key it came with.
+- A repeater row sent without `_id` on a later write gets a NEW one: the MCP and Management API
+  write path does not match rows to the stored ones. Always echo `_id` from the read.
+- On a re-run of a load, match each source item to its stored item by content and reuse that key.
+- `array` items (scalars) have no key. Their address is the index, so do not reorder them for style.
+
+## Dry run
+
+`create_content_entry`, `create_content_entries`, `create_content_model`, `add_field`,
+`compose_pages`, `create_redirect` and `import_redirects` take `dryRun: true`. The call runs every
+check a real one runs and writes nothing:
+no row, no ingested image, no webhook, no rebuild. The answer carries `dryRun: true` and, per item,
+`would-create` (`would-update` for a composed page) or the refusal a real run gives. A batch dry run
+also catches a slug repeated inside the batch; a repeated `unique` value shows only on the real run.
+
+Rule: dry-run a bulk write first, fix the failed rows, then send it again without `dryRun`.
+
+## Safe re-runs
+
+A load that stops halfway is run again. Write it so the second run changes nothing it already did.
+
+`create_content_entries` rows and `create_content_entry` take `externalKey` (1 to 255 characters):
+the item's id in the system it comes from. The key is unique per collection. Each keyed row answers:
+
+| Status | Meaning |
+|---|---|
+| `created` | No entry had the key. A new draft is stored under it |
+| `unchanged` | The entry exists and the row equals the one last sent. Nothing is written |
+| `updated` | The entry exists and the row differs. `data` replaces its draft; a published entry stays published with pending changes |
+| `failed` | The refusal a plain create or update gives (`FIELD_LOCKED`, a taken slug, a validation error), or the key repeated inside the batch |
+
+"Equals" compares a hash of the `slug` and `data` you send, not the stored values (image URLs are
+re-hosted on the way in), so send the same payload to get `unchanged`. With `dryRun: true` the
+statuses are `would-create`, `would-update`, `unchanged` and `failed`. Optional `source` (the source
+URL) and `runId` are kept with the entry. A row without `externalKey` always creates.
+
+`list_content_entries` takes `externalKey` (exact match) and its summaries carry the key, so a
+stopped run resumes by reading what is already stored. Only entries created with a key match.
+
+Rule: give every migrated row its source id as `externalKey`, then re-run the whole batch freely.
+Entries then need no local id map. Media, and a reference to an item not yet created, still do.
+
+What has no `externalKey` (models, components, pages, redirects, repeater rows, Portable Text):
+
+- Reuse stable identifiers: the same slug per entry, the same `_key` and `_id` per item (see Stable
+  keys), the same component id. Read the stored row and match by content before you mint anything.
+- Skip a write whose source did not change. Keep a content hash per source page and asset.
+- These answers mean "already done". Record them as success and move on:
+
+| Answer | From | Why it is success |
+|---|---|---|
+| `ALREADY_COMPONENTIZED` | `componentize_sections` | The group is already placed as a component; nothing is written |
+| `existing` on a row | `import_redirects` | The same rule is already stored |
+| 409 `slug_taken` on a row you created earlier in this load | entry or model create without `externalKey` | Switch to update for that row |
+| 409 `EXTERNAL_KEY_TAKEN` | a keyed entry create that raced another write | Send the row again: it matches that entry |
+
+- A `create_redirect` 409 means a rule for that source exists, identical or not: the tool does
+  not tell the two apart. Read it with `list_redirects` and decide. On a re-run use
+  `import_redirects`, which answers `existing` for a rule already stored as sent.
+- Batch writes report each row. One failed row does not stop the rest: record the failures, fix
+  them, re-run only those rows.
+- Before a bulk load, write ONE entry per collection, read it back, open its page, then load the
+  rest. A wrong shape costs one entry instead of hundreds.
+- Create reference targets before the entries that point at them, or the write is refused with
+  `ref_missing`.
+
+## Limits that exist
+
+| Limit | Behaviour |
+|---|---|
+| `maxLength` / `minLength` in text field config | Counted in characters. An empty value is left to `required` |
+| `pattern` in text field config | Tested against every non-empty value |
+| Numeric limit config (`maxLength`, `minLength`, `min`, `max`, `step`) on model save | A numeric string (`"60"`) is stored as a number; an impossible value (`"abc"`, a negative length, `step: 0`, `min` above `max`, a pattern that does not compile) is refused with `FIELD_CONFIG_INVALID`, naming the field and the fix |
+| Repeater `maxItems` | Enforced when a number |
+| `select` value | Must be one of the field's options |
+| Rich text top-level `_type` | A name nothing renders is refused, naming `_type` and `_key`. Top level only — a foreign mark keeps its text unmarked, a foreign inline child renders nothing |
+| Reference target | Each referenced entry id must exist in the workspace: 400 `ref_missing`, keyed by field. A reference chain that loops back to the entry is refused with 400 and `errors._base` |
+| Request body | 260 MB for the whole server |
+
+## Limits that do not exist (you hold them)
+
+| Missing check | Rule for the agent |
+|---|---|
+| Limit config saved as a string before the model-save check existed | Write every numeric config value as a JSON number; re-save a model you find with string limits |
+| Modular (block) field `blockSlugs`, `minItems`, `maxItems` | Check the block list against the field config yourself before writing |
+| A reference to a trashed entry (stored, with a warning) | Read `warnings` after the write; repoint or restore the target |
+| Markup inside plain text; a datetime with no offset; `null` on an optional field | Follow the value contract above |
+| Component `overrides` (any keys, any types; required props not enforced) | Write only declared prop keys with the declared type; fill every prop the component needs |
+| Size or depth of text, richtext and JSON values | Keep values to what the page renders; never paste whole documents into one field |
+| Publish re-validation (publish copies the draft to live) | Only publish a draft you wrote through the write path above |
+| Version restore re-validation (restore writes the stored snapshot) | After a restore, read the entry and write it back through `update_content_entry` so checks run |
+
+## Normaliser output shapes
+
+What you read back after a write:
+
+| Field | Stored shape |
+|---|---|
+| richtext | `{ format, value, html }` envelope |
+| image | `{ id, url, name, altText }`. An asset id or media URL resolves to its asset; a site-relative path resolves to the asset the build adopted; an external URL on a project-scoped write is fetched and stored as a new asset. Only when none of that works (fetch refused or failed, no project scope) is it kept as `{ url }` (plus `altText` if given) |
+| group / repeater (zoned) | Zone envelopes `{ nonRepeatable, repeatable }`, walked field by field |
+| repeater given a bare array | Wrapped as `{ repeatable: [...] }` |
+
+Rich text written as HTML or markdown may be stored in the older Lexical format depending on a
+server flag. Portable Text arrays are always stored as Portable Text
+([portable-text.md](portable-text.md)).
+
+A stored value of `{ html }` is the shape starter templates and `bcms-content.json` seed. Writes
+accept it and store the full envelope, so sending an entry's data back unchanged works. Do not
+write new rich text in that shape.
+
+## Other refusal codes that exist today
+
+| Area | Codes | Where described |
+|---|---|---|
+| Content sidebar structure | `NAV_SYSTEM_FOLDER`, `NAV_TYPE_MISMATCH`, `NAV_KIND_MISMATCH`, `NAV_PAGE_BOUND_MODEL`, `SCHEMA_ACCESS_REQUIRED` | the folder tool descriptions |
+| Hosting | `HEADLESS_NO_BUILD`, `HEADLESS_NEEDS_CUSTOM_HOST`, `HEADLESS_ARTIFACT_TARGET` | [frameworks.md](frameworks.md) |
+| Components | `COMPONENT_*` publish codes | [components.md](components.md) §4 |
+| Content models | `FIELD_CONFIG_INVALID` | this file |
+| Entries | `FIELD_LOCKED` (403: the write changes or omits a `readOnly: "developer"` field without schema access; carries `field` and `lockReason`), `EXTERNAL_KEY_TAKEN` (409) | [content-modeling.md](content-modeling.md) §4, Safe re-runs above |
+| Forms | `FORM_FIELD_INVALID`, `FORM_DEFINITION_INVALID`, `FORMS_WORKER_NOT_CONFIGURED`, `FORMS_WORKER_SECRET_UNSET`, `FORM_SUBMISSION_NOT_FOUND`, `FORM_SECRET_DASHBOARD_ONLY` | [forms-and-interactions.md](forms-and-interactions.md) |
+
+`SCHEMA_ACCESS_REQUIRED` (403): see the owner boundary in SKILL.md.
+
+## What each refusal means and what to do next
+
+| Answer | Meaning | Next step |
+|---|---|---|
+| 400 `{ errors }`, no code | A value failed the request schema or a field check | Fix exactly the named fields, write once more |
+| 400 `ref_missing` | A reference field names an entry id that is not in this workspace. `errors` is keyed by the field | Create or find the target first, then write the real id. Never invent an id |
+| 400 `FIELD_CONFIG_INVALID` | A model or component save carries an impossible setting: a limit that is not a number, `min` above `max`, `step: 0`, a pattern that does not compile, a prop `defaultValue` of the wrong type. The message names the field and the setting | Send a value that makes sense for that setting |
+| 400 `PROJECT_REQUIRED` | A delivery read with no project scope hit a slug that exists in more than one project of the workspace | Add `?projectId=` to the read, or use a project-scoped API key |
+| 409 `slug_taken` | The slug is in use. Entries: `slug` plus `suggestions`. Models: `code`, `suggestions` and `errors.slug` | Read the existing row first: on a re-run it is usually yours, so update it. Otherwise take one of `suggestions` |
+| 409 `EXTERNAL_KEY_TAKEN` | Another write created an entry with the same `externalKey` at the same moment | Send the row again: it matches that entry and answers `updated` or `unchanged` |
+| 403 `FIELD_LOCKED` | The write changes a `readOnly: "developer"` field and the caller has no schema access. Carries `field` and `lockReason` | Send the stored value back for that field, or ask an Admin or Developer to change it |
+| 403 `SCHEMA_ACCESS_REQUIRED` | A model save adds or removes a lock (`readOnly: "developer"`, `lockReason`) without schema access | Send the fields with their stored lock, or ask an Admin or Developer |
+| 409 `unique_conflict` | Another entry already holds this value in a unique field. `conflicts` names it | Match to that entry and update it; do not create a twin |
+| 409 `locale_conflict` | The translation group already has an entry in that locale. `errors` names `locale` or `translationOf` | Edit the existing translation |
+| 409 `Version conflict` (entries), `VERSION_CONFLICT` (sidebar, section zones) | Someone wrote since your read. The entry body carries `currentVersion` | Read again, re-apply your change to the fresh value, write with the new version |
+| 409 `stale-plan` | The site changed after the componentize plan was read; `digest` is the current one | `get_componentize_plan` again, re-confirm, resubmit with the new digest |
+| 409 `style-edits` | The conversion receipt lists changed classes or styles. `styleEdits` holds up to 40 tokens | Restore every token, rerun `npx @bettercms-ai/convert --verify-styles`, resubmit the receipt |
+| 400 `digest-mismatch` | The receipt was built for a different brief | Read the brief again and rebuild the receipt against it |
+| 422 `PRESENTATION_INVALID` | `update_project` got a `presentation` value the renderer cannot use. `error` names the key | Fix that key; other settings in the same call were not saved |
+| Warning `UNPROPPED_COPY` | A saved component holds copy no prop targets, so it is not editable. The line lists up to 8 leaves as `<blockType>#<blockId>.<path>` | Declare a prop with a matching `target` for each leaf. The save itself succeeded |
+| Warning `REFERENCE_NOT_FOUND` | A reference points at a trashed entry. Stored anyway | Repoint the field or restore the target |
+
+Component, form, hosting and sidebar codes: the table above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.83.0",
+  "version": "0.83.2",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {