docs(gittensory-ui): fix stale website docs and add a CI docs-drift check

apps/gittensory-ui/src/lib/selfhost-env-reference.ts

@@ -291,7 +291,7 @@ export const SELFHOST_ENV_REFERENCE_ROWS: SelfHostEnvReferenceRow[] = [
   },
   {
     name: "PGPOOL_MAX",
-    firstReference: "src/selfhost/queue-common.ts:710",
+    firstReference: "src/selfhost/queue-common.ts:713",
   },
   {
     name: "PGVECTOR_ENABLED",
@@ -327,11 +327,11 @@ export const SELFHOST_ENV_REFERENCE_ROWS: SelfHostEnvReferenceRow[] = [
   },
   {
     name: "QUEUE_DEAD_LETTER_AUTO_RETRY_MAX_EXTRA_ATTEMPTS",
-    firstReference: "src/selfhost/queue-common.ts:718",
+    firstReference: "src/selfhost/queue-common.ts:721",
   },
   {
     name: "QUEUE_STARTUP_JITTER_MIN_JOBS",
-    firstReference: "src/selfhost/queue-common.ts:699",
+    firstReference: "src/selfhost/queue-common.ts:702",
   },
   {
     name: "REDIS_URL",
@@ -457,7 +457,7 @@ export const SELFHOST_ENV_REFERENCE_MARKDOWN = [
   "| `OTEL_TRACES_EXPORTER` | `src/selfhost/otel.ts:40` |",
   "| `OTEL_TRACES_SAMPLER` | `src/selfhost/otel.ts:74` |",
   "| `OTEL_TRACES_SAMPLER_ARG` | `src/selfhost/otel.ts:76` |",
-  "| `PGPOOL_MAX` | `src/selfhost/queue-common.ts:710` |",
+  "| `PGPOOL_MAX` | `src/selfhost/queue-common.ts:713` |",
   "| `PGVECTOR_ENABLED` | `src/server.ts:229` |",
   "| `PORT` | `src/server.ts:715` |",
   "| `PUBLIC_API_ORIGIN` | `src/selfhost/preflight.ts:192` |",
@@ -466,8 +466,8 @@ export const SELFHOST_ENV_REFERENCE_MARKDOWN = [
   "| `QDRANT_URL` | `src/server.ts:527` |",
   "| `QUEUE_BACKGROUND_CONCURRENCY` | `src/selfhost/queue-common.ts:130` |",
   "| `QUEUE_CONCURRENCY` | `src/selfhost/pg-queue.ts:285` |",
-  "| `QUEUE_DEAD_LETTER_AUTO_RETRY_MAX_EXTRA_ATTEMPTS` | `src/selfhost/queue-common.ts:718` |",
-  "| `QUEUE_STARTUP_JITTER_MIN_JOBS` | `src/selfhost/queue-common.ts:699` |",
+  "| `QUEUE_DEAD_LETTER_AUTO_RETRY_MAX_EXTRA_ATTEMPTS` | `src/selfhost/queue-common.ts:721` |",
+  "| `QUEUE_STARTUP_JITTER_MIN_JOBS` | `src/selfhost/queue-common.ts:702` |",
   "| `REDIS_URL` | `src/selfhost/preflight.ts:144` |",
   "| `REVIEW_AUDIT_DIR` | `src/server.ts:572` |",
   "| `SELFHOST_BUNDLE_ALL` | `scripts/build-selfhost.mjs:13` |",

apps/gittensory-ui/src/routes/docs.ai-summaries.tsx

@@ -1,7 +1,7 @@
 import { createFileRoute } from "@tanstack/react-router";
 
 import { DocsPage } from "@/components/site/docs-page";
-import { Callout, CodeBlock } from "@/components/site/primitives";
+import { Callout } from "@/components/site/primitives";
 
 export const Route = createFileRoute("/docs/ai-summaries")({
   head: () => ({
@@ -43,39 +43,41 @@ function AiSummariesDoc() {
       <h2>Where they appear</h2>
       <ul>
         <li>
-          In the <code>/app/playground</code> tool runs, behind an opt-in toggle, above the JSON.
+          In the <code>/app/playground</code> tool runs, behind an opt-in "Include AI summary"
+          toggle, above the JSON.
         </li>
         <li>
-          Optionally inside the MCP CLI with <code>--summary</code>, printed above the structured
-          output.
-        </li>
-        <li>
-          Never in public GitHub comments. Never in maintainer packets without explicit maintainer
-          opt-in.
+          As an optional AI-clarified rewrite of the public PR intelligence comment, gated
+          server-side by <code>AI_PUBLIC_COMMENTS_ENABLED</code> and always falling back to the
+          deterministic comment body on any error, quota limit, or unsafe output.
         </li>
+        <li>Never in maintainer packets without explicit maintainer opt-in.</li>
       </ul>
+      <Callout variant="note">
+        The playground's toggle currently renders a local, deterministic preview of the structured
+        response — it does not call the backend AI summary service described below yet. Treat it as
+        a stand-in for what a wired-up summary would look like.
+      </Callout>
 
       <h2>What is sent to the model</h2>
-      <CodeBlock
-        lang="json"
-        code={`{
-  "tool":   "plan-next-work",
-  "response": { /* deterministic JSON shown to user */ },
-  "context": {
-    "boundary": "private-mcp",
-    "ruleset_snapshot": "rs_2026_05_29_a1f3"
-  }
-}`}
-      />
       <p>
-        Only the response Gittensory already showed you, plus the boundary and ruleset snapshot, are
-        sent. No source code, no PAT, no GitHub identity, no per-user history.
+        A compacted signal bundle — the run's objective, actor login, surface, status, and data
+        quality, plus up to five ranked actions (kind, recommendation, why, blockers) and up to
+        eight freshness warnings. For a public rewrite, scoreability/risk fields are stripped before
+        the bundle is built, not filtered out of the model's response after the fact.
+      </p>
+      <p>
+        No source code, no PAT, no GitHub identity beyond the acting login, and no per-user history
+        beyond the current run are sent.
       </p>
 
       <h2>Model choice</h2>
       <p>
-        You pick the provider per-session: GPT, Claude, or a local model. Defaults to off. The
-        selection lives in your browser only and is cleared on sign-out.
+        There is no per-user or per-session model picker. The self-hosted or hosted operator
+        configures one fixed Cloudflare Workers AI model (<code>WORKERS_AI_SUMMARY_MODEL</code>,
+        default a small Llama instruct model) for the whole instance. Summaries are off by default (
+        <code>AI_SUMMARIES_ENABLED</code>); public-comment rewriting is a separate,
+        also-off-by-default switch (<code>AI_PUBLIC_COMMENTS_ENABLED</code>).
       </p>
 
       <Callout variant="safety">

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

@@ -149,7 +149,8 @@ gittensory-mcp preflight --login your-login --json`}
 @gittensory blockers
 @gittensory duplicate-check
 @gittensory miner-context
-@gittensory next-action`}
+@gittensory next-action
+@gittensory reviewability`}
           />
         </li>
       </ol>
@@ -160,7 +161,7 @@ gittensory-mcp preflight --login your-login --json`}
 
       <h2>Repo owner journey</h2>
       <p>
-        Repo owners care about registration readiness and sensible <code>.gittensor.yml</code>{" "}
+        Repo owners care about registration readiness and sensible <code>.gittensory.yml</code>{" "}
         configuration before promoting labels or maintainer-cut policy.
       </p>
       <ol>

apps/gittensory-ui/src/routes/docs.branch-analysis.tsx

@@ -67,14 +67,27 @@ Authorization: Bearer ••••••••
 Content-Type: application/json
 
 {
-  "repo": { "owner": "entrius", "repo": "gittensor" },
-  "refs": { "base": "main", "head": "feat/scorer-cleanup" },
-  "files": [ { "path": "src/scorer.ts", "added": 42, "removed": 8 } ],
+  "login": "your-github-login",
+  "repoFullName": "entrius/gittensor",
+  "baseRef": "main",
+  "headRef": "feat/scorer-cleanup",
+  "changedFiles": [
+    { "path": "src/scorer.ts", "additions": 42, "deletions": 8, "status": "modified" }
+  ],
   "labels": ["scorer", "ready-for-review"],
-  "linked_issues": [421],
-  "commits": ["refactor scorer gating", "fix linked-issue projection"]
+  "linkedIssues": [421],
+  "commitMessages": ["refactor scorer gating", "fix linked-issue projection"],
+  "validation": [
+    { "command": "npm run typecheck", "status": "passed" }
+  ]
 }`}
       />
+      <p>
+        The request body is a strict schema — every field must match a known key exactly (
+        <code>repoFullName</code> not a nested repo object, <code>changedFiles</code> with{" "}
+        <code>additions</code>/<code>deletions</code>, <code>linkedIssues</code> not{" "}
+        <code>linked_issues</code>) and unknown keys are rejected rather than ignored.
+      </p>
 
       <Callout variant="safety">
         File <strong>metadata</strong> is allowed (path, line counts). File contents are not

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

@@ -169,9 +169,10 @@ GET /v1/installations/:id/repair`}
         <code>gateCheckMode</code> (<code>off</code> / <code>enabled</code>); each dimension then
         refines an already-enabled gate with a tri-state mode — <code>off</code> (not evaluated),{" "}
         <code>advisory</code> (surfaced, never blocks), or <code>block</code> (can become a hard{" "}
-        <strong>Gittensory Orb Review Agent</strong> blocker). Blocking is always
-        confirmed-contributor-gated: the mode chooses which deterministic checks are active, never{" "}
-        <em>who</em> can be blocked.
+        <strong>Gittensory Orb Review Agent</strong> blocker). A configured blocker fails the gate
+        for any author identically — confirmed-Gittensor-contributor status does not change{" "}
+        <em>who</em> can be blocked; it's carried through only for on-chain scoring, a separate
+        concern from the gate's own merge/close decision.
       </p>
       <ul>
         <li>
@@ -203,15 +204,37 @@ GET /v1/installations/:id/repair`}
         <li>
           <code>aiReviewMode</code> — AI review. Default <code>off</code>; <code>advisory</code>{" "}
           posts AI review notes only, <code>block</code> lets a dual-model high-confidence consensus
-          defect become a blocker (confirmed contributors only).
+          defect become a blocker.
+        </li>
+        <li>
+          <code>sizeGateMode</code> — PR-size hold. Default <code>off</code>; a PR at or above the
+          configured file/line thresholds is held for manual review rather than auto-merged, never a
+          hard failure.
+        </li>
+        <li>
+          <code>lockfileIntegrityGateMode</code> — lockfile-tamper-risk check (a resolved/integrity
+          change with no matching version bump, or a dependency pointed off the npm registry).
+          Default <code>off</code>.
+        </li>
+        <li>
+          <code>claGateMode</code> — CLA / license-compatibility gate. Default <code>off</code>.
+        </li>
+        <li>
+          <code>selfAuthoredLinkedIssueGateMode</code> — flags or blocks a PR whose author also
+          opened the linked issue. Default <code>advisory</code>.
+        </li>
+        <li>
+          <code>moderationGateMode</code> — whether the moderation-rules engine (contributor cap,
+          blacklist, review-nag feeding a shared cross-repo violation tally) runs on this repo.
+          Default <code>inherit</code> (defers to the instance-wide default); <code>off</code>/
+          <code>enabled</code> force it per repo.
         </li>
       </ul>
       <p>
         The policy pack (<code>gatePack</code>) selects which rule set runs: <code>gittensor</code>{" "}
-        (confirmed-contributor-gated, registry-aware) or <code>oss-anti-slop</code> (the
-        deterministic rules against any author on any repo). Enable{" "}
-        <code>firstTimeContributorGrace</code> to soften a would-be block to advisory for a genuine
-        newcomer.
+        (registry-aware, tracks confirmed-Gittensor-contributor status for scoring) or{" "}
+        <code>oss-anti-slop</code> (the deterministic rules against any author on any repo, with no
+        confirmed-contributor tracking at all).
       </p>
 
       <h2>
@@ -221,7 +244,7 @@ GET /v1/installations/:id/repair`}
         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,
+        <em>what</em> Gittensory does — a configured blocker gates every author identically,
         regardless of config.
       </p>
       <CodeBlock

apps/gittensory-ui/src/routes/docs.how-reviews-work.tsx

@@ -80,10 +80,10 @@ function HowReviewsWork() {
         </li>
       </ul>
       <p>
-        A <code>block</code> outcome is always <strong>confirmed-contributor-gated</strong>: the
-        mode chooses <em>which</em> checks are active, never <em>who</em> can be blocked. A genuine
-        newcomer can be softened from a block to an advisory when{" "}
-        <code>firstTimeContributorGrace</code> is on.
+        A <code>block</code> outcome fails the gate for any author identically — confirmed-
+        Gittensor-contributor status doesn't change <em>who</em> can be blocked, only the mode
+        chooses <em>which</em> checks are active. Confirmed status is carried through for on-chain
+        scoring, a separate concern from the gate's own merge/close decision.
       </p>
 
       <h3>The gate dimensions</h3>
@@ -119,11 +119,37 @@ function HowReviewsWork() {
           issue and test expectations) becomes enforceable. Manual-review path holds are controlled
           separately by <code>settings.hardGuardrailGlobs</code>.
         </li>
+        <li>
+          <strong>PR-size hold</strong> (<code>sizeGateMode</code>, default <code>off</code>) — a PR
+          at or above the configured file/line thresholds is held for manual review, never a hard
+          failure.
+        </li>
+        <li>
+          <strong>Lockfile-integrity gate</strong> (<code>lockfileIntegrityGateMode</code>, default{" "}
+          <code>off</code>) — flags a lockfile-tamper-risk finding (a resolved/integrity change with
+          no matching version bump, or a dependency pointed off the npm registry).
+        </li>
+        <li>
+          <strong>CLA / license gate</strong> (<code>claGateMode</code>, default <code>off</code>) —
+          CLA / license-compatibility check.
+        </li>
+        <li>
+          <strong>Self-authored-linked-issue gate</strong> (
+          <code>selfAuthoredLinkedIssueGateMode</code>, default <code>advisory</code>) — flags or
+          blocks a PR whose author also opened the linked issue.
+        </li>
+        <li>
+          <strong>Moderation-rules engine</strong> (<code>moderationGateMode</code>, default{" "}
+          <code>inherit</code>) — whether the contributor-cap / blacklist / review-nag mechanisms
+          feed a shared, cross-repo violation tally on this repo; <code>inherit</code> defers to the
+          instance-wide default, <code>off</code>/<code>enabled</code> force it per repo.
+        </li>
       </ul>
       <p>
         Which deterministic rules even apply is set by the <strong>policy pack</strong> (
-        <code>gatePack</code>): <code>gittensor</code> (confirmed-contributor-gated, registry-aware)
-        or <code>oss-anti-slop</code> (runs the rules against any author on any repo).
+        <code>gatePack</code>): <code>gittensor</code> (registry-aware, tracks confirmed-Gittensor-
+        contributor status for scoring) or <code>oss-anti-slop</code> (runs the rules against any
+        author on any repo, with no confirmed-contributor tracking at all).
       </p>
       <CodeBlock
         filename=".gittensory.yml"
@@ -139,8 +165,7 @@ function HowReviewsWork() {
     mode: block
     minScore: 60
   mergeReadiness: advisory
-  manifestPolicy: block
-  firstTimeContributorGrace: true`}
+  manifestPolicy: block`}
       />
 
       <h2>2. The dual-AI review and consensus</h2>
@@ -155,15 +180,17 @@ function HowReviewsWork() {
         </li>
         <li>
           <code>block</code> — a <strong>dual-model high-confidence consensus</strong> defect is
-          allowed to become a blocker (confirmed contributors only).
+          allowed to become a blocker.
         </li>
       </ul>
       <p>
-        The blocking decision always runs on a <strong>pair</strong> of free models and only blocks
-        when <em>both</em> models independently agree, with high confidence, on a real defect. Two
-        agreeing models is the bar — there is no single-model block and no tie-breaker third model.
-        That consensus requirement is what keeps a confident-but-wrong single model from blocking a
-        good PR.
+        By default, the blocking decision runs on a <strong>pair</strong> of free models and only
+        blocks when <em>both</em> models independently agree, with high confidence, on a real defect
+        — no single-model block and no tie-breaker third model, so a confident-but-wrong single
+        model can't block a good PR on its own. An operator can override this per repo (
+        <code>aiReviewCombine</code>: <code>single</code> / <code>consensus</code> /{" "}
+        <code>synthesis</code>); in <code>single</code> mode, one reviewer's verdict is the
+        decision.
       </p>
 
       <h3>Bring your own model (advisory only)</h3>

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

@@ -128,15 +128,18 @@ POST /v1/repos/:owner/:repo/settings-preview`}
           {
             title: "Command access",
             description:
-              "PR-thread commands are maintainer-authorized. Untrusted contributors should not be able to trigger private maintainer packets.",
+              "PR-thread commands default to maintainers, collaborators, and confirmed miners. Untrusted contributors should not be able to trigger private maintainer packets.",
           },
         ]}
       />
 
       <h2>Command authorization</h2>
       <p>
-        Maintainer commands should be treated like privileged review actions. Use them to fetch
-        context on demand, not to create always-on public scoring.
+        Commands should be treated like privileged review actions. Use them to fetch context on
+        demand, not to create always-on public scoring. The default authorized roles are{" "}
+        <strong>maintainer</strong>, <strong>collaborator</strong>, and{" "}
+        <strong>confirmed miner</strong> — a repo can narrow (or further restrict) this per command
+        via <code>commandAuthorization</code> in its settings.
       </p>
       <CodeBlock code={PUBLIC_COMMAND_LIST} />
       <p>

apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx

@@ -82,6 +82,12 @@ const SECTION_LINKS = [
     description: "Official images, tags, source maps, upgrade cadence, and local custom builds.",
     to: "/docs/self-hosting-releases",
   },
+  {
+    title: "Beta release checklist",
+    description:
+      "The smoke matrix to run against a candidate image before tagging an orb-vX.Y.Z release.",
+    to: "/docs/self-hosting-release-checklist",
+  },
   {
     title: "Security",
     description:
@@ -167,6 +173,10 @@ function MaintainerSelfHosting() {
           <Link to="/docs/self-hosting-security">Security</Link> before exposing the service to
           production traffic.
         </li>
+        <li>
+          Run the <Link to="/docs/self-hosting-release-checklist">beta release checklist</Link>{" "}
+          before tagging or promoting a candidate image.
+        </li>
       </ol>
 
       <h2>Pages</h2>

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

@@ -147,8 +147,10 @@ GET /v1/repos/:owner/:repo/registration-readiness`}
 
       <h2>On-demand commands</h2>
       <p>
-        Maintainers (and only maintainers) can trigger context with a comment. Output is scoped to
-        maintainer-visible packets when appropriate.
+        By default, the public commands below are authorized for maintainers, collaborators, and
+        confirmed miners (not the general public) — output stays scoped to maintainer-visible
+        packets when appropriate. A repo can narrow this per command via{" "}
+        <code>commandAuthorization</code> in its settings.
       </p>
       <CodeBlock code={PUBLIC_COMMAND_LIST} />
       <p>