feat(config): add .gittensory.yml surface to enable/scope repo-doc generation

[JSONbored]

Summary

• Adds a repoDocGeneration: block to the .gittensory.yml manifest (src/signals/focus-manifest.ts, parsed via parseFocusManifest) with three fields: enabled (default false -- the feature is opt-in per repo), scope (default ["agents"] -- which generated file types are in play, forward-compatible with "skills" once feat(review): generate repo-specific Claude Code / Codex skill files #3001 lands), and allowOverwriteExisting (default false).
• Deliberately a manifest-only surface with no DB-backed counterpart -- there is no dashboard toggle for repo-doc generation today, so precedence collapses to "the manifest value, or the default when unset" rather than the full yml-over-DB-over-defaults three-way merge a dashboard-configurable field would need. Matches the issue's own scoped deliverable list (schema + resolver + docs, not a migration/OpenAPI/dashboard round-trip).
• Wires two gates into openRepoDocPullRequest (src/github/repo-doc-pr.ts):
  1. enabled/scope.includes("agents") are checked immediately after the installation check, before any profile extraction or GitHub call -- cheap, since the common case is disabled.
  2. When the diff-aware refresh (fix(review): make repo-doc refresh diff-aware and preserve manual edits #3004) reports manual-review-required (its "this file looks hand-maintained, no marker block" signal), allowOverwriteExisting decides whether that repo stays skipped (default) or gets a fresh wholesale generate discarding the old content (opt-in).
• Updates CONTRIBUTING.md's config-as-code reference and the root .gittensory.yml (plus its bundled fallback copy in src/config/gittensory-repo-focus-manifest.ts) with a commented-out worked example.

Part of #2993 (repo-doc generation roadmap). Closes #3002.

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 (not run -- no workflow files touched)
• npm run typecheck
• npm run test:coverage -- scoped to the two changed source files: 100% statements/branches/functions/lines on the new repoDocGeneration parsing (src/signals/focus-manifest.ts) and the new gating logic (src/github/repo-doc-pr.ts). Full unsharded test:coverage left to CI per this repo's own "don't duplicate CI locally" convention; ran npm run test:changed against origin/main instead, which pulled in 223 affected files (5676 tests) -- all green, including the bundled-YAML-alignment test this PR's .gittensory.yml edit required updating (test/unit/gittensory-focus-manifest.test.ts).
• npm run test:workers (not run -- no Cloudflare-Workers-pool-specific code touched)
• npm run build:mcp / npm run test:mcp-pack (not run -- no MCP package changes)
• npm run ui:openapi:check / npm run ui:lint / npm run ui:typecheck / npm run ui:build (not run -- no apps/gittensory-ui changes; this field has no OpenAPI/API surface since it's manifest-only, not a RepositorySettings field)
• npm audit --audit-level=moderate (not run locally -- no dependency changes; CI's dependency-review job covers this)
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Skipped checks above are for UI/MCP/Workers/API surfaces this PR does not touch. CI's validate job runs them as a backstop.

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. (The generated PR body's "Opting out" line now points at the real config key.)
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (Covered: disabled-by-default, explicitly-disabled, scope-excludes-agents, and the manual-review-required + allowOverwriteExisting interaction, both with and without the opt-in.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A -- no API/OpenAPI/MCP surface changed; this is deliberately manifest-only, see Summary.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A -- no UI changes.)
• Visible UI changes include a UI Evidence section below with screenshots. (N/A -- no visible UI changes.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (CONTRIBUTING.md updated; changelog untouched per convention.)

Notes

• Considered wiring this as a full RepositorySettings field instead (the gittensory-gate-setting-wiring template: migration + Drizzle + resolver + 4 OpenAPI schemas + api/routes.ts + UI openapi.json regen), matching how e.g. reviewCheckMode (feat(selfhost): configurable review-check publish mode (required/visible/disabled) #2852) was added. Chose the lighter manifest-only path because repo-doc generation has no dashboard/API surface today and the issue's own deliverables only ask for "yml schema addition with resolver wiring" -- adding an unused DB/OpenAPI round-trip for a field nothing reads from there would be scope creep.
• scope's empty-vs-omitted handling is deliberate: an omitted scope key falls back to the default ["agents"], but an explicit scope: [] is honored as "nothing in scope" rather than silently re-defaulted -- and a genuinely malformed (non-list) scope value falls back to the default rather than emptying it out, since that would otherwise silently disable an enabled: true config with no warning a maintainer would notice.

[superagent-security]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-04 18:42:31 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
The change adds a manifest-only repoDocGeneration surface, persists it through focus-manifest snapshots, and gates repo-doc PR creation on enabled/scope plus an explicit overwrite opt-in for hand-maintained AGENTS.md. The wiring is coherent with the stated no-DB-counterpart design, the default stays fail-closed, and the tests exercise the real openRepoDocPullRequest path rather than fabricated payloads. I do not see a reachable correctness blocker in the provided diff.

Nits — 5 non-blocking

• src/github/repo-doc-pr.ts:15 says enabled/scope are checked before any GitHub call, but loadRepoFocusManifest can fetch raw.githubusercontent.com on a cache miss; tighten the comment to say before GitHub App write/profile work, or change the loader call to a cache-only path if that was the intended contract.
• CONTRIBUTING.md:278 keeps the global precedence sentence as `.gittensory.yml gate > .gittensory.yml settings > dashboard repository settings > safe defaults`, which now reads incomplete for the new manifest-only repoDocGeneration block; add an explicit exception in that paragraph so future contributors do not add a DB/OpenAPI layer by assumption.
• src/github/repo-doc-pr.ts:125 should either move the mode check before loadRepoFocusManifest or update the surrounding comment to make clear dry-run/paused invocations may still read config; that keeps the no-side-effect boundary easy to audit.
• src/signals/focus-manifest.ts:959 has good parser coverage, but add a tiny assertion for `scope: ["bogus"]` resolving to an empty list if you want to lock the documented “all invalid entries means nothing in scope” behavior, not just mixed valid/invalid entries.
• 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	#3002
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: 60 registered-repo PR(s), 50 merged, 442 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 60 PR(s), 442 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: 60 PR(s), 442 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 94.72%. Comparing base (fa38886) to head (e5fef4a).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3169   +/-   ##
=======================================
  Coverage   94.71%   94.72%           
=======================================
  Files         269      269           
  Lines       29544    29571   +27     
  Branches    10773    10784   +11     
=======================================
+ Hits        27984    28011   +27     
  Misses        916      916           
  Partials      644      644           

Files with missing lines	Coverage Δ
src/config/gittensory-repo-focus-manifest.ts	100.00% <ø> (ø)
src/github/repo-doc-pr.ts	100.00% <100.00%> (ø)
src/signals/focus-manifest-loader.ts	99.09% <ø> (ø)
src/signals/focus-manifest.ts	98.55% <100.00%> (+0.03%)	⬆️

🚀 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.