fix(docs): repair dead xrefs in api.md, runbook, skill

[Fearvox]

Summary

Three documentation cross-references point at targets that do not exist, so readers who click them land nowhere (or, in the plugin skill, are told to call MCP tools the server never exposes). All three are Markdown-only fixes that share one purpose: make the docs' internal references resolve to what actually exists.

• docs/api.md:796 — the content row of the buffered-message table links [MessageItem.content](#addmessage). There is no addmessage heading or HTML anchor anywhere in the file. Every other MessageItem cross-reference in api.md uses #messageitem (lines 21, 491), which matches the ### MessageItem heading at line 198. Fixed to #messageitem.
• docs/cascade_runbook.md:207 — [Recovery paths § FD exhaustion](#fd-exhaustion-os-error-24-emfile) uses a single hyphen. The GitHub-rendered slug of the heading ### FD exhaustion (\os error 24` / EMFILE)(line 146) isfd-exhaustion-os-error-24--emfile— the / ` separator becomes a double hyphen once the slash is stripped and both surrounding spaces are hyphenated. Fixed to the double-hyphen slug so the link scrolls to the FD-exhaustion section.
• use-cases/claude-code-plugin/skills/memory-tools.md:12 — this skill has alwaysInclude: true, so it is injected into every plugin session. It names two tools, search_memories and get_memory, that are implemented nowhere in the slice; get_memory's get-by-id capability does not exist at all. The MCP server (mcp/server.js:15) and commands/ask.md:18 expose exactly one tool, evermem_search (params query required, limit default 10 / max 20). Replaced the two phantom tool names with the real one so the always-on guidance matches the implementation.

Fixes #266, #267, #268.

Area

• Architecture method
• Benchmark
• Use case
• Documentation
• Developer experience
• CI, build, or release

Verification

# Patch applies cleanly
$ git apply --check ps-r1-docs.patch   # OK, all three hunks

# Docs hygiene gate (the workflow triggered by **/*.md changes) — no regressions
$ make docs-check
  python3 scripts/check_docs.py        # OK
  ruby -e YAML.load_file ISSUE_TEMPLATE # YAML ok x 5

# r1-1 / r1-2 anchor targets confirmed by manual slug check
#   (scripts/check_docs.py validates file existence, not in-page fragments)
$ grep -n '### MessageItem' docs/api.md         # 198: heading -> slug #messageitem
$ grep -n '#messageitem'   docs/api.md          # 21, 491, 796 all resolve to it
$ grep -n 'FD exhaustion (\`os error 24\`'   docs/cascade_runbook.md  # 146
#   GitHub slug of that heading = fd-exhaustion-os-error-24--emfile (double hyphen)

# r1-3 doc-vs-impl match confirmed against the live MCP surface
$ grep -rn 'evermem_search' use-cases/claude-code-plugin/mcp/server.js   # name + schema
$ grep -rn 'search_memories\\get_memory' use-cases/claude-code-plugin/   # 0 matches after fix

Checklist

• I kept the change scoped to the relevant area.
• I am opening this from a separate branch, not pushing directly to main.
• I updated docs, examples, or setup notes when behavior changed.
• I added or updated tests when the change affects behavior.
• I did not commit secrets, .env files, dependency folders, or generated output.
• Active relative links in Markdown files resolve.

Tests N/A: these are documentation cross-reference corrections with no runtime behavior change. The make docs-check gate and manual slug verification cover them.

Notes for Reviewers

• The memory-tools.md fix is the highest-impact one: the skill is alwaysInclude: true, so until it is corrected every plugin session is told to call two tools that do not exist, while the one real tool (evermem_search) is never named.
• scripts/check_docs.py deliberately strips the #fragment before validating links (link = raw.split("#", 1)[0]), so it does not catch dead in-page anchors. The two anchor fixes (r1-1, r1-2) are therefore verified by manual GitHub-slug computation rather than the CI gate; they will not regress the Docs workflow.
• No source code, tests, or config changed — Markdown only.

By submitting this pull request, I agree that my contribution is licensed under the Apache License 2.0.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.