docs(commands): add @gittensory command reference page (#2171)

[rust-toml]

Fixes #2171

Summary

• Add /docs/gittensory-commands documenting every Q&A verb, maintainer queue digest, and PR action command with syntax, effect, and default authorization roles.
• State the hard boundary: commands never flip the gate to advisory; pause/resume affect only auto-review.
• Extend gen-command-reference to export action-command catalog entries for docs drift safety.
• Link the doc from the @gittensory help card, maintainer workflow, and docs index.

Test plan

• npm run test:ci (local, Node 22.18)
• npm run command-reference:check and npm run docs:drift-check
• helpSections includes the public docs URL (docs(commands): document the @gittensory PR command surface (verbs, roles, auto-review-vs-gate boundary) #2171)
• UI typecheck + build (route tree regenerated)

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-06 19:45:46 UTC}

11 files · 1 AI reviewer · no blockers · readiness 100/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

Review summary
This PR adds a docs page enumerating every @​gittensory command with syntax, effect, and default roles, extends the code-generator to emit ACTION_COMMAND_ENTRIES/LIST alongside the existing public/maintainer entries, and wires drift checks plus a help-card link to the new page. The generator and drift-check changes are mechanical and consistent with the existing pattern (same extraction/render/write flow just parameterized over a third catalog), and the new route/tests follow existing conventions. The one soft spot is that apps/gittensory-ui/src/routes/docs.gittensory-commands.tsx:20-46 hand-maintains a `DEFAULT_ROLE_SUMMARY` role map that is not generated or drift-checked, so despite the stated goal of 'docs drift safety' the per-command role text can silently go stale even though the command IDs themselves are protected.

Nits — 5 non-blocking

• docs.gittensory-commands.tsx:20-46 — `DEFAULT_ROLE_SUMMARY` duplicates per-command authorization roles by hand; unlike the generated ID/description entries, nothing checks this map against the real default policy, so it can drift silently (falls back to 'see policy' if a new command id is added, but existing entries can still go stale).
• scripts/gen-command-reference.mjs:58 — the magic number `7` for the minimum action-command count should be a named constant like the existing `MIN_TOTAL_COMMANDS`, for consistency and self-documentation.
• docs.gittensory-commands.tsx:98 — `GittensoryCommandsReference` is right at the 60-line function-size threshold; consider extracting the `CodeBlock`/table sections if it grows further.
• Test-to-code ratio is low for this PR (13 test lines added vs 355 source lines); consider a test asserting `DEFAULT_ROLE_SUMMARY` covers every id in the three exported entry arrays to catch future drift.
• Add a small assertion (unit test or drift-check addition) that every `entry.id` across PUBLIC/MAINTAINER/ACTION_COMMAND_ENTRIES has a corresponding key in `DEFAULT_ROLE_SUMMARY`, so new commands can't ship with a silently-wrong 'see policy' fallback.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2171
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: 0 registered-repo PR(s), 0 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	rust-toml; Gittensor profile; 0 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: rust-toml
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, Rust, C++, Go, Java, JavaScript, Solidity
• Official Gittensor activity: 0 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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

[superagent-security]

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

[codecov]

❌ 10 Tests Failed:

Tests completed	Failed	Passed	Skipped
10571	10	10561	7

View the top 3 failed test(s) by shortest run time

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > self-defends against a broken flag-extraction regex (fewer than 10 flags found)

Stack Traces | 0.000761s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:216:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > self-defends against a broken gate-mode-extraction regex (fewer than 5 fields found)

Stack Traces | 0.000939s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:237:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > catches a docs page missing a known @gittensory command

Stack Traces | 0.00103s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:172:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > catches a docs page missing a known feature flag

Stack Traces | 0.00104s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:161:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > catches an unmapped *GateMode field missing from GATE_MODE_MANIFEST

Stack Traces | 0.00108s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:148:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > skips per-command checks for a page that delegates to the generated command-reference instead of listing commands itself

Stack Traces | 0.00112s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:185:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > still checks a page for missing commands when it does NOT delegate to the generated command-reference

Stack Traces | 0.00198s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:195:22

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > catches a docs page missing a gate-mode alias

Stack Traces | 0.00332s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:207:22

test/unit/gen-command-reference-script.test.ts > gen-command-reference script (#3046) > collectCommandCatalogs > extracts a fixture with exactly 15 total commands without throwing

Stack Traces | 0.0125s run time

Error: gen-command-reference: extraction found only 0 PR action command(s) in src/github/commands.ts -- expected 7; the extraction regex may be broken
 ❯ collectCommandCatalogs scripts/gen-command-reference.mjs:59:11
 ❯ test/unit/gen-command-reference-script.test.ts:87:54

test/unit/check-docs-drift-script.test.ts > check-docs-drift script > checkDocsDrift > passes cleanly against a fully-consistent synthetic fixture set

Stack Traces | 0.0133s run time

Error: unexpected read: .../src/routes/docs.gittensory-commands.tsx
 ❯ test/unit/check-docs-drift-script.test.ts:132:43
 ❯ read scripts/check-docs-drift.mjs:80:34
 ❯ checkDocsDrift scripts/check-docs-drift.mjs:114:24
 ❯ test/unit/check-docs-drift-script.test.ts:139:22

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.