Cookbook · Developers Hub

Use the cookbook when you know the task and need the shortest safe path to the right guide. Each recipe names both the human path and the AI path so local authoring does not get confused with installed MCP access.

Human Path

Choose the recipe that matches the task, read its prerequisites, make the local or admin change, and run the listed verification.

AI Path

An AI coding agent can author local extension files and run local verification. An installed MCP client can only use exposed runtime tools and resources after the extension is loaded and scoped.

Recipes

Task	Page	Human path	AI path	Scope/status
Build the first local extension	Hello World Extension	Create a local package under `app/extensions/{vendor}/`.	AI coding agent authors local files and runs verification.	Local authoring; sample action uses `content.read`.
Verify an extension	Verify Your Extension	Run CLI checks, then direct API and MCP checks in a running install.	AI coding agent runs CLI checks; installed MCP client can verify listed tools only.	Runtime calls require action scope.
Write a read action	Write A Read Action	Implement `MyronAction` with a GET metadata contract.	AI coding agent writes local action code and checks metadata.	Usually `content.read`, `design.read`, or `administration.read`.
Write a write action	Write A Write Action	Implement a mutating action with side effects and preconditions.	AI coding agent writes local code; installed MCP caller needs exposed tool and scope.	Write scope required by action.
Add an admin route	Add An Extension Admin Route	Add a manifest route and local route file.	AI coding agent authors files; route use is browser/admin mediated.	Human-admin route, usually administration access.
Add isolated migrations	Add Isolated Migrations	Add migration files under the extension package.	AI coding agent writes migrations and runs verification.	Local authoring; storage must stay `{vendor}_*`.
Register a MIC type	Register A MIC Type	Implement and return a resolver from `bootstrap.php`.	AI coding agent authors resolver code; runtime descriptor discovery follows load.	Descriptor scopes such as `content.read`.
Insert a rich-text MIC token	Rich-Text Insertion	Insert a valid `[mic-*]` token through normal content editing.	AI coding agent can author resolver and examples; installed AI must use normal content actions.	Content action scope still applies.
Build a mail provider transport	Build A Provider Transport	Implement `MailTransportInterface` and return it from bootstrap.	AI coding agent authors provider transport without hard-coding secrets.	Setup surfaces usually need administration scopes.
Handle action errors	Action Error Handling	Return declared errors and verify API/MCP envelopes.	AI coding agent implements safe error handling; MCP client remediates within scope.	Does not change action scope.
Recover from load errors	Load Errors And Recovery	Review `/extensions`, fix local files, and reload.	AI coding agent can fix files and report admin follow-up.	Enable/disable/grant is human-admin-only.
Write manifest examples	Manifest Examples	Create or review a valid `manifest.json`.	AI coding agent authors local manifest files.	Manifest scopes limited to base extension scopes.
Diagnose common rejections	Common Rejection Errors	Identify the failing layer and apply safe remediation.	AI coding agent fixes local mistakes; installed MCP client stops at trust boundaries.	Depends on failing layer.

Scopes

This index has no runtime scope requirement. Recipe pages name their own scopes. When a recipe has both local authoring and runtime verification, remember that:

local file edits require repository access, not runtime scopes,
extension loading requires operator registration, enablement, and grants,
direct API and MCP calls require caller scopes,
MCP tools/list also requires exposeToMcp:true.

Artifacts

Common recipe artifacts include:

manifest.json
bootstrap.php
action classes,
admin route files,
migrations,
MIC resolver classes,
mail transport classes,
/api/v1/manifest,
MCP tools/list and tools/call results.

Safety Boundary

Do not add cookbook shortcuts that skip the extension loader, scope grants, migration runner, rich-text sanitization, mail transport abstraction, or MCP exposure policy. Future marketplace behavior belongs in marketplace-prep documentation, not current recipes.

Verification

Each recipe has its own verification. General checks:

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

For runtime recipes, verify both direct API behavior and MCP discovery when MCP exposure is part of the workflow.

Failure Modes

Failure	Likely cause	Safe response
Recipe seems to require marketplace install	Wrong page family for current support.	Use local extension authoring docs; marketplace is future/prep.
AI path says "call MCP" for local files	Local authoring and installed runtime were confused.	Use an AI coding agent for files and MCP for loaded tools.
Runtime call fails after local recipe succeeds	Extension is not registered, enabled, granted, exposed, or scoped for the caller.	Check `/extensions`, `/api/v1/manifest`, and MCP `tools/list`.