[mikestankavich]

The trakrf/docs share of TRA-1128. Three commits, deliberately separate.

1. chore: ignore block + untrack (29 files)

The ignore rule pointed at spec/superpowers/ — the old path, swept in dca90c0 on 2026-08-03. The tooling had already started writing to superpowers/ at repo root three days before that sweep, so the sweep cleaned and ignored a location nothing writes to any more while the tree at the new location was never in scope. 29 files accumulated there unignored. spec/ no longer exists.

Adopts the canonical block. Byte-identity is acceptance criterion 1, so it was taken from the ticket itself — the description's superpowers stanza plus the docs/notes/ stanza from comment bd1463d8 — rather than from any relayed copy. Three sessions each broadcast a "paste-verbatim canonical block" and no two matched; one had picked up a sentence the ticket never contained.

Verified rather than eyeballed, since a pattern can be present and still not fire:

superpowers/specs/probe.md      → .gitignore:49:superpowers/
docs/superpowers/plans/probe.md → .gitignore:50:docs/superpowers/
.superpowers/probe.md           → .gitignore:51:.superpowers/
docs/notes/probe.md             → .gitignore:59:docs/notes/

sha256 of the 14 canonical lines is cfc7cf43…88a6d225, matching all four repos — provable identity rather than four people asserting they pasted carefully.

Three superpowers paths rather than one because the tooling's output default has already moved twice (spec/superpowers/ → docs/superpowers/ → root superpowers/), breaking a different repo each time. superpowers/ and .superpowers/ have no internal slash so they match at any depth; docs/superpowers/ has one and anchors to the root. Both deliberate.

The tree is removed from disk as well as untracked (AC#2 says deleted, not merely ignored) — load-bearing here, since an ignored-but-present file under a path Docusaurus globs still renders locally.

Also drops the orphaned # CSW local symlink comment, a header left with nothing under it when dca90c0 removed the pattern. No CSW pattern reintroduced; CSW is a plugin now.

2. style: prettier the three docs/api pages

prettier --check . reported 24 failures on main; 21 were the tracked superpowers files removed above. These three are the real remainder and are customer-facing. Own commit so the sweep reviews as a pure mechanical change (AC#6).

Whitespace only — table realignment, one rewrapped row, one blank line moved where Prettier normalises list spacing. No prose, links or code samples touched.

pnpm lint now exits zero (AC#5), which is what makes the validate command in .claude/csw.json usable as a gate.

3. docs: split shared agreements into AGENTS.md

CLAUDE.md carried two kinds of instruction with nothing marking the boundary. Each repo kept its own copy of the shared half, so they drifted independently and — as the ticket diagnoses — none mentioned spec artifacts at all.

• AGENTS.md (root) — shared, byte-identical in docs, platform, infra. sha256 8aae612ddf7bea89358c13df03ae395aef041533afb019406c15d7c9bd9ac3c1, 25 lines
• CLAUDE.md — only what is true of this repo, importing the shared half via @AGENTS.md

AGENTS.md rather than a bespoke name so any agent tool reads it, not only Claude Code. At the repo root rather than under .claude/ because a directory that reads as tool config is not where someone cloning the repo would look — tracked and discoverable are different properties and only the first was covered.

The split is justified by shared content across three repos, not by size. Imported files load at launch, so an import costs the same context as inlining. Both files are written to state rather than explain on separate grounds: this text loads every session in three repos, so rationale that can be re-derived isn't worth carrying.

	lines	words
CLAUDE.md on main	55	287
CLAUDE.md + AGENTS.md now	45	338

Fewer lines covering materially more (spec and note policy, verification rules, publishing gate, OpenAPI provenance). Not a token reduction against main — stating that plainly rather than claiming a win.

Scope is narrow by the same logic: only what a fresh session would otherwise get wrong. Contributing rules already live in CONTRIBUTING.md and now have a single source there. Worktrees are not mentioned — a workflow choice driven by .claude/csw.json, not one to impose on anyone cloning a public repo.

ble-mcp-test is deliberately not in this family — separate org, published npm package, different governance.

Pins the spec and plan output path (AC#3), the actual fix rather than documentation for its own sake: the tooling defaults to docs/superpowers/, but docs/ here is the published tree, and Docusaurus globs docs/**/*.md at build, so an ignored-but-present file renders locally while CI's fresh clone never sees it.

CONTRIBUTING.md gains the merge policy it was missing and its branch-naming is corrected — it documented feature/add-xyz while .claude/csw.json specifies <type>/<ticket>-<slug> and every branch actually cut uses the latter. Outside contributors have no ticket, so the plain <type>/<slug> form is named for them.

On the digest above: AGENTS.md has been superseded twice during this work, so earlier digests (f01ea43d…, and one before it) are dead while looking exactly as canonical as the current one. Re-derive from the branch rather than trusting any hash quoted elsewhere, and pipe straight to sha256sum — capturing file content into a shell variable strips the trailing newline and yields a wrong-but-plausible result. Line count is the cheap tell: 25 is current, 28 is dead.

Verification

pnpm lint       PASS   (was failing on main)
pnpm typecheck  PASS
pnpm build      PASS

• Wide grep -rn superpowers — zero dangling references into the deleted tree. The passing build under onBrokenLinks: throw independently confirms no published page linked into it.
• grep -n "@" CLAUDE.md AGENTS.md — exactly one hit, the intended import, not backtick-wrapped. Import parsing skips code spans, so a backticked @path is present, correct-looking and silently dead.

One gap, stated rather than glossed: the import is documented-to-work and syntactically verified, but not observed loading. It is verified that AGENTS.md exists at the expected path, that CLAUDE.md contains exactly one bare @AGENTS.md outside a code span, and that no stray @ could resolve elsewhere. Whether the loader actually consumed it is unverified.

/context is the only way to confirm the import loaded. Worth ten seconds at review time to close.

Correction — that instruction was wrong and is struck rather than deleted, since it was acted on. /context reports Memory files as a token total only (⛁ Memory files: 9.6k tokens (1.0%)), with no filenames; /context all expands MCP tools and skills, not memory files. There is no list in which AGENTS.md could appear, so the check had no place for a negative answer to show up — it could not fail visibly, while telling a reviewer they had verified something. The instruction was sourced from documentation describing a list this build does not print: an accurate citation over a false premise, and nobody ran it before recommending it.

RESOLVED — the import loads. Confirmed by artifact, not agreement. An InstructionsLoaded hook (registered in gitignored local settings, never repo config, deliberately not in this PR) caught a fresh session start:

{"hook_event_name":"InstructionsLoaded",
 "file_path":".../AGENTS.md",
 "memory_type":"Project","load_reason":"include",
 "parent_file_path":".../CLAUDE.md"}

load_reason: "include" with parent_file_path naming CLAUDE.md is the harness stating the import resolved at session start. The same log carries CLAUDE.md at load_reason: "session_start" — the control that proves the instrument was live, without which an empty log would have been evidence of nothing rather than evidence of absence.

A weaker but real fallback is the Memory files token count. Retracted. A fresh session reads 9.4k and a long-running one 9.6k, but that comparison confounds three variables at once — old vs new CLAUDE.md, import absent vs present, and an auto-memory index that grew mid-session. The number cannot separate them, so it is not a weak signal but no signal. Use the hook or nothing.

Notes for review

• AGENTS.md is a shared artifact — platform and infra should pull the file from this branch rather than retype it. Retyping is what produced three non-matching "canonical" blocks earlier in this work.
• This repo's CONTRIBUTING.md was checked for the stale-example-filename rot found in infra and is clean; nothing fixed there beyond what the ruling touched.

Closes the trakrf/docs portion of TRA-1128 — 99 files ever tracked across the estate, 0 remaining once this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RWAqULDa91P8QxVD6hRaer

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	6a0e3d7
Status:	✅  Deploy successful!
Preview URL:	https://b0803f08.docs-4n7.pages.dev
Branch Preview URL:	https://preview.docs-4n7.pages.dev

View logs

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id