docs: correct claims the apm conversion left false

Documentation asserted things the code no longer did, which is how several of this
round's defects survived three review passes.

- `docs/spec/architecture.md` still described the pre-APM model — "each plugin has a
  `plugin.json` manifest" — when no such file exists. AGENTS.md routes agents here
  for the current structure, so it was live drift, not archive. Also cited ADR-0012
  where ADR-0003 is meant.
- AGENTS.md never said `.apm/` is the sole hand-edited source, while the generated
  mirror is byte-identical with no marker — an agent reading only AGENTS.md would
  edit the mirror and find out at pre-push. It also omitted that `apm` and `jq` are
  now required to push, unlike the `vale` bullet that exists for exactly that reason,
  and understated the pre-push gate. `apm marketplace check` hard-fails offline and
  `--offline` does not help, so the `SKIP=` escape hatch is documented rather than
  new machinery built.
- ADR-0017 carried hardcoded line numbers that drifted twice within one PR, and said
  `mcpServers` reinjection was real-syncs-only where the script's own header says
  both modes. Line numbers dropped rather than corrected.
- ADR-0015 asserted issue #90 was closed. It is open. Reworded to defer to the
  issue's own state rather than depend on someone remembering to close it.
- ADR-0014 said both audit skills pass `--config`; both SKILL.md files say pass none,
  and passing one fails with E100. The ADR was wrong.
- ADR-0007 cross-referenced an archived ADR-0011 whose number was later reused.
  Disambiguated with a note — renumbering a published ADR rewrites an immutable
  record and breaks every existing citation.
- CONTEXT.md claimed `lint-runner` is report-only via a missing `Edit` tool.
  Plugin-scope APM agents cannot express `tools:` (ADR-0016), so it is report-only by
  instruction now; ADR-0016 accepted that regression but CONTEXT.md was not updated.
- Recorded two undocumented consequences of the conversion: `displayName` dropped
  from all six compiled manifests and `owner.email` from the marketplace, and
  `mattpocock-skills` silently version-pinned and manually maintained.
- Wrote the version-bump policy issue #90 specified but never delivered. Its previous
  carrier, `marketplace-author`, was deleted in this PR, leaving the per-package rule
  documented nowhere.
- README fixes: kyberforge listed skills belonging to the `git` plugin and a deleted
  hooks path, `bin` advertised an agents directory it never had, and the docs index
  listed files that do not exist.

Refs: #90

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT

docs/adr/0007-gitea-canonical-issue-tracker.md

@@ -2,6 +2,8 @@
 
 **Supersedes:** ADR-0011 (provider-agnostic issue tracker with file-based default — archived during refactoring)
 
+> **Note on the ADR-0011 number.** Every "ADR-0011" on this page means the *archived* provider-agnostic issue tracker ADR, which no longer exists in `docs/adr/` — it was removed when it was superseded, and the number 0011 was later reused for an unrelated decision, `docs/adr/0011-gitea-skill-deep-modules.md` (the gitea skill's split into deep modules). That file is not the ADR referenced below. The number is not renumbered here: these ADRs are a published record and renumbering would break every citation that already points at either one. The archived text is recoverable from git history.
+
 ADR-0011 established a provider-agnostic model with `docs/issues/NNNN-<slug>.md` as the file-based default, switching to Gitea MCP at runtime when available. The interim model was justified because Gitea would not be configured until after Chunk 3, and the repo needed to work before then.
 
 Gitea is now configured and in active use. The condition in ADR-0011 has been met. This ADR supersedes it.

docs/adr/0014-vale-prefilter-ships-from-the-plugin.md

@@ -65,8 +65,13 @@ cannot be expressed as a `--config` argument at all — the config path has to b
 the process, from the script's own location. `vale-wrap.sh` accordingly defaults to its sibling
 `assets/vale/.vale.ini`, resolved from `${BASH_SOURCE[0]}`, whenever no `--config` is supplied;
 an explicit `--config` from any other caller still wins and still resolves against the caller's
-cwd, so both audit skills' Step 1 (`--config assets/vale/.vale.ini`) is unaffected. Both
-manifests now carry the identical argument-free `entry:`. Keeping them identical is part of the
+cwd. Both audit skills' Step 1 passes no `--config` either, for the same reason and one more: a
+relative `--config assets/vale/.vale.ini` resolves against the cwd, not against the skill
+directory the wrapper path was resolved from, so it yields `E100 Runtime error … does not exist`
+and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades
+to full LLM judgment, the exact failure the self-location exists to prevent. Both `SKILL.md` Step
+1 sections say so explicitly ("Pass no `--config`"), and both manifests now carry the identical
+argument-free `entry:`. Keeping them identical is part of the
 decision: the local `repo: local` hook resolved its `--config` correctly only because the
 consuming repo *was* this repo, and that one difference is why three review rounds exercised a
 code path no external consumer ever takes.

docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

@@ -52,7 +52,8 @@ new hand-maintained manifest format.
   `apm-orchestrate` (issue #88, already landed on this branch) fully replace what these two skills
   did. `plugin-author`/`marketplace-author` were deleted in issue #90's execution.
 - Translating the existing plugins into `apm.yml` + `.apm/` and running the real conversion was
-  executed in issue #90 (https://git.dev.rkdr.net/Defame1297/holocron/issues/90, closed).
+  executed under issue #90 (https://git.dev.rkdr.net/Defame1297/holocron/issues/90), which tracks
+  that work through to merge.
 - `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries were rewritten in issue #90 to
   describe the compiled-output model directly, rather than carrying a forward-pointer to this ADR.
 
@@ -119,9 +120,34 @@ correction) sorted what they document into three buckets:
   issue #90 had to re-author plugin-scope agents: `.apm/agents/*.agent.md` compiles verbatim to
   both Claude and Copilot, so those files carry only `name`/`description`/`model`/`source_keys` —
   existing dual-file `<name>.md`+`<name>.agent.md` pairs could not be raw-moved, only re-authored.
-- Two follow-up issues tracked the remaining work, both done: #89 (`skill-author`/`agent-author`
-  routing adaptation, merged in #93) and #90 (the actual repo conversion, which also deleted
-  `plugin-author`/`marketplace-author`).
+- Two follow-up issues tracked the remaining work: #89 (`skill-author`/`agent-author` routing
+  adaptation — closed, merged in #93) and #90 (the actual repo conversion, which also deleted
+  `plugin-author`/`marketplace-author` — tracked through to merge; treat #90's own state as the
+  authority on whether it has landed, not this line).
+- **`displayName` is gone from all six compiled `plugin.json` files, and `owner.email` from the
+  marketplace manifest — accepted, not overlooked.** `apm.yml` has no key that compiles to either,
+  so the conversion dropped both: every `plugins/<name>/.claude-plugin/plugin.json` now carries
+  `author`/`description`/`homepage`/`keywords`/`license`/`name`/`repository`/`version` (plus
+  `mcpServers` for `bin`) and no `displayName`, and `.claude-plugin/marketplace.json`'s `owner`
+  block is `{name, url}` only. Both fields are optional —
+  `plugins/kyberforge/docs/research/docs/claude-code-plugins/api-reference.md:14` lists
+  `displayName` as `Required: No`, "Human-readable name shown in plugin manager" — which is why
+  `claude plugin validate --strict` still passes on all six. The visible cost is that the plugin
+  manager falls back to the bare `name` as each plugin's label. Accepted as the price of `apm.yml`
+  being the single authoring source: re-injecting `displayName` post-compile would mean a second
+  `reinject_*` workaround of the kind ADR-0017's amendment reserves for fields apm strips on a
+  factually wrong premise, and apm's premise here is simply that the key does not exist in its
+  schema.
+- **`mattpocock-skills` is now version-pinned, and the pin is maintained by hand.** Pre-conversion
+  the entry was `{"repo": "mattpocock/skills", "source": "github"}` — an unpinned reference that
+  tracked the upstream default branch, so consumers got whatever was on it at install time. Root
+  `apm.yml` now declares `version: "^1.2.0"` for it, which `apm pack` resolves and freezes into
+  `.claude-plugin/marketplace.json` as `ref: v1.2.3` + an explicit `sha`. Consumers get a
+  reproducible version instead of a moving target, which is the improvement; the cost is that
+  nothing advances it. apm has no version-bump automation (established under "Versioning" in issue
+  #90's plan), so picking up a new upstream release means a human editing the `version:` range in
+  root `apm.yml` and re-running `apm pack`. Left un-bumped, the marketplace pins an ageing release
+  indefinitely and silently.
 - **Caveat on "Status: executed" above:** issue #90's own execution comment flagged, before merge,
   that Claude Code's ability to actually load content out of `.apm/` was unverified — that caveat
   turned out to be a real defect, not a formality: the native installer has zero awareness of

docs/spec/architecture.md

@@ -25,7 +25,14 @@ 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/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`.
+Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently via `claude plugin install <name>@holocron`. 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.
+
+Two compilers produce the plugin roots you see in the tree:
+
+- **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins/<name>/apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook.
+- **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract.
+
+`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, and `.mcp.json` — lives at the plugin root and is untouched by either compiler.
 
 ## Governance layer
 
@@ -37,7 +44,7 @@ The governance layer has two phases:
 
 ## AGENTS.md pattern
 
-This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
+This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0003):
 
 - **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
 - **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects. Deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.