docs(config): add self-host review config templates in config/examples

.gittensory.minimal.yml

@@ -4,7 +4,9 @@
 #
 # Copy this file to your repo root as `.gittensory.yml` and customize from here.
 # (This filename is not read directly — only `.gittensory.yml` / `.github/gittensory.yml` are.)
-# For every supported field, defaults, and examples see `.gittensory.yml.example`.
+# Also shipped at config/examples/gittensory.minimal.yml for self-host operators.
+# For every supported field, defaults, and examples see `.gittensory.yml.example` or
+# config/examples/gittensory.full.yml.
 #
 # Safe by default:
 #   - Gate off (enable explicitly when you are ready)

.gittensory.yml.example

@@ -6,9 +6,11 @@
 # review engine scores, gates, and comments on its pull requests — as
 # config-as-code, versioned alongside the project it governs.
 #
-# STARTER TEMPLATES:
-#   .gittensory.minimal.yml  — smallest safe copy-paste starter (gate off, observe-only autonomy)
-#   .gittensory.yml.example  — exhaustive, field-by-field reference (this file's expanded form)
+# STARTER TEMPLATES (also shipped under config/examples/ for self-host operators):
+#   config/examples/gittensory.minimal.yml — smallest safe starter (gate off, observe-only autonomy)
+#   config/examples/gittensory.full.yml    — exhaustive reference (body synced with this file)
+#   .gittensory.minimal.yml                — same minimal starter at repo root
+#   .gittensory.yml.example                — this file
 #
 # WHERE IT LIVES (first match wins):
 #   .gittensory.yml  →  .github/gittensory.yml  →  .gittensory.json  →  .github/gittensory.json

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

@@ -91,13 +91,81 @@ function SelfHostingConfiguration() {
       <p>
         This page covers the environment layer and the shape of the config file. For the full field
         list — every <code>gate:</code> and <code>settings:</code> key, its default, and what it
-        does — see <Link to="/docs/tuning">Tuning your reviews</Link>, and for a complete,
-        commented, copy-pasteable manifest see{" "}
-        <a href="https://github.com/JSONbored/gittensory/blob/main/.gittensory.yml.example">
-          <code>.gittensory.yml.example</code>
-        </a>{" "}
-        in the repo — the authoritative reference for every field, including several documented only
-        in its comments (see below).
+        does — see <Link to="/docs/tuning">Tuning your reviews</Link>, and for copy-paste templates
+        see the table below (also shipped inside the self-host image at{" "}
+        <code>config/examples/</code>).
+      </p>
+
+      <h2>Config templates</h2>
+      <p>
+        Start from a template instead of reverse-engineering env flags, private-config precedence,
+        and the parser. Every template uses the same schema for a public repo-root{" "}
+        <code>.gittensory.yml</code> or a container-private <code>GITTENSORY_REPO_CONFIG_DIR</code>{" "}
+        mount — only what you put in each file differs.
+      </p>
+      <FeatureRow
+        items={[
+          {
+            title: "gittensory.minimal.yml",
+            description:
+              "Smallest safe starter — gate off, observe-only autonomy, no accidental merge/close/label writes. Copy to the repo root or a private mount.",
+          },
+          {
+            title: "gittensory.full.yml",
+            description:
+              "Exhaustive commented reference — every gate:, settings:, review:, and features: field with defaults and allowed values. Body kept in sync with .gittensory.yml.example.",
+          },
+          {
+            title: "global.gittensory.yml + repo-override.gittensory.yml",
+            description:
+              "Private self-host only — illustrative fleet global default and per-repo overlay (deep-merge). Never commit real policy into these example paths.",
+          },
+        ]}
+      />
+      <CodeBlock
+        lang="bash"
+        code={`# Public repo (contributor-visible)
+cp config/examples/gittensory.minimal.yml .gittensory.yml
+
+# Self-host private mount (operator-only policy)
+mkdir -p gittensory-config
+cp config/examples/global.gittensory.yml gittensory-config/.gittensory.yml`}
+      />
+      <Callout variant="note">
+        Keep anti-abuse thresholds, maintainer allowlists, and autonomy dials in the{" "}
+        <strong>private</strong> mount — not in a public <code>.gittensory.yml</code> contributors
+        can read. <code>config/examples/TEMPLATES.md</code> documents the public-vs-private split
+        and how to apply the templates to <code>gittensory</code>, <code>awesome-claude</code>, and{" "}
+        <code>metagraphed</code> without committing private policy. Lint before deploy:{" "}
+        <code>npx tsx scripts/gittensory-config-lint.ts path/to/.gittensory.yml</code>.
+      </Callout>
+      <p>Authoritative copies in git:</p>
+      <ul>
+        <li>
+          <a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/gittensory.minimal.yml">
+            <code>config/examples/gittensory.minimal.yml</code>
+          </a>
+        </li>
+        <li>
+          <a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/gittensory.full.yml">
+            <code>config/examples/gittensory.full.yml</code>
+          </a>{" "}
+          (same body as{" "}
+          <a href="https://github.com/JSONbored/gittensory/blob/main/.gittensory.yml.example">
+            <code>.gittensory.yml.example</code>
+          </a>
+          )
+        </li>
+        <li>
+          <a href="https://github.com/JSONbored/gittensory/blob/main/config/examples/TEMPLATES.md">
+            <code>config/examples/TEMPLATES.md</code>
+          </a>{" "}
+          — catalog + fleet usage notes
+        </li>
+      </ul>
+      <p>
+        Several gate-only fields are documented only in the full template comments — see below for
+        the config-as-code blocks with no dashboard equivalent.
       </p>
 
       <h2>Required baseline env</h2>

config/examples/README.md

@@ -5,6 +5,10 @@ This directory ships **generic, safe** examples for the self-host **private** co
 contains no real policy, thresholds, logins, or repo names — copy what you need into your own
 mounted config directory and edit it there (never in this repo).
 
+See **[TEMPLATES.md](./TEMPLATES.md)** for the full template catalog (minimal + exhaustive
+`gittensory.yml` starters, public-vs-private usage, and fleet notes for `gittensory`,
+`awesome-claude`, and `metagraphed` without committing private policy).
+
 The private config directory is read by `src/selfhost/private-config.ts` and is kept **out of the
 public GitHub repo** on purpose: contributors can read a public `.gittensory.yml`, so anti-abuse
 thresholds, maintainer/admin allowlists, autonomy dials, and model/effort settings belong here
@@ -22,10 +26,11 @@ ${GITTENSORY_REPO_CONFIG_DIR}/.gittensory.yml               # 4. global default,
 ```
 
 `.yaml` and `.json` are accepted everywhere `.yml` is. Every one of these files uses the **exact
-same schema** as the public `.gittensory.yml` — see [`.gittensory.yml.example`](../../.gittensory.yml.example)
-at the repo root for the exhaustive, field-by-field reference (not duplicated here, so the two
-never drift out of sync). For the smallest safe starter, copy [`.gittensory.minimal.yml`](../../.gittensory.minimal.yml)
-to your repo root as `.gittensory.yml` and customize from there.
+same schema** as the public `.gittensory.yml` — see [`gittensory.full.yml`](./gittensory.full.yml)
+(or [`.gittensory.yml.example`](../../.gittensory.yml.example) at the repo root) for the exhaustive,
+field-by-field reference. For the smallest safe starter, copy [`gittensory.minimal.yml`](./gittensory.minimal.yml)
+(or [`.gittensory.minimal.yml`](../../.gittensory.minimal.yml)) to your repo root as `.gittensory.yml`
+or into your private mount and customize from there.
 
 ## Precedence chain
 

config/examples/TEMPLATES.md

@@ -0,0 +1,98 @@
+# Gittensory review config templates
+
+Copy-paste templates for `.gittensory.yml` — the per-repo review manifest. Every file in this
+directory uses the **same schema** whether it lives in a public repo root or a self-host private
+mount (`GITTENSORY_REPO_CONFIG_DIR`).
+
+## Template catalog
+
+| File | Purpose |
+|------|---------|
+| [`gittensory.minimal.yml`](./gittensory.minimal.yml) | Smallest safe starter — gate off, observe-only autonomy, no accidental writes |
+| [`gittensory.full.yml`](./gittensory.full.yml) | Exhaustive commented reference — every `gate:`, `settings:`, `review:`, and `features:` field |
+| [`global.gittensory.yml`](./global.gittensory.yml) | **Private only** — illustrative fleet-wide default for a self-host mount |
+| [`repo-override.gittensory.yml`](./repo-override.gittensory.yml) | **Private only** — per-repo overlay deep-merged over `global.gittensory.yml` |
+
+Canonical copies of the minimal and full templates also live at the repo root as
+[`.gittensory.minimal.yml`](../../.gittensory.minimal.yml) and
+[`.gittensory.yml.example`](../../.gittensory.yml.example). CI keeps the `config/examples/` copies
+in sync with those files.
+
+## Public repo root vs private self-host mount
+
+| Layer | Path | Who can read it | Typical contents |
+|-------|------|-----------------|------------------|
+| **Public** | `.gittensory.yml` or `.github/gittensory.yml` in git | Contributors | `wantedPaths`, test expectations, public review presentation |
+| **Private global** | `${GITTENSORY_REPO_CONFIG_DIR}/.gittensory.yml` | Operator only | Shared autonomy baseline, contributor caps, maintainer allowlists |
+| **Private per-repo** | `${GITTENSORY_REPO_CONFIG_DIR}/owner__repo/.gittensory.yml` | Operator only | Repo-specific CI context names, AI mode, overrides |
+
+When **either** a private global or private per-repo file exists, the loader **never fetches** the
+public repo file for that review — mount private policy deliberately. See [README.md](./README.md)
+for precedence and deep-merge rules.
+
+**Never commit real private policy** (maintainer logins, thresholds, autonomy dials you do not want
+contributors to read) into a public repository. Copy `global.gittensory.yml` into your gitignored
+`gittensory-config/` mount and edit there.
+
+## Quick start
+
+### Public repo (contributor-visible config)
+
+```bash
+cp config/examples/gittensory.minimal.yml .gittensory.yml
+# edit wantedPaths / gate when ready
+```
+
+### Self-host private mount (operator-only policy)
+
+```bash
+mkdir -p gittensory-config
+cp config/examples/global.gittensory.yml gittensory-config/.gittensory.yml
+# edit your-admin-login placeholders before going live
+# optional per-repo overlay:
+mkdir -p gittensory-config/myorg__myrepo
+cp config/examples/repo-override.gittensory.yml gittensory-config/myorg__myrepo/.gittensory.yml
+```
+
+Point `GITTENSORY_REPO_CONFIG_DIR` at that directory (default `/config` in `docker-compose.yml` maps
+`./gittensory-config`).
+
+## Fleet examples (without committing private policy)
+
+These patterns apply to common JSONbored repos. **Do not copy real maintainer logins or thresholds
+into public git** — use the private mount for anything marked *private* below.
+
+### `JSONbored/gittensory` (dogfooding)
+
+- **Public** `.gittensory.yml` in the repo: work-area guardrails, test expectations, gate dimensions
+  contributors should understand.
+- **Private** `gittensory-config/` (gitignored locally, operator mount in production): fleet
+  autonomy, anti-abuse caps, maintainer exemption lists — the same split described in
+  [`global.gittensory.yml`](./global.gittensory.yml).
+- Start from `gittensory.minimal.yml` in the public repo until gate semantics are tuned, then promote
+  fields into the private global default as you enable autonomous review.
+
+### `JSONbored/awesome-claude` (public template repo)
+
+- Prefer **`gittensory.minimal.yml`** or a trimmed public manifest: `wantedPaths`, linked-issue
+  policy, and advisory gate modes only.
+- Keep contributor caps, `autoCloseExemptLogins`, and `autonomy.close: auto` in **private config
+  only** — this repo is meant to be copied; do not bake operator-specific enforcement into its
+  public history.
+
+### `JSONbored/metagraphed` (sibling product repo)
+
+- Same split as `gittensory`: public manifest for transparent contributor guidance; private mount
+  for thresholds and maintainer-only rules.
+- Use `repo-override.gittensory.yml` when one repo needs different `expectedCiContexts` or
+  `gate.checkMode: disabled` while sharing a fleet-wide `global.gittensory.yml` baseline.
+
+## Validation
+
+Every template in this directory is parsed in CI (`test/unit/config-templates.test.ts` and
+`test/unit/selfhost-config-examples.test.ts`). The exhaustive template body is kept identical to
+`.gittensory.yml.example` from `# WHERE IT LIVES` onward. Lint a local file before deploy:
+
+```bash
+npx tsx scripts/gittensory-config-lint.ts path/to/.gittensory.yml
+```