Parity Gap Policy · Developers Hub

Every Extensions SDK page must be usable by human developers and AI agents. That does not mean every human workflow has current MCP parity. It means the page must say exactly what AI can do today, or explicitly mark the gap.

Use this policy when writing or reviewing Extensions SDK pages.

Human Path

A documentation author classifies each workflow:

Is the capability current, advanced current, future planned, or prohibited current?
Can an installed AI client perform it through MCP tools, MCP resources, or direct API?
Can an AI coding agent perform it as local repository authoring?
If not, is the missing AI route intentional safety policy, missing action coverage, missing resource coverage, or missing documentation?
What wording prevents the reader from assuming unsupported AI access?

AI Path

An AI coding agent can use this page as a review checklist when authoring docs. An installed MCP client can use live discovery to verify whether a documented tool or resource exists:

MCP tools/list
MCP resources/list
GET /api/v1/manifest

If a page describes a workflow but no AI route exists, the docs must mark the gap instead of inventing a call path.

Metadata Review

Every SDK page should include the AI-native metadata block defined in AI-Native Documentation Contract.

Key fields for parity review:

Field	Review question
`support_status`	Is the capability current, future, or prohibited?
`ai_access`	Is the named AI route actually present?
`required_scopes`	Are runtime scopes complete and source-grounded?
`runtime_entrypoints`	Are MCP, API, admin, or local file paths named?
`safety_boundaries`	Does the page prevent bypass wording?
`parity_gap`	Is a missing AI route explicitly triaged?

AI Access Classes

Use the contract vocabulary consistently:

Class	Use when
`mcp-tool`	A scope-allowed, exposed `MyronAction` appears through MCP `tools/list`.
`mcp-resource`	Information is exposed through MCP `resources/list` and `resources/read`.
`api-callable-not-mcp`	A route exists but is not exposed as an MCP tool.
`local-authoring`	Work happens by editing repository files.
`human-admin-only`	The current workflow is browser/admin mediated and intentionally not AI-callable.
`parity-gap`	Human workflow exists but current AI route is missing, unsafe, unclear, or policy-blocked.

Parity Gap Triage

When parity_gap: true, the page must answer:

What can a human do today?
Why can an AI not do it through current API, MCP, or local authoring?
Is the gap intentional safety policy, missing action coverage, missing resource coverage, or missing documentation?
What future contract question must be answered before exposing it?
What is the safest interim wording?

Safe interim wording should be plain. Example:

Current status: human-admin-only. An installed MCP client cannot perform this workflow today. Treat this as a parity-gap candidate rather than a supported AI route.

`exposeToMcp:false`

If an action is hidden from MCP, classify the reason:

Category	Documentation treatment
Recursive control vector	Never document as MCP-callable.
Tier-3 identity/admin surface	Document as policy-hidden unless a later privileged-admin primitive changes the rule.
Visitor-facing action	Document runtime behavior, not operator MCP control.
Internal dispatch	Document only as internals.
Unresolved over-hide	Mark as parity-gap candidate and route through Evaluate.

Do not hide or document hiding solely because an action writes. Writes can be valid MCP tools when scopes, preconditions, side effects, and operator intent are explicit.

Current, Future, And Prohibited Claims

Current docs may give runnable instructions only for current supported surfaces.

Future-planned pages may explain direction, prerequisites, and open questions. They must not include runnable instructions that imply support exists.

Prohibited-current pages should classify the boundary and stop. They should not include workaround recipes.

For extension v1, prohibited-current surfaces include public render hooks, design token group registration, snapshot contribution, core rail injection, sandboxing, signing, dependency resolution, and core action override.

Scopes

This policy page has no runtime scope requirement. Pages that document runtime calls must name the scopes declared by the relevant action or explain why the route is public or local-only.

Artifacts

Review source contracts:

docs/extensions-sdk/03-ai-native-documentation-contract.md
docs/extensions-sdk/01-surface-inventory.md
docs/extensions-sdk/core/current-boundaries.md
docs/extensions-sdk/start/what-extensions-can-do.md
.amphion/control-plane/architecture-log/full-parity-mcp-2026-05-10.md

Live discovery checks:

/api/v1/manifest
MCP tools/list
MCP resources/list

Safety Boundary

Do not use vague AI language such as "AI can manage this" without naming the exact route. Name the tool, resource, API path, local file path, or parity gap.

Do not turn documentation into a platform expansion. If a workflow needs new API/MCP coverage, start a new Evaluate and Contract cycle.

Verification

Use this reviewer checklist:

Page has required metadata.
Human workflow is named.
AI route or parity gap is named.
Runtime scopes are listed or explicitly empty.
Source contracts are listed.
Runtime entrypoints are concrete.
Safety boundaries prohibit trust-gate bypasses.
Future/prohibited claims are not written as current tutorials.
Existing MCP claims can be checked through live discovery.

Failure Modes

Failure	Likely cause	Safe response
Page says "AI-supported" but names no route	AI support was implied through vibes.	Add MCP/API/local-authoring route or mark a gap.
Future marketplace feature has current instructions	Support status is wrong.	Change to future-planned and remove runnable current workflow steps.
Human admin workflow is documented as MCP-callable	Admin UI and action/MCP surfaces were confused.	Verify source entrypoint and classify human-admin-only or parity gap.
Hidden action is presented as a normal tool	`exposeToMcp:false` policy was ignored.	Document the hidden category and safe alternative.
AI is told to bypass scopes	Trust boundary was violated.	Route access changes through operator/admin review.