docs(gitops-api): onboarding repo-discovery design (F8)

docs/architecture.md

@@ -910,7 +910,7 @@ hydrates only touched files into buffers for the commit, and flushes only change
   entry in the document's kustomization chain is written back to that entry (comment-preserving, only
   fields the entry already declares); the source manifest keeps its bytes. Anything the inversion cannot
   express falls back to the plain in-place patch. See
-  [gitops-api/f1-images-replicas-edit-through.md](design/gitops-api/f1-images-replicas-edit-through.md).
+  [gitops-api/finished/f1-images-replicas-edit-through.md](design/gitops-api/finished/f1-images-replicas-edit-through.md).
 * **Deletes:** use the manifest identity index, so a moved manifest can still be deleted even when it is
   not at the canonical path.
 * **Field patches** (currently `/scale` → parent `spec.replicas`) are intentionally narrow: they only

docs/configuration.md

@@ -542,7 +542,7 @@ entry). These fallbacks are recorded as store diagnostics — visible in the ana
 the running operator, in the logs at debug verbosity (`manifest store diagnostic`).
 
 For design details and the exact boundary, see
-[design/gitops-api/f1-images-replicas-edit-through.md](design/gitops-api/f1-images-replicas-edit-through.md).
+[design/gitops-api/finished/f1-images-replicas-edit-through.md](design/gitops-api/finished/f1-images-replicas-edit-through.md).
 
 ## `WatchRule`
 

docs/design/gitops-api/README.md

@@ -28,6 +28,11 @@ The division of responsibility is deliberate and already a recorded decision
   `Pushed=True` + `status.sha` + `status.branch`).
 - **Product layer**: session/branch lifecycle policy, PR creation and merge,
   branch cleanup, and any UI.
+- **Onboarding (CLI / library)**: repo-wide discovery — enumerate candidate
+  `GitTarget`s, classify each folder's layout, report supported-vs-refused with
+  reasons, and propose the CRs — built on the shared analyzer engine, writing
+  nothing. See
+  [f8-repo-discovery-and-onboarding-scan.md](f8-repo-discovery-and-onboarding-scan.md).
 
 The operator never gains Git-host knowledge (no GitHub/GitLab API calls).
 
@@ -115,23 +120,25 @@ exactly what prices F3.
 
 Ordered by delivery priority for the launch path above (F-numbers are stable
 identifiers, not an ordering). Each feature gets its own design doc in this
-folder when work starts. The cross-cutting scope decisions behind the ladder — the
+folder when work starts; a shipped feature's doc moves to
+[finished/](finished/). The cross-cutting scope decisions behind the ladder — the
 kustomization field taxonomy, the supported-layout allowlist, who runs
 kustomize, the multi-environment product model (promotion, "factor into
 base"), and the mirror-mode vs. intent-cluster topology — live in
 [kustomize-support-boundary-and-product-model.md](kustomize-support-boundary-and-product-model.md).
 
 | # | Feature | Design doc | Status |
 |---|---------|-----------|--------|
-| F1 | Kustomize `images:` / `replicas:` edit-through — a live change produced by an override entry is written back to that entry, never through into the source manifest | [f1-images-replicas-edit-through.md](f1-images-replicas-edit-through.md) | implemented ([#198](https://github.com/ConfigButler/gitops-reverser/pull/198)) |
-| F7 | Higher-level KRM objects as first-class documents — corpus + e2e pinning that Flux `HelmRelease`/`Kustomization`, Argo CD `Application`, KRO resources, and core resources mirror and edit like any KRM document (they should already; F7 *proves* it), plus "install an app = add KRM" user docs | [f7-higher-level-krm-documents.md](f7-higher-level-krm-documents.md) | implemented (manifestedit corpus for HelmRelease/Application/KRO; HelmRelease mirror+edit e2e; [installing-apps-as-krm.md](../../installing-apps-as-krm.md) user docs) |
+| F1 | Kustomize `images:` / `replicas:` edit-through — a live change produced by an override entry is written back to that entry, never through into the source manifest | [finished/f1-images-replicas-edit-through.md](finished/f1-images-replicas-edit-through.md) | implemented ([#198](https://github.com/ConfigButler/gitops-reverser/pull/198)) |
+| F7 | Higher-level KRM objects as first-class documents — corpus + e2e pinning that Flux `HelmRelease`/`Kustomization`, Argo CD `Application`, KRO resources, and core resources mirror and edit like any KRM document (they should already; F7 *proves* it), plus "install an app = add KRM" user docs | [finished/f7-higher-level-krm-documents.md](finished/f7-higher-level-krm-documents.md) | implemented (manifestedit corpus for HelmRelease/Application/KRO; HelmRelease mirror+edit e2e; [installing-apps-as-krm.md](../../installing-apps-as-krm.md) user docs) |
 | F2 | Render-root scoping — a GitTarget declares its render root (e.g. `overlays/env1`); base files reached through `../../base` become read-only context, dissolving overlay fan-out ambiguity. Launch scope: overlay `images:`/`replicas:` entries + overlay-local documents, shipped **with** the per-edit `FullyReflected` accounting | — | not designed — **launch-critical** |
 | F4 | New-file placement rules — sibling inference + `spec.placement` template so new resources land in the folder's convention, not the canonical REST path; includes creating the `resources:` entry when the target folder carries a kustomization | designed in [version2/gittarget-new-file-placement-rules.md](../manifest/version2/gittarget-new-file-placement-rules.md) | implemented (v1: declared policy + sibling inference steps 1/2/4 + kustomize `resources:` entry; step 3 and ordered-rule Option A deferred) |
 | F5 | Branch/session ergonomics — base-branch selection, opt-in remote branch cleanup, a GitTarget-level quiescence condition | — | not designed — **launch-critical** |
 | F3 | Restricted patch authoring — write/update scalar-field strategic-merge patches in an overlay ("live drift lands in the environment's overlay"); turns the launch-time unreflected class (per-env edits of base-owned fields) into reflected edits | — | post-launch; priced by tier-2 metrics |
 | F6 | Admission preflight gate — opt-in intent-cluster webhook rejecting edits that cannot be reflected into the folder (fail-open; the underlying per-edit `FullyReflected` accounting ships with the F2/F4 launch unit) | [unreflectable-edits-and-write-gating.md](unreflectable-edits-and-write-gating.md) | designed, unbuilt — value highest while F3 is absent |
+| F8 | Repo discovery & onboarding scan (**CLI / product-layer**) — walk a whole repo, enumerate candidate `GitTarget`s, classify each folder's layout (plain / kustomize-single / kustomize-overlay / refused), report supported-vs-refused with reasons, and propose the CRs; the product layer (GitHub App) consumes the report to generate `GitTarget`s and open PRs. Built on the shared analyzer engine — **ships no operator code** | [f8-repo-discovery-and-onboarding-scan.md](f8-repo-discovery-and-onboarding-scan.md) | designed, unbuilt |
 
-## What already works (baseline, 2026-07-06)
+## What already works (baseline, 2026-07-09)
 
 - Raw-YAML folders (explicit namespaces): in-place, comment-preserving edits;
   match-first placement; mark-and-sweep resync.
@@ -146,7 +153,7 @@ base"), and the mirror-mode vs. intent-cluster topology — live in
 - Higher-level KRM documents (Flux `HelmRelease`, Argo CD `Application`, KRO
   resources) mirror and edit exactly like core resources — the pipeline is
   kind-agnostic, now pinned by F7's corpus + HelmRelease e2e
-  ([f7-higher-level-krm-documents.md](f7-higher-level-krm-documents.md)).
+  ([finished/f7-higher-level-krm-documents.md](finished/f7-higher-level-krm-documents.md)).
 
 ## Known boundary (what stays refused)