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

plugins/kyberforge/.apm/skills/apm-install/references/sources.md

@@ -7,3 +7,11 @@
 - **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
 - **Contributing files:** SKILL.md
 - **Status:** `extracted`
+
+## apm-github-repo
+
+- **URL:** https://github.com/microsoft/apm
+- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Informed the research doc's primitive-schema and releasing pages; nothing in this skill's install/runtime guidance derives from it.
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Contributing files:** (none)
+- **Status:** `referenced`

plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md

@@ -37,6 +37,31 @@ version: 1.0.0
 
 See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
 
+## Bumping a package's own version (repo policy)
+
+apm ships no version-bump command, so `version:` in a package's own `apm.yml` is a hand edit.
+Policy: **bump a package's own `apm.yml` `version:` whenever anything that reaches its compiled
+output changes.** Two triggers, not one:
+
+- **Its `.apm/` content** — a new or removed skill/agent/hook, or a substantive edit to an
+  existing one.
+- **Its own `apm.yml` manifest metadata** — `description`, `keywords`, `author`, `license`,
+  `homepage`, `repository`. These are compiled verbatim into `.claude-plugin/plugin.json` and
+  `.github/plugin/plugin.json`, so editing them republishes the package's public description
+  under an unchanged version number, which is the same defect as shipping changed content
+  silently. Purely local edits that reach no compiled output — a `README.md`, a `docs/` page —
+  do not require a bump on their own.
+
+The version belongs to the package, not to the repo: editing `plugins/foo/.apm/` never bumps
+`plugins/bar/apm.yml`.
+
+Under a `per_package` strategy the same number is also carried in the catalog's
+`marketplace.packages[]` entry, so both copies move together in the same commit. The catalog's own
+version follows a separate rule — see `references/marketplace.md`. `apm pack --check-versions`
+fails the push when a package's version disagrees with the configured strategy, so a bump applied
+in only one of the two places is caught, but a bump skipped in both is not: nothing infers intent
+from a content diff.
+
 ## Dependency reference forms
 
 `dependencies.apm` entries accept: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).

plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md

@@ -4,6 +4,7 @@ source_keys:
   - context7-microsoft-apm
   - context7-websites-code-claude
   - claude-code-plugins-docs
+  - apm-github-repo
 ---
 
 ## Building a marketplace from a producer repo
@@ -68,6 +69,33 @@ marketplace:
 
 Without this block, the default versioning strategy ties every listed package to the marketplace/root version.
 
+## Bumping the catalog's own version (repo policy)
+
+The section above is apm's *mechanic* — how per-package versions are declared and how
+`marketplace.versioning.strategy` resolves them. This section is *policy*: apm has no version-bump
+automation, so the one number apm will never pick for you is the catalog's own
+`marketplace.version` in the root `apm.yml`. Bump it by hand, in the same commit as the change that
+earned it:
+
+- **Minor** when a `marketplace.packages[]` entry is added or removed. The catalog's contents
+  changed — a consumer resolving it now gets a different set of installable packages.
+- **Patch** when only `marketplace:`-block fields change and the set of packages is unchanged: the
+  catalog description, owner, `build:`/`outputs:` config, or an existing entry's `version:`,
+  description, or category. The catalog describes the same packages; only its metadata moved. An
+  entry's `version:` is the most frequent of these by far — under `per_package` it moves here every
+  time any package bumps (see `references/configure.md`), and that alone earns the catalog patch.
+
+Keep the root `apm.yml`'s top-level `version:` in step with `marketplace.version`. They are separate
+keys — the top-level one is not inherited into the compiled `marketplace.json`, but `apm audit`
+reads it — so letting them diverge produces two different answers to "what version is this catalog".
+
+Editing a package's *own* `.apm/` content is a different bump against a different number — see
+`references/configure.md`. Note what the tooling does and does not catch: `apm pack --check-clean`
+regenerates every marketplace output and diffs it against what is on disk, so a bump made in
+`apm.yml` but never re-packed fails the gate. A bump you never made at all fails nothing — no apm
+flag infers a required version change from a content diff, which is why this is policy and not a
+hook.
+
 ## Which mechanism to use
 
 - **Local packages, no distribution needed yet** — local-path dependencies in `apm.yml` (`./packages/my-shared-skills`); no marketplace or registry involved.

plugins/kyberforge/.apm/skills/apm-workflow/references/sources.md

@@ -8,6 +8,14 @@
 - **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md
 - **Status:** `extracted`
 
+## apm-github-repo
+
+- **URL:** https://github.com/microsoft/apm
+- **Description:** APM's own Python source (`src/apm_cli/`), read directly for schema and compile-mapping ground truth where Context7's doc snippets were thin. Backs the marketplace output-profile claim (`apm_cli/marketplace/output_profiles.py` — only `claude` and `codex` profiles exist, so there is no native Copilot marketplace output) and the `apm pack --check-clean`/`--check-versions` semantics.
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Contributing files:** references/marketplace.md
+- **Status:** `extracted`
+
 ## context7-websites-code-claude
 
 - **URL:** context7:/websites/code_claude