diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md
index 137ad93..dc21323 100644
--- a/docs/spec/architecture.md
+++ b/docs/spec/architecture.md
@@ -25,7 +25,7 @@ Skills are **not** deployed by `install.sh`. They are distributed as plugins and
 
 ## Plugin model
 
-Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
+Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
 
 Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
 
diff --git a/scripts/sync-marketplace-mirror.sh b/scripts/sync-marketplace-mirror.sh
index 1af7882..ffdb066 100755
--- a/scripts/sync-marketplace-mirror.sh
+++ b/scripts/sync-marketplace-mirror.sh
@@ -60,7 +60,7 @@ fi
 if [[ "$CHECK" -eq 1 ]]; then
   if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then
     echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2
-    echo "Fix: bash scripts/sync-marketplace-mirror.sh" >&2
+    echo "Fix: bash scripts/sync-marketplace-mirror.sh -- apm ships no output profile targeting this path, so \`apm pack\` does not refresh it. Expecting it to is exactly the drift this script and its pre-push hook exist to prevent." >&2
     exit 1
   fi
   exit 0