Skip to content

feat(docs): generate the @gittensory command reference from src/github/commands.ts instead of hand-copying #3046

Description

@JSONbored

Context

docs.maintainer-workflow.tsx, docs.maintainer-install-trust.tsx, and docs.beta-onboarding.tsx each hand-list a subset of the @gittensory command surface. This is exactly how the 9-command maintainer-only queue-digest family (queue-summary, confirmed-miners, review-now, needs-author, duplicate-clusters, burden-forecast, intake-health, outcome-patterns, noise-report) went completely undocumented until a 2026-07-04 audit caught it -- three independent hand-copies of a list that lives as structured data in src/github/commands.ts (PUBLIC_MENTION_COMMAND_CATALOG, MAINTAINER_QUEUE_DIGEST_COMMAND_CATALOG, each entry already carrying id/title/description).

The docs-drift lint (see the Phase 1 sibling issue) catches this going forward by failing CI, but it doesn't fix the root cause: the list is still hand-copied three times, so drift is caught late (at CI) rather than prevented (by construction).

Goal

Generate a markdown or TS fragment from the command catalogs -- mirroring scripts/gen-selfhost-env-reference.mjs's existing generate-from-source pattern -- and have the docs pages import/render it instead of hand-listing commands.

Requirements

  • A generator script (e.g. scripts/gen-command-reference.mjs) that reads src/github/commands.ts's two catalogs and emits a data structure (or markdown table) consumable by the docs pages, matching gen-selfhost-env-reference.mjs's check/write dual-mode convention (--check for CI, no flag to regenerate).
  • Update docs.maintainer-workflow.tsx and docs.maintainer-install-trust.tsx to render the generated list instead of a hand-written CodeBlock.
  • docs.beta-onboarding.tsx intentionally curates a shorter onboarding subset -- leave it hand-picked, but reference the full generated list for readers who want the complete surface.
  • Once this ships, evaluate whether the same treatment is worth it for the GITTENSORY_REVIEW_* flag descriptions on docs.tuning.tsx/docs.privacy-security.tsx -- today those descriptions are free-text JSDoc comments in src/env.d.ts, not a structured catalog like commands.ts already has, so this would need a lightweight structured registry added first. Scope that as a follow-up if it's worth the churn, don't block this issue on it.

Deliverables

  • scripts/gen-command-reference.mjs (+ --check mode wired into test:ci)
  • Updated docs.maintainer-workflow.tsx / docs.maintainer-install-trust.tsx

Expected outcomes

The command surface is documented exactly once, at the source, so a new command can't ship without automatically appearing in the docs -- eliminating this whole failure class by construction rather than by lint.

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions