docs: restructure the README, and generate the settings index from the CRDs

.devcontainer/devcontainer.json

@@ -106,6 +106,12 @@
     "HOST_PROJECT_PATH": "${localWorkspaceFolder}",
     "PROJECT_PATH": "/workspaces/${localWorkspaceFolderBasename}",
     "GIT_USER_NAME": "${localEnv:GIT_USER_NAME}",
-    "GIT_USER_EMAIL": "${localEnv:GIT_USER_EMAIL}"
+    "GIT_USER_EMAIL": "${localEnv:GIT_USER_EMAIL}",
+    // Same path as go.testEnvVars above, so a plain `go test ./internal/controller/...`
+    // in the terminal works too and not only a test launched from the Go extension.
+    // post-create.sh creates the symlink; `task link-envtest-assets` repairs it. Note
+    // `task test` does NOT read this: it exports the path from setup-envtest itself, so
+    // the gate is unaffected by a stale link.
+    "KUBEBUILDER_ASSETS": "${containerWorkspaceFolder}/bin/k8s/current"
   }
 }

.devcontainer/post-create.sh

@@ -56,6 +56,22 @@ else
   sudo chown -R vscode:vscode /home/vscode || true
 fi
 
+# envtest binaries, and the bin/k8s/current symlink that KUBEBUILDER_ASSETS points at.
+# Doing it here means a controller test run from the Test Explorer works on a fresh
+# container, before anyone has run `task test` to create the link as a side effect.
+#
+# Non-fatal on purpose: it needs the network to fetch the binaries, and an environment
+# that is otherwise usable should not fail to come up because that fetch did not. The
+# task is idempotent, so `task test` repairs it later either way.
+if command -v task >/dev/null 2>&1; then
+  log "Linking envtest assets for KUBEBUILDER_ASSETS"
+  if ! (cd "${workspace_dir}" && task link-envtest-assets); then
+    log "WARNING: could not prepare envtest assets. Run 'task link-envtest-assets' once you"
+    log "WARNING: have network; until then IDE-run controller tests will fail on a missing"
+    log "WARNING: KUBEBUILDER_ASSETS path."
+  fi
+fi
+
 # Persist the ~/.claude.json file by making it a symlink (this trick can be used for other potenial config file in the home folder as well)
 touch /home/vscode/persisted-home/.claude.json
 rm -f /home/vscode/.claude.json && ln -s /home/vscode/persisted-home/.claude.json /home/vscode/.claude.json

.docs-lint-scope

@@ -27,3 +27,5 @@ docs/architecture.md
 docs/configuration.md
 docs/spec/attribution.md
 docs/components.md
+docs/quickstart.md
+docs/demo/commit-window.md

.golangci.yml

@@ -384,6 +384,12 @@ linters:
       # opens nothing it was handed by a reference, and writes nothing at all.
       - path: 'hack/doccheck/.*\.go'
         linters: [forbidigo, gosec]
+      # The settings-index generator is a standalone dev CLI too: it reports what it
+      # rewrote to the console (forbidigo), and it reads the CRD glob and writes the
+      # one document named by the targetFile constant (gosec G304/G703). The only
+      # caller that supplies a different path is its own test, into t.TempDir().
+      - path: 'hack/crdfields/.*\.go'
+        linters: [forbidigo, gosec]
       # Allow fmt.Println in metrics exporter (initialization logs)
       - path: 'internal/telemetry/.*\.go'
         linters: [forbidigo]

.vale/styles/HouseStyle/Filler-Judgment.yml

@@ -1,7 +1,19 @@
 # docs/style-guide.md -> "Words to cut", the rows that need the deletion test.
 #
-# Split out of WordsToCut.yml. These four are sometimes correct, and no linter can
-# tell which time it is looking at, so this rule reminds rather than rules.
+# Split out of WordsToCut.yml. These are sometimes correct, and no linter can tell
+# which time it is looking at, so this rule reminds rather than rules.
+#
+# `real` is here rather than in WordsToCut.yml because it fails the same test in
+# both directions. It is filler wherever nothing unreal is in play -- "the real
+# configuration objects that drive gitops-reverser" promised a distinction the
+# guide never draws, since there is no second, fake set of objects to tell them
+# apart from. It earns its place wherever there IS a counterpart: "it can never
+# clash with a real one" contrasts with a synthetic `_unlabeled` bucket, and "a
+# real apiserver" contrasts with a fake. Measured before adding it: 431 uses
+# across docs/ and the README, more than three times `actually`, and nearly all
+# of them the second kind. That ratio is why this can only ever be a suggestion
+# -- a rule that fired on all 431 would be read as noise and skimmed, which is
+# exactly the failure WordsToCut.yml's header records.
 #
 # The guide's own example is the proof: `actually` earns its place in "the source
 # document, where the value actually lives", because it marks a contrast with the
@@ -22,3 +34,4 @@ tokens:
   - actually
   - genuinely
   - really
+  - real

CONTRIBUTING.md

@@ -149,21 +149,29 @@ The design note for the playground flow lives in
 
 ## Documentation checks
 
-`task lint-docs` runs all three, and `task lint` includes it. Each owns one thing and none of them
+`task lint-docs` runs them all, and `task lint` includes it. Each owns one thing and none of them
 overlaps with the others:
 
 | Task | Tool | Checks |
 |---|---|---|
 | `task lint-doc-links` | `hack/doccheck` | Every reference resolves, including repo-relative doc paths cited inside Go comments, YAML, and shell. No off-the-shelf tool reads those. |
 | `task lint-markdown` | markdownlint-cli2 | Structure: fences, headings, lists, blank lines, bullet style. |
 | `task lint-prose` | Vale | English against [`docs/style-guide.md`](docs/style-guide.md): em dashes, American spelling, product names, words to cut. |
+| `task lint-metric-names` | `hack/metricnames.sh` | Every `gitopsreverser_` metric named anywhere in the tree is actually registered. |
+| `task lint-settings-index` | `hack/crdfields` | The settings index in [`docs/configuration.md`](docs/configuration.md) lists every CRD field, with the schema's own required flags and defaults. |
 
 ```bash
 task lint-docs                  # links and structure everywhere; prose on the gated files
 task lint-markdown-fix          # apply the safe mechanical fixes
 task lint-prose DOCS_SCOPE=all  # the whole tree, to see the prose backlog
+task settings-index             # rewrite the settings index after an API change
 ```
 
+**The settings index is generated.** `docs/configuration.md` carries it between
+`<!-- BEGIN GENERATED: settings-index -->` markers; edit
+[`hack/crdfields/fields.yaml`](hack/crdfields/fields.yaml) and run `task settings-index` instead of
+editing the table. Adding an API field without describing it there fails the gate, naming the field.
+
 **Links and structure are checked on every tracked file; only prose is gated on the files
 [`.docs-lint-scope`](.docs-lint-scope) lists.** Structure was staged the same way until the residue
 was cleared, so markdownlint now gates the whole tree and a new document cannot regress it. Vale