feat(review): generate AGENTS.md/CLAUDE.md from repo profile, deliver as a PR

[JSONbored]

Summary

• Adds renderRepoDocContent(profile) (src/review/repo-doc-render.ts), a pure template that turns a RepoProfile (feat(review): extract a codebase-grounded repo profile from RAG + signals #2999) into the markdown body of a generated AGENTS.md: architecture, naming/test conventions, build/test/lint commands, and contribution-workflow facts. Returns null for an absent profile -- never a placeholder document.
• Adds openRepoDocPullRequest(env, repoFullName, mode) (src/github/repo-doc-pr.ts), which renders the content and opens (or finds the already-open) pull request carrying AGENTS.md + CLAUDE.md, reusing the SAME installation-token write chokepoint (makeInstallationOctokit) every other GitHub write in this engine goes through -- never a direct commit to the target repo's default branch.
• CLAUDE.md is delivered as a real git symlink (mode 120000) pointing at AGENTS.md when the target tree accepts one, falling back to a byte-identical regular-file copy when it doesn't -- matching this repo's own convention (verified directly: CLAUDE.md here really is a symlink to AGENTS.md, not the singular "AGENT.md" the parent issue's prose loosely uses).
• Both files are written as ONE commit (base_tree + explicit per-path tree entries), so a first-run repo (no existing file) and a refresh (file already present) are handled identically at the delivery layer -- no separate "does it exist yet" probe.
• A non-"live" action mode short-circuits before any GitHub write, rather than chaining four dependent writes through synthetic dry-run responses (mirrors the same guard maybeEscalateModeration uses in agent-action-executor.ts).

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

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 files: 100% statements/branches/functions/lines on both src/review/repo-doc-render.ts and 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 the affected suites directly instead (test/unit/repo-doc-render.test.ts, test/unit/repo-doc-pr.test.ts, plus test/unit/repo-profile.test.ts and test/unit/no-direct-octokit.test.ts as regression checks -- 79/79 passing).
• 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, no API/OpenAPI surface changed)
• 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 surfaces this PR does not touch (two new backend modules). 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 and file content describe only repo-derived facts -- architecture, conventions, commands, workflow -- with no scoring/reward language.)
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (This PR adds a new GitHub-write path; it is covered by dry-run/paused-mode tests, a symlink-rejected fallback test, an already-open-PR short-circuit test, and both an Error and a non-Error thrown-value test for the outer catch.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A -- no API/OpenAPI/MCP surface changed; this capability is not yet wired to any endpoint or scheduler -- that's feat(config): add .gittensory.yml surface to enable/scope repo-doc generation #3002/feat(selfhost): scheduled + on-demand refresh for repo-doc generation #3003.)
• 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. (N/A.)

Notes

• This module is not yet invoked by anything (no queue processor, no route, no scheduler) -- it is the generation+delivery primitive the roadmap's remaining issues wire up: feat(config): add .gittensory.yml surface to enable/scope repo-doc generation #3002 adds the .gittensory.yml surface to enable/scope it per repo, feat(selfhost): scheduled + on-demand refresh for repo-doc generation #3003 adds scheduled/on-demand triggering, and fix(review): make repo-doc refresh diff-aware and preserve manual edits #3004 makes a repeat run diff-aware instead of just re-writing both files onto the same stable branch.
• The stable branch name (gittensory/repo-docs) and the "reuse the already-open PR" check are deliberate: fix(review): make repo-doc refresh diff-aware and preserve manual edits #3004 is expected to push new commits onto this same branch rather than opening a second PR, so this PR does the minimum needed to make that safe (one branch, one PR, add-or-replace tree entries) without implementing the diffing itself.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.11%. Comparing base (feee775) to head (b9db6ef).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3052   +/-   ##
=======================================
  Coverage   96.10%   96.11%           
=======================================
  Files         261      263    +2     
  Lines       28888    28953   +65     
  Branches    10516    10533   +17     
=======================================
+ Hits        27762    27827   +65     
  Misses        492      492           
  Partials      634      634           

Files with missing lines	Coverage Δ
src/github/repo-doc-pr.ts	100.00% <100.00%> (ø)
src/review/repo-doc-render.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 10:24:16 UTC}

4 files · 1 AI reviewer · 1 blocker · readiness 82/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• AI reviewers agree on a likely critical defect: src/github/repo-doc-pr.ts:114 will fail to open a new repo-doc PR whenever refs/heads/gittensory/repo-docs already exists but has no open PR, because line 100 only searches open PRs and line 114 always POSTs a new ref instead of reading/updating the existing branch
• change this path to GET/PATCH the branch ref when it exists, or delete/recreate only with an explicit reason. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This adds a pure repo-profile-to-AGENTS.md renderer and a GitHub delivery path that opens a generated-doc PR through the installation-token client, with reasonable coverage for absent profiles, dry-run mode, existing open PR reuse, symlink fallback, and rendering variants. The renderer is straightforward and fail-closed, but the PR delivery is not idempotent once the stable branch exists without an open PR, which is a reachable lifecycle state after a maintainer closes a previous generated-doc PR.

Blockers

• src/github/repo-doc-pr.ts:114 will fail to open a new repo-doc PR whenever refs/heads/gittensory/repo-docs already exists but has no open PR, because line 100 only searches open PRs and line 114 always POSTs a new ref instead of reading/updating the existing branch; change this path to GET/PATCH the branch ref when it exists, or delete/recreate only with an explicit reason.

Nits — 6 non-blocking

• nit: src/github/repo-doc-pr.ts:46 catches every tree-creation error and retries as a regular copy, so transient/auth/rate-limit failures on the symlink attempt are misclassified as symlink incompatibility; restrict the fallback to the expected GitHub validation status and rethrow everything else.
• nit: src/github/repo-doc-pr.ts:103 reports claudeMode: "symlink" for a reused PR even though the already-open branch may contain the copy fallback, so either omit that field for reused results or inspect the existing tree before claiming the mode.
• nit: test/unit/repo-doc-pr.test.ts:221 fabricates a bare repo name and asserts a malformed /repos//widgets request, which documents an invalid state instead of protecting the real owner/repo path; replace it with validation of the DB invariant or remove the test.
• In src/github/repo-doc-pr.ts, after no open PR is found, try GET /repos/{owner}/{repo}/git/ref/heads/{branch} and PATCH it to the new commit when present, falling back to POST /git/refs only on 404.
• In src/github/repo-doc-pr.ts, gate the symlink-to-copy retry on the GitHub error status that actually means the tree entry was rejected, then let transient failures bubble to the outer fail-safe catch.
• 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.

Concerns raised — review before merging

• src/github/repo-doc-pr.ts:114 will fail to open a new repo-doc PR whenever refs/heads/gittensory/repo-docs already exists but has no open PR, because line 100 only searches open PRs and line 114 always POSTs a new ref instead of reading/updating the existing branch; change this path to GET/PATCH the branch ref when it exists, or delete/recreate only with an explicit reason.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#3000
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High 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), 51 merged, 421 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 60 PR(s), 421 issue(s).
Gate result	❌ Blocking	Repo-configured hard 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), 421 issue(s).
• Related work: Titles/paths share 7 meaningful terms. (issue #2995, issue #2568)

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Review top overlaps.
• Add a concise scope and risk note.
• No action.
• Check active issues and PRs before submitting.

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