Compatibility Documents · Developers Hub

Compatibility documents tell AI clients what a MyronCMS site type or running install can currently support. They are planning documents for agents, not mutation endpoints.

There are two modes:

Mode	Question answered	Current source
Default	What does this site type activate out of the box?	`MyronCompatibilityDocumentService::default()`
Configured	What does this running install currently contain?	`MyronCompatibilityDocumentService::configured()`

Human Path

A developer or operator uses compatibility documents to explain capability context without forcing an AI client to infer from marketing copy or unrelated docs.

Use default compatibility when discussing a site type before setup. Use configured compatibility when planning work against a real install.

AI Path

An MCP client can discover compatibility resources through:

MCP resources/list

Then read:

mcp://myroncms/system/compatibility/default?siteType=BIZ
mcp://myroncms/system/compatibility/configured

An API client can call:

GET /api/v1/system/compatibility/default
GET /api/v1/administration/compatibility/configured

The default API action requires a siteType input and is public in current source. The configured API action requires administration.read because it exposes live install state.

Default Compatibility

Default compatibility is site-type reference material. It describes a known site type's recommended bundle, default footer, design surface, supported actions, token authority notes, and content-resolution model.

Current API entrypoint:

GET /api/v1/system/compatibility/default

Required input:

{
  "siteType": "BIZ"
}

Current MCP resource pattern:

mcp://myroncms/system/compatibility/default?siteType=BIZ

Configured Compatibility

Configured compatibility is live install state. It composes a snapshot, active site type, active bundle, current default footer, design surface, manifest summary, and snapshot data.

Current API entrypoint:

GET /api/v1/administration/compatibility/configured

Current MCP resource:

mcp://myroncms/system/compatibility/configured

The configured action itself declares administration.read. Documentation should preserve that sensitivity even where an MCP resource handler composes the resource directly.

Scopes

Entry point	Current scope posture
`GET /api/v1/system/compatibility/default`	Public action, `requiredScope: null`.
Default MCP resource	Listed as an MCP resource; current handler resolves by URI.
`GET /api/v1/administration/compatibility/configured`	`administration.read`.
Configured MCP resource	Listed as an MCP resource; contains live install state and should be handled as sensitive context.

Do not use compatibility documents to bypass action scopes. They are read surfaces for planning.

Artifacts

Source contracts:

app/modules/system/CompatibilityDocumentService.php
app/api/actions/system/GetCompatibilityDocumentDefaultAction.php
app/api/actions/administration/GetCompatibilityDocumentConfiguredAction.php
app/system/mcp/Server.php
.amphion/control-plane/architecture-log/full-parity-mcp-2026-05-10.md

Runtime surfaces:

/api/v1/system/compatibility/default
/api/v1/administration/compatibility/configured
MCP resources/list
MCP resources/read

Snapshot And `liveContentResolution`

Configured compatibility depends on the snapshot service. Snapshot-eligible read actions declare snapshotInclude and snapshotKey in action metadata. The configured compatibility document includes a snapshot block composed from the running install.

liveContentResolution describes how content and component resolver behavior should be understood by AI clients. It is part of the compatibility model for planning. It is not an extension hook. Current extension v1 docs still classify extension snapshot contribution as prohibited-current.

Safety Boundary

Do not treat compatibility documents as mutable configuration. If an AI client wants to change content, design, or administration state, it must use the appropriate scoped action.

Do not copy a full compatibility payload into docs as if it is permanent. Use small shapes and tell clients to read the running install.

Verification

For API verification:

GET /api/v1/system/compatibility/default with siteType returns mode=default
GET /api/v1/administration/compatibility/configured requires administration.read

For MCP verification:

resources/list includes both compatibility resources
resources/read returns application/json content for each compatibility URI
default URI accepts a siteType query such as BIZ

For documentation QA, verify all claims against CompatibilityDocumentService.php and the two action classes.

Failure Modes

Failure	Likely cause	Safe response
Default document returns unknown site type	`siteType` does not match a registered site type key.	Use a known key such as BIZ, PORT, BLOG, AGY, ECOM, SAAS, NEWS, EDU, MKT, or RST.
Configured API call fails with `scope_insufficient`	Caller lacks `administration.read`.	Use an operator-approved caller with the required scope.
AI plans against default data for a configured install	Client read the wrong mode.	Read configured compatibility before changing a live site.
Docs claim extension snapshot contribution	Extension v1 boundary was exceeded.	Mark as prohibited-current or future evaluation, not current support.
Payload fields do not match docs	Docs copied stale output.	Re-read the running install and update docs to describe contracts, not fixed state.