docs(ui): point maintainer CTAs and GitHub App docs at self-hosting as the default path

apps/gittensory-ui/src/components/site/docs-nav.tsx

@@ -27,14 +27,6 @@ export const docsNav: DocsGroup[] = [
   {
     title: "Maintainers",
     subgroups: [
-      {
-        title: "Hosted app",
-        items: [
-          { to: "/docs/maintainer-workflow", label: "Maintainer workflow" },
-          { to: "/docs/github-app", label: "GitHub App" },
-          { to: "/docs/maintainer-install-trust", label: "Maintainer install & trust" },
-        ],
-      },
       {
         title: "Self-hosting: setup",
         items: [
@@ -68,6 +60,14 @@ export const docsNav: DocsGroup[] = [
           { to: "/docs/self-hosting-security", label: "Security" },
         ],
       },
+      {
+        title: "GitHub App & managed beta",
+        items: [
+          { to: "/docs/github-app", label: "GitHub App configuration" },
+          { to: "/docs/maintainer-workflow", label: "Maintainer workflow" },
+          { to: "/docs/maintainer-install-trust", label: "Maintainer install & trust" },
+        ],
+      },
     ],
   },
   {

apps/gittensory-ui/src/routes/docs.beta-onboarding.tsx

@@ -107,14 +107,17 @@ gittensory-mcp preflight --login your-login --json`}
 
       <h2>Maintainer journey</h2>
       <p>
-        Maintainers install the GitHub App, configure per-repo policy, preview what could appear on
-        a confirmed-miner PR, then pull context on demand.
+        Maintainers self-host the review stack and install a GitHub App, configure per-repo policy,
+        preview what could appear on a confirmed-miner PR, then pull context on demand.
       </p>
       <ol>
         <li>
-          <strong>Install the GitHub App.</strong> Choose repositories and approve permissions —
-          default posture is silence. Start with the{" "}
-          <Link to="/docs/github-app">GitHub App first-10-minutes checklist</Link>.
+          <strong>Self-host, then install your own App.</strong> Choose repositories and approve
+          permissions — default posture is silence. Start with{" "}
+          <Link to="/docs/maintainer-self-hosting">self-hosting setup</Link>, which covers the
+          direct App's install checklist, then{" "}
+          <Link to="/docs/github-app">GitHub App configuration</Link> for the review behavior (PR
+          panel, checks, gate modes).
         </li>
         <li>
           <strong>Configure settings.</strong> Opt in to at most one configured label and one sticky
@@ -241,7 +244,8 @@ GET /v1/readiness`}
           <Link to="/docs/miner-workflow">Miner workflow</Link>
         </li>
         <li>
-          Maintainers: <Link to="/docs/github-app">GitHub App</Link> →{" "}
+          Maintainers: <Link to="/docs/maintainer-self-hosting">Self-hosting</Link> →{" "}
+          <Link to="/docs/github-app">GitHub App</Link> →{" "}
           <Link to="/docs/maintainer-workflow">Maintainer workflow</Link>
         </li>
         <li>

apps/gittensory-ui/src/routes/docs.github-app.tsx

@@ -8,17 +8,17 @@ const GITHUB_APP_INSTALL_URL = "https://github.com/apps/gittensory/installations
 export const Route = createFileRoute("/docs/github-app")({
   head: () => ({
     meta: [
-      { title: "GitHub App setup — Gittensory docs" },
+      { title: "GitHub App configuration — Gittensory docs" },
       {
         name: "description",
         content:
-          "Install the Gittensory GitHub App so the gittensory app reviews your pull requests — the Gittensory Orb Review Agent check plus a review comment posted as gittensory[bot]. Choose repos, configure sticky PR panels, advisory checks, and optional review-agent enforcement.",
+          "How the Gittensory GitHub App reviews pull requests once installed — self-hosted (recommended) or via the private managed-beta shared app. The Gittensory Orb Review Agent check plus a review comment posted as gittensory[bot]. Choose repos, configure sticky PR panels, advisory checks, and optional review-agent enforcement.",
       },
-      { property: "og:title", content: "GitHub App setup — Gittensory docs" },
+      { property: "og:title", content: "GitHub App configuration — Gittensory docs" },
       {
         property: "og:description",
         content:
-          "Install the Gittensory GitHub App so the gittensory app reviews your pull requests — the Gittensory Orb Review Agent check plus a review comment posted as gittensory[bot]. Choose repos, configure sticky PR panels, advisory checks, and optional review-agent enforcement.",
+          "How the Gittensory GitHub App reviews pull requests once installed — self-hosted (recommended) or via the private managed-beta shared app. Choose repos, configure sticky PR panels, advisory checks, and optional review-agent enforcement.",
       },
       { property: "og:url", content: "/docs/github-app" },
     ],
@@ -31,21 +31,35 @@ function GithubApp() {
   return (
     <DocsPage
       eyebrow="Workflows"
-      title="GitHub App setup"
-      description="Install Gittensory on a repo so the gittensory app reviews your pull requests, then choose whether it should stay advisory or enforce repo-configured PR quality rules."
+      title="GitHub App configuration"
+      description="Install a Gittensory GitHub App on a repo so it reviews your pull requests, then choose whether it should stay advisory or enforce repo-configured PR quality rules."
     >
       <p>
-        Once installed, the <strong>gittensory app reviews every pull request</strong> on the repos
-        you select. Each review produces two surfaces: the{" "}
-        <strong>Gittensory Orb Review Agent</strong> check run (and the advisory{" "}
+        Once installed, a <strong>Gittensory GitHub App reviews every pull request</strong> on the
+        repos you select — whether that's your own self-hosted App (recommended; see{" "}
+        <Link to="/docs/maintainer-self-hosting">self-hosting setup</Link>) or, for private
+        managed-beta operators, the shared <code>gittensory</code> App below. Each review produces
+        two surfaces: the <strong>Gittensory Orb Review Agent</strong> check run (and the advisory{" "}
         <strong>Gittensory Context</strong> check), and a single review comment posted by{" "}
-        <code>gittensory[bot]</code> that updates in place as the PR evolves. Everything on this
-        page configures that review.
+        <code>gittensory[bot]</code> that updates in place as the PR evolves. The review behavior
+        below this page's Install section (PR panel, checks, gate modes, config-as-code) applies
+        identically whichever App you install — but the App's{" "}
+        <em>install steps and required permissions differ</em>, since a self-hosted App needs write
+        access the shared App does not.
       </p>
 
       <h2>Install</h2>
       <p>
-        The hosted deployment uses the GitHub App slug <code>gittensory</code>. Start from{" "}
+        <strong>Self-hosting is the recommended, default path.</strong> Run the review stack
+        yourself, then install your own GitHub App on exactly the repos you choose using the
+        self-host setup wizard. The direct App's required permissions and events are covered in{" "}
+        <Link to="/docs/self-hosting-github-app">GitHub App and Orb</Link> — use that page's
+        checklist, not the one below, for a self-hosted install.
+      </p>
+      <p>
+        The shared <code>gittensory</code> App is <strong>private / managed-beta only</strong> — it
+        is not open for general public install. If you've been invited into the managed beta, start
+        from{" "}
         <a href={GITHUB_APP_INSTALL_URL} target="_blank" rel="noreferrer">
           the GitHub App install flow
         </a>
@@ -66,6 +80,12 @@ function GithubApp() {
           <code>pull_request</code>, and <code>repository</code>.
         </li>
       </ol>
+      <Callout variant="note">
+        This checklist is for the shared managed-beta App only. A self-hosted App needs{" "}
+        <code>Pull requests: write</code> (not read) and <code>Checks: write</code> is mandatory,
+        not optional — see <Link to="/docs/self-hosting-github-app">GitHub App and Orb</Link> for
+        the direct App's exact permission and event list.
+      </Callout>
 
       <h2>First 10 minutes</h2>
       <ol>
@@ -332,11 +352,13 @@ GITTENSORY_REVIEW_REPOS="JSONbored/gittensory"`}
       </p>
       <p>
         If the install route changes, check the deployed <code>GITHUB_APP_SLUG</code> before
-        publishing setup copy. For the hosted app, the expected slug is <code>gittensory</code>.
+        publishing setup copy. Self-hosted deployments use whatever slug you chose during setup; for
+        the shared managed-beta app the expected slug is <code>gittensory</code>.
       </p>
 
       <p>
-        New maintainers should continue with{" "}
+        New maintainers should start with{" "}
+        <Link to="/docs/maintainer-self-hosting">self-hosting setup</Link>, then continue with{" "}
         <Link to="/docs/maintainer-workflow">Maintainer workflow</Link> or the{" "}
         <Link to="/docs/beta-onboarding">beta onboarding checklist</Link> after the health endpoint
         reports clean permissions and events.

apps/gittensory-ui/src/routes/docs.index.tsx

@@ -70,10 +70,10 @@ const AUDIENCES: Audience[] = [
     description: "Install, tune, or self-host the review system for your repos.",
     primary: { to: "/docs/beta-onboarding", label: "Beta onboarding" },
     links: [
+      { to: "/docs/maintainer-self-hosting", label: "Self-host reviews" },
       { to: "/docs/maintainer-install-trust", label: "Install & trust guide" },
-      { to: "/docs/github-app", label: "Install the GitHub App" },
+      { to: "/docs/github-app", label: "GitHub App configuration" },
       { to: "/docs/maintainer-workflow", label: "Maintainer workflow" },
-      { to: "/docs/maintainer-self-hosting", label: "Self-host reviews" },
       { to: "/docs/self-hosting-rees-analyzers", label: "REES analyzers" },
       { to: "/docs/upstream-drift", label: "Upstream drift" },
       { to: "/docs/ai-summaries", label: "AI summaries policy" },

apps/gittensory-ui/src/routes/docs.maintainer-install-trust.tsx

@@ -10,7 +10,7 @@ export const Route = createFileRoute("/docs/maintainer-install-trust")({
       {
         name: "description",
         content:
-          "Install Gittensory as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable.",
+          "Self-host and install a Gittensory GitHub App as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable. Self-hosting is the recommended default path; the shared App is private managed-beta only.",
       },
       {
         property: "og:title",
@@ -19,7 +19,7 @@ export const Route = createFileRoute("/docs/maintainer-install-trust")({
       {
         property: "og:description",
         content:
-          "Install Gittensory as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable.",
+          "Self-host and install a Gittensory GitHub App as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable. Self-hosting is the recommended default path; the shared App is private managed-beta only.",
       },
       { property: "og:url", content: "/docs/maintainer-install-trust" },
     ],
@@ -33,18 +33,26 @@ function MaintainerInstallTrust() {
     <DocsPage
       eyebrow="Launch guide"
       title="Maintainer install and trust guide"
-      description="A maintainer-first checklist for installing the GitHub App, keeping public output safe, authorizing commands, using the browser extension, and rejecting weak Gittensory-driven PRs."
+      description="A maintainer-first checklist for self-hosting and installing a GitHub App, keeping public output safe, authorizing commands, using the browser extension, and rejecting weak Gittensory-driven PRs."
     >
       <Callout variant="safety" title="Trust posture">
         Gittensory is advisory-first. It may help you review contribution readiness, but it does not
         replace human maintainer judgment, expose private scoreability signals, or make reward,
         payout, wallet, hotkey, or trust-score claims in public surfaces.
       </Callout>
 
-      <h2>Install the GitHub App</h2>
+      <h2>Install the App</h2>
       <p>
-        Start from <Link to="/docs/github-app">GitHub App setup</Link>, then keep the first rollout
-        narrow until the repo owner has verified permissions, webhook delivery, and public copy.
+        <strong>Self-hosting is the recommended, default path.</strong> Start from{" "}
+        <Link to="/docs/maintainer-self-hosting">self-hosting setup</Link> — the direct App's
+        required permissions and events are covered in{" "}
+        <Link to="/docs/self-hosting-github-app">GitHub App and Orb</Link>, not the checklist below.
+        Either way, keep the first rollout narrow until the repo owner has verified permissions,
+        webhook delivery, and public copy.
+      </p>
+      <p>
+        The checklist below is for the shared <strong>private / managed-beta only</strong> App — see{" "}
+        <Link to="/docs/github-app">GitHub App configuration</Link> for the install flow.
       </p>
       <ol>
         <li>Install Gittensory on one test repository or a selected repository set.</li>
@@ -62,6 +70,11 @@ function MaintainerInstallTrust() {
           preview output matches the repo's maintainer policy.
         </li>
       </ol>
+      <Callout variant="note">
+        A self-hosted direct App needs <code>Pull requests: write</code> (not read) and{" "}
+        <code>Checks: write</code> is mandatory, not optional — this checklist's permissions are
+        scoped to the shared managed-beta App only.
+      </Callout>
       <CodeBlock
         lang="http"
         code={`GET /v1/installations

apps/gittensory-ui/src/routes/docs.maintainer-workflow.tsx

@@ -114,7 +114,7 @@ GET /v1/repos/:owner/:repo/registration-readiness`}
       ),
       nextStep: {
         miner: { label: "PR packet format", to: "/docs/miner-workflow" },
-        maintainer: { label: "Install the GitHub App", to: "/docs/github-app" },
+        maintainer: { label: "Self-host reviews", to: "/docs/maintainer-self-hosting" },
       },
     },
   ];
@@ -131,15 +131,17 @@ GET /v1/repos/:owner/:repo/registration-readiness`}
         the contributor is doing privately via MCP at the same point.
       </p>
       <p>
-        New installations should start with <Link to="/docs/github-app">GitHub App setup</Link>:
-        install on one repo, verify installation health, preview the public panel, then decide
-        whether <strong>Gittensory Orb Review Agent</strong> should become a required check.
+        New installations should start with{" "}
+        <Link to="/docs/maintainer-self-hosting">self-hosting setup</Link>, then{" "}
+        <Link to="/docs/github-app">GitHub App configuration</Link>: install on one repo, verify
+        installation health, preview the public panel, then decide whether{" "}
+        <strong>Gittensory Orb Review Agent</strong> should become a required check.
       </p>
       <WorkflowMirror
         role="maintainer"
         steps={steps}
         minerCta={{ label: "See the contributor side", to: "/docs/miner-workflow" }}
-        maintainerCta={{ label: "Install the GitHub App", to: "/docs/github-app" }}
+        maintainerCta={{ label: "Self-host reviews", to: "/docs/maintainer-self-hosting" }}
       />
 
       <h2>On-demand commands</h2>

apps/gittensory-ui/src/routes/docs.miner-workflow.tsx

@@ -103,7 +103,7 @@ function MinerWorkflow() {
       ),
       nextStep: {
         miner: { label: "Set up your MCP client", to: "/docs/mcp-clients" },
-        maintainer: { label: "Install the GitHub App", to: "/docs/github-app" },
+        maintainer: { label: "Self-host reviews", to: "/docs/maintainer-self-hosting" },
       },
     },
   ];

apps/gittensory-ui/src/routes/index.tsx

@@ -14,9 +14,6 @@ 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: [
@@ -80,14 +77,12 @@ 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"
+            <Link
+              to="/docs/maintainer-self-hosting"
               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>
+              Self-host reviews →
+            </Link>
             <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"

apps/gittensory-ui/src/routes/maintainers.tsx

@@ -50,16 +50,16 @@ function MaintainersPage() {
             Quiet by default. Loud only when you ask.
           </h1>
           <p className="mt-4 text-token-lg text-muted-foreground">
-            Install Gittensory on a repo and your review surface stays calm. No always-on check
+            Self-host Gittensory on a repo and your review surface stays calm. No always-on check
             runs. No public scoring. You opt into confirmed-miner context, packets, and diagnostics
             with explicit commands.
           </p>
           <div className="mt-6 flex flex-wrap gap-3">
             <Link
-              to="/docs/github-app"
+              to="/docs/maintainer-self-hosting"
               className="inline-flex items-center gap-2 rounded-token bg-mint px-4 py-2 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 <ArrowRight className="size-4" />
+              Self-host reviews <ArrowRight className="size-4" />
             </Link>
             <Link
               to="/docs/maintainer-workflow"
@@ -230,10 +230,10 @@ GET /v1/repos/:owner/:repo/registration-readiness`}
               Open the preview <ArrowRight className="size-4" />
             </Link>
             <Link
-              to="/docs/github-app"
+              to="/docs/maintainer-self-hosting"
               className="inline-flex items-center gap-2 rounded-token border border-border bg-transparent px-4 py-2 text-token-sm hover:border-foreground/30"
             >
-              Install the GitHub App
+              Self-host reviews
             </Link>
           </div>
         </div>