fix(selfhost): stop embedding line numbers in the generated env-reference doc

[JSONbored]

Summary

• `scripts/gen-selfhost-env-reference.mjs` embedded the exact `file:line` of each env var's first source reference into the committed `apps/gittensory-ui/src/lib/selfhost-env-reference.ts`. Any PR that adds/removes lines anywhere above such a reference shifts that line number, so two concurrent PRs touching the same source file produce two different regenerated versions of the same row and collide on rebase — a merge conflict in a generated file no human is meant to hand-edit.
• Confirmed real, repeated churn from git history (not theoretical): 3 past reactive regeneration commits (`408ea483`, `eec83fd3` "again", `a4132113`) plus a CI-enforcement commit (`ae0faa8e`) added specifically because this kept happening. Most recently hit PR fix(selfhost): preserve legacy dual-review behavior for multi-provider AI_PROVIDER #3625, which needed a manual conflict resolution before it could merge.
• Dropped the embedded line number; `firstReference` is now just the file path. The path only changes when a read is actually added/removed/relocated to a different file — the only case that should ever require regenerating this doc.
• Updated the three docs that documented the old `file:line`-triggers-regeneration behavior: `AGENTS.md`/`CLAUDE.md` (symlinked), and the contributing skill's `SKILL.md` + `reference.md`.
• A follow-up audit (separate investigation, not part of this diff) confirmed this is the ONLY generated file in the repo with this failure mode — `worker-configuration.d.ts`, `openapi.json`, `routeTree.gen.ts`, and `command-reference.ts` all extract by symbol/content, not AST position; DB migration numbering already has dedicated collision tooling (`scripts/check-migrations.mjs`).

Closes #3675

Scope

• `scripts/gen-selfhost-env-reference.mjs` — drop line-number computation and embedding
• `apps/gittensory-ui/src/lib/selfhost-env-reference.ts` — regenerated (96 rows, all now file-only)
• `test/unit/selfhost-env-reference-script.test.ts` — updated fixtures + new regression test proving line-shift immunity
• `AGENTS.md`/`CLAUDE.md`, `.claude/skills/contributing-to-gittensory/{SKILL,reference}.md` — doc updates for the new trigger condition

Validation

• `npx vitest run test/unit/selfhost-env-reference-script.test.ts test/unit/selfhost-ai.test.ts` — 129/129 passing
• `npm run selfhost:env-reference:check` — passes on the regenerated output
• `npm run typecheck` — clean
• Directly verified the regression test's premise: same file, 10 unrelated lines inserted above an existing env read, `collectSelfHostEnvVars` output is byte-identical before/after
• No coverage obligation: `scripts/**` is Codecov-ignored per this repo's patch-coverage config; confirmed the one pre-existing branch-coverage gap in this file (the CLI `main()` entry point, never exercised by tests that only import the module) predates this change via a stash-diff comparison against `main`

Safety

• No secrets, wallet/hotkey/trust-score/reward terms introduced
• Purely additive precision loss in a generated doc's display (file instead of file:line) — no behavior change to any runtime code path

[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	a20e0be	Commit Preview URL Branch Preview URL	Jul 06 2026, 01:11 AM

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-06 01:16:09 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR drops the embedded `file:line` from the generated `selfhost-env-reference.ts` doc, keeping only the file path, to eliminate the well-documented rebase-churn problem (3 prior reactive regen commits + a CI-enforcement commit cited). The `scripts/gen-selfhost-env-reference.mjs` change correctly removes all line-tracking (`sourceFile.getLineAndCharacterOfPosition`, the `line` field) and simplifies `addRead` accordingly; the regenerated `selfhost-env-reference.ts` (96 rows) and updated test fixtures/assertions are consistent with the new file-only format. A new regression test explicitly exercises the fix's premise (adding 10 unrelated lines above a read leaves `firstReference` unchanged), and the three docs describing the old line-shift-triggers-regeneration behavior are updated to match. This is a narrow, well-scoped, correctly-traced fix with no algorithmic or wiring risk.

Nits — 3 non-blocking

• The renamed `addRead(name)` in scripts/gen-selfhost-env-reference.mjs no longer uses its second parameter anywhere, so the diff cleanly drops all `node`/`element` arguments at each call site — worth double-checking no other caller in the full file still expects the two-arg signature (none is visible here, but confirm).
• None beyond the nit above — the diff is coherent, the regenerated artifact matches the script's new output shape, and the new regression test directly targets the described bug.
• 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	#3675
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: 55 registered-repo PR(s), 46 merged, 464 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 55 PR(s), 464 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: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 55 PR(s), 464 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 93.29%. Comparing base (2783a25) to head (a20e0be).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3676   +/-   ##
=======================================
  Coverage   93.29%   93.29%           
=======================================
  Files         314      314           
  Lines       32058    32058           
  Branches    11749    11749           
=======================================
  Hits        29907    29907           
  Misses       1517     1517           
  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.