[clubanderson]

Part 2 of #15299 — Fixes #15299.

src/docs/api-reference.md becomes an index page; each former ## section is now its own page under src/docs/api-reference/<area>.md, grouped the way the table already was (route prefix / handler file):

health-status-events, snapshots-and-style, auth, configuration, agents-and-controls, packs-and-acmm, cost-tokens-telemetry, knowledge, contribute, nous, inception, beads, dashboard-misc, hub-saas, hub-server — 15 pages, all 620 route rows moved verbatim (relative links re-rooted with ../).

Anchors. The index keeps every former ## <section> heading (each now a one-line pointer to its page), so existing api-reference.md#<section> links keep resolving; the two in-tree users (agent-configuration.md, acmm-advisor.md) were pointed straight at the area pages. check-docs-links.py passes.

Tooling.

• check-api-reference-citations.sh walks api-reference.md + api-reference/*.md by default; a file or directory may still be passed. Drift messages name the page (DRIFT api-reference/contribute.md:12 …), and --fix rewrites only the page whose citations drifted, so a route move in one area touches one small file.
• check-docs-citations.py --fix passes the directory through to the checker.
• test-check-api-reference-citations.sh gains a case for the directory walk and the per-page --fix (other pages and the index stay byte-identical).
• Workflow step names/messages (docs-link-check.yml, changelog-fragment-guard.yml), AGENTS.md, src/README.md, documentation-map.md updated. No Go code reads api-reference.md (only comments mention it).

Verified: check-api-reference-citations.sh, test-check-api-reference-citations.sh, check-docs-links.py src/docs, check-docs-citations.py src/docs, test-check-docs-citations.sh — all green.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign danathar for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#15282	📖 docs: make Hive guides easier to follow	same files	src/docs/agent-configuration.md src/docs/documentation-map.md
#15303	🌱 refactor: split API reference into area files	same files	.github/workflows/changelog-fragment-guard.yml .github/workflows/docs-link-check.yml AGENTS.md src/docs/api-reference.md src/docs/api-reference/beads.md src/docs/api-reference/configuration.md src/docs/api-reference/contribute.md src/docs/api-reference/cost-tokens-telemetry.md src/docs/api-reference/health-status-events.md src/docs/api-reference/hub-saas.md src/docs/api-reference/hub-server.md src/docs/api-reference/inception.md src/docs/api-reference/knowledge.md src/scripts/check-api-reference-citations.sh src/scripts/check-docs-citations.py src/scripts/test-check-api-reference-citations.sh
#15300	🌱 dashboard: generate index.html from per-area sources	same files	src/docs/documentation-map.md

[hivecommons-hive]

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

[hivecommons-hive]

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

• the branch conflicts with the base and needs a rebase

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

[hivecommons-hive]

Read the checker changes against v5 and the whole diff. Looks correct to me.

• check-api-reference-citations.sh: the original citation loop has no early exit, so turning it into check_doc with shared counters and iterating DOCS preserves the existing --fix / drift exit semantics across pages (src/scripts/check-api-reference-citations.sh:131-219). DOC_LABEL="${DOC#*/docs/}" makes drift messages name the page to edit, and the new test case asserts the index and the non-drifted page stay byte-identical.
• check-docs-citations.py:279-288 passes api-reference/ explicitly, so --fix reaches the pages without relying on the shell default.
• Index keeps every former ## heading; acmm-advisor.md:73 and agent-configuration.md:130 are re-pointed at the pages. Link check is green.

Two small notes, neither blocking:

1. add_doc_path on a directory containing no *.md adds nothing and the run then reports success (:71-84) — only reachable by passing an empty directory explicitly; #15303's version of the same change fails that case.
2. The body says Fixes #15299, so merging this closes the tracker while part 1 (#15300) is still open. If #15299 should stay open until both parts land, Refs #15299 is the non-closing form.

This is the same change as #15303 (conflicting page names); I've flagged the duplicate there for a decision on which survives.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Superseded by #15303 (earlier fix for #15299). Leaving open because a person authored this PR — close it if #15303 covers your change, or comment why both should land.

[hivecommons-hive]

35d3162

ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head 35d31621eb53) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

• sensitive_path — changes 2 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
  • .github/workflows/changelog-fragment-guard.yml
  • .github/workflows/docs-link-check.yml

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

[hivecommons-hive]

Decision needed: @clubanderson should decide whether #15304 supersedes fork PR #15303 (same split of api-reference.md into 15 area pages, different page slugs, so the two conflict) and whether this part-2 PR should say Refs #15299 rather than Fixes #15299 while part 1 (#15300) is still open.

Looks correct to me as a split; it duplicates and conflicts with #15303 (thatguywob, fork). I read both diffs in full.

Verified on this PR:

• Every | METHOD | route row removed from src/docs/api-reference.md reappears in exactly one src/docs/api-reference/*.md page, byte-identical after the ](../ relative-link re-rooting — 622 removed, 622 added (+2 fixture rows in src/scripts/test-check-api-reference-citations.sh). The only rows that appear twice in hub-saas.md (e.g. /api/saas/whoami, /api/saas/upgrade-pause) are already duplicated twice on v5 api-reference.md, so that is pre-existing, not introduced here.
• .github/workflows/changelog-fragment-guard.yml / docs-link-check.yml changes are comment text, step names and the ::error:: message only — no permission, trigger or step-content changes.
• The index keeps each former ## <section> heading as a one-line pointer, so existing api-reference.md#<anchor> links keep resolving.

Why this and #15303 cannot both land: #15303 makes the same 15-page split with different slugs (agents-controls, auth-external-accounts, nous-strategy-lab, dashboard-miscellaneous, snapshots-style, packs-acmm vs agents-and-controls, auth, nous, dashboard-misc, snapshots-and-style, packs-and-acmm here) and both rewrite check-api-reference-citations.sh, check-docs-citations.py and the two workflows. #15303 is currently dirty against v5, carries sentinel-alert, and is at stage 072 (returned to contributor); this one is mergeable, also updates src/README.md, documentation-map.md and the two in-tree anchor users (acmm-advisor.md, agent-configuration.md), which #15303 does not. On that basis this one looks like the survivor — but closing a contributor's PR is a maintainer call, and I have not closed anything.

One link-semantics note: the body says "Part 2 of #15299 — Fixes #15299" while part 1 (#15300) is open and its own body only says "Part 1 of #15299". Whichever merges first with Fixes closes the issue with the other half unmerged; Refs #15299 (part 1 in #15300) would keep it open until both land.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Decision needed: @clubanderson should decide which of #15304 and #15303 carries the api-reference split for #15299 — they choose different page filenames, so they conflict and only one can land.

Overlaps #15303 — same change, conflicting layout. Both PRs implement part 2 of #15299: turn src/docs/api-reference.md into an index, move the 620 route rows into 15 pages under src/docs/api-reference/, and teach check-api-reference-citations.sh / check-docs-citations.py --fix to walk the directory. I read both diffs; the tooling is functionally equivalent, but the page names differ (auth.md vs auth-external-accounts.md, agents-and-controls.md vs agents-controls.md, nous.md vs nous-strategy-lab.md, dashboard-misc.md vs dashboard-miscellaneous.md, …), so they conflict rather than stack — whichever merges second cannot rebase cleanly.

Of the two, this one looks preferable to me: it is mergeable against v5 (#15303 is currently DIRTY), and it also re-points the two in-tree api-reference.md#… deep links (acmm-advisor.md, agent-configuration.md) and documentation-map.md/src/README.md, which #15303 leaves at the old anchors. #15303 was already routed to a human at its current head, so I am not commenting there again.

One thing to change here regardless: the body says Fixes #15299, but #15299 is explicitly a two-part tracker and part 1 (dashboard index.html, #15300) is still open. As written, merging this closes the issue with half the work undone. Suggest Refs #15299 (part 2; part 1 remains in #15300) — which is what #15303 does.

What I verified in the tooling (src/scripts/check-api-reference-citations.sh):

• add_doc_path / DOCS resolution (lines 71–91) accepts files or directories and preserves the single-file legacy call; check_doc sets the global DOC that extract_citations reads, and the drifted/resolved/unresolved counters stay global across pages, so the exit code aggregates correctly.
• --fix rewrites only the page whose citation drifted (the awk→mv on "$DOC" is the pre-existing in-place path, now per page).
• .github/workflows/* changes are comments, an error message, and one step name (Check api-reference source citations); no job rename, no permission change. Flagging only because workflow files are a trust surface.

I have not closed or approved anything.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Decision needed: @clubanderson should decide whether #15304 is the api-reference split that lands (and #15303 is closed), and whether its "Fixes #15299" should become "Refs #15299" while dashboard part 1 (#15300) is still open.

Conclusion: the split itself checks out locally and the red CI on this head is baseline breakage on v5, not this PR. Two things need a maintainer's call: this PR conflicts with #15303 (same refactor, different page names), and the issue-link wording.

Verified against the tree (head fcc6802):

• bash src/scripts/test-check-api-reference-citations.sh → PASS (incl. the new directory-walk and per-page --fix cases).
• bash src/scripts/check-api-reference-citations.sh → "all pkg/: references verified".
• python3 src/scripts/check-docs-links.py → 274 files, all links and anchors resolve.
• Route rows: 622 in the old api-reference.md, 622 across api-reference/*.md. All 15 former ## headings survive in the index (plus a new ## Areas), so api-reference.md#<section> links keep resolving as the body claims.
• .github/workflows/docs-link-check.yml changes only a comment and a step name — no permission or trigger change. AGENTS.md change is the matching one-line guidance update.

CI is red for reasons unrelated to this diff. Every failing job (test, coverage, golangci-lint, test (dashboard */4), shuffle) dies at the same compile error: pkg/dashboard/stage_tracker_linked_progress_test.go:95:31: not enough arguments in call to stageTrackerResolveLinkedPRs. That file is untouched here; on v5 HEAD (4536f90) the test calls stageTrackerResolveLinkedPRs(items) while stage_tracker.go:2948 now takes (items, open func(string,int) bool). The test check is also failing on v5 HEAD itself. So this PR will stay red until v5 is fixed, regardless of its content — worth a separate fix PR.

Conflict with #15303 (refactor: split API reference into area files, @thatguywob). I read both diffs in full: same 15-way split, same checker extension, but the page filenames differ (agents-and-controls.md vs agents-controls.md, auth.md vs auth-external-accounts.md, dashboard-misc.md vs dashboard-miscellaneous.md, nous.md vs nous-strategy-lab.md, packs-and-acmm.md vs packs-acmm.md, snapshots-and-style.md vs snapshots-style.md). Only one can land. #15303 is currently DIRTY against v5 and carries stage/072-returned-to-contributor + sentinel-alert; this one is mergeable and additionally re-points the two in-tree deep links (agent-configuration.md, acmm-advisor.md) and documentation-map.md/README.md. On that basis this PR looks like the one to keep, but closing a contributor's PR is a human call. I have not closed anything.

Issue link. The body says "Part 2 of #15299 — Fixes #15299" while part 1 (dashboard, #15300) is still open and #15303 deliberately used Refs for that reason. If #15300 should land before #15299 closes, this should be Refs #15299 (part 1 in #15300); if the dashboard half is being dropped or tracked elsewhere, Fixes is right. Either way the body should say which.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Shared CI baseline incident — not caused by this PR. The failing pkg/dashboard shards (and the downstream test, coverage, build-and-test, golangci-lint checks) are red on v5 HEAD itself:

pkg/dashboard/stage_tracker_linked_progress_test.go:95:31: not enough arguments in call to stageTrackerResolveLinkedPRs

Tracked in #15322; fix in #15321. No action needed here — once #15321 lands, this PR will go green on its next run / rebase.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Decision needed: @clubanderson should decide whether #15304 supersedes #15303 (both implement part 2 of #15299 with different area-page filenames, so they conflict rather than coexist) and whether this PR should say Refs #15299 instead of Fixes #15299 while part 1 (#15300) is still open.

Looks correct to me; the two open questions are routing, not code.

Verified at cfaf252 (clone of v5 + PR head, scripts run locally):

• bash src/scripts/test-check-api-reference-citations.sh → PASS, including the three new Case 4 assertions (directory walk, per-page --fix, untouched siblings).
• bash src/scripts/check-api-reference-citations.sh → all pkg/<file>:<line> citations verified across the index + 15 pages.
• python3 src/scripts/check-docs-links.py src/docs → 274 files, all links/anchors resolve.
• Row count: origin/v5:src/docs/api-reference.md has 622 table rows; the 15 pages under src/docs/api-reference/ total 622, index has 0 — the move is verbatim as the body claims.
• src/scripts/check-api-reference-citations.sh:131-134 — check_doc reassigns the global DOC per page, so the pre-existing extract_citations and the awk rewrite at :209 keep operating on the right file; --fix only writes ${DOC}.tmp for the page containing a drifted row.
• The two .github/workflows/* hunks change only a comment and an ::error:: message string (changelog-fragment-guard.yml:143,160, docs-link-check.yml:108-114); no permissions, triggers or steps change.

Duplicate of #15303. I read both diffs in full: #15303 (fork, 9f03fde, currently dirty against v5) makes the same split of the same 15 sections into src/docs/api-reference/ with the same checker/--fix extension, but under different filenames (agents-controls.md vs agents-and-controls.md, auth-external-accounts.md vs auth.md, nous-strategy-lab.md vs nous.md, packs-acmm.md, snapshots-style.md, dashboard-miscellaneous.md). Same intent per both bodies; they cannot both merge. This one is mergeable, authored in-repo, also repoints the two in-tree deep links (agent-configuration.md, acmm-advisor.md) and updates documentation-map.md/src/README.md, which #15303 does not. If you agree, #15303 could be closed in favour of this one. I have not closed anything.

Issue link. #15299 is a two-part tracker (part 1 = dashboard, #15300, still open). Fixes #15299 here will close the issue when this merges with part 1 unmerged; #15303 deliberately used Refs. If the tracker should stay open until #15300 lands, Refs #15299 is the intended form.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback