Core Concepts
Current Boundaries
Extension v1 is a bounded local SDK. It supports local extension packages, scoped actions, optional isolated migrations, optional isolated admin routes, MIC resolver registration, and mail transport registration. It is not a general plugin marketplace or core override layer.
Human Path
Before authoring an extension, classify the idea:
- If it can live in local files under
app/extensions/{vendor}/, use extension v1. - If it can register a namespaced action under
/api/v1/x/{vendor}/..., use extension v1. - If it can use isolated
{vendor}_*storage, use extension v1. - If it needs a supported MIC resolver or mail transport registration, use extension v1 with the later content or integrations guides.
- If it needs marketplace install, dependency resolution, signing, sandboxing, public render hooks, core rail injection, or core table mutation, it does not fit extension v1.
AI Path
An AI coding agent can help classify the idea and author local files for supported surfaces.
An installed MCP client can call loaded exposed actions, but it cannot install packages, grant trust, inject hooks, or create PHP code. If MCP parity for a human/admin workflow is missing or intentionally hidden, document that as a policy boundary or future parity gap rather than inventing an unsupported route.
Stable Current
| Surface | Current support |
|---|---|
| Local extension package | Supported under app/extensions/{vendor}/. |
| Manifest parsing | Supported through ExtensionManifest.php. |
| Bootstrap payload | Supports actions, MIC resolvers, and mail transports. |
| Scoped actions | Supported under /api/v1/x/{vendor}/.... |
| Action MCP exposure | Supported when exposeToMcp: true and caller scopes allow it. |
| Scope grants | Supported through Extensions admin surfaces. |
| Isolated admin routes | Supported through manifest adminRoutes. |
| Isolated migrations | Supported for {vendor}_* tables. |
| Load error capture | Supported through extension_load_errors. |
| MIC resolver registration | Supported through micElementTypes. |
| Mail transport registration | Supported through mailTransports. |
Future Planned
| Surface | Current posture |
|---|---|
| Marketplace browse | Reserved for a later release; the current admin button is disabled. |
| Marketplace install | Not implemented in extension v1. |
| Package review criteria | Can be planned later as marketplace readiness docs. |
| Compatibility declarations beyond current manifest fields | Future marketplace-prep topic. |
| Webhook/event extension surface | Product direction exists, but not a current extension SDK hook. |
Prohibited Current
| Requested behavior | Current status | Rationale |
|---|---|---|
| PHP event hooks | Prohibited current | No extension event hook API exists in v1. |
| Public render hooks | Prohibited current | Extensions cannot hook public rendering in v1. |
| Design token group registration | Prohibited current | Design tokens remain governed by the design system contract. |
| Snapshot contribution | Prohibited current | Extensions cannot contribute snapshot sections. |
| Core admin rail injection | Prohibited current | Extension admin routes are isolated; they do not add new core rail sections. |
| Code signing | Prohibited current | No signing contract exists in extension v1. |
| Sandbox isolation | Prohibited current | No sandbox isolation contract exists in extension v1. |
| Dependency resolution | Prohibited current | No package dependency resolver exists in extension v1. |
| Core table mutation | Prohibited current | Extension migrations may modify only {vendor}_* tables. |
| Core action override | Prohibited current | Extension actions register under /api/v1/x/{vendor}/..., not core API paths. |
Parity Gap Candidates
Some human/admin workflows are current but not MCP-callable. Scope grant creation, extension enable/disable, and scope revocation are intentionally human/admin mediated in current docs. If later work proposes MCP or API coverage for those privileged operations, it needs a new Evaluate and Contract cycle because it changes the trust boundary.
Safety Boundary
Do not document future surfaces as workarounds. If a desired extension requires a prohibited-current or future-planned capability, stop at classification. The next step is a new MCD cycle to evaluate whether the platform should grow that surface.
Verification
For current stable surfaces, use:
php app/tests/verify-extension-system-foundation.phpFor future or prohibited surfaces, verification is documentary: the page must say the surface is unavailable today and must not include runnable instructions that imply support.