docs: correct the claims this review found false

AGENTS.md told an offline agent to push with SKIP=apm-marketplace-check and
asserted that hook was "the only one whose failure mode is 'no network'".
Running all 12 pre-push hooks under a network namespace shows two fail, for
one shared cause: apm-pack-check-clean resolves the same remote entry. An
exact pin does not remove the ls-remote, so both hooks are named now.

AGENTS.md also said everything in a plugin root except .apm/ is generated.
Plugin roots carry hand-authored README.md, docs/, bin/, sources.md and
.mcp.json, so an agent would hunt for an .apm/ source that does not exist or
refuse the edit. The rule is positional: immunity belongs to the plugin root,
and anything inside a mirrored directory is still rm -rf'd.

ADR-0017 said apm strips a hooks field. The real loop is (agents, skills,
commands, instructions) -- hooks absent, instructions never mentioned -- and
it can never fire, because synthesize_plugin_json_from_apm_yml only emits the
eight identity fields. The decision stands; the mechanism was overstated. Its
mcpServers amendment is rewritten for the pointer payload and now records the
real reason: inlining bypassed apm's credential sanitizer.

ADR-0015's owner.email and version-pin passages are corrected against the apm
source, and ADR-0016 gains the disallowedTools amendment. agent-audit's
allowlist is data, so it gains disallowedTools too -- the ADR and the
validator that enforces it had come apart.

architecture.md described a root CLAUDE.md that imports two files (it imports
one, plus an RTK block) and pointed at an ADR index that does not exist.
Seven skill READMEs listed tests/ files the mirror strips, promising installed
users files their install lacks; those rows are marked source-only, with the
depth-4 template tests explicitly called out as surviving. And
plugins/kyberforge/hooks/README.md, deleted during the conversion and
preserved nowhere, is restored to a path the mirror does not own -- verified
by running a sync against a scratch copy.

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

plugins/kyberforge/docs/README.md

@@ -2,7 +2,11 @@
 
 Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
 
-This directory currently holds no standalone documents of its own — everything under it is research material.
+| Path | Purpose |
+|------|---------|
+| `hooks.md` | Where this plugin's hooks are authored (`.apm/hooks/`), where they are generated to (`hooks/hooks.json`), and the Claude Code and Copilot CLI schemas |
+
+Everything else under this directory is research material.
 
 ## research/
 

plugins/kyberforge/docs/hooks.md

@@ -0,0 +1,54 @@
+# Hooks
+
+Reference for this plugin's hook definitions: where to edit them, where they end up, and what the
+host reads.
+
+This document lives in `docs/` rather than next to the hooks it describes. `plugins/kyberforge/hooks/`
+is a **generated mirror** — `scripts/sync-plugin-content.sh` runs `rm -rf` on it before every
+rebuild, so any hand-written file placed there is deleted on the next sync with no drift warning
+(a prior copy of this document was lost exactly that way). See ADR-0017.
+
+## Where to edit
+
+Author hooks in `plugins/kyberforge/.apm/hooks/*.json`. `apm pack --format plugin` merges every
+file in that directory into a single `hooks.json`, which `sync-plugin-content.sh` copies to
+`plugins/kyberforge/hooks/hooks.json` — the path Claude Code convention-scans. Never edit the
+mirrored file; the `check-plugin-content-sync` pre-push hook reports it as drift.
+
+## Claude Code structure
+
+`hooks/hooks.json` is read by Claude Code. Structure:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "echo 'tool used'" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Supported events: `PreToolUse`, `PostToolUse`, `Notification`, `Stop`.
+
+Use `${CLAUDE_PLUGIN_ROOT}` to reference scripts inside this plugin — the plugin runs from a cache
+path after install, not its original repo location.
+
+## GitHub Copilot CLI
+
+Copilot reads a differently-shaped `hooks.json`: `version: 1` is required, each entry is
+`type: "command"` with separate `bash` and `powershell` scripts, and the lifecycle points are
+lowercase and differently named (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`,
+`postToolUse`, `errorOccurred`, `agentStop`). See
+`docs/research/docs/github-copilot-plugins/configuration.md`.
+
+There is no separate Copilot hooks file at this plugin root. An earlier revision of this document
+pointed at `hooks.json` at the plugin root for Copilot; that file was a stale artifact of the
+pre-ADR-0017 sync and was deleted. Both ecosystems now resolve to the single generated
+`hooks/hooks.json`, which is currently empty (`{"hooks": {}}`) — the two schemas would need
+reconciling before any real hook ships to both.