feat(docs): generate the @gittensory command reference from source instead of hand-copying

[JSONbored]

Summary

• docs.maintainer-workflow.tsx and docs.maintainer-install-trust.tsx each hand-copied the @gittensory command list from src/github/commands.ts's two catalogs (PUBLIC_MENTION_COMMAND_CATALOG, MAINTAINER_QUEUE_DIGEST_COMMAND_CATALOG) — exactly how the 9-command maintainer-only queue-digest family went completely undocumented until a separate audit caught it.
• Adds scripts/gen-command-reference.mjs, mirroring scripts/gen-selfhost-env-reference.mjs's generate/--check dual-mode convention: it extracts both catalogs' full {id, title, description} entries from src/github/commands.ts (same catalog-array-slicing regex approach as extractCatalogIds, extended to keep the full entry) and writes apps/gittensory-ui/src/lib/command-reference.ts, exporting PUBLIC_COMMAND_LIST and MAINTAINER_COMMAND_LIST as plain @gittensory <id>-per-line string constants.
• Wires command-reference / command-reference:check into package.json and adds command-reference:check to the test:ci chain (before ui:lint).
• Updates both docs pages to import and render PUBLIC_COMMAND_LIST / MAINTAINER_COMMAND_LIST from @/lib/command-reference instead of a hand-written CodeBlock string, bringing both pages to the full 10 public + 9 maintainer-only command set.
• docs.beta-onboarding.tsx is intentionally left untouched — it curates a smaller 7-command onboarding subset by design, not the full catalog (per the issue).
• Includes a self-defense floor (fewer than 15 total extracted commands = fail loudly, not silently write a tiny file) and a regression-guard test proving the committed generated file matches what the generator produces right now from the real source.

Fixes #3046

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — my diff touches only scripts/**, apps/**, and test/**, all Codecov-ignored paths, so it carries no src/** patch-coverage obligation; ran anyway as part of the full npm run test:ci gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — see test/unit/gen-command-reference-script.test.ts: catalog-slicing extraction (including the "two catalogs don't bleed into each other" case), empty-list rendering, the sub-15-total self-defense throw, a fixture with exactly 15 total commands, the real-repo extraction (10 public + 9 maintainer, in source order), a regression guard that the committed generated file is byte-identical to what the generator produces right now, and a subprocess --check run against the real repo state.

Also ran, additionally, beyond the template's list: npm run command-reference:check (passes — the generated file matches source), and the full npm run test:ci chain end-to-end (all steps green, including the new command-reference:check step in its wired position before ui:lint).

Note on npm run docs:drift-check: this script does not exist yet on main at the base commit of this branch — it ships in the still-open sibling issue #3047 (PR #3059). I confirmed the ordering this issue asks for (command-reference:check immediately before ui:lint) is exactly the slot docs:drift-check will also occupy once that PR lands, so no reordering will be needed later. I also confirmed my generated @gittensory <id> lines are literal substrings docs:drift-check's extractCatalogIds-based cross-check will look for, once it exists.

If any required check was skipped, explain why:

• None skipped. npm run test:release/changelog:check are release-prep only and not applicable here.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/session/CORS changes in this PR.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no API/OpenAPI/MCP surface changed.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — this replaces a static hand-written string with a build-time-generated static string; both are static docs content, not runtime data.)
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails — see the UI Evidence note below for why screenshots are not attached here.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

This PR does change what two docs pages render (docs.maintainer-workflow.tsx's "On-demand commands" section and docs.maintainer-install-trust.tsx's "Command authorization" section), but the visible text is byte-identical to what a correctly-completed hand-copy of the current source catalogs would show — I generated PUBLIC_COMMAND_LIST/MAINTAINER_COMMAND_LIST directly from the same src/github/commands.ts catalogs the hand-written blocks were always meant to mirror, in the same catalog order, using the same @gittensory <id> line format the existing hand-written CodeBlocks already used. A rendered screenshot of the new page would look identical to a correctly-maintained hand-copy of the current 10 public + 9 maintainer-only commands; the change is entirely in how that text is produced (generated from source vs. hand-typed), not in its rendered appearance for a reader looking at the page today. I'm omitting a before/after screenshot table for this reason rather than attaching one of an unchanged render, per the issue's own framing (the goal is generation without changing the intended documented surface).

Notes

• scripts/check-docs-drift.mjs (the CI check referenced by issue feat(docs): generate the @gittensory command reference from src/github/commands.ts instead of hand-copying #3046 as extractCatalogIds's source) does not exist on main yet — it is still part of the open sibling issue feat(ci): add a docs-drift check for GITTENSORY_REVIEW_* flags, @gittensory commands, and gate-mode dimensions #3047 / PR docs(gittensory-ui): fix stale website docs and add a CI docs-drift check #3059. I read PR docs(gittensory-ui): fix stale website docs and add a CI docs-drift check #3059's diff to confirm the exact extractCatalogIds regex shape and reused the same catalog-array-slicing approach (const <NAME> = [...] as const;, non-greedy to the first close) in scripts/gen-command-reference.mjs's own extractCatalogEntries, extended to capture the full {id, title, description} entry instead of just the id.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	9ab1d60	Commit Preview URL Branch Preview URL	Jul 04 2026, 11:14 AM

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-04 11:18:39 UTC}

7 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR moves the two maintainer docs pages from hand-copied command lists to a generated UI module and wires a stale-file check into the main CI script. The generated file matches the claimed 10 public and 9 maintainer-only command IDs, and the docs imports are straightforward. I do not see a reachable correctness break in the provided diff, but the extraction parser is intentionally brittle and should be tightened before it becomes the next drift source.

Nits — 6 non-blocking

• nit: scripts/gen-command-reference.mjs:31 relies on a regex that only extracts entries when `id`, `title`, and `description` appear in that exact order with double-quoted string literals, so a harmless catalog formatting change could drop a command while still staying above the 15-command floor.
• nit: scripts/gen-command-reference.mjs:31 accepts `catalogConstName` directly into `new RegExp`; the current internal callers pass constants, but the exported helper should either escape the name or keep it private to avoid surprising matches in tests/tools.
• nit: test/unit/gen-command-reference-script.test.ts:76 only proves the happy-path fixture with the current exact property order, so it does not document the parser's accepted source shape or guard against partial extraction above the floor.
• scripts/gen-command-reference.mjs:31: either parse `src/github/commands.ts` through TypeScript/tsx and import the catalogs directly, or add explicit tests and failure messaging that define the exact supported catalog literal shape.
• scripts/gen-command-reference.mjs:31: escape `catalogConstName` before interpolating it into the regex, or stop exporting `extractCatalogEntries` if arbitrary catalog names are not a supported API.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3046
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 59 registered-repo PR(s), 50 merged, 454 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 59 PR(s), 454 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 59 PR(s), 454 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.11%. Comparing base (f306d07) to head (9ab1d60).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3063   +/-   ##
=======================================
  Coverage   96.11%   96.11%           
=======================================
  Files         263      263           
  Lines       28962    28962           
  Branches    10538    10538           
=======================================
  Hits        27836    27836           
  Misses        492      492           
  Partials      634      634           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.