Reference Index · Developers Hub

Use this page to find the source authority for current extension-facing PHP contracts. The index is intentionally stable and source-grounded. It does not replace live discovery from /api/v1/manifest or MCP tools/list.

Human Path

A developer uses this index to choose the contract behind a local extension task, then reads the linked source and the deeper guide page before writing files under:

app/extensions/{vendor}/

The source files are the authority when a documentation example and code disagree.

AI Path

An AI coding agent can use this page as a local-authoring map. It may inspect source files, create or edit extension files, and run verification commands inside the repository.

An installed MCP client cannot write PHP files or create extension packages. It should discover loaded runtime capabilities from /api/v1/manifest, MCP tools/list, and MCP resources/list.

Core Extension Contracts

Contract	Source file	Status	Primary use	AI relevance	Safety notes
`MyronExtensionManifest`	`app/system/extensions/ExtensionManifest.php`	Stable current	Parses `manifest.json`, validates vendor, scopes, migrations flag, and admin routes.	Local-authoring contract for manifest files.	Vendor must be snake_case and match the normalized directory; scopes are limited to base extension scopes.
`MyronExtensionLoader`	`app/system/extensions/ExtensionLoader.php`	Stable current	Boots granted extensions, runs migrations, registers actions, MIC resolvers, mail transports, and admin routes.	Explains why local files do or do not appear at runtime.	Loader skips unregistered/disabled extensions and records load failures; do not bypass it.
`MyronExtensionScopeGrantRepository`	`app/system/extensions/ExtensionScopeGrantRepository.php`	Stable current	Stores operator extension grants, enabled state, and load errors.	Classifies grant flows as human-admin-controlled.	MCP clients must not grant, revoke, enable, or disable their own trust gate.
`MyronExtensionMigrationRunner`	`app/system/extensions/ExtensionMigrationRunner.php`	Stable current	Runs extension migrations and creates `{vendor}_schema_migrations`.	Local-authoring contract for extension storage.	SQL list migrations may only touch `{vendor}_*` tables; callable migrations remain contractually isolated.
`MyronExtensionSDK`	`app/system/extensions/MyronExtensionSDK.php`	Stable current	Gives extension code helper access to site settings, site type, admin URLs, asset URLs, and vendor identity.	Preferred helper surface for local extension code.	Do not use it as permission to call unrelated core factories directly.

Action And API Contracts

Contract	Source file	Status	Primary use	AI relevance	Safety notes
`MyronAction`	`app/system/api/Action.php`	Stable current	Interface implemented by API actions.	Local action authoring; runtime tool behavior after registration.	`execute()` runs only after dispatcher auth, scope, and schema checks.
`MyronActionMetadata`	`app/system/api/Action.php`	Stable current	Declares URI, method, domain, schemas, scope, side effects, MCP exposure, and related metadata.	Feeds `/api/v1/manifest` and MCP tool discovery.	Extension URIs and domains must stay under `/api/v1/x/{vendor}/` and `x.{vendor}.`.
`MyronActionCallerContext`	`app/system/api/Action.php`	Stable current	Carries caller type, caller id, and held scopes into action code.	Lets actions attribute work and inspect held scopes.	Action code must not manufacture broader caller scopes.
`MyronActionResult`	`app/system/api/Action.php`	Stable current	Returns success or declared action failure before dispatcher wrapping.	Stable pattern for AI-readable action errors.	Caller-correctable failures should use declared errors, not uncaught exceptions.
`MyronActionRegistry`	`app/system/api/ActionRegistry.php`	Stable current	Registers actions and resolves method/URI requests.	Explains why an extension action may be rejected before runtime.	Extension actions need vendor-valid URI/domain prefixes and non-empty schemas.
`MyronActionDispatcher`	`app/system/api/ActionDispatcher.php`	Stable current	Authenticates, rate-limits, checks scope, validates schema, executes actions, and returns canonical envelopes.	Direct API and MCP action calls share this behavior.	Do not document dispatcher errors as permission to bypass auth, scopes, or rate limits.
`MyronApiScopes`	`app/system/api/Scopes.php`	Stable current	Defines base scope strings and base-to-sub-scope coverage.	Shared scope vocabulary for humans, AI callers, and extension grants.	Extension manifests and grants accept only base extension scopes.

Content Capability Contracts

Contract	Source file	Status	Primary use	AI relevance	Safety notes
`MicElementResolverInterface`	`app/system/mic/MicElementResolverInterface.php`	Stable current	Resolves one MIC id to pre-blessed HTML and describes the type.	Local-authoring contract for reusable rich-text insertions.	Resolver output must remain trusted local code; do not write raw database content directly.
`MicElementRegistry`	`app/system/mic/MicElementRegistry.php`	Stable current	Registers core and extension MIC types, validates descriptors, and lists known types.	Runtime descriptor discovery for editor/tooling surfaces.	Extension MIC types register as `x.{vendor}.{slug}`; picker bank surfaces require `parentSurfaceUrl`.

Mail Integration Contracts

Contract	Source file	Status	Primary use	AI relevance	Safety notes
`MailTransportInterface`	`app/system/mail/MailTransportInterface.php`	Stable current	Defines provider transport `send()` and `describe()` methods.	Local-authoring contract for provider-specific mail extensions.	Do not hard-code secrets in transport files or descriptors.
`MailEnvelope`	`app/system/mail/MailEnvelope.php`	Stable current	Carries normalized outbound mail fields.	Gives AI authors the exact narrow payload to map into provider APIs.	Header import allowlists only `x-myron-context` and `x-myron-source`.
`MailDispatchResult`	`app/system/mail/MailDispatchResult.php`	Stable current	Returns transport success, provider message id, or error.	Stable result shape for provider transports.	Provider-specific response bodies are outside this core contract.
`MailTransportRegistry`	`app/system/mail/MailTransportRegistry.php`	Stable current	Registers core and extension transports and exposes descriptors.	Explains current transport namespace and descriptor discovery.	Extension transport vendor and slug must be snake_case and register as `x.{vendor}.{slug}`.

Runtime Discovery

This index is not a live runtime catalog. For a running install:

use /api/v1/manifest for current action metadata,
use MCP tools/list for exposed, scope-allowed tools,
use MCP resources/list for MCP-readable documents and live resources,
use installed extension admin screens for human grant/load review.

Scopes

Reading this page requires no runtime scope.

The contracts it references use scopes differently:

extension manifests and grants use the six base extension scopes,
action calls use the action's requiredScope,
MCP tool discovery filters by caller scope and exposeToMcp,
local file authoring is not an installed MCP operation.

Artifacts

Primary local artifacts:

app/extensions/{vendor}/manifest.json
app/extensions/{vendor}/bootstrap.php
app/extensions/{vendor}/actions/*.php
app/extensions/{vendor}/migrations/*.php
optional extension admin route files
optional resolver or transport classes

Runtime artifacts:

registered actions,
extension admin routes,
extension-owned tables,
MIC descriptors,
mail transport descriptors,
action envelopes and audit ids.

Safety Boundary

Do not use this index to justify unsupported surfaces. Extension v1 does not provide marketplace install, package dependency resolution, signing, sandboxing, public render hooks, design token group registration, snapshot contribution, or arbitrary core admin rail injection.

Verification

Use source and runtime checks together:

php app/tests/verify-extension-system-foundation.php
php app/tests/verify-content-banks-mic.php
php app/tests/verify-forms-mail-substrate.php

Then, for a running install, read /api/v1/manifest and MCP tools/list with a scoped caller before claiming an action is available to an AI client.

Failure Modes

Failure	Likely cause	Safe response
Documentation names a class that no longer exists	Source contract drifted.	Re-check `app/system/...` and update this index.
AI client expects local file authoring over MCP	Local-authoring and installed runtime access were confused.	Use a coding agent for repo edits; use MCP only for loaded runtime surfaces.
Tool is missing from MCP	Action is not loaded, hidden from MCP, or caller lacks scope.	Check loader state, `exposeToMcp`, and caller scopes.
Extension mutates core state through a contract here	Scope boundary was misread.	Keep extension storage, routes, and namespaces vendor-owned unless a new contract expands the substrate.