How PMA works under the hood. For operators who already use PMA and now need to debug, operate, extend, or contribute to it.
| Page | What it covers |
|---|---|
| Architecture | The nine pillars (Install Skill, Package, Framework, Testing, Contract, MCP, PMA-UI, Enforcement, Release). How they cooperate. |
| Package system | How packages/<svc>/ is structured, what each file does, how the framework activates it (no service-specific code in framework). |
| Bootstrap | The bootstrap flow — phases 0 through 8. Hooks (pre_start, post_start, post_data_restore, ensure-config). State tracking via skill-state.ts. |
| MCP gateway | The credential guard (gwkh enforcement), the per-service tool surface, how AI agents authenticate + get attribution. |
| Recovery playbooks | The machine-readable runbook format. How to add a playbook entry. Why every bootstrap fix needs one. |
| Install Skill | The formal protocol AI agents follow to add a new service. Phase model, regression requirements, state tracking. |
| Release orchestrator | release-run internals — the four phases, state file format, resume-from-phase, backup integration. |
| Contract system | just contract-generate — in-memory snapshot of every command + package. Pre-commit, pre-push, CI enforcement. |
/asd/cookbook/debug-a-broken-route decision tree./install-service slash command); it covers everything.asd internalsPMA is built on top of asd. Several internals concepts (Caddy
state, tunnels, registry, credential model) live in the asd layer —
see /asd/internals.
PMA's internals docs reference asd internals where they share a
mechanism (e.g. PMA's recovery playbooks complement asd's net
verification; PMA's release orchestrator wraps asd's deploy
verbs).
/pma/learn — the ladder, for users who want to build things./pma/reference — schemas + CLI for looking things up./asd/internals — the layer PMA is built on.