This is the compact, AI-facing design and authoring contract for WebBlocks CMS. Read it before proposing or applying a page design through the Internal Content API.

It answers five questions for every shipped core block:

1. What content remains editable in the CMS admin?
2. Which shared settings and variants are supported?
3. Which child and media relationships are valid?
4. What stable public HTML does the renderer emit?
5. What visual result can the block produce without raw page HTML?

This document summarizes source-backed behavior. Live API discovery remains authoritative for install-specific IDs, enabled plugins, custom block types, locales, layouts, media records, navigation menus, and capabilities.

• Repository: fklavyenet/webblocks-cms
• Branch: main
• Audited commit: 741a44bc0fe00bf38cae0753bd9edb02978b0dbe
• Audited release documentation: 1.40.2
• Audit date: 2026-07-14
• Repository shape: package-only Composer package
• Published core catalog rows: 51
• Draft legacy catalog rows: 7
• AI-writable structured core rows after the policy below is enforced: 50
• AI-writable raw HTML rows after the policy below is enforced: 0

The baseline above is still the last full audit. These entries were corrected against source afterwards rather than re-auditing every block, so treat anything outside this list as 1.40.2-era and confirm it through live API discovery.

• card (1.40.5): the Card style variant exists. This document previously stated that no supported Card visual variant field existed, which was wrong from 1.40.5 onward.
• link-list (1.40.10): settings.row_layout and settings.list_frame.
• link-list-item (1.40.8): optional media_id thumbnail.
• 1.91.0: optional mobile-image relationships on eight native media blocks.
• 1.91.1: all nine Slide and Slider content positions.
• 1.93.0: Rich Text undo/redo, focus mode, word count, and safe paste behavior.
• 1.94.0–1.94.2: managed-plugin startup validation, quarantine, retained packages, and active-account recovery checks.

Historical repository note: the pre-package-only CMS tree contained docs/feature-inventory.md, a broad product-feature discoverability matrix. It was removed when the package-only repository tree was constructed and was not a per-block AI authoring inventory. The runtime contract now lives at resources/contracts/inventory.md.

Source families inspected:

• src/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• src/Support/BlockTypes/BlockTypeContractRegistry.php
• src/Support/Blocks/BlockTranslationRegistry.php
• src/Models/Block.php
• src/Http/Requests/Admin/BlockRequest.php
• src/Support/InternalContentApi/InternalContentPlanService.php
• src/Support/InternalContentApi/InternalContentApiOperations.php
• src/Http/Controllers/InternalContentApi/InternalContentResourceController.php
• src/Http/Controllers/InternalContentApi/InternalSharedSlotController.php
• src/Http/Controllers/InternalContentApi/InternalApiDiscoveryController.php
• routes/admin.php
• resources/views/admin/blocks/types/*.blade.php
• resources/views/admin/blocks/settings/*.blade.php
• resources/views/pages/partials/blocks/*.blade.php
• public/cms/css/public.css
• focused package tests and current product documentation

1. Use structured blocks. Do not store a page, section, card collection, navigation shell, form, or visual component in Trusted HTML.
2. html is a human-only escape hatch. API discovery may identify it as unavailable, but no API mutation may create, update, replace, move, reorder, clone, promote, publish, or delete an HTML block.
3. Do not bypass the HTML restriction through Rich Text, <style>, <script>, event-handler attributes, iframe markup, SVG markup, encoded markup, or invented settings.
4. Use only fields, enum values, media roles, and child relationships documented here and confirmed by live discovery.
5. Treat an admin-editable field as part of the supported authoring contract. A value recognized only by a renderer or legacy compatibility path is not a normal AI authoring field.
6. If a visual region cannot be expressed with the supported contract, stop and report a capability gap. Do not silently approximate it with unrelated blocks and do not fall back to HTML.
7. Site CSS may refine typography, spacing, color, borders, shadows, and responsive presentation through stable public hooks. It must not become a hidden content store or reconstruct missing semantic markup.
8. Do not target database IDs, generated block IDs, sibling position selectors, or :nth-child() for essential design behavior. Prefer block-type attributes, native wb-* classes, page body classes, and documented settings.
9. Keep every visible title, paragraph, label, button, badge, image, caption, menu, and form setting editable through its native CMS field or related record.
10. Validate first, apply only after explicit user approval, create drafts first, and leave live system-update actions and live visual testing to the human operator unless separately authorized.
11. Treat Card as opt-in presentation, not the default way to group related copy. Use a Card only for an independently actionable, repeatable, or bounded entity such as a product, plugin, price plan, download, or form.
12. Before choosing blocks, state one site-level design direction covering character, density, typography, geometry, imagery, corners, and contrast. Make the block tree and site CSS implement that direction instead of choosing each section in isolation.
13. Vary page rhythm deliberately. Combine narrow, regular, wide, and full-width regions; alternate quiet copy, dominant imagery, and structured collections rather than repeating equally weighted sections.

The target product contract is:

This policy is enforced in code by a single product policy class, WebBlocks\Cms\Support\BlockTypes\BlockTypeApiAuthoringPolicy. Every API surface consults it instead of repeating the rule: both block normalizers, existing-block PATCH, page and Shared Slot incremental create, page/Shared Slot reorder, subtree delete, Shared Slot clear-all, page and Shared Slot publish, draft slot replacement, staged update creation and promotion, Shared Slot assignment, and API page delete. Rejections happen before any transaction or write, return HTTP 422 with the stable code block_type_not_api_writable, and leave no partial changes. No token capability overrides it.

A design is CMS-manageable only when all of the following are true:

• Visible content is stored in native translation fields, settings, Media Library relations, Navigation records, Commerce records, or child blocks.
• The normal block editor exposes the fields needed to maintain the result.
• Public markup comes from a package or plugin renderer, not from page content.
• Presentation uses documented variants, settings, theme tokens, and stable CSS hooks.
• Reordering or editing content does not require editing HTML or CSS.
• Mobile behavior comes from the renderer, WebBlocks UI, or stable site CSS rather than duplicated mobile markup in content.

A renderer may recognize a legacy or internal value that the normal admin form does not expose. Such a value is documented as a compatibility input, not as a recommended AI authoring field.

Use nested children arrays. Do not submit database relationship IDs in a content plan.

Content-plan conventions:

• Put locale-owned copy directly under translations for the selected plan locale.
• Put URL, target, presentation variant, and other shared options under settings.
• Put direct Media Library assignment in media_id.
• slide, image, hero, section, card, cta, content_header, and link-list-item also accept an optional top-level mobile_media_id referencing an image Media Library record. It is stored in block_media with role mobile_image, shared across locales, and editable through the admin media picker and PATCH /blocks/{block}. On screens up to 768 px wide it replaces the default image; an absent, deleted, or private mobile image falls back to the default. Send null to clear it; omitting it in PATCH preserves it. Foreground images use <picture><source media="(max-width: 768px)">; background blocks use a responsive CSS background. Use another crop of the same visual: alt text, captions, position, fit, overlays, and links stay shared. The Image block's Gallery Viewer continues to open the default full-resolution image. Gallery items, brand logos, video, and audio do not accept this field.
• Put Gallery items in gallery_items or gallery_media_ids.
• Use only nested children; do not send id, parent_id, block_id, slot_type_id, or block_type_id.
• The API currently accepts a broadly shaped settings object. That permissiveness is not permission to invent settings; use only the keys listed below.

Normal main-slot rendering provides:

Blocks marked root-owning place data-wb-public-block-type on their own semantic root. Other top-level blocks normally receive:

Underscores normalize to hyphens in data-wb-public-block-type; for example content_header becomes content-header.

The current published core catalog contains 55 rows:

Use plain for qualities, principles, benefits, process summaries, and other copy that does not represent independent objects. Use cards only when every item has a meaningful boundary of its own. The number of items — especially the familiar set of three — is never by itself a reason to choose cards.

Do not treat a Blade partial as proof that a handle is available for new API content. The current source contains compatibility renderers and draft rows that are not published core authoring contracts.

Draft catalog rows include:

Renderer-only, alias, partial, or compatibility handles include examples such as:

Rules:

• Never author these merely because a renderer file exists.
• Use them only if the live authenticated block catalog reports the exact handle as published and usable for the current install.
• Prefer canonical structured blocks documented above.
• Internal partials such as gallery viewer and sidebar link renderers are never content-plan block types.

These are managed block trees, not fixed templates. Confirm all handles at runtime.

Start from the least framed recipe that satisfies the content. Do not repeat the same recipe in adjacent page bands, and do not select the feature-card recipe merely because the source contains three short items.

Use a large, meaningful image and restrained surface styling. Choose layout:full-bleed when the image should become a viewport-wide, unframed opening band; retain split when the image is semantic foreground content.

This is the normal starting point for qualities such as experience, communication, care, speed, or reliability. Promote it to Cards only when the items are independently actionable or bounded.

Use this only when the action row should sit outside the Hero promo root. Hero itself accepts Button Link children in every layout, including split; keep actions inside Hero when that is the intended composition.

Every title, paragraph, and action remains independently editable. Reserve this recipe for bounded entities such as products, plugins, plans, downloads, or services with their own actions. Use site CSS for a consistent site-specific Card skin through stable hooks; do not inject card HTML.

Use Image for foreground media. Use a background-capable block only when the image is semantically a background.

Navigation labels and URLs belong to CMS Navigation records, not to HTML.

Before applying a visual design, produce a mapping table:

For each region:

1. Identify every editable piece of copy, media, action, badge, navigation data, and dynamic record.
2. Map each piece to an admin-editable native field.
3. Confirm parent/child rules and renderer HTML.
4. Confirm the visual composition is possible with the documented DOM.
5. Use site CSS only for presentation that the stable DOM can support.
6. If any semantic field, wrapper, slot, or variant is missing, mark the region unsupported.
7. Propose the smallest reusable CMS or plugin capability: a renderer variant, a new structured block, a pattern composed of existing blocks, or a domain block such as a Commerce product collection.
8. Do not apply a knowingly low-fidelity substitute unless the user explicitly approves that compromise.

Capability-gap report format:

Use styling layers in this order:

1. WebBlocks UI primitives already emitted by the renderer.
2. Public Theme tokens and mode-aware public color roles.
3. Native block settings and variants.
4. Narrow site-specific CSS using stable hooks.
5. A reusable renderer or block contract change when the required DOM is missing.

Stable selectors include:

Do not use site CSS to:

• insert essential text with pseudo-elements;
• depend on generated block IDs;
• infer semantics from sibling order;
• hide CMS-authored content merely to replace it with CSS content;
• rebuild a missing layout with fragile absolute positioning;
• hardcode light-only colors that break Light/Dark/Auto mode.

These are implementation findings, not permissions to invent behavior:

1. Resolved: this inventory now ships as resources/contracts/inventory.md and is served to tools by GET /webadmin/api/inventory.
2. webblocks-cms-docs/docs/block-type-contracts.md says 42 published core types, while the current catalog defines 51.
3. Several existing docs still show pre-package-only renderer paths under packages/webblocks-cms/...; current package paths begin at resources/views/....
4. Resolved: Trusted HTML is no longer API-writable. BlockTypeApiAuthoringPolicy blocks every API mutation path, including generic normalization, existing-block PATCH, and the Shared Slot reorder, subtree-delete, clear-all, and publish operations.
5. Resolved: Hero and CTA are plain containers for button_link children in both the admin and the API. The primary_cta / secondary_cta fields survive as a two-button shorthand. The unpublished legacy button catalog row is no longer an authoring blocker.
6. Resolved: the Column Item editor now exposes the subtitle field that the Columns stats variant renders as the stat value.
7. Audio has a normal admin media picker and public media renderer, but the content-plan direct-media allowlist omits Audio.
8. Resolved: icon normalization has one owner. InternalContentApiOperations holds the canonical PUBLIC_ICON_BLOCK_TYPES list plus the shared slug/tone normalizers, and the full content plan delegates to them, so plans and incremental block endpoints validate icons identically.
9. API block settings are not yet governed by one per-block machine-readable settings schema. Unknown settings can survive normalization even when no renderer or admin field uses them.
10. Resolved: navigation-auto now has a documented contract in BlockTypeContractRegistry and is discoverable through block-types and content-contract.
11. WebBlocks UI ships a wb-footer-* anatomy (wb-footer-grid, wb-footer-brand, wb-footer-nav, wb-footer-link, wb-footer-list, wb-footer-item, wb-footer-copy, wb-footer-meta, wb-footer-text, wb-footer-logo) that no CMS renderer emits. A shared-slot footer composes generic wb-section/wb-container/wb-grid/wb-stack/wb-cluster instead, so the pattern is reachable only from hand-written layouts. Cosmetic since 1.50.0 gave .wb-slot-footer its own surface; a footer-composition block remains deliberately deferred rather than pending.
12. Resolved: GET /content-contract derives its media_library section from the registered route table, so supported_operations and unsupported_operations cannot drift from what openapi.json publishes. Upload, remote fetch, delete, replace and move are published as supported with the capability each route enforces.
13. Resolved: consent has a visitor-facing half. The System Settings banner toggle renders WebBlocks UI's Cookie Consent pattern on public pages and wires it to the existing POST /privacy-consent/sync endpoint, and contact_form gained settings.consent_required plus a translated consent_label recorded on each submission.
14. The repository has dashboard and page-management screenshots, but no canonical per-block/per-variant visual fixture gallery. The “Example appearance” descriptions in this inventory are therefore source-derived, not screenshot-backed golden references. Until that gallery exists, prefer documented neutral compositions and avoid claiming visual fidelity from prose alone.
15. Resolved for planning: GET /content-contract now publishes a machine-readable design-direction contract covering character, density, typography, geometry, imagery, corners, contrast, rhythm roles, Card policy, and known composition gaps. It deliberately does not persist a hidden style record; AI tools state the direction in their plan/report and implement it through supported block choices, theme tokens, and stable site CSS.

The product owns this runtime contract. The documentation repository keeps a generated version snapshot with a distinct source identity; edits start in the product contract.

From CMS 1.94.3, composer test:inventory and composer test:docs validate resources/contracts/inventory-review.json against the current contract and runtime source fingerprints. Changed, added, or removed runtime files and product version changes require a new explicit review. CI and pre-push run the same check; release preparation checks the working tree, and the artifact builder checks the selected Git tree.

After reviewing supported fields, enums, children, media, rendering, editor behavior, permissions, and plugin lifecycle, update this prose and record the review with composer inventory:review -- --reviewed --note="review summary". An unchanged contract after a source change is accepted only with an explicit --no-authoring-impact="reason" explanation. Review records must never be refreshed automatically by CI or release scripts.

The mechanical record captures the published core catalog, child rules, renderer-root ownership, API write policy, and mobile-media support from actual product helpers. PHPUnit compares this record with the current helpers, and the source check requires a unique inventory heading for every published core block. Fingerprints and mechanical comparisons enforce review and structural consistency; they do not prove every sentence's meaning. Prose and no-impact explanations remain the contributor's and reviewer's responsibility.

The documentation repository's tools/inventory-snapshot.php regenerates the snapshot and its inventory-source.json provenance. Its checks reject manual snapshot edits and compare product version, source fingerprint, review checksum, and document content against a selected product checkout. Isolated documentation checks verify recorded provenance without requiring the product at runtime. Snapshot generation and CMS publication remain separate operations.

• webblocks-cms-docs/docs/ai-page-building-guide.md
• webblocks-cms-docs/docs/internal-content-api.md
• webblocks-cms-docs/docs/api-discovery.md
• webblocks-cms-docs/docs/block-type-contracts.md
• webblocks-cms-docs/docs/public-block-render-markup.md
• webblocks-cms-docs/docs/block-ui-renderer-contract.md
• webblocks-cms-docs/docs/public-theme-and-tones.md
• webblocks-cms-docs/docs/public-assets.md
• webblocks-cms-docs/docs/media-image-variants.md

This inventory should be the first document an AI reads for page-design capability selection. The detailed references remain useful for endpoint workflows, historical compatibility, and full renderer notes.

Catalog and ZIP installation, updates, and panel/API activation validate plugin source, provider startup, commands, and routes in a fresh PHP process through cms:plugin-probe. Validation is required even when no migration is pending. A failed or timed-out probe leaves the current package active; subprocess diagnostics are not exposed in responses. The default startup timeout is 30 seconds (webblocks-plugins.install.boot_timeout_seconds).

Successful updates retain the previous package and record whether migrations ran. Database setup failures leave the plugin disabled and preserve its tables and packages. Runtime source/route failures quarantine the plugin; an explicit disable overrides configuration-based enablement. Lifecycle JSON records use atomic replacement.

/webadmin/plugin-recovery and its login form load without installed plugin source, routes, or commands. Existing CMS login controls, active admin-access and Super admin authorization, and CSRF protection apply. Recovery can disable a plugin or restore the retained package when no migration ran, after another startup probe. A restore also republishes its assets. This is recovery for CMS-managed packages; it does not isolate arbitrary host providers or sandbox executable PHP. Uncatchable process termination still requires the separate recovery request rather than an in-process error handler.