docs: add platform RGD delivery design

docs/docs/designs/gitops-multi-cluster.md

@@ -194,6 +194,7 @@ gitops/
 │   │   │   └── teamb.yaml
 │   │   └── applicationsets/
 │   │       ├── platform.yaml
+│   │       ├── clusters-platform.yaml
 │   │       ├── clusters-nonprod.yaml
 │   │       ├── clusters-prod.yaml
 │   │       ├── teams-nonprod.yaml
@@ -211,17 +212,32 @@ gitops/
 │   │       ├── teama-appa3/
 │   │       ├── teamb-appb1/
 │   │       └── teamb-appb2/
-│   └── rgds/
-│       ├── appdeployment.yaml
-│       └── teamnamespace.yaml
 ├── clusters/
+│   ├── platform/
+│   │   ├── platform/
+│   │   │   ├── kro.yaml
+│   │   │   ├── rgds-platform.yaml
+│   │   │   ├── rgds-apps.yaml
+│   │   │   └── platform.yaml
+│   │   ├── policies/
+│   │   └── shared/
 │   ├── nonprod/
+│   │   ├── platform/
+│   │   │   ├── kro.yaml
+│   │   │   ├── rgds-platform.yaml
+│   │   │   ├── rgds-apps.yaml
+│   │   │   └── platform.yaml
 │   │   ├── capsule/
 │   │   │   ├── teama.yaml
 │   │   │   └── teamb.yaml
 │   │   ├── policies/
 │   │   └── shared/
 │   └── prod/
+│       ├── platform/
+│       │   ├── kro.yaml
+│       │   ├── rgds-platform.yaml
+│       │   ├── rgds-apps.yaml
+│       │   └── platform.yaml
 │       ├── capsule/
 │       │   ├── teama.yaml
 │       │   └── teamb.yaml
@@ -243,8 +259,11 @@ gitops/
 
 The ownership model is:
 
-- `platform/`: platform-cluster state and shared APIs
-- `clusters/`: workload-cluster shared state
+- `platform/`: platform-cluster control-plane state
+- `clusters/*/platform/`: cluster-local `kro` bootstrap, released RGD bundle
+  installation, and cluster-local `Platform` instances
+- `clusters/*/capsule`, `clusters/*/policies`, and `clusters/*/shared`:
+  workload-cluster shared state
 - `teams/`: team-owned application instances
 
 ## Argo CD Model
@@ -253,10 +272,14 @@ One `Argo CD` instance runs on the platform cluster.
 
 It syncs:
 
-- `platform/argocd`, `platform/capi`, `platform/kargo`, and `platform/rgds` to
-  the platform cluster
-- `clusters/nonprod` to the `nonprod` cluster
-- `clusters/prod` to the `prod` cluster
+- `platform/argocd`, `platform/capi`, and `platform/kargo` to the platform
+  cluster
+- `clusters/platform/platform` to the platform cluster
+- `clusters/nonprod/platform`, `clusters/nonprod/capsule`,
+  `clusters/nonprod/policies`, and `clusters/nonprod/shared` to the `nonprod`
+  cluster
+- `clusters/prod/platform`, `clusters/prod/capsule`,
+  `clusters/prod/policies`, and `clusters/prod/shared` to the `prod` cluster
 - `teams/*/*/envs/dev`, `teams/*/*/envs/staging`, and
   `teams/*/*/ephemeral/*` to the `nonprod` cluster
 - `teams/*/*/envs/prod` to the `prod` cluster
@@ -265,8 +288,14 @@ The intended Argo shape is:
 
 - one `AppProject` per team
 - `ApplicationSet` for platform-owned fleet generation
+- one admin-owned bootstrap `Application` per cluster for
+  `clusters/<cluster>/platform/`
 - `Application` resources kept in the `argocd` namespace
 
+Within each `clusters/<cluster>/platform/` directory, sync waves should order
+objects so `kro` installs first, the released RGD bundles install second, and
+the cluster-local `Platform` instance is created last.
+
 Do not rely on application CRs scattered across arbitrary namespaces as the
 default control model. The central `argocd` namespace is simpler unless a later
 team self-service requirement makes that extra complexity worth it.
@@ -277,11 +306,17 @@ team self-service requirement makes that extra complexity worth it.
 
 The intended pattern is:
 
-- shared `ResourceGraphDefinition`s live under `platform/rgds/`
-- environment-specific custom resources live under `teams/`
+- shared RGD source and release lifecycle live in the `platform` repo
+- cluster-local RGD bundle installation and cluster-local platform instances
+  live under `clusters/<cluster>/platform/`
+- environment-specific application custom resources live under `teams/`
 - Argo CD syncs the YAML
+- versioned RGD bundles are installed from OCI artifacts
 - `kro` expands the custom resources into the Kubernetes objects they own
 
+The platform-side release, CUE authoring, and OCI publication model is defined
+in [Platform RGD Delivery Model](./platform-rgd-delivery.md).
+
 An environment-specific application resource should be narrow and explicit. For
 example:
 
@@ -365,9 +400,12 @@ The intended policy is:
 ## Worked Example: TeamA / AppA1
 
 1. `CAPI` creates the `nonprod` and `prod` workload clusters.
-2. `Argo CD` syncs shared platform state to the platform cluster.
-3. `Argo CD` syncs Capsule tenants `teama` and `teamb` to `nonprod` and `prod`.
-4. `Argo CD` syncs the shared `kro` `ResourceGraphDefinition`s.
+2. `Argo CD` syncs shared control-plane state to the platform cluster.
+3. `Argo CD` syncs `clusters/platform/platform/`,
+   `clusters/nonprod/platform/`, and `clusters/prod/platform/`, installing
+   `kro`, the selected released `platform-rgds` and `apps-rgds` bundles, and
+   the cluster-local `Platform` instances.
+4. `Argo CD` syncs Capsule tenants `teama` and `teamb` to `nonprod` and `prod`.
 5. `teams/teama/appa1/envs/dev/app.yaml` defines an `AppDeployment` with
    namespace `teama-appa1-dev`.
 6. CI publishes a new image for `AppA1`.

docs/docs/designs/index.md

@@ -19,6 +19,7 @@ Current designs:
 
 - [Multi-Cluster GitOps Model](./gitops-multi-cluster.md)
 - [kro Consumption Model](./kro-consumption-model.md)
+- [Platform RGD Delivery Model](./platform-rgd-delivery.md)
 - [App RGD Design](./app-rgd.md)
 
 Once a design is implemented and considered durable, its steady-state shape

docs/docs/designs/kro-consumption-model.md

@@ -10,8 +10,8 @@ description: Proposed design for how GilmanLab publishes, consumes, and promotes
 Proposed.
 
 This document captures the intended role of `kro` in the lab and the current
-working model for how `kro` resources flow from developer-owned source
-repositories into environment-specific desired state in the `gitops` repo.
+working model for how shared platform-owned APIs and developer-owned release
+intent flow into environment-specific desired state in the `gitops` repo.
 
 This is an initial design draft. It intentionally does not define concrete
 `ResourceGraphDefinition` schemas yet. The next design pass should define the
@@ -91,7 +91,12 @@ Examples include future APIs such as:
 - team namespace bootstrap APIs
 - platform capability APIs
 
-This document does not define those schemas yet.
+The source of truth for those shared APIs lives in the `platform` repo, not the
+`gitops` repo. The platform team authors and releases those APIs there, then
+publishes versioned bundle artifacts that `gitops` can install per cluster.
+
+The concrete platform-side release and delivery model is described in
+[Platform RGD Delivery Model](./platform-rgd-delivery.md).
 
 ### Developer-owned application release intent
 
@@ -131,15 +136,21 @@ materialized into the `gitops` repo under environment-specific paths on
 This means the environment-specific folders in the `gitops` repo are still the
 final desired state that Argo CD reconciles.
 
+For platform-side APIs, the `gitops` repo also holds cluster-local installation
+of released RGD bundles and cluster-local instances such as `Platform`.
+
 ## Relationship to the GitOps Model
 
 This design builds on the multi-cluster GitOps model described in
 [Multi-Cluster GitOps Model](./gitops-multi-cluster.md).
 
 The important clarification is:
 
-- `kro` API definitions are platform-owned
+- `kro` API definitions are platform-owned and released from the `platform`
+  repo
 - developer-authored API instances are release inputs
+- `gitops` selects released API bundle versions per cluster and carries
+  cluster-local platform instances
 - Kargo materializes environment-specific outputs into the `gitops` repo
 - Argo CD reconciles those outputs from `main`
 
@@ -159,6 +170,24 @@ gitops/
 This document does not settle the exact `gitops` folder layout beyond that
 principle.
 
+The intended platform-side cluster bootstrap shape in `gitops` is:
+
+```text
+gitops/
+└── clusters/
+    └── <cluster>/
+        └── platform/
+            ├── kro.yaml
+            ├── rgds-platform.yaml
+            ├── rgds-apps.yaml
+            └── platform.yaml
+```
+
+This cluster-local layout installs `kro`, installs selected released RGD
+bundles, and declares the cluster-local `Platform` instance. The detailed
+release, build, and OCI publication model is described in
+[Platform RGD Delivery Model](./platform-rgd-delivery.md).
+
 ## Promotion Model
 
 `Kargo` should treat a release as more than an image update.
@@ -306,10 +335,12 @@ The current working model is:
 3. CI produces an image and a corresponding Git commit.
 4. Kargo bundles those artifacts into Freight.
 5. Kargo promotes Freight between environments.
-6. During promotion, Kargo combines release input with environment-specific
+6. The `gitops` repo installs released shared API bundles per cluster and
+   carries cluster-local platform instances such as `Platform`.
+7. During promotion, Kargo combines release input with environment-specific
    inputs and writes the final resource instances into the environment-specific
    area of the `gitops` repo on `main`.
-7. Argo CD reconciles those final resource instances from the `gitops` repo.
+8. Argo CD reconciles those final resource instances from the `gitops` repo.
 
 This is the design baseline for the next pass.