docs(selfhost): accurate onboarding paths and simplification proposal

[andriypolanski]

Summary

• Bring self-host docs in line with the current setup: INSTALL_AI_CLIS, GITTENSORY_REVIEW_REPOS, container-private .gittensory.yml, Checks:write + re-approval, repo gate activation (POST /v1/repos/{owner}/{repo}/activation), is_registered vs feature allowlist, and the periodic re-gate sweep (agent-regate-sweep / backlog-convergence).
• Add a verified first-repo onboarding path to Quickstart (env allowlist → private global default → advisory activation → go live).
• Document an onboarding-simplification proposal (single-command onboarding, advisory-by-default auto-activate, clearer control-panel vocabulary) without requiring code changes to adopt today's path.
• Add a drift-guard unit test so activation-path docs cannot silently regress.

Closes #1574

Scope

• Docs-only change under apps/gittensory-ui/src/routes/docs.self-hosting-* and docs.maintainer-self-hosting.tsx
• Unit test in test/unit/docs-selfhost-activation-paths.test.ts
• No src/** production code changes (Codecov patch N/A)
• No generated artifacts (OpenAPI, cf-typegen, env reference) invalidated

Changed files

File	Change
apps/gittensory-ui/src/routes/docs.self-hosting-quickstart.tsx	New step 6: three activation layers, private config seed, activation curl, Checks:write callout
apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx	New "Repo activation — three layers" section + activation-preview/POST routes
apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx	Re-gate sweep + backlog-convergence operations section
apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx	Precise RAG activation checklist
apps/gittensory-ui/src/routes/docs.self-hosting-rag.tsx	Clarify allowlist vs is_registered
apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx	Onboarding simplification proposal (#1574 deliverable)
test/unit/docs-selfhost-activation-paths.test.ts	Drift guard for key onboarding strings

Validation

git diff --check
npx vitest run test/unit/docs-selfhost-activation-paths.test.ts
npm run docs:drift-check
npm --workspace @jsonbored/gittensory-ui run lint
npm --workspace @jsonbored/gittensory-ui run typecheck
npm run test:ci
npm audit --audit-level=moderate

Safety

• No secrets, tokens, or private scoring terms added
• No auth/CORS behavior changes
• Docs-only — no contributor-facing runtime change

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 22:45:56 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This is a docs-only PR that expands self-host onboarding documentation (activation layers, re-gate sweep, RAG activation checklist) and adds a single drift-guard unit test asserting the presence of key terms across five doc route files. The changes are consistent with the stated scope (no src/** production code touched), and the new prose is internally coherent — the three-layer activation model (env allowlist, gate activation, is_registered) is explained consistently across quickstart/configuration/rag/troubleshooting. The one notable wrinkle is that the added test also asserts on docs.self-hosting-github-app.tsx, a file not modified by this diff, coupling an unrelated page's exact wording into this PR's test.

Nits — 5 non-blocking

• test/unit/docs-selfhost-activation-paths.test.ts asserts `githubApp.toContain("Re-approving a permission bump")` against docs.self-hosting-github-app.tsx, a file this diff never touches — if that page's copy changes later for unrelated reasons, this activation-paths test breaks even though nothing about activation changed; that assertion would fit better as a test on the github-app page itself.
• The 'three activation layers' explanation (env allowlist vs gate activation vs is_registered) is restated nearly verbatim in docs.self-hosting-quickstart.tsx, docs.self-hosting-configuration.tsx, and docs.self-hosting-rag.tsx — consider having quickstart/rag link to the canonical Configuration section instead of duplicating the full FeatureRow text, since duplicated docs are exactly the kind of drift this PR's own guard test is trying to prevent.
• The drift-guard test only checks literal substring presence (e.g. `toContain("agent-regate-sweep")`), so it would still pass if the surrounding explanation became inaccurate while the literal token remains — it guards against renames/removals but not against factual drift in the prose itself.
• The activation curl example in docs.self-hosting-quickstart.tsx hardcodes `-d '{}'` and a bearer-token auth header; worth double-checking against the actual `/v1/repos/:owner/:repo/activation` handler (not in this diff) that an empty body is in fact accepted and defaults to advisory mode as documented.
• Move the github-app-specific assertion out of docs-selfhost-activation-paths.test.ts and into a dedicated (or existing) test for docs.self-hosting-github-app.tsx so the two concerns don't fail each other's suites.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1574
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	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 117 registered-repo PR(s), 73 merged, 5 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 117 PR(s), 5 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, JavaScript, Python, Rust, Cuda, Kotlin, MDX, Scala
• Official Gittensor activity: 117 PR(s), 5 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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.13%. Comparing base (39431cc) to head (132f33c).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3649   +/-   ##
=======================================
  Coverage   93.13%   93.13%           
=======================================
  Files         314      314           
  Lines       32005    32005           
  Branches    11725    11725           
=======================================
  Hits        29807    29807           
  Misses       1552     1552           
  Partials      646      646           

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