docs: review the configuration surface, and record three consumer asks against the published contract

docs/INDEX.md

@@ -65,12 +65,13 @@ says what we support and refuse** — and then its
 kustomize field taxonomy, the write boundary, the orchestrator/expansion line, and
 how secrets are handled.
 
-Twelve other open items:
+Thirteen other open items:
 
 | Doc | Open question |
 |---|---|
 | [`docs-linting.md`](design/docs-linting.md) | how to mechanize [`style-guide.md`](style-guide.md) with markdownlint-cli2 and Vale. Both are wired into `task lint`, gated on the files [`.docs-lint-scope`](../.docs-lint-scope) lists rather than the whole tree: 102 of 174 files fail markdownlint and 148 of 174 fail Vale, so the two backlogs need different gates. Open: how the scope list grows to cover the tree, the `MD013` limit, and whether `AGENTS.md` and the chart READMEs are in scope |
 | [`attribution-fact-identity.md`](design/attribution-fact-identity.md) | several `ClusterProvider`s may name one physical cluster, but a kube-apiserver posts audit to one route, so only one of those names is ever fed and every other one authors `unknown (attribution unresolved)`. Proposes a declared `spec.attribution.auditRoute` that partitions the facts instead of `metadata.name`, so several providers can share one cluster's facts while cloned clusters stay separate, ingestion loses its last Kubernetes read, and a misrouted provider becomes loud. Renames the key infix and the annotation-key flag to the same word |
+| [`analyzer-consumer-contract-asks.md`](design/analyzer-consumer-contract-asks.md) | three asks from the first downstream consumer of `pkg/manifestanalyzer`, each the same failure at a different layer — a distinction our code knows, published as prose no test defends. Permanence on a `RefusalReason` (they shipped "not supported yet" for `invalid-yaml`, because one deprecated code was the only signal the type offered); the analyzer's version in its own JSON report, plus a signed release binary; and `ResourceIdentifier.Key()`'s string format as a documented contract with a golden test — it has **no test at all** today. Carries our classification of all seventeen internal `IssueKind` values (the public package exports only fourteen, and three codes can reach a consumer with no constant to match on); open: the per-construct split for `unsupported-kustomize`, and whether `Key()` or `ToGitPath()` is the identity when a preferred version bumps |
 | [`watch-and-catalog-architecture.md`](design/watch-and-catalog-architecture.md) | the target three-layer watch model — **needs a human call before building** |
 | [`metrics-observability-plan.md`](design/metrics-observability-plan.md) | the watch-stage metrics do not exist yet |
 | [`reconcile-triggering.md`](design/reconcile-triggering.md) | which controllers still fail to wake up |
@@ -90,7 +91,12 @@ grouping strategies nothing else covers.
 [`ha-gittarget-distribution-plan.md`](future/ha-gittarget-distribution-plan.md) is
 the HA plan `architecture.md` cites three times (and the reason Redis is required).
 [`least-privilege-remaining-work.md`](future/least-privilege-remaining-work.md) has
-three open RBAC items. Five more ideas sit beside them.
+three open RBAC items.
+[`config-surface-for-a-structured-repository.md`](future/config-surface-for-a-structured-repository.md)
+reviews the configuration docs and argues the API never caught up with what the
+folder analysis learned — a look-before-you-write mode, a `status.layout`
+projection, an inference switch, and moving `commitWindow` onto the GitTarget.
+Five more ideas sit beside them.
 
 ## History — [`finished/`](finished/)
 

docs/architecture.md

@@ -530,7 +530,8 @@ team-a-config/                              # GitTarget spec.path
 
 The **built-in default** path is `{spec.path}/{namespace}/{group}/{resource}/{name}.yaml`, namespace
 first, the API group omitted for core resources, no version segment, and a `.sops.yaml` suffix for
-sensitive resources; a cluster-scoped resource uses the literal `cluster/` in place of the namespace.
+sensitive resources; a cluster-scoped resource uses the literal `_cluster/` in place of the namespace
+(an illegal Kubernetes namespace name, so it can never clash with a real one).
 But that default is only the cold-start seed: a new resource first follows its **siblings'** existing
 layout, and a `GitTarget` can declare its own placement policy. Details and the placement policy are in
 [File Placement](#file-placement).
@@ -859,7 +860,7 @@ refreshes that source.
 ### TypeRegistry and followability
 
 - **Source**: [internal/typeset/](../internal/typeset/)
-- **Design**: [design/manifest/version2/type-followability.md](spec/type-followability.md)
+- **Design**: [type-followability.md](spec/type-followability.md)
 
 `internal/typeset` is the single decision surface for "can this type be followed?" Each `TypeRecord`
 carries GVK/GVR identity, scope and preferred version facts, origin classification, subresource facts
@@ -1278,7 +1279,7 @@ Deeper dives live under [docs/design/](design/):
 - [Typeset owns discovery grace](spec/typeset-owns-discovery-grace.md)
 - [Kubernetes API resource catalog](facts/kubernetes-api-resource-catalog.md)
 - [GitTarget status design](spec/status-conditions-guide.md)
-- [GitTarget lifecycle and repo architecture](architecture.md)
+- [The support contract: what we edit, what we refuse, and why](design/support-boundary/support-contract.md)
 - [Git credentials interop](finished/git-credentials-interop.md)
 - [SOPS/age key management](finished/sops-repo-bootstrap-and-key-management-architecture.md)
 - [Commit signing](commit-signing.md)

docs/configuration.md

@@ -661,8 +661,8 @@ The boundaries that keep it predictable:
   want all ConfigMaps bundled even though none exist yet" is a job for `byType` below.
 
 The full ladder, tie-break rules, and edge cases are in
-[design/manifest/version2/gittarget-new-file-placement-rules.md](spec/gittarget-new-file-placement-rules.md);
-the vision behind it is [design/manifest/file-agnostic-placement.md](spec/gittarget-new-file-placement-rules.md).
+[gittarget-new-file-placement-rules.md](spec/gittarget-new-file-placement-rules.md), which also carries
+the vision the sibling-inference step serves.
 
 #### Declaring a layout (`byType` / `default`)