From 181050de4a1993d50484e114c58eec6a27bf1337 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Sat, 13 Jun 2026 04:39:40 -0700
Subject: [PATCH] =?UTF-8?q?feat(ui):=20maintainer=20onboarding=20=E2=80=94?=
 =?UTF-8?q?=20hero=20install=20button=20+=20config-as-code=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Homepage hero: add a prominent "Install the GitHub App →" CTA (one-click maintainer
  onboarding to github.com/apps/gittensory/installations/new), beside the Install MCP path.
- GitHub App docs page: document `.gittensory.yml` config-as-code — the settings / gate /
  review blocks, precedence (.gittensory.yml > dashboard settings > defaults), and the
  public-safe footer guarantee (custom footer text, Gittensor register link always kept).
- Add a worked, commented `review:` example to the repo's own `.gittensory.yml` (+ the bundled
  mirror, kept byte-identical) showing footer text, intro note, and per-row field toggles.

UI typecheck + lint clean; backend typecheck + manifest/alignment tests pass.
Note: visible UI change — hero/docs screenshots should be attached to the PR before merge.
---
 .gittensory.yml                               | 10 +++++
 .../src/routes/docs.github-app.tsx            | 38 +++++++++++++++++++
 apps/gittensory-ui/src/routes/index.tsx       | 11 ++++++
 src/config/gittensory-repo-focus-manifest.ts  | 10 +++++
 4 files changed, 69 insertions(+)

diff --git a/.gittensory.yml b/.gittensory.yml
index 87a4992086..5ad1a3dd5d 100644
--- a/.gittensory.yml
+++ b/.gittensory.yml
@@ -43,6 +43,16 @@ gate:
     mode: advisory             # block | advisory | off — readiness-score floor
     minScore: 60
 
+# Public review-panel content overrides (config-as-code). Maintainer text is dropped if it fails the
+# public-safe filter; the Gittensor attribution + register link always stay appended to the footer.
+# review:
+#   footer:
+#     text: "Reviewed by the Acme maintainer bot."     # custom lead line (attribution still appended)
+#   note: "Run the test suite before requesting review."   # short intro line shown above the panel
+#   fields:                                             # show/hide rows (default: all shown). Keys:
+#     relatedWork: false                                # linkedIssue | relatedWork | reviewLoad |
+#     openPrQueue: false                                # validationEvidence | openPrQueue | contributorContext | gateResult
+
 publicNotes:
   - Prefer backend Workers, MCP, GitHub App, registry, and scoring work when scope allows.
   - Focused control-panel UI changes are welcome when they use live API data or honest empty/error states and tie to safety, release readiness, or operator-facing analytics.
diff --git a/apps/gittensory-ui/src/routes/docs.github-app.tsx b/apps/gittensory-ui/src/routes/docs.github-app.tsx
index ecb471d09c..8a53450156 100644
--- a/apps/gittensory-ui/src/routes/docs.github-app.tsx
+++ b/apps/gittensory-ui/src/routes/docs.github-app.tsx
@@ -124,6 +124,44 @@ GET /v1/installations/:id/repair`}
         <code>qualityGateMinScore</code> threshold is configured.
       </p>
 
+      <h2>
+        Configure as code (<code>.gittensory.yml</code>)
+      </h2>
+      <p>
+        Every setting can be committed to <code>.gittensory.yml</code> at the repo root instead of,
+        or layered over, the dashboard. Precedence is <code>.gittensory.yml</code> &gt; repository
+        settings &gt; safe defaults; an unset field falls back to the next layer. It only chooses{" "}
+        <em>what</em> Gittensory does — only confirmed Gittensor contributors are ever hard-blocked,
+        regardless of config.
+      </p>
+      <CodeBlock
+        lang="yaml"
+        code={`# Repository settings as code — any dashboard toggle:
+settings:
+  gateCheckMode: enabled        # the Gate on/off
+  checkRunMode: enabled         # the advisory Context check on/off
+  commentMode: detected_contributors_only
+  publicSurface: comment_only
+
+# Friendly gate alias (wins over settings: for gate fields):
+gate:
+  enabled: true                 # Gate on/off
+  linkedIssue: advisory         # block | advisory | off
+  duplicates: block
+  readiness: { mode: advisory, minScore: 60 }
+
+# Public review-panel content:
+review:
+  footer: { text: "Reviewed by our bot." }   # custom lead — the Gittensor register link is always appended
+  note: "Run npm test before requesting review."
+  fields: { relatedWork: false }              # show/hide individual panel rows`}
+      />
+      <p>
+        Maintainer-supplied footer and note text is dropped if it contains forbidden public language
+        (reward, score, wallet, hotkey, payout, etc.); the Gittensor attribution and register link
+        always remain on the footer.
+      </p>
+
       <h2>Dogfood mode</h2>
       <p>
         For repos like <code>JSONbored/gittensory</code> and <code>awesome-claude</code>, enable PR
diff --git a/apps/gittensory-ui/src/routes/index.tsx b/apps/gittensory-ui/src/routes/index.tsx
index 500c4e12b8..eabe89be18 100644
--- a/apps/gittensory-ui/src/routes/index.tsx
+++ b/apps/gittensory-ui/src/routes/index.tsx
@@ -13,6 +13,9 @@ import { TrustStrip } from "@/components/site/trust-strip";
 import { describeApiStatus, pingHealth, useApiStatus } from "@/lib/api/status";
 import { MCP_PACKAGE_NAME, getLatestMcpVersion, useMcpPackageMetadata } from "@/lib/mcp-package";
 
+/** Canonical GitHub App install URL (app slug `gittensory`) — dead-simple one-click maintainer onboarding. */
+const GITHUB_APP_INSTALL_URL = "https://github.com/apps/gittensory/installations/new";
+
 export const Route = createFileRoute("/")({
   head: () => ({
     meta: [
@@ -75,6 +78,14 @@ function Hero() {
             Plan better work, preflight branches, and keep maintainer review surfaces quiet.
           </p>
           <div className="mt-7 flex flex-wrap items-center gap-2">
+            <a
+              href={GITHUB_APP_INSTALL_URL}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex h-9 items-center justify-center gap-1.5 whitespace-nowrap rounded-token bg-coral px-4 text-token-sm font-medium text-primary-foreground transition-[filter,transform] duration-150 hover:brightness-110 active:scale-[0.98] focus-ring motion-reduce:transition-none motion-reduce:active:scale-100"
+            >
+              Install the GitHub App →
+            </a>
             <Link
               to="/docs/quickstart"
               className="inline-flex h-9 items-center justify-center gap-1.5 whitespace-nowrap rounded-token bg-coral px-4 text-token-sm font-medium text-primary-foreground transition-[filter,transform] duration-150 hover:brightness-110 active:scale-[0.98] focus-ring motion-reduce:transition-none motion-reduce:active:scale-100"
diff --git a/src/config/gittensory-repo-focus-manifest.ts b/src/config/gittensory-repo-focus-manifest.ts
index f6beb1699e..9e0a05562c 100644
--- a/src/config/gittensory-repo-focus-manifest.ts
+++ b/src/config/gittensory-repo-focus-manifest.ts
@@ -47,6 +47,16 @@ gate:
     mode: advisory             # block | advisory | off — readiness-score floor
     minScore: 60
 
+# Public review-panel content overrides (config-as-code). Maintainer text is dropped if it fails the
+# public-safe filter; the Gittensor attribution + register link always stay appended to the footer.
+# review:
+#   footer:
+#     text: "Reviewed by the Acme maintainer bot."     # custom lead line (attribution still appended)
+#   note: "Run the test suite before requesting review."   # short intro line shown above the panel
+#   fields:                                             # show/hide rows (default: all shown). Keys:
+#     relatedWork: false                                # linkedIssue | relatedWork | reviewLoad |
+#     openPrQueue: false                                # validationEvidence | openPrQueue | contributorContext | gateResult
+
 publicNotes:
   - Prefer backend Workers, MCP, GitHub App, registry, and scoring work when scope allows.
   - Focused control-panel UI changes are welcome when they use live API data or honest empty/error states and tie to safety, release readiness, or operator-facing analytics.