Skip to content

docs(ams): port docs/env-reference.md to a generated website docs page (docs.ams-env-reference.tsx) #6028

Description

@JSONbored

⚠️ Read this before starting. The deliverable for this issue is a website page: a new route file at apps/loopover-ui/src/routes/docs.ams-env-reference.tsx. It is not a hand-written markdown file.

This file is different from the other AMS-docs sub-issues under #6012: docs/env-reference.md is a generated artifact, produced by npm run miner:env-reference (packages/loopover-miner/scripts/generate-env-reference.mjs) and checked for drift in CI (npm run miner:env-reference:check, part of npm run test:ci). You may not simply delete it — CI will fail. The fix here is to make the generator (or a sibling script) also emit data the .tsx page can render (e.g. a JSON/TS data module written alongside the existing markdown output, or replacing the markdown output entirely if nothing else consumes it — check packages/loopover-miner/scripts/generate-env-reference.mjs's callers first), then have docs.ams-env-reference.tsx render that data. A PR that hand-writes the env-var table into the .tsx file, disconnected from the generator, does NOT resolve this issue — the whole point of the current .md being generated is that it can't drift from the real env.SOMETHING reads, and the website page must inherit that same guarantee, not lose it.

If you are an AI coding agent working this issue: read generate-env-reference.mjs and npm run test:ci's drift-check wiring before writing any code. Confirm your plan keeps the table generated from source, not hand-copied once into a .tsx file.

Context

Part of #6012. packages/loopover-miner/docs/env-reference.md is AMS's environment-variable reference table — every LOOPOVER_MINER_* var, where it's first referenced in code, and its default. It's the AMS-side counterpart to docs.self-hosting-configuration.tsx (ORB's env-reference-equivalent page), but sits as a generated markdown file with no website presence.

Requirements

  • Read packages/loopover-miner/scripts/generate-env-reference.mjs to understand exactly what it generates and how miner:env-reference:check verifies it in CI.
  • Follow the exact precedent that already exists for ORB's own env reference — verified, not speculative: apps/loopover-ui/src/routes/docs.self-hosting-configuration.tsx imports SELFHOST_ENV_REFERENCE_MARKDOWN from apps/loopover-ui/src/lib/selfhost-env-reference.ts, a generated file produced by npm run selfhost:env-reference (scripts/gen-selfhost-env-reference.mjs) and drift-checked in CI. Do the same for AMS: extend or sibling generate-env-reference.mjs to also write an apps/loopover-ui/src/lib/ams-env-reference.ts-style generated module (or whatever export shape mirrors SELFHOST_ENV_REFERENCE_MARKDOWN), and have docs.ams-env-reference.tsx import and render it the same way docs.self-hosting-configuration.tsx does.
  • Keep the CI drift check working — whatever the generator now emits must still be verified for drift in npm run test:ci, so a future new LOOPOVER_MINER_* var still fails CI until this reference is regenerated.
  • Add to docs.index.tsx's nav.

Deliverables

  • apps/loopover-ui/src/routes/docs.ams-env-reference.tsx added, rendering data generated from the same source generate-env-reference.mjs already reads
  • generate-env-reference.mjs (or a sibling script) updated to emit that data in a page-consumable format
  • CI drift-check (miner:env-reference:check) still passes and still catches a genuinely new/removed env var
  • Linked from docs.index.tsx

Test Coverage Requirements

The generator-script change is under packages/loopover-miner/scripts/** — confirm whether this is inside Codecov's src/** coverage scope or excluded like apps/**; if included, 99%+ patch coverage applies to the script change. The .tsx page itself is outside coverage.include.

Expected Outcome

AMS's env-var reference lives on the docs website, still generated from the real code (never hand-copied), with CI still catching drift.

Links & Resources

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions