diff --git a/api/v1alpha1/openbaocluster_types.go b/api/v1alpha1/openbaocluster_types.go
index 22fa93100..937c77421 100644
--- a/api/v1alpha1/openbaocluster_types.go
+++ b/api/v1alpha1/openbaocluster_types.go
@@ -703,8 +703,10 @@ type UpgradeConfig struct {
 	// The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
 	// which is automatically created by the operator.
 	//
-	// If OIDC is enabled in SelfInit and this field is empty, a default role
-	// named "openbao-operator-upgrade" will be assumed/created.
+	// If OIDC is enabled during initial SelfInit bootstrap and this field is
+	// empty, a default role named "openbao-operator-upgrade" will be created.
+	// For already-initialized clusters, configure this role explicitly or keep
+	// the default role created during initial bootstrap.
 	//
 	// This is the supported authentication mechanism for built-in upgrade orchestration.
 	// +optional
@@ -713,9 +715,9 @@ type UpgradeConfig struct {
 	// token for future non-JWT upgrade authentication flows.
 	//
 	// Built-in rolling and blue/green upgrade orchestration does not support
-	// token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-	// spec.selfInit.oidc.enabled instead.
-	// +kubebuilder:validation:XValidation:rule="self == null",message="spec.upgrade.tokenSecretRef is not supported; configure spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled"
+	// token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+	// default role created during initial spec.selfInit.oidc bootstrap.
+	// +kubebuilder:validation:XValidation:rule="self == null",message="spec.upgrade.tokenSecretRef is not supported; configure spec.upgrade.jwtAuthRole or use the default role created during initial spec.selfInit.oidc bootstrap"
 	// +optional
 	TokenSecretRef *corev1.LocalObjectReference `json:"tokenSecretRef,omitempty"`
 
@@ -2081,9 +2083,10 @@ type OpenBaoClusterSpec struct {
 	//
 	// Built-in upgrade executor Jobs authenticate with JWT auth using the
 	// upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-	// spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-	// the operator assumes or bootstraps the default "openbao-operator-upgrade"
-	// role.
+	// spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+	// spec.upgrade.jwtAuthRole is empty, the operator creates the default
+	// "openbao-operator-upgrade" role. Already-initialized clusters must keep
+	// that role or configure spec.upgrade.jwtAuthRole explicitly.
 	//
 	// Pre-upgrade snapshots use spec.backup configuration and backup
 	// authentication rather than spec.upgrade credentials.
diff --git a/charts/openbao-operator/crds/openbao.org_openbaoclusters.yaml b/charts/openbao-operator/crds/openbao.org_openbaoclusters.yaml
index e8e2da383..d3789dd33 100644
--- a/charts/openbao-operator/crds/openbao.org_openbaoclusters.yaml
+++ b/charts/openbao-operator/crds/openbao.org_openbaoclusters.yaml
@@ -4579,9 +4579,10 @@ spec:
 
                   Built-in upgrade executor Jobs authenticate with JWT auth using the
                   upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-                  spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-                  the operator assumes or bootstraps the default "openbao-operator-upgrade"
-                  role.
+                  spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+                  spec.upgrade.jwtAuthRole is empty, the operator creates the default
+                  "openbao-operator-upgrade" role. Already-initialized clusters must keep
+                  that role or configure spec.upgrade.jwtAuthRole explicitly.
 
                   Pre-upgrade snapshots use spec.backup configuration and backup
                   authentication rather than spec.upgrade credentials.
@@ -4708,8 +4709,10 @@ spec:
                       The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
                       which is automatically created by the operator.
 
-                      If OIDC is enabled in SelfInit and this field is empty, a default role
-                      named "openbao-operator-upgrade" will be assumed/created.
+                      If OIDC is enabled during initial SelfInit bootstrap and this field is
+                      empty, a default role named "openbao-operator-upgrade" will be created.
+                      For already-initialized clusters, configure this role explicitly or keep
+                      the default role created during initial bootstrap.
 
                       This is the supported authentication mechanism for built-in upgrade orchestration.
                     type: string
@@ -4775,8 +4778,8 @@ spec:
                       token for future non-JWT upgrade authentication flows.
 
                       Built-in rolling and blue/green upgrade orchestration does not support
-                      token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-                      spec.selfInit.oidc.enabled instead.
+                      token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+                      default role created during initial spec.selfInit.oidc bootstrap.
                     properties:
                       name:
                         default: ""
@@ -4791,7 +4794,8 @@ spec:
                     x-kubernetes-map-type: atomic
                     x-kubernetes-validations:
                     - message: spec.upgrade.tokenSecretRef is not supported; configure
-                        spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled
+                        spec.upgrade.jwtAuthRole or use the default role created during
+                        initial spec.selfInit.oidc bootstrap
                       rule: self == null
                 type: object
               version:
diff --git a/config/crd/bases/openbao.org_openbaoclusters.yaml b/config/crd/bases/openbao.org_openbaoclusters.yaml
index bd1bfc60c..8754a74dd 100644
--- a/config/crd/bases/openbao.org_openbaoclusters.yaml
+++ b/config/crd/bases/openbao.org_openbaoclusters.yaml
@@ -4578,9 +4578,10 @@ spec:
 
                   Built-in upgrade executor Jobs authenticate with JWT auth using the
                   upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
-                  spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
-                  the operator assumes or bootstraps the default "openbao-operator-upgrade"
-                  role.
+                  spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and
+                  spec.upgrade.jwtAuthRole is empty, the operator creates the default
+                  "openbao-operator-upgrade" role. Already-initialized clusters must keep
+                  that role or configure spec.upgrade.jwtAuthRole explicitly.
 
                   Pre-upgrade snapshots use spec.backup configuration and backup
                   authentication rather than spec.upgrade credentials.
@@ -4707,8 +4708,10 @@ spec:
                       The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
                       which is automatically created by the operator.
 
-                      If OIDC is enabled in SelfInit and this field is empty, a default role
-                      named "openbao-operator-upgrade" will be assumed/created.
+                      If OIDC is enabled during initial SelfInit bootstrap and this field is
+                      empty, a default role named "openbao-operator-upgrade" will be created.
+                      For already-initialized clusters, configure this role explicitly or keep
+                      the default role created during initial bootstrap.
 
                       This is the supported authentication mechanism for built-in upgrade orchestration.
                     type: string
@@ -4774,8 +4777,8 @@ spec:
                       token for future non-JWT upgrade authentication flows.
 
                       Built-in rolling and blue/green upgrade orchestration does not support
-                      token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
-                      spec.selfInit.oidc.enabled instead.
+                      token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the
+                      default role created during initial spec.selfInit.oidc bootstrap.
                     properties:
                       name:
                         default: ""
@@ -4790,7 +4793,8 @@ spec:
                     x-kubernetes-map-type: atomic
                     x-kubernetes-validations:
                     - message: spec.upgrade.tokenSecretRef is not supported; configure
-                        spec.upgrade.jwtAuthRole or enable spec.selfInit.oidc.enabled
+                        spec.upgrade.jwtAuthRole or use the default role created during
+                        initial spec.selfInit.oidc bootstrap
                       rule: self == null
                 type: object
               version:
diff --git a/docs/reference/api.md b/docs/reference/api.md
index ef8a2949a..8341071e6 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -1038,7 +1038,7 @@ _Appears in:_
 | `auditFileStorage` _[AuditFileStorageConfig](#auditfilestorageconfig)_ | AuditFileStorage configures a shared filesystem integration point for file audit devices.<br />When configured, file audit device paths must be under auditFileStorage.mountPath. |  | Optional: \{\} <br /> |
 | `plugins` _[Plugin](#plugin) array_ | Plugins configures declarative plugins for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/plugins/ |  | Optional: \{\} <br /> |
 | `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures telemetry reporting for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/telemetry/ |  | Optional: \{\} <br /> |
-| `upgrade` _[UpgradeConfig](#upgradeconfig)_ | Upgrade configures upgrade operations.<br />Built-in upgrade executor Jobs authenticate with JWT auth using the<br />upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount). If<br />spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,<br />the operator assumes or bootstraps the default "openbao-operator-upgrade"<br />role.<br />Pre-upgrade snapshots use spec.backup configuration and backup<br />authentication rather than spec.upgrade credentials. |  | Optional: \{\} <br /> |
+| `upgrade` _[UpgradeConfig](#upgradeconfig)_ | Upgrade configures upgrade operations.<br />Built-in upgrade executor Jobs authenticate with JWT auth using the<br />upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount). If<br />spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and<br />spec.upgrade.jwtAuthRole is empty, the operator creates the default<br />"openbao-operator-upgrade" role. Already-initialized clusters must keep<br />that role or configure spec.upgrade.jwtAuthRole explicitly.<br />Pre-upgrade snapshots use spec.backup configuration and backup<br />authentication rather than spec.upgrade credentials. |  | Optional: \{\} <br /> |
 | `unseal` _[UnsealConfig](#unsealconfig)_ | Unseal defines the auto-unseal configuration.<br />If omitted, defaults to "static" mode managed by the operator. |  | Optional: \{\} <br /> |
 | `imageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | ImageVerification configures supply chain security checks. |  | Optional: \{\} <br /> |
 | `operatorImageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | OperatorImageVerification configures supply chain security checks for operator-managed helper images<br />(init container, backup/upgrade/restore executors). These images are typically signed<br />by the operator project (e.g., dc-tec/openbao-operator) rather than the OpenBao upstream project.<br />If omitted, helper image verification does not fall back to ImageVerification.<br />In Development, omitted means disabled. In Hardened, omitted means enabled. |  | Optional: \{\} <br /> |
@@ -2026,8 +2026,8 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `image` _string_ | Image is the container image to use for upgrade operations.<br />This image is used by Kubernetes Jobs created during upgrades (for example, blue/green<br />cluster orchestration actions). The executor runs inside the tenant namespace and<br />authenticates to OpenBao using a projected ServiceAccount token (JWT auth).<br />If not specified, defaults to "&lt;repo&gt;:X.Y.Z" where &lt;repo&gt; is derived from OPERATOR_UPGRADE_IMAGE_REPOSITORY<br />(default: "ghcr.io/dc-tec/openbao-upgrade") and the tag matches OPERATOR_VERSION. |  | Optional: \{\} <br /> |
 | `preUpgradeSnapshot` _boolean_ | PreUpgradeSnapshot, when true, triggers a backup before any upgrade.<br />When enabled, the upgrade manager will create a backup using the backup<br />configuration (spec.backup.target, spec.backup.image, etc.) and<br />wait for it to complete before proceeding with the upgrade.<br />If the backup fails, the upgrade will be blocked and a Degraded condition<br />will be set with Reason=PreUpgradeBackupFailed.<br />Requires spec.backup to be configured with target, image, and<br />authentication (jwtAuthRole or tokenSecretRef). |  | Optional: \{\} <br /> |
-| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for upgrade executor Jobs. The executor authenticates with a projected<br />ServiceAccount token from &lt;cluster-name&gt;-upgrade-serviceaccount.<br />The role must be configured in OpenBao and must grant the permissions<br />required by the selected upgrade strategy, including:<br />- "read" capability on sys/health<br />- "sudo" and "update" capability on sys/step-down<br />- "read" capability on sys/storage/raft/autopilot/state<br />- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations<br />The role must bind to the upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount),<br />which is automatically created by the operator.<br />If OIDC is enabled in SelfInit and this field is empty, a default role<br />named "openbao-operator-upgrade" will be assumed/created.<br />This is the supported authentication mechanism for built-in upgrade orchestration. |  | Optional: \{\} <br /> |
-| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token for future non-JWT upgrade authentication flows.<br />Built-in rolling and blue/green upgrade orchestration does not support<br />token-based authentication. Configure spec.upgrade.jwtAuthRole or enable<br />spec.selfInit.oidc.enabled instead. |  | Optional: \{\} <br /> |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for upgrade executor Jobs. The executor authenticates with a projected<br />ServiceAccount token from &lt;cluster-name&gt;-upgrade-serviceaccount.<br />The role must be configured in OpenBao and must grant the permissions<br />required by the selected upgrade strategy, including:<br />- "read" capability on sys/health<br />- "sudo" and "update" capability on sys/step-down<br />- "read" capability on sys/storage/raft/autopilot/state<br />- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations<br />The role must bind to the upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount),<br />which is automatically created by the operator.<br />If OIDC is enabled during initial SelfInit bootstrap and this field is<br />empty, a default role named "openbao-operator-upgrade" will be created.<br />For already-initialized clusters, configure this role explicitly or keep<br />the default role created during initial bootstrap.<br />This is the supported authentication mechanism for built-in upgrade orchestration. |  | Optional: \{\} <br /> |
+| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token for future non-JWT upgrade authentication flows.<br />Built-in rolling and blue/green upgrade orchestration does not support<br />token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the<br />default role created during initial spec.selfInit.oidc bootstrap. |  | Optional: \{\} <br /> |
 | `strategy` _[UpdateStrategyType](#updatestrategytype)_ | Strategy defines the update strategy to use. | RollingUpdate | Enum: [RollingUpdate BlueGreen] <br /> |
 | `requests` _[UpgradeRequestConfig](#upgraderequestconfig)_ | Requests defines explicit one-shot operator requests for the current<br />upgrade workflow. The operator acts only when a request value changes. |  | Optional: \{\} <br /> |
 | `blueGreen` _[BlueGreenConfig](#bluegreenconfig)_ | BlueGreen configures the behavior when Strategy is BlueGreen. |  | Optional: \{\} <br /> |
diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md
index 76d31c621..b0df2e811 100644
--- a/docs/reference/compatibility.md
+++ b/docs/reference/compatibility.md
@@ -41,7 +41,7 @@ The current stable release line is intended for real deployments, but it remains
       emphasis: 'caution',
     },
     {
-      cells: ['v1.33', 'Not validated for the current release line', 'May work but is not release-gated for 0.2.0', 'Validate in staging before carrying this version into the current pre-GA line'],
+      cells: ['v1.33', 'Not validated for the current release line', 'May work but is not release-gated for the current line', 'Validate in staging before carrying this version into the current pre-GA line'],
       emphasis: 'caution',
     },
     {
diff --git a/docs/reference/known-limitations.md b/docs/reference/known-limitations.md
index 3136ff0d1..40c91e4f8 100644
--- a/docs/reference/known-limitations.md
+++ b/docs/reference/known-limitations.md
@@ -35,7 +35,7 @@ journey: reference
       cells: ['Helm CRD lifecycle', 'Helm does not automatically upgrade or delete CRDs.', 'Use release `crds.yaml` assets for CRD lifecycle operations.'],
     },
     {
-      cells: ['Built-in upgrade authentication', 'Built-in rolling and blue/green upgrade orchestration do not support `spec.upgrade.tokenSecretRef`; upgrade Jobs use JWT authentication only.', 'Configure `spec.upgrade.jwtAuthRole` or enable `spec.selfInit.oidc.enabled` so the operator can bootstrap the upgrade auth path.'],
+      cells: ['Built-in upgrade authentication', 'Built-in rolling and blue/green upgrade orchestration do not support `spec.upgrade.tokenSecretRef`; upgrade Jobs use JWT authentication only.', 'Configure `spec.upgrade.jwtAuthRole`, or use the default role created during initial `selfInit.oidc` bootstrap.'],
     },
     {
       cells: ['Audit file storage archival', '`spec.auditFileStorage` provides a PVC-backed collector handoff and replay buffer; it does not provide rotation, pruning, tamper-proof retention, or a collector.', 'Mount the audit PVC read-only into a collector and ship records to external retention-controlled storage.'],
diff --git a/release-notes/0.3.0.md b/release-notes/0.3.0.md
new file mode 100644
index 000000000..ae4a71eea
--- /dev/null
+++ b/release-notes/0.3.0.md
@@ -0,0 +1,130 @@
+0.3.0 is the next stable pre-GA release line for OpenBao Operator. This
+release focuses on production operations hardening across operator
+authentication, observability, audit logging, Gateway and Ingress integration,
+runtime configuration, and backup and restore safety.
+
+### Highlights
+
+* Defaulted supported operator JWT flows to inline authentication, reducing
+  repeated login overhead while keeping controller, backup, restore, and upgrade
+  roles scoped separately.
+* Added workload metrics scraping support, including declarative metrics
+  configuration, managed `ServiceMonitor` reconciliation, active-node and
+  all-node scrape profiles, and optional metrics-only listener support.
+* Added audit file storage support for `OpenBaoCluster`, including managed PVC
+  wiring, pod-specific audit file paths, status reporting, and OpenBao-aligned
+  audit device options.
+* Improved Gateway and Ingress integration readiness with Gateway API v1
+  `TLSRoute` emission, explicit Gateway/Ingress readiness conditions, and
+  tolerance for GatewayClass implementations that omit the `SupportedVersion`
+  condition.
+* Improved PKCS#11 runtime ergonomics for HSM-backed deployments, including
+  runtime environment and file-based configuration wiring for vendor libraries.
+* Hardened backup, restore, storage endpoint, transit unseal, JWT role, and
+  helper input handling so unsafe or ambiguous configuration fails earlier and
+  more consistently.
+
+### Breaking and Migration Notes
+
+* Apply the `0.3.0` CRDs before upgrading the controller or Helm chart. This
+  release adds and tightens several `openbao.org/v1alpha1` fields and admission
+  checks.
+* Inline authentication is now the default supported JWT flow. Environments with
+  proxies or intermediaries between the operator and OpenBao must preserve the
+  `X-Vault-Inline-Auth-*` headers. Use the login compatibility strategy only
+  when inline auth headers cannot be passed reliably.
+* Audit file storage changes the OpenBao workload pod template. Enabling it on
+  an existing cluster can require StatefulSet recreation because Kubernetes
+  locks some volume and volume mount fields after creation. Preserve data PVCs
+  and plan the rollout before enabling audit file storage on production
+  clusters.
+* Static restore token Secrets are now validated more strictly. A restore token
+  Secret must be in the target namespace and carry the expected identity labels
+  for the target cluster and restore-token purpose before the operator launches
+  the restore job.
+* Backup, restore, and object storage endpoints are validated more strictly and
+  guarded at request time. Review custom S3-compatible endpoints, private
+  endpoints, and restore source configuration before upgrading.
+* Metrics-only listener and all-node metrics configurations can expose OpenBao
+  metrics without normal client authentication. Restrict access with
+  NetworkPolicy or equivalent cluster controls before enabling unauthenticated
+  scraping.
+* Gateway passthrough exposure requires a Gateway API implementation with the
+  needed Standard resources and listener behavior. ACME and OpenBao-managed TLS
+  flows should use passthrough rather than Gateway-side termination.
+
+### Operational Notes
+
+* The audit file storage PVC contains sensitive audit material. Treat it as
+  security-sensitive storage, include it in backup and retention planning, and
+  do not treat the operator-managed PVC as an immutable compliance archive.
+* File audit device paths must stay under the configured audit file storage
+  mount path.
+* Backup, restore, and upgrade jobs now rely on narrower auth roles. Existing
+  initialized clusters may need OpenBao policy or role updates before using
+  those workflows because the operator does not mutate OpenBao auth
+  configuration after initial bootstrap.
+* `spec.upgrade.tokenSecretRef` is not supported for upgrade jobs. Upgrade jobs
+  authenticate through the configured JWT auth role. For already-initialized
+  clusters, create or update the required OpenBao auth role and policy before
+  requesting an upgrade; `selfInit` only bootstraps auth during initial cluster
+  initialization and does not retrofit running clusters.
+* PKCS#11 deployments still require an OpenBao image with HSM support and the
+  vendor PKCS#11 module available at the configured library path. The operator
+  now wires the runtime more explicitly, but it does not provide vendor HSM
+  libraries.
+* OCI plugin downloads use OpenBao runtime configuration and the mounted plugin
+  cache directory. Kubernetes image pull secrets do not automatically authorize
+  OpenBao runtime plugin downloads, so private or disconnected environments
+  should mirror plugin images and configure registry access deliberately.
+* Tenants and platform teams that own Pod Security Standards labels outside the
+  operator can now keep that ownership model while using the operator
+  provisioner.
+* Users already running `0.2.1` have the duplicate Helm RBAC label and OCI plugin
+  directory fixes from the patch line; they remain included in `0.3.0`.
+
+### Upgrade from 0.2.x
+
+Before upgrading an existing `0.2.x` installation:
+
+1. Review every existing `OpenBaoCluster`, `OpenBaoRestore`, backup, Gateway,
+   Ingress, metrics, audit, and unseal configuration against the stricter
+   validation described above.
+2. For clusters using intermediary proxies between the operator and OpenBao,
+   confirm inline auth headers are preserved or plan to use the login
+   compatibility strategy.
+3. For clusters that will enable audit file storage, plan the StatefulSet
+   rollout and confirm data PVC retention before applying the change.
+4. For restore workflows using static token Secrets, add the required target
+   namespace and restore-token identity labels before creating new restores.
+5. For backup and restore workflows using S3-compatible storage, validate the
+   endpoint URLs and credentials in staging.
+6. Apply the `0.3.0` CRDs first:
+
+   ```sh
+   kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/0.3.0/crds.yaml
+   ```
+
+7. Upgrade the Helm release:
+
+   ```sh
+   helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
+     --version 0.3.0 \
+     --namespace openbao-operator-system \
+     --reuse-values
+   ```
+
+8. Verify the operator rollout, CRD presence, managed cluster conditions,
+   Gateway/Ingress readiness conditions, backup/restore events, and recent
+   controller logs before continuing with OpenBao workload changes.
+
+Kubernetes `v1.34` and `v1.35` are the 0.3.0 release-gated versions. Kubernetes
+`v1.33` may work but is not release-gated for this line. Kubernetes `v1.36` is
+tracked as the next candidate once controller-runtime, Kind, and release-gate
+coverage are available.
+
+### Compatibility
+
+OpenBao Operator requires Kubernetes `v1.33+`. The current release validation
+baseline is Kubernetes `v1.34`-`v1.35` and OpenBao `2.5.4`, with config
+compatibility coverage for OpenBao `2.4.4`.
diff --git a/releases/0.2.0.mdx b/releases/0.2.0.mdx
index 10ea40341..142b3ee83 100644
--- a/releases/0.2.0.mdx
+++ b/releases/0.2.0.mdx
@@ -9,7 +9,7 @@ slug: /0.2.0
 Published 2026-05-01.
 
 <CardGrid>
-  <LinkCard title="Matching docs" to="/docs">
+  <LinkCard title="Matching docs" to="/docs/0.2.0">
     Open the docs experience aligned to this release line.
   </LinkCard>
   <LinkCard title="GitHub release" to="https://github.com/dc-tec/openbao-operator/releases/tag/0.2.0">
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index 4fa19275b..a1676296d 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -13,6 +13,7 @@ const docsPluginDefaultExclude = [
   '**/__tests__/**',
 ];
 const releaseLineVersionLabels = {
+  '0.3.0': '0.3.x',
   '0.2.0': '0.2.x',
   '0.1.0': '0.1.x',
 } as const;
diff --git a/website/tests/behavior.spec.ts b/website/tests/behavior.spec.ts
index b338105b8..05d428e9f 100644
--- a/website/tests/behavior.spec.ts
+++ b/website/tests/behavior.spec.ts
@@ -42,7 +42,7 @@ test('version dropdown switches from next docs to the stable release line', asyn
   await versionDropdown.hover();
 
   const archivedRelease = page.locator('.dropdown__menu').getByRole('link', {
-    name: '0.2.x',
+    name: '0.3.x',
     exact: true,
   });
   await expect(archivedRelease).toBeVisible();
@@ -50,7 +50,7 @@ test('version dropdown switches from next docs to the stable release line', asyn
 
   await expect(page).toHaveURL(/\/openbao-operator\/docs\/get-started\/deployment-decision-guide$/);
   await expect(page.getByText('Published release documentation')).toBeVisible();
-  await expect(page.getByText('Version: 0.2.x')).toBeVisible();
+  await expect(page.getByText('Version: 0.3.x')).toBeVisible();
 });
 
 test.describe('curated legacy redirects stay alive', () => {
diff --git a/website/tests/smoke.spec.ts b/website/tests/smoke.spec.ts
index 24dc37462..87ab374dd 100644
--- a/website/tests/smoke.spec.ts
+++ b/website/tests/smoke.spec.ts
@@ -46,7 +46,7 @@ test('stable docs expose the current release banner', async ({page}) => {
 
   await expect(page.getByRole('heading', {name: 'OpenBao Operator documentation'})).toBeVisible();
   await expect(page.getByText('Published release documentation')).toBeVisible();
-  await expect(page.getByText('Version: 0.2.x')).toBeVisible();
+  await expect(page.getByText('Version: 0.3.x')).toBeVisible();
 });
 
 test('architecture section exposes grouped local navigation', async ({page}) => {
diff --git a/website/versioned_docs/version-0.3.0/architecture/backup-manager.md b/website/versioned_docs/version-0.3.0/architecture/backup-manager.md
new file mode 100644
index 000000000..82447eb2c
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/backup-manager.md
@@ -0,0 +1,200 @@
+---
+title: Backup Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Schedule snapshot jobs, enforce retention, and update backup status while keeping snapshot data transport out of the controller.
+---
+
+<PageHeader
+  title="Backup manager workflow"
+  lede="The backup manager owns scheduled and manual snapshot orchestration for `OpenBaoCluster`. It validates cluster readiness, acquires the operation lock, creates executor Jobs, and records backup state so backups stay auditable and resumable while snapshot transport stays outside the controller."
+/>
+
+
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'adminops reconciler',
+        'internal/app/openbaocluster/adminops',
+        'internal/service/backup',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'backup trigger detection for schedules and manual requests',
+        'preflight validation and operation-lock ownership for backup',
+        'retention evaluation after successful uploads',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'backup executor Jobs and job annotations',
+        'status.backup timing, success, and failure counters',
+        'operation lock state while backup is in progress',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'cluster health and absence of conflicting upgrade or restore work',
+        'spec.backup target, authentication, and executor image configuration',
+        'object-storage reachability and trust configuration for the selected provider',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Backup orchestration belongs to the AdminOps path:
+
+1. `internal/controller/openbaocluster` receives an adminops reconcile event.
+2. The controller delegates into `internal/app/openbaocluster/adminops`.
+3. AdminOps orchestration invokes `internal/service/backup` to validate, launch, and observe backup execution.
+
+That keeps the controller focused on reconcile plumbing while the backup manager owns timing, job launch, and retention decisions.
+
+<DecisionTable
+  kind="reference"
+  title="Owned surfaces"
+  columns={['Surface', 'What the manager decides', 'Why it matters']}
+  rows={[
+    {
+      cells: ['Backup trigger window', 'Whether a cron window, manual trigger, or pre-upgrade request should launch a new Job.', 'Backups need at-most-once behavior per scheduled window and predictable manual overrides.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Executor Job', 'Job name, annotations, auth wiring, and provider-specific environment for the backup binary.', 'The controller should schedule work, not stream snapshot data itself.'],
+    },
+    {
+      cells: ['status.backup', 'Attempt timing, next schedule, last success, and consecutive failure state.', 'Operators need backup visibility without inspecting transient Jobs.'],
+    },
+    {
+      cells: ['Retention policy', 'Which completed backups can be deleted after a successful upload.', 'Retention belongs to the control plane so cleanup stays consistent across providers.'],
+    },
+  ]}
+/>
+
+## Backup flow
+
+<DiagramFrame
+  title="Validate, launch, then record"
+  caption="The backup manager validates cluster state first, launches a stateless Job second, and only updates backup status after the Job reaches a terminal result."
+  code={`graph TD
+    Trigger["Cron or manual trigger"] --> Validate{"Preflight checks"}
+    Validate --> Retry["Requeue without launch"]
+    Validate --> Lock["Acquire backup operation lock"]
+    Lock --> Job["Create backup Job"]
+    Job --> Auth["Authenticate to OpenBao"]
+    Auth --> Snapshot["Stream Raft snapshot"]
+    Snapshot --> Upload["Upload to object storage"]
+    Upload --> Result{"Job result"}
+    Result --> Success["Patch lastSuccessfulBackup and next schedule"]
+    Result --> Failure["Increment consecutiveFailures and record attempt"]
+    Success --> Retention["Apply retention policy"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef critical fill:transparent,stroke:#dc2626,stroke-width:2px,color:#f8fafc;
+
+    class Trigger read;
+    class Validate,Lock,Job,Auth,Snapshot,Upload,Retention process;
+    class Success write;
+    class Failure critical;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Preflight and status model"
+  columns={['Check', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['Cluster readiness', 'Backup launches only when the cluster is in a stable running phase and the workload is not already mid-transition.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Conflicting operations', 'Restore and active upgrade state block backup launch; only one long-running operation may own the cluster lock at a time.'],
+    },
+    {
+      cells: ['At-most-once scheduling', 'status.backup.lastAttemptScheduledTime and nextScheduledBackup prevent duplicate launches in the same cron window.'],
+    },
+    {
+      cells: ['Failure accounting', 'Consecutive failures increase only when a terminal Job fails, not on every reconcile that notices the same failed Job.'],
+    },
+  ]}
+/>
+
+## Provider and retention surfaces
+
+<DecisionTable
+  kind="reference"
+  title="Provider integration surfaces"
+  columns={['Provider family', 'Auth patterns the manager supports', 'What stays the same']}
+  rows={[
+    {
+      cells: ['S3-compatible', 'Static access keys, explicit web identity, ambient workload identity, or ServiceAccount annotation-driven identity.', 'The manager still creates one executor Job and records status the same way after upload completes.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['GCS', 'Service account key, Application Default Credentials, or Workload Identity metadata on the generated pod identity.', 'Upload and retention stay job-driven; only the credential wiring changes.'],
+    },
+    {
+      cells: ['Azure Blob Storage', 'Account key, connection string, or managed identity/workload identity defaults.', 'Retention and backup naming stay provider-agnostic at the manager boundary.'],
+    },
+  ]}
+/>
+
+Backups are stored under a stable object prefix so restore workflows can locate artifacts without reverse-engineering Job names:
+
+```text
+<pathPrefix>/<namespace>/<cluster>/<timestamp>-<short-uuid>.snap
+```
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['No data-plane coupling', 'The controller never handles snapshot bytes directly; the executor Job performs authentication, snapshot, and upload work.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Retention timing', 'Retention runs only after a successful upload so cleanup never removes older recovery points before a new one exists.'],
+    },
+    {
+      cells: ['Upgrade coordination', 'Pre-upgrade snapshots reuse backup job machinery rather than creating a second snapshot implementation in the upgrade manager.'],
+    },
+    {
+      cells: ['Local buffering risk', 'The backup path is designed around streaming to object storage rather than writing large transient snapshot files inside the controller.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Restore manager',
+      description: 'Restore consumes the snapshot contract that backup writes and protects with lock ownership.',
+      docId: 'architecture/restore-manager',
+    },
+    {
+      label: 'Upgrade manager',
+      description: 'Pre-upgrade snapshots depend on the same backup execution surface instead of a separate snapshot implementation.',
+      docId: 'architecture/upgrade-manager',
+    },
+    {
+      label: 'Backups guide',
+      description: 'Compare the internal backup orchestration model with the user-facing schedule, provider, and restore instructions.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/cert-manager.md b/website/versioned_docs/version-0.3.0/architecture/cert-manager.md
new file mode 100644
index 000000000..5e874ded4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/cert-manager.md
@@ -0,0 +1,170 @@
+---
+title: Cert Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Manage TLS certificate sources, rotation windows, and hot-reload signaling for the OpenBao workload path.
+---
+
+<PageHeader
+  title="Certificate lifecycle management"
+  lede="The cert manager keeps TLS lifecycle close to the workload contract. It decides whether certificates are operator-managed, externally supplied, or handled by ACME, and it turns certificate changes into reload signals rather than pod restarts."
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'workload reconciler',
+        'internal/controller/openbaocluster',
+        'internal/service/certs',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'TLS mode handling for OperatorManaged, External, and ACME',
+        'CA and server certificate Secret lifecycle when the operator is the source',
+        'certificate hash generation and hot-reload signaling when leaf certs change',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'cluster TLS CA and server Secrets in OperatorManaged mode',
+        'trust-bundle ConfigMap surfaces for workload consumers',
+        'pod annotations used to trigger in-pod TLS reload',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'spec.tls.mode and rotation window settings',
+        'external Secret availability when TLS is not operator-managed',
+        'ready workload pods to accept reload signaling',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+TLS lifecycle stays on the workload reconcile path:
+
+1. `internal/controller/openbaocluster` determines that TLS state must reconcile.
+2. The controller calls `internal/service/certs`.
+3. The cert manager creates, validates, or watches certificate material and signals reload when the active server certificate changes.
+
+That keeps TLS behavior close to workload rendering while avoiding a second, disconnected certificate controller path.
+
+<DecisionTable
+  kind="decision"
+  title="TLS mode responsibilities"
+  columns={['Mode', 'Certificate source', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['OperatorManaged', 'Operator-generated root CA and server certificate Secrets.', 'Generate, rotate, export trust, and trigger reload when the leaf certificate hash changes.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['External', 'User or external controller provided Secrets.', 'Wait for required Secrets, validate usability, and still trigger reload when the external provider rotates content.'],
+    },
+    {
+      cells: ['ACME', 'OpenBao internal ACME flow and certificate cache.', 'Render the ACME listener configuration and step out of Secret management and hot-reload ownership.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+## Rotation and reload path
+
+<DiagramFrame
+  title="TLS rotation loop"
+  caption="In operator-managed mode, the manager decides when the current server certificate is within the rotation window, writes fresh material, computes a new hash, and signals reload only when the hash changed."
+  code={`graph TD
+    Check{"Check cert expiry"} --> Generate["Generate or reuse cert material"]
+    Generate --> Secrets["Update tls-ca / tls-server Secrets"]
+    Secrets --> Hash["Compute server-cert hash"]
+    Hash --> Change{"Hash changed?"}
+    Change --> Skip["No reload signal"]
+    Change --> Annotate["Annotate ready pods with new hash"]
+    Annotate --> Watcher["In-pod watcher observes change"]
+    Watcher --> Reload["Send SIGHUP / reload TLS"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Check read;
+    class Generate,Hash,Watcher process;
+    class Secrets,Annotate,Reload write;
+    class Change,Skip read;`}
+/>
+
+<DiagramFrame
+  title="Hot-reload boundary"
+  caption="The manager does not restart pods to pick up new certificates. Instead, it updates pod-level hash annotations that a lightweight in-pod watcher turns into a reload signal."
+  code={`sequenceDiagram
+    participant Certs as Cert manager
+    participant K8s as Kubernetes API
+    participant Pod as Pod annotation + mounted volume
+    participant Watcher as PID 1 watcher
+    participant Bao as OpenBao
+
+    Certs->>K8s: Update TLS Secret or confirm external change
+    Certs->>K8s: Patch pod annotation openbao.org/tls-cert-hash
+    K8s->>Pod: Project new Secret contents and annotation
+    Pod->>Watcher: File or annotation change observed
+    Watcher->>Bao: Send reload signal
+    Bao->>Bao: Reload listener certificate
+  `}
+/>
+
+<Callout type="note" title="ACME changes the ownership boundary">
+
+When `spec.tls.mode=ACME`, the cert manager still participates in rendering the listener contract, but OpenBao owns the live ACME issuance and cache lifecycle. Kubernetes TLS Secrets stop being the source of truth for the workload certificate.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['No forced pod restart', 'Certificate changes become hot-reload signals instead of StatefulSet rollouts or manual restart requirements.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['External TLS still observed', 'External mode is passive about issuance, but active about detecting usable Secret changes and propagating reload signals.'],
+    },
+    {
+      cells: ['Reload only on change', 'The manager computes a certificate hash and skips signaling when the new material is identical to what ready pods already observe.'],
+    },
+    {
+      cells: ['Source-of-truth clarity', 'OperatorManaged owns Secrets, External owns watching those Secrets, and ACME owns only the rendered listener contract rather than Secret reconciliation.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Workload managers',
+      description: 'See how bootstrap, networking, identity, and workload services consume TLS outputs on the workload path.',
+      docId: 'architecture/workload-managers',
+    },
+    {
+      label: 'TLS security guide',
+      description: 'Compare the internal certificate lifecycle model with the user-facing TLS configuration guidance.',
+      docId: 'security/workload/tls',
+    },
+    {
+      label: 'External TLS validated deployment',
+      description: 'See how external certificate ownership looks in a concrete hardened deployment recipe.',
+      docId: 'user-guide/validated-deployments/recipes/local/hardened-transit-external-tls',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/components.md b/website/versioned_docs/version-0.3.0/architecture/components.md
new file mode 100644
index 000000000..cd8b9994a
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/components.md
@@ -0,0 +1,200 @@
+---
+title: Component Design
+hide_title: true
+pageType: concept
+journey: architecture
+description: Split-controller architecture for OpenBaoCluster, OpenBaoRestore, and OpenBaoTenant, including controller boundaries, app-layer orchestration, and service-layer coordination.
+---
+
+<PageHeader
+  title="Split-controller control plane"
+  lede="Focused controllers, app-layer orchestration, narrow domain managers, and shared platform contracts keep workload churn, long-running operations, and status writes separated."
+/>
+
+## Controller split
+
+<DiagramFrame
+  title="Controller split"
+  caption="Workload, admin operations, and status are separated so high-churn reconciliation, long-running workflows, and API status writes do not block each other."
+  code={`graph TD
+    Manager["Manager process"] --> WorkloadCtrl["Workload controller"]
+    Manager --> Admin["AdminOps controller"]
+    Manager --> Status["Status controller"]
+
+    subgraph Roles["Responsibilities"]
+      WorkloadCtrl --> Cert["Cert manager"]
+      WorkloadCtrl --> Bootstrap["Bootstrap manager"]
+      WorkloadCtrl --> Networking["Networking manager"]
+      WorkloadCtrl --> Identity["Identity manager"]
+      WorkloadCtrl --> Init["Init manager"]
+      WorkloadCtrl --> WorkloadMgr["Workload manager"]
+
+      Admin --> Upgrade["Upgrade manager"]
+      Admin --> Backup["Backup manager"]
+
+      Status --> Conditions["Status conditions"]
+    end
+
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Manager process;
+    class WorkloadCtrl,Admin,Status write;
+    class Cert,Bootstrap,Networking,Identity,Init,WorkloadMgr,Upgrade,Backup,Conditions read;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Controller responsibilities"
+  columns={['Controller', 'Primary role', 'Why it stays separate']}
+  rows={[
+    {
+      cells: ['Workload', 'Reconciles workload-side certificate, bootstrap, networking, identity, initialization, and StatefulSet resources.', 'It handles high-churn pod and platform state and needs to react quickly.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['AdminOps', 'Runs upgrades and backups.', 'Long-running workflows should not block pod recovery or normal reconciliation.'],
+    },
+    {
+      cells: ['Status', 'Aggregates state and writes status updates.', 'Serializing status writes avoids ResourceVersion conflicts and keeps conditions stable.'],
+    },
+    {
+      cells: ['OpenBaoRestore', 'Reconciles destructive restore workflows.', 'Restore needs its own lock-aware control surface instead of riding on normal cluster reconcile loops.'],
+    },
+    {
+      cells: ['Provisioner', 'Reconciles OpenBaoTenant onboarding and namespace scaffolding.', 'Tenant guardrails belong to Day 0 provisioning, not to workload reconciliation.'],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Restore controller">
+
+Restores are reconciled through the separate `OpenBaoRestore` controller, which orchestrates restore Jobs and acquires the cluster operation lock before destructive work starts.
+
+</Callout>
+
+## App orchestration and managers
+
+<DiagramFrame
+  title="App-layer orchestration"
+  caption="Controllers hand off to narrow app-layer facades first, then into focused managers and shared lifecycle services. This keeps import surfaces small and responsibilities explicit."
+  code={`graph TD
+    OBC["OpenBaoCluster controllers"] --> OBCApp["internal/app/openbaocluster"]
+    OBR["OpenBaoRestore controller"] --> OBRApp["internal/app/openbaorestore"]
+    Prov["Provisioner controller"] --> ProvApp["internal/app/provisioner"]
+
+    OBCApp --> WorkloadOps["Workload orchestration"]
+    OBCApp --> AdminOps["AdminOps orchestration"]
+    OBCApp --> StatusOps["Status and deletion orchestration"]
+
+    WorkloadOps --> Cert["Cert manager"]
+    WorkloadOps --> Bootstrap["Bootstrap manager"]
+    WorkloadOps --> Networking["Networking manager"]
+    WorkloadOps --> Identity["Identity manager"]
+    WorkloadOps --> Init["Init manager"]
+    WorkloadOps --> WorkloadMgr["Workload manager"]
+    AdminOps --> Upgrade["Upgrade manager"]
+    AdminOps --> Backup["Backup manager"]
+
+    OBRApp --> Restore["Restore manager"]
+    ProvApp --> Provisioner["Provisioner manager"]
+
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class OBC,OBR,Prov write;
+    class OBCApp,OBRApp,ProvApp,WorkloadOps,AdminOps,StatusOps process;
+    class Cert,Bootstrap,Networking,Identity,Init,WorkloadMgr,Upgrade,Backup,Restore,Provisioner read;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Manager boundaries"
+  columns={['Manager', 'Scope', 'Key reason for separation']}
+  rows={[
+    {
+      cells: ['Bootstrap manager', 'Renders config and prepares bootstrap prerequisites.', 'Config rendering and seal or self-init prerequisites change for different reasons than networking or StatefulSet mutation.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Networking manager', 'Owns Services, Gateway or Ingress resources, and workload network policy.', 'Reachability and network contract changes should not be coupled to config rendering or RBAC wiring.'],
+    },
+    {
+      cells: ['Identity manager', 'Owns the workload ServiceAccount and tenant-scoped RBAC.', 'Workload identity and RBAC should evolve independently from networking and StatefulSet behavior.'],
+    },
+    {
+      cells: ['Workload manager', 'Owns StatefulSet, PodDisruptionBudget, and rollout-safe workload mutation.', 'Replica intent, pod-template mutation, and rollout triggers belong close to the StatefulSet contract.'],
+    },
+    {
+      cells: ['Cert manager', 'Handles operator-managed, ACME, and external TLS interactions.', 'TLS integration has its own dependency model and readiness surface.'],
+    },
+    {
+      cells: ['Init manager', 'Coordinates initialization when self-init is disabled or needs confirmation.', 'Bootstrap logic is security-sensitive and distinct from normal steady-state reconcile work.'],
+    },
+    {
+      cells: ['Upgrade / Backup / Restore managers', 'Run lock-aware disruptive operations.', 'These workflows share lifecycle helpers but own different risk profiles and side effects.'],
+    },
+    {
+      cells: ['Provisioner manager', 'Onboards tenant namespaces and guardrails.', 'Tenant governance belongs to provisioning time, not to the cluster workload loop.'],
+    },
+  ]}
+/>
+
+## Shared contracts below managers
+
+The controller and app layers coordinate managers, but some semantics stay below the manager boundary because they must stay uniform across multiple services.
+
+<DecisionTable
+  kind="reference"
+  title="Shared contracts"
+  columns={['Contract', 'Used by', 'Why it stays separate']}
+  rows={[
+    {
+      cells: ['Configuration service', 'Bootstrap manager and blue-green upgrade startup.', '`config.hcl` semantics should stay in one place even though both workload bootstrap and upgrade orchestration need them.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Resource identity', 'Bootstrap, networking, identity, and workload managers.', 'Names, labels, and selectors define the managed-resource contract and should not drift across services.'],
+    },
+    {
+      cells: ['Owned apply', 'Bootstrap, networking, identity, and workload managers.', 'Generic owner-ref-aware SSA apply behavior is a platform concern; object-specific exceptions still stay in the owning service.'],
+    },
+    {
+      cells: ['Architecture boundary policy', 'Controllers, app packages, services, and selected platform packages.', 'Explicit service and adapter allowlists keep layered architecture rules enforced in CI instead of implied by convention alone.'],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Boundary contract">
+
+Controller, app, service, and selected platform import surfaces are intentionally narrow and enforced by generated architecture-boundary rules from `.ast-grep/policy/architecture-boundaries.yml`.
+
+</Callout>
+
+<NextActions
+  title="Deep dives"
+  items={[
+    {
+      label: 'Workload managers',
+      description: 'Bootstrap, networking, identity, and StatefulSet ownership on the workload reconcile path.',
+      docId: 'architecture/workload-managers',
+    },
+    {
+      label: 'Upgrade manager',
+      description: 'RollingUpdate and BlueGreen state transitions.',
+      docId: 'architecture/upgrade-manager',
+    },
+    {
+      label: 'Restore manager',
+      description: 'Destructive restore path and lock lifecycle behind OpenBaoRestore.',
+      docId: 'architecture/restore-manager',
+    },
+    {
+      label: 'Lifecycle architecture',
+      description: 'Day-by-day lifecycle flows that use these components.',
+      docId: 'architecture/lifecycle/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/index.mdx b/website/versioned_docs/version-0.3.0/architecture/index.mdx
new file mode 100644
index 000000000..38b69f0b8
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/index.mdx
@@ -0,0 +1,86 @@
+---
+title: Architecture
+slug: /architecture
+hide_title: true
+pageType: landing
+journey: architecture
+description: Internal design, controller boundaries, lifecycle flows, invariants, and implementation decisions behind OpenBao Operator.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Architecture"
+  title="Operator architecture"
+  lede="Controller boundaries, lifecycle coordination, invariants, and implementation tradeoffs behind OpenBao Operator."
+  actions={[
+    {label: 'Read the invariants', docId: 'architecture/operator-invariants', variant: 'primary'},
+    {label: 'Open component design', docId: 'architecture/components', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Use architecture when you need to"
+    items={[
+      'understand the contracts the operator is trying to preserve',
+      'see how controllers, managers, and shared services divide responsibility',
+      'follow a lifecycle flow from tenant onboarding to day 2 operations',
+      'connect internal behavior back to security posture and status semantics',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Architecture routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Operator invariants',
+      description: 'Lifecycle contracts and the assumptions the controller design depends on.',
+      docId: 'architecture/operator-invariants',
+    },
+    {
+      eyebrow: '02',
+      title: 'Component design',
+      description: 'Split-controller control plane, app layer, and manager boundaries.',
+      docId: 'architecture/components',
+    },
+    {
+      eyebrow: '03',
+      title: 'Workload managers',
+      description: 'Bootstrap, networking, identity, and StatefulSet ownership on the workload reconcile path.',
+      docId: 'architecture/workload-managers',
+    },
+    {
+      eyebrow: '04',
+      title: 'Operation lifecycle coordination',
+      description: 'Shared lock, retry, and phase-transition primitives behind backup, restore, and upgrade flows.',
+      docId: 'architecture/operation-lifecycle',
+    },
+    {
+      eyebrow: '05',
+      title: 'Lifecycle architecture',
+      description: 'Follow the operator from Day 0 provisioning through Day 2 operations and backup-driven recovery.',
+      docId: 'architecture/lifecycle/index',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related sections"
+  items={[
+    {
+      label: 'Open security',
+      description: 'Security contracts for RBAC, admission, identity, and workload controls.',
+      docId: 'security/index',
+    },
+    {
+      label: 'Open reference',
+      description: 'Status conditions, events, and observable contracts.',
+      docId: 'reference/status-and-events',
+    },
+    {
+      label: 'Open Operate',
+      description: 'User-facing operating guides for upgrades, backups, and recovery.',
+      docId: 'user-guide/openbaocluster/operations/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/init-manager.md b/website/versioned_docs/version-0.3.0/architecture/init-manager.md
new file mode 100644
index 000000000..5c25a2ef9
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/init-manager.md
@@ -0,0 +1,202 @@
+---
+title: Init Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Bootstrap a new cluster safely, handle self-init or operator init flows, and configure autopilot before scaling out.
+---
+
+<PageHeader
+  title="Initialize one node first, then scale only after the cluster is safe to join."
+  lede="The init manager owns the first-boot contract for a new `OpenBaoCluster`. It keeps bootstrap on a single node, handles operator-driven or self-init flows, stores or suppresses root material appropriately, and configures Raft autopilot before the workload expands to full replica count."
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'workload reconciler',
+        'internal/controller/openbaocluster',
+        'internal/service/init',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'bootstrap detection and first init call behavior',
+        'root token handling or self-init completion detection',
+        'initial autopilot configuration immediately after cluster initialization',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'status.initialized and status.selfInitialized',
+        'root token Secret when self-init is disabled',
+        'autopilot configuration through the OpenBao API once initialization completes',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'single-replica bootstrap from the workload manager',
+        'pod readiness and TLS Secret availability before init proceeds',
+        'self-init requests and auth bootstrap configuration when self-init is enabled',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Initialization stays on the workload-side controller path while the cluster is not yet ready for normal steady-state reconciliation:
+
+1. `internal/controller/openbaocluster` keeps the cluster on the uninitialized path.
+2. The controller calls `internal/service/init` once the first pod and TLS prerequisites are ready.
+3. The init manager marks initialization state, configures autopilot, and only then allows the workload manager to scale to the requested replica count.
+
+That separation prevents first-boot logic from leaking into every steady-state reconcile.
+
+## Bootstrap flow
+
+<DiagramFrame
+  title="Initialize, then scale"
+  caption="The workload manager holds the StatefulSet at one replica until the init manager confirms the cluster is initialized. Only then does the cluster expand to the requested replica count."
+  code={`sequenceDiagram
+    participant Ctrl as OpenBaoCluster controller
+    participant Workload as Workload manager
+    participant Pod0 as Pod-0
+    participant Init as Init manager
+    participant Bao as OpenBao API
+    participant Status as Cluster status
+
+    Ctrl->>Workload: Render StatefulSet at replicas=1
+    Workload->>Pod0: Start first pod
+    Pod0-->>Init: Pod ready + TLS available
+    Init->>Bao: Detect initialized or call /sys/init
+    Bao-->>Init: Init response or initialized health
+    Init->>Status: Set initialized / selfInitialized
+    Init->>Bao: Configure autopilot defaults
+    Status-->>Workload: Initialization confirmed
+    Workload->>Workload: Scale StatefulSet to spec.replicas
+  `}
+/>
+
+## Initialization phases
+
+<Tabs groupId="init-manager-phases">
+  <TabItem value="bootstrap" label="Bootstrap one node">
+
+<Checklist
+  title="Bootstrap contract"
+  items={[
+    'A new cluster starts at one replica even when spec.replicas is greater than one.',
+    'The workload manager keeps the StatefulSet capped until status.initialized becomes true.',
+    'This avoids race conditions where multiple uninitialized pods could compete to become the first Raft leader.',
+  ]}
+/>
+
+  </TabItem>
+  <TabItem value="initialize" label="Initialize safely">
+
+<Checklist
+  title="Initialization contract"
+  items={[
+    'The manager first checks for an already initialized cluster and skips the init call when status or health proves bootstrap already happened.',
+    'When self-init is disabled, it performs the init call, captures the root material once, and stores the root token in a Secret without logging the response.',
+    'When self-init is enabled, it treats pod readiness and initialization signals as the completion boundary and does not create a root-token Secret.',
+  ]}
+/>
+
+  </TabItem>
+  <TabItem value="scale" label="Scale after success">
+
+<Checklist
+  title="Scale-out contract"
+  items={[
+    'The manager sets status.initialized after the cluster is known-good and, when relevant, also sets status.selfInitialized.',
+    'Autopilot defaults are configured immediately after initialization so day-2 health policy exists before the cluster grows.',
+    'Only after that handoff does the workload path expand the StatefulSet and let additional pods join through retry_join.',
+  ]}
+/>
+
+  </TabItem>
+</Tabs>
+
+## Autopilot defaults
+
+<DecisionTable
+  kind="reference"
+  title="Autopilot configuration defaults"
+  columns={['Setting', 'Default behavior', 'Why the init manager sets it early']}
+  rows={[
+    {
+      cells: ['cleanup_dead_servers', 'Enabled by default, but forced off when minQuorum < 3 and the user did not explicitly override it.', 'The rendered policy must remain valid for small clusters before steady-state operations begin.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['dead_server_last_contact_threshold', '5m', 'Dead-peer cleanup should wait long enough to avoid reacting to short network turbulence.'],
+    },
+    {
+      cells: ['last_contact_threshold', '10s', 'Autopilot needs a consistent heartbeat tolerance before higher replica counts join.'],
+    },
+    {
+      cells: ['server_stabilization_time', '10s', 'New members should remain stable briefly before being treated as healthy participants.'],
+    },
+    {
+      cells: ['max_trailing_logs', '1000', 'Replication lag needs a default budget before dead-server or readiness logic starts treating peers as unhealthy.'],
+    },
+    {
+      cells: ['min_quorum', 'Hardened profile defaults to 3, or replicas when replicas > 3; other profiles use max(1, replicas).', 'The cleanup policy and quorum safety model must be aligned from the first initialized reconcile.'],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Already initialized is recovery, not import">
+
+If the manager detects that a cluster is already initialized, it takes the initialized-cluster path as recovery for an operator-managed cluster. It is not a generic import path for arbitrary unmanaged OpenBao clusters.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['Split-brain at bootstrap', 'Single-pod bootstrap stays in force until initialization is confirmed, so the first Raft leader forms in a controlled way.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Root material handling', 'The init response is used in-memory only for the current request and is not logged; self-init intentionally avoids creating a root-token Secret.'],
+    },
+    {
+      cells: ['TLS readiness', 'Initialization waits for the TLS server Secret when TLS is managed by the operator so the API path is not used before the workload is ready.'],
+    },
+    {
+      cells: ['Invalid autopilot cleanup', 'The manager forces cleanupDeadServers off for small-cluster configurations that OpenBao would reject.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Workload managers',
+      description: 'See how bootstrap, networking, identity, and workload services prepare Day 1 resources and keep the StatefulSet at one replica.',
+      docId: 'architecture/workload-managers',
+    },
+    {
+      label: 'Self-init guide',
+      description: 'Compare the internal self-init behavior with the user-facing bootstrap requests and auth setup.',
+      docId: 'user-guide/openbaocluster/configuration/self-init',
+    },
+    {
+      label: 'Day 1 lifecycle flow',
+      description: 'Follow where initialization fits in the broader cluster-creation sequence.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/lifecycle/day0-provisioning.md b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day0-provisioning.md
new file mode 100644
index 000000000..006f483d2
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day0-provisioning.md
@@ -0,0 +1,182 @@
+---
+title: Day 0 Provisioning
+hide_title: true
+pageType: concept
+journey: architecture
+description: Tenant provisioning flow from OpenBaoTenant creation through namespace-scoped RBAC, policy defaults, and the handoff to cluster creation.
+---
+
+<PageHeader
+  title="Provision the tenant boundary before any cluster exists."
+  lede="Day 0 is the namespace and tenancy setup phase. The provisioner controller takes an `OpenBaoTenant` request, applies tenant-scoped RBAC and policy defaults, and leaves behind a namespace that is safe for later `OpenBaoCluster` creation."
+/>
+
+
+
+<JourneyRail
+  current={1}
+  title="Lifecycle phases"
+  items={[
+    {
+      label: 'Day 0 provisioning',
+      description: 'Prepare a namespace boundary and tenant-scoped policy before any cluster exists.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+    {
+      label: 'Day 1 creation',
+      description: 'Bootstrap the first node, initialize safely, and only then scale out.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      label: 'Day 2 operations',
+      description: 'Hand off into upgrades, maintenance, and long-running operational workflows.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      label: 'Backups and restore',
+      description: 'Protect data durability with scheduled snapshots and explicit restore requests.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+  ]}
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Starts with',
+      items: [
+        '`OpenBaoTenant` creation and target namespace selection',
+        'operator ServiceAccount identity and tenant policy defaults',
+        'admission dependencies that must exist before Secret access is widened',
+      ],
+    },
+    {
+      label: 'Primary owners',
+      items: [
+        'internal/controller/provisioner',
+        'internal/app/provisioner',
+        'internal/service/provisioner',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'tenant Role and RoleBinding resources',
+        'Secret reader and writer allowlist roles',
+        'Pod Security labels when configured plus optional ResourceQuota and LimitRange defaults',
+      ],
+    },
+    {
+      label: 'Hands off to',
+      items: [
+        'a namespace that is ready for `OpenBaoCluster` creation',
+        'tenant operators who can now move into Day 1 cluster creation',
+        'later Secret allowlist sync as clusters appear or disappear',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Day 0 provisioning uses the dedicated tenant-controller path:
+
+1. A cluster admin or namespace owner creates `OpenBaoTenant`.
+2. `internal/controller/provisioner` receives the reconcile event and delegates into `internal/app/provisioner`.
+3. `internal/service/provisioner` applies namespace-scoped RBAC, policy labels, allowlists, and quota defaults.
+
+This keeps tenant onboarding separate from steady-state cluster reconciliation and makes the tenant boundary explicit before any workload resources exist.
+
+Day 0 also defines the handoff into Day 1. In multi-tenant mode, `OpenBaoCluster` controllers wait until the tenant `RoleBinding` exists before they begin finalizer, status, or workload mutation in that namespace.
+
+<DiagramFrame
+  title="Day 0 provisioning flow"
+  caption="Provisioning establishes the namespace boundary first, then keeps Secret access aligned with the managed clusters that later appear in that namespace."
+  code={`sequenceDiagram
+    autonumber
+    participant Admin as Admin or namespace owner
+    participant K8s as Kubernetes API
+    participant Ctrl as Provisioner controller
+    participant App as App orchestration
+    participant Manager as Provisioner manager
+    participant Namespace as Tenant namespace
+
+    Admin->>K8s: Create OpenBaoTenant
+    K8s-->>Ctrl: Watch OpenBaoTenant
+    Ctrl->>App: Reconcile tenant request
+    App->>Manager: Apply tenant provisioning contract
+    Manager->>Namespace: Create tenant Role / RoleBinding
+    Manager->>Namespace: Apply Pod Security labels when configured to own them
+    Manager->>Namespace: Apply optional quota defaults
+    Manager->>Namespace: Sync Secret allowlist roles
+    Namespace-->>Admin: Namespace ready for OpenBaoCluster
+    Namespace-->>K8s: Tenant RoleBinding exists
+    K8s-->>Ctrl: OpenBaoCluster reconcile may proceed
+  `}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Day 0 responsibilities"
+  columns={['Stage', 'Primary owner', 'Why it matters']}
+  rows={[
+    {
+      cells: ['Namespace targeting', 'Provisioner controller and app layer.', 'Tenant provisioning must decide which namespace is allowed before any RBAC or policy defaults are applied.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Operator tenant RBAC', 'Provisioner manager.', 'The operator needs enough namespace-scoped access to manage OpenBao resources there without defaulting to broad cluster-wide permissions.'],
+    },
+    {
+      cells: ['Controller handoff', 'Provisioner manager plus OpenBaoCluster controllers.', 'The tenant `RoleBinding` marks when the namespace is actually writable for cluster reconciliation, which matters for GitOps paths that submit tenant and cluster objects together.'],
+    },
+    {
+      cells: ['Secret allowlists', 'Provisioner manager plus tenant Secret RBAC sync.', 'Multi-tenant safety depends on explicit Secret access derived from actual managed cluster references.'],
+    },
+    {
+      cells: ['Policy defaults', 'Provisioner manager plus platform policy when namespace labels are externally managed.', 'Pod Security labels and optional quotas give the namespace a safe baseline before a cluster is created.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Provisioning behavior']}
+  rows={[
+    {
+      cells: ['Self-service namespace scope', 'Self-service tenants may target only their own namespace; cross-namespace provisioning is reserved for trusted centrally managed cases.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Admission readiness', 'Tenant Secret allowlists wait for admission-policy dependencies so Secret access is not widened before enforcement is available.'],
+    },
+    {
+      cells: ['Shared RBAC lifecycle', 'Tenant RBAC avoids OwnerReferences that would let a single cluster deletion garbage-collect shared namespace permissions.'],
+    },
+    {
+      cells: ['Cleanup timing', 'Provisioned RBAC remains in place until managed clusters are gone, then the tenant finalizer can be released safely.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the lifecycle"
+  items={[
+    {
+      label: 'Day 1 creation',
+      description: 'Follow how a provisioned namespace hands off into first-cluster bootstrap and initialization.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      label: 'Provisioner manager',
+      description: 'Open the deep dive for the exact namespace-scoped RBAC, allowlist, and cleanup contract.',
+      docId: 'architecture/provisioner-manager',
+    },
+    {
+      label: 'Tenant onboarding guide',
+      description: 'Compare the internal provisioning flow with the operator-facing onboarding steps.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/lifecycle/day1-creation.md b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day1-creation.md
new file mode 100644
index 000000000..ca77d0fea
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day1-creation.md
@@ -0,0 +1,227 @@
+---
+title: Day 1 Creation
+hide_title: true
+pageType: concept
+journey: architecture
+description: Cluster creation flow from OpenBaoCluster creation through TLS bootstrap, one-node initialization, autopilot configuration, and scale-out.
+---
+
+<PageHeader
+  title="Bootstrap one node, initialize safely, then scale to the requested cluster shape."
+  lede="Day 1 begins when `OpenBaoCluster` is created. The control plane bootstraps TLS and unseal prerequisites, prepares workload-side resources, keeps the StatefulSet at one replica for safe initialization, then hands off into steady-state operations only after the cluster is known-good."
+/>
+
+<JourneyRail
+  current={2}
+  title="Lifecycle phases"
+  items={[
+    {
+      label: 'Day 0 provisioning',
+      description: 'Prepare a namespace boundary and tenant-scoped policy before any cluster exists.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+    {
+      label: 'Day 1 creation',
+      description: 'Bootstrap the first node, initialize safely, and only then scale out.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      label: 'Day 2 operations',
+      description: 'Hand off into upgrades, maintenance, and long-running operational workflows.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      label: 'Backups and restore',
+      description: 'Protect data durability with scheduled snapshots and explicit restore requests.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+  ]}
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Starts with',
+      items: [
+        '`OpenBaoCluster` creation and the requested replica count',
+        'TLS mode, unseal mode, and optional self-init configuration',
+        'a provisioned namespace boundary from Day 0 when multi-tenancy is in use',
+      ],
+    },
+    {
+      label: 'Primary owners',
+      items: [
+        'internal/service/certs',
+        'internal/service/bootstrap',
+        'internal/service/networking',
+        'internal/service/identity',
+        'internal/service/workload',
+        'internal/service/init',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'TLS Secrets, trust-bundle surfaces, and rendered `config.hcl`',
+        'network and identity prerequisites for the main workload',
+        'single-replica StatefulSet followed by scale-out after initialization',
+        '`status.initialized`, `status.selfInitialized`, and initial autopilot configuration',
+      ],
+    },
+    {
+      label: 'Hands off to',
+      items: [
+        'steady-state workload reconciliation once the cluster is initialized',
+        'day 2 upgrade, maintenance, and backup workflows',
+        'operator-facing configuration and first-cluster guides',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Day 1 creation crosses the workload-side services in sequence:
+
+1. The cert manager ensures TLS material exists or is ready to be observed.
+2. The bootstrap manager renders config and startup prerequisites.
+3. The networking and identity managers create the service and RBAC surfaces the workload needs.
+4. The workload manager holds the StatefulSet at one replica and applies rollout-safe workload resources.
+5. The init manager initializes the cluster, configures autopilot defaults, and only then allows scale-out.
+
+That split keeps first-boot safety logic separate from routine steady-state reconciliation.
+
+<DiagramFrame
+  title="Day 1 creation flow"
+  caption="First boot is a controlled handoff: TLS and rendered prerequisites first, one-node bootstrap second, initialization and autopilot third, then scale-out into the requested cluster size."
+  code={`sequenceDiagram
+    autonumber
+    participant User as User
+    participant K8s as Kubernetes API
+    participant Certs as Cert manager
+    participant Bootstrap as Bootstrap manager
+    participant Networking as Networking manager
+    participant Identity as Identity manager
+    participant Workload as Workload manager
+    participant Init as Init manager
+    participant Pod0 as Pod-0
+
+    User->>K8s: Create OpenBaoCluster
+    K8s-->>Certs: Reconcile TLS state
+    Certs->>K8s: Create or validate TLS material
+    K8s-->>Bootstrap: Render config and bootstrap prerequisites
+    Bootstrap->>K8s: Apply ConfigMaps, seal prerequisites, and startup config
+    K8s-->>Networking: Reconcile service and network surfaces
+    Networking->>K8s: Apply Services, Ingress or Gateway, and NetworkPolicy
+    K8s-->>Identity: Reconcile workload identity
+    Identity->>K8s: Apply ServiceAccount and RBAC
+    K8s-->>Workload: Reconcile workload state
+    Workload->>K8s: Render StatefulSet at replicas=1
+    Workload->>Pod0: Start first pod
+    Pod0-->>Init: Pod ready and API reachable
+    Init->>Pod0: Detect initialized or perform init
+    Init->>K8s: Set initialized status
+    Init->>Pod0: Configure autopilot defaults
+    K8s-->>Workload: Initialization confirmed
+    Workload->>K8s: Scale StatefulSet to spec.replicas
+  `}
+/>
+
+<DecisionTable
+  kind="decision"
+  title="Initialization paths"
+  columns={['Path', 'Best fit', 'What changes in the control plane']}
+  rows={[
+    {
+      cells: ['Self-init', 'Recommended when OpenBao supports native self-initialization and you want no root-token Secret in the cluster.', 'The workload renders self-init requests for pod-0, initialization is detected rather than performed by the operator, and status.selfInitialized becomes true.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Standard initialization', 'Use when self-init is not enabled or you need the operator to drive `/sys/init` directly.', 'The init manager performs the init call, stores the root token in a Secret, then marks status.initialized before scale-out.'],
+    },
+  ]}
+/>
+
+<Tabs groupId="day1-init-paths">
+  <TabItem value="self-init" label="Self-init">
+
+<Checklist
+  title="Self-init flow"
+  items={[
+    'Cert and bootstrap managers prepare TLS, seal, rendered config, and self-init requests before the first pod starts.',
+    'Networking and identity managers ensure the workload reaches the expected service and RBAC baseline before scale-out begins.',
+    'OpenBao initializes itself on first start and auto-revokes the transient root token instead of returning it to the operator.',
+    'The init manager detects successful initialization through service-registration labels or equivalent readiness signals and sets status.selfInitialized.',
+    'Once initialized, the workload manager scales to the requested replica count and later pods auto-unseal and join the Raft cluster.',
+  ]}
+/>
+
+<Callout type="note" title="Self-init changes root-token handling">
+
+Self-init requires an auto-unseal mechanism. In exchange, it avoids creating a root-token Secret and keeps bootstrap closer to OpenBao’s native startup path.
+
+</Callout>
+
+  </TabItem>
+  <TabItem value="standard" label="Standard init">
+
+<Checklist
+  title="Standard init flow"
+  items={[
+    'The bootstrap, networking, identity, and workload managers still force single-pod bootstrap and render TLS, storage, retry_join, and seal prerequisites first.',
+    'The init manager waits for pod-0 readiness, detects whether the cluster is already initialized, and calls `/v1/sys/init` only when needed.',
+    'The init response is handled in-memory, the root token is stored in `<cluster>-root-token`, and initialization status is patched back to the cluster.',
+    'After initialization and autopilot configuration complete, the workload manager scales the StatefulSet to the requested replica count.',
+  ]}
+/>
+
+<Callout type="warning" title="Static auto-unseal version requirement">
+
+Static auto-unseal requires OpenBao v2.4.0 or later. Older versions need a supported external KMS seal instead of the built-in static seal path.
+
+</Callout>
+
+  </TabItem>
+</Tabs>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Creation behavior']}
+  rows={[
+    {
+      cells: ['Split-brain at first boot', 'The cluster always starts with one replica so only one node can become the first Raft leader.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Root material handling', 'Standard init stores the root token in a Secret without logging the init response; self-init avoids creating the Secret entirely.'],
+    },
+    {
+      cells: ['Already initialized detection', 'The init manager skips the init call when service-registration labels or health prove the cluster is already initialized.'],
+    },
+    {
+      cells: ['Autopilot baseline', 'The init manager applies valid autopilot defaults before steady-state operations and later upgrades begin.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the lifecycle"
+  items={[
+    {
+      label: 'Day 2 operations',
+      description: 'Move from first boot into upgrades, maintenance, and the long-running operation model.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      label: 'Init manager',
+      description: 'Open the deep dive for the exact initialization, root-token, and autopilot contract.',
+      docId: 'architecture/init-manager',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Compare the internal creation flow with the operator-facing first-cluster guide.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/lifecycle/day2-operations.md b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day2-operations.md
new file mode 100644
index 000000000..0cffe3951
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/lifecycle/day2-operations.md
@@ -0,0 +1,200 @@
+---
+title: Day 2 Operations
+hide_title: true
+pageType: concept
+journey: architecture
+description: Operational lifecycle for upgrades, maintenance controls, and long-running admin operations after the cluster is live.
+---
+
+<PageHeader
+  title="Day 2 operations lifecycle"
+  lede="Day 2 starts once the cluster is initialized and the workload path is steady. From that point on, long-running operations such as upgrades and backups move through the admin operations path, while maintenance controls gate how much automation is allowed to continue during manual intervention."
+/>
+
+
+
+<JourneyRail
+  current={3}
+  title="Lifecycle phases"
+  items={[
+    {
+      label: 'Day 0 provisioning',
+      description: 'Prepare a namespace boundary and tenant-scoped policy before any cluster exists.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+    {
+      label: 'Day 1 creation',
+      description: 'Bootstrap the first node, initialize safely, and only then scale out.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      label: 'Day 2 operations',
+      description: 'Hand off into upgrades, maintenance, and long-running operational workflows.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      label: 'Backups and restore',
+      description: 'Protect data durability with scheduled snapshots and explicit restore requests.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+  ]}
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Starts with',
+      items: [
+        'an initialized cluster with steady-state workload reconciliation',
+        'version drift, backup schedules, or explicit maintenance requests',
+        'operation lifecycle coordination available for lock and retry management',
+      ],
+    },
+    {
+      label: 'Primary owners',
+      items: [
+        'adminops controller path',
+        'internal/service/upgrade',
+        'internal/service/backup and internal/service/opslifecycle',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        '`status.upgrade`, `status.blueGreen`, and operation-lock state',
+        'upgrade and backup executor Jobs plus green revision resources when needed',
+        'maintenance annotations or pause-driven no-op behavior depending on user intent',
+      ],
+    },
+    {
+      label: 'Hands off to',
+      items: [
+        'backup and restore flows once a cluster needs ongoing durability',
+        'troubleshooting and recovery guides when automation must pause',
+        'steady-state workload reconciliation after an operation completes',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Day 2 work is intentionally separated from the high-churn workload loop:
+
+1. Workload reconciliation continues to own the steady-state pod, Service, and config contract.
+2. Admin operations orchestration takes over when a change requires long-running coordination such as upgrade or backup.
+3. `internal/service/opslifecycle` keeps disruptive operations consistent around lock ownership, retry timing, and audit fields.
+
+That separation prevents upgrades, backups, and other long-running workflows from blocking normal workload repair.
+
+<DiagramFrame
+  title="Day 2 control-plane handoff"
+  caption="Once the cluster is live, disruptive operations route through the admin operations path instead of staying inside the high-churn workload controller."
+  code={`graph TD
+    Drift["Version drift or operation request"] --> AdminOps["AdminOps orchestration"]
+    AdminOps --> Upgrade["Upgrade manager"]
+    AdminOps --> Backup["Backup manager"]
+    Upgrade --> Lifecycle["Operation lifecycle"]
+    Backup --> Lifecycle
+    Lifecycle --> Lock["status.operationLock"]
+    Upgrade --> Status["Upgrade and blue-green status"]
+    Backup --> BackupStatus["status.backup"]
+    Workload["Workload reconcile loop"] --> Ready["Steady-state pod repair"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Drift,Workload read;
+    class AdminOps,Upgrade,Backup,Lifecycle process;
+    class Lock,Status,BackupStatus,Ready write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Day 2 operation families"
+  columns={['Operation family', 'Primary owner', 'Lifecycle role']}
+  rows={[
+    {
+      cells: ['Routine workload repair', 'Workload reconcile path.', 'Keeps StatefulSets, Services, ConfigMaps, and Secrets converged without entering the long-running adminops model.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Upgrade orchestration', 'Upgrade manager via adminops.', 'Handles version drift, strategy-specific state, and Raft-aware cutover logic.'],
+    },
+    {
+      cells: ['Backup scheduling', 'Backup manager via adminops.', 'Runs snapshot Jobs and updates backup status without moving data through the controller.'],
+    },
+    {
+      cells: ['Manual intervention gates', 'User-driven pause and maintenance settings.', 'Limit or reshape automation when an operator needs to intervene directly.'],
+    },
+  ]}
+/>
+
+<Tabs groupId="day2-upgrade-paths">
+  <TabItem value="rolling" label="Rolling upgrades">
+
+<Checklist
+  title="Rolling path"
+  items={[
+    'Version drift triggers pre-upgrade validation around semver, health, and optional snapshot prerequisites.',
+    'The upgrade manager uses StatefulSet partitioning and leader step-down to replace one pod at a time in reverse ordinal order.',
+    'Progress is preserved in status so a failed step can stop cleanly and later resume from an explicit retry request.',
+    'Completion updates currentVersion and clears the transient rolling-upgrade state once the workload fully converges.',
+  ]}
+/>
+
+  </TabItem>
+  <TabItem value="bluegreen" label="Blue-green upgrades">
+
+<Checklist
+  title="Blue-green path"
+  items={[
+    'A parallel green revision is created and joined as non-voters before any traffic cutover happens.',
+    'Promotion, demotion, cleanup, and rollback all move through explicit phases stored in status.',
+    'The Service selector changes only during cleanup, after a green leader is confirmed and blue peers are ready to leave.',
+    'If rollback safety breaks down late, the manager enters break-glass instead of continuing risky automation blindly.',
+  ]}
+/>
+
+  </TabItem>
+</Tabs>
+
+<DecisionTable
+  kind="reference"
+  title="Operational control surfaces"
+  columns={['Control', 'What it does', 'When to use it']}
+  rows={[
+    {
+      cells: ['`spec.paused=true`', 'Short-circuits reconcilers so the operator stops mutating managed resources for the cluster.', 'Use when you need manual intervention and want automation to stop entirely.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`spec.maintenance.enabled=true`', 'Keeps reconciliation running, but marks resources for controlled disruptive changes allowed by policy.', 'Use when the operator should continue known-safe automation during maintenance work.'],
+    },
+    {
+      cells: ['`spec.breakGlassAck`', 'Acknowledges an issued nonce before risky late-stage recovery automation can continue.', 'Use only after an operator has reviewed a break-glass condition and accepts the next step explicitly.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the lifecycle"
+  items={[
+    {
+      label: 'Backups and restore',
+      description: 'Move into the durability path that protects live clusters with snapshots and explicit restore requests.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+    {
+      label: 'Upgrade manager',
+      description: 'Open the deep dive for the exact rolling and blue-green orchestration contract.',
+      docId: 'architecture/upgrade-manager',
+    },
+    {
+      label: 'Operate docs',
+      description: 'Compare the internal Day 2 control-plane model with the operator-facing upgrade, maintenance, and troubleshooting guides.',
+      docId: 'user-guide/openbaocluster/operations/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/lifecycle/dayN-backups.md b/website/versioned_docs/version-0.3.0/architecture/lifecycle/dayN-backups.md
new file mode 100644
index 000000000..d28091fe3
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/lifecycle/dayN-backups.md
@@ -0,0 +1,176 @@
+---
+title: Day N Backups And Restore
+hide_title: true
+pageType: concept
+journey: architecture
+description: Backup and restore lifecycle for live clusters, including snapshot scheduling, status surfaces, retention, and explicit restore requests.
+---
+
+<PageHeader
+  title="Protect live clusters with scheduled snapshots and explicit restore requests."
+  lede="Once the cluster is running in production, durability becomes its own lifecycle. The backup manager schedules and records snapshot Jobs, the restore manager handles destructive restore requests through a separate CRD path, and both rely on shared operation-lock coordination so they do not collide with upgrades."
+/>
+
+
+
+<JourneyRail
+  current={4}
+  title="Lifecycle phases"
+  items={[
+    {
+      label: 'Day 0 provisioning',
+      description: 'Prepare a namespace boundary and tenant-scoped policy before any cluster exists.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+    {
+      label: 'Day 1 creation',
+      description: 'Bootstrap the first node, initialize safely, and only then scale out.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      label: 'Day 2 operations',
+      description: 'Hand off into upgrades, maintenance, and long-running operational workflows.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      label: 'Backups and restore',
+      description: 'Protect data durability with scheduled snapshots and explicit restore requests.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+  ]}
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Starts with',
+      items: [
+        'a live initialized cluster and an optional `spec.backup` schedule',
+        'object-storage configuration plus backup authentication',
+        'explicit `OpenBaoRestore` requests when destructive recovery is needed',
+      ],
+    },
+    {
+      label: 'Primary owners',
+      items: [
+        'internal/service/backup',
+        'internal/service/restore',
+        'internal/service/opslifecycle',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'backup executor Jobs and `status.backup` timing and failure state',
+        '`OpenBaoRestore` phase progression and cluster operation-lock ownership',
+        'retention cleanup after successful uploads and restore job launch/cleanup state',
+      ],
+    },
+    {
+      label: 'Hands off to',
+      items: [
+        'normal steady-state operation when backups succeed',
+        'post-restore follow-up when a restore request completes',
+        'operator-facing backup, restore, and recovery procedures',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Durability work is shared across two explicit operation surfaces:
+
+1. The backup manager lives on the adminops path and handles scheduled, manual, and pre-upgrade snapshot jobs.
+2. The restore manager runs through the dedicated `OpenBaoRestore` controller path so destructive recovery stays explicit and auditable.
+3. `internal/service/opslifecycle` supplies shared lock and retry behavior so backups, restores, and upgrades coordinate instead of colliding.
+
+That model keeps backup routine and restore exceptional, even though both exist in the same durability phase of the lifecycle.
+
+<DiagramFrame
+  title="Day N durability loop"
+  caption="Backups produce durable recovery points during live operation; restore consumes one of those recovery points through a separate request path when the cluster needs destructive recovery."
+  code={`graph TD
+    Schedule["Backup schedule or manual trigger"] --> Backup["Backup manager"]
+    Backup --> Job["Snapshot executor Job"]
+    Job --> Storage["Object storage"]
+    Job --> BackupStatus["status.backup"]
+    Storage --> RestoreReq["OpenBaoRestore request"]
+    RestoreReq --> Restore["Restore manager"]
+    Restore --> Lock["status.operationLock"]
+    Restore --> RestoreJob["Restore Job"]
+    RestoreJob --> Cluster["Cluster restored or follow-up required"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef critical fill:transparent,stroke:#dc2626,stroke-width:2px,color:#f8fafc;
+
+    class Schedule,RestoreReq read;
+    class Backup,Job,Restore,RestoreJob process;
+    class Storage,BackupStatus,Lock write;
+    class Cluster critical;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Durability surfaces"
+  columns={['Surface', 'Primary owner', 'Purpose']}
+  rows={[
+    {
+      cells: ['`spec.backup`', 'Backup manager consumes it.', 'Declares schedule, provider target, auth wiring, and retention policy for routine snapshots.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`status.backup`', 'Backup manager writes it.', 'Records last attempt, next schedule, last success, and consecutive failures so durability is visible without inspecting Jobs.'],
+    },
+    {
+      cells: ['`OpenBaoRestore`', 'Restore manager consumes and updates it.', 'Keeps restore explicit, immutable, and auditable instead of hiding destructive recovery inside cluster status.'],
+    },
+    {
+      cells: ['`status.operationLock`', 'Shared via opslifecycle.', 'Blocks conflicting upgrade, backup, or restore work while one disruptive operation is in flight.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Durability behavior']}
+  rows={[
+    {
+      cells: ['Backup during disruptive work', 'Scheduled backups do not start while upgrades or restore are already active on the same cluster.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Authentication surface', 'Backup and restore use dedicated auth wiring such as JWT roles or explicit token references; root tokens are not the durability mechanism.'],
+    },
+    {
+      cells: ['Restore visibility', 'Restore is modeled as a separate CRD-backed request so destructive recovery has its own audit trail and phase status.'],
+    },
+    {
+      cells: ['Retention timing', 'Retention cleanup runs only after a successful backup so older recovery points are not removed before a new one exists.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related durability pages"
+  items={[
+    {
+      label: 'Backup manager',
+      description: 'Open the deep dive for scheduled backup execution, status, and retention details.',
+      docId: 'architecture/backup-manager',
+    },
+    {
+      label: 'Restore manager',
+      description: 'Open the deep dive for explicit restore requests, lock ownership, and destructive workflow handling.',
+      docId: 'architecture/restore-manager',
+    },
+    {
+      label: 'Restore guide',
+      description: 'Compare the internal durability model with the operator-facing restore and recovery procedures.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/lifecycle/index.md b/website/versioned_docs/version-0.3.0/architecture/lifecycle/index.md
new file mode 100644
index 000000000..9af5698e2
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/lifecycle/index.md
@@ -0,0 +1,79 @@
+---
+title: Lifecycle Architecture
+hide_title: true
+pageType: landing
+journey: architecture
+description: Lifecycle overview for OpenBao Operator from Day 0 provisioning through Day 1 creation, Day 2 operations, and backup-and-restore flows.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Architecture / Lifecycle"
+  title="Lifecycle architecture"
+  lede="Operator lifecycle flows from the controller and manager perspective, covering Day 0 provisioning, Day 1 creation, Day 2 operations, and backup-and-restore behavior."
+  actions={[
+    {label: 'Start with Day 0 provisioning', docId: 'architecture/lifecycle/day0-provisioning', variant: 'primary'},
+    {label: 'Open Day 2 operations', docId: 'architecture/lifecycle/day2-operations', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Lifecycle pages show"
+    items={[
+      'which controller and manager own each phase',
+      'where security and tenant boundaries enter the lifecycle',
+      'how upgrades, backups, and restore fit into day 2 behavior',
+      'how the internal lifecycle maps back to the user-facing docs',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Lifecycle flows"
+  items={[
+    {
+      eyebrow: '00',
+      title: 'Day 0 provisioning',
+      description: 'Tenant onboarding, namespace creation, RBAC delegation, and the provisioner boundary before a cluster exists.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+    {
+      eyebrow: '01',
+      title: 'Day 1 creation',
+      description: 'Cluster initialization, PKI bootstrapping, and the early readiness path for a new OpenBaoCluster.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+    {
+      eyebrow: '02',
+      title: 'Day 2 operations',
+      description: 'Upgrade strategies, maintenance mode, and the internal flow behind normal production operations.',
+      docId: 'architecture/lifecycle/day2-operations',
+    },
+    {
+      eyebrow: 'N',
+      title: 'Backups and restore',
+      description: 'Snapshot scheduling, restore dependencies, and the backup-driven durability path after the cluster is live.',
+      docId: 'architecture/lifecycle/dayN-backups',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related architecture pages"
+  items={[
+    {
+      label: 'Component design',
+      description: 'Start with the control-plane split when you need the static system boundaries behind these lifecycle flows.',
+      docId: 'architecture/components',
+    },
+    {
+      label: 'Operation lifecycle coordination',
+      description: 'See how upgrade, backup, and restore managers share the same lock and retry model.',
+      docId: 'architecture/operation-lifecycle',
+    },
+    {
+      label: 'Open Operate',
+      description: 'Compare the internal lifecycle model with the user-facing operating guides for upgrades, backups, and restore.',
+      docId: 'user-guide/openbaocluster/operations/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/operation-lifecycle.md b/website/versioned_docs/version-0.3.0/architecture/operation-lifecycle.md
new file mode 100644
index 000000000..4505ff4f3
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/operation-lifecycle.md
@@ -0,0 +1,196 @@
+---
+title: Operation Lifecycle Coordination
+hide_title: true
+pageType: concept
+journey: architecture
+description: Shared lock, retry, and phase-audit primitives used by backup, restore, and upgrade managers.
+---
+
+<PageHeader
+  title="Operation lifecycle coordination"
+  lede="`internal/service/opslifecycle` is the shared service-layer contract behind backup, restore, and upgrade orchestration. It does not own a controller or CRD of its own. Instead, it keeps operation lock identity, retry timing, and phase audit logging consistent whenever a manager needs to take disruptive action against a cluster."
+/>
+
+
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Used by',
+      items: [
+        'internal/service/backup',
+        'internal/service/restore',
+        'internal/service/upgrade',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'operation-lock identity helpers for disruptive work',
+        'retry intent classes and default requeue mapping',
+        'phase-transition audit field normalization',
+      ],
+    },
+    {
+      label: 'Writes through',
+      items: [
+        'internal/service/opslifecycle for status.operationLock updates',
+        'audit event fields for phase transitions',
+        'shared retry delays consumed by controller requeues',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'OpenBaoCluster.status.operationLock as the persisted mutex surface',
+        'controller requeue behavior for long-running progress polling',
+        'manager-specific phase names and audit metadata',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Operation lifecycle coordination sits below the concrete managers and owns the shared lock write path:
+
+1. A manager such as backup, restore, or upgrade decides it needs to start or resume work.
+2. It uses `internal/service/opslifecycle` to acquire or release the expected lock identity, classify retry intent, and log phase changes.
+3. `opslifecycle` applies `status.operationLock` directly through the shared SSA lock plane.
+
+That keeps the shared safety model in one place instead of scattering lock and retry semantics across several managers.
+
+<DecisionTable
+  kind="reference"
+  title="OpenBaoCluster status ownership planes"
+  columns={['Plane', 'Field manager', 'Owned status fields']}
+  rows={[
+    {
+      cells: ['Observed status', '`openbao-status-controller`', '`status.observedGeneration`, `status.phase`, `status.activeLeader`, `status.readyReplicas`, `status.currentVersion`, `status.lastBackupTime`, `status.conditions`'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Workload status', '`openbao-workload-controller`', '`status.initialized`, `status.selfInitialized`, `status.workload`'],
+    },
+    {
+      cells: ['AdminOps status', '`openbao-adminops-controller`', '`status.upgrade`, `status.upgradeRequests`, `status.backup`, `status.blueGreen`, `status.breakGlass`, `status.adminOps`'],
+    },
+    {
+      cells: ['Operation lock status', '`openbao-operationlock-controller`', '`status.operationLock`'],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Coordination model"
+  caption="Backup, restore, and upgrade do not each implement their own lock and retry policy. They share one coordination service that owns the lock write path and keeps audit fields consistent."
+  code={`graph TD
+    Backup["Backup manager"] --> Ops["Operation lifecycle"]
+    Restore["Restore manager"] --> Ops
+    Upgrade["Upgrade manager"] --> Ops
+    Ops --> Lock["Operation lock status writer"]
+    Ops --> Retry["Retry classes"]
+    Ops --> Audit["Phase audit logging"]
+    Lock --> Status["OpenBaoCluster.status.operationLock"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Backup,Restore,Upgrade read;
+    class Ops,Retry,Audit process;
+    class Lock process;
+    class Status write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Shared primitives"
+  columns={['Primitive', 'What it standardizes', 'Why it exists']}
+  rows={[
+    {
+      cells: ['OperationLock', 'A stable holder + operation identity for a long-running action.', 'Managers need an exact lock identity so renew and release only succeed for the intended owner.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Acquire / Release', 'Status-based lock ownership via the adapter with a fresh read-before-write gateway.', 'Controllers should not each patch status.operationLock differently, rely on stale cached objects, or invent different lock messages.'],
+    },
+    {
+      cells: ['IsLockHeld / HeldError / AddHeldAuditFields', 'A shared way to classify contention and enrich audit events with who currently owns the lock.', 'Contention should produce consistent diagnostics instead of manager-specific strings.'],
+    },
+    {
+      cells: ['LogPhaseTransition', 'Stable phase_from / phase_to audit fields for long-running operations.', 'Audit streams stay comparable across backup, restore, and upgrade.'],
+    },
+  ]}
+/>
+
+## Retry and lock model
+
+<DecisionTable
+  kind="reference"
+  title="Retry classes"
+  columns={['Retry class', 'Default delay', 'Typical use']}
+  rows={[
+    {
+      cells: ['lock-contention', '`5s`', 'Another disruptive operation already owns the cluster lock, so the manager should requeue quickly and check again.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['progress-poll', '`5s`', 'A Job or long-running operation is still in progress and the manager is waiting for the next observable state change.'],
+    },
+    {
+      cells: ['standard', '`1m` by default, overridable with `OPENBAO_REQUEUE_STANDARD`', 'Background retry work that does not need tight polling.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Lock contract"
+  columns={['Concern', 'Shared behavior']}
+  rows={[
+    {
+      cells: ['Acquire vs renew', 'If the exact holder and operation already own the lock, acquisition renews the same lock instead of treating it as contention.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Exact-match release', 'Release succeeds only when holder and operation match the active lock, so one manager cannot accidentally clear another manager’s ownership.'],
+    },
+    {
+      cells: ['Legacy takeover', 'The adapter only forces ownership when a clear or explicit override hits an SSA ownership conflict, so normal lock renewals stay non-destructive.'],
+    },
+    {
+      cells: ['Force override', 'Force semantics exist for explicit override paths only; normal long-running operations should not silently steal the lock.'],
+    },
+    {
+      cells: ['Contention diagnostics', 'HeldError exposes the current operation and holder so audit events and logs can explain why a manager requeued.'],
+    },
+  ]}
+/>
+
+<Callout type="note" title="This is coordination, not orchestration">
+
+`opslifecycle` does not decide whether an upgrade should roll or blue-green, whether a restore request is valid, or whether a backup target is reachable. It only standardizes the lock, retry, and audit mechanics around those domain decisions.
+
+</Callout>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Upgrade manager',
+      description: 'See how rolling and blue-green orchestration use shared lock and retry primitives during long-running transitions.',
+      docId: 'architecture/upgrade-manager',
+    },
+    {
+      label: 'Backup manager',
+      description: 'See how scheduled and manual snapshot flows reuse the same contention and requeue model.',
+      docId: 'architecture/backup-manager',
+    },
+    {
+      label: 'Restore manager',
+      description: 'See how destructive restore requests rely on the same lock identity and audit mechanics.',
+      docId: 'architecture/restore-manager',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/operator-invariants.md b/website/versioned_docs/version-0.3.0/architecture/operator-invariants.md
new file mode 100644
index 000000000..b66439400
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/operator-invariants.md
@@ -0,0 +1,247 @@
+---
+title: Operator Invariants
+description: Cross-cutting invariants preserved by OpenBao Operator across identity boundaries, production posture, configuration ownership, and lifecycle safety.
+hide_title: true
+pageType: concept
+journey: architecture
+---
+
+<PageHeader
+  title="Operator invariants"
+  lede="Cross-cutting contracts behind the rest of the architecture. They explain why some designs are split, which shortcuts are blocked, and which safety properties must survive refactors, new features, and operational changes."
+/>
+
+
+
+<Callout type="note" title="Lifecycle contract">
+
+`OpenBaoCluster` is an operator-owned lifecycle contract. It is not a generic import API for arbitrary unmanaged OpenBao clusters.
+
+</Callout>
+
+<DecisionTable
+  title="Invariant families"
+  columns={['Family', 'What the operator is trying to preserve', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Identity boundaries',
+        'Provisioning, control-plane, and workload trust boundaries stay explicit and mutation-locked.',
+        'This keeps privileged access narrow and prevents tenant onboarding or operator RBAC from drifting into normal reconcile paths.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Production posture',
+        'Hardened production means self-init, trusted TLS, and a non-static unseal path.',
+        'Production safety is part of the supported operating contract.',
+      ],
+    },
+    {
+      cells: [
+        'Integration assumptions',
+        'External dependencies surface as explicit status and readiness conditions.',
+        'This makes environment assumptions visible before they become runtime failures.',
+      ],
+    },
+    {
+      cells: [
+        'Lifecycle safety',
+        'Disruptive workflows stay explicit, lock-aware, and separated from steady-state workload reconciliation.',
+        'This prevents upgrades, backups, and restores from colliding or becoming invisible side effects.',
+      ],
+    },
+  ]}
+/>
+
+## Identity boundary invariants
+
+<DecisionTable
+  kind="reference"
+  title="Identity and access"
+  columns={['Invariant', 'Why it exists', 'Primary enforcement']}
+  rows={[
+    {
+      cells: [
+        'Provisioner and controller identities stay separate.',
+        'A long-running workload identity should not both mint and consume tenant access.',
+        'Split ServiceAccounts, RBAC boundaries, and admission policies.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Rendered operator identities stay internally consistent and mutation-locked.',
+        'Install drift in ServiceAccounts, RoleBindings, and admission subjects weakens the control-plane trust model.',
+        'Helm/raw-manifest rendering, managed-resource locks, and break-glass allowlists.',
+      ],
+    },
+    {
+      cells: [
+        'Tenant namespace access is introduced explicitly and remains provisioner-owned.',
+        'Tenant onboarding should be deliberate, not discovered passively by a broad controller identity.',
+        '`OpenBaoTenant` onboarding flow, tenant governance policy, and controller RBAC exclusions.',
+      ],
+    },
+    {
+      cells: [
+        'Secret access stays name-scoped and non-enumerating.',
+        'The operator needs to create or read specific secrets without gaining broad tenant secret visibility.',
+        'Allowlisted Secret roles, blind-create patterns, and admission restrictions on managed Secret writes.',
+      ],
+    },
+    {
+      cells: [
+        'Admission enforcement remains part of the normal safety model.',
+        'Guardrails should fail early at the API boundary, and loss of those guardrails should pause sensitive reconciliation.',
+        'Validating admission policy inventory, runtime admission tracking, and degraded conditions.',
+      ],
+    },
+  ]}
+/>
+
+Related reading: <SiteLink docId="security/infrastructure/rbac">RBAC Architecture</SiteLink>, <SiteLink docId="security/infrastructure/admission-policies">Admission Policies</SiteLink>, and <SiteLink docId="user-guide/operator/identity-and-access">Operator Identity and Access</SiteLink>.
+
+## Production posture invariants
+
+<DecisionTable
+  kind="reference"
+  title="Production posture"
+  columns={['Invariant', 'Why it exists', 'Primary enforcement']}
+  rows={[
+    {
+      cells: [
+        'Hardened production requires self-init, trusted TLS, and a non-static unseal path.',
+        'This prevents root token Secret persistence and weak bootstrap or transport defaults in production.',
+        'Cluster validation, the `ProductionReady` condition, and hardened-profile checks.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`OperatorManaged` TLS is not a hardened production path.',
+        'Production trust should align with externally managed or OpenBao-native certificate models.',
+        'Admission validation and `ProductionReady=False` when an unsupported TLS mode is selected.',
+      ],
+    },
+    {
+      cells: [
+        'Self-init is the supported production bootstrap path.',
+        'Production bootstrap should stay declarative and avoid persisting the initial root token.',
+        'Self-init validation, hardened profile requirements, and production posture evaluation.',
+      ],
+    },
+    {
+      cells: [
+        'Operator-owned configuration stays operator-owned.',
+        'Networking, storage, seal settings, and listener identity need a single ownership model to stay correct.',
+        'Rendered configuration ownership and admission policy enforcement.',
+      ],
+    },
+  ]}
+/>
+
+Related reading: <SiteLink docId="security/fundamentals/profiles">Security Profiles</SiteLink>, <SiteLink docId="security/workload/tls">TLS and Identity</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/configuration/self-init">Self-Initialization</SiteLink>.
+
+## Integration invariants
+
+<DecisionTable
+  kind="reference"
+  title="External dependencies and readiness"
+  columns={['Invariant', 'Why it exists', 'Primary enforcement']}
+  rows={[
+    {
+      cells: [
+        'Gateway, ACME, audit storage, and API-server assumptions surface as explicit conditions.',
+        'Environment and controller dependencies should become visible status contracts before they become runtime failures.',
+        '`GatewayIntegrationReady`, `ACMEIntegrationReady`, `ACMECacheReady`, `AuditFileStorageReady`, and `APIServerNetworkReady` conditions.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Audit file storage stays an explicit integration point.',
+        'The operator can mount and validate the handoff PVC, but retention, tamper resistance, and collection pipelines belong to the surrounding platform.',
+        '`spec.auditFileStorage`, `spec.audit`, status readiness, and workload mount guardrails.',
+      ],
+    },
+    {
+      cells: [
+        'Backup and restore identity stays separate from the main workload identity.',
+        'Day-2 Jobs should not silently inherit the wrong auth path, cloud permissions, or egress assumptions from the StatefulSet.',
+        'Dedicated job identities, readiness evaluation, and explicit backup/restore status reasons.',
+      ],
+    },
+  ]}
+/>
+
+Related reading: <SiteLink docId="reference/status-and-events">Status and Events</SiteLink>, <SiteLink docId="user-guide/openbaocluster/configuration/observability">Observability</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/operations/backups">Configure Backups</SiteLink>.
+
+## Lifecycle safety invariants
+
+<DecisionTable
+  kind="reference"
+  title="Disruptive operation safety"
+  columns={['Invariant', 'Why it exists', 'Primary enforcement']}
+  rows={[
+    {
+      cells: [
+        'Only one disruptive operation owns the cluster operation lock at a time.',
+        'Upgrades, backups, and restores should not collide on the same cluster.',
+        '`status.operationLock`, shared lifecycle coordination, and manager-specific lock handling.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Restore remains destructive, explicit, and lock-aware.',
+        'Restore should never be mistaken for a routine reconcile side effect.',
+        '`OpenBaoRestore`, restore validation, override-lock handling, and operation-lock checks.',
+      ],
+    },
+    {
+      cells: [
+        'Break-glass access stays explicit and narrow.',
+        'Administrative escape hatches should exist without turning privileged mutation into the normal operating model.',
+        'Configured maintenance groups, admission exceptions, and recovery runbooks.',
+      ],
+    },
+    {
+      cells: [
+        'OpenBao remains the source of truth for data consistency and snapshot semantics.',
+        'The operator should orchestrate and guard the lifecycle, not reimplement the data plane.',
+        'Supervisor pattern, API-driven backup/restore flows, and OpenBao-led snapshot semantics.',
+      ],
+    },
+  ]}
+/>
+
+Related reading: <SiteLink docId="architecture/operation-lifecycle">Operation Lifecycle</SiteLink>, <SiteLink docId="user-guide/openbaorestore/restore">Restore from Backup</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/recovery/index">Recovery and Restore</SiteLink>.
+
+<Callout type="tip" title="Invariant changes affect the contract">
+
+If a change weakens one of these invariants, update the related architecture, security, and user-guide pages in the same change set. It changes the product operating contract.
+
+</Callout>
+
+<NextActions
+  title="Continue through the architecture"
+  items={[
+    {
+      label: 'Component design',
+      description: 'Where controllers, app facades, and managers split responsibilities to preserve these invariants.',
+      docId: 'architecture/components',
+    },
+    {
+      label: 'Operation lifecycle',
+      description: 'Shared lifecycle coordination for upgrades, backups, and restores.',
+      docId: 'architecture/operation-lifecycle',
+    },
+    {
+      label: 'Security overview',
+      description: 'User-facing security model behind these invariants.',
+      docId: 'security/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/provisioner-manager.md b/website/versioned_docs/version-0.3.0/architecture/provisioner-manager.md
new file mode 100644
index 000000000..612b34650
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/provisioner-manager.md
@@ -0,0 +1,174 @@
+---
+title: Provisioner Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Provision tenant namespaces with scoped RBAC, Secret allowlists, Pod Security label ownership, and quota defaults for OpenBaoTenant.
+---
+
+<PageHeader
+  title="Provision tenant namespaces with scoped RBAC, Secret allowlists, and policy defaults."
+  lede="The provisioner manager owns the tenant-onboarding contract for `OpenBaoTenant`. It creates namespace-scoped permissions for the operator, applies quota defaults, applies Pod Security labels when configured to own them, and keeps Secret access narrowed to explicit allowlists derived from managed clusters."
+/>
+
+
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'dedicated OpenBaoTenant controller',
+        'internal/app/provisioner',
+        'internal/service/provisioner',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'tenant-scoped operator Role and RoleBinding resources',
+        'reader and writer Secret allowlists derived from tenant clusters',
+        'Pod Security labels when configured plus optional ResourceQuota and LimitRange defaults',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'tenant Role / RoleBinding and Secret RBAC resources',
+        'namespace labels that enforce Pod Security defaults unless platform policy owns them',
+        'ResourceQuota and LimitRange resources from OpenBaoTenant.spec',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'OpenBaoTenant namespace targeting rules and resource policies',
+        'admission dependencies before tenant Secret RBAC sync can proceed',
+        'current OpenBaoCluster objects that still exist in the tenant namespace',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Provisioning follows a dedicated tenant-controller path:
+
+1. `internal/controller/provisioner` receives the reconcile event for `OpenBaoTenant`.
+2. The controller delegates orchestration to `internal/app/provisioner`.
+3. The app layer invokes `internal/service/provisioner` to apply RBAC, labels, allowlists, and cleanup behavior.
+
+That keeps tenant onboarding separate from `OpenBaoCluster` steady-state reconciliation while still using the same design system and policy language.
+
+The tenant `RoleBinding` is also the explicit handoff marker into the cluster controllers. Until that object exists, `OpenBaoCluster` workload, admin-operations, and status reconciliation pause and requeue instead of trying to mutate resources in a namespace that is not yet provisioned.
+
+<DecisionTable
+  kind="reference"
+  title="Owned surfaces"
+  columns={['Surface', 'What the manager decides', 'Why it matters']}
+  rows={[
+    {
+      cells: ['Tenant RBAC', 'The operator ServiceAccount permissions granted in the tenant namespace.', 'The operator needs enough access to manage clusters there, but not broad namespace-level privileges by default.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Secret allowlists', 'Which Secrets the operator may read or write for managed clusters in the tenant namespace.', 'Multi-tenant safety depends on explicit Secret access instead of wildcard RBAC.'],
+    },
+    {
+      cells: ['Controller handoff', 'When the tenant namespace is actually ready for `OpenBaoCluster` reconciliation.', 'GitOps paths can submit tenant and cluster objects together only if the controller has a deterministic, namespace-scoped readiness marker.'],
+    },
+    {
+      cells: ['Pod Security labels', 'The baseline namespace policy applied to tenant workloads and operator-managed pods when the chart is in enforce mode.', 'Tenants need a secure default even before any cluster objects are created, whether owned by the Provisioner or by platform policy.'],
+    },
+    {
+      cells: ['Quota defaults', 'Optional ResourceQuota and LimitRange resources derived from OpenBaoTenant.spec.', 'Tenants need resource guardrails that travel with the namespace onboarding contract.'],
+    },
+  ]}
+/>
+
+## Provisioning flow
+
+<DiagramFrame
+  title="Tenant onboarding flow"
+  caption="Provisioning applies namespace-scoped guardrails first, then keeps Secret allowlists synchronized as managed clusters appear or disappear in the tenant namespace. Pod Security labels can be owned by the Provisioner or by platform policy."
+  code={`graph TD
+    Tenant["OpenBaoTenant"] --> Ctrl["Provisioner controller"]
+    Ctrl --> App["internal/app/provisioner"]
+    App --> Manager["Provisioner manager"]
+    Manager --> RBAC["Tenant Role / RoleBinding"]
+    Manager --> Secrets["Reader / writer Secret allowlists"]
+    Manager -. enforce mode .-> Labels["Pod Security labels"]
+    Manager --> Quotas["ResourceQuota / LimitRange"]
+    Quotas --> Ready["Tenant namespace ready for OpenBaoCluster"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Tenant read;
+    class Ctrl,App,Manager process;
+    class RBAC,Secrets,Labels,Quotas,Ready write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Security guardrails"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['Namespace targeting', 'Self-service tenants may target only their own namespace; cross-namespace provisioning is reserved for trusted operator-managed cases.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Admission dependencies', 'Tenant Secret allowlists wait for admission-policy dependencies so Secret access is not widened before enforcement is ready.'],
+    },
+    {
+      cells: ['Cluster-controller handoff', 'The tenant `RoleBinding` is the readiness marker that allows `OpenBaoCluster` reconciliation to proceed in multi-tenant mode.'],
+    },
+    {
+      cells: ['Shared RBAC lifecycle', 'Provisioned tenant RBAC avoids OwnerReferences that would let a single cluster deletion garbage-collect shared namespace permissions.'],
+    },
+    {
+      cells: ['Secret scope', 'Reader and writer Secret Roles are derived from explicit cluster references instead of wildcard list or get access to every Secret in the namespace.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Deletion lifecycle"
+  columns={['Phase', 'Manager intent']}
+  rows={[
+    {
+      cells: ['Tenant marked for deletion', 'Keep provisioned RBAC in place while managed clusters still exist in the namespace.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Namespace emptied of managed clusters', 'Remove provisioned Role, RoleBinding, Secret allowlist roles, and default quota resources.'],
+    },
+    {
+      cells: ['Finalizer removal', 'Only remove the tenant finalizer after namespace-scoped provisioning artifacts are cleaned up.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Tenant onboarding guide',
+      description: 'Compare the internal provisioning contract with the user-facing onboarding sequence for OpenBaoTenant.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Admission policies',
+      description: 'See why tenant Secret allowlists wait for infrastructure policy dependencies before broadening access.',
+      docId: 'security/infrastructure/admission-policies',
+    },
+    {
+      label: 'Day 0 lifecycle flow',
+      description: 'Follow where tenant provisioning sits before cluster creation begins.',
+      docId: 'architecture/lifecycle/day0-provisioning',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/restore-manager.md b/website/versioned_docs/version-0.3.0/architecture/restore-manager.md
new file mode 100644
index 000000000..590892f02
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/restore-manager.md
@@ -0,0 +1,176 @@
+---
+title: Restore Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Reconcile OpenBaoRestore requests, acquire operation locks, and orchestrate restore jobs as explicit destructive workflows.
+---
+
+<PageHeader
+  title="Restore manager workflow"
+  lede="Restore requests run outside normal cluster reconciliation. The manager models restore as an immutable CRD-backed request, coordinates execution through a dedicated controller path, and protects the cluster with explicit validation and lock ownership."
+/>
+
+
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'dedicated openbaorestore controller',
+        'internal/app/openbaorestore',
+        'internal/service/restore',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'restore request validation',
+        'operation lock lifecycle for restore',
+        'restore job creation and terminal cleanup',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'OpenBaoRestore phase progression',
+        'OpenBaoCluster.status.operationLock for restore ownership',
+        'restore job launch and cleanup state',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'snapshot source accessibility',
+        'restore authentication and token strategy',
+        'backup provider configuration and cluster lock state',
+      ],
+    },
+  ]}
+/>
+
+## Request model
+
+<DecisionTable
+  kind="reference"
+  title="Restore request contract"
+  columns={['Contract', 'Why it exists']}
+  rows={[
+    {
+      cells: ['CRD-based request', 'Restore is visible, declarative, and auditable instead of being hidden inside OpenBaoCluster status or imperative scripts.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Immutable spec', 'Changing restore inputs requires a new request so the audit trail and execution intent stay stable.'],
+    },
+    {
+      cells: ['Stateless controller', 'The controller polls the restore job rather than depending on broad watch permissions across every child object.'],
+    },
+    {
+      cells: ['Operation lock ownership', 'Restore must block upgrades and backups while destructive data-plane changes are in flight.'],
+    },
+  ]}
+/>
+
+## Restore lifecycle
+
+<DiagramFrame
+  title="Restore lifecycle"
+  caption="Restore validates first, acquires the cluster lock second, and only then launches a restore job. Terminal phases keep retrying lock cleanup until the cluster is no longer marked as restore-owned."
+  code={`graph TD
+    Start["OpenBaoRestore created"] --> Pending["Pending"]
+    Pending --> Validate{"Validate request"}
+    Validate --> Failed["Failed"]
+    Validate --> Lock{"Acquire restore lock"}
+    Lock --> Pending
+    Lock --> Running["Running"]
+    Running --> Job["Launch restore job"]
+    Job --> Pull["Pull snapshot"]
+    Pull --> Apply["Restore to OpenBao"]
+    Apply --> Completed["Completed"]
+    Apply --> Retry{"Retry?"}
+    Retry --> Job
+    Retry --> Failed
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef critical fill:transparent,stroke:#dc2626,stroke-width:2px,color:#f8fafc;
+
+    class Start read;
+    class Pending,Validate,Lock,Running,Job,Pull,Retry process;
+    class Completed write;
+    class Failed,Apply critical;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Restore phases"
+  columns={['Phase', 'Manager intent']}
+  rows={[
+    {
+      cells: ['Pending / Validating', 'Reject invalid target clusters, inaccessible snapshots, missing auth, and unsafe conflicting operations before anything destructive starts.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Running', 'Launch the restore job after the restore lock is owned and the request is known-good.'],
+    },
+    {
+      cells: ['Completed', 'Release the lock and preserve the restore record as the audit trail of what happened.'],
+    },
+    {
+      cells: ['Failed', 'Expose terminal failure while continuing lock cleanup on later reconciles until the cluster is no longer marked as restore-owned.'],
+    },
+  ]}
+/>
+
+## Safety boundaries
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['Conflicting operations', 'Backups and upgrades are blocked by the restore operation lock while restore is active.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Emergency override', 'Override requires explicit force semantics rather than silently ignoring a stuck or conflicting lock.'],
+    },
+    {
+      cells: ['Execution surface', 'The controller delegates the destructive work to a job instead of embedding restore logic in normal reconcile loops.'],
+    },
+    {
+      cells: ['After restore', 'The manager may leave the cluster requiring unseal or follow-up recovery work; completion only means the restore workflow finished.'],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Restore workflow scope">
+
+Restore is intentionally modeled outside the normal `OpenBaoCluster` lifecycle. The operator treats it as a destructive recovery operation with its own request object, its own controller path, and its own lock semantics.
+
+</Callout>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Backup manager',
+      description: 'Restore depends on the snapshot and object-storage path owned by the backup manager.',
+      docId: 'architecture/backup-manager',
+    },
+    {
+      label: 'Operation lifecycle coordination',
+      description: 'Lock and retry primitives shared with other disruptive operations.',
+      docId: 'architecture/operation-lifecycle',
+    },
+    {
+      label: 'Restore guide',
+      description: 'User-facing restore and recovery procedures.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/upgrade-manager.md b/website/versioned_docs/version-0.3.0/architecture/upgrade-manager.md
new file mode 100644
index 000000000..868c57e09
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/upgrade-manager.md
@@ -0,0 +1,261 @@
+---
+title: Upgrade Manager
+hide_title: true
+pageType: concept
+journey: architecture
+description: Orchestrate rolling and blue-green upgrades, status-backed resumability, rollback safety, and Raft-aware rollout behavior.
+---
+
+<PageHeader
+  title="Upgrade orchestration and safety model"
+  lede="The upgrade manager handles disruptive version changes. It keeps upgrade orchestration out of the workload loop, persists state in status so upgrades survive controller restarts, and prioritizes cluster availability during rollout."
+/>
+
+
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'adminops reconciler',
+        'internal/app/openbaocluster/adminops',
+        'internal/service/upgrade/rolling and internal/service/upgrade/bluegreen',
+        'shared seams in internal/service/upgrade/core, snapshot, and raftops',
+      ],
+    },
+    {
+      label: 'Owns',
+      items: [
+        'strategy-specific rolling and blue-green phase orchestration',
+        'shared lock, status, metrics, and root-lifecycle mechanics',
+        'upgrade executor jobs, snapshot prerequisites, and Raft coordination',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'status.upgrade, status.blueGreen, and status.breakGlass through shared status helpers',
+        'partition changes, green revision resources, and executor jobs',
+        'break-glass and failure state when rollback safety is compromised',
+      ],
+    },
+    {
+      label: 'Depends on',
+      items: [
+        'target version policy and image alignment',
+        'backup readiness and network egress for snapshot prerequisites',
+        'shared configuration rendering semantics for green revision startup config',
+        'operation lifecycle coordination for lock, retry, and phase timing',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+Upgrade execution belongs to the AdminOps orchestration path:
+
+1. `internal/controller/openbaocluster` receives an adminops reconcile event.
+2. The controller delegates to `internal/app/openbaocluster`.
+3. AdminOps orchestration invokes either the rolling or blue-green upgrade manager flow.
+4. Strategy packages delegate shared mechanics to `internal/service/upgrade/core`,
+   `internal/service/upgrade/snapshot`, `internal/service/upgrade/raftops`, and
+   `internal/platform/statusapply`.
+
+That keeps upgrade state machines out of the workload loop and lets long-running transitions own their own retry model.
+
+## Package shape
+
+The upgrade subsystem is split so strategy packages keep workflow ownership while
+shared mechanics live behind narrower seams:
+
+- `internal/service/upgrade` keeps root helpers that are shared by both
+  strategies but are not strategy-specific or executor-specific, such as
+  request parsing, version and image policy, shared metrics types, pod client
+  helpers, and root lifecycle helpers.
+- `internal/service/upgrade/rolling` owns the rolling state machine: partition
+  progression, leader step-down sequencing, per-pod rollout, convergence, and
+  rolling-specific retry/failure handling.
+- `internal/service/upgrade/bluegreen` owns the blue-green phase machine:
+  green deployment, sync/promotion/cutover, rollback, and break-glass handling.
+- `internal/service/upgrade/core` owns shared lifecycle mechanics used by
+  strategy code, including upgrade locks, common status mutators, metrics
+  session bookkeeping, and blue-green status/state helpers that are not tied to
+  a single phase.
+- `internal/service/upgrade/snapshot` owns shared pre-upgrade snapshot
+  preparation: prerequisite validation, runtime bootstrap, Job state modeling,
+  and common existing-Job result handling.
+- `internal/service/upgrade/raftops` owns executor-side Raft and OpenBao
+  coordination such as leader discovery, leader transfer, peer
+  join/promote/demote/remove, and autopilot capability fallback.
+- `internal/service/configuration` owns shared `config.hcl` rendering
+  semantics so bootstrap and blue-green startup paths do not fork the config
+  contract.
+- `internal/platform/statusapply` owns the shared AdminOps status apply and
+  mutate+apply gateways so upgrade, backup, and adminops flows use the same
+  status-subresource ownership rules and field-manager boundaries.
+
+<DecisionTable
+  kind="decision"
+  title="Strategy selection"
+  columns={['Strategy', 'Best fit', 'Primary tradeoff']}
+  rows={[
+    {
+      cells: ['Rolling update', 'Default upgrades with minimal extra infrastructure.', 'Lower resource cost, but each pod replacement must preserve Raft health and leader safety.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Blue-green', 'High-control cutovers with explicit promotion and rollback phases.', 'More orchestration and roughly double storage during the transition.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<Tabs groupId="upgrade-manager-strategies">
+  <TabItem value="rolling" label="Rolling update">
+
+<DiagramFrame
+  title="Rolling update flow"
+  caption="Rolling upgrades use StatefulSet partitioning and leader step-down so each pod can be replaced while Raft remains healthy."
+  code={`graph TD
+    Trigger["Version change"] --> Partition["Set partition to replicas"]
+    Partition --> Loop{"Partition > 0"}
+    Loop --> Identify["Identify leader"]
+    Identify --> StepDown["Step down if target pod is leader"]
+    StepDown --> Update["Decrement partition"]
+    Update --> Ready["Wait for pod ready"]
+    Ready --> Health["Wait for OpenBao health"]
+    Health --> Loop
+    Loop --> Converge["Verify StatefulSet and pod convergence"]
+    Converge --> Finalize["Atomically finalize status"]
+
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Trigger,Identify,Ready,Health read;
+    class Partition,StepDown,Update,Converge process;
+    class Finalize write;`}
+/>
+
+<Checklist
+  title="Rolling safety controls"
+  items={[
+    'StatefulSet partitioning pauses Kubernetes-driven rollout until the manager explicitly advances each ordinal.',
+    'Reverse ordinal updates and forced leader step-down protect Raft availability during pod replacement.',
+    'Finalization only happens after the StatefulSet revision and observed workload health fully converge.',
+  ]}
+/>
+
+  </TabItem>
+  <TabItem value="bluegreen" label="Blue-green">
+
+<Callout type="warning" title="Resource usage">
+
+Blue-green creates a second revision and needs roughly double storage capacity for the duration of the transition.
+
+</Callout>
+
+<DiagramFrame
+  title="Blue-green flow"
+  caption="Blue-green creates a parallel revision, promotes it through explicit phases, then switches traffic only after leadership and voter transitions are safe."
+  code={`graph TD
+    Deploy["Deploy green revision"] --> Join["Join green as non-voters"]
+    Join --> Sync["Wait for sync and optional hold"]
+    Sync --> Promote["Promote green to voters"]
+    Promote --> Demote["Demote blue and step down"]
+    Demote --> Leader{"Green leader observed?"}
+    Leader --> Switch["Cleanup: switch service to green"]
+    Switch --> Remove["Remove blue peers"]
+    Remove --> Delete["Delete blue StatefulSet"]
+    Promote --> Rollback["Late failure triggers rollback"]
+    Rollback --> Repair["Repair consensus"]
+    Repair --> DeleteGreen["Delete green revision"]
+
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef critical fill:transparent,stroke:#dc2626,stroke-width:2px,stroke-dasharray: 5 5,color:#f8fafc;
+
+    class Deploy,Join,Sync,Promote,Demote,Remove,Delete,Repair,DeleteGreen process;
+    class Switch,Rollback critical;
+    class Leader write;`}
+/>
+
+<Checklist
+  title="Blue-green safety controls"
+  tone="warning"
+  items={[
+    'The service selector switches to green only in cleanup.',
+    'Manual promotion, manual rollback, and validation-hook failures all route through explicit phase handling in status.',
+    'If rollback consensus repair fails late, the manager enters break-glass and stops risky automation.',
+  ]}
+/>
+
+  </TabItem>
+</Tabs>
+
+## State and recovery model
+
+<DecisionTable
+  kind="reference"
+  title="Status-backed upgrade state"
+  columns={['State surface', 'What it preserves']}
+  rows={[
+    {
+      cells: ['status.upgrade', 'Rolling partition progress, completed pods, finalization gating, and the structured failure surface under `status.upgrade.failure` (with deprecated `lastError*` compatibility fields still mirrored for now).'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['status.blueGreen.phase', 'The active blue-green phase and whether promotion, cleanup, or rollback is in progress.'],
+    },
+    {
+      cells: ['status.upgradeRequests', 'Edge-trigger bookkeeping for retry, promote, and rollback requests so one-shot adminops intent is handled exactly once.'],
+    },
+    {
+      cells: ['status.breakGlass', 'The nonce and diagnostic state when late rollback automation can no longer continue safely.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Safety boundaries"
+  columns={['Concern', 'Manager behavior']}
+  rows={[
+    {
+      cells: ['Availability over progress', 'Rolling pauses or retries when health is ambiguous; blue-green aborts early and rolls back later phases instead of forcing completion.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Version policy and image alignment', 'Invalid semantic versions, downgrades, and conflicting image/version inputs are rejected before orchestration begins.'],
+    },
+    {
+      cells: ['Backup prerequisites', 'Snapshot prerequisites and backup authentication must already be valid before upgrade safety checks pass.'],
+    },
+    {
+      cells: ['Atomic completion', 'Rolling finalization updates upgrade state and currentVersion together so status does not split across two truths.'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Operation lifecycle coordination',
+      description: 'Lock, retry, and phase-transition helpers shared with backup and restore.',
+      docId: 'architecture/operation-lifecycle',
+    },
+    {
+      label: 'Backup manager',
+      description: 'Pre-upgrade snapshots and object-storage readiness.',
+      docId: 'architecture/backup-manager',
+    },
+    {
+      label: 'Upgrades guide',
+      description: 'User-facing rolling and blue-green operating procedures.',
+      docId: 'user-guide/openbaocluster/operations/upgrades',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/architecture/workload-managers.md b/website/versioned_docs/version-0.3.0/architecture/workload-managers.md
new file mode 100644
index 000000000..59a7d4076
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/architecture/workload-managers.md
@@ -0,0 +1,233 @@
+---
+title: Workload Managers
+hide_title: true
+pageType: concept
+journey: architecture
+description: Bootstrap, networking, identity, and workload managers plus shared contracts on the OpenBaoCluster workload reconcile path.
+---
+
+<PageHeader
+  title="Workload managers"
+  lede="The OpenBaoCluster workload path is coordinated through bootstrap, networking, identity, workload, cert, and init managers. Shared configuration, resource identity, and owned-apply contracts keep the cross-service behavior aligned."
+/>
+
+<ManagerAtAGlance
+  sections={[
+    {
+      label: 'Control path',
+      items: [
+        'workload reconciler',
+        'internal/controller/openbaocluster',
+        'internal/app/openbaocluster workload orchestration',
+      ],
+    },
+    {
+      label: 'Workload-side managers',
+      items: [
+        'internal/service/bootstrap',
+        'internal/service/networking',
+        'internal/service/identity',
+        'internal/service/workload',
+      ],
+    },
+    {
+      label: 'Coordinates with',
+      items: [
+        'internal/service/certs',
+        'internal/service/init',
+      ],
+    },
+    {
+      label: 'Shared contracts',
+      items: [
+        'internal/service/configuration',
+        'internal/platform/resourceidentity',
+        'internal/platform/resourceapply',
+      ],
+    },
+    {
+      label: 'Writes',
+      items: [
+        'rendered config and bootstrap prerequisites',
+        'Services, Ingress or Gateway resources, and network policies',
+        'ServiceAccount and tenant-scoped RBAC for the main workload',
+        'StatefulSet, PodDisruptionBudget, and rollout-triggering pod template changes',
+      ],
+    },
+  ]}
+/>
+
+## Architectural placement
+
+The workload reconcile path is now sequenced explicitly:
+
+1. `internal/controller/openbaocluster` receives a workload-side reconcile event.
+2. The controller delegates into `internal/app/openbaocluster`.
+3. The app layer coordinates cert, bootstrap, networking, identity, workload, and init behavior in the correct order.
+4. Shared contracts keep `config.hcl`, managed-resource identity, and generic owned-apply behavior consistent across those managers.
+5. Each manager owns a narrower write surface on the same reconcile path.
+
+This keeps change-coupling lower: config rendering, service exposure, ServiceAccount or RBAC wiring, and StatefulSet lifecycle do not need to move together by default.
+
+<DiagramFrame
+  title="Workload managers on the reconcile path"
+  caption="The app layer sequences narrow managers so each one owns a specific part of the workload-side contract."
+  code={`graph TD
+    Event["Workload-side reconcile event"] --> App["internal/app/openbaocluster"]
+
+    App --> Cert["Cert manager"]
+    App --> Bootstrap["Bootstrap manager"]
+    App --> Networking["Networking manager"]
+    App --> Identity["Identity manager"]
+    App --> Workload["Workload manager"]
+    App --> Init["Init manager when uninitialized"]
+    Bootstrap --> ConfigSvc["Configuration service"]
+    Bootstrap --> IdentityContract["Resource identity"]
+    Networking --> IdentityContract
+    Identity --> IdentityContract
+    Workload --> IdentityContract
+    Bootstrap --> ApplyContract["Owned apply"]
+    Networking --> ApplyContract
+    Identity --> ApplyContract
+    Workload --> ApplyContract
+
+    Cert --> TLS["TLS Secrets and reload signals"]
+    Bootstrap --> Config["config.hcl, self-init config, seal prerequisites"]
+    Networking --> Network["Services, Ingress or Gateway, NetworkPolicy"]
+    Identity --> RBAC["ServiceAccount, Role, RoleBinding"]
+    Workload --> Stateful["StatefulSet, PDB, rollout triggers"]
+    Init --> InitState["status.initialized, autopilot handoff"]
+
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class App process;
+    class Event,TLS,Config,Network,RBAC,Stateful,InitState read;
+    class Cert,Bootstrap,Networking,Identity,Workload,Init write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Manager boundaries within the workload path"
+  columns={['Manager', 'Owns', 'Primary writes', 'Why it stays separate']}
+  rows={[
+    {
+      cells: ['Bootstrap manager', 'Rendered config, self-init surfaces, unseal prerequisites, and related validation.', 'ConfigMap surfaces, static unseal Secret when applicable, self-init ConfigMap, shared-cache PVC setup, and managed audit file storage PVC setup.', 'Config and bootstrap prerequisites change for different reasons than networking or StatefulSet lifecycle.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Networking manager', 'Cluster reachability and policy surfaces.', 'Headless and external Services, Ingress or Gateway resources, gateway CA ConfigMap, and network policies.', 'Service exposure and network policy assumptions are a distinct domain from config rendering or pod-template mutation.'],
+    },
+    {
+      cells: ['Identity manager', 'Main workload Kubernetes identity.', 'ServiceAccount, Role, and RoleBinding for the cluster workload.', 'Workload RBAC should change independently from config, networking, or rollout behavior.'],
+    },
+    {
+      cells: ['Workload manager', 'StatefulSet lifecycle and rollout boundaries.', 'StatefulSet, PodDisruptionBudget, revision-scoped rendered config, and pod-template rollout triggers.', 'Replica intent, pod-template mutation, and rollout safety belong close to the StatefulSet contract.'],
+    },
+  ]}
+/>
+
+## What each manager does
+
+### Bootstrap manager
+
+The bootstrap manager prepares everything the workload needs before the StatefulSet can be reconciled safely:
+
+- reconcile the main ConfigMap using `config.hcl` rendered by the shared configuration service
+- reconcile the self-init ConfigMap when self-init is enabled
+- generate the static unseal Secret when that seal mode is selected
+- validate unseal prerequisites and related secret references
+- prepare ACME shared-cache storage when that mode requires it
+- prepare managed audit file storage PVCs when file audit handoff storage is configured
+
+### Networking manager
+
+The networking manager owns how traffic and policy reach the cluster:
+
+- headless and external Services, including the shared client Service and optional dedicated read Service
+- Ingress and Gateway API resources
+- gateway CA export and backend TLS policy resources
+- workload and job network policies
+- API server network discovery and related preflight checks
+
+### Identity manager
+
+The identity manager owns the steady-state Kubernetes identity for the cluster workload:
+
+- ServiceAccount creation or reuse
+- Role and RoleBinding for pod-level runtime actions
+- resource naming and ownership metadata for those identity objects
+
+### Workload manager
+
+The workload manager owns the StatefulSet-facing contract:
+
+- StatefulSet render and apply
+- steady-state read-replica StatefulSet lifecycle and safe drain or delete behavior
+- PodDisruptionBudget reconciliation
+- rollout triggers from rendered config or certificate hash changes
+- audit file storage volume and mount wiring for voter and read-replica StatefulSets
+- single-replica bootstrap and later scale-out after initialization
+- revision-scoped workload resources used by blue/green and rollout-safe updates
+- read-first or restore-safe operational ordering delegated by the app layer for rolling upgrades, blue-green, and restore
+
+<Callout type="note" title="The shared client endpoint is intentional">
+
+The networking manager keeps the main client Service attached to the shared client-serving selector, which can include both voters and steady read replicas. The optional dedicated read Service remains a separate networking surface for explicit consumers, but the primary endpoint stays stable so OpenBao can handle standby reads and request forwarding itself.
+
+</Callout>
+
+## Shared contracts on the workload path
+
+The workload-side managers share three narrower contracts instead of reimplementing the same semantics in each package:
+
+<DecisionTable
+  kind="reference"
+  title="Shared contracts below the managers"
+  columns={['Contract', 'Used by', 'Owns']}
+  rows={[
+    {
+      cells: ['Configuration service', 'Bootstrap manager and blue-green upgrade flow.', 'Shared `config.hcl` rendering semantics, including revision-aware green startup config.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Resource identity', 'Bootstrap, networking, identity, and workload managers.', 'Managed-resource names, labels, and selectors that must stay aligned across services.'],
+    },
+    {
+      cells: ['Owned apply', 'Bootstrap, networking, identity, and workload managers.', 'Generic owner-ref-aware apply flow and shared SSA error handling for resources that do not need object-specific special cases.'],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Cert and init stay adjacent to the workload path">
+
+TLS lifecycle and first-boot initialization stay as separate managers on the same workload-side reconcile path. They continue to coordinate with the workload managers without becoming part of the bootstrap, networking, identity, or workload services.
+
+</Callout>
+
+<NextActions
+  title="Related deep dives"
+  items={[
+    {
+      label: 'Component design',
+      description: 'See where the workload-side managers sit relative to controllers, admin operations, and status writes.',
+      docId: 'architecture/components',
+    },
+    {
+      label: 'Init manager',
+      description: 'Follow the first-boot contract and the handoff into scale-out after initialization succeeds.',
+      docId: 'architecture/init-manager',
+    },
+    {
+      label: 'Cert manager',
+      description: 'See how TLS lifecycle fits into the same workload-side path without becoming part of the bootstrap manager.',
+      docId: 'architecture/cert-manager',
+    },
+    {
+      label: 'Day 1 creation',
+      description: 'Follow how these managers interact during cluster bootstrap and the first safe scale-out.',
+      docId: 'architecture/lifecycle/day1-creation',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/assets/favicon.png b/website/versioned_docs/version-0.3.0/assets/favicon.png
new file mode 100644
index 000000000..9e79d9345
Binary files /dev/null and b/website/versioned_docs/version-0.3.0/assets/favicon.png differ
diff --git a/website/versioned_docs/version-0.3.0/assets/logo.svg b/website/versioned_docs/version-0.3.0/assets/logo.svg
new file mode 100644
index 000000000..8e2ab9b0a
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/assets/logo.svg
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   version="1.1"
+   id="svg1"
+   width="2000"
+   height="1200"
+   viewBox="0 0 2000 1200"
+   xml:space="preserve"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"><defs
+     id="defs1"><clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath23"><g
+         id="use23"
+         style="stroke-width:1.52068"><path
+           style="display:inline;opacity:1;fill:#87d6be;fill-opacity:1;stroke:none;stroke-width:144.464;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:0;stroke-opacity:1"
+           id="path73"
+           d="M 2479.5983,735.4187 A 1207.5515,346.58099 0 0 1 1272.0468,1081.9997 1207.5515,346.58099 0 0 1 64.495239,735.4187 1207.5515,346.58099 0 0 1 1272.0468,388.83771 1207.5515,346.58099 0 0 1 2479.5983,735.4187 Z" /></g></clipPath></defs><path
+     id="path1"
+     style="display:inline;opacity:1;fill:#87d6be;fill-opacity:1;stroke:none;stroke-width:94.9998;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:0;stroke-opacity:1"
+     d="m 1646.9766,568.29883 c -0.4021,9.28858 -1.3002,18.39774 -2.6954,27.26953 -4.6656,29.66707 -15.0317,57.29226 -34.1464,79.10742 -19.1148,21.81515 -48.4485,36.15534 -80.1465,36.08594 h -184.1426 c 12.617,42.748 15.9028,85.66477 9.8535,124.13086 -4.2633,27.10897 -13.2879,52.51386 -29.3965,73.33789 68.8327,-8.90446 131.0365,-20.6396 186.836,-34.23242 9.6441,-2.41785 19.0831,-4.9023 28.3086,-7.45117 15.5469,-4.1773 30.8395,-8.4187 45.1152,-12.92383 10.084,-3.23573 19.8439,-6.55349 29.2676,-9.94922 13.0842,-4.63661 25.6485,-9.38035 37.414,-14.29102 8.6066,-3.59282 16.8522,-7.25578 24.7266,-10.98437 10.7781,-5.10303 20.6966,-10.3456 30.0586,-15.68164 9.0307,-4.94306 17.4257,-9.97966 25.168,-15.09961 1.7009,-1.17781 3.5135,-2.34066 5.1465,-3.52735 10.8179,-7.89868 20.0901,-15.96463 27.7734,-24.16015 1.2964,-1.37505 2.5344,-2.7549 3.7422,-4.13867 7.5539,-8.52306 13.3826,-17.16446 17.457,-25.88086 0.1479,-0.32607 0.2945,-0.65211 0.4375,-0.97852 4.1825,-9.44684 6.298,-18.95962 6.334,-28.48242 -0.024,-9.28617 -2.0261,-18.56323 -5.9941,-27.7793 -0.1212,-0.28309 -0.2776,-0.56475 -0.4024,-0.84765 -3.9066,-8.73927 -9.5756,-17.40616 -16.9785,-25.95704 -1.1175,-1.29964 -2.5435,-2.57371 -3.7402,-3.86718 -6.7524,-7.29785 -14.7643,-14.49488 -24.0059,-21.56446 -1.638,-1.25293 -3.0506,-2.52867 -4.7656,-3.77343 -9.9076,-7.0605 -21.0414,-13.97411 -33.3594,-20.71485 -17.1484,-9.52786 -36.0153,-18.83451 -57.8652,-27.64648 z M 313.74414,585.77734 c -2.72099,1.49732 -5.38392,3.00327 -7.98828,4.51758 -11.95017,6.20546 -23.60183,12.4558 -33.44531,18.92383 -12.18098,8.00471 -22.74854,16.20378 -31.65039,24.55664 -0.0184,0.0172 -0.0422,0.0336 -0.0605,0.0508 -17.85239,16.7615 -28.90854,34.05812 -32.94922,51.54688 -1.15886,5.01851 -1.7386,10.04665 -1.73828,15.07617 -1e-5,1.01729 0.0232,2.03358 0.0703,3.04883 0.47184,10.05362 3.26114,20.08725 8.34961,30.03515 0.0102,0.0201 0.0171,0.0405 0.0273,0.0606 5.07495,9.87744 12.40584,19.64849 21.94531,29.25 0.0956,0.0964 0.15979,0.19661 0.25586,0.29297 9.58024,9.60606 21.35108,19.0209 35.23633,28.18359 0.0901,0.0595 0.16166,0.12025 0.25195,0.17969 13.97497,9.2054 30.05428,18.13566 48.13281,26.73242 1.95321,0.92869 4.48123,1.74928 6.48047,2.66992 16.28357,7.611 34.11185,14.9407 53.39258,21.95118 7.09747,2.54598 15.53413,4.78023 23.01758,7.24023 15.06111,5.15717 30.91062,10.12037 47.50195,14.875 50.21668,13.81638 107.13891,25.86543 169.9375,35.67187 l 0.36719,0.0664 c -12.80324,-19.30266 -20.37048,-41.86587 -24.13672,-65.81445 -6.065,-38.56565 -2.7466,-81.60514 9.95117,-124.46289 H 429.3457 c -31.69806,0.0694 -61.03174,-14.27079 -80.14648,-36.08594 -19.11474,-21.81516 -29.48093,-49.44035 -34.14649,-79.10742 -0.61408,-3.90477 -1.08133,-7.55087 -1.30859,-9.45899 z" /><path
+     id="path2"
+     style="baseline-shift:baseline;display:inline;overflow:visible;opacity:1;vector-effect:none;fill:#79c0ab;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:0;stroke-opacity:1;enable-background:accumulate;stop-color:#000000;stop-opacity:1"
+     d="m 1598.6133,685.90039 c -18.4516,15.37405 -42.7507,24.91798 -68.625,24.86133 h -184.1426 c 12.617,42.748 15.9028,85.66477 9.8535,124.13086 -2.6536,16.87326 -7.152,33.08629 -14.0547,47.94531 l 254.4746,-194.84375 c 0.8622,-0.66034 1.6945,-1.35896 2.4942,-2.09375 z m -1236.57424,0.74609 c 0.7484,0.69584 1.52578,1.35984 2.33008,1.99024 l 124.85742,97.72266 120.75977,94.51757 c -6.43677,-14.31499 -10.70437,-29.83462 -13.24414,-45.98437 -6.065,-38.56565 -2.7466,-81.60514 9.95117,-124.46289 H 429.3457 c -25.26313,0.0553 -49.02356,-9.04329 -67.30664,-23.78321 z" /><path
+     style="baseline-shift:baseline;display:inline;overflow:visible;opacity:1;vector-effect:none;fill:#fdd0a4;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:round;stroke-opacity:1;enable-background:accumulate;stop-color:#000000;stop-opacity:1"
+     d="m 694.53154,245.55178 c -125.79647,0 -246.4673,61.14684 -308.99869,174.44864 -62.53139,113.30181 -44.14841,254.23947 43.73404,254.04718 H 694.53154 959.79615 C 1047.6786,674.23989 1066.0616,533.30223 1003.5302,420.00042 940.99887,306.69862 820.32801,245.55178 694.53154,245.55178 Z"
+     id="path3" /><path
+     style="baseline-shift:baseline;display:inline;overflow:visible;opacity:1;vector-effect:none;fill:#dab991;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:round;stroke-opacity:1;enable-background:accumulate;stop-color:#000000;stop-opacity:1"
+     d="m 1264.8027,245.88334 c -125.7965,0 -246.4673,61.14683 -308.99869,174.44864 -62.53139,113.3018 -44.14841,254.23946 43.73404,254.04718 h 265.26465 265.2646 c 87.8825,0.19228 106.2655,-140.74538 43.7341,-254.04718 C 1511.27,307.03017 1390.5992,245.88334 1264.8027,245.88334 Z"
+     id="path4" /><path
+     style="baseline-shift:baseline;display:inline;overflow:visible;opacity:1;vector-effect:none;fill:#fdfccf;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:round;stroke-opacity:1;enable-background:accumulate;stop-color:#000000;stop-opacity:1"
+     d="m 976.22056,485.20746 c -125.79647,0 -246.4673,61.14684 -308.99869,174.44864 -62.53139,113.30181 -44.14841,254.23947 43.73404,254.04718 h 265.26465 265.26464 c 87.8825,0.19229 106.2655,-140.74537 43.734,-254.04718 C 1222.6879,546.3543 1102.017,485.20746 976.22056,485.20746 Z"
+     id="path5" /><path
+     d="m 694.52929,209.16798 c -4.32301,7e-5 -8.51715,0.31785 -12.65235,0.77539 -133.06468,4.02349 -260.91613,70.56506 -328.19921,192.47656 -23.94621,43.38858 -37.54667,89.74295 -40.79883,133.66992 -95.32789,48.37554 -146.35347,105.67812 -146.35352,164.35742 -1.9e-4,77.01482 87.8123,150.87626 244.11914,205.33401 156.30684,54.45772 368.30412,85.05074 589.35548,85.05074 221.0513,0 433.0486,-30.59302 589.3555,-85.05074 156.3068,-54.45776 244.1193,-128.3192 244.1191,-205.33401 -2e-4,-67.18843 -66.8739,-132.29785 -189.2246,-184.23242 -5.4283,-37.76175 -18.2942,-76.67813 -38.5957,-113.46289 -67.2871,-121.91871 -195.1477,-188.47006 -328.2208,-192.48633 -4.0405,-0.44612 -8.1396,-0.75559 -12.3593,-0.76562 -0.091,-2.2e-4 -0.1808,0 -0.2715,0 -0.09,0 -0.1796,-2.2e-4 -0.2695,0 -3.8,0.009 -7.5117,0.23836 -11.1661,0.60351 -115.687,3.16481 -227.4809,53.66962 -299.18549,146.76172 8.08791,-10.50074 16.58939,-20.56235 25.64654,-29.98047 C 908.37984,252.40094 808.2573,212.29106 705.17577,209.67384 c -3.48404,-0.32383 -7.02864,-0.50586 -10.64453,-0.50586 z m -36.38087,84.86133 v 82.81249 c -2e-4,7.68298 2.43172,15.16883 6.94727,21.38477 2.24448,3.08946 4.96133,5.80631 8.05078,8.05078 6.21595,4.51555 13.7018,6.94747 21.38477,6.94727 20.09352,-3.6e-4 36.38245,-16.28929 36.38281,-36.38282 v -82.81249 c 0.50905,0.27314 1.01697,0.55118 1.52148,0.83203 14.39063,8.01007 27.90229,19.76611 29.93165,22.1914 12.89044,15.40541 30.07617,44.25372 30.07617,59.78906 3.6e-4,20.09428 16.29048,36.38353 36.38475,36.38282 20.09355,-3.6e-4 36.38248,-16.28929 36.38281,-36.38282 0,-21.44623 -5.50308,-40.32062 -13.0918,-56.4414 30.86066,16.46666 58.79644,38.07178 82.33596,64.52929 4.70323,-7.48303 9.92808,-14.45177 15.09374,-21.47656 -9.17112,12.47194 -17.92209,25.38784 -25.59959,39.29883 -9.55548,17.3137 -17.46406,35.1 -23.72463,53.01562 -17.66522,3.26447 -35.06938,7.6711 -52.07424,13.19727 -0.98805,-1.70873 -2.15924,-3.35914 -3.48825,-4.91797 -12.44525,-14.59746 -29.2714,-24.04331 -47.34375,-24.3457 -18.07228,-0.30238 -35.81646,9.47463 -46.20703,24.76367 -8.51417,12.52804 -11.2745,22.8254 6.13867,33.57227 5.05018,3.11681 10.4698,4.33563 15.61133,4.39648 -56.17176,32.48516 -104.22857,79.36806 -137.49414,139.64258 0.81601,-1.47849 1.6409,-2.94974 2.47461,-4.41211 h -208.57618 -0.0781 c -12.24317,0.027 -18.1629,-3.17815 -25.25781,-11.27539 -7.09491,-8.09723 -13.89508,-22.75099 -16.99414,-42.45703 -6.19812,-39.41208 2.99805,-96.60873 30.45117,-146.35156 28.37185,-51.40751 70.22849,-90.85867 119.55664,-117.17969 -7.58852,16.1206 -13.0918,34.99555 -13.0918,56.4414 3.6e-4,20.09429 16.29048,36.38353 36.38477,36.38282 20.09352,-3.6e-4 36.38245,-16.28929 36.38281,-36.38282 0,-15.53534 17.18573,-44.38365 30.07617,-59.78906 2.02936,-2.42529 15.54101,-14.18133 29.93164,-22.1914 0.50452,-0.28085 1.01244,-0.55889 1.52148,-0.83203 z m 570.27148,0.33203 v 82.81054 c 0,7.68364 2.4313,15.17024 6.9472,21.38672 2.2441,3.08862 4.9603,5.80479 8.0489,8.04883 6.2162,4.51663 13.7028,6.94927 21.3867,6.94922 20.0943,-3.6e-4 36.3835,-16.29048 36.3828,-36.38477 v -82.81054 c 0.5091,0.27315 1.017,0.54924 1.5215,0.83007 14.3906,8.01008 27.9023,19.76807 29.9316,22.19336 12.8905,15.40541 30.0762,44.25177 30.0762,59.78711 0,20.09506 16.2897,36.3855 36.3848,36.38477 20.0943,-3.6e-4 36.3835,-16.29048 36.3828,-36.38477 0,-21.44632 -5.505,-40.32057 -13.0938,-56.44141 49.3287,26.32152 91.1865,65.77381 119.5586,117.18165 27.4531,49.74283 36.6493,106.93948 30.4512,146.35156 -3.0991,19.70604 -9.8992,34.35979 -16.9941,42.45703 -7.0949,8.09726 -13.0147,11.30216 -25.2579,11.27539 h -0.08 -215.2793 c -35.9412,-63.1981 -88.322,-111.18925 -149.1934,-142.94531 2.7104,0.0282 4.5543,1.2576 7.42,2.65234 7.7378,3.76605 20.9421,6.34036 32.2851,-0.66015 17.4132,-10.74687 14.6528,-21.04618 6.1387,-33.57422 -10.3906,-15.28904 -28.1348,-25.06411 -46.2071,-24.76172 -18.0723,0.30239 -34.8985,9.74824 -47.3437,24.3457 -2.3835,2.79565 -4.2586,5.87981 -5.4824,9.08203 -39.5113,-13.70009 -81.3324,-21.29738 -123.67972,-22.5625 -3.98763,-0.43584 -8.0332,-0.73679 -12.19529,-0.74804 2.01949,10e-4 4.03702,0.0163 6.05467,0.0469 25.08504,-49.98918 67.06654,-97.00544 124.68744,-128.26173 -7.6182,16.14736 -13.1484,35.06253 -13.1484,56.5625 0,20.09506 16.2897,36.3855 36.3848,36.38477 20.0943,-3.6e-4 36.3835,-16.29048 36.3828,-36.38477 0,-15.53534 17.1857,-44.3817 30.0761,-59.7871 2.0294,-2.42529 15.5411,-14.18329 29.9317,-22.19336 0.5046,-0.28084 1.0125,-0.55693 1.5215,-0.83008 z m -686.5078,143.3496 c -18.0723,0.30239 -34.90043,9.7502 -47.3457,24.34766 -8.64754,10.14297 -10.60039,24.08653 0.94922,33.67187 10.2567,8.51234 20.67217,8.93224 38.47851,0.69141 8.8115,-4.07798 10.69895,-2.14656 15.69922,0.28711 7.73787,3.76605 20.94218,6.34036 32.28516,-0.66016 17.41316,-10.74686 14.65283,-21.04617 6.13867,-33.57421 -10.39057,-15.28904 -28.1328,-25.06606 -46.20508,-24.76368 z m 887.3457,0.9961 c -18.0723,-0.30239 -35.8146,9.47268 -46.2051,24.76172 -8.5142,12.52804 -11.2764,22.82735 6.1367,33.57422 11.343,7.00051 24.5493,4.4262 32.2871,0.66015 5.0003,-2.43367 6.8877,-4.36509 15.6992,-0.28711 17.8064,8.24082 28.2199,7.82093 38.4766,-0.6914 11.5496,-9.58535 9.5968,-23.52891 0.9492,-33.67188 -12.4452,-14.59746 -29.2714,-24.04331 -47.3437,-24.3457 z m -489.41993,94.97852 v 82.81054 c -5.9e-4,7.68364 2.43135,15.17024 6.9473,21.38672 2.244,3.08861 4.96016,5.80478 8.04878,8.04883 6.21625,4.51663 13.70285,6.94927 21.38673,6.94922 20.09427,-3.6e-4 36.38352,-16.29048 36.38282,-36.38477 v -82.81054 c 0.509,0.27314 1.017,0.54925 1.5215,0.83007 14.3906,8.01008 27.9023,19.76807 29.9316,22.19336 12.8905,15.40541 30.0762,44.25177 30.0762,59.78711 0,20.09506 16.2897,36.3855 36.3848,36.38477 20.0934,-10e-4 36.3815,-16.29125 36.3808,-36.38477 0,-21.44644 -5.503,-40.32051 -13.0918,-56.44141 49.3287,26.32165 91.1865,65.77385 119.5586,117.18165 27.4531,49.74284 36.6473,106.93944 30.4492,146.35156 -3.099,19.70603 -9.8973,34.35978 -16.9922,42.45703 -7.0949,8.09725 -13.0146,11.30218 -25.2578,11.27541 h -0.08 -265.26362 -265.26561 -0.0801 c -12.24316,0.027 -18.16093,-3.17816 -25.25586,-11.27541 -7.09493,-8.09725 -13.89506,-22.751 -16.99414,-42.45703 -6.1981,-39.41212 2.99807,-96.60872 30.45117,-146.35156 28.37171,-51.40709 70.22861,-90.85802 119.55664,-117.17969 -7.58859,16.12066 -13.09179,34.99347 -13.09179,56.43945 -6.6e-4,20.09504 16.28968,36.38548 36.38474,36.38477 20.09428,-3.6e-4 36.38354,-16.29048 36.38281,-36.38477 0,-15.53534 17.18577,-44.3817 30.07621,-59.78711 2.02936,-2.42529 15.54097,-14.18328 29.9316,-22.19336 0.50485,-0.281 1.01212,-0.55676 1.5215,-0.83007 z m 707.13863,34.61328 c 95.692,38.59219 147.1124,84.78304 147.1114,132.15039 -5e-4,89.63578 -183.0629,170.94845 -467.7852,207.78123 16.1089,-20.82415 25.1331,-46.22863 29.3965,-73.33788 6.0493,-38.46609 2.7635,-81.38285 -9.8535,-124.13085 h 184.1426 c 31.698,0.0694 61.0317,-14.27079 80.1465,-36.08594 19.1147,-21.81516 29.4808,-49.44035 34.1464,-79.10742 1.3952,-8.87191 2.2932,-17.98081 2.6953,-27.26953 z M 313.74413,585.77539 c 0.2272,1.90773 0.69436,5.55521 1.3086,9.46094 4.66556,29.66707 15.03174,57.29227 34.14648,79.10743 19.11474,21.81515 48.44843,36.15531 80.14649,36.08594 h 177.34765 c -12.69777,42.85775 -16.01617,85.89723 -9.95117,124.46288 3.85879,24.53707 11.70744,47.62084 25.08984,67.23244 -0.33862,-0.49623 -0.76426,-0.93682 -1.0957,-1.43752 C 365.07544,860.79801 205.91103,783.96833 205.9121,700.44923 c -0.001,-40.28802 37.20632,-79.85678 107.83203,-114.67384 z m 785.81837,90.9297 c -18.0723,-0.30244 -35.8145,9.47274 -46.2051,24.76172 -8.5142,12.5281 -11.2745,22.82736 6.1387,33.57421 11.3429,7.0005 24.5473,4.42618 32.2851,0.66016 5.0003,-2.43372 6.8877,-4.3651 15.6992,-0.28711 17.8064,8.2408 28.2219,7.82092 38.4785,-0.6914 11.5496,-9.58534 9.5969,-23.5289 0.9493,-33.67188 -12.4453,-14.59745 -29.2734,-24.04334 -47.3457,-24.3457 z m -275.96095,0.6621 c -18.07233,0.30243 -34.90045,9.75022 -47.3457,24.34766 -8.64753,10.14299 -10.60037,24.08459 0.94922,33.66992 10.25675,8.51233 20.67217,8.93417 38.47852,0.69336 8.81151,-4.07798 10.69896,-2.14654 15.69923,0.28711 7.73787,3.76602 20.94218,6.33846 32.28516,-0.66211 17.41316,-10.74686 14.65281,-21.04423 6.13865,-33.57226 -10.39057,-15.28905 -28.1328,-25.06604 -46.20508,-24.76368 z"
+     style="display:inline;opacity:1;fill:#091a28;fill-opacity:1;stroke:none;stroke-width:94.9998;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:0;stroke-opacity:1"
+     id="path6" />
+  <text
+     x="1000"
+     y="1120"
+     text-anchor="middle"
+     style="font-size:170px;font-family:'DM Sans',sans-serif;font-weight:700;letter-spacing:1px;fill:#f8fafc;fill-opacity:1;stroke:#091a28;stroke-width:14px;stroke-linejoin:round;paint-order:stroke fill">OpenBao Operator</text></svg>
diff --git a/website/versioned_docs/version-0.3.0/assets/repo_logo.png b/website/versioned_docs/version-0.3.0/assets/repo_logo.png
new file mode 100644
index 000000000..d7d2bb7c1
Binary files /dev/null and b/website/versioned_docs/version-0.3.0/assets/repo_logo.png differ
diff --git a/website/versioned_docs/version-0.3.0/contribute/ci.md b/website/versioned_docs/version-0.3.0/contribute/ci.md
new file mode 100644
index 000000000..c3b12d8c6
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/ci.md
@@ -0,0 +1,208 @@
+---
+title: Continuous Integration
+description: CI pipeline overview for OpenBao Operator, including local parity, change routing, E2E expansion, release hardening, and maintainer-only workflow lanes.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="CI workflow and local parity"
+  lede="Pull request, `main`, nightly, and release workflows, plus the closest local command set for each validation lane."
+/>
+
+<DiagramFrame
+  title="CI and publish flow"
+  caption="Pull requests are change-routed; publish channels add provenance and reproducibility gates before anything is promoted."
+  code={`graph TD
+    PR["Pull request"] --> Detect["Detect changes"]
+    Main["Push to main"] --> Detect
+    Detect --> Core["Core quality gates"]
+    Detect --> E2E["E2E routing"]
+    Core --> Result["CI result"]
+    E2E --> Result
+    Result --> Edge["Edge publish"]
+    Nightly["Nightly schedule"] --> NightlyRun["Nightly validation"]
+    NightlyRun --> NightlyPublish["Nightly publish"]
+    Tag["SemVer tag"] --> Release["Release workflow"]
+    Edge --> Harden["Hardening gates"]
+    NightlyPublish --> Harden
+    Release --> Harden
+    Harden --> Publish["Promote and publish artifacts"]`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="PR-equivalent local gate"
+  code={`make bootstrap
+make doctor
+make ci-core`}
+>
+  Default local baseline before handing work to CI.
+</CommandBlock>
+
+<DecisionTable
+  title="Map CI lanes to local commands"
+  columns={["CI concern", "Run locally", "Notes"]}
+  rows={[
+    {
+      cells: [
+        "Core PR validation",
+        "`make ci-core`",
+        "Covers lint, formatting, tidy, vendor, generated artifacts, tests, docs, Helm, security, fuzz smoke, and config compatibility.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Docs-only changes",
+        "`make docs-build`",
+        "For changes isolated to documentation, routing, or site behavior.",
+      ],
+    },
+    {
+      cells: [
+        "Dependency and license policy",
+        "`make verify-vendor` and `make license-check`",
+        "The repository enforces vendored dependency resolution and shipped-license allowlists through its local and CI artifact checks.",
+      ],
+    },
+    {
+      cells: [
+        "Static security and filesystem scans",
+        "`make semgrep-ci`, `make security-ci`, and `make security-scan-built-images`",
+        "Run these when dependencies, network-facing code, container-facing surfaces, or CI/config security surfaces changed. `make semgrep-ci` is the blocking local Semgrep scan across `cmd`, `internal`, `api`, `hack`, `config`, and `.github`; `make security-ci` includes that scan plus vulncheck, license policy, and the Trivy filesystem scan.",
+      ],
+    },
+    {
+      cells: [
+        "Focused E2E and platform validation",
+        "`make test-e2e-ci ...`, `make helm-e2e-smoke`, or `make test-e2e-existing ...`",
+        "Label filters and the existing-cluster path provide smaller or platform-specific reproductions.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="What CI assumes">
+
+CI and release workflows enforce vendored Go dependencies. After dependency changes, rerun `make verify-vendor`. License verification uses that same vendored view of the dependency graph.
+
+Inline `nosemgrep` suppressions are reserved for bounded intentional exceptions. Put the suppression on the exact reported line and add a plain-language explanation immediately above it.
+
+</Callout>
+
+<DecisionTable
+  title="How routing expands"
+  columns={["Situation", "What usually happens", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Docs-only or workflow-only pull request",
+        "CI skips broad E2E by default and focuses on the relevant smaller lanes.",
+        "You avoid paying for cluster work that cannot fail for the files you touched.",
+      ],
+    },
+    {
+      cells: [
+        "PR touches backup, upgrades, security, provisioner, admission, or controller-critical code",
+        "Targeted E2E shards expand automatically.",
+        "Coverage follows the risk of the changed surface.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Maintainer adds `ci:full-e2e`",
+        "The broader E2E suite runs.",
+        "This is appropriate when the change spans enough surface area that targeted routing is no longer sufficient.",
+      ],
+    },
+    {
+      cells: [
+        "Nightly, edge, or tagged release flow",
+        "Publish channels add provenance, reproducibility, and release-oriented hardening gates.",
+        "Passing PR CI alone is not enough to publish artifacts.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Typical focused E2E reproductions"
+  code={`make test-e2e-ci \\
+  KIND_NODE_IMAGE=kindest/node:v1.35.1 \\
+  E2E_LABEL_FILTER='(((lifecycle && !tls) || manager) && !openshift)' \\
+  E2E_PARALLEL_NODES=2
+
+make helm-e2e-smoke
+
+make fuzz
+FUZZ_TARGET_FILTER='FuzzDiscoverConfig|internal/service/upgrade' make fuzz`}
+>
+  Choose the smallest reproduction that still matches the CI lane under investigation.
+</CommandBlock>
+
+CI E2E shards write both JUnit and Ginkgo JSON reports under the uploaded E2E artifact. The workflow summary includes the selected label filter, spec counts, failures, and the slowest specs. Local reproductions can use the same report path variables:
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Local E2E report output"
+  code={`make test-e2e-ci \\
+  E2E_LABEL_FILTER='lifecycle && !openshift' \\
+  E2E_JUNIT_REPORT=artifacts/e2e-reports/local/junit.xml \\
+  E2E_JSON_REPORT=artifacts/e2e-reports/local/ginkgo.json \\
+  E2E_FAIL_ON_EMPTY=true`}
+>
+  Use `go run ./hack/tools/e2e_report --json-report artifacts/e2e-reports/local/ginkgo.json` to render the same Markdown summary locally.
+</CommandBlock>
+
+The E2E suite manifest is validated in `ci-core` through `make verify-e2e-manifest`. That check regenerates the catalog from `ginkgo outline`, validates `test/e2e/suites.yaml`, generates the GitHub Actions PR and nightly E2E matrices, and fails if suite ownership, labels, coverage tags, risk tier, isolation class, or routing metadata drift.
+
+The same manifest owns E2E parallelism. Matrix rows include `parallel_nodes`, and CI passes that value to `E2E_PARALLEL_NODES`. Lanes may use more than one Ginkgo process only when every assigned suite is declared `parallel-safe` or `serial`; shared-cluster, global-mutator, external-cluster, and multi-cluster suites stay single-process until their isolation model changes.
+
+Lanes may also declare `prLabelFilter` for pull-request routing. CI uses that optimized filter unless a full E2E run is requested or the run is for `main`; nightly and release-gate profiles continue to use the full lane `labelFilter`.
+
+Nightly E2E routing is manifest-driven. The daily profile runs full coverage on the primary Kubernetes version and compatibility smoke rows on adjacent supported versions. The weekly profile runs full compatibility coverage across supported Kubernetes versions. Maintainers can manually dispatch the release-gate profile, optionally filtered to one lane or one Kubernetes version while preserving the same manifest validation.
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect generated E2E matrices"
+  code={`make e2e-ci-matrix
+make e2e-nightly-matrix E2E_NIGHTLY_PROFILE=daily
+make e2e-nightly-matrix E2E_NIGHTLY_PROFILE=weekly-full
+make e2e-nightly-matrix \\
+  E2E_NIGHTLY_PROFILE=release-gate \\
+  E2E_NIGHTLY_LANE=core \\
+  E2E_NIGHTLY_KUBERNETES=1.35.1`}
+>
+  Use these before changing `test/e2e/suites.yaml` or workflow routing.
+</CommandBlock>
+
+`test/e2e/suites.yaml` owns the E2E version policy. Keep the OpenBao default image and the active Kind Kubernetes versions under `versions` instead of repeating concrete versions in each profile. The nightly profiles should reference `@primary`, `@compatibility`, and `@releaseGate`; update those central sets when Kind publishes a new runnable node image.
+
+<NextActions
+  title="After CI parity"
+  items={[
+    {
+      label: "Testing strategy",
+      description: "Testing strategy covers validation depth before it is mapped to a workflow.",
+      to: "/contribute/testing",
+    },
+    {
+      label: "Release management",
+      description: "Release management covers release execution, docs snapshots, and post-publish verification.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Dependency license policy",
+      description: "Dependency license policy covers shipped-license allowlists and their enforcement.",
+      to: "/contribute/dependency-licenses",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/dependency-licenses.md b/website/versioned_docs/version-0.3.0/contribute/dependency-licenses.md
new file mode 100644
index 000000000..57ac69c5c
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/dependency-licenses.md
@@ -0,0 +1,177 @@
+---
+title: Dependency License Policy
+description: License policy for shipped OpenBao Operator dependencies, including the allowlist, special handling for MPL-2.0, blocked license classes, and local verification steps.
+pageType: reference
+journey: contribute
+---
+
+<PageHeader
+  title="Dependency license policy"
+  lede="Allowed license classes, MPL-2.0 handling, and the checks maintainers expect when dependency changes are proposed."
+/>
+
+<Callout type="note" title="Policy, not legal advice">
+
+This is project policy for contributors and maintainers. It does not replace legal review.
+
+</Callout>
+
+<DecisionTable
+  title="License policy summary"
+  kind="reference"
+  columns={["License class", "Project policy", "Contributor action"]}
+  rows={[
+    {
+      cells: [
+        "Permissive licenses such as `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MIT`, and `Unicode-DFS-2016`",
+        "Allowed by default for shipped binaries.",
+        "Keep notices intact and still run the normal verification flow.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`MPL-2.0`",
+        "Allowed with explicit maintainer care because it is file-level copyleft, not whole-program copyleft.",
+        "Preserve notices, avoid casual vendored patches, and call out the dependency explicitly in the PR.",
+      ],
+    },
+    {
+      cells: [
+        "Strong copyleft, source-available, field-of-use restricted, unknown, or unrecognized licenses",
+        "Not allowed for shipped dependencies.",
+        "Do not merge until the dependency is removed or replaced.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Scope
+
+The blocking license gate covers shipped Go binaries:
+
+- `./cmd/controller`
+- `./cmd/bao-backup`
+- `./cmd/bao-upgrade`
+- `./cmd/provisioner`
+
+Use vendored mode when evaluating the policy so local results match build and release behavior.
+
+## Allowed licenses
+
+These licenses are allowed without additional license-specific review:
+
+- `Apache-2.0`
+- `BSD-2-Clause`
+- `BSD-3-Clause`
+- `ISC`
+- `MIT`
+- `Unicode-DFS-2016`
+
+## Allowed with obligations
+
+`MPL-2.0` is allowed, but maintainers expect explicit handling:
+
+1. Do not patch vendored `MPL-2.0` files casually.
+2. Do not copy `MPL-2.0` code into first-party project files without explicit review.
+3. Preserve upstream license and notice files during redistribution.
+4. If modified `MPL-2.0` files are redistributed, keep corresponding source for those modified files available as required by the license.
+5. Call out newly introduced `MPL-2.0` dependencies in the PR description so the review trail is explicit.
+
+## Forbidden licenses
+
+Do not ship dependencies under these licenses or license classes:
+
+- `GPL-2.0`
+- `GPL-3.0`
+- `AGPL-3.0`
+- `LGPL-2.1`
+- `LGPL-3.0`
+- `SSPL`
+- `BUSL` / `BSL`
+- `Elastic License`
+- `Commons-Clause`
+- non-commercial, no-derivatives, field-of-use-restricted, or source-available-only licenses
+- `Unknown`, `NOASSERTION`, and custom or unrecognized licenses
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Local license verification"
+  code={`make verify-vendor
+make license-check
+make license-report`}
+>
+  `make license-check` is the canonical full-tree gate for this repository. `make license-report` writes the report and stderr log under `dist/licenses/`.
+</CommandBlock>
+
+<DecisionTable
+  title="How the policy is enforced"
+  kind="reference"
+  columns={["Enforcement layer", "What it checks", "Implementation surface"]}
+  rows={[
+    {
+      cells: [
+        "Pull-request dependency review",
+        "Newly introduced dependency vulnerabilities in package manifests and lockfiles.",
+        "`.github/workflows/dependency-review.yml` and `.github/dependency-review-config.yml`.",
+      ],
+    },
+    {
+      cells: [
+        "Vendored full-tree gate",
+        "The shipped dependency graph for project binaries in the same mode used by build and release paths.",
+        "`make license-check` with `go-licenses`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Documentation and maintainer review",
+        "Policy intent, special cases such as `MPL-2.0`, and explicit approval of allowlist changes.",
+        "This policy, PR review, and matching CI configuration updates.",
+      ],
+    },
+  ]}
+/>
+
+## Updating the policy
+
+Treat allowlist changes as maintainer-level changes. When you change the allowed or forbidden set:
+
+1. Explain the change in the PR description.
+2. Update this document in the same PR.
+3. Update the matching machine-enforced CI configuration.
+
+## GitHub dependency review scope
+
+The GitHub dependency review workflow is currently used as a pull-request
+vulnerability gate, not as the canonical license gate. In practice, its npm
+license metadata is not reliable enough for this repository's documentation-site
+dependencies.
+
+License policy is still enforced, but the authoritative check is the shipped
+artifact workflow around `make license-check` and maintainer review of
+dependency-policy changes.
+
+<NextActions
+  title="Related governance pages"
+  items={[
+    {
+      label: "Supply chain security",
+      description: "See how dependency policy fits into the larger artifact-trust model.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      label: "Release management",
+      description: "Use the release workflow when a dependency change is already on the path to publication.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Project governance",
+      description: "Return to the governance landing page for the broader policy and maintainer map.",
+      to: "/contribute/project-governance",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/distribution.md b/website/versioned_docs/version-0.3.0/contribute/distribution.md
new file mode 100644
index 000000000..ef813686b
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/distribution.md
@@ -0,0 +1,126 @@
+---
+title: Distribution
+description: Distribution model for OpenBao Operator, including Artifact Hub, GHCR Helm OCI publication, verified ownership metadata, and intentionally deferred public OperatorHub publication.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Current distribution model"
+  lede="OpenBao Operator uses an Artifact Hub-first distribution model. OCI Helm chart releases are published to GHCR, indexed in Artifact Hub for discovery, and OLM bundle assets remain in-repo and CI-validated rather than being part of the current supported publication surface."
+/>
+
+<DecisionTable
+  title="Distribution surfaces"
+  columns={["Surface", "Published now", "Current role"]}
+  rows={[
+    {
+      cells: [
+        "GHCR OCI Helm chart",
+        "Yes",
+        "Canonical chart publication target for released versions.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Artifact Hub package entry",
+        "Yes",
+        "Discovery and installation entry point for the published chart.",
+      ],
+    },
+    {
+      cells: [
+        "GitHub Release assets",
+        "Yes",
+        "Installer manifests, CRDs, checksums, SBOMs, and provenance metadata.",
+      ],
+    },
+    {
+      cells: [
+        "OLM bundle assets",
+        "Kept in-repo and CI-validated",
+        "Preparation surface only; not yet a public distribution contract.",
+      ],
+    },
+    {
+      cells: [
+        "Public OperatorHub submission",
+        "No",
+        "Explicitly deferred until post-pre-GA maturity and support posture are ready.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Callout type="note" title="Artifact Hub first">
+
+The project currently treats Artifact Hub plus GHCR Helm OCI publication as the supported public discovery model. Do not add new public distribution expectations without updating this policy and the release flow that backs it.
+
+</Callout>
+
+<Callout type="note" title="Installer manifests are channel artifacts">
+
+`dist/install.yaml` and `dist/crds.yaml` are local build outputs, not source-controlled distribution assets. Release, edge, and nightly workflows generate fresh manifests from `config/` with the target image and operator version, then publish those generated files through the relevant channel.
+
+</Callout>
+
+<DecisionTable
+  title="Artifact Hub metadata expectations"
+  columns={["Metadata area", "What must be present"]}
+  rows={[
+    {
+      cells: [
+        "Chart annotations",
+        "`artifacthub.io/category`, `license`, `operator`, `operatorCapabilities`, release changes, image metadata, CRD cards/examples, maintainers, and useful links.",
+      ],
+    },
+    {
+      cells: [
+        "Prerelease and security state",
+        "`artifacthub.io/prerelease` for prereleases, `artifacthub.io/changes` from the release-please changelog, and `artifacthub.io/containsSecurityUpdates` when applicable for the release.",
+      ],
+    },
+    {
+      cells: [
+        "Verified ownership",
+        "`artifacthub-repo.yml` with repository ID or ownership information published to the chart OCI path under the `artifacthub.io` tag.",
+      ],
+      emphasis: "recommended",
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Push Artifact Hub repository metadata for the OCI chart"
+  code={`oras push \\
+  ghcr.io/dc-tec/charts/openbao-operator:artifacthub.io \\
+  --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \\
+  artifacthub-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml`}
+>
+  Use this only when `artifacthub-repo.yml` changes or ownership metadata must be refreshed for the chart repository.
+</CommandBlock>
+
+<NextActions
+  title="After distribution review"
+  items={[
+    {
+      label: "Release management",
+      description: "Go back to the release workflow when you are publishing a version rather than changing distribution policy.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Supply chain security",
+      description: "Open the policy side when distribution changes affect provenance, signing, or verification expectations.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      label: "Dependency license policy",
+      description: "Use the governance policy if the published artifact surface changes what licenses are considered shipped.",
+      to: "/contribute/dependency-licenses",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/docs-style-guide.md b/website/versioned_docs/version-0.3.0/contribute/docs-style-guide.md
new file mode 100644
index 000000000..4e660916d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/docs-style-guide.md
@@ -0,0 +1,188 @@
+---
+title: OpenBao Operator Documentation Style Guide
+description: Editorial and page-design standards for OpenBao Operator documentation, including voice, page types, approved components, navigation language, and validation steps.
+pageType: reference
+journey: contribute
+---
+
+<PageHeader
+  title="Documentation style guide"
+  lede="The docs are written for platform engineers, SREs, operators, maintainers, and contributors doing real work. This guide defines the voice, page contracts, navigation language, and shared components that keep the documentation product coherent as it grows."
+/>
+
+<DecisionTable
+  title="Page types"
+  kind="reference"
+  columns={["Page type", "Use it for", "Expected shape"]}
+  rows={[
+    {
+      cells: [
+        "`landing`",
+        "Section entry and routing pages.",
+        "`PageHero`, a routing surface such as `RouteList` or `JourneyRail`, then `NextActions`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`task`",
+        "Installation, configuration, and procedural work.",
+        "When to use it, prerequisites, steps, verification, then next actions.",
+      ],
+    },
+    {
+      cells: [
+        "`concept`",
+        "Behavior, invariants, tradeoffs, and internal reasoning.",
+        "Scope, responsibilities, implications, and related tasks.",
+      ],
+    },
+    {
+      cells: [
+        "`runbook`",
+        "Incident diagnosis and recovery.",
+        "Trigger, diagnosis, recovery steps, verification, and escalation.",
+      ],
+    },
+    {
+      cells: [
+        "`reference`",
+        "Exact support data, policies, matrices, and schemas.",
+        "Short scope statement plus dense, precise content with minimal ornament.",
+      ],
+    },
+  ]}
+/>
+
+## Voice
+
+- Write for someone doing real work on a cluster or in the repository.
+- Prefer direct operational language over design commentary.
+- Use the imperative for instructions: `Run`, `Apply`, `Verify`, `Check`.
+- Keep explanations short enough to scan under time pressure.
+- Be lightly opinionated when the project has a recommended path.
+
+## Wording and headings
+
+- Keep the page title as needed for navigation, but use sentence case for headings below the page title.
+- Start sections with the decision, scope, or instruction itself. Do not spend the first sentence explaining that the section exists.
+- Prefer direct wording over evaluative filler. Replace words such as `strong`, `practical`, `useful`, `good`, and `mature` with the actual recommendation.
+- Reduce repeated `This page...`, `This section...`, and `The goal is...` framing when the heading or surrounding structure already provides that context.
+- Prefer direct verbs such as `Use`, `Keep`, `Limit`, `Reserve`, `Place`, and `Do not give` over repetitive `should` phrasing.
+- Prefer operational wording over abstract noun clusters. Name the action, object, or control directly.
+- Vary sentence length and cadence. Do not let every section open with the same balanced or three-part construction.
+- Keep one main idea per paragraph when possible.
+
+## Terms
+
+Use product and platform terms consistently:
+
+- `OpenBao Operator`
+- `OpenBao`
+- `Kubernetes` or `K8s`
+- `OpenBaoCluster`, `OpenBaoRestore`, `OpenBaoTenant`
+- `Hardened` and `Development` as profile names
+- `single-tenant` and `multi-tenant`
+
+## What to avoid
+
+- Explaining the docs system inside the docs.
+- Design commentary such as "the first job of the docs is routing".
+- Abstract language when concrete verbs such as `install`, `upgrade`, `restore`, or `troubleshoot` are clearer.
+- Slogan-heavy copy on normal pages.
+- `not X, but Y` framing when it does not clarify a real technical distinction.
+- Repeated evaluative framing such as "a strong baseline", "a practical model", "a useful default", or "a good starting point".
+- Opening sections by restating the heading before making a point.
+- Generic transition sentences that only restate the obvious benefit of the previous line.
+- Stacked hedging such as `usually`, `often`, `generally`, `typically`, and `in most cases` when the docs are describing the baseline recommendation.
+- Taxonomy or categorization that does not drive an actual operator or maintainer decision.
+
+## Metadata and shared components
+
+Use the Docusaurus frontmatter fields that support the docs system:
+
+```yaml
+---
+description: One sentence summary of the page intent.
+pageType: landing | task | concept | runbook | reference
+journey: get-started | operate | security | architecture | reference | contribute
+journeyStep: 1
+---
+```
+
+Prefer the shared components in `website/src/components`:
+
+- `PageHero`
+- `RouteList`
+- `JourneyRail`
+- `DecisionTable`
+- `CommandBlock`
+- `DiagramFrame`
+- `NextActions`
+- `Callout`
+- `Tabs`
+
+## Navigation language
+
+Route labels should be task-led whenever possible.
+
+Prefer:
+
+- `Install the operator`
+- `Plan upgrades`
+- `Recover from no leader`
+- `Open compatibility`
+
+Avoid:
+
+- `Learn more`
+- `Explore`
+- `Continue journey`
+- `Read this section`
+
+Section ownership:
+
+- `Get Started` takes a user from first choice to a day 2 baseline.
+- `Operate` owns routine operations, troubleshooting, recovery, and restore.
+- `Security` explains trust boundaries and production controls.
+- `Architecture` explains why the system behaves the way it does.
+- `Reference` stores exact facts, policies, and schemas.
+- `Contribute` is for maintainers and contributors, not operators.
+
+## Validation
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Docs preview and validation"
+  code={`make docs-serve
+make docs-preview
+make docs-build
+
+npm --prefix website run typecheck
+npm --prefix website run build
+npm --prefix website run test:e2e`}
+>
+  Use `make docs-serve` for the fast authoring loop. Use `make docs-preview` when you need production-style behavior such as local search. Run the full site checks before merging structural or high-traffic documentation changes.
+</CommandBlock>
+
+<NextActions
+  title="Related contributor pages"
+  items={[
+    {
+      label: "Contribute",
+      description: "Return to the contributor landing page for the full maintainer and contributor map.",
+      to: "/contribute",
+    },
+    {
+      label: "Generated artifacts",
+      description: "Use the generation guide when docs changes also affect emitted reference or chart output.",
+      to: "/contribute/standards/generated-artifacts",
+    },
+    {
+      label: "Validate & Ship",
+      description: "Open the release and CI section when the documentation change also affects verification or publication flow.",
+      to: "/contribute/validate-and-ship",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/getting-started/development.md b/website/versioned_docs/version-0.3.0/contribute/getting-started/development.md
new file mode 100644
index 000000000..174686297
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/getting-started/development.md
@@ -0,0 +1,222 @@
+---
+title: Setting Up Your Environment
+description: Contributor environment setup for OpenBao Operator, including prerequisites, recommended development loops, local verification, and troubleshooting.
+pageType: task
+journey: contribute
+---
+
+<PageHeader
+  title="Contributor workstation setup"
+  lede="Start by bootstrapping the repository-managed tools, then choose the smallest development loop that matches your task. Most contributor work does not need a full cluster deployment on the first edit, although webhooks, RBAC, networking, and lifecycle behavior usually do."
+/>
+
+## Prerequisites
+
+Required tools:
+
+- Go `1.26.3+`
+- Docker `28.3.3+`
+- `kubectl` `1.33+`
+- Helm `3+`
+- Trivy
+- Python `3`
+- Node.js `20+` with `npm`
+- a Kubernetes cluster such as Kind, Minikube, or a cloud cluster
+
+Optional but recommended:
+
+- Kind for local E2E work
+- k9s for cluster inspection
+- Tilt for the fast in-cluster inner loop
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Bootstrap the repository-managed toolchain"
+  code={`make bootstrap
+make doctor`}
+>
+  Run this first on a new machine, inside a fresh devcontainer, or after toolchain changes. `make bootstrap` also installs the repo-local Git hooks from `.githooks/`, including the pre-commit check for staged Go formatting plus targeted linting and the pre-push `make lint-ci` gate. Use `OPENBAO_OPERATOR_SKIP_PRE_COMMIT=1` or `OPENBAO_OPERATOR_SKIP_PRE_PUSH=1` only for deliberate one-off bypasses. `make doctor` is the quickest way to see what is still missing locally.
+</CommandBlock>
+
+<DecisionTable
+  title="Choose a development loop"
+  columns={["Use this loop", "Best for", "Main command path"]}
+  rows={[
+    {
+      cells: [
+        "Local controller on your host",
+        "Fast logic changes, renderer work, and controller behavior that does not depend on webhook reachability or cluster-local network policy.",
+        "`make install` then `make run-controller`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "In-cluster integration loop",
+        "RBAC, webhook, lifecycle, and deployment behavior where the controller must run as a Pod inside the cluster.",
+        "Build image, load it into Kind, then `make deploy IMG=...`.",
+      ],
+    },
+    {
+      cells: [
+        "Tilt fast cluster loop",
+        "Repeated controller changes against a local cluster when you want rebuilds, deploys, logs, and helper actions in one UI.",
+        "`make tilt-up` and `make tilt-down`.",
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Fast local controller loop"
+  code={`git clone https://github.com/dc-tec/openbao-operator.git
+cd openbao-operator
+
+make bootstrap
+make doctor
+make install
+make run-controller`}
+>
+  This is the default contributor loop. It is fast, but it does not fully represent webhook reachability or cluster-local network behavior.
+</CommandBlock>
+
+<Callout type="warning" title="Local loop limitations">
+
+When the controller runs on your host, validating webhooks usually need additional tunneling or a different deployment path. NetworkPolicies are also not realistically tested from this loop.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="In-cluster integration loop"
+  code={`kind create cluster --name openbao-dev
+
+make bootstrap
+make doctor
+make docker-build IMG=openbao-operator:dev
+kind load docker-image openbao-operator:dev --name openbao-dev
+make deploy IMG=openbao-operator:dev
+
+kubectl get pods -n openbao-operator-system`}
+>
+  Use this when the feature depends on cluster-local execution, admission behavior, or realistic operator RBAC.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Tilt fast cluster loop"
+  code={`make bootstrap
+make doctor
+make tilt-up
+
+# optional helper image override
+tilt up -- --operator-version=edge
+
+make tilt-down`}
+>
+  Tilt is the best inner loop when you expect several controller edits against the same local cluster and want logs, deploy state, and helper actions in one place.
+</CommandBlock>
+
+<DecisionTable
+  title="High-value local commands"
+  kind="reference"
+  columns={["Area", "Command", "What it gives you"]}
+  rows={[
+    {
+      cells: [
+        "Core verification",
+        "`make ci-core`",
+        "The default local PR-equivalent gate except E2E.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Unit and integration",
+        "`make test`, `make test-integration`, `make test-sum`, `make test-integration-sum`",
+        "Targeted test coverage with optional JUnit output under `dist/test/`.",
+      ],
+    },
+    {
+      cells: [
+        "Security static analysis",
+        "`make semgrep-scan`, `make semgrep-ci`, `make security-ci`",
+        "Use `make semgrep-scan` for a report-only pass, `make semgrep-ci` for the blocking repo-wide Semgrep gate across runtime, config, and CI surfaces, or `make security-ci` for the full CI-equivalent security lane with vulncheck, license checks, Semgrep, and Trivy.",
+      ],
+    },
+    {
+      cells: [
+        "Controller debugging",
+        "`make air-controller`, `make debug-controller`, `make debug-test PKG=... TEST=...`",
+        "Live reload or Delve-based debugging for controller and test work.",
+      ],
+    },
+    {
+      cells: [
+        "Architecture policy",
+        "`make generate-ast-rules`, `make verify-arch-policy`, `make report-internal-deps`",
+        "Boundary verification plus a local dependency report for internal package drift.",
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Architecture report and policy verification"
+  code={`make report-internal-deps
+make report-internal-deps-snapshot
+make report-internal-deps-diff
+
+make generate-ast-rules
+make verify-arch-policy
+make test-ast
+make lint-ast`}
+>
+  Use this when you change controller wiring, add new `internal/*` package boundaries, or want to compare package drift across a refactor.
+</CommandBlock>
+
+<ExpandableCallout type="question" title="RBAC errors during `make deploy`?">
+
+Make sure the current kubeconfig identity has enough privileges to install CRDs, RBAC, and admission resources.
+
+</ExpandableCallout>
+
+<ExpandableCallout type="question" title="Webhooks failing locally?">
+
+Switch from the host-based loop to the in-cluster loop. Webhook traffic needs the API server to reach the operator inside the cluster network.
+
+</ExpandableCallout>
+
+<ExpandableCallout type="question" title="How do I confirm my workstation is still healthy?">
+
+Run `make doctor`. It reports missing external tools and which contributor workflows they block.
+
+</ExpandableCallout>
+
+<NextActions
+  title="After your environment works"
+  items={[
+    {
+      label: "Testing strategy",
+      description: "Choose the smallest test layer that proves the change you are about to make.",
+      to: "/contribute/testing",
+    },
+    {
+      label: "Project conventions",
+      description: "Review the repository-specific rules that shape how code, generated files, and reviews should look.",
+      to: "/contribute/standards/project-conventions",
+    },
+    {
+      label: "Continuous integration",
+      description: "Open the CI map when you need to understand how local checks expand into branch and release workflows.",
+      to: "/contribute/ci",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/getting-started/index.md b/website/versioned_docs/version-0.3.0/contribute/getting-started/index.md
new file mode 100644
index 000000000..7ed0bd4bc
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/getting-started/index.md
@@ -0,0 +1,117 @@
+---
+title: Getting Started with Contributing
+description: First-time contributor path for OpenBao Operator, including workstation setup, first local checks, and where to go after the environment is ready.
+pageType: landing
+journey: contribute
+---
+
+<PageHero
+  eyebrow="Contribute / Start Here"
+  title="Contributor setup"
+  lede="Prepare a workstation, create a first branch, and run the initial local checks."
+  actions={[
+    {label: "Set up your environment", to: "/contribute/getting-started/development", variant: "primary"},
+    {label: "Open testing strategy", to: "/contribute/testing", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Use this page to"
+    items={[
+      "prepare the required local tools for repo-managed commands",
+      "understand the first commands maintainers expect you to run on a clean clone",
+      "see the basic contribution path before diving into standards or CI details",
+      "find the right next page once the environment itself is working",
+    ]}
+  />
+</PageHero>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="PR-equivalent local gate"
+  code={`make bootstrap
+make doctor
+make ci-core`}
+>
+  Use this as the baseline local proof for a new branch or workstation setup.
+</CommandBlock>
+
+<RouteList
+  title="Core path"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Set up your environment",
+      description: "Install the required tools, use the repo-managed bootstrap flow, and verify that your local environment is actually healthy.",
+      to: "/contribute/getting-started/development",
+    },
+    {
+      eyebrow: "02",
+      title: "Learn the coding rules",
+      description: "Read the project conventions, code standards, and generated-artifact rules before reshaping code or manifests.",
+      to: "/contribute/standards",
+    },
+    {
+      eyebrow: "03",
+      title: "Understand the testing stack",
+      description: "Know which layers to run locally and what CI is going to enforce for the branch.",
+      to: "/contribute/testing",
+    },
+    {
+      eyebrow: "04",
+      title: "Open a clean branch",
+      description: "Use the commit and change-management rules the project expects once your local setup is stable.",
+      to: "/contribute/standards/conventional-commits",
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Contribution lanes"
+  columns={["Type", "What it usually changes", "Read this next"]}
+  rows={[
+    {
+      cells: [
+        "Code changes",
+        "Controller logic, APIs, adapters, reconciliation behavior, tests, or generated assets.",
+        "Open the coding standards and testing strategy.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Documentation changes",
+        "User guides, contributor docs, IA work, examples, or style fixes.",
+        "Open the documentation style guide and contributor standards.",
+      ],
+    },
+    {
+      cells: [
+        "Maintainer work",
+        "Release flow, CI changes, distribution policy, or supply-chain controls.",
+        "Open Validate & Ship and Project Governance.",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="After setup"
+  items={[
+    {
+      label: "Set up your environment",
+      description: "Use the detailed setup page for tools, versions, and local cluster guidance.",
+      to: "/contribute/getting-started/development",
+    },
+    {
+      label: "Coding standards",
+      description: "Read the project rules for code and docs changes.",
+      to: "/contribute/standards",
+    },
+    {
+      label: "Testing strategy",
+      description: "Map your change to the right unit, integration, E2E, or manual validation layer.",
+      to: "/contribute/testing",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/index.mdx b/website/versioned_docs/version-0.3.0/contribute/index.mdx
new file mode 100644
index 000000000..bf46210ef
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/index.mdx
@@ -0,0 +1,84 @@
+---
+title: Contribute
+slug: /
+description: Contributor and maintainer documentation for OpenBao Operator, covering local setup, coding standards, testing, release flow, and project governance.
+pageType: landing
+journey: contribute
+---
+
+<PageHero
+  eyebrow="Contribute"
+  title="Contributor documentation"
+  lede="Local setup, coding standards, testing, release workflows, and project governance for contributors and maintainers."
+  actions={[
+    {label: "Start here", to: "/contribute/getting-started", variant: "primary"},
+    {label: "Open testing strategy", to: "/contribute/testing", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Common uses"
+    items={[
+      "set up a clean contributor environment for your first change",
+      "follow the project conventions for code, docs, tests, and generated artifacts",
+      "run the right local checks before handing the branch to CI or maintainers",
+      "understand release, supply-chain, and policy material when you are maintaining the project itself",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Contributor routes"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Start Here",
+      description: "First-time contributor setup, local tooling, and the shortest path to a clean branch with passing baseline checks.",
+      to: "/contribute/getting-started",
+    },
+    {
+      eyebrow: "02",
+      title: "Build & Change",
+      description: "Coding standards, project conventions, docs rules, and generated-artifact guidance for day-to-day development work.",
+      to: "/contribute/standards",
+    },
+    {
+      eyebrow: "03",
+      title: "Validate & Ship",
+      description: "Testing strategy, CI behavior, release execution, and distribution guidance for contributor and maintainer workflows.",
+      to: "/contribute/validate-and-ship",
+    },
+    {
+      eyebrow: "04",
+      title: "Project Governance",
+      description: "SDLC, supply-chain controls, and dependency policy for maintainers changing how the project is run and published.",
+      to: "/contribute/project-governance",
+    },
+  ]}
+/>
+
+<Callout type="note" title="AI-assisted contributions">
+
+AI assistance is welcome, but the submitter remains responsible for correctness, security, testing, and adherence to project standards.
+
+</Callout>
+
+<NextActions
+  title="Common starting points"
+  items={[
+    {
+      label: "Set up environment",
+      description: "Bootstrap the repo-managed tools and verify your workstation for a new change.",
+      to: "/contribute/getting-started/development",
+    },
+    {
+      label: "Coding standards",
+      description: "Project rules beyond standard Go style.",
+      to: "/contribute/standards",
+    },
+    {
+      label: "Testing strategy",
+      description: "Project testing model and local PR-equivalent checks.",
+      to: "/contribute/testing",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/project-governance.mdx b/website/versioned_docs/version-0.3.0/contribute/project-governance.mdx
new file mode 100644
index 000000000..994351f2c
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/project-governance.mdx
@@ -0,0 +1,72 @@
+---
+title: Project Governance
+description: Maintainer-focused documentation for OpenBao Operator project policy, SDLC, supply-chain controls, and dependency license governance.
+pageType: landing
+journey: contribute
+---
+
+<PageHero
+  eyebrow="Contribute / Project Governance"
+  title="Project governance and policy"
+  lede="SDLC, supply-chain controls, and dependency license policy for OpenBao Operator."
+  actions={[
+    {label: "Open SDLC", to: "/contribute/sdlc", variant: "primary"},
+    {label: "Open supply chain security", to: "/contribute/supply-chain-security", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Covers"
+    items={[
+      "secure development and release flow across the project lifecycle",
+      "supply-chain controls, provenance expectations, and reproducibility requirements",
+      "dependency license policy for shipped binaries",
+      "maintainer and policy work outside day-to-day feature development",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Project governance guides"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Software development lifecycle",
+      description: "Planning, implementation, verification, release, and operations in the project lifecycle.",
+      to: "/contribute/sdlc",
+    },
+    {
+      eyebrow: "02",
+      title: "Supply chain security",
+      description: "Review provenance, reproducibility, signing, evidence, and release-control expectations.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      eyebrow: "03",
+      title: "Supply-chain incident response",
+      description: "Maintainer runbook for freezing Actions, suspending release automation, rotating trust roots, or inspecting publication state.",
+      to: "/contribute/supply-chain-incident-response",
+    },
+    {
+      eyebrow: "04",
+      title: "Dependency license policy",
+      description: "Understand which licenses are allowed for shipped binaries and how the policy is enforced.",
+      to: "/contribute/dependency-licenses",
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related maintainer work"
+  items={[
+    {
+      label: "Release management",
+      description: "Release workflow for turning policy into an actual release event.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Continuous integration",
+      description: "CI implementation that enforces many of these policy expectations in practice.",
+      to: "/contribute/ci",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/release-management.md b/website/versioned_docs/version-0.3.0/contribute/release-management.md
new file mode 100644
index 000000000..c49472d48
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/release-management.md
@@ -0,0 +1,253 @@
+---
+title: Release Management
+description: Maintainer release workflow for OpenBao Operator, including release-please, stable docs snapshots, channel behavior, artifact verification, and post-release checks.
+pageType: task
+journey: contribute
+---
+
+<PageHeader
+  title="Release management workflow"
+  lede="Build-once, promote-everywhere release workflow covering versioning, changelog state, release orchestration, signing, docs deployment, and release evidence."
+/>
+
+<Callout type="note" title="Maintainer workflow">
+
+[Release Policy](pathname:///docs/next/reference/release-policy) covers the public release cadence, channel rules, and stable release gates. The steps below cover the maintainer workflow once a release is being executed.
+
+</Callout>
+
+<DiagramFrame
+  title="Build once, promote everywhere"
+  caption="Release workflows build immutable artifacts first, then gate, sign, and publish by digest."
+  code={`graph TD
+    PR["Release-please PR merged"] --> Tagger["Tag workflow"]
+    Tagger --> Tag["Git tag + draft GitHub Release"]
+    Tag --> Build["Build once"]
+    Build --> Gates["Security, E2E, performance, reproducibility"]
+    Gates --> Promote["Promote by digest"]
+    Promote --> Sign["Sign and attest"]
+    Sign --> Publish["GitHub Release, GHCR, docs, metadata"]`}
+/>
+
+<DecisionTable
+  title="Release channels"
+  columns={["Channel", "Trigger", "What it publishes", "Operational rule"]}
+  rows={[
+    {
+      cells: [
+        "Stable release",
+        "Merge the release-please PR so the `Release Tag` workflow can resolve the merged release PR, create the signed stable version tag, and create the draft GitHub Release from `main` or a `release-*` branch.",
+        "GitHub Release assets, OCI Helm chart, signed images, stable docs snapshot, docs deployment, and provenance evidence.",
+        "Stable releases become permanent release-line docs and own the default `/docs` route.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Patch release",
+        "Backport the targeted fixes to the relevant `release-*` branch, then use the `Prepare Release-As PR` workflow to create the auditable `Release-As: X.Y.Z` marker PR.",
+        "Same release artifacts as stable releases, built from the patch branch tag.",
+        "Keep the patch branch narrow; patch releases in an existing stable line reuse that line's docs snapshot.",
+      ],
+    },
+    {
+      cells: [
+        "Prerelease",
+        "Prefer the `Prepare Release-As PR` workflow to create a tiny PR that carries an empty commit with `Release-As: 0.1.0-rc.6`, then merge the resulting release-please PR so the `Release Tag` workflow creates the signed prerelease tag and draft GitHub Release.",
+        "GitHub Release assets, OCI Helm chart, signed images, docs site deployment, and provenance evidence.",
+        "Prereleases use `/docs/next` plus release notes; do not create a permanent versioned docs snapshot.",
+      ],
+    },
+    {
+      cells: [
+        "Edge",
+        "CI success on `main`.",
+        "Mutable and immutable edge manifests plus signed images and provenance metadata.",
+        "Pre-release validation channel; production support expectations remain with stable releases.",
+      ],
+    },
+    {
+      cells: [
+        "Nightly",
+        "Nightly validation success.",
+        "Nightly manifests, tags, and provenance metadata.",
+        "Scheduled validation and drift-detection channel; stable releases remain the publication path.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="important" title="Stable release-line docs snapshots">
+
+Before merging the first stable `X.Y.0` release PR for a release line, snapshot the docs for that release line and commit the generated artifacts. Patch releases in the same line reuse the `X.Y.0` docs version, but user-facing docs fixes for that patch must refresh the existing `X.Y.0` snapshot from the release branch. Prereleases continue to use `/docs/next` and release notes only; do not add patch, `-alpha`, `-beta`, or `-rc` entries to `website/versions.json`.
+
+</Callout>
+
+<Callout type="note" title="Patch branch workflow state">
+
+GitHub Actions runs workflow definitions from the branch that receives the push. Before using release-please on an older `release-*` branch for the first time, make sure the branch contains the current release workflow support, including `Release Please PR`, `Release Tag`, and `Prepare Release-As PR` behavior.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Snapshot docs for the stable release line"
+  code={`make docs-version DOCS_VERSION=X.Y.0`}
+>
+  This updates `website/versioned_docs/`, `website/versioned_sidebars/`, and `website/versions.json`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Refresh docs for a patch release line"
+  code={`git switch release-X.Y
+make docs-refresh-version DOCS_VERSION=X.Y.0`}
+>
+  Run this from the release branch after backporting docs that apply to the patch release. This updates the existing release-line docs snapshot without adding a patch version to `website/versions.json`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Cut an explicit release with a Release-As PR"
+  code={`# In GitHub Actions, run:
+# Prepare Release-As PR
+#
+# target_branch: main        # or release-0.2
+# version: 0.1.0-rc.6       # or 0.2.1`}
+>
+  This workflow creates a tiny PR containing an empty `Release-As: <version>` commit. Merge that marker PR first; the branch-aware Release Please workflow then opens or updates the real release PR.
+</CommandBlock>
+
+<Callout type="note" title="`workflow_dispatch` `release_as` path">
+
+`Release Please PR` still exposes a `workflow_dispatch` `release_as` input, but maintainers should prefer the `Prepare Release-As PR` workflow. The marker PR leaves the version override in git history and works consistently for `main` and `release-*` branches.
+
+</Callout>
+
+<Callout type="note" title="Helm chart changelog">
+
+Release-please remains the source of truth for release notes. After release-please opens or updates a release PR, the `Release Please PR` workflow syncs `charts/openbao-operator/Chart.yaml` so Artifact Hub receives `artifacthub.io/changes`, image metadata, prerelease state, and security-update state from the release-please changelog.
+
+</Callout>
+
+<Callout type="note" title="Human release notes">
+
+Keep `CHANGELOG.md` generated by release-please. Put hand-written release summaries, migration notes, and operator-facing callouts in `release-notes/X.Y.Z.md`; the website release generator and draft GitHub Release creation prepend that file to the generated changelog entry for the matching version.
+
+For patch releases, make the source that release-please sees match the release note you want. Prefer one cherry-picked conventional commit per user-facing fix. If a backport PR is squash-merged, make the squash title deliberately user-facing because it becomes the generated changelog entry. Use `release-notes/X.Y.Z.md` for extra context, but do not hand-edit generated `CHANGELOG.md` sections.
+
+</Callout>
+
+<DecisionTable
+  title="Release manager checklist"
+  columns={["Stage", "What to prove before moving on"]}
+  rows={[
+    {
+      cells: [
+        "Pre-flight",
+        "Release-please PR looks correct, docs are updated, new stable release lines have a committed `X.Y.0` docs snapshot, compatibility docs are current, CI is green, full E2E release evidence is clean, nightly regressions are reviewed, and performance findings are either cleared or explicitly accepted by maintainers.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Publish",
+        "Release workflow passes the `release-publish` environment gate, then tags, signs, attests, publishes assets, and keeps chart/app versions aligned with the git tag.",
+      ],
+    },
+    {
+      cells: [
+        "Post-release",
+        "GitHub Release exists, assets verify, provenance evidence is recorded, Artifact Hub metadata is visible, no unexpected release-please PR or branch remains, and announcement links are captured.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Run post-release verification"
+  code={`VERSION=X.Y.Z REPO=dc-tec/openbao-operator hack/ci/verify-post-release.sh`}
+>
+  Requires `gh`, `jq`, `git`, Docker Buildx, and `cosign`. Checks the remote tag, published GitHub Release assets, checksum signature, OCI Helm chart publication and signature, and leftover release-please PRs or branches.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Post-release verification skeleton"
+  code={`IMAGE="ghcr.io/dc-tec/openbao-operator@sha256:<digest>"
+CHART="ghcr.io/dc-tec/charts/openbao-operator@sha256:<digest>"
+
+cosign verify \\
+  --new-bundle-format=true \\
+  --certificate-identity "https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/X.Y.Z" \\
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \\
+  "\${IMAGE}"
+
+gh attestation verify "oci://\${CHART}" \\
+  --repo dc-tec/openbao-operator \\
+  --signer-workflow dc-tec/openbao-operator/.github/workflows/release.yml \\
+  --source-ref refs/tags/X.Y.Z \\
+  --cert-oidc-issuer https://token.actions.githubusercontent.com \\
+  --deny-self-hosted-runners
+
+jq '.release, .identity_constraints, .images, .chart, .release_artifacts.checksums_txt' provenance-index.json`}
+>
+  Verify images, charts, checksums, and the provenance index against the exact tag and workflow identity used for the release.
+</CommandBlock>
+
+## Verifying artifacts {#5-verifying-artifacts}
+
+Run `hack/ci/verify-post-release.sh` first and use the verification skeleton above for deeper spot checks or release evidence capture. Keep the exact workflow identity, tag ref, and digest-pinned subjects aligned with the artifacts that were just published. Once the release is fully published, delete the matching `release-please--branches--<base>` branch unless release-please still has an active release PR for that base branch.
+
+<Callout type="note" title="release-please token requirements">
+
+Release automation must use non-default tokens so the resulting tag and GitHub Release can trigger downstream workflows. Use two repo-scoped GitHub Apps:
+
+- `OPENBAO_OPERATOR_RELEASE_PR_CLIENT_ID` and `OPENBAO_OPERATOR_RELEASE_PR_PRIVATE_KEY` for PR-only `release-please`
+- `OPENBAO_OPERATOR_RELEASE_TAG_CLIENT_ID` and `OPENBAO_OPERATOR_RELEASE_TAG_PRIVATE_KEY` for the custom `Release Tag` workflow
+
+The tag app should be the only actor with semver tag ruleset bypass, and it only needs repository `contents: write`.
+
+Signed release tags also require these repo secrets:
+
+- `OPENBAO_OPERATOR_RELEASE_TAG_GPG_PRIVATE_KEY` - armored private key for the dedicated release-signing identity
+- `OPENBAO_OPERATOR_RELEASE_TAG_GPG_PASSPHRASE` - passphrase for that private key
+- `OPENBAO_OPERATOR_RELEASE_TAG_GPG_NAME` - tagger name to write into signed release tags
+- `OPENBAO_OPERATOR_RELEASE_TAG_GPG_EMAIL` - tagger email to write into signed release tags
+
+Upload the matching public key to the GitHub identity that should show the `Verified` badge for release tags. Prefer a dedicated release-signing key instead of a day-to-day maintainer key. A PAT fallback is possible through `RELEASE_PLEASE_TOKEN`, but a bot identity is safer than a maintainer’s personal token.
+
+</Callout>
+
+<NextActions
+  title="After release execution"
+  items={[
+    {
+      label: "Release policy",
+      description: "Release policy covers cadence and release-gate rules.",
+      to: "/docs/next/reference/release-policy",
+    },
+    {
+      label: "Distribution",
+      description: "Distribution covers Artifact Hub metadata, chart publishing assumptions, and deferred OLM posture.",
+      to: "/contribute/distribution",
+    },
+    {
+      label: "Continuous integration",
+      description: "Continuous integration covers workflow behavior before publish.",
+      to: "/contribute/ci",
+    },
+    {
+      label: "Project governance",
+      description: "Project governance covers SDLC and supply-chain policy changes.",
+      to: "/contribute/project-governance",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/sdlc.md b/website/versioned_docs/version-0.3.0/contribute/sdlc.md
new file mode 100644
index 000000000..fbd195ea3
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/sdlc.md
@@ -0,0 +1,140 @@
+---
+title: Software Development Lifecycle
+description: How OpenBao Operator maps design, implementation, verification, release, and operations into one secure development lifecycle.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Software development lifecycle"
+  lede="How the project connects planning, implementation, verification, release, and operational feedback."
+/>
+
+<DiagramFrame
+  title="Lifecycle model"
+  caption="The lifecycle links planning, implementation, verification, release, and operational feedback."
+  code={`graph LR
+    Plan["Plan and design"]
+    Build["Implement"]
+    Verify["Verify"]
+    Release["Release and publish"]
+    Operate["Operate and learn"]
+
+    Plan --> Build
+    Build --> Verify
+    Verify --> Release
+    Release --> Operate
+    Operate --> Plan`}
+/>
+
+<DecisionTable
+  title="Lifecycle stages and the question each one answers"
+  columns={["Stage", "Primary question", "Typical evidence", "Related guides"]}
+  rows={[
+    {
+      cells: [
+        "Plan and design",
+        "Should this change exist, and what constraints must it respect?",
+        "Architecture notes, compatibility expectations, security model updates, and scoped implementation plans.",
+        "[Architecture](/docs/architecture), [Security](/docs/security), [Reference](/docs/reference)",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Implement",
+        "Is the change expressed in a way the codebase can maintain safely?",
+        "Conforming code, generated artifacts, and reviewable diffs that follow project standards.",
+        "[Coding standards](/contribute/standards), [Set up your environment](/contribute/getting-started/development)",
+      ],
+    },
+    {
+      cells: [
+        "Verify",
+        "What is the smallest proof that the change behaves correctly and safely?",
+        "Unit, integration, E2E, security, and reproducibility signals matched to the scope of the change.",
+        "[Testing strategy](/contribute/testing), [Continuous integration](/contribute/ci)",
+      ],
+    },
+    {
+      cells: [
+        "Release and publish",
+        "Are the artifacts reproducible, attributable, and ready to promote?",
+        "Signed subjects, provenance evidence, reproducibility gates, and release metadata.",
+        "[Release management](/contribute/release-management), [Distribution](/contribute/distribution), [Supply chain security](/contribute/supply-chain-security)",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Operate and learn",
+        "Did the shipped change behave as intended in real environments, and what should feed back into the next cycle?",
+        "Operational feedback, recovery learnings, production checklists, and follow-up design or policy updates.",
+        "[Operate](/docs/operate), [Recovery & Restore](/docs/recover), [Project conventions](/contribute/standards/project-conventions)",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="How this page fits">
+
+Workflow pages cover concrete commands and release execution. The sections below show how the controls fit together.
+
+</Callout>
+
+<DecisionTable
+  title="Where the strongest controls live"
+  columns={["Control family", "What it protects", "Main enforcement surface"]}
+  rows={[
+    {
+      cells: [
+        "Contribution standards",
+        "Code quality, consistency, and maintainability before CI has to compensate for weak inputs.",
+        "[Build & Change](/contribute/standards) plus normal review.",
+      ],
+    },
+    {
+      cells: [
+        "Testing and CI",
+        "Behavioral correctness and regression detection across code, controllers, and cluster flows.",
+        "[Testing strategy](/contribute/testing) and [Continuous integration](/contribute/ci).",
+      ],
+    },
+    {
+      cells: [
+        "Supply-chain hardening",
+        "Artifact trust, provenance, reproducibility, and signed release outputs.",
+        "[Supply chain security](/contribute/supply-chain-security) and [Release management](/contribute/release-management).",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Operational feedback",
+        "Learning from production operation, upgrades, backup and restore, and failure handling.",
+        "The operator docs themselves, especially [Operate](/docs/operate) and [Security](/docs/security).",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Follow the lifecycle into concrete work"
+  items={[
+    {
+      label: "Supply chain security",
+      description: "See the hardening controls that govern provenance, reproducibility, and release trust.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      label: "Continuous integration",
+      description: "Open the workflow view of how verification is routed and enforced on branches, tags, and release lanes.",
+      to: "/contribute/ci",
+    },
+    {
+      label: "Coding standards",
+      description: "Implementation rules for fitting a change into the repository.",
+      to: "/contribute/standards",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/conventional-commits.md b/website/versioned_docs/version-0.3.0/contribute/standards/conventional-commits.md
new file mode 100644
index 000000000..cd92f4d58
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/conventional-commits.md
@@ -0,0 +1,85 @@
+---
+title: Conventional Commits
+description: Conventional commit rules for OpenBao Operator, including the required format, supported types and scopes, breaking-change signaling, and CI enforcement.
+pageType: reference
+journey: contribute
+---
+
+<PageHeader
+  title="Use Conventional Commits so history, changelog generation, and release tooling all agree on what changed."
+  lede="The repository uses Conventional Commits to keep PR titles and commit history predictable. This matters both for human review and for the release automation that turns merged changes into versioned output."
+/>
+
+<CommandBlock
+  language="text"
+  label="configure"
+  title="Commit format"
+  code={`<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]`}
+>
+  Use the same shape for PR titles because the project relies on squash merge and changelog automation.
+</CommandBlock>
+
+<DecisionTable
+  title="Common commit types"
+  kind="reference"
+  columns={["Type", "Use it for", "Release effect"]}
+  rows={[
+    {cells: ["`feat`", "new user-visible or contributor-visible functionality", "minor"]},
+    {cells: ["`fix`", "bug fixes and behavior corrections", "patch"], emphasis: "recommended"},
+    {cells: ["`docs`", "documentation-only changes", "patch"]},
+    {cells: ["`refactor`", "code changes that do not add a feature or fix a bug", "patch"]},
+    {cells: ["`test`", "test additions or corrections", "patch"]},
+    {cells: ["`build`, `ci`, `chore`", "build-system, workflow, or maintenance changes", "patch"]},
+    {cells: ["`revert`", "reversal of a previous change", "patch"]},
+  ]}
+/>
+
+<DecisionTable
+  title="Common scopes in this repository"
+  kind="reference"
+  columns={["Scope", "Area it maps to"]}
+  rows={[
+    {cells: ["`api`, `controller`, `infra`, `config`, `security`, `rbac`", "core controller and platform areas"]},
+    {cells: ["`backup`, `restore`, `upgrade`, `bluegreen`", "manager and lifecycle features"]},
+    {cells: ["`charts`, `manifests`, `deps`, `build`, `ci`, `docs`, `ai`", "tooling, artifacts, workflows, and docs"]},
+    {cells: ["`test(unit)`, `test(integration)`, `test(e2e)`", "test-only changes with explicit layer scoping"]},
+  ]}
+/>
+
+<Callout type="note" title="Breaking changes">
+
+Mark a breaking change with `!` after the type or scope, or use a `BREAKING CHANGE:` footer when the description needs more room.
+
+</Callout>
+
+## CI enforcement
+
+The repository validates Conventional Commit format in CI for:
+
+- PR titles, which are required for the squash-merge workflow
+- commit-subject checks, which remain informational rather than blocking
+
+<NextActions
+  title="Related contributor pages"
+  items={[
+    {
+      label: "Release management",
+      description: "Open the release flow when the next question is how commit semantics feed the published release process.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Distribution",
+      description: "Use the distribution page for how release outputs are published after the change is merged.",
+      to: "/contribute/distribution",
+    },
+    {
+      label: "Coding standards",
+      description: "Return to the build-and-change landing page for implementation rules beyond commit formatting.",
+      to: "/contribute/standards",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/error-handling.md b/website/versioned_docs/version-0.3.0/contribute/standards/error-handling.md
new file mode 100644
index 000000000..a73390802
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/error-handling.md
@@ -0,0 +1,113 @@
+---
+title: Error Handling
+description: Error-handling rules for OpenBao Operator, including wrapping, guard clauses, Kubernetes typed errors, checkable sentinels, and panic avoidance.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Error-handling defaults"
+  lede="Return failures with enough structure and context for the next layer to act correctly."
+/>
+
+<DecisionTable
+  title="Default error-handling rules"
+  columns={["Rule", "Expected default", "Avoid"]}
+  rows={[
+    {
+      cells: [
+        "Wrap returned errors",
+        "Add local context and preserve the chain with `%w`.",
+        "Returning an upstream error with no explanation of what failed here.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Use guard clauses",
+        "Return early on failure and keep the happy path unindented.",
+        "Nesting success logic inside `if err == nil` branches.",
+      ],
+    },
+    {
+      cells: [
+        "Check Kubernetes error types explicitly",
+        "Handle `NotFound` and similar typed API failures with `apierrors` helpers.",
+        "String-matching Kubernetes errors.",
+      ],
+    },
+    {
+      cells: [
+        "Define checkable sentinels only for real control flow",
+        "Expose well-known errors when callers truly need `errors.Is` behavior.",
+        "Creating exported errors for every failure string in the codebase.",
+      ],
+    },
+    {
+      cells: [
+        "Do not panic in controllers",
+        "Return an error or surface an internal invariant failure explicitly.",
+        "Panics that can crash operator management for every cluster.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Wrapping and context
+
+```go
+if err := r.Client.Create(ctx, secret); err != nil {
+    return fmt.Errorf("create bootstrap secret %s/%s: %w", secret.Namespace, secret.Name, err)
+}
+```
+
+## Kubernetes typed errors
+
+```go
+if err := r.Client.Get(ctx, key, secret); err != nil {
+    if apierrors.IsNotFound(err) {
+        return r.createSecret(ctx, ...)
+    }
+
+    return fmt.Errorf("get secret %s: %w", key.Name, err)
+}
+```
+
+## Checkable internal errors
+
+Use exported sentinel errors only when the caller genuinely needs to branch on the result:
+
+```go
+var (
+    ErrClusterLocked = errors.New("cluster is locked")
+    ErrNoLeader = errors.New("no leader available")
+)
+```
+
+<Callout type="danger" title="No panics in controller or internal logic paths">
+
+If a nil or impossible state appears, return a contextual error and let the caller decide how to surface it. A panic in a reconcile worker can take down management for the entire operator process.
+
+</Callout>
+
+<NextActions
+  title="Related coding rules"
+  items={[
+    {
+      label: "Go style guide",
+      description: "Return to naming, imports, and logging rules that sit next to error handling in normal implementation work.",
+      to: "/contribute/standards/go-style",
+    },
+    {
+      label: "Security practices",
+      description: "Open the secure-coding guidance when the error path also handles secrets, external input, or filesystem state.",
+      to: "/contribute/standards/security-practices",
+    },
+    {
+      label: "Testing strategy",
+      description: "Use the testing guide when a failure path needs explicit unit, integration, or E2E coverage.",
+      to: "/contribute/testing",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/generated-artifacts.md b/website/versioned_docs/version-0.3.0/contribute/standards/generated-artifacts.md
new file mode 100644
index 000000000..ca7e8cd91
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/generated-artifacts.md
@@ -0,0 +1,111 @@
+---
+title: Generated Artifacts
+description: Generated-artifact rules for OpenBao Operator, including what generates CRDs, API docs, Helm sync output, golden files, and architecture policy rules.
+pageType: reference
+journey: contribute
+---
+
+<PageHeader
+  title="Generated artifact ownership"
+  lede="Generated output is part of the source tree contract in this repository. If an API, policy, renderer, or chart input changes, the matching generated artifacts must change in the same PR. Do not edit generated files directly."
+/>
+
+<Callout type="warning" title="Do not edit generated files manually">
+
+Edit the source input and rerun the owning command. Manual edits to generated output will be overwritten and usually hide the real source of truth from the next reviewer.
+
+</Callout>
+
+<DecisionTable
+  title="Quick reference"
+  kind="reference"
+  columns={["If you changed", "Regenerate with", "Main CI verifier"]}
+  rows={[
+    {
+      cells: [
+        "`api/v1alpha1/*.go`",
+        "`make manifests generate`",
+        "`verify-generated`",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`api/v1alpha1/*.go` comments or API shapes that affect docs",
+        "`make api-reference`",
+        "`verify-generated`",
+      ],
+    },
+    {
+      cells: [
+        "CRD, admission, or RBAC inputs that feed the chart",
+        "`make helm-sync`",
+        "`verify-helm`",
+      ],
+    },
+    {
+      cells: [
+        "Release or channel installer manifest output",
+        "`make build-installer` and `make build-crds`",
+        "Release, edge, and nightly workflows; not committed",
+      ],
+    },
+    {
+      cells: [
+        "`.ast-grep/policy/architecture-boundaries.yml`",
+        "`make generate-ast-rules`",
+        "`verify-arch-policy`",
+      ],
+    },
+    {
+      cells: [
+        "`internal/adapter/config/*.go` renderer behavior",
+        "`make test-update-golden`",
+        "`test`",
+      ],
+    },
+  ]}
+/>
+
+## Artifact ownership
+
+- Kubernetes CRDs and `zz_generated.deepcopy.go` come from `api/v1alpha1/*.go`.
+- API reference docs come from API types and comments.
+- Helm chart sync output comes from CRD, policy, and RBAC source material.
+- Channel installer manifests such as `dist/install.yaml` and `dist/crds.yaml` come from Kustomize targets and are intentionally ignored. Release, edge, and nightly workflows generate and publish them as channel artifacts.
+- Golden HCL files come from renderer behavior in `internal/adapter/config/`.
+- Ast-grep boundary rules come from `.ast-grep/policy/architecture-boundaries.yml`.
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Safe regeneration sweep"
+  code={`make manifests generate
+make api-reference
+make helm-sync
+make generate-ast-rules
+make test-update-golden`}
+>
+  Use this when several change areas overlap or when CI tells you generated output drifted but the failing surface is not obvious yet.
+</CommandBlock>
+
+<NextActions
+  title="After regeneration"
+  items={[
+    {
+      label: "Testing strategy",
+      description: "Run the right validation layer after generation so output drift does not hide a deeper logic problem.",
+      to: "/contribute/testing",
+    },
+    {
+      label: "Project conventions",
+      description: "Return to the repository conventions when the question is scope, review hygiene, or architecture policy ownership.",
+      to: "/contribute/standards/project-conventions",
+    },
+    {
+      label: "Continuous integration",
+      description: "Open the CI guide if you need to understand which workflow enforces a particular generator or verifier.",
+      to: "/contribute/ci",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/go-style.md b/website/versioned_docs/version-0.3.0/contribute/standards/go-style.md
new file mode 100644
index 000000000..f40a243ac
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/go-style.md
@@ -0,0 +1,119 @@
+---
+title: Go Style Guide
+description: Go coding style for OpenBao Operator, covering naming, error wrapping, structured logging, reconciler concurrency, imports, and constants.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Repository Go style defaults"
+  lede="Naming, error handling, logging, reconciler-safe concurrency, imports, and constants used across the repository."
+/>
+
+<DecisionTable
+  title="Default coding choices"
+  columns={["Area", "Expected default", "Avoid"]}
+  rows={[
+    {
+      cells: [
+        "Naming",
+        "Keep acronyms consistently cased and use direct Go-style getter names.",
+        "Mixed-case acronym spellings such as `ServeHttp` or getters such as `GetStatus()`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Errors",
+        "Wrap returned errors with `%w` so callers keep context and error identity.",
+        "Returning opaque upstream errors with no explanation.",
+      ],
+    },
+    {
+      cells: [
+        "Logging",
+        "Use structured `logr` key-value logging.",
+        "`fmt.Printf`, `log.Println`, or string-built log lines that lose context.",
+      ],
+    },
+    {
+      cells: [
+        "Reconcilers",
+        "Keep work synchronous and requeue explicitly when you need another pass.",
+        "Unmanaged goroutines or `time.Sleep` in reconcile code.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Imports and constants",
+        "Use stable import grouping and name magic values explicitly.",
+        "Ad hoc import ordering and raw literals with unclear meaning.",
+      ],
+    },
+  ]}
+/>
+
+## Naming
+
+- Keep acronyms consistently cased: `ServeHTTP`, `ParseURL`, `userID`.
+- Do not prefix getters with `Get`.
+- Prefer `-er` names for single-method interfaces when the interface describes capability.
+
+## Errors and logging
+
+Use wrapped errors and structured logging together. Most reviewer comments in this area come from missing context, not from complex logic.
+
+```go
+if err := syncSecret(ctx, obj); err != nil {
+    return fmt.Errorf("sync secret for %s/%s: %w", obj.Namespace, obj.Name, err)
+}
+
+log.Info("reconciling cluster",
+    "cluster_namespace", req.Namespace,
+    "cluster_name", req.Name,
+)
+```
+
+<Callout type="danger" title="Never log secrets">
+
+Do not log tokens, keys, passwords, or raw Secret data, even in debug-only paths.
+
+</Callout>
+
+## Reconcile-safe concurrency
+
+- Do not spawn unmanaged goroutines in reconcile code.
+- Do not block workers with `time.Sleep`.
+- Use `RequeueAfter` when the controller should check again later.
+
+## Imports and constants
+
+Group imports into three blocks:
+
+1. standard library
+2. third-party dependencies
+3. local `github.com/dc-tec/openbao-operator/...` packages
+
+Name important values explicitly instead of leaving raw numbers or suffix strings in logic.
+
+<NextActions
+  title="Related standards"
+  items={[
+    {
+      label: "Error handling",
+      description: "Open the error-specific rules when the question is how to preserve context, classify failure, or avoid panics.",
+      to: "/contribute/standards/error-handling",
+    },
+    {
+      label: "Kubernetes operator patterns",
+      description: "Use the controller-specific guidance when the change lives in reconciliation, status, or app-layer delegation.",
+      to: "/contribute/standards/kubernetes-patterns",
+    },
+    {
+      label: "Project conventions",
+      description: "Go back to the repository-level rules when the problem is scope, boundaries, or generated output.",
+      to: "/contribute/standards/project-conventions",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/index.md b/website/versioned_docs/version-0.3.0/contribute/standards/index.md
new file mode 100644
index 000000000..7bb2a5b4b
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/index.md
@@ -0,0 +1,112 @@
+---
+title: Coding Standards
+description: Contributor standards for OpenBao Operator covering Go style, project conventions, Kubernetes patterns, error handling, generated artifacts, security practices, commit rules, and docs standards.
+pageType: landing
+journey: contribute
+---
+
+<PageHero
+  eyebrow="Contribute / Build & Change"
+  title="Repository standards"
+  lede="Coding, documentation, generated-artifact, and commit-history standards for OpenBao Operator."
+  actions={[
+    {label: "Open project conventions", to: "/contribute/standards/project-conventions", variant: "primary"},
+    {label: "Open documentation style guide", to: "/contribute/docs-style-guide", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Use this section to"
+    items={[
+      "understand what the project considers idiomatic Go and acceptable controller patterns",
+      "avoid common review feedback around error handling, logging, generated files, and commit shape",
+      "follow the project’s security, docs, and architecture expectations when you submit code",
+      "know which standards are global and which are specific to OpenBao Operator itself",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Build & change guides"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Project conventions",
+      description: "OpenBao Operator-specific rules around type safety, metrics, logging, testing depth, and architectural boundaries.",
+      to: "/contribute/standards/project-conventions",
+    },
+    {
+      eyebrow: "02",
+      title: "Go style guide",
+      description: "Naming, formatting, package structure, and idiomatic Go patterns expected in the repo.",
+      to: "/contribute/standards/go-style",
+    },
+    {
+      eyebrow: "03",
+      title: "Kubernetes operator patterns",
+      description: "Reconcile-loop shape, controller behavior, and Kubernetes-native design expectations.",
+      to: "/contribute/standards/kubernetes-patterns",
+    },
+    {
+      eyebrow: "04",
+      title: "Error handling",
+      description: "Required error-wrapping, propagation, and debugging conventions for production-grade controller code.",
+      to: "/contribute/standards/error-handling",
+    },
+    {
+      eyebrow: "05",
+      title: "Generated artifacts",
+      description: "What must never be edited by hand and which commands regenerate the project outputs CI verifies.",
+      to: "/contribute/standards/generated-artifacts",
+    },
+    {
+      eyebrow: "06",
+      title: "Security practices",
+      description: "Contributor rules for secrets, file permissions, input handling, and secure-by-default changes.",
+      to: "/contribute/standards/security-practices",
+    },
+    {
+      eyebrow: "07",
+      title: "Conventional commits",
+      description: "Commit message format used for consistent history and release automation.",
+      to: "/contribute/standards/conventional-commits",
+    },
+    {
+      eyebrow: "08",
+      title: "Documentation style guide",
+      description: "Writing, page-type, and design-system rules for user-facing and contributor-facing docs.",
+      to: "/contribute/docs-style-guide",
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Baseline contributor gate"
+  code={`make bootstrap
+make doctor
+make ci-core`}
+>
+  If your change affects generated artifacts, manifests, or docs, run the more specific regeneration commands before the baseline gate.
+</CommandBlock>
+
+<NextActions
+  title="Pair standards with execution"
+  items={[
+    {
+      label: "Testing strategy",
+      description: "Match your change to the right test layer after you understand the code and docs rules.",
+      to: "/contribute/testing",
+    },
+    {
+      label: "Continuous integration",
+      description: "See how the repo enforces these standards once your branch hits CI.",
+      to: "/contribute/ci",
+    },
+    {
+      label: "Set up your environment",
+      description: "Go back to the local setup guide if you still need a clean contributor workstation.",
+      to: "/contribute/getting-started/development",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/kubernetes-patterns.md b/website/versioned_docs/version-0.3.0/contribute/standards/kubernetes-patterns.md
new file mode 100644
index 000000000..c7f8a41bd
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/kubernetes-patterns.md
@@ -0,0 +1,106 @@
+---
+title: Kubernetes Operator Patterns
+description: Kubernetes-native controller patterns for OpenBao Operator, including level-triggered reconciliation, idempotency, app-layer delegation, context handling, and structured logging.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Kubernetes-native controller patterns"
+  lede="The operator relies on predictable reconcile loops, explicit controller boundaries, and safe interaction with the API server. These patterns are the default shape of controller work in this repository, especially when app-layer orchestration and manager boundaries are involved."
+/>
+
+<DiagramFrame
+  title="Level-triggered reconciliation"
+  caption="Controllers reconcile the current world against desired state. They do not assume a single event arrives only once."
+  code={`graph TD
+    Trigger["Event or scheduled requeue"] --> Fetch["Fetch current custom resource"]
+    Fetch --> Exists{"Object exists?"}
+    Exists -- No --> Stop["Stop or finalize"]
+    Exists -- Yes --> Observe["Fetch child resources and status"]
+    Observe --> Diff{"State drift?"}
+    Diff -- No --> Status["Patch status if needed"]
+    Diff -- Yes --> Act["Create, update, or delete resources"]
+    Act --> Status
+    Status --> End["Return and requeue if needed"]`}
+/>
+
+<DecisionTable
+  title="Controller patterns to keep"
+  columns={["Pattern", "What it means", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Level-triggered reconciliation",
+        "Always reconcile from current observed state rather than assuming a single edge event is authoritative.",
+        "Controllers may run repeatedly for the same change and still need to converge safely.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Idempotent fetch-check-act flow",
+        "Fetch existing state, compare with desired state, and act only when drift exists.",
+        "Blind create or blind update paths become noisy and brittle on the second reconcile.",
+      ],
+    },
+    {
+      cells: [
+        "Controller boundary stays thin",
+        "Controllers should observe, delegate, patch status, and requeue, not encode deep orchestration directly.",
+        "This keeps the app layer and manager boundaries testable and enforceable.",
+      ],
+    },
+    {
+      cells: [
+        "No unmanaged concurrency",
+        "Use the context and lifecycle controller-runtime already provides.",
+        "Background goroutines lose error handling, ordering, and shutdown semantics.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Structured logging with context",
+        "Attach stable keys such as cluster namespace, name, and phase to log entries.",
+        "Logs stay queryable and preserve reconcile context across the workflow.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Boundary rules are policy-enforced">
+
+Architecture boundaries are generated from `.ast-grep/policy/architecture-boundaries.yml` and enforced in CI. If a new controller or internal package boundary is required, change the policy first and regenerate the rules in the same branch.
+
+</Callout>
+
+```go
+// Controller path: observe, delegate, then return result and error.
+result, err := appopenbaocluster.ReconcileAdminOps(ctx, r.Client, req, log, deps)
+if err != nil {
+    return ctrl.Result{}, err
+}
+return result, nil
+```
+
+<NextActions
+  title="Related implementation guides"
+  items={[
+    {
+      label: "Architecture",
+      description: "Use the architecture section when the next question is which manager or controller owns a responsibility.",
+      to: "/docs/architecture",
+    },
+    {
+      label: "Go style guide",
+      description: "Return to the language-level rules for naming, errors, and imports.",
+      to: "/contribute/standards/go-style",
+    },
+    {
+      label: "Error handling",
+      description: "Open the error-specific guidance when the reconcile path needs clearer failure contracts.",
+      to: "/contribute/standards/error-handling",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/project-conventions.md b/website/versioned_docs/version-0.3.0/contribute/standards/project-conventions.md
new file mode 100644
index 000000000..32881f1e1
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/project-conventions.md
@@ -0,0 +1,144 @@
+---
+title: Project Conventions
+description: Repository-specific implementation conventions for OpenBao Operator, including type safety, review scope, architecture boundaries, observability, and testing expectations.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Repository project conventions"
+  lede="These are the project-specific rules that go beyond generic Go style. They keep controller code predictable, reviews focused, architecture boundaries enforceable, and generated output aligned with the code that owns it."
+/>
+
+<DecisionTable
+  title="Core project conventions"
+  columns={["Convention", "What it means in practice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Prefer strict types",
+        "Avoid `any` or `interface{}` in core logic except where an external library leaves no alternative.",
+        "Compile-time guarantees beat runtime assertions in controller code.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Delay abstraction until the rule of three",
+        "Do not create shared helpers the first or second time a pattern appears.",
+        "This keeps the codebase from filling with speculative utility layers.",
+      ],
+    },
+    {
+      cells: [
+        "Keep PRs single-theme",
+        "A change should primarily be a feature, bug fix, refactor, or doc update, not several unrelated cleanups at once.",
+        "Smaller review surfaces keep maintainers effective.",
+      ],
+    },
+    {
+      cells: [
+        "Keep architecture boundaries aligned with policy",
+        "Update the boundary policy before adding new top-level internal packages, controller packages, or service-level service or adapter dependencies.",
+        "The repository enforces these rules automatically, so design intent and CI stay aligned.",
+      ],
+    },
+    {
+      cells: [
+        "Always update the generated or test artifacts a change implies",
+        "If APIs, manifests, golden files, or rules change, regenerate them in the same PR.",
+        "Generated drift should never be left for the next contributor to discover.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Avoid type erasure in core logic">
+
+Reserve `any` and `interface{}` for external API boundaries. Helpers that only work because they erase types usually need a narrower contract.
+
+</Callout>
+
+## Type safety and package shape
+
+- Use defined types for enum-like status and phase values instead of raw strings.
+- Avoid junk-drawer package names such as `util`, `common`, or `shared`.
+- Prefer package names that describe the actual boundary or job, such as `k8sutil`, `config`, or `schema`.
+- Reuse shared platform contracts such as `internal/platform/resourceidentity` and `internal/platform/resourceapply` instead of copying names, labels, selectors, or generic apply flow into another service.
+- Keep `config.hcl` semantics behind `internal/service/configuration` instead of letting workload bootstrap and upgrade flows render around each other.
+
+## Review hygiene
+
+- Keep a PR to one main theme.
+- Avoid drive-by reformatting of unrelated files.
+- If a change touches `api/`, update the generated artifacts in the same branch.
+- If a service needs a new adapter import, update `serviceBoundaries` and regenerate the ast-grep rules in the same branch.
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Boundary policy regeneration and verification"
+  code={`make generate-ast-rules
+make verify-arch-policy
+make test-ast
+make lint-ast`}
+>
+  Run this when you add a new top-level `internal/*` package, introduce a new controller package, or change the boundary policy itself.
+</CommandBlock>
+
+<DecisionTable
+  title="Observability and testing expectations"
+  columns={["Area", "Repository expectation", "Primary entry point"]}
+  rows={[
+    {
+      cells: [
+        "Metrics",
+        "Use the `openbao_` prefix and stable label sets.",
+        "The metrics conventions in the existing controllers plus review.",
+      ],
+    },
+    {
+      cells: [
+        "Logging",
+        "Prefer structured, context-rich logging with consistent field names.",
+        "[Kubernetes operator patterns](/contribute/standards/kubernetes-patterns).",
+      ],
+    },
+    {
+      cells: [
+        "Testing",
+        "Match the verification depth to the change, and update golden files when renderer output changes.",
+        "[Testing strategy](/contribute/testing).",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "CRD evolution",
+        "Prefer additive API changes and document migrations when a breaking shape change is unavoidable.",
+        "API review plus [Reference](/docs/reference).",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related build-and-change guides"
+  items={[
+    {
+      label: "Go style guide",
+      description: "Open the lower-level coding rules for naming, imports, logging, and reconcilers.",
+      to: "/contribute/standards/go-style",
+    },
+    {
+      label: "Generated artifacts",
+      description: "Generated artifacts maps emitted files back to their owning commands.",
+      to: "/contribute/standards/generated-artifacts",
+    },
+    {
+      label: "Kubernetes operator patterns",
+      description: "Review the controller-specific patterns that keep reconciliation logic idempotent and boundary-aware.",
+      to: "/contribute/standards/kubernetes-patterns",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/standards/security-practices.md b/website/versioned_docs/version-0.3.0/contribute/standards/security-practices.md
new file mode 100644
index 000000000..ef097adb4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/standards/security-practices.md
@@ -0,0 +1,104 @@
+---
+title: Security Practices
+description: Secure coding practices for OpenBao Operator contributors, including file permissions, randomness, input validation, secret handling, and controller safety boundaries.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Secure coding practices"
+  lede="Least-privilege permissions, standard cryptographic primitives, controller-safe execution, and careful handling of secrets in memory and logs."
+/>
+
+<DecisionTable
+  title="Secure coding defaults"
+  columns={["Area", "Expected default", "Avoid"]}
+  rows={[
+    {
+      cells: [
+        "Filesystem permissions",
+        "Use the narrowest permissions possible, especially `0600` for keys and secrets.",
+        "World-writable or broadly readable secret material.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Randomness",
+        "Use `crypto/rand` for security-sensitive values.",
+        "`math/rand` for tokens, passwords, keys, or nonces.",
+      ],
+    },
+    {
+      cells: [
+        "Controller execution model",
+        "Use Go libraries and Kubernetes clients directly.",
+        "Shelling out to `kubectl`, `helm`, `bao`, `vault`, or similar binaries from controllers.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Input validation",
+        "Validate paths, ranges, and other CR-driven input before use.",
+        "Passing raw user input into filesystem or runtime-sensitive operations.",
+      ],
+    },
+    {
+      cells: [
+        "Secret handling",
+        "Do not log secret contents and minimize their lifetime in memory.",
+        "Debug output that prints token, key, or secret payload fields.",
+      ],
+    },
+  ]}
+/>
+
+## Minimal secure examples
+
+```go
+// private key file permissions
+if err := os.WriteFile(keyPath, keyData, 0o600); err != nil {
+    return err
+}
+
+// cryptographically secure randomness
+token := make([]byte, 32)
+if _, err := rand.Read(token); err != nil {
+    return err
+}
+```
+
+<Callout type="warning" title="Controllers must not shell out">
+
+Shelling out introduces injection risk, hidden runtime dependencies, and slower, harder-to-test control paths. Use Kubernetes clients and internal helpers instead.
+
+</Callout>
+
+## Input and secret handling
+
+- Clean and validate filesystem paths before use.
+- Enforce numeric and enum bounds from CR input explicitly.
+- Never log secret payloads, even in debug-only paths.
+- Zero sensitive byte slices after use when the code keeps them in memory for any meaningful period.
+
+<NextActions
+  title="Related secure-contributor guides"
+  items={[
+    {
+      label: "Supply chain security",
+      description: "Open the artifact-trust controls when the change moves from secure coding into build, provenance, or release security.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      label: "Dependency license policy",
+      description: "Use the dependency policy when the security question is whether a new dependency is even shippable.",
+      to: "/contribute/dependency-licenses",
+    },
+    {
+      label: "Security docs",
+      description: "Return to the operator-facing security section when you need the runtime trust model rather than contributor implementation rules.",
+      to: "/docs/security",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/supply-chain-incident-response.md b/website/versioned_docs/version-0.3.0/contribute/supply-chain-incident-response.md
new file mode 100644
index 000000000..6a1175247
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/supply-chain-incident-response.md
@@ -0,0 +1,159 @@
+---
+title: Supply-Chain Incident Response
+description: Maintainer runbook for responding to CI, release, GHCR, or GitHub App supply-chain incidents in OpenBao Operator.
+pageType: task
+journey: contribute
+---
+
+<PageHeader
+  title="Freeze release automation fast and recover with evidence."
+  lede="During a supply-chain incident, speed and containment matter more than elegance. This runbook is for freezing publication, suspending high-trust credentials, inspecting recent releases, and restoring trust in a controlled order."
+/>
+
+<DecisionTable
+  title="Immediate containment order"
+  columns={["Priority", "Action", "Why it comes first"]}
+  rows={[
+    {
+      cells: [
+        "1",
+        "Disable GitHub Actions or restrict them to approved workflows only until the cause is understood.",
+        "Stops further workflow-triggered token minting, package publication, or release mutation.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "2",
+        "Suspend `openbao-operator-release-pr` and `openbao-operator-release-tag` if release automation is in scope.",
+        "Cuts off the highest-trust automation identities before new tags or draft releases can appear.",
+      ],
+    },
+    {
+      cells: [
+        "3",
+        "Freeze semver tag creation and updates through repository rulesets.",
+        "Prevents a forged or replayed release tag from triggering the stable release pipeline.",
+      ],
+    },
+    {
+      cells: [
+        "4",
+        "Rotate app private keys, the release-tag signing key, and any affected repository secrets.",
+        "Assumes any app key, signing key, or workflow-level credential may already have leaked.",
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="List recent high-trust workflow runs"
+  code={`gh run list \
+  --repo dc-tec/openbao-operator \
+  --limit 30 \
+  --workflow "Release"
+
+gh run list \
+  --repo dc-tec/openbao-operator \
+  --limit 30 \
+  --workflow "Release Please PR"
+
+gh run list \
+  --repo dc-tec/openbao-operator \
+  --limit 30 \
+  --workflow "Release Tag"
+
+gh run list \
+  --repo dc-tec/openbao-operator \
+  --limit 30 \
+  --workflow "Publish Edge"`}
+>
+  Start here when you need a quick view of the workflows that can mutate releases, tags, GHCR publication state, or public manifests.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect recent release state"
+  code={`gh release list --repo dc-tec/openbao-operator --limit 20
+git ls-remote --tags origin
+
+crane ls ghcr.io/dc-tec/openbao-operator | tail -n 20
+crane ls ghcr.io/dc-tec/openbao-init | tail -n 20
+crane ls ghcr.io/dc-tec/openbao-backup | tail -n 20
+crane ls ghcr.io/dc-tec/openbao-upgrade | tail -n 20`}
+>
+  Compare recent tags, draft releases, and registry publication state to what should have been produced by the workflows you trust.
+</CommandBlock>
+
+<DecisionTable
+  title="What to verify before restoring automation"
+  columns={["Area", "What to prove", "Where to check"]}
+  rows={[
+    {
+      cells: [
+        "Workflow integrity",
+        "Pinned actions, workflow helper sources, and release logic still match reviewed repository state.",
+        "Default branch commits, workflow diffs, and recent PR history.",
+      ],
+    },
+    {
+      cells: [
+        "Release identities",
+        "Only the tag app has semver-tag bypass and the PR app has no release-tag authority.",
+        "Repository rulesets, app installation settings, and repository secrets.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Published subjects",
+        "Recent images, charts, checksums, and releases still verify against the expected workflow identity and source ref.",
+        "Release verification commands, provenance index, and GHCR digests.",
+      ],
+    },
+    {
+      cells: [
+        "Credential hygiene",
+        "Suspicious app keys, release-signing keys, tokens, PATs, sessions, or SSH keys have been revoked or rotated.",
+        "GitHub account sessions, SSH keys, GPG signing keys, app private keys, and repo/org secrets.",
+      ],
+    },
+  ]}
+/>
+
+## Recovery checklist
+
+- Re-enable GitHub Actions only after the triggering cause is understood and contained.
+- Unsuspend the PR app first; keep the tag app suspended until release creation is safe again.
+- Run a controlled prerelease or RC before restoring normal stable-release activity.
+- Record the affected workflow run IDs, tags, releases, GHCR digests, and remediation steps in the incident notes.
+
+<Callout type="warning" title="Single-maintainer constraint">
+
+This runbook improves speed and consistency, but it does not create multi-party approval. If the maintainer account is compromised, treat repository settings, Actions secrets, GitHub Apps, and release state as potentially affected until proven otherwise.
+
+</Callout>
+
+<NextActions
+  title="After containment"
+  items={[
+    {
+      label: "Supply chain security",
+      description: "Return to the underlying trust model once the immediate incident is contained.",
+      to: "/contribute/supply-chain-security",
+    },
+    {
+      label: "Release management",
+      description: "Use the concrete release workflow when you are ready to run a controlled validation release.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Continuous integration",
+      description: "Inspect the implementation surface that may have allowed the incident path in the first place.",
+      to: "/contribute/ci",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/supply-chain-security.md b/website/versioned_docs/version-0.3.0/contribute/supply-chain-security.md
new file mode 100644
index 000000000..454fd2903
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/supply-chain-security.md
@@ -0,0 +1,189 @@
+---
+title: Supply Chain Security
+description: Supply-chain security controls for OpenBao Operator, including provenance, reproducibility, signing, release evidence, and channel hardening.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Supply-chain security controls"
+  lede="Provenance, reproducibility, and publish-time checks for OpenBao Operator release assets."
+/>
+
+<DiagramFrame
+  title="Build once, verify, then promote"
+  caption="Promotion is gated by trust evidence, not by rebuilding the same subject a second time during publish."
+  code={`graph TD
+    Commit["Commit or tag"] --> Build["Build immutable artifacts"]
+    Build --> Provenance["Verify provenance"]
+    Build --> Repro["Verify reproducibility"]
+    Provenance --> Promote["Promote by digest"]
+    Repro --> Promote
+    Promote --> Sign["Sign and attest publish subjects"]
+    Sign --> Publish["Publish releases, manifests, and metadata"]`}
+/>
+
+<DecisionTable
+  title="Channel coverage"
+  columns={["Channel", "Primary workflow path", "Blocking trust gates", "Published output"]}
+  rows={[
+    {
+      cells: [
+        "CI",
+        "`.github/workflows/ci.yml`",
+        "Validation only. No publish path.",
+        "PR and branch confidence, but no public artifacts.",
+      ],
+    },
+    {
+      cells: [
+        "Edge",
+        "`.github/workflows/publish-edge.yml` plus reusable hardening",
+        "Provenance verification and byte reproducibility before publish.",
+        "GitHub Pages edge manifests, checksums, and provenance index.",
+      ],
+    },
+    {
+      cells: [
+        "Nightly",
+        "`.github/workflows/publish-nightly.yml` plus reusable hardening",
+        "Provenance verification and byte reproducibility before publish.",
+        "GitHub Pages nightly manifests, checksums, and provenance index.",
+      ],
+    },
+    {
+      cells: [
+        "Stable release",
+        "`.github/workflows/release.yml`",
+        "Provenance, reproducibility, signing, and release evidence gates.",
+        "GitHub Release assets, OCI images, chart artifacts, versioned docs, and machine-readable provenance metadata.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Prerelease",
+        "`.github/workflows/release.yml`",
+        "Provenance, reproducibility, signing, and release evidence gates.",
+        "GitHub Release assets, OCI images, chart artifacts, release notes, and docs deployment through `/docs/next`.",
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Control families"
+  columns={["Control family", "What it protects", "Primary implementation surface"]}
+  rows={[
+    {
+      cells: [
+        "Governance",
+        "Branch, tag, and change-management expectations for release-critical paths.",
+        "Repository rulesets, signed semver tags, CODEOWNERS, PR checks, and pinned GitHub Actions usage.",
+      ],
+    },
+    {
+      cells: [
+        "Build inputs",
+        "Deterministic dependency resolution and low-drift toolchains.",
+        "Vendored Go modules, pinned base-image digests, pinned tool versions, and workflow-defined build parameters.",
+      ],
+    },
+    {
+      cells: [
+        "Provenance and signing",
+        "Evidence that published subjects came from the expected workflow and identity.",
+        "`actions/attest-build-provenance`, `cosign`, `gh attestation`, and the release verification scripts.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Reproducibility",
+        "Confidence that an independent rebuild matches expected bytes before publication.",
+        "`hack/ci/verify-byte-reproducibility.sh`, deterministic SPDX normalization, and release/channel hardening gates.",
+      ],
+    },
+    {
+      cells: [
+        "Release evidence",
+        "Retained proof that a release met the hardening contract at publish time.",
+        "Workflow run metadata, verification output, artifact listings, and provenance indexes.",
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect hardening entry points"
+  code={`rg -n "verify-image-attestations|verify-byte-reproducibility|provenance-index" \\
+  .github/workflows hack/ci
+
+sed -n '1,220p' .github/workflows/release.yml
+sed -n '1,220p' .github/workflows/reusable-channel-hardening.yml`}
+>
+  Use these commands to trace the workflow or script that implements a trust gate.
+</CommandBlock>
+
+<Callout type="warning" title="Single-maintainer operating constraint">
+
+Human two-person approval controls are still limited by the current single-maintainer operating model. The project compensates with stronger automation, pinned workflow identity checks, and explicit release evidence requirements, but this does not create true multi-person release separation on its own.
+
+</Callout>
+
+<DecisionTable
+  title="Common failure classes"
+  columns={["Failure", "Likely cause", "Where to look first"]}
+  rows={[
+    {
+      cells: [
+        "Attestation verification fails",
+        "Workflow identity, signer identity, or source ref does not match the expected constraint.",
+        "Release workflow inputs and `hack/ci/verify-image-attestations.sh`.",
+      ],
+    },
+    {
+      cells: [
+        "Byte reproducibility fails",
+        "A build input or emitted artifact changed nondeterministically between rebuilds.",
+        "`hack/ci/verify-byte-reproducibility.sh`, normalized SPDX output, and build metadata sources.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Checksums or chart subject verification fails",
+        "A signed or attested subject was regenerated after evidence was captured.",
+        "`hack/ci/verify-release-artifact-attestations.sh` and the release job ordering.",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Turn policy into release work"
+  items={[
+    {
+      label: "Release management",
+      description: "Release procedure for verification, publish, and post-release steps.",
+      to: "/contribute/release-management",
+    },
+    {
+      label: "Continuous integration",
+      description: "How these controls appear earlier in the branch and PR lifecycle.",
+      to: "/contribute/ci",
+    },
+    {
+      label: "Dependency license policy",
+      description: "Dependency policy for which shipped dependencies may enter the release graph.",
+      to: "/contribute/dependency-licenses",
+    },
+    {
+      label: "Incident response",
+      description: "Supply-chain incident runbook for freezing publishing, rotating credentials, or inspecting recent releases.",
+      to: "/contribute/supply-chain-incident-response",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/testing.md b/website/versioned_docs/version-0.3.0/contribute/testing.md
new file mode 100644
index 000000000..2da13c8e9
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/testing.md
@@ -0,0 +1,176 @@
+---
+title: Testing Strategy
+description: Contributor testing strategy for OpenBao Operator, including test depth selection, local PR-equivalent checks, fuzzing, performance gates, and targeted cluster validation.
+pageType: concept
+journey: contribute
+---
+
+<PageHeader
+  title="Testing strategy by change scope"
+  lede="Validation depth by change scope across unit, integration, E2E, fuzzing, and exploratory coverage."
+/>
+
+<DiagramFrame
+  title="Testing layers"
+  caption="Move to the next layer when the lower-cost layer no longer proves the behavior you changed."
+  code={`graph BT
+    Unit["Unit tests"]
+    Contract["Fast contracts"]
+    Integration["EnvTest integration"]
+    E2E["Kind end-to-end"]
+    Exploratory["Manual and exploratory"]
+
+    Unit --> Contract
+    Contract --> Integration
+    Integration --> E2E
+    E2E --> Exploratory`}
+/>
+
+<DecisionTable
+  title="Choose test depth by change scope"
+  columns={["If your change affects", "Run this first", "What it proves"]}
+  rows={[
+    {
+      cells: [
+        "Pure Go logic, parsers, renderers, helpers, or small decision functions",
+        "`make test` or targeted `go test ./...`",
+        "Deterministic in-process behavior with no Kubernetes API dependency.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Object builders, manifests, patches, or fake-client contract behavior",
+        "`make test` plus targeted package tests",
+        "Resource shape and emitted contracts when API-server semantics do not matter.",
+      ],
+    },
+    {
+      cells: [
+        "Reconciliation, finalizers, status writes, admission behavior, or server-side validation/defaulting",
+        "`make test-integration`",
+        "Real API-server semantics through EnvTest.",
+      ],
+    },
+    {
+      cells: [
+        "Lifecycle flows, networking, storage, upgrades, backup and restore, or workload startup",
+        "`make test-e2e` or a label-filtered `make test-e2e-ci ...` run",
+        "Real cluster behavior with real images and controller wiring.",
+      ],
+    },
+    {
+      cells: [
+        "Disaster recovery, performance baselines, or compatibility against an existing platform cluster",
+        "Focused manual or scheduled workflow validation",
+        "Evidence from the environment that production-like assumptions actually hold.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Callout type="note" title="Fake client boundary">
+
+Use the controller-runtime fake client as a fast contract tool, not as a substitute for the API server. If the test depends on validation, defaulting, `Generation` or `ResourceVersion` behavior, subresources, watches, cache wiring, or controller-manager setup, move to EnvTest.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="PR-equivalent local gate"
+  code={`make bootstrap
+make doctor
+make ci-core`}
+>
+  Standard local validation baseline before review or handoff.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Focused fuzz and existing-cluster checks"
+  code={`make fuzz
+FUZZTIME=30s make fuzz
+FUZZ_TARGET_FILTER='FuzzRenderHCL|internal/adapter/auth' make fuzz
+
+export KUBECONFIG=/path/to/your/kubeconfig
+export E2E_OPERATOR_IMAGE=quay.io/your-org/openbao-operator:dev
+export E2E_API_SERVER_CIDR=0.0.0.0/0
+make test-e2e-existing E2E_LABEL_FILTER='openshift'`}
+>
+  These commands cover parser, auth, renderer, and platform-specific validation that does not fit the default local gate.
+</CommandBlock>
+
+For E2E debugging, prefer structured reports over log-only inspection. Set `E2E_JSON_REPORT` for the native Ginkgo report, `E2E_JUNIT_REPORT` for CI-compatible test output, and `E2E_FAIL_ON_EMPTY=true` when using a label filter so an accidental empty selection fails immediately.
+
+E2E suites are declared in `test/e2e/suites.yaml`. When adding or changing an E2E file, update the manifest with the suite owner, risk tier, isolation class, labels, coverage tags, CI lane, and nightly policy, then run `make verify-e2e-manifest`.
+
+<CommandBlock
+  language="bash"
+  label="hsm"
+  title="Run the manual HSM/KMIP E2E lane locally"
+  code={`make docker-build-e2e-openbao-softhsm OPENBAO_SOFTHSM_IMG=openbao-softhsm:dev
+make docker-build-e2e-pykmip-server PYKMIP_SERVER_IMG=pykmip-server:dev
+
+E2E_ENABLE_SOFTHSM_SUITE=true \\
+E2E_ENABLE_KMIP_SUITE=true \\
+E2E_OPENBAO_IMAGE=openbao-softhsm:dev \\
+E2E_KMIP_SERVER_IMAGE=pykmip-server:dev \\
+E2E_LABEL_FILTER='hsm && !openshift' \\
+make test-e2e`}
+>
+  The HSM lane is manual because it needs test-only images and provider fixtures. The KMIP suite uses a PyKMIP server fixture with mTLS and a pre-seeded active AES key; the PKCS#11 suite uses a SoftHSM-enabled OpenBao image.
+</CommandBlock>
+
+<DecisionTable
+  title="Special validation lanes"
+  columns={["Lane", "When to use it", "Primary entry point"]}
+  rows={[
+    {
+      cells: [
+        "Fuzzing",
+        "Parser, renderer, auth, or normalization changes that benefit from mutated input coverage.",
+        "`make fuzz` locally, `make fuzz-long` in longer sweeps.",
+      ],
+    },
+    {
+      cells: [
+        "Performance",
+        "Controller or lifecycle changes that may affect reconcile cost, startup time, or upgrade behavior.",
+        "`make verify-perf` and the Performance Baseline Capture workflow.",
+      ],
+    },
+    {
+      cells: [
+        "Existing-cluster compatibility",
+        "OpenShift or platform-specific validation that a local Kind cluster cannot faithfully represent.",
+        "`make test-e2e-existing ...` with a preconfigured cluster context.",
+      ],
+    },
+  ]}
+/>
+
+Performance scenarios are declared in `hack/perf/v2/scenarios.yaml`, with policies under `hack/perf/v2/policies/` and per-scenario baselines under `hack/perf/v2/baselines/`. Each scenario owns its executor, measured artifacts, and metric policy surface. Native scenarios now cover lifecycle convergence, tenant churn, and rolling upgrades with direct phase events; Ginkgo-backed DR scenarios also attach `By` step timestamps to their sample phases so backup and restore artifacts expose the slow step when a run fails. The weekly workflow runs scenarios as separate matrix jobs, uploads per-scenario artifacts, and renders a merged v2 report for triage. Keep policies narrow: primary phase timings should gate only after calibration, while broad counters such as workqueue retries remain warning or diagnostic signals.
+
+<NextActions
+  title="After test selection"
+  items={[
+    {
+      label: "Continuous integration",
+      description: "Continuous integration maps these validation layers to workflow gates and routing.",
+      to: "/contribute/ci",
+    },
+    {
+      label: "Coding standards",
+      description: "Coding standards cover implementation cleanup when more test depth would not help yet.",
+      to: "/contribute/standards",
+    },
+    {
+      label: "Release management",
+      description: "Release management covers release and publish flow once the branch is stable.",
+      to: "/contribute/release-management",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/contribute/validate-and-ship.mdx b/website/versioned_docs/version-0.3.0/contribute/validate-and-ship.mdx
new file mode 100644
index 000000000..ff4f96e4a
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/contribute/validate-and-ship.mdx
@@ -0,0 +1,72 @@
+---
+title: Validate & Ship
+description: Contributor and maintainer workflow for local checks, CI behavior, release execution, and distribution decisions in OpenBao Operator.
+pageType: landing
+journey: contribute
+---
+
+<PageHero
+  eyebrow="Contribute / Validate & Ship"
+  title="Validation and release workflows"
+  lede="Local validation, CI behavior, release execution, and distribution workflows."
+  actions={[
+    {label: "Open testing strategy", to: "/contribute/testing", variant: "primary"},
+    {label: "Open release management", to: "/contribute/release-management", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Covers"
+    items={[
+      "local test depth before a branch is pushed",
+      "CI-to-local command mapping and workflow failure triage",
+      "release flow, artifact publication, and distribution mechanics",
+      "the split between contributor checks and maintainer release responsibilities",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Validate & ship guides"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Testing strategy",
+      description: "Map your change to unit, contract, integration, E2E, fuzzing, or manual validation work.",
+      to: "/contribute/testing",
+    },
+    {
+      eyebrow: "02",
+      title: "Continuous integration",
+      description: "Understand local command parity, CI stages, and the workflow gates maintainers expect to stay green.",
+      to: "/contribute/ci",
+    },
+    {
+      eyebrow: "03",
+      title: "Release management",
+      description: "Follow the release flow, promotion rules, and provenance requirements used for published builds.",
+      to: "/contribute/release-management",
+    },
+    {
+      eyebrow: "04",
+      title: "Distribution",
+      description: "Review how the project publishes charts and artifacts and what is intentionally deferred.",
+      to: "/contribute/distribution",
+    },
+  ]}
+/>
+
+<NextActions
+  title="After the execution path"
+  items={[
+    {
+      label: "Project governance",
+      description: "SDLC, supply-chain, and dependency policy when the change affects project policy.",
+      to: "/contribute/project-governance",
+    },
+    {
+      label: "Coding standards",
+      description: "Coding standards when CI is failing because the implementation still violates project conventions.",
+      to: "/contribute/standards",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/design/claims-and-service-offerings.mdx b/website/versioned_docs/version-0.3.0/design/claims-and-service-offerings.mdx
new file mode 100644
index 000000000..8ab378acc
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/design/claims-and-service-offerings.mdx
@@ -0,0 +1,152 @@
+---
+title: Claims and Service Offerings
+description: Public design note for Claims and Service Offerings.
+hide_title: true
+pageType: concept
+---
+
+<PageHeader
+  title="Claims and Service Offerings"
+  lede="Claims and Service Offerings provide a self-service API above the concrete OpenBaoCluster lifecycle API."
+/>
+
+<Callout type="note" title="Design status">
+
+This design note describes the current same-cluster Claims and Service Offerings direction. The feature is in
+integration and remains subject to API review, documentation review, security review, and release validation.
+
+</Callout>
+
+## Summary
+
+`OpenBaoClusterClaim` is the planned tenant-facing service request API for OpenBao clusters.
+
+It gives a tenant one place to request an OpenBao service instance without requiring direct access to the full
+`OpenBaoCluster` workload specification. Platform operators define approved service shapes. The claim resolves
+that service intent into the concrete lifecycle resources the operator already knows how to manage.
+
+`OpenBaoCluster` still exists. It remains the concrete workload API, the direct advanced path, and the object
+same-cluster claims materialize into.
+
+## Problem statement
+
+Without a claim layer, tenants must interact with the concrete workload API too early. That leaks low-level
+lifecycle knobs into a self-service workflow and makes it harder for platform operators to offer curated,
+repeatable service classes.
+
+Claims separate:
+
+- tenant-facing service intent
+- platform-owned offerings and profiles
+- internal approved service contracts
+- rendered execution contracts
+- concrete runtime materialization
+
+## User-facing model
+
+The claim model keeps the tenant surface small. A tenant selects an approved offering or service profile and
+provides only the parameters that the platform chose to expose.
+
+<DiagramFrame
+  title="Claim resolution model"
+  caption="Claims express service intent. The platform catalog and internal contracts render that intent into a concrete lifecycle object."
+  code={`flowchart TD
+    Claim["OpenBaoClusterClaim"] --> Offering["OpenBaoServiceOffering or profile"]
+    Offering --> Approved["Approved service contract"]
+    Claim --> Params["Typed service parameters"]
+    Params --> Approved
+    Approved --> Rendered["Rendered execution contract"]
+    Rendered --> Cluster["claim-managed OpenBaoCluster"]
+    Cluster --> Status["claim status and connection output"]`}
+/>
+
+The important rule is that the claim path does not bypass the core lifecycle contract. If the direct
+`OpenBaoCluster` API cannot represent a rendered service shape honestly, the claim path blocks instead of
+silently weakening that shape.
+
+## Technical model
+
+The same-cluster path resolves service intent through a bounded pipeline:
+
+1. Validate the claim, tenant reference, and selected service offering or profile.
+2. Load immutable platform-owned catalog inputs.
+3. Bind an approved service contract.
+4. Render same-cluster execution inputs.
+5. Materialize or patch the deterministic claim-managed `OpenBaoCluster`.
+6. Publish claim-facing status and connection output.
+
+The concrete workload remains visible and owned. Claim-managed clusters are machine-distinguishable from directly
+managed clusters through ownership labels and admission protection.
+
+## Current implementation status
+
+The same-cluster path is in integration. The implementation branch is `integration/claims-service`.
+
+Current same-cluster work includes:
+
+- tenant and service selection
+- immutable catalog inputs
+- approved and rendered internal contracts
+- claim-managed `OpenBaoCluster` materialization
+- `Development` and bounded `Hardened` service shapes
+- `SelfInit` bootstrap as the supported claim-managed bootstrap posture
+- cluster-internal, Gateway, and Ingress exposure projection where supported
+- bootstrap dependency projection through ConfigMaps or Secrets where supported
+- storage, read replica, upgrade strategy, and first-wave backup projection
+- claim-facing status and connection publication
+- admission guardrails for claim-managed child objects
+- workflow events and claim-native status for supported operations
+
+## Security and ownership model
+
+The claim path is intentionally fail-closed.
+
+Security and ownership boundaries include:
+
+- tenant namespace access still flows through explicit tenant onboarding
+- claim-managed child objects carry ownership markers
+- non-controller identities cannot spoof or mutate claim ownership markers
+- claim-managed child deletion is guarded
+- connection output custody is bound to the claim
+- unsupported shapes remain blocked until the concrete lifecycle API can carry them honestly
+- secret values stay out of CRDs, status, logs, and events
+
+The claim controller does not need broad tenant object discovery for arbitrary `ConfigMap`, `Secret`, or Gateway
+objects. Dependencies stay explicit so the controller can remain narrow in multi-tenant environments.
+
+## Rollout and upgrade posture
+
+The first public model is deliberately conservative after materialization.
+
+Fields that change the service contract, tenant binding, or backup partitioning are treated as rollout-sensitive.
+Ordinary claim edits should not trigger hidden migration, adoption, or replacement behavior.
+
+Supported rollout and upgrade workflows should be explicit. When a requested change cannot be classified safely,
+the operator should block the change and surface status instead of guessing.
+
+## Non-goals
+
+The initial Claims and Service Offerings surface does not include:
+
+- generic import of unmanaged OpenBao clusters
+- ordinary claim-reconcile adoption of directly managed `OpenBaoCluster` objects
+- arbitrary mutation of low-level workload fields through the claim API
+- broad bootstrap modes beyond the supported claim-managed posture
+- ongoing in-band management of auth methods, policies, secret engines, or audit devices after bootstrap
+- secret-value movement between clusters
+
+## Open questions
+
+Open design questions include:
+
+- how much of the Service Offering alias layer should be exposed in the first public API
+- which claim upgrade classes should be tenant-facing and which should remain platform-admin workflows
+- how adoption of existing direct `OpenBaoCluster` objects should be handled without weakening ownership safety
+
+## Related work
+
+This design note connects to:
+
+- <SiteLink docId="roadmap">Roadmap</SiteLink>
+- <SiteLink docId="architecture/operator-invariants">Operator invariants</SiteLink>
+- <SiteLink docId="reference/known-limitations">Known limitations</SiteLink>
diff --git a/website/versioned_docs/version-0.3.0/design/index.mdx b/website/versioned_docs/version-0.3.0/design/index.mdx
new file mode 100644
index 000000000..ba0f6abf5
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/design/index.mdx
@@ -0,0 +1,48 @@
+---
+title: Design
+slug: /design
+description: Selected public design notes for active OpenBao Operator features.
+hide_title: true
+pageType: concept
+---
+
+<PageHeader
+  title="Design notes"
+  lede="Selected public design notes for active OpenBao Operator features."
+/>
+
+<Callout type="note" title="Design scope">
+
+This section is not a complete backlog, local workstream archive, or promise to ship every described detail. It
+contains selected public design notes where visibility helps reviewers, users, and maintainers understand active
+or near-term work.
+
+</Callout>
+
+<RouteList
+  title="Current design notes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Claims and Service Offerings',
+      description: 'Self-service OpenBao clusters through a claim API and platform-owned offerings.',
+      docId: 'design/claims-and-service-offerings',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related sections"
+  items={[
+    {
+      label: 'Roadmap',
+      description: 'Project direction and planned modular capability areas.',
+      docId: 'roadmap',
+    },
+    {
+      label: 'Operator invariants',
+      description: 'Lifecycle contracts and safety properties that design work must preserve.',
+      docId: 'architecture/operator-invariants',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/index.mdx b/website/versioned_docs/version-0.3.0/index.mdx
new file mode 100644
index 000000000..b53494027
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/index.mdx
@@ -0,0 +1,105 @@
+---
+title: Operator Docs
+slug: /
+hide_title: true
+pageType: landing
+description: OpenBao Operator documentation for installation, configuration, operations, security, and reference material, with recovery and restore kept inside Operate.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Operator docs"
+  title="OpenBao Operator documentation"
+  lede="Installation, configuration, day 2 operations, security, architecture, and reference material for OpenBao Operator. Recovery and restore guidance lives under Operate."
+  actions={[
+    {label: 'Start with Get Started', docId: 'user-guide/index', variant: 'primary'},
+    {label: 'Open Operate', docId: 'user-guide/openbaocluster/operations/index', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Use these docs to"
+    items={[
+      'deploy OpenBao Operator for the first time',
+      'move from installation into configuration and day 2 operations',
+      'understand security posture and tenant boundaries',
+      'move from troubleshooting into recovery and restore when the cluster is unstable',
+    ]}
+  />
+</PageHero>
+
+<Callout type="note" title="Pre-GA release line">
+
+OpenBao Operator is intended for real deployments, but the CRD API remains `v1alpha1`, minor releases may introduce breaking changes, and support is best-effort for the latest published stable line.
+
+</Callout>
+
+<RouteList
+  title="Primary routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Get Started',
+      description: 'Choose a deployment model, install the operator, create the first cluster, and hand off cleanly into day 2 work.',
+      docId: 'user-guide/index',
+    },
+    {
+      eyebrow: '02',
+      title: 'Operate',
+      description: 'Plan upgrades, backups, maintenance, troubleshooting, recovery, and production hardening around the cluster lifecycle.',
+      docId: 'user-guide/openbaocluster/operations/index',
+    },
+    {
+      eyebrow: '03',
+      title: 'Security',
+      description: 'Understand the trust boundaries, admission posture, workload controls, and multi-tenant assumptions behind the platform.',
+      docId: 'security/index',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Deployment planning"
+  items={[
+    {
+      label: 'Configure',
+      description: 'Set profiles, bootstrap, exposure, storage, and observability before production traffic arrives.',
+      docId: 'user-guide/openbaocluster/configuration/index',
+    },
+    {
+      label: 'Validated Deployments',
+      description: 'Use tested baselines, recipes, and DR lanes when you want a deployment path to reproduce.',
+      docId: 'user-guide/validated-deployments/index',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Supporting sections"
+  items={[
+    {
+      label: 'Roadmap',
+      description: 'Review the project direction for lifecycle, self-service, multi-cluster, federation, and application integration work.',
+      docId: 'roadmap',
+    },
+    {
+      label: 'Architecture',
+      description: 'Controller boundaries, lifecycle coordination, and the internal reasoning behind operator behavior.',
+      docId: 'architecture/index',
+    },
+    {
+      label: 'Reference',
+      description: 'Compatibility, support posture, API reference, and status and event semantics.',
+      docId: 'reference/index',
+    },
+    {
+      label: 'Releases',
+      description: 'Versioned release context aligned with the published docs and artifacts.',
+      to: '/releases',
+    },
+    {
+      label: 'Contribute',
+      description: 'Development setup, standards, CI, testing, and release management guidance.',
+      to: '/contribute',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/api.md b/website/versioned_docs/version-0.3.0/reference/api.md
new file mode 100644
index 000000000..4c0f1a388
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/api.md
@@ -0,0 +1,2455 @@
+---
+title: API Reference
+description: Generated API reference for OpenBao Operator CRDs from api/v1alpha1.
+pageType: reference
+journey: reference
+---
+
+<PageHero
+  variant="minimal"
+  eyebrow="Reference / API Surface"
+  title="Use the API reference when you need the exact CRD field contract."
+  lede="This page is generated from `api/v1alpha1` and is the source of truth for field-level schema, validation, and description details across the operator CRDs."
+  actions={[
+    {label: 'Open compatibility matrix', docId: 'reference/compatibility', variant: 'primary'},
+    {label: 'Open status and events', docId: 'reference/status-and-events', variant: 'secondary'},
+  ]}
+/>
+
+<Callout type="info" title="Generated file">
+
+This page is generated from `api/v1alpha1` by `make api-reference`.
+Do not edit this file manually.
+
+</Callout>
+
+## CRDs
+
+<Tabs groupId="openbaocluster-openbaorestore-openbaotenant">
+
+<TabItem value="openbaocluster" label="OpenBaoCluster">
+
+## Packages
+- [openbao.org/v1alpha1](#openbaoorgv1alpha1)
+
+
+## openbao.org/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.
+
+### Resource Types
+- [OpenBaoCluster](#openbaocluster)
+
+
+
+#### ACMEConfig
+
+
+
+ACMEConfig configures ACME certificate management for OpenBao.
+See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters
+
+
+
+_Appears in:_
+- [TLSConfig](#tlsconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `directoryURL` _string_ | DirectoryURL is the ACME directory URL (e.g., "https://acme-v02.api.letsencrypt.org/directory"). |  | MinLength: 1 <br /> |
+| `domain` _string_ | Domain is the domain name for which to obtain the certificate.<br />Deprecated: use Domains to request a certificate with multiple SANs. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `domains` _string array_ | Domains is the list of domain names for which to obtain the certificate.<br />This maps to OpenBao's listener `tls_acme_domains` field.<br />When empty, the operator will default to an internal Service name suitable for<br />private ACME CAs running inside the cluster (e.g., "&lt;cluster&gt;-acme.&lt;namespace&gt;.svc"). |  | MinItems: 1 <br />Optional: \{\} <br /> |
+| `email` _string_ | Email is the email address to use for ACME registration. |  | Optional: \{\} <br /> |
+| `sharedCache` _[ACMESharedCacheConfig](#acmesharedcacheconfig)_ | SharedCache configures a filesystem cache shared across OpenBao replicas for ACME account<br />and certificate state. This is required for HA ACME topologies where more than one Pod<br />can serve the same hostname concurrently. |  | Optional: \{\} <br /> |
+
+
+#### ACMESharedCacheConfig
+
+
+
+ACMESharedCacheConfig configures the shared filesystem cache for ACME account and certificate state.
+See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters
+
+
+
+_Appears in:_
+- [ACMEConfig](#acmeconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `mode` _[ACMESharedCacheMode](#acmesharedcachemode)_ | Mode selects whether the operator creates a dedicated RWX PVC or mounts an existing one. |  | Enum: [ManagedPVC ExistingPVC] <br /> |
+| `existingClaimName` _string_ | ExistingClaimName is the name of a pre-created RWX PVC in the same namespace.<br />Required when Mode is ExistingPVC. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `size` _string_ | Size is the requested capacity for the managed ACME cache PVC.<br />Required when Mode is ManagedPVC. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `storageClassName` _string_ | StorageClassName is an optional StorageClass for the managed ACME cache PVC. |  | Optional: \{\} <br /> |
+
+
+#### ACMESharedCacheMode
+
+_Underlying type:_ _string_
+
+ACMESharedCacheMode controls how the operator provides a shared filesystem for OpenBao's ACME cache.
+
+_Validation:_
+- Enum: [ManagedPVC ExistingPVC]
+
+_Appears in:_
+- [ACMESharedCacheConfig](#acmesharedcacheconfig)
+
+| Field | Description |
+| --- | --- |
+| `ManagedPVC` | ACMESharedCacheModeManagedPVC instructs the operator to create a dedicated RWX PVC.<br /> |
+| `ExistingPVC` | ACMESharedCacheModeExistingPVC instructs the operator to mount an existing RWX PVC.<br /> |
+
+
+#### AWSKMSSealConfig
+
+
+
+AWSKMSSealConfig configures the AWS KMS seal type.
+See: https://openbao.org/docs/configuration/seal/awskms/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `region` _string_ | Region is the AWS region where the encryption key lives. |  | MinLength: 1 <br /> |
+| `kmsKeyID` _string_ | KMSKeyID is the AWS KMS key ID or ARN to use for encryption and decryption.<br />An alias in the format "alias/key-alias-name" may also be used. |  | MinLength: 1 <br /> |
+| `endpoint` _string_ | Endpoint is the KMS API endpoint to be used for AWS KMS requests.<br />Useful when connecting to KMS over a VPC Endpoint. |  | Optional: \{\} <br /> |
+| `accessKey` _string_ | AccessKey is the AWS access key ID to use.<br />Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead. |  | Optional: \{\} <br /> |
+| `secretKey` _string_ | SecretKey is the AWS secret access key to use.<br />Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead. |  | Optional: \{\} <br /> |
+| `sessionToken` _string_ | SessionToken specifies the AWS session token. |  | Optional: \{\} <br /> |
+
+
+#### AdminOpsControllerStatus
+
+
+
+AdminOpsControllerStatus holds status owned by the adminops controller.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `lastError` _[ControllerErrorStatus](#controllererrorstatus)_ | LastError is the last adminops-controller error observed for this cluster. |  | Optional: \{\} <br /> |
+
+
+#### AuditDevice
+
+
+
+AuditDevice defines a declarative audit device configuration.
+See: https://openbao.org/docs/configuration/audit/
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the type of audit device (e.g., "file", "syslog", "socket", "http"). |  | Enum: [file syslog socket http] <br />MinLength: 1 <br /> |
+| `path` _string_ | Path is the path of the audit device in the root namespace. |  | MinLength: 1 <br /> |
+| `description` _string_ | Description is an optional description for the audit device. |  | Optional: \{\} <br /> |
+| `fileOptions` _[FileAuditOptions](#fileauditoptions)_ | FileOptions configures options for file audit devices.<br />Only used when Type is "file". |  | Optional: \{\} <br /> |
+| `httpOptions` _[HTTPAuditOptions](#httpauditoptions)_ | HTTPOptions configures options for HTTP audit devices.<br />Only used when Type is "http". |  | Optional: \{\} <br /> |
+| `syslogOptions` _[SyslogAuditOptions](#syslogauditoptions)_ | SyslogOptions configures options for syslog audit devices.<br />Only used when Type is "syslog". |  | Optional: \{\} <br /> |
+| `socketOptions` _[SocketAuditOptions](#socketauditoptions)_ | SocketOptions configures options for socket audit devices.<br />Only used when Type is "socket". |  | Optional: \{\} <br /> |
+| `options` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#json-v1-apiextensions-k8s-io)_ | Options contains device-specific configuration options as a string map.<br />This is a fallback for backward compatibility and advanced use cases.<br />If structured options (FileOptions, HTTPOptions, etc.) are provided, they take precedence.<br />OpenBao audit options are string-to-string; scalar JSON values are rendered as strings,<br />while nested objects and arrays are rejected. For HTTP headers, prefer httpOptions.headers. |  | Optional: \{\} <br /> |
+
+
+#### AuditFileStorageConfig
+
+
+
+AuditFileStorageConfig configures the shared filesystem integration point for file audit devices.
+
+The operator mounts the selected PVC into each OpenBao Pod. Each Pod uses a
+pod-specific subPath under the same PVC so all Pods can render the same audit
+file path while collectors can mount the PVC read-only and read per-Pod audit
+files from the backing directories. This storage is intended as a collector
+handoff and replay buffer, not as the authoritative compliance archive.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `mode` _[AuditFileStorageMode](#auditfilestoragemode)_ | Mode selects whether the operator creates a dedicated RWX PVC or mounts an existing one. |  | Enum: [ManagedPVC ExistingPVC] <br /> |
+| `existingClaimName` _string_ | ExistingClaimName is the name of a pre-created RWX PVC in the same namespace.<br />Required when Mode is ExistingPVC. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `size` _string_ | Size is the requested capacity for the managed audit file storage PVC.<br />Required when Mode is ManagedPVC. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `storageClassName` _string_ | StorageClassName is an optional StorageClass for the managed audit file storage PVC. |  | Optional: \{\} <br /> |
+| `mountPath` _string_ | MountPath is where the audit file storage PVC is mounted in OpenBao Pods.<br />File audit device paths must be under this path when auditFileStorage is configured. | /openbao/audit | Optional: \{\} <br /> |
+
+
+#### AuditFileStorageMode
+
+_Underlying type:_ _string_
+
+AuditFileStorageMode controls how the operator provides shared filesystem storage for file audit logs.
+
+_Validation:_
+- Enum: [ManagedPVC ExistingPVC]
+
+_Appears in:_
+- [AuditFileStorageConfig](#auditfilestorageconfig)
+
+| Field | Description |
+| --- | --- |
+| `ManagedPVC` | AuditFileStorageModeManagedPVC instructs the operator to create a dedicated RWX PVC.<br /> |
+| `ExistingPVC` | AuditFileStorageModeExistingPVC instructs the operator to mount an existing RWX PVC.<br /> |
+
+
+#### AutoRollbackConfig
+
+
+
+AutoRollbackConfig defines conditions that trigger automatic rollback.
+
+
+
+_Appears in:_
+- [BlueGreenConfig](#bluegreenconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether automatic rollback is active. | true |  |
+| `onJobFailure` _boolean_ | OnJobFailure triggers rollback when job failures exceed MaxJobFailures.<br />Only applies during early phases (before demoting Blue). | true |  |
+| `onValidationFailure` _boolean_ | OnValidationFailure triggers automatic abort/rollback if the pre-promotion<br />hook fails. | true |  |
+
+
+#### AzureKeyVaultSealConfig
+
+
+
+AzureKeyVaultSealConfig configures the Azure Key Vault seal type.
+See: https://openbao.org/docs/configuration/seal/azurekeyvault/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `vaultName` _string_ | VaultName is the name of the Azure Key Vault. |  | MinLength: 1 <br /> |
+| `keyName` _string_ | KeyName is the name of the key in the Azure Key Vault. |  | MinLength: 1 <br /> |
+| `tenantID` _string_ | TenantID is the Azure tenant ID. |  | Optional: \{\} <br /> |
+| `clientID` _string_ | ClientID is the Azure client ID. |  | Optional: \{\} <br /> |
+| `clientSecret` _string_ | ClientSecret is the Azure client secret.<br />Note: It is strongly recommended to use CredentialsSecretRef or Managed Service Identity instead. |  | Optional: \{\} <br /> |
+| `resource` _string_ | Resource is the Azure AD resource endpoint.<br />For Managed HSM, this should usually be "managedhsm.azure.net". |  | Optional: \{\} <br /> |
+| `environment` _string_ | Environment is the Azure environment (e.g., "AzurePublicCloud", "AzureUSGovernmentCloud"). |  | Optional: \{\} <br /> |
+
+
+#### AzureTargetConfig
+
+
+
+AzureTargetConfig holds Azure Blob Storage specific configuration.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `storageAccount` _string_ | StorageAccount is the Azure storage account name.<br />Required when using Azure provider. |  | MinLength: 1 <br /> |
+| `container` _string_ | Container is the blob container name. If empty, uses the Bucket field value. |  | Optional: \{\} <br /> |
+
+
+#### BackendTLSConfig
+
+
+
+BackendTLSConfig configures BackendTLSPolicy for Gateway API.
+
+
+
+_Appears in:_
+- [GatewayConfig](#gatewayconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether the Operator creates a BackendTLSPolicy.<br />When true (default when Gateway is enabled), the Operator creates a BackendTLSPolicy<br />that enables HTTPS and certificate validation for backend connections.<br />When false, no BackendTLSPolicy is created and the Gateway will use HTTP (or rely on<br />external configuration for TLS). | true | Optional: \{\} <br /> |
+| `hostname` _string_ | Hostname is the hostname to verify in the backend certificate.<br />If not specified, defaults to the Service DNS name: &lt;service-name&gt;.&lt;namespace&gt;.svc<br />This should match the certificate SAN or the service DNS name. |  | Optional: \{\} <br /> |
+
+
+#### BackupRetention
+
+
+
+BackupRetention defines retention policy for backups.
+
+
+
+_Appears in:_
+- [BackupSchedule](#backupschedule)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `maxCount` _integer_ | MaxCount is the maximum number of backups to retain (0 = unlimited). |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `maxAge` _string_ | MaxAge is the maximum age of backups to retain, e.g., "168h" for 7 days.<br />Backups older than this are deleted after successful new backup upload. |  | Optional: \{\} <br /> |
+
+
+#### BackupSchedule
+
+
+
+BackupSchedule defines when and where snapshots are stored.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `schedule` _string_ | Schedule is a cron-style schedule, for example "0 3 * * *". |  | MinLength: 1 <br /> |
+| `target` _[BackupTarget](#backuptarget)_ | Target is the object storage configuration for backups. |  |  |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for backup operations. When set, the backup executor will use JWT Auth<br />(projected ServiceAccount token) instead of a static token. This is the preferred authentication<br />method as tokens are automatically rotated by Kubernetes.<br />The role must be configured in OpenBao and must grant the "read" capability on<br />sys/storage/raft/snapshot. The role must bind to the backup ServiceAccount<br />(&lt;cluster-name&gt;-backup-serviceaccount) in the cluster namespace.<br />If OIDC is enabled in SelfInit and this field is empty, a default role<br />named "openbao-operator-backup" will be assumed/created. |  | Optional: \{\} <br /> |
+| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token to use for backup operations (fallback method).<br />The Secret must exist in the same namespace as the OpenBaoCluster.<br />Cross-namespace references are not allowed for security reasons.<br />For standard clusters (non self-init), this is typically omitted and the<br />operator uses the root token from &lt;cluster&gt;-root-token. For self-init<br />clusters (no root token Secret), this field must reference a token with<br />permission to read sys/storage/raft/snapshot.<br />If JWTAuthRole is set, this field is ignored in favor of JWT Auth. |  | Optional: \{\} <br /> |
+| `retention` _[BackupRetention](#backupretention)_ | Retention defines optional backup retention policy. |  | Optional: \{\} <br /> |
+| `image` _string_ | Image is the container image to use for backup operations.<br />If not specified, defaults to "&lt;repo&gt;:X.Y.Z" where &lt;repo&gt; is derived from OPERATOR_BACKUP_IMAGE_REPOSITORY<br />(default: "ghcr.io/dc-tec/openbao-backup") and the tag matches OPERATOR_VERSION.<br />This allows users to override the image for air-gapped environments or custom registries. |  | Optional: \{\} <br /> |
+
+
+#### BackupStatus
+
+
+
+BackupStatus tracks the state of backups for a cluster.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `lastBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastBackupTime is the timestamp of the last successful backup. |  | Optional: \{\} <br /> |
+| `lastAttemptTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastAttemptTime is the timestamp of the last backup attempt, regardless of outcome.<br />This is used to avoid retry loops when a scheduled backup fails. |  | Optional: \{\} <br /> |
+| `lastAttemptScheduledTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastAttemptScheduledTime is the scheduled time of the last backup attempt.<br />It is derived from the cron schedule and used to ensure at-most-once execution<br />per scheduled window. |  | Optional: \{\} <br /> |
+| `lastHandledManualTrigger` _string_ | LastHandledManualTrigger is the last observed manual trigger token that<br />has progressed into an actual backup attempt. |  | Optional: \{\} <br /> |
+| `lastBackupSize` _integer_ | LastBackupSize is the size in bytes of the last successful backup. |  | Optional: \{\} <br /> |
+| `lastBackupDuration` _string_ | LastBackupDuration is how long the last backup took (e.g., "45s"). |  | Optional: \{\} <br /> |
+| `lastBackupName` _string_ | LastBackupName is the object key/path of the last successful backup. |  | Optional: \{\} <br /> |
+| `nextScheduledBackup` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | NextScheduledBackup is when the next backup is scheduled. |  | Optional: \{\} <br /> |
+| `consecutiveFailures` _integer_ | ConsecutiveFailures is the number of consecutive backup failures. |  | Optional: \{\} <br /> |
+| `lastFailureReason` _string_ | LastFailureReason is the low-cardinality reason code for the last backup failure (if applicable). |  | Optional: \{\} <br /> |
+| `lastFailureMessage` _string_ | LastFailureMessage is the detailed message for the last backup failure (if applicable). |  | Optional: \{\} <br /> |
+| `lastFailureTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastFailureTime is when the last backup failure was recorded. |  | Optional: \{\} <br /> |
+
+
+#### BackupTarget
+
+
+
+BackupTarget describes a generic, cloud-agnostic object storage destination.
+
+
+
+_Appears in:_
+- [BackupSchedule](#backupschedule)
+- [RestoreSource](#restoresource)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `provider` _string_ | Provider selects the storage backend. Defaults to "s3" for backward compatibility. | s3 | Enum: [s3 gcs azure] <br />Optional: \{\} <br /> |
+| `endpoint` _string_ | Endpoint is the HTTP(S) endpoint for the object storage service.<br />For S3: Required (e.g., "https://s3.amazonaws.com" or MinIO endpoint).<br />For GCS: Optional (defaults to googleapis.com).<br />For Azure: Optional (derived from StorageAccount if not specified). |  | Optional: \{\} <br /> |
+| `bucket` _string_ | Bucket is the bucket or container name. |  | MinLength: 1 <br /> |
+| `pathPrefix` _string_ | PathPrefix is an optional prefix within the bucket for this cluster's snapshots. |  | Optional: \{\} <br /> |
+| `credentialsSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | CredentialsSecretRef optionally references a Secret containing credentials for the object store.<br />The Secret must exist in the same namespace as the owning OpenBao resource.<br />Cross-namespace references are not allowed for security reasons.<br />For S3: Expected keys are "accessKeyId" and "secretAccessKey" (optional: "sessionToken", "region", "caCert").<br />For GCS: Expected key is "credentials.json" containing a service account JSON key.<br />For Azure: Expected keys are "accountKey" or "connectionString".<br />Omit this field when relying on ambient workload identity or another default credential chain. |  | Optional: \{\} <br /> |
+| `workloadIdentity` _[WorkloadIdentityConfig](#workloadidentityconfig)_ | WorkloadIdentity optionally applies provider-specific metadata required by cloud workload identity integrations.<br />Use this for ambient identity setups such as EKS Pod Identity or IRSA, GKE Workload Identity, or Azure Workload Identity.<br />When omitted, backup and restore workloads can still use any credentials exposed through the pod's default provider chain. |  | Optional: \{\} <br /> |
+| `partSize` _integer_ | PartSize is the size of each part in multipart uploads (in bytes).<br />Defaults to 10MB (10485760 bytes). Larger values may improve performance for large snapshots<br />on fast networks, while smaller values may be better for slow or unreliable networks. | 10485760 | Minimum: 5.24288e+06 <br />Optional: \{\} <br /> |
+| `concurrency` _integer_ | Concurrency is the number of concurrent parts to upload during multipart uploads.<br />Defaults to 3. Higher values may improve throughput on fast networks but increase<br />memory usage and may overwhelm slower storage backends. | 3 | Maximum: 10 <br />Minimum: 1 <br />Optional: \{\} <br /> |
+| `region` _string_ | Region is the AWS region to use for S3-compatible clients.<br />For AWS, this should match the bucket region (for example, "eu-west-1").<br />For many S3-compatible stores (MinIO/Ceph), this can be any non-empty value.<br />Only used when Provider is "s3". | us-east-1 | Optional: \{\} <br /> |
+| `roleArn` _string_ | RoleARN is the IAM role ARN (or S3-compatible equivalent) to assume via Web Identity.<br />When set, backup and restore Jobs mount a projected ServiceAccount token and set the<br />AWS Web Identity environment variables explicitly.<br />Leave this empty when relying on ambient workload identity or provider-managed default credentials instead.<br />Only used when Provider is "s3". |  | Optional: \{\} <br /> |
+| `usePathStyle` _boolean_ | UsePathStyle controls whether to use path-style addressing (bucket.s3.amazonaws.com/object)<br />or virtual-hosted-style addressing (bucket.s3.amazonaws.com/object).<br />Set to true for MinIO and S3-compatible stores that require path-style.<br />Set to false for AWS S3 (default, as AWS is deprecating path-style).<br />Only used when Provider is "s3". | false | Optional: \{\} <br /> |
+| `gcs` _[GCSTargetConfig](#gcstargetconfig)_ | GCS contains Google Cloud Storage specific configuration.<br />Only used when Provider is "gcs". |  | Optional: \{\} <br /> |
+| `azure` _[AzureTargetConfig](#azuretargetconfig)_ | Azure contains Azure Blob Storage specific configuration.<br />Only used when Provider is "azure". |  | Optional: \{\} <br /> |
+| `insecureSkipVerify` _boolean_ | InsecureSkipVerify allows skipping TLS verification (useful for MinIO/LocalStack/Azurite with self-signed certs).<br />This applies to all providers that support TLS. |  | Optional: \{\} <br /> |
+
+
+#### BlueGreenConfig
+
+
+
+BlueGreenConfig configures the behavior when Type is BlueGreen.
+
+
+
+_Appears in:_
+- [UpgradeConfig](#upgradeconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `autoPromote` _boolean_ | AutoPromote controls whether newly started blue/green upgrades<br />automatically switch traffic and delete the old cluster after sync.<br />If false when an upgrade starts, that upgrade stays in the Syncing<br />phase waiting for an explicit promotion request via spec.upgrade.requests.promote.<br />Changing this field while an upgrade is already in progress affects only<br />future upgrades. | true |  |
+| `verification` _[VerificationConfig](#verificationconfig)_ | VerificationConfig allows defining custom health checks before promotion. |  | Optional: \{\} <br /> |
+| `maxJobFailures` _integer_ | MaxJobFailures is the maximum consecutive job failures before aborting/rolling back.<br />Defaults to 5 if not specified. | 5 | Minimum: 1 <br />Optional: \{\} <br /> |
+| `preUpgradeSnapshot` _boolean_ | PreUpgradeSnapshot triggers a backup at the start of an upgrade.<br />Creates a recovery point before any changes are made.<br />Requires spec.backup to be configured. |  | Optional: \{\} <br /> |
+| `autoRollback` _[AutoRollbackConfig](#autorollbackconfig)_ | AutoRollback configures automatic rollback behavior. |  | Optional: \{\} <br /> |
+
+
+#### BlueGreenPhase
+
+_Underlying type:_ _string_
+
+BlueGreenPhase is a high-level summary of blue/green upgrade state.
+
+_Validation:_
+- Enum: [Idle DeployingGreen JoiningMesh Syncing Promoting DemotingBlue Cleanup RestoringReadReplicas RollingBack RollbackCleanup]
+
+_Appears in:_
+- [BlueGreenStatus](#bluegreenstatus)
+
+| Field | Description |
+| --- | --- |
+| `Idle` | PhaseIdle indicates no blue/green upgrade is in progress.<br /> |
+| `DeployingGreen` | PhaseDeployingGreen indicates the Green StatefulSet is being created and pods are becoming ready.<br />This phase includes waiting for pods to be unsealed.<br /> |
+| `JoiningMesh` | PhaseJoiningMesh indicates Green pods are joining the Raft cluster as non-voters.<br /> |
+| `Syncing` | PhaseSyncing indicates waiting for Green nodes to catch up with Blue nodes.<br /> |
+| `Promoting` | PhasePromoting indicates Green nodes are being promoted to voters.<br /> |
+| `DemotingBlue` | PhaseDemotingBlue indicates Blue nodes are being demoted to non-voters.<br /> |
+| `Cleanup` | PhaseCleanup indicates Blue StatefulSet is being deleted.<br /> |
+| `RestoringReadReplicas` | PhaseRestoringReadReplicas indicates the steady-state read-replica pool is<br />being restored after cutover cleanup and must converge before the upgrade<br />returns to Idle.<br /> |
+| `RollingBack` | PhaseRollingBack indicates the upgrade is being rolled back.<br />Blue nodes are re-promoted and Green nodes are demoted.<br /> |
+| `RollbackCleanup` | PhaseRollbackCleanup indicates Green StatefulSet is being deleted after rollback.<br /> |
+
+
+#### BlueGreenStatus
+
+
+
+BlueGreenStatus tracks the lifecycle of the "Green" revision during blue/green upgrades.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `phase` _[BlueGreenPhase](#bluegreenphase)_ | Phase is the current phase of the blue/green upgrade. |  | Enum: [Idle DeployingGreen JoiningMesh Syncing Promoting DemotingBlue Cleanup RestoringReadReplicas RollingBack RollbackCleanup] <br /> |
+| `blueRevision` _string_ | BlueRevision is the hash/name of the currently active cluster. |  |  |
+| `blueImage` _string_ | BlueImage is the container image used by the Blue cluster.<br />This ensures the Blue cluster is not actively upgraded when spec.image changes. |  |  |
+| `greenRevision` _string_ | GreenRevision is the hash/name of the next cluster (if upgrade in progress). |  |  |
+| `manualPromotionRequired` _boolean_ | ManualPromotionRequired snapshots whether the current in-flight blue/green<br />upgrade requires an explicit spec.upgrade.requests.promote request before<br />promotion can proceed. It is derived from spec.upgrade.blueGreen.autoPromote<br />when the upgrade starts. |  | Optional: \{\} <br /> |
+| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | StartTime is when the current phase began. |  |  |
+| `jobFailureCount` _integer_ | JobFailureCount tracks consecutive job failures in the current phase.<br />Reset to 0 on phase transition or successful job completion. |  | Optional: \{\} <br /> |
+| `lastJobFailure` _string_ | LastJobFailure records the name of the last failed job for debugging. |  | Optional: \{\} <br /> |
+| `preUpgradeSnapshotJobName` _string_ | PreUpgradeSnapshotJobName is the name of the backup job triggered at upgrade start. |  | Optional: \{\} <br /> |
+| `rollbackReason` _string_ | RollbackReason records why a rollback was triggered (if any). |  | Optional: \{\} <br /> |
+| `rollbackStartTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | RollbackStartTime is when the rollback was initiated. |  | Optional: \{\} <br /> |
+| `rollbackAttempt` _integer_ | RollbackAttempt increments each time rollback automation is retried.<br />It is used to produce stable, deterministic Job names per attempt. |  | Optional: \{\} <br /> |
+
+
+#### BreakGlassReason
+
+_Underlying type:_ _string_
+
+BreakGlassReason describes why the operator required manual intervention.
+
+_Validation:_
+- Enum: [RollbackConsensusRepairFailed RollbackCleanupPeerRemovalFailed]
+
+_Appears in:_
+- [BreakGlassStatus](#breakglassstatus)
+
+| Field | Description |
+| --- | --- |
+| `RollbackConsensusRepairFailed` |  |
+| `RollbackCleanupPeerRemovalFailed` |  |
+
+
+#### BreakGlassStatus
+
+
+
+BreakGlassStatus captures safe-mode / break-glass state and recovery guidance.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `active` _boolean_ | Active indicates whether break glass mode is currently active. |  | Optional: \{\} <br /> |
+| `reason` _[BreakGlassReason](#breakglassreason)_ | Reason is a stable, typed reason for entering break glass mode. |  | Enum: [RollbackConsensusRepairFailed RollbackCleanupPeerRemovalFailed] <br />Optional: \{\} <br /> |
+| `message` _string_ | Message provides a short summary of the detected unsafe state. |  | Optional: \{\} <br /> |
+| `nonce` _string_ | Nonce is the acknowledgment token required to resume automation. |  | Optional: \{\} <br /> |
+| `enteredAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | EnteredAt is when break glass mode became active. |  | Optional: \{\} <br /> |
+| `steps` _string array_ | Steps provides deterministic recovery guidance. |  | Optional: \{\} <br /> |
+| `acknowledgedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | AcknowledgedAt records when break glass was acknowledged. |  | Optional: \{\} <br /> |
+
+
+#### ClusterOperation
+
+_Underlying type:_ _string_
+
+ClusterOperation identifies a mutually-exclusive operator operation.
+
+_Validation:_
+- Enum: [Upgrade Backup Restore]
+
+_Appears in:_
+- [OperationLockStatus](#operationlockstatus)
+
+| Field | Description |
+| --- | --- |
+| `Upgrade` |  |
+| `Backup` |  |
+| `Restore` |  |
+
+
+#### ClusterPhase
+
+_Underlying type:_ _string_
+
+ClusterPhase is a high-level summary of cluster state.
+
+_Validation:_
+- Enum: [Initializing Running Upgrading BackingUp Failed]
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description |
+| --- | --- |
+| `Initializing` |  |
+| `Running` |  |
+| `Upgrading` |  |
+| `BackingUp` |  |
+| `Failed` |  |
+
+
+
+
+#### ControllerErrorStatus
+
+
+
+ControllerErrorStatus captures a controller-scoped error signal that the status controller
+can translate into high-level conditions.
+
+
+
+_Appears in:_
+- [AdminOpsControllerStatus](#adminopscontrollerstatus)
+- [UpgradeProgress](#upgradeprogress)
+- [WorkloadControllerStatus](#workloadcontrollerstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `reason` _string_ | Reason is a low-cardinality identifier for the error. |  | Optional: \{\} <br /> |
+| `message` _string_ | Message is a human-readable error message (best-effort). |  | Optional: \{\} <br /> |
+| `at` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | At is when the error was observed (best-effort). |  | Optional: \{\} <br /> |
+
+
+#### DeletionPolicy
+
+_Underlying type:_ _string_
+
+DeletionPolicy defines what happens to underlying resources when the CR is deleted.
+
+_Validation:_
+- Enum: [Retain DeletePVCs DeleteAll]
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description |
+| --- | --- |
+| `Retain` | DeletionPolicyRetain keeps StatefulSets, PVCs, and external backups.<br /> |
+| `DeletePVCs` | DeletionPolicyDeletePVCs deletes StatefulSets and PVCs, but retains external backups.<br /> |
+| `DeleteAll` | DeletionPolicyDeleteAll deletes StatefulSets, PVCs, and attempts to delete external backups.<br /> |
+
+
+#### FileAuditOptions
+
+
+
+FileAuditOptions configures options for file audit devices.
+See: https://openbao.org/docs/audit/file/
+
+
+
+_Appears in:_
+- [AuditDevice](#auditdevice)
+- [SelfInitAuditDevice](#selfinitauditdevice)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `filePath` _string_ | FilePath is the path to where the audit log will be written.<br />Special keywords: "stdout" writes to standard output, "discard" discards output. |  | MinLength: 1 <br /> |
+| `mode` _string_ | Mode is a string containing an octal number representing the bit pattern for the file mode.<br />Defaults to "0600" if not specified. Set to "0000" to prevent OpenBao from modifying the file mode. |  | Optional: \{\} <br /> |
+
+
+#### GCPCloudKMSSealConfig
+
+
+
+GCPCloudKMSSealConfig configures the GCP Cloud KMS seal type.
+See: https://openbao.org/docs/configuration/seal/gcpckms/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `project` _string_ | Project is the GCP project ID. |  | MinLength: 1 <br /> |
+| `region` _string_ | Region is the GCP region where the key ring lives. |  | MinLength: 1 <br /> |
+| `keyRing` _string_ | KeyRing is the name of the GCP KMS key ring. |  | MinLength: 1 <br /> |
+| `cryptoKey` _string_ | CryptoKey is the name of the GCP KMS crypto key. |  | MinLength: 1 <br /> |
+| `credentials` _string_ | Credentials is the path to the GCP credentials JSON file.<br />Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity instead. |  | Optional: \{\} <br /> |
+
+
+#### GCSTargetConfig
+
+
+
+GCSTargetConfig holds Google Cloud Storage specific configuration.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `project` _string_ | Project is the GCP project ID. Optional if using ADC with default project or<br />if the credentials JSON includes the project. |  | Optional: \{\} <br /> |
+
+
+#### GatewayConfig
+
+
+
+GatewayConfig configures Kubernetes Gateway API access for the OpenBao cluster.
+This is an alternative to Ingress for external access, using the more modern
+and expressive Gateway API.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled activates Gateway API support for this cluster.<br />When true, the Operator creates an HTTPRoute for the cluster. |  |  |
+| `listenerName` _string_ | ListenerName optionally targets a specific listener (sectionName) on the referenced Gateway.<br />When set, the generated Route (HTTPRoute or TLSRoute) attaches only to that listener.<br />This is useful when a Gateway exposes multiple listeners for the same hostname (e.g. Traefik<br />"web" and "websecure") and you want deterministic attachment. |  | Optional: \{\} <br /> |
+| `gatewayRef` _[GatewayReference](#gatewayreference)_ | GatewayRef references an existing Gateway resource that will handle<br />traffic for this OpenBao cluster. The Gateway must already exist. |  |  |
+| `hostname` _string_ | Hostname for routing traffic to this OpenBao cluster.<br />This hostname will be automatically added to the TLS SANs. |  | MinLength: 1 <br /> |
+| `path` _string_ | Path prefix for the HTTPRoute (defaults to "/"). |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations to apply to the HTTPRoute resource. |  | Optional: \{\} <br /> |
+| `backendTLS` _[BackendTLSConfig](#backendtlsconfig)_ | BackendTLS configures BackendTLSPolicy for end-to-end TLS between the Gateway and OpenBao.<br />When enabled, the Operator creates a BackendTLSPolicy that configures the Gateway to use<br />HTTPS when communicating with the OpenBao backend service and validates the backend<br />certificate using the cluster's CA certificate. |  | Optional: \{\} <br /> |
+| `tlsPassthrough` _boolean_ | TLSPassthrough enables TLS passthrough mode using TLSRoute instead of HTTPRoute.<br />When true, the Operator creates a TLSRoute that routes encrypted TLS traffic based on SNI<br />without terminating TLS at the Gateway. OpenBao terminates TLS directly.<br />When false (default), the Operator creates an HTTPRoute with TLS termination at the Gateway.<br />Note: TLSRoute and HTTPRoute are mutually exclusive - only one can be used per cluster.<br />BackendTLSPolicy is not needed when TLSPassthrough is enabled since the Gateway does not<br />decrypt traffic. The Gateway listener must be configured with protocol: TLS and mode: Passthrough. |  | Optional: \{\} <br /> |
+
+
+#### GatewayReference
+
+
+
+GatewayReference identifies a Gateway resource.
+
+
+
+_Appears in:_
+- [GatewayConfig](#gatewayconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name of the Gateway resource. |  | MinLength: 1 <br /> |
+| `namespace` _string_ | Namespace of the Gateway resource. If empty, uses the OpenBaoCluster namespace. |  | Optional: \{\} <br /> |
+
+
+#### HTTPAuditOptions
+
+
+
+HTTPAuditOptions configures options for HTTP audit devices.
+See: https://openbao.org/docs/audit/http/
+
+
+
+_Appears in:_
+- [AuditDevice](#auditdevice)
+- [SelfInitAuditDevice](#selfinitauditdevice)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `uri` _string_ | URI is the URI of the remote server where the audit logs will be written. |  | MinLength: 1 <br /> |
+| `headers` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#json-v1-apiextensions-k8s-io)_ | Headers is a JSON object describing headers. Must take the shape map[string][]string,<br />i.e., an object of headers, with each having one or more values.<br />Headers without values will be ignored. The operator renders this object as OpenBao's<br />expected JSON-encoded options.headers string. |  | Optional: \{\} <br /> |
+
+
+#### ImageVerificationConfig
+
+
+
+ImageVerificationConfig configures supply chain security checks for container images.
+When enabled, verification applies to all operator-managed images for this cluster (StatefulSets, Deployments, and Jobs).
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether image verification is enforced. |  |  |
+| `publicKey` _string_ | PublicKey is the Cosign public key content used to verify the signature.<br />Required for static key verification. If empty, keyless verification will be used<br />(requires Issuer and Subject to be set). |  | Optional: \{\} <br /> |
+| `issuer` _string_ | Issuer is the OIDC issuer for keyless verification (e.g., https://token.actions.githubusercontent.com).<br />Required for keyless verification when PublicKey is not provided.<br />For GitHub Actions keyless verification, use: https://token.actions.githubusercontent.com |  | Optional: \{\} <br /> |
+| `subject` _string_ | Subject is the OIDC subject for keyless verification.<br />Required for keyless verification when PublicKey is not provided.<br />Example (GitHub Actions): https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/&lt;VERSION&gt;<br />The version in the subject MUST match the image tag version. |  | Optional: \{\} <br /> |
+| `issuerRegExp` _string_ | IssuerRegExp is a regular expression for the OIDC issuer when using keyless verification.<br />Use this to allow a controlled set of issuers instead of a single exact issuer string.<br />Requires SubjectRegExp when PublicKey is not provided. |  | Optional: \{\} <br /> |
+| `subjectRegExp` _string_ | SubjectRegExp is a regular expression for the OIDC subject when using keyless verification.<br />Use this to allow a controlled set of workflow identities instead of a single exact subject.<br />Requires IssuerRegExp when PublicKey is not provided. |  | Optional: \{\} <br /> |
+| `failurePolicy` _string_ | FailurePolicy defines behavior on verification failure.<br />"Block" blocks reconciliation of the affected workload when verification fails.<br />"Warn" logs an error and emits a Kubernetes Event but proceeds. | Block | Enum: [Warn Block] <br /> |
+| `ignoreTlog` _boolean_ | IgnoreTlog controls whether to verify against the Rekor transparency log.<br />When false (default), signatures are verified against Rekor for non-repudiation.<br />When true, only signature verification is performed without transparency log checks. | false | Optional: \{\} <br /> |
+| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array_ | ImagePullSecrets is a list of references to secrets in the same namespace<br />to use for pulling images from private registries during verification.<br />These secrets must be of type kubernetes.io/dockerconfigjson or kubernetes.io/dockercfg. |  | Optional: \{\} <br /> |
+
+
+#### IngressConfig
+
+
+
+IngressConfig controls optional HTTP(S) ingress in front of the OpenBao Service.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether the Operator manages an Ingress for external access. |  | Optional: \{\} <br /> |
+| `className` _string_ | ClassName is an optional IngressClassName (for example, "nginx", "traefik"). |  | Optional: \{\} <br /> |
+| `host` _string_ | Host is the primary host for external access, for example "bao.example.com". |  | MinLength: 1 <br /> |
+| `path` _string_ | Path is the HTTP path to route to OpenBao, defaulting to "/". |  | Optional: \{\} <br /> |
+| `pathType` _[IngressPathType](#ingresspathtype)_ | PathType identifies how the ingress controller should interpret Path. | Prefix | Enum: [Prefix Exact ImplementationSpecific] <br />Optional: \{\} <br /> |
+| `tlsSecretName` _string_ | TLSSecretName is an optional TLS Secret name; when empty the cluster TLS Secret is used. |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations to apply to the Ingress. |  | Optional: \{\} <br /> |
+| `readinessMode` _[IngressReadinessMode](#ingressreadinessmode)_ | ReadinessMode identifies when the operator should consider ingress<br />integration ready for endpoint publication. | LoadBalancerPublished | Enum: [Created LoadBalancerPublished] <br />Optional: \{\} <br /> |
+
+
+#### IngressPathType
+
+_Underlying type:_ _string_
+
+IngressPathType identifies how a Kubernetes Ingress path should match requests.
+
+_Validation:_
+- Enum: [Prefix Exact ImplementationSpecific]
+
+_Appears in:_
+- [IngressConfig](#ingressconfig)
+
+| Field | Description |
+| --- | --- |
+| `Prefix` | IngressPathTypePrefix uses prefix path matching.<br /> |
+| `Exact` | IngressPathTypeExact uses exact path matching.<br /> |
+| `ImplementationSpecific` | IngressPathTypeImplementationSpecific defers path matching to the controller.<br /> |
+
+
+#### IngressReadinessMode
+
+_Underlying type:_ _string_
+
+IngressReadinessMode identifies how the operator decides whether ingress
+integration is ready for endpoint publication.
+
+_Validation:_
+- Enum: [Created LoadBalancerPublished]
+
+_Appears in:_
+- [IngressConfig](#ingressconfig)
+
+| Field | Description |
+| --- | --- |
+| `Created` | IngressReadinessModeCreated considers ingress integration ready once the<br />managed Ingress object exists.<br /> |
+| `LoadBalancerPublished` | IngressReadinessModeLoadBalancerPublished considers ingress integration<br />ready only after the managed Ingress reports a published load balancer<br />address in status.<br /> |
+
+
+#### InitContainerConfig
+
+
+
+InitContainerConfig configures the init container used to render OpenBao configuration.
+The init container is responsible for rendering the final config.hcl from a template
+using environment variables such as HOSTNAME and POD_IP.
+
+The operator relies on this init container to render config.hcl at runtime. Disabling
+the init container is not supported and will be rejected by validation.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether the init container is used to render the configuration.<br />The operator requires the init container; disabling it is not supported. | true | Optional: \{\} <br /> |
+| `image` _string_ | Image is the container image to use for the init container.<br />If not specified, defaults to "&lt;repo&gt;:X.Y.Z" where &lt;repo&gt; is derived from OPERATOR_INIT_IMAGE_REPOSITORY<br />(default: "ghcr.io/dc-tec/openbao-init") and the tag matches OPERATOR_VERSION. |  | Optional: \{\} <br /> |
+
+
+#### KMIPSealConfig
+
+
+
+KMIPSealConfig configures the KMIP seal type.
+See: https://openbao.org/docs/configuration/seal/kmip/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `endpoint` _string_ | Endpoint is the KMIP server endpoint. |  | MinLength: 1 <br /> |
+| `kmsKeyID` _string_ | KMSKeyID is the unique identifier of the KMIP key to use. |  | MinLength: 1 <br /> |
+| `clientCert` _string_ | ClientCert is the path to the client certificate used for KMIP communication. |  | MinLength: 1 <br /> |
+| `clientKey` _string_ | ClientKey is the path to the private key used for KMIP communication. |  | MinLength: 1 <br /> |
+| `caCert` _string_ | CACert is the path to the CA certificate for KMIP communication. |  | Optional: \{\} <br /> |
+| `serverName` _string_ | ServerName is the TLS server name to use when connecting to the KMIP endpoint. |  | Optional: \{\} <br /> |
+| `timeout` _integer_ | Timeout is the timeout in seconds for KMIP requests. |  | Minimum: 1 <br />Optional: \{\} <br /> |
+| `encryptAlg` _string_ | EncryptAlg is the encryption algorithm used for KMIP requests. |  | Enum: [AES_GCM RSA_OAEP_SHA256 RSA_OAEP_SHA384 RSA_OAEP_SHA512] <br />Optional: \{\} <br /> |
+| `tls12Ciphers` _string_ | TLS12Ciphers configures the TLS 1.2 cipher suites to use when connecting<br />to the KMIP endpoint. |  | Optional: \{\} <br /> |
+| `disabled` _boolean_ | Disabled disables this seal configuration, for example during seal migration. |  | Optional: \{\} <br /> |
+
+
+#### ListenerConfig
+
+
+
+ListenerConfig allows tuning the TCP listener configuration.
+
+
+
+_Appears in:_
+- [OpenBaoConfiguration](#openbaoconfiguration)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `tlsDisable` _boolean_ | TLSDisable controls TLS on the listener.<br />Note: This is typically managed by the operator based on spec.tls.enabled. |  | Optional: \{\} <br /> |
+| `proxyProtocolBehavior` _string_ | ProxyProtocolBehavior allows configuring proxy protocol (e.g. for LoadBalancers). |  | Enum: [use_always allow_any deny_unauthorized] <br />Optional: \{\} <br /> |
+
+
+#### LoggingConfig
+
+
+
+LoggingConfig allows configuring logging behavior for OpenBao.
+
+
+
+_Appears in:_
+- [OpenBaoConfiguration](#openbaoconfiguration)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `format` _string_ | Format specifies the log format. |  | Enum: [standard json] <br />Optional: \{\} <br /> |
+| `file` _string_ | File is the path to the log file.<br />If not specified, logs are written to stderr. |  | Optional: \{\} <br /> |
+| `rotateDuration` _string_ | RotateDuration specifies how often to rotate logs (e.g., "24h", "7d"). |  | Optional: \{\} <br /> |
+| `rotateBytes` _integer_ | RotateBytes specifies the maximum size in bytes before rotating logs. |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `rotateMaxFiles` _integer_ | RotateMaxFiles is the maximum number of rotated log files to keep. |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `pidFile` _string_ | PIDFile is the path to write the PID file. |  | Optional: \{\} <br /> |
+
+
+#### MaintenanceConfig
+
+
+
+MaintenanceConfig defines supported maintenance operations.
+This is intended to provide a first-class workflow for day-2 operations in
+clusters that enforce managed-resource mutation locks via admission policy.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled enables maintenance mode for this cluster.<br />When true, the operator annotates managed resources (Pods/StatefulSet) with<br />`openbao.org/maintenance=true` to allow controlled restarts/deletes where<br />admission policies require an explicit maintenance signal. |  | Optional: \{\} <br /> |
+| `restartAt` _string_ | RestartAt triggers a rolling restart when changed.<br />The operator propagates this value as a Pod template annotation; any change<br />results in a new StatefulSet revision and a controlled restart.<br />Recommended value is an RFC3339 timestamp string.<br />Deprecated: use spec.runtime.restartAt instead. spec.runtime.restartAt<br />takes precedence when both fields are set. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+
+
+#### MetricsConfig
+
+
+
+MetricsConfig configures metrics collection.
+
+
+
+_Appears in:_
+- [ObservabilityConfig](#observabilityconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled configures the OpenBao telemetry stanza and creates a ServiceMonitor. | false |  |
+| `scrapeProfile` _string_ | ScrapeProfile selects which OpenBao pods are targeted by generated scrape resources.<br />Active targets only the active OpenBao pod. AllNodes targets every OpenBao pod and<br />requires a dedicated metrics-only listener. | Active | Enum: [Active AllNodes] <br />Optional: \{\} <br /> |
+| `metricsOnlyListener` _[MetricsOnlyListenerConfig](#metricsonlylistenerconfig)_ | MetricsOnlyListener configures a dedicated listener for metrics scraping.<br />It is enabled automatically when scrapeProfile is AllNodes. |  | Optional: \{\} <br /> |
+| `serviceMonitor` _[ServiceMonitorConfig](#servicemonitorconfig)_ | ServiceMonitor controls whether to create a Prometheus Operator ServiceMonitor. |  | Optional: \{\} <br /> |
+
+
+#### MetricsOnlyListenerConfig
+
+
+
+MetricsOnlyListenerConfig configures a dedicated metrics-only TCP listener.
+
+
+
+_Appears in:_
+- [MetricsConfig](#metricsconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether to render the dedicated metrics-only listener.<br />When omitted, the listener is enabled automatically for the AllNodes scrape profile. |  | Optional: \{\} <br /> |
+| `port` _integer_ | Port is the dedicated metrics listener port. | 8202 | Maximum: 65535 <br />Minimum: 1 <br />Optional: \{\} <br /> |
+| `unauthenticatedMetricsAccess` _boolean_ | UnauthenticatedMetricsAccess allows unauthenticated access to /v1/sys/metrics<br />on the metrics-only listener. AllNodes scraping needs this so standby nodes can<br />expose metrics. Restrict this listener with NetworkPolicy. |  | Optional: \{\} <br /> |
+
+
+#### NetworkConfig
+
+
+
+NetworkConfig configures network-related settings for the OpenBaoCluster.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiServerCIDR` _string_ | APIServerCIDR is an optional CIDR block for the Kubernetes API server.<br />When specified, this value is used instead of auto-detection for NetworkPolicy egress rules.<br />This is useful when you want an explicit allow-list (or when the in-cluster service VIP<br />injected into pods is unavailable/unusable in your environment).<br />Example: "10.43.0.0/16" for service network or "192.168.1.0/24" for control plane nodes. |  | Optional: \{\} <br /> |
+| `apiServerEndpointIPs` _string array_ | APIServerEndpointIPs is an optional list of Kubernetes API server endpoint IPs.<br />When set, the operator adds least-privilege NetworkPolicy egress rules for these IPs on port 6443.<br />This is required on some CNI implementations where egress enforcement happens on the post-NAT<br />destination (the API server endpoint) rather than the kubernetes Service IP (10.43.0.1:443).<br />The operator does not auto-detect these endpoint IPs because doing so reliably requires broader<br />cluster permissions (list/watch). Configure this field explicitly when needed.<br />Example (k3d): ["192.168.166.2"] |  | Optional: \{\} <br /> |
+| `dnsNamespace` _string_ | DNSNamespace specifies the namespace where the cluster DNS service resides.<br />Defaults to "kube-system" if not specified. | kube-system | Optional: \{\} <br /> |
+| `dnsEndpointIPs` _string array_ | DNSEndpointIPs is an optional list of DNS resolver endpoint IPs that should be<br />allow-listed directly in the operator-managed NetworkPolicy on TCP/UDP port 53.<br />Use this for clusters that resolve DNS through node-local or host-networked caches<br />instead of pod-backed DNS Services in a namespace. These IP-based rules are additive<br />to the namespace-based allow-list controlled by DNSNamespace.<br />The operator does not auto-detect these endpoint IPs because doing so reliably would<br />require environment-specific node or DNS discovery logic outside the current trust model.<br />Example: ["169.254.20.10"] |  | Optional: \{\} <br /> |
+| `egressRules` _[NetworkPolicyEgressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#networkpolicyegressrule-v1-networking) array_ | EgressRules allows users to specify additional egress rules that will be merged into<br />the operator-managed NetworkPolicy. This is useful for allowing access to external<br />services such as transit seal backends, object storage endpoints, or other dependencies.<br />The operator's default egress rules (DNS, API server, cluster pods) are always included<br />and cannot be overridden. User-provided rules are appended to the operator-managed rules.<br />Example: Allow egress to a transit seal backend in another namespace:<br />  egressRules:<br />  - to:<br />    - namespaceSelector:<br />        matchLabels:<br />          kubernetes.io/metadata.name: transit-namespace<br />    ports:<br />    - protocol: TCP<br />      port: 8200 |  | Optional: \{\} <br /> |
+| `ingressRules` _[NetworkPolicyIngressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#networkpolicyingressrule-v1-networking) array_ | IngressRules allows users to specify additional ingress rules that will be merged into<br />the operator-managed NetworkPolicy. This is useful for allowing access from external<br />services, monitoring tools, or other components that need to reach OpenBao pods.<br />The operator's default ingress rules (cluster pods, kube-system, operator, gateway)<br />are always included and cannot be overridden. User-provided rules are appended to<br />the operator-managed rules.<br />Example: Allow ingress from a monitoring namespace:<br />  ingressRules:<br />  - from:<br />    - namespaceSelector:<br />        matchLabels:<br />          kubernetes.io/metadata.name: monitoring<br />    ports:<br />    - protocol: TCP<br />      port: 8200 |  | Optional: \{\} <br /> |
+| `trustedIngressPeers` _[NetworkPolicyPeer](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#networkpolicypeer-v1-networking) array_ | TrustedIngressPeers allows users to declare ingress-controller or passthrough-proxy peers<br />that should be allowed to reach OpenBao on the API port without writing full raw<br />NetworkPolicy ingress rules.<br />This is useful for user-managed TCP passthrough or external ingress components that the<br />operator does not manage directly. The operator adds least-privilege ingress rules for<br />port 8200 using these peers.<br />Example: Allow a Traefik namespace to reach OpenBao on port 8200:<br />  trustedIngressPeers:<br />  - namespaceSelector:<br />      matchLabels:<br />        kubernetes.io/metadata.name: traefik<br />Example: Allow only specific ingress-controller pods in another namespace:<br />  trustedIngressPeers:<br />  - namespaceSelector:<br />      matchLabels:<br />        kubernetes.io/metadata.name: ingress-system<br />    podSelector:<br />      matchLabels:<br />        app.kubernetes.io/name: traefik |  | Optional: \{\} <br /> |
+
+
+#### OCIKMSSealConfig
+
+
+
+OCIKMSSealConfig configures the OCI KMS seal type.
+See: https://openbao.org/docs/configuration/seal/ocikms/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `keyID` _string_ | KeyID is the OCID of the master encryption key. |  | MinLength: 1 <br /> |
+| `cryptoEndpoint` _string_ | CryptoEndpoint is the OCI KMS crypto endpoint. |  | MinLength: 1 <br /> |
+| `managementEndpoint` _string_ | ManagementEndpoint is the OCI KMS management endpoint. |  | MinLength: 1 <br /> |
+| `authTypeAPIKey` _boolean_ | AuthTypeAPIKey enables OCI API key authentication through an OCI SDK config file.<br />When false or omitted, OpenBao uses the default OCI principal flow for the runtime<br />environment, such as instance principal. |  | Optional: \{\} <br /> |
+| `disabled` _boolean_ | Disabled disables this seal configuration, for example during seal migration. |  | Optional: \{\} <br /> |
+
+
+#### ObservabilityConfig
+
+
+
+ObservabilityConfig configures observability features.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metrics` _[MetricsConfig](#metricsconfig)_ | Metrics configures integration with Prometheus/OpenMetrics. |  | Optional: \{\} <br /> |
+
+
+#### OpenBaoCluster
+
+
+
+OpenBaoCluster is the Schema for the openbaoclusters API.
+
+
+
+
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `openbao.org/v1alpha1` | | |
+| `kind` _string_ | `OpenBaoCluster` | | |
+| `spec` _[OpenBaoClusterSpec](#openbaoclusterspec)_ | Spec defines the desired state of OpenBaoCluster. |  |  |
+| `status` _[OpenBaoClusterStatus](#openbaoclusterstatus)_ | Status defines the observed state of OpenBaoCluster. |  | Optional: \{\} <br /> |
+
+
+#### OpenBaoClusterSpec
+
+
+
+OpenBaoClusterSpec defines the desired state of an OpenBaoCluster.
+The Operator owns certain protected OpenBao configuration stanzas (for example,
+listener "tcp", storage "raft", and seal "static" when using default unseal).
+Users must not override these via spec.configuration.
+
+
+
+_Appears in:_
+- [OpenBaoCluster](#openbaocluster)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `version` _string_ | Version is the semantic OpenBao version, used for upgrade orchestration.<br />The Operator uses static auto-unseal, which requires OpenBao v2.4.0 or later.<br />Versions below 2.4.0 do not support the static seal feature and will fail to start. |  | MinLength: 1 <br /> |
+| `image` _string_ | Image is the container image to run; defaults may be derived from Version. |  | Optional: \{\} <br /> |
+| `serviceAccount` _[ServiceAccountConfig](#serviceaccountconfig)_ | ServiceAccount configures the Kubernetes ServiceAccount used by the OpenBao Pods. |  | Optional: \{\} <br /> |
+| `podMetadata` _[PodMetadataConfig](#podmetadataconfig)_ | PodMetadata configures additional labels and annotations for the OpenBao Pod template.<br />This is useful for platform integrations that select Pods via metadata, such as<br />Azure Workload Identity. Operator-managed Pod metadata takes precedence. |  | Optional: \{\} <br /> |
+| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array_ | ImagePullSecrets is a list of references to secrets in the same namespace<br />to use for pulling any images used by this Cluster (server, init, sidecars). |  | Optional: \{\} <br /> |
+| `observability` _[ObservabilityConfig](#observabilityconfig)_ | Observability configures telemetry and metrics integration. |  | Optional: \{\} <br /> |
+| `replicas` _integer_ | Replicas is the desired number of quorum-carrying voter Pods. | 3 | Minimum: 1 <br /> |
+| `readReplicas` _[ReadReplicaConfig](#readreplicaconfig)_ | ReadReplicas configures the steady-state non-voter read-replica pool. |  | Optional: \{\} <br /> |
+| `paused` _boolean_ | Paused, when true, pauses reconciliation for this OpenBaoCluster (except delete and finalizers). |  | Optional: \{\} <br /> |
+| `maintenance` _[MaintenanceConfig](#maintenanceconfig)_ | Maintenance configures supported maintenance workflows. |  | Optional: \{\} <br /> |
+| `runtime` _[RuntimeConfig](#runtimeconfig)_ | Runtime configures explicit runtime control requests for the OpenBao workload. |  | Optional: \{\} <br /> |
+| `breakGlassAck` _string_ | BreakGlassAck is an explicit acknowledgment token used to exit Break Glass / Safe Mode.<br />When the operator enters break glass mode, it writes a nonce to status.breakGlass.nonce.<br />To acknowledge and allow the operator to resume quorum-risk automation, set this field<br />to match that nonce.<br />Example:<br />  kubectl -n &lt;ns&gt; patch openbaocluster &lt;name&gt; --type merge -p '\{"spec":\{"breakGlassAck":"&lt;nonce&gt;"\}\}' |  | Optional: \{\} <br /> |
+| `tls` _[TLSConfig](#tlsconfig)_ | TLS configures TLS for the cluster. |  |  |
+| `storage` _[StorageConfig](#storageconfig)_ | Storage configures persistent storage for the cluster. |  |  |
+| `service` _[ServiceConfig](#serviceconfig)_ | Service configures the primary Service used to expose OpenBao inside or outside the cluster. |  | Optional: \{\} <br /> |
+| `ingress` _[IngressConfig](#ingressconfig)_ | Ingress configures optional HTTP(S) ingress in front of the OpenBao Service. |  | Optional: \{\} <br /> |
+| `configuration` _[OpenBaoConfiguration](#openbaoconfiguration)_ | Configuration defines the server configuration. |  | Optional: \{\} <br /> |
+| `backup` _[BackupSchedule](#backupschedule)_ | Backup configures scheduled backups for the cluster. |  | Optional: \{\} <br /> |
+| `restore` _[RestoreConfig](#restoreconfig)_ | Restore configures optional restore authentication bootstrap for the cluster. |  | Optional: \{\} <br /> |
+| `deletionPolicy` _[DeletionPolicy](#deletionpolicy)_ | DeletionPolicy controls what happens to underlying resources when the CR is deleted. |  | Enum: [Retain DeletePVCs DeleteAll] <br />Optional: \{\} <br /> |
+| `selfInit` _[SelfInitConfig](#selfinitconfig)_ | SelfInit configures OpenBao's native self-initialization feature.<br />When enabled, OpenBao initializes itself on first start using the configured<br />requests, and the root token is automatically revoked.<br />See: https://openbao.org/docs/configuration/self-init/ |  | Optional: \{\} <br /> |
+| `gateway` _[GatewayConfig](#gatewayconfig)_ | Gateway configures Kubernetes Gateway API access (alternative to Ingress).<br />When enabled, the Operator creates an HTTPRoute that routes traffic through<br />a user-managed Gateway resource. |  | Optional: \{\} <br /> |
+| `network` _[NetworkConfig](#networkconfig)_ | Network configures network-related settings for the cluster. |  | Optional: \{\} <br /> |
+| `initContainer` _[InitContainerConfig](#initcontainerconfig)_ | InitContainer configures the init container used to render OpenBao configuration.<br />The init container renders the final config.hcl from a template using environment<br />variables such as HOSTNAME and POD_IP. |  | Optional: \{\} <br /> |
+| `audit` _[AuditDevice](#auditdevice) array_ | Audit configures declarative audit devices for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/audit/ |  | Optional: \{\} <br /> |
+| `auditFileStorage` _[AuditFileStorageConfig](#auditfilestorageconfig)_ | AuditFileStorage configures a shared filesystem integration point for file audit devices.<br />When configured, file audit device paths must be under auditFileStorage.mountPath. |  | Optional: \{\} <br /> |
+| `plugins` _[Plugin](#plugin) array_ | Plugins configures declarative plugins for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/plugins/ |  | Optional: \{\} <br /> |
+| `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures telemetry reporting for the OpenBao cluster.<br />See: https://openbao.org/docs/configuration/telemetry/ |  | Optional: \{\} <br /> |
+| `upgrade` _[UpgradeConfig](#upgradeconfig)_ | Upgrade configures upgrade operations.<br />Built-in upgrade executor Jobs authenticate with JWT auth using the<br />upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount). If<br />spec.selfInit.oidc.enabled is true during initial SelfInit bootstrap and<br />spec.upgrade.jwtAuthRole is empty, the operator creates the default<br />"openbao-operator-upgrade" role. Already-initialized clusters must keep<br />that role or configure spec.upgrade.jwtAuthRole explicitly.<br />Pre-upgrade snapshots use spec.backup configuration and backup<br />authentication rather than spec.upgrade credentials. |  | Optional: \{\} <br /> |
+| `unseal` _[UnsealConfig](#unsealconfig)_ | Unseal defines the auto-unseal configuration.<br />If omitted, defaults to "static" mode managed by the operator. |  | Optional: \{\} <br /> |
+| `imageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | ImageVerification configures supply chain security checks. |  | Optional: \{\} <br /> |
+| `operatorImageVerification` _[ImageVerificationConfig](#imageverificationconfig)_ | OperatorImageVerification configures supply chain security checks for operator-managed helper images<br />(init container, backup/upgrade/restore executors). These images are typically signed<br />by the operator project (e.g., dc-tec/openbao-operator) rather than the OpenBao upstream project.<br />If omitted, helper image verification does not fall back to ImageVerification.<br />In Development, omitted means disabled. In Hardened, omitted means enabled. |  | Optional: \{\} <br /> |
+| `workloadHardening` _[WorkloadHardeningConfig](#workloadhardeningconfig)_ | WorkloadHardening configures opt-in workload hardening features. |  | Optional: \{\} <br /> |
+| `securityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#podsecuritycontext-v1-core)_ | SecurityContext allows specifying the PodSecurityContext for the OpenBao Pods.<br />If set, these values override the default security context generated by the operator.<br />This is useful for OpenShift (SCC) compatibility or custom security requirements. |  | Optional: \{\} <br /> |
+| `profile` _[Profile](#profile)_ | Profile defines the security posture for this cluster.<br />When set to "Hardened", the operator enforces strict security requirements:<br />- TLS must be External (cert-manager/CSI managed)<br />- Unseal must use external KMS (no static unseal)<br />- SelfInit must be enabled (no root token)<br />When set to "Development", relaxed security is allowed but a security warning<br />condition is set. |  | Enum: [Hardened Development] <br /> |
+
+
+#### OpenBaoClusterStatus
+
+
+
+DriftStatus tracks drift detection and correction events for a cluster.
+OpenBaoClusterStatus defines the observed state of an OpenBaoCluster.
+
+
+
+_Appears in:_
+- [OpenBaoCluster](#openbaocluster)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `observedGeneration` _integer_ | ObservedGeneration is the most recent metadata.generation that has been<br />reconciled into this status. |  | Optional: \{\} <br /> |
+| `phase` _[ClusterPhase](#clusterphase)_ | Phase is a high-level summary of the cluster state. |  | Enum: [Initializing Running Upgrading BackingUp Failed] <br />Optional: \{\} <br /> |
+| `activeLeader` _string_ | ActiveLeader is the current Raft leader pod name, for example "prod-cluster-0". |  | Optional: \{\} <br /> |
+| `readyReplicas` _integer_ | ReadyReplicas is the number of replicas that are currently Ready. |  | Optional: \{\} <br /> |
+| `readReplicas` _[ReadReplicaStatus](#readreplicastatus)_ | ReadReplicas captures observed state for the read-replica pool. |  | Optional: \{\} <br /> |
+| `currentVersion` _string_ | CurrentVersion is the OpenBao version currently running on the cluster. |  | Optional: \{\} <br /> |
+| `initialized` _boolean_ | Initialized indicates whether the OpenBao cluster has been initialized.<br />This is set to true after the first pod is initialized using bao operator init<br />or after self-initialization completes. |  | Optional: \{\} <br /> |
+| `selfInitialized` _boolean_ | SelfInitialized indicates whether the cluster was initialized using<br />OpenBao's self-initialization feature. When true, no root token Secret<br />exists for this cluster (the root token was auto-revoked). |  | Optional: \{\} <br /> |
+| `lastBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastBackupTime is the timestamp of the last successful backup, if configured.<br />Deprecated: Use Backup.LastBackupTime instead. |  | Optional: \{\} <br /> |
+| `upgrade` _[UpgradeProgress](#upgradeprogress)_ | Upgrade tracks the state of an in-progress upgrade (if any).<br />When non-nil, an upgrade is in progress and the UpgradeManager is orchestrating<br />the pod-by-pod rolling update with leader step-down. |  | Optional: \{\} <br /> |
+| `upgradeRequests` _[UpgradeRequestStatus](#upgraderequeststatus)_ | UpgradeRequests tracks which explicit upgrade request values have already<br />been handled so one-shot requests are edge-triggered instead of level-triggered. |  | Optional: \{\} <br /> |
+| `backup` _[BackupStatus](#backupstatus)_ | Backup tracks the state of backups for this cluster. |  | Optional: \{\} <br /> |
+| `blueGreen` _[BlueGreenStatus](#bluegreenstatus)_ | BlueGreen tracks the state of blue/green upgrades (if enabled). |  | Optional: \{\} <br /> |
+| `operationLock` _[OperationLockStatus](#operationlockstatus)_ | OperationLock prevents concurrent long-running operations (upgrade/backup/restore)<br />from acting on the same cluster at the same time. |  | Optional: \{\} <br /> |
+| `breakGlass` _[BreakGlassStatus](#breakglassstatus)_ | BreakGlass records when the operator has halted quorum-risk automation and requires<br />explicit operator acknowledgment to continue. |  | Optional: \{\} <br /> |
+| `workload` _[WorkloadControllerStatus](#workloadcontrollerstatus)_ | Workload holds signals owned by the workload controller (infrastructure reconciliation). |  | Optional: \{\} <br /> |
+| `adminOps` _[AdminOpsControllerStatus](#adminopscontrollerstatus)_ | AdminOps holds signals owned by the adminops controller (upgrade + backup). |  | Optional: \{\} <br /> |
+| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array_ | Conditions represent the current state of the OpenBaoCluster resource. |  | Optional: \{\} <br /> |
+
+
+#### OpenBaoConfiguration
+
+
+
+OpenBaoConfiguration defines the server configuration for OpenBao.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `ui` _boolean_ | UI enables the built-in web interface. | true | Optional: \{\} <br /> |
+| `logLevel` _string_ | LogLevel specifies the log level. | info | Enum: [trace debug info warn err] <br />Optional: \{\} <br /> |
+| `listener` _[ListenerConfig](#listenerconfig)_ | Listener allows tuning the TCP listener.<br />Note: Address and ClusterAddress are managed by the operator and cannot be changed. |  | Optional: \{\} <br /> |
+| `raft` _[RaftConfig](#raftconfig)_ | Raft allows tuning the Raft storage backend. |  | Optional: \{\} <br /> |
+| `acmeCARoot` _string_ | ACMECARoot is the path to the ACME CA root certificate file.<br />This is used when TLS mode is ACME to specify a custom CA root for ACME certificate validation. |  | Optional: \{\} <br /> |
+| `logging` _[LoggingConfig](#loggingconfig)_ | Logging allows configuring logging behavior. |  | Optional: \{\} <br /> |
+| `plugin` _[PluginConfig](#pluginconfig)_ | Plugin allows configuring plugin behavior.<br />Note: This is separate from spec.plugins which defines plugin instances. |  | Optional: \{\} <br /> |
+| `defaultLeaseTTL` _string_ | DefaultLeaseTTL is the default lease TTL for tokens and secrets (e.g., "720h", "30m").<br />If not specified, OpenBao uses its default. |  | Optional: \{\} <br /> |
+| `maxLeaseTTL` _string_ | MaxLeaseTTL is the maximum lease TTL for tokens and secrets (e.g., "8760h", "1y").<br />This must be greater than or equal to DefaultLeaseTTL.<br />If not specified, OpenBao uses its default. |  | Optional: \{\} <br /> |
+| `cacheSize` _integer_ | CacheSize is the size of the cache in bytes.<br />If not specified, OpenBao uses its default cache size. |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `disableCache` _boolean_ | DisableCache disables the cache entirely.<br />When true, all caching is disabled. |  | Optional: \{\} <br /> |
+| `detectDeadlocks` _boolean_ | DetectDeadlocks enables deadlock detection in OpenBao.<br />This is an experimental feature for debugging. |  | Optional: \{\} <br /> |
+| `rawStorageEndpoint` _boolean_ | RawStorageEndpoint enables the raw storage endpoint.<br />This is an experimental feature that exposes raw storage operations. |  | Optional: \{\} <br /> |
+| `introspectionEndpoint` _boolean_ | IntrospectionEndpoint enables the introspection endpoint.<br />This is an experimental feature for debugging and introspection. |  | Optional: \{\} <br /> |
+| `impreciseLeaseRoleTracking` _boolean_ | ImpreciseLeaseRoleTracking enables imprecise lease role tracking.<br />This is an experimental feature that may improve performance in some scenarios. |  | Optional: \{\} <br /> |
+| `unsafeAllowAPIAuditCreation` _boolean_ | UnsafeAllowAPIAuditCreation allows API-based audit device creation.<br />This bypasses the normal audit device configuration validation.<br />Use with caution. |  | Optional: \{\} <br /> |
+| `allowAuditLogPrefixing` _boolean_ | AllowAuditLogPrefixing allows audit log prefixing.<br />This enables custom prefixes in audit log entries. |  | Optional: \{\} <br /> |
+| `enableResponseHeaderHostname` _boolean_ | EnableResponseHeaderHostname enables the hostname in response headers.<br />When true, OpenBao includes the hostname in HTTP response headers. |  | Optional: \{\} <br /> |
+| `enableResponseHeaderRaftNodeID` _boolean_ | EnableResponseHeaderRaftNodeID enables the Raft node ID in response headers.<br />When true, OpenBao includes the Raft node ID in HTTP response headers. |  | Optional: \{\} <br /> |
+
+
+#### OperationLockStatus
+
+
+
+OperationLockStatus represents a status-based lock held by the operator.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `operation` _[ClusterOperation](#clusteroperation)_ | Operation is the operation currently holding the lock. |  | Enum: [Upgrade Backup Restore] <br />Optional: \{\} <br /> |
+| `holder` _string_ | Holder is a stable identifier for the lock holder (controller/component). |  | Optional: \{\} <br /> |
+| `message` _string_ | Message provides human-readable context for why the lock is held. |  | Optional: \{\} <br /> |
+| `acquiredAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | AcquiredAt is when the lock was first acquired. |  | Optional: \{\} <br /> |
+| `renewedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | RenewedAt is updated when the holder reasserts the lock during reconciliation. |  | Optional: \{\} <br /> |
+
+
+#### PKCS11RuntimeConfig
+
+
+
+PKCS11RuntimeConfig configures local runtime wiring needed by PKCS#11 vendor
+libraries. It is intentionally scoped to environment variables and library
+lookup paths so HSM integrations do not require custom wrapper scripts.
+
+
+
+_Appears in:_
+- [PKCS11SealConfig](#pkcs11sealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `libraryPath` _string_ | LibraryPath sets LD_LIBRARY_PATH for the OpenBao process. Use this when<br />the configured PKCS#11 module depends on sibling vendor libraries that<br />are not in the image's default dynamic linker search path. |  | Optional: \{\} <br /> |
+| `env` _[PKCS11RuntimeEnvVar](#pkcs11runtimeenvvar) array_ | Env exposes literal environment variables from keys in<br />spec.unseal.credentialsSecretRef. Use this for vendor runtime settings<br />such as HSM endpoints or authentication key references. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
+| `fileEnv` _[PKCS11RuntimeFileEnvVar](#pkcs11runtimefileenvvar) array_ | FileEnv exposes environment variables whose values are paths to files<br />mounted from keys in spec.unseal.credentialsSecretRef. Use this for vendor<br />settings that expect a config file path, for example SOFTHSM2_CONF or<br />vendor-specific PKCS#11 client configuration variables. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
+
+
+#### PKCS11RuntimeEnvVar
+
+
+
+PKCS11RuntimeEnvVar maps a PKCS#11 runtime environment variable to a key in
+spec.unseal.credentialsSecretRef.
+
+
+
+_Appears in:_
+- [PKCS11RuntimeConfig](#pkcs11runtimeconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name is the environment variable name to expose to the OpenBao process.<br />Names owned by OpenBao's PKCS#11 seal configuration, such as BAO_HSM_PIN,<br />are managed by the operator and must not be configured here. |  | Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br /> |
+| `secretKey` _string_ | SecretKey is the key in spec.unseal.credentialsSecretRef to source as the<br />environment variable value. |  | MinLength: 1 <br />Pattern: `^[-._A-Za-z0-9]+$` <br /> |
+
+
+#### PKCS11RuntimeFileEnvVar
+
+
+
+PKCS11RuntimeFileEnvVar maps a PKCS#11 runtime environment variable to the
+mounted file path for a key in spec.unseal.credentialsSecretRef.
+
+
+
+_Appears in:_
+- [PKCS11RuntimeConfig](#pkcs11runtimeconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name is the environment variable name to expose to the OpenBao process. |  | Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br /> |
+| `secretKey` _string_ | SecretKey is the key in spec.unseal.credentialsSecretRef whose mounted<br />file path should become the environment variable value. |  | MinLength: 1 <br />Pattern: `^[-._A-Za-z0-9]+$` <br /> |
+
+
+#### PKCS11SealConfig
+
+
+
+PKCS11SealConfig configures the PKCS#11 seal type.
+See: https://openbao.org/docs/configuration/seal/pkcs11/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `lib` _string_ | Lib is the path to the PKCS#11 library provided by the HSM vendor. |  | MinLength: 1 <br /> |
+| `slot` _string_ | Slot is the slot number where the HSM token is located. |  | Optional: \{\} <br /> |
+| `tokenLabel` _string_ | TokenLabel is the token label of the HSM slot to use instead of Slot. |  | Optional: \{\} <br /> |
+| `pin` _string_ | PIN is the PIN for accessing the HSM token.<br />Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly. |  | Optional: \{\} <br /> |
+| `keyLabel` _string_ | KeyLabel is the label for the encryption key used by OpenBao. |  | MinLength: 1 <br /> |
+| `keyID` _string_ | KeyID is the PKCS#11 key identifier to use instead of KeyLabel. |  | Optional: \{\} <br /> |
+| `mechanism` _string_ | Mechanism overrides the PKCS#11 wrapping or encryption mechanism. |  | Optional: \{\} <br /> |
+| `disableSoftwareEncryption` _boolean_ | DisableSoftwareEncryption disables the software encryption fallback. |  | Optional: \{\} <br /> |
+| `disabled` _boolean_ | Disabled disables this seal configuration, for example during seal migration. |  | Optional: \{\} <br /> |
+| `rsaOAEPHash` _string_ | RSAOAEPHash specifies the hash algorithm to use for RSA with OAEP padding.<br />Valid values: sha1, sha224, sha256, sha384, sha512. |  | Enum: [sha1 sha224 sha256 sha384 sha512] <br />Optional: \{\} <br /> |
+| `runtime` _[PKCS11RuntimeConfig](#pkcs11runtimeconfig)_ | Runtime configures local PKCS#11 vendor runtime wiring such as library<br />lookup paths and environment variables sourced from credentialsSecretRef. |  | Optional: \{\} <br /> |
+
+
+#### Plugin
+
+
+
+Plugin defines a declarative plugin configuration.
+See: https://openbao.org/docs/configuration/plugins/
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the plugin type (e.g., "secret", "auth"). |  | MinLength: 1 <br /> |
+| `name` _string_ | Name is the name of the plugin. |  | MinLength: 1 <br /> |
+| `image` _string_ | Image is the OCI image URL including registry and repository.<br />Required if Command is not set. Conflicts with Command. |  | Optional: \{\} <br /> |
+| `command` _string_ | Command is the command name of a manually downloaded plugin.<br />Required if Image is not set. Conflicts with Image. |  | Optional: \{\} <br /> |
+| `version` _string_ | Version is the image version or tag. |  | MinLength: 1 <br /> |
+| `binaryName` _string_ | BinaryName is the name of the plugin binary file within the OCI image. |  | MinLength: 1 <br /> |
+| `sha256sum` _string_ | SHA256Sum is the expected SHA256 checksum of the plugin binary.<br />Must be a 64-character hexadecimal string. |  | MaxLength: 64 <br />MinLength: 64 <br />Pattern: `^[0-9a-fA-F]\{64\}$` <br /> |
+| `args` _string array_ | Args are arguments to pass to the running plugin.<br />Only used if plugin_auto_register=true is set. |  | Optional: \{\} <br /> |
+| `env` _string array_ | Env are environment variables to pass to the running plugin.<br />Only used if plugin_auto_register=true is set. |  | Optional: \{\} <br /> |
+
+
+#### PluginConfig
+
+
+
+PluginConfig allows configuring plugin behavior.
+
+
+
+_Appears in:_
+- [OpenBaoConfiguration](#openbaoconfiguration)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `fileUID` _integer_ | FileUID is the UID to use for plugin files. |  | Optional: \{\} <br /> |
+| `filePermissions` _string_ | FilePermissions are the file permissions for plugin files (e.g., "0755"). |  | Optional: \{\} <br /> |
+| `autoDownload` _boolean_ | AutoDownload controls automatic plugin downloads from OCI registries. |  | Optional: \{\} <br /> |
+| `autoRegister` _boolean_ | AutoRegister controls automatic plugin registration. |  | Optional: \{\} <br /> |
+| `downloadBehavior` _string_ | DownloadBehavior controls whether OpenBao startup fails or continues when<br />declarative OCI plugin downloads fail. Valid values are "fail" and<br />"continue"; OpenBao defaults to "fail" when unset. |  | Enum: [fail continue] <br />Optional: \{\} <br /> |
+
+
+#### PodMetadataConfig
+
+
+
+PodMetadataConfig configures additional metadata for the OpenBao Pod template.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+- [ReadReplicaTemplateConfig](#readreplicatemplateconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `labels` _object (keys:string, values:string)_ | Labels are merged into the generated OpenBao Pod template labels.<br />Operator-managed labels take precedence if the same key is specified here. |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations are merged into the generated OpenBao Pod template annotations.<br />Operator-managed annotations take precedence if the same key is specified here. |  | Optional: \{\} <br /> |
+
+
+#### Profile
+
+_Underlying type:_ _string_
+
+Profile defines the security posture for an OpenBaoCluster.
+
+_Validation:_
+- Enum: [Hardened Development]
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description |
+| --- | --- |
+| `Hardened` | ProfileHardened enforces strict security requirements (production-ready).<br /> |
+| `Development` | ProfileDevelopment allows relaxed security for development/testing.<br /> |
+
+
+#### RaftAutopilotConfig
+
+
+
+RaftAutopilotConfig configures Raft Autopilot behavior for dead server cleanup.
+See: https://openbao.org/docs/concepts/integrated-storage/autopilot/
+
+
+
+_Appears in:_
+- [RaftConfig](#raftconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `cleanupDeadServers` _boolean_ | CleanupDeadServers enables automatic removal of dead Raft peers.<br />When enabled, Autopilot periodically removes servers that have been<br />unhealthy for longer than DeadServerLastContactThreshold.<br />Requires MinQuorum to be set (defaults to replicas/2 + 1). | true | Optional: \{\} <br /> |
+| `deadServerLastContactThreshold` _string_ | DeadServerLastContactThreshold is the duration after which a server<br />is considered dead if it hasn't contacted the leader.<br />Minimum: "1m". Default: "5m" (operator default, shorter than OpenBao's 24h). | 5m | Optional: \{\} <br /> |
+| `minQuorum` _integer_ | MinQuorum is the minimum number of servers before Autopilot can prune<br />dead servers. This prevents removing so many servers that quorum is lost.<br />If not specified, defaults to max(3, replicas/2 + 1). |  | Minimum: 3 <br />Optional: \{\} <br /> |
+| `serverStabilizationTime` _string_ | ServerStabilizationTime is the minimum time a server must be healthy<br />before being promoted to voter. Default: "10s". |  | Optional: \{\} <br /> |
+| `lastContactThreshold` _string_ | LastContactThreshold is the limit on the amount of time a server can<br />go without leader contact before being considered unhealthy.<br />Default: "10s". |  | Optional: \{\} <br /> |
+| `maxTrailingLogs` _integer_ | MaxTrailingLogs is the amount of entries in the Raft Log that a server<br />can be behind before being considered unhealthy. Default: 1000. |  | Optional: \{\} <br /> |
+
+
+#### RaftConfig
+
+
+
+RaftConfig allows tuning the Raft storage backend.
+
+
+
+_Appears in:_
+- [OpenBaoConfiguration](#openbaoconfiguration)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `performanceMultiplier` _integer_ | PerformanceMultiplier scales the Raft timing parameters. |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `autopilot` _[RaftAutopilotConfig](#raftautopilotconfig)_ | Autopilot configures Raft Autopilot settings.<br />By default, dead server cleanup is enabled with a 5-minute threshold. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaConfig
+
+
+
+ReadReplicaConfig defines the steady-state read-replica pool.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `replicas` _integer_ | Replicas is the desired number of permanent non-voters. |  | Minimum: 0 <br />Optional: \{\} <br /> |
+| `service` _[ReadReplicaServiceConfig](#readreplicaserviceconfig)_ | Service configures an optional dedicated Service for read traffic. |  | Optional: \{\} <br /> |
+| `template` _[ReadReplicaTemplateConfig](#readreplicatemplateconfig)_ | Template configures read-replica-specific Pod template overrides. |  | Optional: \{\} <br /> |
+| `storage` _[ReadReplicaStorageConfig](#readreplicastorageconfig)_ | Storage configures read-replica-specific storage overrides. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaSchedulingConfig
+
+
+
+ReadReplicaSchedulingConfig defines scheduling overrides for read replicas.
+
+
+
+_Appears in:_
+- [ReadReplicaTemplateConfig](#readreplicatemplateconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `nodeSelector` _object (keys:string, values:string)_ | NodeSelector defines node-selection constraints for read-replica Pods. |  | Optional: \{\} <br /> |
+| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#toleration-v1-core) array_ | Tolerations defines Pod tolerations for read-replica Pods. |  | Optional: \{\} <br /> |
+| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#affinity-v1-core)_ | Affinity defines Pod affinity / anti-affinity rules for read-replica Pods. |  | Optional: \{\} <br /> |
+| `topologySpreadConstraints` _[TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#topologyspreadconstraint-v1-core) array_ | TopologySpreadConstraints defines topology spread constraints for<br />read-replica Pods. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaServiceConfig
+
+
+
+ReadReplicaServiceConfig controls the optional read-only Service for the
+read-replica pool.
+
+
+
+_Appears in:_
+- [ReadReplicaConfig](#readreplicaconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether the operator creates a dedicated Service for the<br />read-replica pool. |  | Optional: \{\} <br /> |
+| `type` _[ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core)_ | Type is the Kubernetes Service type, for example "ClusterIP" or<br />"LoadBalancer". |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations to apply to the read Service. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaStatus
+
+
+
+ReadReplicaStatus captures observed state for the read-replica pool.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `desiredReplicas` _integer_ | DesiredReplicas is the desired number of read replicas. |  | Optional: \{\} <br /> |
+| `readyReplicas` _integer_ | ReadyReplicas is the number of Ready read-replica Pods observed. |  | Optional: \{\} <br /> |
+| `registeredReplicas` _integer_ | RegisteredReplicas is the number of observed non-voter peers registered in<br />Raft membership. |  | Optional: \{\} <br /> |
+| `healthyReplicas` _integer_ | HealthyReplicas is the number of read-replica peers that are currently<br />healthy according to the Raft Autopilot state endpoint. |  | Optional: \{\} <br /> |
+| `storage` _[ReadReplicaStorageStatus](#readreplicastoragestatus)_ | Storage captures read-replica-specific storage observation state. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaStorageConfig
+
+
+
+ReadReplicaStorageConfig defines storage overrides for the read-replica
+StatefulSet.
+
+
+
+_Appears in:_
+- [ReadReplicaConfig](#readreplicaconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `size` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#quantity-resource-api)_ | Size is the requested persistent volume size for read replicas. |  | Optional: \{\} <br /> |
+| `storageClassName` _string_ | StorageClassName is an optional StorageClass for read-replica PVCs. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaStorageStatus
+
+
+
+ReadReplicaStorageStatus captures observed storage state for the read-replica
+pool.
+
+
+
+_Appears in:_
+- [ReadReplicaStatus](#readreplicastatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `desiredPVCs` _integer_ | DesiredPVCs is the number of data PVCs expected for the read-replica pool. |  | Optional: \{\} <br /> |
+| `boundPVCs` _integer_ | BoundPVCs is the number of observed data PVCs for the read-replica pool. |  | Optional: \{\} <br /> |
+| `storageClassName` _string_ | StorageClassName is the effective StorageClass observed for the<br />read-replica PVCs when it is consistent. |  | Optional: \{\} <br /> |
+
+
+#### ReadReplicaTemplateConfig
+
+
+
+ReadReplicaTemplateConfig defines Pod-template overrides for read replicas.
+
+
+
+_Appears in:_
+- [ReadReplicaConfig](#readreplicaconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `metadata` _[PodMetadataConfig](#podmetadataconfig)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
+| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#resourcerequirements-v1-core)_ | Resources defines container resource requests and limits for read replicas. |  | Optional: \{\} <br /> |
+| `scheduling` _[ReadReplicaSchedulingConfig](#readreplicaschedulingconfig)_ | Scheduling defines node-placement and topology overrides for read replicas. |  | Optional: \{\} <br /> |
+
+
+#### RestoreConfig
+
+
+
+RestoreConfig defines optional configuration for restore operations.
+
+This is primarily used with self-init JWT bootstrap to pre-create a JWT role
+that can be referenced by OpenBaoRestore resources.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for restore operations. When set, and when spec.selfInit.oidc.enabled is true,<br />the operator bootstraps a restore policy and JWT role bound to the restore ServiceAccount<br />(&lt;cluster-name&gt;-restore-serviceaccount).<br />If OIDC is enabled in SelfInit and this field is empty, a default role<br />named "openbao-operator-restore" will be assumed/created.<br />The role must grant "update" capability on sys/storage/raft/snapshot-force. |  | Optional: \{\} <br /> |
+
+
+#### RuntimeConfig
+
+
+
+RuntimeConfig defines explicit runtime control requests for the OpenBao
+workload.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `restartAt` _string_ | RestartAt triggers a rolling restart when changed.<br />The operator propagates this value as a Pod template annotation; any change<br />results in a new StatefulSet revision and a controlled restart.<br />Recommended value is an RFC3339 timestamp string. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+
+
+#### SelfInitAuditDevice
+
+
+
+SelfInitAuditDevice provides structured configuration for enabling audit devices
+via self-init requests. This replaces the need for raw JSON in the Data field.
+See: https://openbao.org/api-docs/system/audit/
+
+
+
+_Appears in:_
+- [SelfInitRequest](#selfinitrequest)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the type of audit device (e.g., "file", "syslog", "socket", "http"). |  | Enum: [file syslog socket http] <br />MinLength: 1 <br /> |
+| `description` _string_ | Description is an optional description for the audit device. |  | Optional: \{\} <br /> |
+| `fileOptions` _[FileAuditOptions](#fileauditoptions)_ | FileOptions configures options for file audit devices.<br />Only used when Type is "file". |  | Optional: \{\} <br /> |
+| `httpOptions` _[HTTPAuditOptions](#httpauditoptions)_ | HTTPOptions configures options for HTTP audit devices.<br />Only used when Type is "http". |  | Optional: \{\} <br /> |
+| `syslogOptions` _[SyslogAuditOptions](#syslogauditoptions)_ | SyslogOptions configures options for syslog audit devices.<br />Only used when Type is "syslog". |  | Optional: \{\} <br /> |
+| `socketOptions` _[SocketAuditOptions](#socketauditoptions)_ | SocketOptions configures options for socket audit devices.<br />Only used when Type is "socket". |  | Optional: \{\} <br /> |
+
+
+#### SelfInitAuthMethod
+
+
+
+SelfInitAuthMethod provides structured configuration for enabling auth methods
+via self-init requests. This replaces the need for raw JSON in the Data field.
+See: https://openbao.org/api-docs/system/auth/
+
+
+
+_Appears in:_
+- [SelfInitRequest](#selfinitrequest)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the type of auth method (e.g., "jwt", "kubernetes", "userpass", "ldap"). |  | MinLength: 1 <br /> |
+| `description` _string_ | Description is an optional description for the auth method. |  | Optional: \{\} <br /> |
+| `config` _object (keys:string, values:string)_ | Config contains optional configuration for the auth method mount.<br />Common fields include: default_lease_ttl, max_lease_ttl, listing_visibility, etc. |  | Optional: \{\} <br /> |
+
+
+#### SelfInitConfig
+
+
+
+SelfInitConfig enables OpenBao's self-initialization feature.
+When enabled, OpenBao initializes itself on first start using the configured
+requests, and the root token is automatically revoked.
+See: https://openbao.org/docs/configuration/self-init/
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled activates OpenBao's self-initialization feature.<br />When true, the Operator injects initialize stanzas into config.hcl<br />and does NOT create a root token Secret (root token is auto-revoked).<br />WARNING: The root token is auto-revoked during initialization. You MUST<br />configure user authentication (e.g., userpass, JWT, Kubernetes auth) via<br />spec.selfInit.requests before enabling this. spec.selfInit.oidc.enabled<br />only provides Operator authentication for lifecycle tasks, NOT user access.<br />Enabling without user authentication results in permanent lockout. | false |  |
+| `oidc` _[SelfInitOIDCConfig](#selfinitoidcconfig)_ | OIDC configures JWT authentication for the Operator to perform cluster<br />lifecycle operations (backups, upgrades, restores). When enabled, this<br />sets up the jwt-operator auth method, OIDC discovery, and operator roles.<br />This is for Operator authentication only - users must configure their own<br />authentication methods via spec.selfInit.requests. |  | Optional: \{\} <br /> |
+| `requests` _[SelfInitRequest](#selfinitrequest) array_ | Requests defines the API operations to execute during self-initialization.<br />Each request becomes a named request block inside an initialize stanza. |  | Optional: \{\} <br /> |
+
+
+#### SelfInitOIDCConfig
+
+
+
+SelfInitOIDCConfig configures OIDC identity for the cluster.
+
+
+
+_Appears in:_
+- [SelfInitConfig](#selfinitconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled triggers the bootstrap logic. |  |  |
+| `audience` _string_ | Audience, if set, must match the operator installation audience used for<br />projected OpenBao auth tokens.<br />This field does not create a per-cluster TokenRequest audience override. |  | Optional: \{\} <br /> |
+| `issuer` _string_ | Issuer overrides the auto-discovered K8s issuer URL.<br />Critical for scenarios where OpenBao sees a different K8s URL than the Operator. |  | Optional: \{\} <br /> |
+
+
+#### SelfInitOperation
+
+_Underlying type:_ _string_
+
+SelfInitOperation defines valid operations for self-initialization requests.
+
+_Validation:_
+- Enum: [create read update delete list patch]
+
+_Appears in:_
+- [SelfInitRequest](#selfinitrequest)
+
+| Field | Description |
+| --- | --- |
+| `create` | SelfInitOperationCreate creates a new resource.<br /> |
+| `read` | SelfInitOperationRead reads an existing resource.<br /> |
+| `update` | SelfInitOperationUpdate updates an existing resource.<br /> |
+| `patch` | SelfInitOperationPatch performs a partial update to an existing resource.<br /> |
+| `delete` | SelfInitOperationDelete deletes an existing resource.<br /> |
+| `list` | SelfInitOperationList lists resources.<br /> |
+
+
+#### SelfInitPolicy
+
+
+
+SelfInitPolicy provides structured configuration for creating/updating policies
+via self-init requests. This replaces the need for raw JSON in the Data field.
+See: https://openbao.org/api-docs/system/policies-acl/
+
+
+
+_Appears in:_
+- [SelfInitRequest](#selfinitrequest)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `policy` _string_ | Policy is the HCL or JSON policy content.<br />This is the actual policy rules that will be applied. |  | MinLength: 1 <br /> |
+
+
+#### SelfInitRequest
+
+
+
+SelfInitRequest defines a single API operation to execute during self-initialization.
+
+
+
+_Appears in:_
+- [SelfInitConfig](#selfinitconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name is a unique identifier for this request (used as the block name).<br />Must match regex ^[A-Za-z_][A-Za-z0-9_-]*$ |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_-]*$` <br /> |
+| `operation` _[SelfInitOperation](#selfinitoperation)_ | Operation is the API operation type: create, read, update, delete, or list. |  | Enum: [create read update delete list patch] <br /> |
+| `path` _string_ | Path is the API path to call (e.g., "sys/audit/stdout", "auth/kubernetes/config"). |  | MinLength: 1 <br /> |
+| `auditDevice` _[SelfInitAuditDevice](#selfinitauditdevice)_ | AuditDevice configures an audit device when Path starts with "sys/audit/".<br />This provides structured configuration for audit devices instead of raw JSON.<br />Only used when Path matches the pattern "sys/audit/*". |  | Optional: \{\} <br /> |
+| `authMethod` _[SelfInitAuthMethod](#selfinitauthmethod)_ | AuthMethod configures an auth method when Path starts with "sys/auth/".<br />This provides structured configuration for enabling auth methods.<br />Only used when Path matches the pattern "sys/auth/*". |  | Optional: \{\} <br /> |
+| `secretEngine` _[SelfInitSecretEngine](#selfinitsecretengine)_ | SecretEngine configures a secret engine when Path starts with "sys/mounts/".<br />This provides structured configuration for enabling secret engines.<br />Only used when Path matches the pattern "sys/mounts/*". |  | Optional: \{\} <br /> |
+| `policy` _[SelfInitPolicy](#selfinitpolicy)_ | Policy configures a policy when Path starts with "sys/policies/".<br />This provides structured configuration for creating/updating policies.<br />Only used when Path matches the pattern "sys/policies/*". |  | Optional: \{\} <br /> |
+| `data` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#json-v1-apiextensions-k8s-io)_ | Data contains the request payload for paths that don't have structured types.<br />This must be a JSON/YAML object whose shape matches the target API endpoint.<br />Nested maps and lists are supported and are rendered into the initialize stanza as HCL objects.<br />**Note:** For common paths, use structured types instead:<br />- `sys/audit/*` → use `auditDevice`<br />- `sys/auth/*` → use `authMethod`<br />- `sys/mounts/*` → use `secretEngine`<br />- `sys/policies/*` → use `policy`<br />This payload is stored in the OpenBaoCluster resource and persisted in etcd;<br />it must not contain sensitive values such as tokens, passwords, or unseal keys. |  | Optional: \{\} <br /> |
+| `allowFailure` _boolean_ | AllowFailure allows this request to fail without blocking initialization.<br />Defaults to false. |  | Optional: \{\} <br /> |
+
+
+#### SelfInitSecretEngine
+
+
+
+SelfInitSecretEngine provides structured configuration for enabling secret engines
+via self-init requests. This replaces the need for raw JSON in the Data field.
+See: https://openbao.org/api-docs/system/mounts/
+
+
+
+_Appears in:_
+- [SelfInitRequest](#selfinitrequest)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the type of secret engine (e.g., "kv", "pki", "transit", "database"). |  | MinLength: 1 <br /> |
+| `description` _string_ | Description is an optional description for the secret engine. |  | Optional: \{\} <br /> |
+| `options` _object (keys:string, values:string)_ | Options contains optional configuration specific to the secret engine type.<br />For KV engines, common options include: version ("1" or "2").<br />For other engines, options vary by type. |  | Optional: \{\} <br /> |
+
+
+#### ServiceAccountConfig
+
+
+
+ServiceAccountConfig configures the ServiceAccount used by OpenBao pods.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name overrides the generated ServiceAccount name.<br />If not specified, defaults to "&lt;cluster-name&gt;-serviceaccount". |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations to add to the ServiceAccount.<br />Useful for cloud provider Workload Identity (e.g. eks.amazonaws.com/role-arn). |  | Optional: \{\} <br /> |
+
+
+#### ServiceConfig
+
+
+
+ServiceConfig controls how the main OpenBao Service is exposed.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _[ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core)_ | Type is the Kubernetes Service type, for example "ClusterIP" or "LoadBalancer". |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations to apply to the Service. |  | Optional: \{\} <br /> |
+
+
+#### ServiceMonitorAuthorizationConfig
+
+
+
+ServiceMonitorAuthorizationConfig configures Prometheus Operator endpoint authorization.
+
+
+
+_Appears in:_
+- [ServiceMonitorConfig](#servicemonitorconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type is the authorization type.<br />Defaults to Bearer when credentialsSecret is set. |  | Optional: \{\} <br /> |
+| `credentialsSecret` _[ServiceMonitorKeySelector](#servicemonitorkeyselector)_ | CredentialsSecret references a Secret key containing the authorization credentials.<br />The Secret must exist in the same namespace as the ServiceMonitor. |  |  |
+
+
+#### ServiceMonitorConfig
+
+
+
+ServiceMonitorConfig configures the Prometheus ServiceMonitor.
+
+
+
+_Appears in:_
+- [MetricsConfig](#metricsconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether to create the ServiceMonitor.<br />Defaults to true if Metrics are enabled. | true |  |
+| `interval` _string_ | Interval is the scrape interval. | 30s | Optional: \{\} <br /> |
+| `scrapeTimeout` _string_ | ScrapeTimeout is the scrape timeout. | 10s | Optional: \{\} <br /> |
+| `labels` _object (keys:string, values:string)_ | Labels are added to the ServiceMonitor metadata.<br />Use this for Prometheus selectors, such as release labels used by kube-prometheus-stack. |  | Optional: \{\} <br /> |
+| `annotations` _object (keys:string, values:string)_ | Annotations are added to the ServiceMonitor metadata. |  | Optional: \{\} <br /> |
+| `jobLabel` _string_ | JobLabel selects the Service label Prometheus uses as the job label.<br />Defaults to app.kubernetes.io/name. |  | Optional: \{\} <br /> |
+| `authorization` _[ServiceMonitorAuthorizationConfig](#servicemonitorauthorizationconfig)_ | Authorization configures an optional ServiceMonitor authorization block.<br />Use this for authenticated /v1/sys/metrics scraping. |  | Optional: \{\} <br /> |
+| `tlsConfig` _[ServiceMonitorTLSConfig](#servicemonitortlsconfig)_ | TLSConfig configures TLS verification for the OpenBao scrape endpoint. |  | Optional: \{\} <br /> |
+
+
+#### ServiceMonitorKeySelector
+
+
+
+ServiceMonitorKeySelector identifies a key in a Secret or ConfigMap.
+
+
+
+_Appears in:_
+- [ServiceMonitorAuthorizationConfig](#servicemonitorauthorizationconfig)
+- [ServiceMonitorTLSConfig](#servicemonitortlsconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `name` _string_ | Name is the Secret or ConfigMap name. |  | MinLength: 1 <br /> |
+| `key` _string_ | Key is the key within the Secret or ConfigMap.<br />Defaults to token for authorization credentials and ca.crt for CA references. |  | Optional: \{\} <br /> |
+
+
+#### ServiceMonitorTLSConfig
+
+
+
+ServiceMonitorTLSConfig configures TLS settings for the Prometheus Operator endpoint.
+
+
+
+_Appears in:_
+- [ServiceMonitorConfig](#servicemonitorconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `serverName` _string_ | ServerName verifies the hostname in the OpenBao serving certificate. |  | Optional: \{\} <br /> |
+| `insecureSkipVerify` _boolean_ | InsecureSkipVerify disables TLS certificate verification.<br />Use only for temporary non-production environments. |  | Optional: \{\} <br /> |
+| `caConfigMap` _[ServiceMonitorKeySelector](#servicemonitorkeyselector)_ | CAConfigMap references a ConfigMap key containing the CA certificate.<br />Mutually exclusive with CASecret. |  | Optional: \{\} <br /> |
+| `caSecret` _[ServiceMonitorKeySelector](#servicemonitorkeyselector)_ | CASecret references a Secret key containing the CA certificate.<br />Mutually exclusive with CAConfigMap. |  | Optional: \{\} <br /> |
+
+
+#### SocketAuditOptions
+
+
+
+SocketAuditOptions configures options for socket audit devices.
+See: https://openbao.org/docs/audit/socket/
+
+
+
+_Appears in:_
+- [AuditDevice](#auditdevice)
+- [SelfInitAuditDevice](#selfinitauditdevice)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `address` _string_ | Address is the socket server address to use.<br />Example: "127.0.0.1:9090" or "/tmp/audit.sock". |  | Optional: \{\} <br /> |
+| `socketType` _string_ | SocketType is the socket type to use, any type compatible with net.Dial is acceptable.<br />Defaults to "tcp" if not specified. |  | Optional: \{\} <br /> |
+| `writeTimeout` _string_ | WriteTimeout is the (deadline) time in seconds to allow writes to be completed over the socket.<br />A zero value means that write attempts will not time out.<br />Defaults to "2s" if not specified. |  | Optional: \{\} <br /> |
+
+
+#### StaticSealConfig
+
+
+
+StaticSealConfig configures the static seal type.
+This is the default seal type managed by the operator.
+See: https://openbao.org/docs/configuration/seal/static-key/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `currentKey` _string_ | CurrentKey is the path to the static unseal key file.<br />Defaults to "file:///etc/bao/unseal/key" (operator-managed). |  | Optional: \{\} <br /> |
+| `currentKeyID` _string_ | CurrentKeyID is the identifier for the current unseal key.<br />Defaults to "operator-generated-v1" (operator-managed). |  | Optional: \{\} <br /> |
+
+
+#### StorageConfig
+
+
+
+StorageConfig captures storage-related configuration for the StatefulSet.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `size` _string_ | Size is the requested persistent volume size, for example "10Gi". |  | MinLength: 1 <br /> |
+| `storageClassName` _string_ | StorageClassName is an optional StorageClass for the PVCs. |  | Optional: \{\} <br /> |
+
+
+#### SyslogAuditOptions
+
+
+
+SyslogAuditOptions configures options for syslog audit devices.
+See: https://openbao.org/docs/audit/syslog/
+
+
+
+_Appears in:_
+- [AuditDevice](#auditdevice)
+- [SelfInitAuditDevice](#selfinitauditdevice)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `facility` _string_ | Facility is the syslog facility to use.<br />Defaults to "AUTH" if not specified. |  | Optional: \{\} <br /> |
+| `tag` _string_ | Tag is the syslog tag to use.<br />Defaults to "openbao" if not specified. |  | Optional: \{\} <br /> |
+
+
+#### TLSConfig
+
+
+
+TLSConfig captures TLS configuration for an OpenBaoCluster.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `enabled` _boolean_ | Enabled controls whether TLS is enabled for the cluster. |  | Required: \{\} <br /> |
+| `mode` _[TLSMode](#tlsmode)_ | Mode controls who manages the certificate lifecycle. | OperatorManaged | Enum: [OperatorManaged External ACME] <br />Optional: \{\} <br /> |
+| `acme` _[ACMEConfig](#acmeconfig)_ | ACME configures settings when Mode is 'ACME'. |  | Optional: \{\} <br /> |
+| `rotationPeriod` _string_ | RotationPeriod is a duration string (for example, "720h") controlling certificate rotation.<br />Only used when Mode is OperatorManaged. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `extraSANs` _string array_ | ExtraSANs lists additional subject alternative names to include in server certificates.<br />Only used when Mode is OperatorManaged. |  | Optional: \{\} <br /> |
+
+
+#### TLSMode
+
+_Underlying type:_ _string_
+
+TLSMode controls who manages the certificate lifecycle.
+
+_Validation:_
+- Enum: [OperatorManaged External ACME]
+
+_Appears in:_
+- [TLSConfig](#tlsconfig)
+
+| Field | Description |
+| --- | --- |
+| `OperatorManaged` | TLSModeOperatorManaged: The operator acts as the CA, generating keys and rotating certs (Current Behavior).<br /> |
+| `External` | TLSModeExternal: The operator assumes Secrets are managed by an external entity (cert-manager, user, or CSI driver).<br />The operator will mount them but NOT modify/rotate them.<br /> |
+| `ACME` | TLSModeACME: OpenBao uses its native ACME client to fetch certificates.<br />No Secrets are mounted. No sidecar is injected. Best for Zero Trust.<br /> |
+
+
+#### TelemetryConfig
+
+
+
+TelemetryConfig defines telemetry reporting configuration.
+See: https://openbao.org/docs/configuration/telemetry/
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `usageGaugePeriod` _string_ | Common telemetry options<br />UsageGaugePeriod specifies the interval at which high-cardinality usage data is collected. |  | Optional: \{\} <br /> |
+| `maximumGaugeCardinality` _integer_ | MaximumGaugeCardinality is the maximum cardinality of gauge labels. |  | Optional: \{\} <br /> |
+| `disableHostname` _boolean_ | DisableHostname specifies if gauge values should be prefixed with the local hostname. |  | Optional: \{\} <br /> |
+| `enableHostnameLabel` _boolean_ | EnableHostnameLabel specifies if all metric values should contain the host label. |  | Optional: \{\} <br /> |
+| `metricsPrefix` _string_ | MetricsPrefix specifies the prefix used for metric values. |  | Optional: \{\} <br /> |
+| `leaseMetricsEpsilon` _string_ | LeaseMetricsEpsilon specifies the size of the bucket used to measure future lease expiration. |  | Optional: \{\} <br /> |
+| `prometheusRetentionTime` _string_ | Prometheus-specific options<br />PrometheusRetentionTime specifies how long to retain metrics in Prometheus format. |  | Optional: \{\} <br /> |
+| `statsiteAddress` _string_ | Statsite-specific options<br />StatsiteAddress is the address of the statsite server. |  | Optional: \{\} <br /> |
+| `statsdAddress` _string_ | StatsD-specific options<br />StatsdAddress is the address of the StatsD server. |  | Optional: \{\} <br /> |
+| `dogStatsdAddress` _string_ | DogStatsD-specific options<br />DogStatsdAddress is the address of the DogStatsD server. |  | Optional: \{\} <br /> |
+| `dogStatsdTags` _string array_ | DogStatsdTags are tags to add to all metrics. |  | Optional: \{\} <br /> |
+| `circonusAPIKey` _string_ | Circonus-specific options<br />CirconusAPIKey is the API key for Circonus. |  | Optional: \{\} <br /> |
+| `circonusAPIApp` _string_ | CirconusAPIApp is the API app name for Circonus. |  | Optional: \{\} <br /> |
+| `circonusAPIURL` _string_ | CirconusAPIURL is the API URL for Circonus. |  | Optional: \{\} <br /> |
+| `circonusSubmissionInterval` _string_ | CirconusSubmissionInterval is the submission interval for Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckID` _string_ | CirconusCheckID is the check ID for Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckForceMetricActivation` _string_ | CirconusCheckForceMetricActivation forces metric activation in Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckInstanceID` _string_ | CirconusCheckInstanceID is the instance ID for Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckSearchTag` _string_ | CirconusCheckSearchTag is the search tag for Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckDisplayName` _string_ | CirconusCheckDisplayName is the display name for Circonus. |  | Optional: \{\} <br /> |
+| `circonusCheckTags` _string_ | CirconusCheckTags is the tags for Circonus. |  | Optional: \{\} <br /> |
+| `circonusBrokerID` _string_ | CirconusBrokerID is the broker ID for Circonus. |  | Optional: \{\} <br /> |
+| `circonusBrokerSelectTag` _string_ | CirconusBrokerSelectTag is the broker select tag for Circonus. |  | Optional: \{\} <br /> |
+| `stackdriverProjectID` _string_ | Stackdriver-specific options<br />StackdriverProjectID is the Google Cloud Project ID. |  | Optional: \{\} <br /> |
+| `stackdriverLocation` _string_ | StackdriverLocation is the GCP or AWS region. |  | Optional: \{\} <br /> |
+| `stackdriverNamespace` _string_ | StackdriverNamespace is a namespace identifier for the telemetry data. |  | Optional: \{\} <br /> |
+| `stackdriverDebugLogs` _boolean_ | StackdriverDebugLogs specifies if OpenBao writes additional stackdriver debug logs. |  | Optional: \{\} <br /> |
+
+
+#### TransitSealConfig
+
+
+
+TransitSealConfig configures the Transit seal type.
+See: https://openbao.org/docs/configuration/seal/transit/
+
+
+
+_Appears in:_
+- [UnsealConfig](#unsealconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `address` _string_ | Address is the full HTTPS address to the OpenBao cluster providing the Transit seal. |  | MinLength: 1 <br /> |
+| `token` _string_ | Token is the OpenBao token to use for authentication.<br />Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly. |  | Optional: \{\} <br /> |
+| `keyName` _string_ | KeyName is the transit key to use for encryption and decryption. |  | MinLength: 1 <br /> |
+| `mountPath` _string_ | MountPath is the mount path to the transit secret engine. |  | MinLength: 1 <br /> |
+| `namespace` _string_ | Namespace is the namespace path to the transit secret engine. |  | Optional: \{\} <br /> |
+| `disableRenewal` _boolean_ | DisableRenewal disables automatic token renewal.<br />Set to true if token lifecycle is managed externally (e.g., by OpenBao Agent). |  | Optional: \{\} <br /> |
+| `tlsCACert` _string_ | TLSCACert is the path to the CA certificate file for TLS communication. |  | Optional: \{\} <br /> |
+| `tlsClientCert` _string_ | TLSClientCert is the path to the client certificate for TLS communication. |  | Optional: \{\} <br /> |
+| `tlsClientKey` _string_ | TLSClientKey is the path to the private key for TLS communication. |  | Optional: \{\} <br /> |
+| `tlsServerName` _string_ | TLSServerName is the SNI host name to use when connecting via TLS. |  | Optional: \{\} <br /> |
+| `tlsSkipVerify` _boolean_ | TLSSkipVerify disables verification of TLS certificates.<br />Using this option is highly discouraged and decreases security. |  | Optional: \{\} <br /> |
+
+
+#### UnsealConfig
+
+
+
+UnsealConfig defines the auto-unseal configuration for an OpenBaoCluster.
+If omitted, defaults to "static" mode managed by the operator.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `type` _string_ | Type specifies the seal type.<br />Defaults to "static". | static | Enum: [static awskms gcpckms azurekeyvault transit kmip ocikms pkcs11] <br /> |
+| `static` _[StaticSealConfig](#staticsealconfig)_ | Static configures the static seal type.<br />Optional when Type is "static" (operator provides defaults if omitted). |  | Optional: \{\} <br /> |
+| `transit` _[TransitSealConfig](#transitsealconfig)_ | Transit configures the Transit seal type.<br />Required when Type is "transit". |  | Optional: \{\} <br /> |
+| `awskms` _[AWSKMSSealConfig](#awskmssealconfig)_ | AWSKMS configures the AWS KMS seal type.<br />Required when Type is "awskms". |  | Optional: \{\} <br /> |
+| `azureKeyVault` _[AzureKeyVaultSealConfig](#azurekeyvaultsealconfig)_ | AzureKeyVault configures the Azure Key Vault seal type.<br />Required when Type is "azurekeyvault". |  | Optional: \{\} <br /> |
+| `gcpCloudKMS` _[GCPCloudKMSSealConfig](#gcpcloudkmssealconfig)_ | GCPCloudKMS configures the GCP Cloud KMS seal type.<br />Required when Type is "gcpckms". |  | Optional: \{\} <br /> |
+| `kmip` _[KMIPSealConfig](#kmipsealconfig)_ | KMIP configures the KMIP seal type.<br />Required when Type is "kmip". |  | Optional: \{\} <br /> |
+| `ocikms` _[OCIKMSSealConfig](#ocikmssealconfig)_ | OCIKMS configures the OCI KMS seal type.<br />Required when Type is "ocikms". |  | Optional: \{\} <br /> |
+| `pkcs11` _[PKCS11SealConfig](#pkcs11sealconfig)_ | PKCS11 configures the PKCS#11 seal type.<br />Required when Type is "pkcs11". |  | Optional: \{\} <br /> |
+| `credentialsSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | CredentialsSecretRef references a Secret containing provider credentials<br />(for example AWS access keys, GCP credentials.json, Azure client-secret keys,<br />or OCI SDK config for authTypeAPIKey mode).<br />If using Workload Identity (IRSA, GKE WI, Azure MSI), this can be omitted.<br />The Secret must exist in the same namespace as the OpenBaoCluster.<br />Cross-namespace references are not allowed for security reasons. |  | Optional: \{\} <br /> |
+
+
+#### UpdateStrategyType
+
+_Underlying type:_ _string_
+
+UpdateStrategyType defines the type of update strategy to use.
+
+_Validation:_
+- Enum: [RollingUpdate BlueGreen]
+
+_Appears in:_
+- [UpgradeConfig](#upgradeconfig)
+
+| Field | Description |
+| --- | --- |
+| `RollingUpdate` | UpdateStrategyRollingUpdate uses a rolling update strategy (default).<br /> |
+| `BlueGreen` | UpdateStrategyBlueGreen uses a blue/green deployment strategy.<br /> |
+
+
+#### UpgradeConfig
+
+
+
+UpgradeConfig defines configuration for upgrade operations.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `image` _string_ | Image is the container image to use for upgrade operations.<br />This image is used by Kubernetes Jobs created during upgrades (for example, blue/green<br />cluster orchestration actions). The executor runs inside the tenant namespace and<br />authenticates to OpenBao using a projected ServiceAccount token (JWT auth).<br />If not specified, defaults to "&lt;repo&gt;:X.Y.Z" where &lt;repo&gt; is derived from OPERATOR_UPGRADE_IMAGE_REPOSITORY<br />(default: "ghcr.io/dc-tec/openbao-upgrade") and the tag matches OPERATOR_VERSION. |  | Optional: \{\} <br /> |
+| `preUpgradeSnapshot` _boolean_ | PreUpgradeSnapshot, when true, triggers a backup before any upgrade.<br />When enabled, the upgrade manager will create a backup using the backup<br />configuration (spec.backup.target, spec.backup.image, etc.) and<br />wait for it to complete before proceeding with the upgrade.<br />If the backup fails, the upgrade will be blocked and a Degraded condition<br />will be set with Reason=PreUpgradeBackupFailed.<br />Requires spec.backup to be configured with target, image, and<br />authentication (jwtAuthRole or tokenSecretRef). |  | Optional: \{\} <br /> |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for upgrade executor Jobs. The executor authenticates with a projected<br />ServiceAccount token from &lt;cluster-name&gt;-upgrade-serviceaccount.<br />The role must be configured in OpenBao and must grant the permissions<br />required by the selected upgrade strategy, including:<br />- "read" capability on sys/health<br />- "sudo" and "update" capability on sys/step-down<br />- "read" capability on sys/storage/raft/autopilot/state<br />- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations<br />The role must bind to the upgrade ServiceAccount (&lt;cluster-name&gt;-upgrade-serviceaccount),<br />which is automatically created by the operator.<br />If OIDC is enabled during initial SelfInit bootstrap and this field is<br />empty, a default role named "openbao-operator-upgrade" will be created.<br />For already-initialized clusters, configure this role explicitly or keep<br />the default role created during initial bootstrap.<br />This is the supported authentication mechanism for built-in upgrade orchestration. |  | Optional: \{\} <br /> |
+| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token for future non-JWT upgrade authentication flows.<br />Built-in rolling and blue/green upgrade orchestration does not support<br />token-based authentication. Configure spec.upgrade.jwtAuthRole, or use the<br />default role created during initial spec.selfInit.oidc bootstrap. |  | Optional: \{\} <br /> |
+| `strategy` _[UpdateStrategyType](#updatestrategytype)_ | Strategy defines the update strategy to use. | RollingUpdate | Enum: [RollingUpdate BlueGreen] <br /> |
+| `requests` _[UpgradeRequestConfig](#upgraderequestconfig)_ | Requests defines explicit one-shot operator requests for the current<br />upgrade workflow. The operator acts only when a request value changes. |  | Optional: \{\} <br /> |
+| `blueGreen` _[BlueGreenConfig](#bluegreenconfig)_ | BlueGreen configures the behavior when Strategy is BlueGreen. |  | Optional: \{\} <br /> |
+
+
+#### UpgradeProgress
+
+
+
+UpgradeProgress tracks the state of an in-progress upgrade.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `targetVersion` _string_ | TargetVersion is the version being upgraded to. |  |  |
+| `fromVersion` _string_ | FromVersion is the version being upgraded from. |  |  |
+| `startedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | StartedAt is when the upgrade began. |  | Optional: \{\} <br /> |
+| `currentPartition` _integer_ | CurrentPartition is the current StatefulSet partition value. |  |  |
+| `completedPods` _integer array_ | CompletedPods lists ordinals of pods that have been successfully upgraded. |  | Optional: \{\} <br /> |
+| `lastStepDownTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastStepDownTime records when the last leader step-down was performed. |  | Optional: \{\} <br /> |
+| `failure` _[ControllerErrorStatus](#controllererrorstatus)_ | Failure is the structured rolling-upgrade failure status.<br />When Failure.Reason is non-empty, the upgrade is considered failed. |  | Optional: \{\} <br /> |
+| `lastErrorReason` _string_ | LastErrorReason is a low-cardinality reason describing why the upgrade failed (if it did).<br />Deprecated: use Failure.Reason.<br />When set, the status controller should consider the cluster Degraded. |  | Optional: \{\} <br /> |
+| `lastErrorMessage` _string_ | LastErrorMessage is a human-readable failure message (best-effort).<br />Deprecated: use Failure.Message. |  | Optional: \{\} <br /> |
+| `lastErrorAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | LastErrorAt is when the last upgrade error was recorded (best-effort).<br />Deprecated: use Failure.At. |  | Optional: \{\} <br /> |
+
+
+#### UpgradeRequestConfig
+
+
+
+UpgradeRequestConfig defines one-shot operator requests for upgrade workflows.
+
+
+
+_Appears in:_
+- [UpgradeConfig](#upgradeconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `retry` _string_ | Retry requests a retry of the current failed rolling upgrade when changed<br />to a new non-empty value.<br />The operator compares this value against status.upgradeRequests.lastHandledRetry<br />and acts only when the value changes. Recommended value is an RFC3339<br />timestamp string. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `promote` _string_ | Promote requests promotion of a held blue/green upgrade when changed to a<br />new non-empty value while spec.upgrade.blueGreen.autoPromote=false.<br />The operator compares this value against<br />status.upgradeRequests.lastHandledPromote and acts only when the value<br />changes. Recommended value is an RFC3339 timestamp string. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `rollback` _string_ | Rollback requests a manual abort or rollback of the current blue/green<br />upgrade when changed to a new non-empty value.<br />The operator compares this value against<br />status.upgradeRequests.lastHandledRollback and acts only when the value<br />changes. Recommended value is an RFC3339 timestamp string. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+
+
+#### UpgradeRequestStatus
+
+
+
+UpgradeRequestStatus tracks which explicit upgrade request values have already been handled.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `lastHandledRetry` _string_ | LastHandledRetry is the last observed spec.upgrade.requests.retry value<br />that the operator has handled. |  | Optional: \{\} <br /> |
+| `lastHandledPromote` _string_ | LastHandledPromote is the last observed spec.upgrade.requests.promote<br />value that the operator has handled. |  | Optional: \{\} <br /> |
+| `lastHandledRollback` _string_ | LastHandledRollback is the last observed spec.upgrade.requests.rollback<br />value that the operator has handled. |  | Optional: \{\} <br /> |
+
+
+#### ValidationHookConfig
+
+
+
+ValidationHookConfig defines a user-supplied validation Job.
+
+
+
+_Appears in:_
+- [VerificationConfig](#verificationconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `image` _string_ | Image is the container image for the validation job. |  | MinLength: 1 <br /> |
+| `command` _string array_ | Command is the command to run. |  | Optional: \{\} <br /> |
+| `args` _string array_ | Args are arguments passed to the command. |  | Optional: \{\} <br /> |
+| `timeoutSeconds` _integer_ | TimeoutSeconds is the job timeout (default: 300s). | 300 | Optional: \{\} <br /> |
+
+
+#### VerificationConfig
+
+
+
+VerificationConfig allows defining custom health checks before promotion.
+
+
+
+_Appears in:_
+- [BlueGreenConfig](#bluegreenconfig)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `minSyncDuration` _string_ | MinSyncDuration ensures the Green cluster stays healthy as a non-voter<br />for at least this duration before promotion (e.g., "5m"). |  | Optional: \{\} <br /> |
+| `prePromotionHook` _[ValidationHookConfig](#validationhookconfig)_ | PrePromotionHook specifies a Job template to run before promoting Green.<br />The job must complete successfully (exit 0) for promotion to proceed.<br />If the job fails, the operator either aborts or rolls back automatically<br />when blueGreen.autoRollback.onValidationFailure is enabled; otherwise it<br />holds for manual resolution. |  | Optional: \{\} <br /> |
+
+
+#### WorkloadControllerStatus
+
+
+
+WorkloadControllerStatus holds status owned by the workload controller.
+
+
+
+_Appears in:_
+- [OpenBaoClusterStatus](#openbaoclusterstatus)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `lastError` _[ControllerErrorStatus](#controllererrorstatus)_ | LastError is the last workload-controller error observed for this cluster. |  | Optional: \{\} <br /> |
+
+
+#### WorkloadHardeningConfig
+
+
+
+WorkloadHardeningConfig configures optional workload hardening features.
+
+
+
+_Appears in:_
+- [OpenBaoClusterSpec](#openbaoclusterspec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `appArmorEnabled` _boolean_ | AppArmorEnabled controls whether the operator sets AppArmor profiles on<br />generated Pods and Jobs. Some Kubernetes environments do not support AppArmor;<br />this is opt-in to avoid scheduling failures. |  | Optional: \{\} <br /> |
+
+
+#### WorkloadIdentityConfig
+
+
+
+WorkloadIdentityConfig configures cloud workload identity metadata for backup and restore workloads.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `serviceAccountAnnotations` _object (keys:string, values:string)_ | ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount.<br />This is typically used for provider-specific bindings such as GKE Workload Identity<br />or webhook-based AWS/Azure workload identity integrations. |  | Optional: \{\} <br /> |
+| `podLabels` _object (keys:string, values:string)_ | PodLabels are merged into the generated backup or restore Job pod template.<br />This is typically used for provider-specific selectors such as Azure Workload Identity.<br />Operator-managed labels take precedence if the same key is specified here. |  | Optional: \{\} <br /> |
+
+</TabItem>
+
+<TabItem value="openbaorestore" label="OpenBaoRestore">
+
+## Packages
+- [openbao.org/v1alpha1](#openbaoorgv1alpha1)
+
+
+## openbao.org/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.
+
+### Resource Types
+- [OpenBaoRestore](#openbaorestore)
+
+
+
+#### AzureTargetConfig
+
+
+
+AzureTargetConfig holds Azure Blob Storage specific configuration.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `storageAccount` _string_ | StorageAccount is the Azure storage account name.<br />Required when using Azure provider. |  | MinLength: 1 <br /> |
+| `container` _string_ | Container is the blob container name. If empty, uses the Bucket field value. |  | Optional: \{\} <br /> |
+
+
+#### BackupTarget
+
+
+
+BackupTarget describes a generic, cloud-agnostic object storage destination.
+
+
+
+_Appears in:_
+- [BackupSchedule](#backupschedule)
+- [RestoreSource](#restoresource)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `provider` _string_ | Provider selects the storage backend. Defaults to "s3" for backward compatibility. | s3 | Enum: [s3 gcs azure] <br />Optional: \{\} <br /> |
+| `endpoint` _string_ | Endpoint is the HTTP(S) endpoint for the object storage service.<br />For S3: Required (e.g., "https://s3.amazonaws.com" or MinIO endpoint).<br />For GCS: Optional (defaults to googleapis.com).<br />For Azure: Optional (derived from StorageAccount if not specified). |  | Optional: \{\} <br /> |
+| `bucket` _string_ | Bucket is the bucket or container name. |  | MinLength: 1 <br /> |
+| `pathPrefix` _string_ | PathPrefix is an optional prefix within the bucket for this cluster's snapshots. |  | Optional: \{\} <br /> |
+| `credentialsSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | CredentialsSecretRef optionally references a Secret containing credentials for the object store.<br />The Secret must exist in the same namespace as the owning OpenBao resource.<br />Cross-namespace references are not allowed for security reasons.<br />For S3: Expected keys are "accessKeyId" and "secretAccessKey" (optional: "sessionToken", "region", "caCert").<br />For GCS: Expected key is "credentials.json" containing a service account JSON key.<br />For Azure: Expected keys are "accountKey" or "connectionString".<br />Omit this field when relying on ambient workload identity or another default credential chain. |  | Optional: \{\} <br /> |
+| `workloadIdentity` _[WorkloadIdentityConfig](#workloadidentityconfig)_ | WorkloadIdentity optionally applies provider-specific metadata required by cloud workload identity integrations.<br />Use this for ambient identity setups such as EKS Pod Identity or IRSA, GKE Workload Identity, or Azure Workload Identity.<br />When omitted, backup and restore workloads can still use any credentials exposed through the pod's default provider chain. |  | Optional: \{\} <br /> |
+| `partSize` _integer_ | PartSize is the size of each part in multipart uploads (in bytes).<br />Defaults to 10MB (10485760 bytes). Larger values may improve performance for large snapshots<br />on fast networks, while smaller values may be better for slow or unreliable networks. | 10485760 | Minimum: 5.24288e+06 <br />Optional: \{\} <br /> |
+| `concurrency` _integer_ | Concurrency is the number of concurrent parts to upload during multipart uploads.<br />Defaults to 3. Higher values may improve throughput on fast networks but increase<br />memory usage and may overwhelm slower storage backends. | 3 | Maximum: 10 <br />Minimum: 1 <br />Optional: \{\} <br /> |
+| `region` _string_ | Region is the AWS region to use for S3-compatible clients.<br />For AWS, this should match the bucket region (for example, "eu-west-1").<br />For many S3-compatible stores (MinIO/Ceph), this can be any non-empty value.<br />Only used when Provider is "s3". | us-east-1 | Optional: \{\} <br /> |
+| `roleArn` _string_ | RoleARN is the IAM role ARN (or S3-compatible equivalent) to assume via Web Identity.<br />When set, backup and restore Jobs mount a projected ServiceAccount token and set the<br />AWS Web Identity environment variables explicitly.<br />Leave this empty when relying on ambient workload identity or provider-managed default credentials instead.<br />Only used when Provider is "s3". |  | Optional: \{\} <br /> |
+| `usePathStyle` _boolean_ | UsePathStyle controls whether to use path-style addressing (bucket.s3.amazonaws.com/object)<br />or virtual-hosted-style addressing (bucket.s3.amazonaws.com/object).<br />Set to true for MinIO and S3-compatible stores that require path-style.<br />Set to false for AWS S3 (default, as AWS is deprecating path-style).<br />Only used when Provider is "s3". | false | Optional: \{\} <br /> |
+| `gcs` _[GCSTargetConfig](#gcstargetconfig)_ | GCS contains Google Cloud Storage specific configuration.<br />Only used when Provider is "gcs". |  | Optional: \{\} <br /> |
+| `azure` _[AzureTargetConfig](#azuretargetconfig)_ | Azure contains Azure Blob Storage specific configuration.<br />Only used when Provider is "azure". |  | Optional: \{\} <br /> |
+| `insecureSkipVerify` _boolean_ | InsecureSkipVerify allows skipping TLS verification (useful for MinIO/LocalStack/Azurite with self-signed certs).<br />This applies to all providers that support TLS. |  | Optional: \{\} <br /> |
+
+
+#### GCSTargetConfig
+
+
+
+GCSTargetConfig holds Google Cloud Storage specific configuration.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `project` _string_ | Project is the GCP project ID. Optional if using ADC with default project or<br />if the credentials JSON includes the project. |  | Optional: \{\} <br /> |
+
+
+#### OpenBaoRestore
+
+
+
+OpenBaoRestore represents a request to restore an OpenBao cluster from a snapshot.
+This resource is immutable after creation - it acts as a "job request".
+
+
+
+
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `openbao.org/v1alpha1` | | |
+| `kind` _string_ | `OpenBaoRestore` | | |
+| `spec` _[OpenBaoRestoreSpec](#openbaorestorespec)_ |  |  |  |
+| `status` _[OpenBaoRestoreStatus](#openbaorestorestatus)_ |  |  |  |
+
+
+#### OpenBaoRestoreSpec
+
+
+
+OpenBaoRestoreSpec defines the desired state for a restore operation.
+An OpenBaoRestore acts as a "job request" - it is immutable after creation.
+
+
+
+_Appears in:_
+- [OpenBaoRestore](#openbaorestore)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `cluster` _string_ | Cluster is the name of the OpenBaoCluster to restore INTO.<br />Must exist in the same namespace as the OpenBaoRestore. |  | MinLength: 1 <br /> |
+| `source` _[RestoreSource](#restoresource)_ | Source defines where the snapshot comes from. |  |  |
+| `jwtAuthRole` _string_ | JWTAuthRole is the name of the JWT Auth role configured in OpenBao<br />for restore operations. When set, the restore executor will use JWT Auth<br />(projected ServiceAccount token) instead of a static token.<br />The role must be configured in OpenBao and must grant the "update" capability on<br />sys/storage/raft/snapshot-force. The role must bind to the restore ServiceAccount<br />(&lt;cluster-name&gt;-restore-serviceaccount) in the cluster namespace.<br />If this field is empty and the target OpenBaoCluster has OIDC enabled,<br />the operator will default to using the "openbao-operator-restore" role. |  | Optional: \{\} <br /> |
+| `tokenSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core)_ | TokenSecretRef optionally references a Secret containing an OpenBao API<br />token to use for restore operations (fallback method).<br />The Secret must exist in the same namespace as the OpenBaoRestore.<br />Cross-namespace references are not allowed for security reasons.<br />The token must have permission to update sys/storage/raft/snapshot-force.<br />If JWTAuthRole is set, this field is ignored in favor of JWT Auth. |  | Optional: \{\} <br /> |
+| `image` _string_ | Image is the container image to use for restore operations.<br />Defaults to the same image used for backup operations if not specified.<br />If the target OpenBaoCluster has image verification enabled, the operator will verify this image and pin the restore Job to the verified digest. |  | MinLength: 1 <br />Optional: \{\} <br /> |
+| `force` _boolean_ | Force allows restore even if the cluster appears unhealthy.<br />This is required for disaster recovery scenarios where the cluster<br />may be in a degraded state. | false | Optional: \{\} <br /> |
+| `overrideOperationLock` _boolean_ | OverrideOperationLock allows the restore controller to clear an active cluster<br />operation lock (upgrade/backup) and proceed with restore. This is a break-glass<br />escape hatch intended for disaster recovery.<br />For safety, this requires force: true. When used, the controller emits a Warning<br />event and records a Condition on the OpenBaoRestore. | false | Optional: \{\} <br /> |
+
+
+#### OpenBaoRestoreStatus
+
+
+
+OpenBaoRestoreStatus defines the observed state of OpenBaoRestore.
+
+
+
+_Appears in:_
+- [OpenBaoRestore](#openbaorestore)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `phase` _[RestorePhase](#restorephase)_ | Phase represents the current phase of the restore operation. | Pending | Enum: [Pending Validating Running Completed Failed] <br /> |
+| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | StartTime is when the restore operation started. |  | Optional: \{\} <br /> |
+| `completionTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | CompletionTime is when the restore operation completed (success or failure). |  | Optional: \{\} <br /> |
+| `snapshotKey` _string_ | SnapshotKey is the key of the snapshot that was restored. |  | Optional: \{\} <br /> |
+| `snapshotSize` _integer_ | SnapshotSize is the size of the restored snapshot in bytes. |  | Optional: \{\} <br /> |
+| `message` _string_ | Message provides additional details about the current phase. |  | Optional: \{\} <br /> |
+| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array_ | Conditions represent the latest available observations of the restore's state. |  | Optional: \{\} <br /> |
+
+
+#### RestorePhase
+
+_Underlying type:_ _string_
+
+RestorePhase represents the current phase of a restore operation.
+
+_Validation:_
+- Enum: [Pending Validating Running Completed Failed]
+
+_Appears in:_
+- [OpenBaoRestoreStatus](#openbaorestorestatus)
+
+| Field | Description |
+| --- | --- |
+| `Pending` | RestorePhasePending indicates the restore has been created but not yet started.<br /> |
+| `Validating` | RestorePhaseValidating indicates the controller is validating preconditions.<br /> |
+| `Running` | RestorePhaseRunning indicates the restore job is executing.<br /> |
+| `Completed` | RestorePhaseCompleted indicates the restore completed successfully.<br /> |
+| `Failed` | RestorePhaseFailed indicates the restore failed.<br /> |
+
+
+#### RestoreSource
+
+
+
+RestoreSource defines where the snapshot comes from.
+
+
+
+_Appears in:_
+- [OpenBaoRestoreSpec](#openbaorestorespec)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `target` _[BackupTarget](#backuptarget)_ | Target reuses BackupTarget for storage connection details.<br />This includes endpoint, bucket, region, credentials, etc. |  |  |
+| `key` _string_ | Key is the full path to the snapshot object in the bucket.<br />For example, "clusters/prod/2025-10-14-120000.snap". |  | MinLength: 1 <br /> |
+
+
+#### WorkloadIdentityConfig
+
+
+
+WorkloadIdentityConfig configures cloud workload identity metadata for backup and restore workloads.
+
+
+
+_Appears in:_
+- [BackupTarget](#backuptarget)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `serviceAccountAnnotations` _object (keys:string, values:string)_ | ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount.<br />This is typically used for provider-specific bindings such as GKE Workload Identity<br />or webhook-based AWS/Azure workload identity integrations. |  | Optional: \{\} <br /> |
+| `podLabels` _object (keys:string, values:string)_ | PodLabels are merged into the generated backup or restore Job pod template.<br />This is typically used for provider-specific selectors such as Azure Workload Identity.<br />Operator-managed labels take precedence if the same key is specified here. |  | Optional: \{\} <br /> |
+
+</TabItem>
+
+<TabItem value="openbaotenant" label="OpenBaoTenant">
+
+## Packages
+- [openbao.org/v1alpha1](#openbaoorgv1alpha1)
+
+
+## openbao.org/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.
+
+### Resource Types
+- [OpenBaoTenant](#openbaotenant)
+
+
+
+#### OpenBaoTenant
+
+
+
+OpenBaoTenant is the Schema for the openbaotenants API.
+OpenBaoTenant is a governance CRD that explicitly declares which namespace
+should be provisioned with tenant RBAC. This replaces the previous label-based
+approach (openbao.org/tenant=true) to improve security by eliminating the need
+for the Provisioner to have list/watch permissions on namespaces.
+
+
+
+
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `apiVersion` _string_ | `openbao.org/v1alpha1` | | |
+| `kind` _string_ | `OpenBaoTenant` | | |
+| `spec` _[OpenBaoTenantSpec](#openbaotenantspec)_ |  |  |  |
+| `status` _[OpenBaoTenantStatus](#openbaotenantstatus)_ |  |  |  |
+
+
+#### OpenBaoTenantSpec
+
+
+
+OpenBaoTenantSpec defines the desired state of OpenBaoTenant.
+
+
+
+_Appears in:_
+- [OpenBaoTenant](#openbaotenant)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `targetNamespace` _string_ | TargetNamespace is the name of the namespace to provision with tenant RBAC.<br />The Provisioner will create Role and RoleBinding resources in this namespace<br />to grant the OpenBaoCluster controller permission to manage OpenBaoCluster<br />resources in that namespace. |  | MinLength: 1 <br /> |
+| `quota` _[ResourceQuotaSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#resourcequotaspec-v1-core)_ | Quota defines the resource quota to apply to the tenant namespace. |  | Optional: \{\} <br /> |
+| `limitRange` _[LimitRangeSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#limitrangespec-v1-core)_ | LimitRange defines the limit range to apply to the tenant namespace. |  | Optional: \{\} <br /> |
+
+
+#### OpenBaoTenantStatus
+
+
+
+OpenBaoTenantStatus defines the observed state of OpenBaoTenant.
+
+
+
+_Appears in:_
+- [OpenBaoTenant](#openbaotenant)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `provisioned` _boolean_ | Provisioned indicates if the RBAC has been successfully applied to the target namespace. |  | Optional: \{\} <br /> |
+| `lastError` _string_ | LastError reports any issues finding the namespace or applying RBAC. |  | Optional: \{\} <br /> |
+| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array_ | Conditions represent the latest available observations of the tenant's state. |  | Optional: \{\} <br /> |
+
+</TabItem>
+
+</Tabs>
diff --git a/website/versioned_docs/version-0.3.0/reference/compatibility.md b/website/versioned_docs/version-0.3.0/reference/compatibility.md
new file mode 100644
index 000000000..b0df2e811
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/compatibility.md
@@ -0,0 +1,135 @@
+---
+title: Compatibility Matrix
+description: Compatibility matrix for OpenBao Operator covering CI validation scope, support posture, and production guidance.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Compatibility matrix"
+  lede="Validated versions, support posture, and production guidance for the current pre-GA line."
+/>
+
+<Callout type="note" title="Terminology">
+
+Use these terms consistently on this page:
+
+- **Validated**: explicitly exercised in CI.
+- **Best-effort supported**: eligible for issue triage and fixes on the latest stable release line only.
+- **Recommended for production**: stable releases using the documented `Hardened` profile, `selfInit`, admission enforcement, explicit version pinning, and staged upgrade validation.
+
+</Callout>
+
+## Pre-GA posture
+
+The current stable release line is intended for real deployments, but it remains pre-GA. The served CRD API is `openbao.org/v1alpha1`, and minor releases may introduce breaking changes. See [Deprecation Policy](deprecation-policy.md) and [Support Policy](support-policy.md) for the full release contract.
+
+<DecisionTable
+  kind="reference"
+  title="Kubernetes versions"
+  columns={['Version', 'Validated', 'Support posture', 'Production note']}
+  rows={[
+    {
+      cells: ['v1.35', 'PR gate, release gate, and nightly E2E', 'Best-effort supported on the latest stable line', 'Primary validated baseline'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['v1.34', 'Release gate, nightly E2E, and performance baseline', 'Best-effort supported on the latest stable line', 'Minimum validated version'],
+    },
+    {
+      cells: ['v1.36', 'Not validated for the current release line', 'Tracked as the next supported Kubernetes candidate', 'Adopt after controller-runtime, Kind, and release-gate coverage are available'],
+      emphasis: 'caution',
+    },
+    {
+      cells: ['v1.33', 'Not validated for the current release line', 'May work but is not release-gated for the current line', 'Validate in staging before carrying this version into the current pre-GA line'],
+      emphasis: 'caution',
+    },
+    {
+      cells: ['v1.32', 'Not validated', 'Out of support scope', 'Do not use for the current pre-GA line'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Platforms"
+  columns={['Platform', 'Validated', 'Support posture', 'Production note']}
+  rows={[
+    {
+      cells: ['Kubernetes', 'Default CI and nightly path', 'Best-effort supported on the latest stable line', 'Default recommended platform path'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['OpenShift', 'Helm rendering regression checks, manifest admission tests, and focused platform E2E', 'Best-effort supported on the latest stable line', 'Validate on your target cluster before production rollout'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="OpenBao versions"
+  columns={['Version', 'Validated', 'Support posture', 'Production note']}
+  rows={[
+    {
+      cells: ['2.5.x', 'PR gate, nightly E2E, and config compatibility checks', 'Best-effort supported on the latest stable line', 'Primary validated target'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['2.4.x', 'Nightly config compatibility checks', 'Best-effort supported on the latest stable line', 'Validate workload behavior and upgrade flow in staging before production rollout'],
+    },
+    {
+      cells: ['2.3.x', 'Not validated', 'Deprecated and out of support scope', 'Upgrade before production use'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="CI validation matrix"
+  caption="Versions and paths exercised by CI workflows."
+  columns={['Workflow', 'Scope', 'Versions tested']}
+  rows={[
+    {
+      cells: ['PR Gate', 'Logic, manifests, and primary compatibility path', 'K8s 1.35.1 + OpenBao 2.5.4'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Release Gate E2E', 'Stable release lifecycle coverage', 'K8s 1.34.3 and 1.35.1 + OpenBao 2.5.4'],
+    },
+    {
+      cells: ['Nightly E2E', 'Full lifecycle coverage', 'K8s 1.34.3 and 1.35.1 + OpenBao 2.5.4'],
+    },
+    {
+      cells: ['Nightly Config Compatibility', 'Render and config compatibility checks', 'OpenBao 2.4.4 and 2.5.4'],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Production upgrade rule">
+
+Always validate new Kubernetes or OpenBao versions in a staging environment before upgrading production, even when they are listed as validated and best-effort supported.
+
+</Callout>
+
+<NextActions
+  title="Related reference pages"
+  items={[
+    {
+      label: 'Upgrade compatibility',
+      description: 'Upgrade sequencing and rollback stance for operator upgrades.',
+      docId: 'reference/operator-upgrade-compatibility',
+    },
+    {
+      label: 'Support policy',
+      description: 'Release-line maintenance beyond raw validation coverage.',
+      docId: 'reference/support-policy',
+    },
+    {
+      label: 'Known limitations',
+      description: 'Current caveats and explicit non-goals for unsupported paths.',
+      docId: 'reference/known-limitations',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/deprecation-policy.md b/website/versioned_docs/version-0.3.0/reference/deprecation-policy.md
new file mode 100644
index 000000000..aead3b0db
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/deprecation-policy.md
@@ -0,0 +1,113 @@
+---
+title: Deprecation Policy
+description: Deprecation and API lifecycle policy for OpenBao Operator, including pre-1.0 compatibility expectations and migration requirements.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Deprecation and API lifecycle policy"
+  lede="How deprecations are announced, how removals happen, and what migration guidance must ship with a breaking or removing change."
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Pre-GA lifecycle rules"
+  columns={['Change type', 'Current contract', 'Contributor or maintainer expectation']}
+  rows={[
+    {
+      cells: [
+        'Minor releases (`0.Y.0`)',
+        'May include breaking API or behavior changes while the project remains pre-GA.',
+        'Document the break clearly and ship a migration path.',
+      ],
+      emphasis: 'caution',
+    },
+    {
+      cells: [
+        'Patch releases (`0.Y.Z`)',
+        'Should avoid intentional breaking changes.',
+        'Reserved for compatible changes or changes required for safety and integrity.',
+      ],
+    },
+    {
+      cells: [
+        'Security or data-integrity fixes',
+        'May force urgent behavior changes earlier than the normal removal timeline.',
+        'Call the exception out explicitly in release notes and migration guidance.',
+      ],
+    },
+  ]}
+/>
+
+## Scope
+
+This policy applies to:
+
+- CRD API versions (`openbao.org/*`)
+- CRD fields (`spec`, `status`)
+- user-visible defaults and behavior contracts
+- operator installation and upgrade workflows
+
+## Deprecation process
+
+When a field or behavior is deprecated, the project aims to do all of the following in the same release:
+
+1. Mark the deprecation in API comments, which feed the generated API docs.
+2. Document the deprecation in [API Reference](api.md) and release notes.
+3. Provide a migration path and a concrete replacement example.
+
+## Removal policy
+
+For pre-1.0 releases:
+
+- removals are expected in minor releases, not patch releases
+- deprecated fields should remain available for at least one minor release when feasible
+- urgent safety or security concerns may force earlier removal, but only with explicit release notes
+
+<DecisionTable
+  kind="reference"
+  title="Migration requirements for breaking changes"
+  columns={['Required output', 'Why it exists']}
+  rows={[
+    {
+      cells: ['A migration section in release notes or changelog', 'Operators need a single place to see what changed and in what order to act.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Clear before-and-after manifests', 'Schema changes are easier to adopt when the new target shape is concrete.'],
+    },
+    {
+      cells: ['Upgrade sequencing notes', 'Some changes are safe only when CRDs, operator version, and workload rollout happen in the right order.'],
+    },
+  ]}
+/>
+
+## Kubernetes versioning mechanics
+
+The project currently serves a single CRD API version, `v1alpha1`. When additional CRD versions are introduced, the project will use Kubernetes-native lifecycle controls such as:
+
+- `served` and `storage`
+- `deprecated: true`
+- `deprecationWarning`
+
+<NextActions
+  title="Related lifecycle references"
+  items={[
+    {
+      label: 'Compatibility matrix',
+      description: 'Platforms and versions that remain in scope.',
+      docId: 'reference/compatibility',
+    },
+    {
+      label: 'Upgrade compatibility',
+      description: 'Sequencing and rollback guidance for operator upgrades.',
+      docId: 'reference/operator-upgrade-compatibility',
+    },
+    {
+      label: 'Release management',
+      description: 'Maintainer workflow for shipping a release that contains the deprecation.',
+      to: '/contribute/release-management',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/index.mdx b/website/versioned_docs/version-0.3.0/reference/index.mdx
new file mode 100644
index 000000000..2f2d1a429
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/index.mdx
@@ -0,0 +1,75 @@
+---
+title: Reference
+slug: /reference
+hide_title: true
+pageType: landing
+journey: reference
+description: Generated API, compatibility, maintenance policy, upgrade compatibility, and status and event reference for OpenBao Operator.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Reference"
+  title="Reference documentation"
+  lede="Generated API fields, compatibility, upgrade constraints, support policy, and status and event semantics."
+  actions={[
+    {label: 'Open compatibility matrix', docId: 'reference/compatibility', variant: 'primary'},
+    {label: 'Open status and events', docId: 'reference/status-and-events', variant: 'secondary'},
+  ]}
+/>
+
+<RouteList
+  title="Quick checks"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Compatibility',
+      description: 'Supported Kubernetes and OpenBao combinations and the validation scope behind them.',
+      docId: 'reference/compatibility',
+    },
+    {
+      eyebrow: '02',
+      title: 'Status and events',
+      description: 'Condition types, reason values, and the fastest way to debug the operator lifecycle.',
+      docId: 'reference/status-and-events',
+    },
+    {
+      eyebrow: '03',
+      title: 'Upgrade compatibility',
+      description: 'Supported operator upgrade paths, CRD upgrade order, and the project rollback stance.',
+      docId: 'reference/operator-upgrade-compatibility',
+    },
+    {
+      eyebrow: '04',
+      title: 'API reference',
+      description: 'Generated CRD schema and field-level descriptions from `api/v1alpha1`.',
+      docId: 'reference/api',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Policies and caveats"
+  items={[
+    {
+      label: 'Release policy',
+      description: 'Public cadence, release channels, and stable release gates.',
+      docId: 'reference/release-policy',
+    },
+    {
+      label: 'Support policy',
+      description: 'Release lines in scope for best-effort maintenance.',
+      docId: 'reference/support-policy',
+    },
+    {
+      label: 'Deprecation policy',
+      description: 'Review how API and behavior changes are introduced across pre-GA release lines.',
+      docId: 'reference/deprecation-policy',
+    },
+    {
+      label: 'Known limitations',
+      description: 'Check current constraints, non-goals, and caveats before assuming a behavior is supported.',
+      docId: 'reference/known-limitations',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/known-limitations.md b/website/versioned_docs/version-0.3.0/reference/known-limitations.md
new file mode 100644
index 000000000..40c91e4f8
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/known-limitations.md
@@ -0,0 +1,74 @@
+---
+title: Known Limitations
+description: Known limitations and explicit non-goals for OpenBao Operator 0.x release lines.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Known limitations and non-goals"
+  lede="Current constraints and explicit non-goals for the pre-GA line."
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Current constraints"
+  columns={['Area', 'Current limitation', 'What to do instead']}
+  rows={[
+    {
+      cells: ['CRD versioning', 'The current served and storage API is `openbao.org/v1alpha1`; multi-version conversion webhooks are out of scope today.', 'Treat API evolution through the pre-GA contract and review release notes carefully.'],
+    },
+    {
+      cells: ['Cluster adoption', 'The operator assumes it manages clusters it created and reconciles; generic import of arbitrary unmanaged OpenBao clusters is out of scope.', 'Create operator-managed clusters directly, or use backup and restore workflows when you need to move data into a new operator-managed cluster.'],
+    },
+    {
+      cells: ['Operator downgrade', 'Routine downgrades are unsupported.', 'Use the recovery and restore guidance when a release cannot move forward safely.'],
+      emphasis: 'caution',
+    },
+    {
+      cells: ['External backup cleanup', '`DeleteAll` removes PVC-backed data but does not delete snapshot objects already written to external object storage.', 'Clean external backup objects explicitly as part of decommission procedures.'],
+    },
+    {
+      cells: ['etcd encryption verification', 'The operator cannot directly prove cluster-level etcd encryption at rest and surfaces a warning condition instead.', 'Validate cluster-level encryption controls outside the operator.'],
+    },
+    {
+      cells: ['Helm CRD lifecycle', 'Helm does not automatically upgrade or delete CRDs.', 'Use release `crds.yaml` assets for CRD lifecycle operations.'],
+    },
+    {
+      cells: ['Built-in upgrade authentication', 'Built-in rolling and blue/green upgrade orchestration do not support `spec.upgrade.tokenSecretRef`; upgrade Jobs use JWT authentication only.', 'Configure `spec.upgrade.jwtAuthRole`, or use the default role created during initial `selfInit.oidc` bootstrap.'],
+    },
+    {
+      cells: ['Audit file storage archival', '`spec.auditFileStorage` provides a PVC-backed collector handoff and replay buffer; it does not provide rotation, pruning, tamper-proof retention, or a collector.', 'Mount the audit PVC read-only into a collector and ship records to external retention-controlled storage.'],
+    },
+    {
+      cells: ['Upgrade strategy switching', 'Switching an existing cluster between `RollingUpdate` and `BlueGreen` is not a supported in-place transition today.', 'Choose the upgrade strategy before the next rollout and keep it stable for that cluster.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related caveat and recovery pages"
+  items={[
+    {
+      label: 'Support policy',
+      description: 'Maintenance contract and release lines that remain in scope.',
+      docId: 'reference/support-policy',
+    },
+    {
+      label: 'Upgrade compatibility',
+      description: 'Rollback stance and CRD sequencing for operator upgrades.',
+      docId: 'reference/operator-upgrade-compatibility',
+    },
+    {
+      label: 'Decommission a cluster',
+      description: 'Operational decommissioning workflow for external-backup caveats.',
+      docId: 'user-guide/openbaocluster/operations/deletion',
+    },
+    {
+      label: 'Restore from backup',
+      description: 'Recovery or migration workflow when an in-place change is not available.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/operator-upgrade-compatibility.md b/website/versioned_docs/version-0.3.0/reference/operator-upgrade-compatibility.md
new file mode 100644
index 000000000..1511f7fd5
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/operator-upgrade-compatibility.md
@@ -0,0 +1,94 @@
+---
+title: Upgrade Compatibility
+description: Operator upgrade compatibility policy, supported upgrade paths, rollback stance, and required CRD upgrade sequence.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Operator upgrade compatibility"
+  lede="Supported operator upgrade paths, required CRD sequencing, and the project stance on downgrade and rollback."
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Supported upgrade paths"
+  columns={['Path', 'Project stance', 'Operator guidance']}
+  rows={[
+    {
+      cells: ['Stable patch upgrades (`0.Y.Z -> 0.Y.(Z+1)`)', 'Supported', 'Use as the normal maintenance path.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Stable minor upgrades (`0.Y.Z -> 0.(Y+1).0`)', 'Supported with release note review', 'Upgrade sequentially across minors and validate in staging.'],
+    },
+    {
+      cells: ['Skipping multiple minors', 'Not recommended', 'Move sequentially so migrations and deprecations are not compressed into one jump.'],
+      emphasis: 'caution',
+    },
+    {
+      cells: ['Operator downgrades as routine rollback', 'Not supported', 'Plan downgrades only as recovery workflows with staging validation.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<Callout type="warning" title="CRD-first upgrade rule">
+
+Apply CRDs before upgrading the Helm release when the target release changed CRD content.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="CRD-first upgrade sequence"
+  code={`kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/crds.yaml
+helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
+  --namespace <operator-namespace>`}
+>
+  This matches the installation guidance and keeps the API surface aligned with the controller you are about to run.
+</CommandBlock>
+
+## Upgrade safety checklist
+
+Before upgrade:
+
+- confirm the target version in [Compatibility Matrix](compatibility.md)
+- take and verify backups for managed clusters
+- review release notes for deprecations and migrations
+
+After upgrade:
+
+- verify operator Deployments are `Running`
+- verify CRD version and controller readiness
+- verify managed cluster conditions and recent events
+
+## Rollback stance
+
+If an upgrade introduces issues:
+
+1. prefer a forward fix on a newer stable release
+2. if rollback is required, validate it as a recovery workflow in staging first
+3. use backup and restore runbooks for data-path recovery scenarios
+
+<NextActions
+  title="Related upgrade references"
+  items={[
+    {
+      label: 'Backup operations',
+      description: 'Open the backup workflow before upgrades when you still need to capture or verify the recovery point.',
+      to: '/docs/operate/backups',
+    },
+    {
+      label: 'Restore from backup',
+      description: 'Restore procedures for cases where rollback is no longer sufficient.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+    {
+      label: 'Status conditions and events',
+      description: 'Readiness and failure signals before and after an upgrade.',
+      docId: 'reference/status-and-events',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/release-policy.md b/website/versioned_docs/version-0.3.0/reference/release-policy.md
new file mode 100644
index 000000000..d37b6af28
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/release-policy.md
@@ -0,0 +1,149 @@
+---
+title: Release Policy
+description: Public release cadence and gating policy for OpenBao Operator, including edge, nightly, prerelease, stable, and patch release rules.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Release channels and cadence"
+  lede="Public cadence, release channels, and gating rules for OpenBao Operator."
+/>
+
+<Callout type="important" title="Best-effort cadence">
+
+The project aims for one stable release every 4 weeks. If the stable release gates are not green, the release window is skipped rather than forced.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Release channels"
+  columns={['Channel', 'Target cadence or trigger', 'What it is for', 'Public expectation']}
+  rows={[
+    {
+      cells: [
+        'Stable (`X.Y.Z`)',
+        'Target every 4 weeks when the stable release gates are green.',
+        'The supported production line.',
+        'Best-effort support on the latest stable line only.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Patch release',
+        'Out-of-band when there is a regression, security fix, or sharp-edge fix worth shipping sooner.',
+        'Fast correction without waiting for the monthly train.',
+        'Keep the scope tight and ship the next patch version directly.',
+      ],
+    },
+    {
+      cells: [
+        'Prerelease (`-rc.N`, `-beta.N`, `-alpha.N`)',
+        'Used for minor releases and for any release with meaningful runtime, security, or lifecycle changes.',
+        'Soak the next stable release before final cut.',
+        'Use for evaluation and staging, not as a supported production channel.',
+      ],
+    },
+    {
+      cells: [
+        'Nightly',
+        'Every successful nightly validation run.',
+        'Scheduled lifecycle validation and drift detection.',
+        'Not a production support channel.',
+      ],
+      emphasis: 'caution',
+    },
+    {
+      cells: [
+        'Edge (`main` snapshots)',
+        'Every green merge to `main`.',
+        'Continuous integration signal and early validation.',
+        'Not a production support channel.',
+      ],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+## Monthly release model
+
+<DecisionTable
+  kind="reference"
+  title="Default release rhythm"
+  columns={['Window', 'Maintainer focus', 'Expected output']}
+  rows={[
+    {
+      cells: [
+        'Weeks 1-3',
+        'Normal development on `main`.',
+        'Features, fixes, and continuous edge validation.',
+      ],
+    },
+    {
+      cells: [
+        'Week 4 hardening window',
+        'Avoid broad refactors. Focus on docs, regressions, generated artifacts, and upgrade, backup, and restore confidence.',
+        'Prepare the next stable release candidate or skip the window if the gates are not ready.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'RC soak',
+        'Use a release candidate for minor releases and for non-trivial runtime, security, or lifecycle changes.',
+        'Gather soak evidence before the stable cut.',
+      ],
+    },
+  ]}
+/>
+
+## Stable release gates
+
+A stable release should meet all of the following:
+
+- clean PR CI on the release branch or release PR
+- full E2E release evidence from the release PR or a maintainer-triggered CI run on the release branch
+- docs and compatibility matrix reviewed and current; new stable release lines have a committed `X.Y.0` docs snapshot
+- nightly validation reviewed for regressions; known flaky nightlies are tracked, but they do not block by themselves when release E2E evidence is clean
+- performance signal reviewed; block only on confirmed product regressions or an explicit maintainer decision while the harness is being calibrated
+- no known upgrade, backup, or restore regressions
+- no open release-blocker issues
+
+<Callout type="note" title="Release window skips">
+
+If a monthly release window is not ready, skip it and say so. Predictability matters more than pushing a release that has not met the public gates.
+
+</Callout>
+
+## Patch release policy
+
+- Do not wait for the monthly stable train when the fix materially improves safety, correctness, or operator usability.
+- Use the next patch version directly.
+- Keep patch releases narrowly scoped and avoid unrelated refactors.
+
+## Current pre-beta support stance
+
+Until the project reaches beta, the support window stays on the latest stable line only. Older stable lines may stop receiving fixes as soon as a newer stable release ships.
+
+<NextActions
+  title="Related release references"
+  items={[
+    {
+      label: 'Support policy',
+      description: 'Maintenance contract for releases after they ship.',
+      docId: 'reference/support-policy',
+    },
+    {
+      label: 'Compatibility matrix',
+      description: 'Kubernetes and OpenBao versions exercised by CI.',
+      docId: 'reference/compatibility',
+    },
+    {
+      label: 'Release management',
+      description: 'Maintainer workflow for executing a release.',
+      to: '/contribute/release-management',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/status-and-events.md b/website/versioned_docs/version-0.3.0/reference/status-and-events.md
new file mode 100644
index 000000000..8ebeb6304
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/status-and-events.md
@@ -0,0 +1,237 @@
+---
+title: Status Conditions and Events
+description: Reference for OpenBao Operator status conditions, Kubernetes Events, and audit events for OpenBaoCluster, OpenBaoRestore, and OpenBaoTenant resources.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Status conditions and event reference"
+  lede="Status conditions and emitted events across `OpenBaoCluster`, `OpenBaoRestore`, and `OpenBaoTenant`."
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect status conditions and namespace events"
+  code={`kubectl -n <ns> get openbaocluster <name> -o jsonpath='{.status.conditions}' | jq
+kubectl -n <ns> get openbaorestore <name> -o jsonpath='{.status.conditions}' | jq
+kubectl -n <ns> get openbaotenant <name> -o jsonpath='{.status.conditions}' | jq
+
+kubectl -n <ns> get events --sort-by=.lastTimestamp`}
+>
+  For the fastest timeline view, run `kubectl describe` on the parent custom resource to see status and recent events together.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Workflow checkpoints"
+  caption="Condition sets for quick checks of common workflows."
+  columns={['Workflow', 'Conditions to watch']}
+  rows={[
+    {
+      cells: ['Hardened with external TLS', '`Available`, `TLSReady`, `UserAccessBootstrap`, `ProductionReady`'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Hardened with ACME', '`Available`, `ACMEIntegrationReady`, `ACMECacheReady`, `UserAccessBootstrap`, `ProductionReady`'],
+    },
+    {
+      cells: ['Gateway exposure', '`GatewayIntegrationReady`'],
+    },
+    {
+      cells: ['Strict NetworkPolicy environments', '`APIServerNetworkReady`'],
+    },
+    {
+      cells: ['Scheduled backups', '`BackupConfigurationReady`'],
+    },
+    {
+      cells: ['File audit storage', '`AuditFileStorageReady`, then `Degraded` if StatefulSet recreation is required'],
+    },
+    {
+      cells: ['Restore execution', '`RestoreConfigurationReady`, then `RestoreComplete`'],
+    },
+  ]}
+/>
+
+## OpenBaoCluster conditions
+
+Condition types defined in `api/v1alpha1`:
+
+| Type | Meaning | Typical Reasons |
+| :--- | :--- | :--- |
+| `Available` | Workload availability from ready replicas | `AllReplicasReady`, `NoReplicasReady`, `NotReady`, `Paused` |
+| `APIServerNetworkReady` | Operator-known Kubernetes API egress contract for operator-managed NetworkPolicies | `APIServerNetworkReady`, `APIServerEndpointIPsRecommended`, `APIServerNetworkConfigurationInvalid`, `Paused` |
+| `TLSReady` | TLS asset readiness | `Ready`, `Disabled`, `TLSSecretMissing`, `TLSSecretInvalid`, `Unknown`, `Paused` |
+| `UserAccessBootstrap` | Best-effort check that `spec.selfInit.requests` appears to create a human login path in addition to operator bootstrap auth | `UserAccessConfigured`, `UserAccessUnverified`, `Disabled`, `Paused` |
+| `ACMEIntegrationReady` | Operator-known ACME prerequisites such as Gateway passthrough, private ACME trust, and supported self-reachability checks | `ACMEIntegrationReady`, `GatewayAPIMissing`, `ACMEGatewayNotConfiguredForPassthrough`, `ACMEDomainNotResolvable`, `PrerequisitesMissing`, `Unknown`, `Paused` |
+| `ACMECacheReady` | Shared ACME cache readiness for HA or blue/green ACME topologies | `ACMECacheReady`, `ACMECacheNotConfigured`, `ACMECacheMissing`, `ACMECachePending`, `ACMECacheInvalidAccessMode` |
+| `AuditFileStorageReady` | Shared file-audit PVC readiness and StatefulSet mount adoption | `AuditFileStorageReady`, `AuditFileStorageMissing`, `AuditFileStoragePending`, `AuditFileStorageInvalidAccessMode`, `AuditFileStorageStatefulSetRecreateRequired`, `Unknown` |
+| `GatewayIntegrationReady` | Operator-known Gateway API prerequisites and controller support for `spec.gateway` | `GatewayIntegrationReady`, `GatewayAPIMissing`, `GatewayReferenceMissing`, `GatewayClassMissing`, `GatewayClassPending`, `GatewayClassNotAccepted`, `GatewayVersionUnsupported`, `GatewayFeatureUnsupported`, `GatewayCapabilitiesUnknown`, `GatewayNotProgrammed`, `GatewayProgrammingPending`, `GatewayListenerIncompatible`, `Paused` |
+| `BackupConfigurationReady` | Operator-known backup Job prerequisites such as auth references, storage credential references, hardened-profile egress rules, and job-specific identity assumptions | `Ready`, `AuthenticationRequired`, `TokenSecretMissing`, `CredentialsSecretMissing`, `WorkloadIdentityConfigured`, `AmbientIdentityAssumed`, `NetworkEgressRulesRequired`, `Unknown`, `Paused` |
+| `CloudUnsealIdentityReady` | Operator-known authentication path for cloud KMS unseal on the main OpenBao Pods | `Ready`, `CredentialsSecretMissing`, `PrerequisitesMissing`, `WorkloadIdentityConfigured`, `AmbientIdentityAssumed`, `Unknown`, `Paused` |
+| `ProductionReady` | Indicates whether the cluster currently meets the operator's Hardened production posture checks. This condition does not represent API stability or project support level. | `ProductionReady`, `ProfileNotSet`, `DevelopmentProfile`, `AdmissionPoliciesNotReady`, `UnsafeAdmissionDisabled`, `OperatorManagedTLS`, `StaticUnsealInUse`, `RootTokenStored`, Gateway or ACME readiness reasons such as `GatewayFeatureUnsupported` or `ACMEGatewayNotConfiguredForPassthrough` |
+| `Upgrading` | Upgrade state | `InProgress`, `Idle`, or upgrade failure reason |
+| `BackingUp` | Backup job state | `InProgress`, `Idle` |
+| `StorageConfigured` | Persistent storage class selection visibility | `StorageClassConfigured`, `StorageClassPending`, `StorageClassDefaulted`, `StorageClassUnset`, `StorageClassMismatch`, `StorageClassInconsistent` |
+| `Degraded` | Problem requiring attention | `BreakGlassRequired`, upgrade failure reason, workload or adminops error reason, `OIDCBootstrapConfigurationInvalid`, `APIServerNetworkConfigurationInvalid`, `RootTokenStored`, `Reconciling`, `Paused` |
+| `EtcdEncryptionWarning` | etcd encryption verification warning | `EtcdEncryptionUnknown` |
+| `SecurityRisk` | Relaxed security mode indicator | `DevelopmentProfile`, `UnsafeAdmissionDisabled` |
+| `OpenBaoInitialized` | OpenBao initialization observed from registration labels | `Initialized`, `NotInitialized`, `Unknown` |
+| `OpenBaoSealed` | OpenBao seal state observed from registration labels | `Sealed`, `Unsealed`, `Unknown` |
+| `OpenBaoLeader` | Leader discovery from registration labels | `LeaderFound`, `LeaderUnknown`, `MultipleLeaders` |
+| `NodeSecurityCapabilityMismatch` | Node capability mismatch for enabled hardening | `Ready`, `AppArmorUnsupported` |
+
+## OpenBaoRestore conditions
+
+| Type | Meaning | Typical Reasons |
+| :--- | :--- | :--- |
+| `RestoreComplete` | Restore terminal state | `RestoreSucceeded`, `RestoreFailed`, `AuthenticationRequired` |
+| `RestoreConfigurationReady` | Operator-known restore prerequisites such as auth references, storage credential references, hardened-profile egress rules, and job-specific identity assumptions | `Ready`, `AuthenticationRequired`, `TokenSecretMissing`, `TokenSecretInvalid`, `CredentialsSecretMissing`, `WorkloadIdentityConfigured`, `AmbientIdentityAssumed`, `NetworkEgressRulesRequired` |
+| `OperationLockOverride` | Break-glass lock override occurred | `OperationLockOverridden` |
+
+<Callout type="note" title="Ambient identity reasons">
+
+`AmbientIdentityAssumed` means the operator classified the configuration as relying on a provider default chain or other ambient identity path. It does not prove that the cloud-side identity binding is correct.
+
+</Callout>
+
+## OpenBaoTenant conditions
+
+| Type | Meaning | Typical Reasons |
+| :--- | :--- | :--- |
+| `Provisioned` | Tenant RBAC provisioning state | `SecurityViolation` and provisioning outcomes |
+
+## Kubernetes events
+
+<Callout type="note" title="Event scope">
+
+The operator emits lifecycle events on parent custom resources only. `OpenBaoCluster` receives cluster lifecycle, init and bootstrap, upgrade, backup, and tenant Secret RBAC sync events. `OpenBaoRestore` receives restore lifecycle events. `OpenBaoTenant` receives tenant provisioning lifecycle events. Jobs do not receive the lifecycle events listed here.
+
+</Callout>
+
+<Callout type="tip" title="Event types">
+
+Expect `Normal` events for routine progression and accepted operator input. Expect `Warning` events for failures, contention, overrides, and other states that need attention.
+
+</Callout>
+
+### OpenBaoCluster safety and maintenance events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Warning` | `ProfileNotSet` | `spec.profile` missing; reconciliation blocked. |
+| `Warning` | `DevelopmentProfile` | Development profile warning for production. |
+| `Warning` | `UnsafeAdmissionDisabled` | Unsafe admission mode is active, required admission guardrails are not enforced, and Hardened clusters are not production-ready. |
+| `Normal` | `AmbientUnsealIdentity` | Cloud KMS unseal is relying on ambient identity or the provider default chain for the main OpenBao Pods. This note is emitted only when the operator is not using a credentials Secret or explicit inline cloud credentials. |
+| `Warning` | `StaticUnsealInUse` | Static unseal warning. |
+| `Warning` | `RootTokenStored` | Self-init is disabled and the operator stored the root token Secret. |
+| `Warning` | `ImageVerificationFailed` and related reasons | Warn-policy image verification failures. |
+| `Normal` | `PVCResize` | PVC expansion started. |
+| `Normal` | `PVCResizeLeaderStepDown` | Leader step-down for resize restart path. |
+| `Normal` | `PVCResizePodRestart` | Pod restart to complete filesystem resize. |
+
+### OpenBaoCluster init and bootstrap events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `InitStarted` | Self-init or operator-driven initialization started or is still in progress. |
+| `Normal` | `InitCompleted` | Cluster initialization completed successfully. |
+| `Warning` | `InitFailed` | Operator-driven initialization failed. |
+
+### OpenBaoCluster tenant Secret RBAC events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `TenantSecretRBACSynchronized` | Tenant Secret RBAC allowlists were synchronized for the namespace. |
+
+### OpenBaoCluster upgrade events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `UpgradeStarted` | Upgrade orchestration started. |
+| `Normal` | `PreUpgradeSnapshotJobCreated` | Pre-upgrade snapshot Job created. |
+| `Normal` | `PreUpgradeSnapshotCompleted` | Pre-upgrade snapshot completed successfully. |
+| `Warning` | `PreUpgradeSnapshotFailed` | Pre-upgrade snapshot failed and upgrade is blocked. |
+| `Normal` | `RollingRetryRequested` | Manual retry requested for a failed rolling upgrade. |
+| `Normal` | `RollingRetryAccepted` | Failed rolling upgrade state cleared and retry resumed. |
+| `Normal` | `BlueGreenHoldEntered` | Blue or green upgrade is waiting for manual promotion approval. |
+| `Normal` | `BlueGreenPromotionApproved` | Promotion approval observed and promotion started. |
+| `Normal` | `UpgradeComplete` | Upgrade finished successfully. |
+| `Warning` | `UpgradeFailed` | Upgrade failed and operator marked the upgrade as failed. |
+| `Warning` | `RollbackStarted` | Blue or green rollback started. |
+| `Warning` | `BreakGlassEntered` | Blue or green rollback entered break-glass mode. |
+| `Normal` | `BreakGlassAcknowledged` | Break-glass mode was acknowledged and automation may resume. |
+| `Warning` | `OperationLockBlocked` | Upgrade is waiting for another cluster operation to release the lock. |
+
+### OpenBaoCluster backup events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `BackupManualTriggerAccepted` | Manual backup trigger accepted. |
+| `Normal` | `BackupSkipped` | Due or manually requested backup intentionally skipped. |
+| `Normal` | `BackupStarted` | Backup attempt started after lock acquisition. |
+| `Normal` | `BackupIdentityConfiguration` | Backup identity mode and generated ServiceAccount attachment point. |
+| `Normal` | `BackupJobCreated` | Backup Job created. |
+| `Normal` | `BackupCompleted` | Backup completed successfully. |
+| `Warning` | `BackupFailed` | Backup Job failed. |
+| `Warning` | `OperationLockBlocked` | Backup is waiting for another cluster operation to release the lock. |
+
+### OpenBaoRestore events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `RestoreValidationStarted` | Restore validation started. |
+| `Normal` | `RestoreStarted` | Restore execution started after validation. |
+| `Normal` | `RestoreIdentityConfiguration` | Restore identity mode and generated ServiceAccount attachment point. |
+| `Normal` | `RestoreJobCreated` | Restore Job created. |
+| `Normal` | `RestoreCompleted` | Restore completed successfully. |
+| `Warning` | `RestoreFailed` | Restore failed. |
+| `Warning` | `OperationLockBlocked` | Restore is waiting for another cluster operation to release the lock. |
+| `Warning` | `OperationLockLost` | Restore lost the cluster operation lock while running. |
+| `Warning` | `OperationLockOverride` | Lock override requested with break-glass restore. |
+
+### OpenBaoTenant provisioning events
+
+| Type | Reason | Notes |
+| :--- | :--- | :--- |
+| `Normal` | `TenantProvisioned` | Tenant namespace RBAC was provisioned successfully. |
+| `Normal` | `TenantRBACCleaned` | Tenant namespace RBAC was cleaned up during deletion. |
+| `Warning` | `TenantProvisioningBlocked` | Provisioning is blocked by guardrails, missing prerequisites, or dependency readiness checks. |
+| `Warning` | `TenantProvisioningFailed` | Provisioning failed while applying tenant RBAC. |
+
+## Structured audit events
+
+In addition to Kubernetes Events, controllers emit structured audit events to logs, for example `UpgradeStarted`, `UpgradeFailed`, `BackupJobCreated`, `RestoreCompleted`, and `TenantRBACProvisioned`.
+
+<Callout type="note" title="Stability">
+
+Condition **types** are part of the API surface. Reason and event values may expand over time as new scenarios are added.
+
+</Callout>
+
+<NextActions
+  title="Related lookup surfaces"
+  items={[
+    {
+      label: 'Unseal configuration',
+      description: 'Provider and Secret requirements behind `CloudUnsealIdentityReady` and seal-mode setup.',
+      docId: 'user-guide/openbaocluster/configuration/unseal',
+    },
+    {
+      label: 'Troubleshoot the cluster',
+      description: 'Operational troubleshooting when the relevant signal is not yet clear.',
+      to: '/docs/operate/troubleshooting',
+    },
+    {
+      label: 'Recovery & Restore',
+      description: 'Move into the recovery section when the condition or event pattern already tells you the system needs intervention.',
+      to: '/docs/recover',
+    },
+    {
+      label: 'Compatibility matrix',
+      description: 'Return to compatibility when an unexpected status might actually come from an unsupported or unvalidated platform assumption.',
+      docId: 'reference/compatibility',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/reference/support-policy.md b/website/versioned_docs/version-0.3.0/reference/support-policy.md
new file mode 100644
index 000000000..1a98256da
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/reference/support-policy.md
@@ -0,0 +1,112 @@
+---
+title: Support Policy
+description: Support and maintenance policy for OpenBao Operator covering pre-GA posture, release channels, and best-effort latest-line support.
+pageType: reference
+journey: reference
+---
+
+<PageHeader
+  title="Support and maintenance policy"
+  lede="Release lines that receive best-effort maintenance attention, channel differences, and issue-triage expectations."
+/>
+
+<Callout type="note" title="Current support window">
+
+The project provides best-effort support for the latest stable release line.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Release channels"
+  columns={['Channel', 'What it is for', 'Support stance']}
+  rows={[
+    {
+      cells: ['Stable (`X.Y.Z`)', 'Real deployments and the main production line.', 'Best-effort support on the latest stable line.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Prerelease (`-rc`, `-beta`, `-alpha`)', 'Evaluation before the next stable release.', 'No expanded support window; use for testing and early adoption only.'],
+    },
+    {
+      cells: ['Edge (`main` snapshots)', 'Continuous validation and integration signal.', 'Evaluation and validation channel only.'],
+      emphasis: 'caution',
+    },
+    {
+      cells: ['Nightly', 'Scheduled validation snapshots.', 'Evaluation and validation channel only.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+## Pre-GA release contract
+
+OpenBao Operator is still pre-GA:
+
+- the served CRD API is `openbao.org/v1alpha1`
+- minor releases may introduce breaking API or behavior changes
+- support is best-effort and focused on the latest stable release line
+
+## Validation versus support
+
+- [Compatibility Matrix](compatibility.md) defines what is explicitly validated in CI.
+- This policy defines what receives best-effort maintenance attention.
+- `Recommended for production` means the documented hardened operating path, not a promise of long-lived pre-GA API stability.
+
+## Security fixes
+
+Security fixes follow [SECURITY.md](https://github.com/dc-tec/openbao-operator/blob/main/SECURITY.md):
+
+- security fixes are provided for the latest released version
+- vulnerabilities should be reported through GitHub Security Advisories
+
+<DecisionTable
+  kind="reference"
+  title="Operator expectations for production use"
+  columns={['Expectation', 'Why it matters']}
+  rows={[
+    {
+      cells: ['Pin explicit operator and chart versions', 'Floating channels make support and rollback reasoning weaker.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Stay close to the latest stable release', 'The project focuses its maintenance effort on that line.'],
+    },
+    {
+      cells: ['Use the `Hardened` profile with admission enforcement enabled', 'This is the documented production posture behind most guidance.'],
+    },
+    {
+      cells: ['Validate upgrades in staging', 'Best-effort support does not remove the need for environment-specific rehearsal.'],
+    },
+    {
+      cells: ['Avoid prerelease, edge, and nightly for production', 'These channels are designed for evaluation and validation, not supported production drift.'],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related support references"
+  items={[
+    {
+      label: 'Release policy',
+      description: 'Public cadence and release-gate rules.',
+      docId: 'reference/release-policy',
+    },
+    {
+      label: 'Compatibility matrix',
+      description: 'Platforms and versions exercised by CI.',
+      docId: 'reference/compatibility',
+    },
+    {
+      label: 'Known limitations',
+      description: 'Current caveats and explicit non-goals behind unsupported behavior.',
+      docId: 'reference/known-limitations',
+    },
+    {
+      label: 'Release management',
+      description: 'Maintainer release workflow behind these support expectations.',
+      to: '/contribute/release-management',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/roadmap.mdx b/website/versioned_docs/version-0.3.0/roadmap.mdx
new file mode 100644
index 000000000..2bc893f35
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/roadmap.mdx
@@ -0,0 +1,310 @@
+---
+title: Roadmap
+slug: /roadmap
+description: Public roadmap for OpenBao Operator and its planned modular platform capabilities.
+hide_title: true
+pageType: concept
+---
+
+<PageHeader
+  title="Roadmap"
+  lede="OpenBao Operator is built around a lifecycle core with optional modules for self-service, fleet management, federation, and application integration."
+/>
+
+<Callout type="note" title="Roadmap status">
+
+This roadmap describes the current project direction. It is not a commitment to release dates, final feature
+scope, or delivery order. Priorities may change based on implementation findings, user feedback, security
+review, and maintainer capacity.
+
+</Callout>
+
+## Direction
+
+OpenBao Operator starts from one primary responsibility: operate OpenBao safely on Kubernetes.
+
+The core lifecycle layer owns deployment, TLS, initialization, unseal configuration, backups, restores, upgrades,
+read scaling, tenant onboarding, production posture checks, admission guardrails, and status reporting. Future
+modules build on that lifecycle contract instead of replacing it.
+
+The design principle is:
+
+> Core owns lifecycle. Modules express intent. Modules do not bypass the lifecycle contract.
+
+## Current focus
+
+Claims and Service Offerings are the next visible product direction. They turn `OpenBaoCluster` into a
+platform-defined offering that tenants can request through a smaller claim API.
+
+The same-cluster Claims and Service Offerings path is in integration. See the
+<SiteLink docId="design/claims-and-service-offerings">Claims and Service Offerings design note</SiteLink> for the
+current public design shape and supported boundaries.
+
+Application integration, multi-cluster management, federation, and SPIFFE/SPIRE remain planned directions while
+their API boundaries, security model, and operating contracts are refined.
+
+## Upstream OpenBao alignment
+
+OpenBao Operator should track upstream OpenBao direction and adopt new OpenBao capabilities when they strengthen
+the operator lifecycle contract or a planned module. Integration still depends on stable upstream behavior,
+documented APIs, security review, and a clear Kubernetes operating model.
+
+Relevant upstream areas include OpenBao scalability, namespace and tenancy features, policy and auth
+improvements, plugin distribution, backup and restore capabilities, read scaling, and future replication or
+data-placement features if they become available in OpenBao.
+
+This does not mean every upstream feature becomes an operator feature. The operator should expose upstream
+capabilities when it can preserve clear ownership, status reporting, upgrade safety, and blast-radius boundaries.
+
+## Capability map
+
+<DecisionTable
+  kind="reference"
+  title="Roadmap areas"
+  columns={['Area', 'Public status', 'Direction']}
+  rows={[
+    {
+      cells: [
+        'Core lifecycle',
+        'Available',
+        'Secure OpenBao cluster lifecycle management on Kubernetes.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Claims and Service Offerings',
+        'In progress',
+        'Self-service OpenBao clusters through platform-defined offerings and smaller tenant-facing claims.',
+      ],
+    },
+    {
+      cells: [
+        'Application integration',
+        'Planned',
+        'Explicit workload access patterns using Kubernetes identity, CSI, Agent or Proxy delivery, and opt-in Secret sync.',
+      ],
+    },
+    {
+      cells: [
+        'Multi-cluster management',
+        'Planned',
+        'A management-plane model with downstream agents that reconcile close to workload clusters.',
+      ],
+    },
+    {
+      cells: [
+        'Federation',
+        'Planned',
+        'Central governance for policy, auth, PKI, and secret-engine configuration while keeping execution local.',
+      ],
+    },
+    {
+      cells: [
+        'SPIFFE/SPIRE integration',
+        'Exploring',
+        'Optional identity integration for environments that already operate SPIFFE/SPIRE.',
+      ],
+    },
+  ]}
+/>
+
+## Core lifecycle foundation
+
+The core lifecycle API is an operator-owned contract for clusters the operator creates and reconciles. It is not a
+generic import API for arbitrary unmanaged OpenBao clusters.
+
+Core lifecycle responsibilities include:
+
+- OpenBao cluster deployment
+- TLS configuration
+- initialization and self-initialization flows
+- external or OpenBao-native unseal configuration
+- backup and restore workflows
+- upgrade orchestration
+- read scaling
+- tenant onboarding
+- production posture checks
+- admission and configuration guardrails
+- status and condition reporting
+
+## Claims and Service Offerings
+
+Claims and Service Offerings add a self-service layer above `OpenBaoCluster`.
+
+Platform operators define approved cluster shapes as offerings. Tenant or application teams request instances
+through a smaller claim API. The claim should expose the decisions a tenant needs to make, while platform policy,
+defaults, guardrails, and lifecycle rendering stay inside the offering.
+
+Direction:
+
+- keep the claim API small and user-focused
+- keep platform policy inside Service Offerings
+- track which offering revision rendered a claim
+- support safe claim behavior when offerings change
+- project useful status from the rendered `OpenBaoCluster` back to the claim
+- avoid exposing raw lifecycle internals unless the offering explicitly allows it
+
+## Application integration
+
+Application integration covers how workloads consume secrets from OpenBao.
+
+The preferred direction is identity-first and explicit. The operator should reconcile access relationships,
+policies, auth roles, and delivery configuration. It should not silently mutate application Pods as the default
+integration mechanism.
+
+Potential integration paths include direct client access, CSI volume delivery, Agent or Proxy delivery,
+compatibility-focused Kubernetes Secret sync, and SPIFFE/SPIRE auth for environments that already operate it.
+
+Direction:
+
+- avoid mutating workload webhooks as the default path
+- avoid Kubernetes Secrets by default
+- use short-lived workload identity
+- make delivery mode explicit
+- keep secret values out of CRDs, status, logs, and events
+- support Kubernetes ServiceAccount identity as the default
+- support SPIFFE/SPIRE as an advanced identity backend
+
+## Multi-cluster management
+
+Multi-cluster management is intended to let a management control plane operate OpenBao clusters on downstream
+workload clusters.
+
+The preferred direction is a hub-and-agent model. The management plane expresses placement and fleet intent. A
+downstream agent runs near each workload cluster and reconciles local resources with local permissions.
+
+Direction:
+
+- avoid storing broad kubeconfigs for downstream clusters in the management cluster
+- prefer outbound connectivity from downstream clusters where possible
+- keep local Kubernetes RBAC local
+- support per-cluster identity and revocation
+- propagate status back to the management plane
+- allow claims to target placements instead of individual clusters
+- support operator-managed mTLS as the default identity mode
+- support SPIFFE/SPIRE as an advanced identity mode
+
+## Federation
+
+Federation provides central governance for multiple OpenBao clusters.
+
+Federation does not mean stretching one OpenBao storage cluster across multiple workload clusters. It also does
+not make tokens, leases, or root credentials portable between clusters.
+
+The preferred model is federated control with local execution. A management OpenBao cluster and federation
+controller can define shared intent, while downstream OpenBao clusters continue to serve local workloads, issue
+local leases, keep local audit trails, and enforce local auth.
+
+Potential federation areas include policies, auth methods, auth roles, secret engines, dynamic secret roles, PKI,
+and explicitly scoped static secret export. Tokens, leases, and root credentials are not federation targets.
+
+Direction:
+
+- keep downstream OpenBao clusters independently operable
+- keep leases local to the cluster that issued them
+- keep application authentication local wherever possible
+- make static secret export explicit and narrow
+- prefer policy, auth, PKI, and secret-engine federation before secret-value federation
+- support drift detection
+- support safe deletion and conflict policies
+- preserve clear blast-radius boundaries
+
+## SPIFFE/SPIRE integration
+
+SPIFFE/SPIRE is planned as an optional advanced identity integration. It should not be required for normal
+OpenBao Operator usage.
+
+SPIFFE/SPIRE may support:
+
+- downstream agent identity in multi-cluster management
+- federation hub-to-agent trust
+- workload identity for application access
+- OpenBao cert-auth or JWT-auth integrations
+- trust-domain-aware policy and access binding models
+
+Default users should be able to use Kubernetes ServiceAccount identity without installing SPIRE. Environments
+with existing SPIFFE/SPIRE deployments should be able to use SPIFFE identities as first-class subjects.
+
+## Longer-term exploration
+
+The following areas are candidates for future work. They are intentionally listed as exploration, not committed
+scope, and remain bounded by the non-goals below.
+
+### Visibility and governance
+
+- access graph and `who can read what` explanations
+- secret consumption inventory across workloads
+- reusable policy packs and policy impact simulation
+- compliance evidence export
+
+### Reliability and fleet operations
+
+- restore drills and backup confidence checks
+- federation drift detection and reconciliation modes
+- fleet-aware progressive rollout strategies
+- cluster capability discovery for placement decisions
+
+### Platform ecosystem
+
+- OpenBao PKI platform capabilities
+- developer portal, GitOps, Crossplane, Terraform, OpenTofu, and CLI integrations
+
+## Non-goals
+
+The following are not current roadmap goals:
+
+- transparent OpenBao storage replication across independent clusters
+- making OpenBao tokens portable between clusters
+- replicating leases between clusters
+- automatically copying all secrets from a management cluster to downstream clusters
+- making SPIFFE/SPIRE mandatory
+- using mutating workload webhooks as the default application integration path
+- turning `OpenBaoCluster` into a generic import API for unmanaged OpenBao clusters
+- giving the management plane unrestricted root access to all downstream clusters by default
+
+## Principles
+
+The roadmap is guided by these principles:
+
+1. Secure defaults first. Prefer explicit identity, least privilege, short-lived credentials, and safe failure modes.
+2. Core lifecycle remains separate. Modules build on the lifecycle contract instead of bypassing or duplicating it.
+3. Modular adoption. Users can adopt self-service, multi-cluster, federation, application integration, and SPIFFE
+   support independently.
+4. No hidden secret movement. Secret values do not move between systems unless a user explicitly configures that
+   behavior.
+5. Status over surprise. External dependencies, missing prerequisites, degraded integrations, and unsafe
+   configurations surface through status conditions.
+6. Local ownership where it matters. Downstream OpenBao clusters retain local authentication, local lease
+   ownership, local auditability, and local recovery options.
+7. Advanced features stay explicit. SPIFFE/SPIRE, federation, secret export, and multi-cluster management do not
+   become hidden requirements for basic OpenBao operation.
+
+## Feedback
+
+The roadmap will evolve through implementation work, user feedback, and security review.
+
+Feedback is welcome through GitHub issues and discussions, especially around self-service claim workflows,
+platform offering design, multi-cluster operating models, federation use cases, application integration patterns,
+SPIFFE/SPIRE expectations, and security boundaries.
+
+<NextActions
+  title="Related sections"
+  items={[
+    {
+      label: 'Operator invariants',
+      description: 'Lifecycle contracts and safety properties that future modules must preserve.',
+      docId: 'architecture/operator-invariants',
+    },
+    {
+      label: 'Known limitations',
+      description: 'Current constraints and explicit non-goals for the pre-GA release line.',
+      docId: 'reference/known-limitations',
+    },
+    {
+      label: 'Support policy',
+      description: 'Current release support posture and pre-GA maintenance expectations.',
+      docId: 'reference/support-policy',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/fundamentals/index.md b/website/versioned_docs/version-0.3.0/security/fundamentals/index.md
new file mode 100644
index 000000000..ec335203b
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/fundamentals/index.md
@@ -0,0 +1,67 @@
+---
+title: Security Model
+hide_title: true
+pageType: landing
+journey: security
+description: Core security fundamentals for OpenBao Operator including threat model, security profiles, and secrets management practices.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Security / Security Model"
+  title="Security model and trust assumptions"
+  lede="Threat model, security profiles, and trust material such as root tokens, unseal keys, and bootstrap identities."
+  actions={[
+    {label: 'Read the threat model', docId: 'security/fundamentals/threat-model', variant: 'primary'},
+    {label: 'Review production posture', docId: 'security/fundamentals/profiles', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Covers"
+    items={[
+      'understand the security assumptions behind the operator architecture',
+      'understand how Development and Hardened profiles change the supported security posture',
+      'review how bootstrap and unseal trust material is handled',
+      'anchor security review conversations before diving into RBAC or network policy details',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Security model routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Threat model',
+      description: 'Trust boundaries, attacker assumptions, and design mitigations.',
+      docId: 'security/fundamentals/threat-model',
+    },
+    {
+      eyebrow: '02',
+      title: 'Production posture',
+      description: 'How Development and Hardened differ, and the supported production contract.',
+      docId: 'security/fundamentals/profiles',
+    },
+    {
+      eyebrow: '03',
+      title: 'Secrets and trust material',
+      description: 'Review how root tokens, unseal keys, and bootstrap credentials are created, stored, or intentionally avoided.',
+      docId: 'security/fundamentals/secrets-management',
+    },
+  ]}
+/>
+
+<NextActions
+  items={[
+    {
+      label: 'Open platform controls',
+      description: 'Kubernetes controls that enforce the trust model.',
+      docId: 'security/infrastructure/index',
+    },
+    {
+      label: 'Configure security profiles',
+      description: 'Task page for setting `spec.profile` on a cluster.',
+      docId: 'user-guide/openbaocluster/configuration/security-profiles',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/fundamentals/profiles.md b/website/versioned_docs/version-0.3.0/security/fundamentals/profiles.md
new file mode 100644
index 000000000..b87c11a79
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/fundamentals/profiles.md
@@ -0,0 +1,174 @@
+---
+title: Production Posture
+hide_title: true
+pageType: concept
+journey: security
+description: What Development and Hardened mean as security contracts, and why Hardened is the supported production posture for OpenBao Operator.
+---
+
+<PageHeader
+  title="Security profile contracts"
+  lede="What `Development` and `Hardened` optimize for, what Hardened requires in production, and how the profiles change the operating contract."
+/>
+
+
+
+<DecisionTable
+  title="Profile intent"
+  columns={['Profile', 'Optimized for', 'What it trades off']}
+  rows={[
+    {
+      cells: [
+        'Hardened',
+        'Production deployments with explicit external trust roots and stricter lifecycle guarantees.',
+        'More up-front requirements, less tolerance for weak bootstrap and trust shortcuts.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Development',
+        'Local testing, CI, and quick evaluation when long-term trust posture is not the goal.',
+        'Allows bootstrap and unseal material to exist in cluster Secrets and relaxes some runtime guarantees.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Profile comparison"
+  columns={['Feature', 'Hardened', 'Development']}
+  rows={[
+    {
+      cells: [
+        'Root token handling',
+        'Auto-revoked; not stored in a Secret as part of the supported production path.',
+        'Can be stored in a Secret when self-init is disabled.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Unseal root of trust',
+        'Requires a non-static external trust source such as transit, cloud KMS, or HSM-backed modes.',
+        'Defaults can rely on a static key in a Kubernetes Secret.',
+      ],
+    },
+    {
+      cells: [
+        'TLS posture',
+        'Requires `External` or `ACME` style trust; `OperatorManaged` TLS is not the production path.',
+        'Allows operator-managed TLS for local or test usage.',
+      ],
+    },
+    {
+      cells: [
+        'Bootstrap model',
+        'Self-init is the supported production path.',
+        'Manual bootstrap or self-init are both possible.',
+      ],
+    },
+    {
+      cells: [
+        'Supply-chain guardrails',
+        'Image verification protections remain on and cannot degrade to warning-only behavior.',
+        'Verification can be relaxed for testing.',
+      ],
+    },
+  ]}
+/>
+
+## Hardened production contract
+
+<DecisionTable
+  kind="reference"
+  title="Hardened production requirements"
+  columns={['Requirement', 'Why it exists', 'Operational effect']}
+  rows={[
+    {
+      cells: [
+        'At least three replicas',
+        'Raft needs quorum and safe disruption handling in production.',
+        'Single-node clusters are not treated as production-safe.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'External trust root for unseal',
+        'The cluster should not keep its root of trust only in Kubernetes etcd.',
+        'Cloud KMS, transit, KMIP, or PKCS#11-style paths become part of the deployment contract.',
+      ],
+    },
+    {
+      cells: [
+        'Trusted TLS path',
+        'The workload identity boundary should be anchored in a production-grade certificate model.',
+        '`OperatorManaged` TLS is rejected for Hardened clusters.',
+      ],
+    },
+    {
+      cells: [
+        'Self-init enabled',
+        'The supported bootstrap path should avoid persisting the initial root token.',
+        'Human bootstrap becomes declarative instead of secret-based.',
+      ],
+    },
+    {
+      cells: [
+        'Verification guardrails stay enforced',
+        'Production image trust should not be optional.',
+        'Managed workloads keep digest and verification enforcement even when omitted from config.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="success" title="Hardened profile assumptions">
+
+Hardened means the operator can rely on an external trust root, explicit runtime identity, and a production-ready lifecycle posture. It defines the operating model for the cluster, not just one field in the CR.
+
+</Callout>
+
+## Development profile relaxations
+
+Development intentionally relaxes the production contract:
+
+- bootstrap material can persist in cluster Secrets
+- static unseal remains available
+- operator-managed TLS can be used
+- runtime and supply-chain controls can be less strict
+- the cluster reports a security-risk signal rather than pretending this posture is production-ready
+
+<Callout type="warning" title="Trust-root migrations">
+
+Teams often start in Development for exploration. When moving to staging or production, create a new Hardened cluster rather than assuming a Development trust path can be promoted safely.
+Teams often start in Development for exploration. For staging or production, create a new Hardened cluster instead of promoting a Development trust path in place.
+
+</Callout>
+
+## Configuration scope
+
+Configuration steps for `spec.profile`, unseal mode, and the production requirements are in <SiteLink docId="user-guide/openbaocluster/configuration/security-profiles">Configure Security Profiles</SiteLink>.
+
+<NextActions
+  title="Continue the security model"
+  items={[
+    {
+      label: 'Configure security profiles',
+      description: 'Cluster fields and configuration steps behind these profile requirements.',
+      docId: 'user-guide/openbaocluster/configuration/security-profiles',
+    },
+    {
+      label: 'Secrets and trust material',
+      description: 'Review how root tokens, unseal keys, and job identities differ between these profiles.',
+      docId: 'security/fundamentals/secrets-management',
+    },
+    {
+      label: 'Threat model',
+      description: 'Rationale behind these profile boundaries.',
+      docId: 'security/fundamentals/threat-model',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/fundamentals/secrets-management.md b/website/versioned_docs/version-0.3.0/security/fundamentals/secrets-management.md
new file mode 100644
index 000000000..1e5f09db8
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/fundamentals/secrets-management.md
@@ -0,0 +1,230 @@
+---
+title: Secrets and Trust Material
+hide_title: true
+pageType: concept
+journey: security
+description: How root tokens, unseal keys, TLS material, and generated job identities are created, avoided, or bounded across the OpenBao Operator lifecycle.
+---
+
+<PageHeader
+  title="Secrets and trust material lifecycle"
+  lede="Bootstrap credentials, unseal roots, TLS material, and the identities used by backup, restore, and upgrade workflows."
+/>
+
+
+
+<DecisionTable
+  kind="reference"
+  title="Managed trust material"
+  columns={['Surface', 'Typical location', 'Security posture']}
+  rows={[
+    {
+      cells: [
+        'Root token',
+        'Secret only when bootstrap mode persists it',
+        'Critical and intentionally avoided by the supported Hardened self-init path.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Static unseal key',
+        '`<cluster>-unseal-key` Secret',
+        'Critical because the root of trust sits inside Kubernetes instead of an external trust system.',
+      ],
+    },
+    {
+      cells: [
+        'Cluster CA and server TLS material',
+        'Secrets when the selected TLS mode requires them',
+        'High-value trust material whose lifecycle depends on the chosen TLS mode.',
+      ],
+    },
+    {
+      cells: [
+        'Backup, restore, and upgrade job auth',
+        'Projected tokens, generated ServiceAccounts, or explicit credentials Secrets',
+        'Separate from the main OpenBao workload identity.',
+      ],
+    },
+  ]}
+/>
+
+## Unseal trust model
+
+<Tabs groupId="trust-material-unseal">
+
+<TabItem value="static" label="Static unseal">
+
+<Callout type="warning" title="Static unseal keeps the root of trust in the cluster">
+
+Static unseal generates a 32-byte key and stores it in a Kubernetes Secret. If etcd encryption or namespace access is weak, the effective trust root of your OpenBao data is weak too.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Static unseal behavior"
+  columns={['Aspect', 'Behavior', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Generation',
+        'The operator creates a random key.',
+        'Bootstrap is convenient, but the cluster is now trusted to protect the root of trust.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Storage',
+        'The key is stored in `<cluster>-unseal-key`.',
+        'Anyone who can read that Secret can compromise the trust root.',
+      ],
+    },
+    {
+      cells: [
+        'Rotation',
+        'Manual, not automatic.',
+        'Operational handling of the trust root stays a human responsibility.',
+      ],
+    },
+  ]}
+/>
+
+</TabItem>
+
+<TabItem value="external" label="External trust root">
+
+<Callout type="success" title="Preferred production posture">
+
+Using transit, cloud KMS, or HSM-backed modes shifts the root of trust away from Kubernetes and into an external system that is designed to protect it.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="External trust behavior"
+  columns={['Aspect', 'Behavior', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Operator-owned unseal key',
+        'Not created',
+        'The cluster does not persist its own trust root in a Kubernetes Secret.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Authentication path',
+        'Uses workload identity or explicit credentials for the selected backend.',
+        'The identity contract becomes part of the production posture and must be observable.',
+      ],
+    },
+    {
+      cells: [
+        'Readiness model',
+        'Surfaced through conditions such as `CloudUnsealIdentityReady`.',
+        'Failures become visible before operators have to infer them from generic pod errors.',
+      ],
+    },
+  ]}
+/>
+
+</TabItem>
+
+</Tabs>
+
+## Bootstrap credentials and root token handling
+
+<DecisionTable
+  title="Bootstrap paths"
+  columns={['Path', 'What happens to the root token', 'Security effect']}
+  rows={[
+    {
+      cells: [
+        'Hardened self-init',
+        'The initial root token is not persisted as the normal operating model.',
+        'This avoids leaving a long-lived administrative credential in namespace Secrets.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Development bootstrap without self-init',
+        'The root token can be stored in `<cluster>-root-token`.',
+        'Testing-oriented path that creates a critical secret in the namespace.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="danger" title="Persisted bootstrap secrets are full-administration material">
+
+If a root token or equivalent bootstrap credential exists in a Secret, anyone who can read that Secret effectively has full administrative control of the OpenBao cluster.
+
+</Callout>
+
+## TLS and job identities
+
+<DiagramFrame
+  title="Job identity separation"
+  caption="The main OpenBao Pods, backup jobs, restore jobs, and upgrade jobs use separate identity paths so each surface stays explicit and observable."
+  code={`sequenceDiagram
+    autonumber
+    participant Operator as Operator
+    participant K8s as Kubernetes API
+    participant Bao as OpenBao
+    participant Job as Lifecycle Job
+
+    Note over Operator,K8s: Discovery
+    Operator->>K8s: Discover OIDC issuer and JWKS
+
+    Note over Operator,Bao: Bootstrap
+    Operator->>Bao: Configure JWT auth and roles
+
+    Note over Operator,Job: Execution
+    Operator->>K8s: Create Job with generated ServiceAccount
+    K8s-->>Job: Start with projected token
+    Job->>Bao: Login with JWT
+    Bao-->>Job: Scoped OpenBao token
+    Job->>Bao: Perform backup, restore, or upgrade work`}
+/>
+
+Lifecycle job identities stay separate from the main workload identity:
+
+- main OpenBao Pods use the trust path selected for the cluster itself
+- backup, restore, and upgrade Jobs use separate generated identities
+- those Jobs do not automatically inherit the cloud or JWT path of the main workload unless the operator deliberately configured it
+
+Backup and restore readiness are surfaced independently in status rather than inferred from the main Pods.
+
+## Related task pages
+
+Operational task pages:
+
+- <SiteLink docId="user-guide/openbaocluster/configuration/security-profiles">Configure Security Profiles</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/operations/backups">Configure Backups</SiteLink>
+- <SiteLink docId="user-guide/openbaorestore/restore">Restore from Backup</SiteLink>
+
+<NextActions
+  title="Continue the security model"
+  items={[
+    {
+      label: 'Production posture',
+      description: 'How these trust-material choices map back to Development versus Hardened.',
+      docId: 'security/fundamentals/profiles',
+    },
+    {
+      label: 'Configure security profiles',
+      description: 'Cluster fields behind these trust-model choices.',
+      docId: 'user-guide/openbaocluster/configuration/security-profiles',
+    },
+    {
+      label: 'Threat model',
+      description: 'Attacker model and surrounding boundary assumptions.',
+      docId: 'security/fundamentals/threat-model',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/fundamentals/threat-model.md b/website/versioned_docs/version-0.3.0/security/fundamentals/threat-model.md
new file mode 100644
index 000000000..1f2cfd2af
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/fundamentals/threat-model.md
@@ -0,0 +1,416 @@
+---
+title: Threat Model
+hide_title: true
+pageType: concept
+journey: security
+description: Threat actors, trust boundaries, protected assets, and accepted residual risks for the OpenBao Operator control plane.
+---
+
+<PageHeader
+  title="Threat model and scope"
+  lede="Threat model for the operator control plane, tenant isolation boundaries, and lifecycle workflows such as onboarding, upgrade, backup, and restore. It complements OpenBao's own internal threat model by covering the extra surface introduced by the operator."
+/>
+
+
+
+<Callout type="note" title="Scope">
+
+This model assumes the operator manages clusters it created and reconciles; generic import of arbitrary unmanaged OpenBao clusters is out of scope.
+
+</Callout>
+
+<DecisionTable
+  title="Threat-model scope"
+  columns={['Area', 'In scope', 'Why']}
+  rows={[
+    {
+      cells: [
+        'Operator control plane',
+        'Yes',
+        'Long-running operator identities, admission dependencies, and controller boundaries define most of the extra risk introduced by the operator.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Tenant isolation',
+        'Yes',
+        'Namespace introduction, RBAC boundaries, and managed-resource ownership are core to the multi-tenant model.',
+      ],
+    },
+    {
+      cells: [
+        'Lifecycle workflows',
+        'Yes',
+        'Backup, restore, upgrade, and tenant onboarding introduce destructive or privileged execution paths.',
+      ],
+    },
+    {
+      cells: [
+        'OpenBao internals unrelated to the operator',
+        'No',
+        'Those belong to OpenBao’s own product threat model rather than the operator-specific surface.',
+      ],
+    },
+  ]}
+/>
+
+## Threat actors
+
+<DecisionTable
+  kind="reference"
+  title="Actors that matter"
+  columns={['Actor', 'Typical access', 'Why they matter']}
+  rows={[
+    {
+      cells: [
+        'Tenant author',
+        'Namespace-scoped write access',
+        'Can attempt to steer the operator, exploit weak isolation, or target Secrets and workload identities inside an onboarded namespace.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'GitOps pipeline or human cluster operator',
+        'Namespace or cluster write access',
+        'Can intentionally or accidentally mutate control-plane configuration, admission dependencies, or operator-managed resources.',
+      ],
+    },
+    {
+      cells: [
+        'Compromised controller or provisioner Pod',
+        'Operator-managed identity',
+        'Tests whether the split-controller model and mutation locks actually narrow blast radius.',
+      ],
+    },
+    {
+      cells: [
+        'Compromised OpenBao Pod or lifecycle Job',
+        'Namespace workload identity',
+        'Exercises the boundary between the steady-state service, generated Jobs, and the control plane.',
+      ],
+    },
+    {
+      cells: [
+        'Compromised or misconfigured external dependency',
+        'Object storage, PKI, KMS, ingress, or identity system',
+        'The operator relies on those systems for unseal, TLS, backup, restore, and external access contracts.',
+      ],
+    },
+  ]}
+/>
+
+## Trust boundaries
+
+<DiagramFrame
+  title="Trust zones"
+  caption="Admission policy is the API enforcement boundary between submitted intent and persisted state. Operator identities, tenant workloads, and external systems each carry different trust assumptions."
+  code={`graph TD
+    subgraph Client_Zone ["Mutation clients"]
+        GitOps["GitOps / human operator"]
+        Tenant["Tenant author"]
+    end
+
+    subgraph Operator_Zone ["Operator identities"]
+        Prov["Provisioner"]
+        Ctrl["Controller"]
+    end
+
+    subgraph API_Zone ["Kubernetes API"]
+        K8sAPI["Kubernetes API"]
+        VAP["Admission policies"]
+    end
+
+    subgraph Tenant_Zone ["Tenant namespace"]
+        Bao["OpenBao Pods"]
+        Jobs["Backup / restore / upgrade Jobs"]
+        Managed["Managed resources"]
+    end
+
+    subgraph External_Zone ["External systems"]
+        Edge["Gateway / ingress"]
+        Storage["Object storage"]
+        Trust["Seal / PKI / identity systems"]
+    end
+
+    GitOps --> K8sAPI
+    Tenant --> K8sAPI
+    K8sAPI --> VAP
+    Prov --> K8sAPI
+    Ctrl --> K8sAPI
+    Ctrl --> Bao
+    Ctrl --> Jobs
+    Ctrl --> Managed
+    Edge --> Bao
+    Bao --> Trust
+    Jobs --> Storage
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class GitOps,Tenant,K8sAPI,Storage,Trust read;
+    class Prov,Ctrl,VAP process;
+    class Bao,Jobs,Managed,Edge write;`}
+/>
+
+## Protected assets
+
+<DecisionTable
+  kind="reference"
+  title="Always-relevant assets"
+  columns={['Asset', 'Risk', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Admission policies and bindings',
+        'Critical',
+        'They enforce the operator’s API-level safety model before unsafe intent persists.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Provisioner and controller identities',
+        'Critical',
+        'They define namespace onboarding and lifecycle authority across the cluster.',
+      ],
+    },
+    {
+      cells: [
+        'Tenant RBAC and Secret allowlists',
+        'High',
+        'They control what an onboarded namespace can read, mutate, or discover.',
+      ],
+    },
+    {
+      cells: [
+        'Raft data and snapshots',
+        'High',
+        'They contain the OpenBao state the operator is trying to protect and recover safely.',
+      ],
+    },
+    {
+      cells: [
+        'Operator-managed configuration and generated job identities',
+        'Medium',
+        'They steer runtime behavior and disruptive workflows even when they do not directly store application secrets.',
+      ],
+    },
+    {
+      cells: [
+        'Audit records',
+        'High',
+        'They can contain sensitive request metadata and are needed for incident reconstruction and compliance evidence.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Conditional assets"
+  columns={['Asset', 'Present when', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Root token Secret',
+        'Bootstrap mode persists the initial root token',
+        'This is a critical administrative credential and is intentionally avoided by Hardened self-init.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Static unseal keys',
+        'Static unseal is used',
+        'The root of trust sits in a Kubernetes Secret instead of an external trust system.',
+      ],
+    },
+    {
+      cells: [
+        'Operator-managed CA key',
+        '`OperatorManaged` TLS mode is selected',
+        'This puts certificate authority material inside the cluster and is one reason that mode is not the Hardened path.',
+      ],
+    },
+    {
+      cells: [
+        'Transit, cloud KMS, or HSM credentials',
+        'External unseal or PKI integration is used',
+        'These credentials and identity paths sit at a high-value trust boundary outside the workload itself.',
+      ],
+    },
+    {
+      cells: [
+        'Audit file storage PVC',
+        '`spec.auditFileStorage` is configured',
+        'This PVC is a local handoff buffer for audit records before the collector ships them to the retention system.',
+      ],
+    },
+  ]}
+/>
+
+## STRIDE analysis
+
+<ExpandableCallout type="failure" title="Spoofing">
+
+**Threats**
+
+- A client or GitOps render path spoofs operator identity by drifting `ServiceAccount` names, policy subjects, or `RoleBinding` subjects.
+- A workload or edge path spoofs cluster identity at the TLS boundary.
+- Backup, restore, or upgrade Jobs inherit the wrong identity path.
+
+<Callout type="success" title="Primary mitigations">
+
+- Split provisioner and controller identities.
+- Validate rendered install identities for Helm and raw-manifest overlays.
+- Validate TLS SANs and trust sources before the cluster becomes ready.
+- Use separate job `ServiceAccount` objects, identity checks, and Job-specific network controls.
+
+</Callout>
+
+</ExpandableCallout>
+
+<ExpandableCallout type="warning" title="Tampering">
+
+**Threats**
+
+- A user, GitOps controller, or compromised namespace actor directly mutates operator-managed resources.
+- A compromised provisioner broadens tenant RBAC or tenant guardrails.
+- A tenant or operator steers backup or restore jobs toward unintended endpoints or credentials.
+- A workload with access to the audit PVC alters or deletes audit files before the collector ships them.
+
+<Callout type="success" title="Primary mitigations">
+
+- Lock operator-managed resources with admission policy.
+- Restrict controller writes for RBAC, `ServiceAccount`, and Secret objects.
+- Restrict provisioner namespace mutation and tenant-governance writes.
+- Keep backup and restore credentials name-scoped and separately validated.
+- Mount audit storage read-only into collectors and ship records to retention-controlled storage.
+
+</Callout>
+
+<Callout type="note" title="PVC posture">
+
+Operator-managed PVCs are intentionally CR-driven and status-observed rather than fully admission-locked because Kubernetes storage controllers and CSI components also mutate PVCs during normal lifecycle.
+
+</Callout>
+
+</ExpandableCallout>
+
+<ExpandableCallout type="note" title="Repudiation">
+
+**Threats**
+
+- High-value control-plane actions cannot be attributed later.
+- Break-glass changes happen without a clear audit boundary.
+- Audit files remain only on PVC-backed handoff storage and are rotated or deleted before durable collection.
+
+<Callout type="success" title="Primary mitigations">
+
+- Emit structured operator audit logs for startup gating, upgrades, backups, restore, and operation-lock transitions.
+- Use Kubernetes API audit logs and admission denials as the primary mutation trail.
+- Keep maintenance mode explicit and grant the custom maintenance permission only to trusted operators.
+- Collect OpenBao audit files into an external log system or immutable archive with retention policy.
+
+</Callout>
+
+</ExpandableCallout>
+
+<ExpandableCallout type="danger" title="Information Disclosure">
+
+**Threats**
+
+- Secrets, credentials, or keys are exposed through logs or broad namespace access.
+- TLS handling leaks sensitive material.
+- Backup and restore credentials leak across workloads.
+- Audit files are read by a workload, user, node operator, or storage administrator outside the intended collection path.
+
+<Callout type="success" title="Primary mitigations">
+
+- Never log secrets.
+- Keep Secret access name-scoped without normal Secret enumeration.
+- Use separate writer and reader roles for operator-managed Secrets.
+- Keep ACME private keys in the OpenBao process instead of Kubernetes Secrets.
+- Use separate workload identities for backup and restore Jobs.
+- Restrict who can mount audit PVCs, use `exec`, configure collectors, or administer backing storage.
+
+</Callout>
+
+</ExpandableCallout>
+
+<ExpandableCallout type="failure" title="Denial of Service">
+
+**Threats**
+
+- Misconfiguration or tampering causes reconcile churn or blocks convergence.
+- Day-2 operations collide or force unsafe concurrent mutations.
+- Voluntary disruption or PDB tampering breaks quorum.
+- Required admission policies disappear after startup.
+
+<Callout type="success" title="Primary mitigations">
+
+- Use controller rate limiting and bounded concurrency.
+- Validate objects at admission before invalid state persists.
+- Use explicit readiness conditions for API-server, Gateway, ACME, backup, and restore assumptions.
+- Use a shared operation lock for disruptive workflows.
+- Manage `PodDisruptionBudget` objects and lock them against drift.
+- Re-check admission dependencies at runtime and pause privileged reconciliation when they disappear.
+
+</Callout>
+
+</ExpandableCallout>
+
+<ExpandableCallout type="danger" title="Elevation of Privilege">
+
+**Threats**
+
+- A compromised controller broadens tenant privileges or writes to unrelated Secrets or `ServiceAccount` objects.
+- A compromised provisioner mints broader tenant access or mutates protected namespaces.
+- Unsafe mode or break-glass use weakens the API-level defense-in-depth boundary.
+
+<Callout type="success" title="Primary mitigations">
+
+- Split long-running identities and restrict controller writes.
+- Keep Secret access name-scoped and allowlisted.
+- Restrict provisioner RBAC, namespace mutation, and tenant-governance writes.
+- Keep unsafe mode explicitly non-production and break-glass scoped.
+
+</Callout>
+
+</ExpandableCallout>
+
+## Accepted residual risks
+
+<Callout type="warning" title="Accepted posture">
+
+- PVCs are intentionally soft-governed rather than fully admission-locked because Kubernetes and CSI controllers also update them.
+- Audit file storage is a handoff and replay buffer. The operator does not provide tamper-proof audit archival or retention controls.
+- `UserAccessBootstrap` is best-effort signaling. The operator does not prove that arbitrary self-init requests create a usable human authentication path.
+- Cloud KMS and external identity integrations are surfaced through conditions and validation, but still depend on systems outside the operator trust boundary.
+- `unsafe mode` intentionally weakens the API-level safety model and is not a supported Hardened production posture.
+
+</Callout>
+
+<NextActions
+  title="Continue the security model"
+  items={[
+    {
+      label: 'Production posture',
+      description: 'Move from threats into the supported security contract for Development versus Hardened.',
+      docId: 'security/fundamentals/profiles',
+    },
+    {
+      label: 'Secrets and trust material',
+      description: 'Review how root tokens, unseal keys, and workload bootstrap identities behave across the lifecycle.',
+      docId: 'security/fundamentals/secrets-management',
+    },
+    {
+      label: 'Admission policies',
+      description: 'See one of the main enforcement layers that turns this model into actual API guardrails.',
+      docId: 'security/infrastructure/admission-policies',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/index.mdx b/website/versioned_docs/version-0.3.0/security/index.mdx
new file mode 100644
index 000000000..57af68c32
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/index.mdx
@@ -0,0 +1,75 @@
+---
+title: Security
+slug: /security
+hide_title: true
+pageType: landing
+journey: security
+description: Threat model, hardened profiles, RBAC, admission policy, network controls, workload security, and multi-tenancy.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Security"
+  title="Security documentation"
+  lede="Operator trust model, production posture, platform controls, workload protections, and tenant isolation."
+  actions={[
+    {label: 'Read the security model', docId: 'security/fundamentals/index', variant: 'primary'},
+    {label: 'Review platform controls', docId: 'security/infrastructure/index', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="A production posture includes"
+    items={[
+      'Hardened profile by default',
+      'admission enforcement enabled',
+      'explicit version pinning and staged upgrade validation',
+      'clear workload and tenant trust boundaries',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Security layers"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Security model',
+      description: 'Threat model, production posture, and the trust material assumptions behind the operator design.',
+      docId: 'security/fundamentals/index',
+    },
+    {
+      eyebrow: '02',
+      title: 'Platform controls',
+      description: 'RBAC architecture, admission policies, and network boundaries for the control plane.',
+      docId: 'security/infrastructure/index',
+    },
+    {
+      eyebrow: '03',
+      title: 'Workload protections',
+      description: 'Pod hardening, TLS identity, and supply-chain verification for the deployed service.',
+      docId: 'security/workload/index',
+    },
+    {
+      eyebrow: '04',
+      title: 'Tenant isolation',
+      description: 'Namespace boundaries, tenancy guarantees, and the limits of the shared-service model.',
+      docId: 'security/multi-tenancy/index',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related task pages"
+  items={[
+    {
+      label: 'Security profiles',
+      description: 'Task page for configuring `spec.profile` on a cluster.',
+      docId: 'user-guide/openbaocluster/configuration/security-profiles',
+    },
+    {
+      label: 'Tenant onboarding',
+      description: 'Namespace introduction and governance path in the user guide.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/infrastructure/admission-policies.md b/website/versioned_docs/version-0.3.0/security/infrastructure/admission-policies.md
new file mode 100644
index 000000000..529dd4f6d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/infrastructure/admission-policies.md
@@ -0,0 +1,234 @@
+---
+title: Admission Policies
+hide_title: true
+pageType: concept
+journey: security
+description: How ValidatingAdmissionPolicy guardrails enforce managed-resource ownership, tenant onboarding boundaries, and fail-closed startup and runtime checks.
+---
+
+<PageHeader
+  title="Admission policies and fail-closed behavior"
+  lede="Kubernetes `ValidatingAdmissionPolicy` guardrails for key safety rules at the API boundary."
+/>
+
+
+
+<DiagramFrame
+  title="Admission enforcement flow"
+  caption="GitOps, human operators, and controller identities all cross the same API boundary. Admission guardrails stop invalid or dangerous objects before the reconcile loop has to repair them."
+  code={`graph LR
+    User["GitOps / human / controller write"] --> API["Kubernetes API"]
+    API --> Policy["ValidatingAdmissionPolicy"]
+    Policy -- "deny" --> Reject["Request rejected"]
+    Policy -- "allow" --> Persist["Object persisted"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class User,API read;
+    class Policy process;
+    class Reject,Persist write;`}
+/>
+
+<DecisionTable
+  title="Policy families"
+  columns={['Family', 'What it protects', 'Representative policies']}
+  rows={[
+    {
+      cells: [
+        'Managed-resource ownership',
+        'Prevents users, GitOps, and controllers from mutating operator-managed objects outside the allowed patterns.',
+        '`openbao-lock-managed-resource-mutations`, controller StatefulSet self-protection, image digest enforcement.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Spec validation',
+        'Rejects invalid `OpenBaoCluster`, `OpenBaoTenant`, and `OpenBaoRestore` objects before they persist.',
+        '`openbao-validate-openbaocluster`, `openbao-validate-openbao-tenant`, `openbao-validate-openbaorestore`.',
+      ],
+    },
+    {
+      cells: [
+        'Provisioner restrictions',
+        'Constrains tenant onboarding, namespace mutation, and day-0 governance writes.',
+        '`openbao-restrict-provisioner-rbac`, namespace-mutation, and tenant-governance policies.',
+      ],
+    },
+    {
+      cells: [
+        'Controller restrictions',
+        'Constrains controller RBAC, ServiceAccount creation, and Secret writes.',
+        '`openbao-restrict-controller-rbac`, ServiceAccount, and Secret-write policies.',
+      ],
+    },
+  ]}
+/>
+
+## Fail-closed startup and runtime behavior
+
+<DecisionTable
+  kind="reference"
+  title="Admission dependency model"
+  columns={['State', 'Operator behavior', 'Why']}
+  rows={[
+    {
+      cells: [
+        'Required policy set present and bound',
+        'Startup and sensitive reconciliation proceed normally.',
+        'The operator can rely on the API-level guardrails it expects.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Required policy set missing at startup',
+        'Startup fails closed by default.',
+        'It is safer to refuse operation than to reconcile privileged workflows without guardrails.',
+      ],
+    },
+    {
+      cells: [
+        'Required policy disappears or becomes misbound later',
+        'Sensitive reconciliation paths pause and surface degraded status.',
+        'The admission dependency is part of the runtime safety model as well as startup validation.',
+      ],
+    },
+    {
+      cells: [
+        'Unsafe mode explicitly enabled',
+        'The operator can start without admission dependency enforcement.',
+        'Reserved for development or explicit break-glass scenarios; materially weakens defense in depth.',
+      ],
+    },
+  ]}
+/>
+
+The required fail-closed dependency set includes:
+
+- `openbao-validate-openbaocluster`
+- `openbao-validate-openbao-tenant`
+- `openbao-validate-openbaorestore`
+- `openbao-lock-controller-statefulset-mutations`
+- `openbao-restrict-provisioner-rbac`
+- `openbao-restrict-provisioner-namespace-mutations`
+- `openbao-restrict-provisioner-tenant-governance`
+- `openbao-restrict-controller-rbac`
+- `openbao-restrict-controller-serviceaccounts`
+- `openbao-restrict-controller-secret-writes`
+- `openbao-lock-managed-resource-mutations`
+- `openbao-enforce-managed-image-digests`
+
+<Callout type="warning" title="Unsafe mode is not a production posture">
+
+Disabling admission policies is treated as unsafe mode. Even if the cluster otherwise uses Hardened settings, turning off API-level guardrails weakens the operator’s defense-in-depth model substantially.
+
+</Callout>
+
+## Provisioner guardrails
+
+<DecisionTable
+  kind="reference"
+  title="Provisioner policy goals"
+  columns={['Policy area', 'What it constrains', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'RBAC writes',
+        'Only fixed Role and RoleBinding names, subjects, and allowed verbs are permitted.',
+        'This prevents the provisioner from becoming a generic RBAC minting identity.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Namespace mutation',
+        'Provisioner namespace updates are limited to fixed Pod Security label enforcement and blocked in system namespaces. In external Pod Security label mode, provisioner namespace mutations are denied entirely.',
+        'Tenant onboarding should not become a generic namespace-mutation channel, and platform-owned namespace labels should stay owned by platform policy.',
+      ],
+    },
+    {
+      cells: [
+        'Tenant governance objects',
+        'Only operator-owned `ResourceQuota` and `LimitRange` shapes are allowed for the fixed names.',
+        'Day-0 guardrails should remain centrally shaped and not drift through arbitrary direct edits.',
+      ],
+    },
+  ]}
+/>
+
+## Controller guardrails
+
+<DecisionTable
+  kind="reference"
+  title="Controller policy goals"
+  columns={['Policy area', 'What it constrains', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'RBAC writes',
+        'Only a narrow per-cluster pod-discovery and service-registration role pattern is allowed.',
+        'This blocks RBAC self-escalation inside tenant namespaces.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'ServiceAccount writes',
+        'Only operator-managed main, backup, restore, and upgrade ServiceAccounts are allowed.',
+        'The controller should not become a general-purpose ServiceAccount management identity.',
+      ],
+    },
+    {
+      cells: [
+        'Secret writes',
+        'Only fixed operator-managed Secret names can be created or mutated.',
+        'A broader RBAC grant should not silently become arbitrary tenant Secret mutation.',
+      ],
+    },
+    {
+      cells: [
+        'Managed-resource mutation',
+        'Drift on operator-managed StatefulSets, Services, Pods, and other objects is denied.',
+        'This protects the reconciliation contract and keeps GitOps or manual edits from undermining the lifecycle model.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Admission canary">
+
+The provisioner supports an optional admission canary that submits a dry-run RBAC request which must be denied. This adds evidence that policy enforcement is active, beyond the presence of the policy objects themselves.
+
+</Callout>
+
+## Configuration ownership
+
+Admission policy is one of the reasons the operator can separate user intent from platform-owned configuration:
+
+- user-owned surfaces stay in the CR where customization is supported
+- operator-owned networking, seal, listener identity, and lifecycle wiring stay protected
+- unsafe or drifted changes are rejected before they have to be repaired later
+
+<NextActions
+  title="Continue platform controls"
+  items={[
+    {
+      label: 'RBAC architecture',
+      description: 'How these policies reinforce the split-controller identity model.',
+      docId: 'security/infrastructure/rbac',
+    },
+    {
+      label: 'Network security',
+      description: 'Default-deny network posture that complements admission enforcement.',
+      docId: 'security/infrastructure/network-security',
+    },
+    {
+      label: 'Threat model',
+      description: 'STRIDE threats mitigated by the admission guardrails.',
+      docId: 'security/fundamentals/threat-model',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/infrastructure/index.md b/website/versioned_docs/version-0.3.0/security/infrastructure/index.md
new file mode 100644
index 000000000..94d824207
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/infrastructure/index.md
@@ -0,0 +1,74 @@
+---
+title: Platform Controls
+hide_title: true
+pageType: landing
+journey: security
+description: Infrastructure security controls in OpenBao Operator, including RBAC architecture, validating admission policies, and network security boundaries.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Security / Platform Controls"
+  title="Platform security controls"
+  lede="Kubernetes-level controls such as RBAC, validating admission policies, and network boundaries."
+  actions={[
+    {label: 'Open RBAC architecture', docId: 'security/infrastructure/rbac', variant: 'primary'},
+    {label: 'Review admission policies', docId: 'security/infrastructure/admission-policies', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Scope"
+    items={[
+      'control-plane access review',
+      'unsafe changes rejected before persistence',
+      'tenant and egress network boundaries',
+      'cluster prerequisites for the security model',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Platform control routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'RBAC architecture',
+      description: 'Split-controller model, narrow identities, and mutation-locked access boundaries.',
+      docId: 'security/infrastructure/rbac',
+    },
+    {
+      eyebrow: '02',
+      title: 'Admission policies',
+      description: 'CEL-based guardrails that reject unsafe configurations and pause sensitive reconciliation when enforcement disappears.',
+      docId: 'security/infrastructure/admission-policies',
+    },
+    {
+      eyebrow: '03',
+      title: 'Network security',
+      description: 'Default-deny traffic boundaries and the explicit egress model used for backups, upgrades, and integrations.',
+      docId: 'security/infrastructure/network-security',
+    },
+  ]}
+/>
+
+<Callout type="note" title="Cluster prerequisites">
+
+- Kubernetes `v1.33+` is required by OpenBao Operator. `ValidatingAdmissionPolicy` is GA on all supported versions.
+- A CNI that actually enforces `NetworkPolicy` is required for the network isolation model to be real.
+
+</Callout>
+
+<NextActions
+  items={[
+    {
+      label: 'Open workload protections',
+      description: 'Pod hardening, TLS, and supply-chain controls.',
+      docId: 'security/workload/index',
+    },
+    {
+      label: 'Open tenant isolation',
+      description: 'How platform controls support the multi-tenant security model.',
+      docId: 'security/multi-tenancy/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/infrastructure/network-security.md b/website/versioned_docs/version-0.3.0/security/infrastructure/network-security.md
new file mode 100644
index 000000000..cacd6c183
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/infrastructure/network-security.md
@@ -0,0 +1,248 @@
+---
+title: Network Security
+hide_title: true
+pageType: concept
+journey: security
+description: Default-deny network posture for OpenBao Pods and lifecycle jobs, plus the control-plane and egress assumptions that support it.
+---
+
+<PageHeader
+  title="Network policy model"
+  lede="Default-deny posture for OpenBao Pods and lifecycle jobs, plus the ingress and egress paths the operator expects when cluster management and integrations are configured."
+/>
+
+
+
+<DiagramFrame
+  title="OpenBao network perimeter"
+  caption="The workload path starts closed and only opens the traffic required for cluster management, Raft, ingress, and explicitly configured integrations."
+  code={`flowchart TB
+    Operator["Operator Pod"]
+    K8sAPI["Kubernetes API"]
+    DNS["CoreDNS"]
+    Peer["Raft peers"]
+
+    subgraph Cluster ["OpenBao perimeter (default deny)"]
+        Node["OpenBao Pod"]
+    end
+
+    Ingress["Gateway / trusted ingress peer"] --> Node
+    Operator --> Node
+    Peer --> Node
+    Jobs["Backup / restore Job"] --> Node
+    Node --> K8sAPI
+    Node --> DNS
+    Node --> Peer
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Operator,K8sAPI,DNS,Peer,Ingress read;
+    class Jobs process;
+    class Node write;`}
+/>
+
+<DecisionTable
+  title="Network posture at a glance"
+  columns={['Surface', 'Default posture', 'What opens it up']}
+  rows={[
+    {
+      cells: [
+        'Workload ingress',
+        'Denied by default',
+        'Operator probes, Raft peer traffic, and explicit ingress peers through gateway or configured trusted peers.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Workload egress',
+        'Denied by default except for core cluster dependencies',
+        'API server, DNS, Raft peer traffic, and explicitly configured integrations.',
+      ],
+    },
+    {
+      cells: [
+        'Backup and restore job egress',
+        'Separate from the main workload policy',
+        'Explicit object-storage and identity reachability assumptions through job-level configuration.',
+      ],
+    },
+    {
+      cells: [
+        'Controller ingress',
+        'Restricted to health and metrics surfaces',
+        'Monitoring and kubelet probe paths only when operator network policies are enabled.',
+      ],
+    },
+  ]}
+/>
+
+## Workload traffic rules
+
+<Tabs groupId="platform-controls-network">
+
+<TabItem value="ingress" label="Ingress">
+
+<DecisionTable
+  kind="reference"
+  title="Allowed ingress paths"
+  columns={['Source', 'Typical port', 'Why it exists']}
+  rows={[
+    {
+      cells: [
+        'Operator',
+        '`8200`',
+        'Required for probes, initialization checks, and status-related interactions with the workload.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Raft peers',
+        '`8201/TCP`',
+        'Required for consensus, leader election, and replication between StatefulSet members.',
+      ],
+    },
+    {
+      cells: [
+        'Gateway or trusted ingress peer',
+        '`8200`',
+        'Allowed only when gateway integration or trusted ingress peers are configured deliberately.',
+      ],
+    },
+    {
+      cells: [
+        'Kube-system health paths',
+        'Platform-dependent',
+        'Some CNIs or DNS health checks require controlled access from system namespaces.',
+      ],
+    },
+  ]}
+/>
+
+If you need additional ingress, use:
+
+- `spec.network.ingressRules` for additive peer rules
+- `spec.network.trustedIngressPeers` for user-managed ingress or passthrough proxies
+
+Managed `spec.ingress.enabled: true` configurations must declare at least one trusted ingress peer so the OpenBao API listener is not opened to every pod that can reach the namespace.
+
+<Callout type="note" title="Read replicas are client-serving Pods">
+
+When steady read replicas are enabled, the main client Service can route to both voter and read-replica Pods. That does not create a separate ingress policy surface by itself; the same cluster ingress rules still govern the client listener, and the optional dedicated read Service remains only a second Service object selecting the same client-serving port on the read pool.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="egress" label="Egress">
+
+<DecisionTable
+  kind="reference"
+  title="Allowed egress paths"
+  columns={['Destination', 'Typical port', 'Why it exists']}
+  rows={[
+    {
+      cells: [
+        'Kubernetes API',
+        '`443`',
+        'Required for service registration, status-related interactions, and controlled API assumptions.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'CoreDNS',
+        '`53/TCP+UDP`',
+        'Required to resolve peers and configured external services.',
+      ],
+    },
+    {
+      cells: [
+        'Raft peers',
+        '`8201/TCP`',
+        'Required for replication and cluster membership traffic.',
+      ],
+    },
+    {
+      cells: [
+        'Object storage, KMS, PKI, or other integrations',
+        'Explicitly configured',
+        'These should only open when the corresponding feature is intentionally enabled.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Lifecycle jobs use separate egress assumptions">
+
+Backup and restore do not rely on the main workload policy alone. They use separate job identities and separate network assumptions, which is why `BackupConfigurationReady` and `RestoreConfigurationReady` exist as distinct status signals.
+
+</Callout>
+
+<Callout type="note" title="Steady read replicas are staged out of destructive workflows">
+
+Blue-green promotion and restore intentionally drain the steady read pool before destructive membership or snapshot work starts, then restore it before the workflow completes. That is a network and safety boundary as much as a rollout detail: destructive workflows do not keep a second permanent client-serving non-voter tier online while peer removal or snapshot replacement is in progress.
+
+</Callout>
+
+</TabItem>
+
+</Tabs>
+
+## Status checkpoints for network assumptions
+
+When manifests alone do not explain the observed behavior, start with these conditions:
+
+- `APIServerNetworkReady` for API-server reachability assumptions
+- `GatewayIntegrationReady` for gateway listener and controller compatibility
+- `BackupConfigurationReady` for object-storage and backup auth reachability
+- `RestoreConfigurationReady` for restore job egress and identity assumptions
+
+## Controller network posture
+
+<DecisionTable
+  kind="reference"
+  title="Controller networking"
+  columns={['Surface', 'Posture', 'Why']}
+  rows={[
+    {
+      cells: [
+        'Ingress',
+        'Restricted to metrics and kubelet probes when operator network policies are enabled.',
+        'The controller should not expose a broad incoming network surface.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Egress',
+        'Primarily the Kubernetes API and essential control-plane services.',
+        'Controller traffic should stay close to reconciliation and not behave like a general egress client.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue platform controls"
+  items={[
+    {
+      label: 'Admission policies',
+      description: 'See how unsafe configuration and drift are blocked before they persist.',
+      docId: 'security/infrastructure/admission-policies',
+    },
+    {
+      label: 'RBAC architecture',
+      description: 'Connect network boundaries back to the split-controller identity model.',
+      docId: 'security/infrastructure/rbac',
+    },
+    {
+      label: 'Configure network settings',
+      description: 'Switch to the task page when you are ready to set ingress or egress rules on a real cluster.',
+      docId: 'user-guide/openbaocluster/configuration/network',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/infrastructure/rbac.md b/website/versioned_docs/version-0.3.0/security/infrastructure/rbac.md
new file mode 100644
index 000000000..90a69d430
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/infrastructure/rbac.md
@@ -0,0 +1,256 @@
+---
+title: RBAC Architecture
+hide_title: true
+pageType: concept
+journey: security
+description: How the provisioner and controller identities stay separate, narrow, and mutation-locked across tenant onboarding and workload reconciliation.
+---
+
+<PageHeader
+  title="Split-controller RBAC model"
+  lede="Provisioner and controller identities stay separate. The provisioner introduces tenant access and namespace guardrails, and the controller uses tenant-scoped permissions to manage workloads."
+/>
+
+
+
+<DiagramFrame
+  title="Split-controller RBAC model"
+  caption="The provisioner creates the tenant `Role` and `RoleBinding`, but the binding points at the controller ServiceAccount rather than granting those permissions back to the provisioner."
+  code={`flowchart TB
+    subgraph OperatorNS ["Operator namespace"]
+        Prov["Provisioner ServiceAccount"]
+        Ctrl["Controller ServiceAccount"]
+    end
+
+    subgraph TenantNS ["Tenant namespace"]
+        TenantRole["Tenant Role"]
+        TenantBinding["Tenant RoleBinding"]
+        PodDiscoveryRBAC["Per-cluster pod-discovery Role / RoleBinding"]
+        Workload["StatefulSet / Pods / Services"]
+    end
+
+    subgraph Guardrails ["Admission guardrails"]
+        ProvRBAC["Provisioner RBAC policy"]
+        ProvNS["Provisioner namespace policy"]
+        CtrlRBAC["Controller RBAC policy"]
+        CtrlSA["Controller ServiceAccount policy"]
+        CtrlSecret["Controller Secret-write policy"]
+    end
+
+    Prov --> TenantRole
+    Prov --> TenantBinding
+    TenantBinding -. binds role .-> TenantRole
+    TenantBinding -. binds subject .-> Ctrl
+    Prov -. constrained by .-> ProvRBAC
+    Prov -. constrained by .-> ProvNS
+
+    Ctrl --> Workload
+    Ctrl --> PodDiscoveryRBAC
+    Ctrl -. constrained by .-> CtrlRBAC
+    Ctrl -. constrained by .-> CtrlSA
+    Ctrl -. constrained by .-> CtrlSecret
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Prov,Ctrl process;
+    class TenantRole,TenantBinding,PodDiscoveryRBAC,Workload write;
+    class ProvRBAC,ProvNS,CtrlRBAC,CtrlSA,CtrlSecret read;`}
+/>
+
+<Callout type="note" title="Projected Kubernetes API tokens">
+
+The operator disables default token auto-mounting and uses explicit projected ServiceAccount tokens for Kubernetes API access. Audience pinning can be configured. API identity remains explicit and short-lived through projected tokens.
+
+</Callout>
+
+<DecisionTable
+  title="Identity split at a glance"
+  columns={['Identity', 'Primary job', 'What it must not become']}
+  rows={[
+    {
+      cells: [
+        'Provisioner',
+        'Introduce tenant namespaces, bind tenant-scoped RBAC, and apply day-0 guardrails.',
+        'A long-running identity that can read tenant Secrets or manage tenant workloads.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Controller',
+        'Reconcile `OpenBaoCluster` workloads and day-1/day-2 lifecycle actions inside onboarded namespaces.',
+        'An identity that can discover arbitrary namespaces or rewrite the RBAC that grants its own access.',
+      ],
+    },
+  ]}
+/>
+
+## Provisioner access model
+
+<DecisionTable
+  kind="reference"
+  title="Provisioner scope"
+  columns={['Resource or action', 'Why it exists', 'Why it stays narrow']}
+  rows={[
+    {
+      cells: [
+        'Watch `OpenBaoTenant`',
+        'Tenant onboarding is the trigger for introducing namespace access.',
+        'It is the only cluster-wide watch the provisioner needs for tenant onboarding.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Patch Namespaces for fixed PSS labels in default enforce mode',
+        'Tenant namespaces need a Pod Security baseline unless a platform policy layer already owns it.',
+        'Namespace mutation is limited to the fixed Pod Security label set and blocked in system namespaces. In external mode, Helm removes namespace update/patch RBAC from the provisioner.',
+      ],
+    },
+    {
+      cells: [
+        'Create and patch fixed `Role` and `RoleBinding` objects',
+        'The provisioner must bind the controller into the target namespace.',
+        'Admission policy constrains names, subjects, verbs, and object shapes so this cannot expand into arbitrary RBAC minting.',
+      ],
+    },
+    {
+      cells: [
+        'Create tenant guardrails such as `ResourceQuota` and `LimitRange`',
+        'Day-0 governance belongs to provisioning, not to workload reconciliation.',
+        'The provisioner manages only the operator-owned fixed objects; it does not manage general namespace inventory.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Access grant flow">
+
+The provisioner writes the RBAC that grants the controller access, but it does not receive those tenant permissions itself. That separation is the core security property of the onboarding path.
+
+</Callout>
+
+## Controller access model
+
+<DecisionTable
+  kind="reference"
+  title="Controller scope"
+  columns={['Resource or action', 'Why it exists', 'Why it stays narrow']}
+  rows={[
+    {
+      cells: [
+        'Watch `OpenBaoCluster`',
+        'The controller needs the global CRD event stream to reconcile clusters.',
+        'This does not imply namespace discovery or broad tenant access by itself.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Manage tenant-scoped workload resources',
+        'StatefulSets, Services, ConfigMaps, Jobs, ServiceMonitors, and related resources are the normal lifecycle surface.',
+        'This access only exists where the provisioner already introduced the controller via RoleBinding.',
+      ],
+    },
+    {
+      cells: [
+        'Read and write allowlisted Secrets',
+        'Lifecycle workflows need specific Secret names for bootstrap, TLS, operations, and private-registry image verification.',
+        'Secret access is fixed-name, non-enumerating, and guarded by dedicated admission policy.',
+      ],
+    },
+    {
+      cells: [
+        'Create minimal per-cluster `Role` and `RoleBinding` objects',
+        'Some service-registration and pod-discovery flows need narrow additional RBAC.',
+        'The controller policy only allows a tightly scoped pattern to prevent RBAC self-escalation.',
+      ],
+    },
+    {
+      cells: [
+        'Create operator-managed ServiceAccounts for workload and jobs',
+        'Backup, restore, and upgrade paths need explicit job identities.',
+        'Admission policy constrains names and shapes so the controller cannot mutate unrelated ServiceAccounts.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Controller reconcile waits for the RBAC handoff">
+
+The controller does not treat missing tenant RBAC as a normal write failure anymore. In multi-tenant mode it first checks for the tenant `RoleBinding`, then requeues cleanly until onboarding is complete. That keeps simultaneous `OpenBaoTenant` and `OpenBaoCluster` submissions safe without weakening the split-identity model.
+
+</Callout>
+
+<Callout type="warning" title="PVC contents are outside Kubernetes object RBAC">
+
+Kubernetes RBAC controls who can read or mutate the PVC object; it does not protect files after another workload can mount the volume. Treat audit file storage as sensitive data. Restrict Pod creation, ephemeral containers, `exec`, collector configuration, and node or storage-admin access around any PVC used by `spec.auditFileStorage`.
+
+</Callout>
+
+## What the RBAC model guarantees
+
+<DecisionTable
+  title="Security properties"
+  columns={['Property', 'What it means operationally', 'Primary control']}
+  rows={[
+    {
+      cells: [
+        'No topology discovery',
+        'The controller is not supposed to list namespaces and infer who else exists in the cluster.',
+        'Provisioner-led namespace introduction and narrow cluster-scope reads.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'No Secret enumeration',
+        'Operator identities should not browse tenant Secrets as generic inventory.',
+        'Name-scoped Secret roles and the controller Secret-write policy.',
+      ],
+    },
+    {
+      cells: [
+        'Privilege separation',
+        'The identity that grants access is not the identity that consumes it.',
+        'Split provisioner/controller model plus admission guardrails.',
+      ],
+    },
+    {
+      cells: [
+        'Blind-create, name-scoped mutate',
+        'The operator can create the Secrets it owns without broadening into arbitrary tenant Secret mutation.',
+        'Dedicated Secret roles and fixed-name admission constraints.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Unsafe mode weakens the model">
+
+Installing with admission policies disabled materially weakens the RBAC defense-in-depth story. The split-controller design still matters, but without the admission guardrails a broader or drifted RBAC grant has fewer backstops.
+
+</Callout>
+
+<NextActions
+  title="Continue platform controls"
+  items={[
+    {
+      label: 'Admission policies',
+      description: 'RBAC writes and managed-resource mutations constrained at the API boundary.',
+      docId: 'security/infrastructure/admission-policies',
+    },
+    {
+      label: 'Network security',
+      description: 'Default-deny network posture that complements these identity boundaries.',
+      docId: 'security/infrastructure/network-security',
+    },
+    {
+      label: 'Tenant isolation',
+      description: 'Connect the RBAC model back to the multi-tenant operating guarantees.',
+      docId: 'security/multi-tenancy/tenant-isolation',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/multi-tenancy/index.md b/website/versioned_docs/version-0.3.0/security/multi-tenancy/index.md
new file mode 100644
index 000000000..e6de24040
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/multi-tenancy/index.md
@@ -0,0 +1,84 @@
+---
+title: Tenant Isolation
+hide_title: true
+pageType: landing
+journey: security
+description: Multi-tenancy security model for OpenBao Operator, describing tenant isolation, namespace boundaries, and least-privilege access control.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Security / Tenant Isolation"
+  title="Tenant isolation model"
+  lede="Multi-tenant security model for OpenBao Operator, including namespace introduction, split controller identities, admission guardrails, and network isolation."
+  actions={[
+    {label: 'Open the isolation model', docId: 'security/multi-tenancy/tenant-isolation', variant: 'primary'},
+    {label: 'Review tenant onboarding', docId: 'user-guide/openbaotenant/overview', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Covers"
+    items={[
+      'understand what the multi-tenant operating model actually guarantees',
+      'review the boundary between the provisioner and namespace-restricted controller',
+      'connect tenant isolation to RBAC and network controls',
+      'decide whether the shared-service model fits your production requirements',
+    ]}
+  />
+</PageHero>
+
+<DecisionTable
+  title="Tenant isolation pillars"
+  columns={['Pillar', 'What it protects', 'Primary mechanism']}
+  rows={[
+    {
+      cells: [
+        'Namespace introduction',
+        'Prevents the controller from discovering or managing arbitrary namespaces.',
+        '`OpenBaoTenant` onboarding, explicit RoleBinding introduction, and no namespace-wide controller discovery.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Identity separation',
+        'Keeps provisioning and workload management from sharing a single all-powerful credential.',
+        'Split provisioner and controller identities with different RBAC scopes.',
+      ],
+    },
+    {
+      cells: [
+        'Admission guardrails',
+        'Blocks unsafe configuration drift and unauthorized mutation of managed resources.',
+        'Validating admission policies and managed-resource ownership rules.',
+      ],
+    },
+    {
+      cells: [
+        'Network isolation',
+        'Prevents cross-tenant traffic and over-broad egress by default.',
+        'Default-deny `NetworkPolicy` plus explicit allow rules.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  items={[
+    {
+      label: 'Read the isolation model',
+      description: 'Namespace, RBAC, and secret-boundary behavior.',
+      docId: 'security/multi-tenancy/tenant-isolation',
+    },
+    {
+      label: 'Open RBAC architecture',
+      description: 'How the split-controller model enforces the tenant boundary at the identity layer.',
+      docId: 'security/infrastructure/rbac',
+    },
+    {
+      label: 'Open tenancy and governance',
+      description: 'User-guide onboarding workflow and governance path.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/multi-tenancy/tenant-isolation.md b/website/versioned_docs/version-0.3.0/security/multi-tenancy/tenant-isolation.md
new file mode 100644
index 000000000..1d4560cde
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/multi-tenancy/tenant-isolation.md
@@ -0,0 +1,195 @@
+---
+title: Tenant Isolation
+hide_title: true
+pageType: concept
+journey: security
+description: How namespace introduction, split controller identities, admission policy, and network boundaries combine into the operator's tenant-isolation model.
+---
+
+<PageHeader
+  title="Tenant isolation model"
+  lede="The operator's multi-tenant model depends on deliberate namespace introduction. A tenant namespace becomes manageable only after onboarding introduces the controller through fixed RBAC, applies namespace guardrails, and keeps the identity that grants access separate from the identity that consumes it."
+/>
+
+
+
+<DecisionTable
+  title="Isolation pillars"
+  columns={["Pillar", "What it protects", "Primary mechanism"]}
+  rows={[
+    {
+      cells: [
+        "Namespace introduction",
+        "The controller does not become present in a namespace by accident.",
+        "`OpenBaoTenant` onboarding creates the fixed Role and RoleBinding that introduce the controller deliberately.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Identity separation",
+        "Provisioning and workload management do not share one broad credential.",
+        "The provisioner grants access, while the controller uses tenant-scoped access without minting it.",
+      ],
+    },
+    {
+      cells: [
+        "Admission guardrails",
+        "Unsafe RBAC writes and operator-object drift are blocked at the API boundary.",
+        "Validating admission policies constrain names, subjects, and managed-object mutation patterns.",
+      ],
+    },
+    {
+      cells: [
+        "Network and namespace hardening",
+        "Cross-tenant traffic and insecure sidecar drift are reduced by default.",
+        "Default-deny `NetworkPolicy` applies at onboarding time. Restricted Pod Security labels are applied by the Provisioner unless the chart delegates namespace labels to platform policy.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Tenant introduction flow"
+  caption="The provisioner writes the access grant into the target namespace, but the ongoing controller uses that access without being able to mint or broaden it freely."
+  code={`flowchart TD
+    Request["OpenBaoTenant request"] --> Provisioner["Provisioner"]
+    Provisioner --> Namespace["Target namespace"]
+    Provisioner --> Role["Tenant Role"]
+    Provisioner --> Binding["Tenant RoleBinding"]
+    Provisioner --> Guardrails["Namespace guardrails"]
+    Binding --> Controller["Controller ServiceAccount"]
+    Controller --> Workload["OpenBao workload"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Request,Namespace read;
+    class Provisioner,Controller process;
+    class Role,Binding,Guardrails,Workload write;`}
+/>
+
+## Onboarding models
+
+<DecisionTable
+  title="Choose the governance model"
+  columns={["Model", "Who creates the request", "Primary constraint", "Why you would use it"]}
+  rows={[
+    {
+      cells: [
+        "Self-service",
+        "A namespace admin creates `OpenBaoTenant` inside the same namespace.",
+        "`spec.targetNamespace` must match `metadata.namespace`.",
+        "Use this when teams manage their own namespaces and you want the least central coordination without granting cross-namespace privilege.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Centralized onboarding",
+        "A platform-admin workflow creates the request in the operator namespace.",
+        "Normal tenant users must not be able to write onboarding requests there.",
+        "Use this when quotas, guardrails, or namespace vending are controlled centrally.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Task versus model">
+
+Use <SiteLink docId="user-guide/openbaotenant/onboarding">Onboard the target namespace</SiteLink> when you need the concrete onboarding workflow and field-level configuration.
+
+</Callout>
+
+## What the model guarantees
+
+<DecisionTable
+  kind="reference"
+  title="Operational guarantees"
+  columns={["Guarantee", "What it means", "Primary control"]}
+  rows={[
+    {
+      cells: [
+        "No namespace discovery as a normal workflow",
+        "The controller does not need to list namespaces to find tenants.",
+        "Namespaces are introduced through onboarding rather than through global discovery.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "No cross-tenant Secret browsing",
+        "The controller should not treat tenant Secrets as generic cluster inventory.",
+        "Secret access is name-scoped, role-scoped, and guarded by admission policy.",
+      ],
+    },
+    {
+      cells: [
+        "No all-powerful long-running operator credential",
+        "The component that grants access does not also reconcile every tenant workload with the same credential.",
+        "Provisioner/controller identity split.",
+      ],
+    },
+    {
+      cells: [
+        "Namespace-level runtime baseline",
+        "Tenant namespaces start from Restricted pod-security enforcement and default network isolation.",
+        "Provisioner-owned namespace labels and network-policy defaults, or platform-owned namespace labels when `tenancy.namespacePodSecurityLabels.mode=external` is set.",
+      ],
+    },
+  ]}
+/>
+
+## Assumptions and residual risk
+
+<DecisionTable
+  kind="reference"
+  title="Assumptions you still need to own"
+  columns={["Assumption", "Why it matters", "What to do"]}
+  rows={[
+    {
+      cells: [
+        "Admission stays enabled",
+        "Without it, the RBAC and managed-object model loses an important API-level backstop.",
+        "Treat unsafe mode as a deliberate exception and not as the normal multi-tenant posture.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "The surrounding cluster is trustworthy",
+        "Node compromise, cluster-admin access, or hostile CNI behavior are outside what namespace isolation can solve.",
+        "Pair the operator model with normal cluster hardening, audit, and node-security controls.",
+      ],
+    },
+    {
+      cells: [
+        "Shared external systems are partitioned appropriately",
+        "Object storage, PKI, and KMS systems can still become cross-tenant blast-radius points if configured broadly.",
+        "Separate identities, prefixes, or trust roots per tenant or per environment where required.",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue tenant isolation"
+  items={[
+    {
+      label: "RBAC architecture",
+      description: "See the identity split that makes namespace introduction safe in the first place.",
+      docId: "security/infrastructure/rbac",
+    },
+    {
+      label: "Network security",
+      description: "Review the default-deny network posture that complements the RBAC boundary.",
+      docId: "security/infrastructure/network-security",
+    },
+    {
+      label: "Tenant onboarding",
+      description: "Switch to the user-guide workflow when you need to create or review an `OpenBaoTenant` request.",
+      docId: "user-guide/openbaotenant/onboarding",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/workload/index.md b/website/versioned_docs/version-0.3.0/security/workload/index.md
new file mode 100644
index 000000000..2377e4a4d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/workload/index.md
@@ -0,0 +1,74 @@
+---
+title: Workload Protections
+hide_title: true
+pageType: landing
+journey: security
+description: Workload security guidance for OpenBao Operator covering pod security defaults, TLS protections, and software supply chain verification.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Security / Workload Protections"
+  title="Workload security controls"
+  lede="Pod and container hardening, workload identity and TLS, and image verification."
+  actions={[
+    {label: 'Open pod and runtime security', docId: 'security/workload/workload-security', variant: 'primary'},
+    {label: 'Review TLS and identity', docId: 'security/workload/tls', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Covers"
+    items={[
+      'verify the default pod hardening posture',
+      'understand how server TLS, peer identity, and trust material are managed',
+      'decide how image verification should work in production',
+      'review runtime protections separately from RBAC and admission policy concerns',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Workload protection routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Pod and runtime security',
+      description: 'Pod security context, filesystem, token, and container-hardening defaults.',
+      docId: 'security/workload/workload-security',
+    },
+    {
+      eyebrow: '02',
+      title: 'TLS and identity',
+      description: 'Server TLS, peer trust, certificate management, and workload-facing identity paths.',
+      docId: 'security/workload/tls',
+    },
+    {
+      eyebrow: '03',
+      title: 'Supply-chain verification',
+      description: 'Digest pinning, signature verification, and image-trust guardrails.',
+      docId: 'security/workload/supply-chain',
+    },
+  ]}
+/>
+
+<Callout type="note" title="Default runtime hardening">
+
+OpenBao Pods are expected to run non-root with a read-only root filesystem, dropped Linux capabilities, and a `RuntimeDefault` seccomp profile. The detailed page should explain exceptions and platform dependencies, not re-argue the baseline.
+OpenBao Pods are expected to run non-root with a read-only root filesystem, dropped Linux capabilities, and a `RuntimeDefault` seccomp profile. The detailed page covers exceptions and platform dependencies.
+
+</Callout>
+
+<NextActions
+  items={[
+    {
+      label: 'Open platform controls',
+      description: 'How runtime protections connect to RBAC, admission, and network boundaries.',
+      docId: 'security/infrastructure/index',
+    },
+    {
+      label: 'Review production posture',
+      description: 'Tie workload protections back to the Hardened production contract.',
+      docId: 'security/fundamentals/profiles',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/workload/supply-chain.md b/website/versioned_docs/version-0.3.0/security/workload/supply-chain.md
new file mode 100644
index 000000000..8b161b249
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/workload/supply-chain.md
@@ -0,0 +1,227 @@
+---
+title: Supply-Chain Verification
+hide_title: true
+pageType: concept
+journey: security
+description: Signature verification, transparency-log checks, digest pinning, and release-artifact validation for operator-managed OpenBao images.
+---
+
+<PageHeader
+  title="Supply-chain verification"
+  lede="Signature verification, digest pinning, and separate trust roots for the main OpenBao image and helper images such as init, backup, restore, and upgrade executors."
+/>
+
+
+
+<DiagramFrame
+  title="Verification flow before reconcile"
+  caption="The controller resolves a tag, verifies the signature and optional transparency-log evidence, then writes only the verified digest into managed workloads."
+  code={`flowchart LR
+    Registry["Container registry"] --> Resolve["Resolve tag to digest"]
+    Resolve --> Verify["Verify signature"]
+    Verify --> Rekor["Check Rekor transparency log"]
+    Rekor --> Pin["Pin digest in workload spec"]
+    Pin --> Reconcile["Reconcile StatefulSet or Job"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Registry,Rekor read;
+    class Resolve,Verify process;
+    class Pin,Reconcile write;`}
+/>
+
+<DecisionTable
+  title="Supply-chain controls at a glance"
+  columns={["Control", "What it blocks", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "Signature verification",
+        "Unsigned or improperly signed images.",
+        "Trust material can come from a public key or from keyless identity matching.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Transparency-log verification",
+        "Opaque signing events with no public evidence trail.",
+        "This is on by default and is usually only disabled for disconnected environments.",
+      ],
+    },
+    {
+      cells: [
+        "Digest pinning",
+        "Tag-mutation races between verification time and pull time.",
+        "The controller writes the immutable digest so the kubelet pulls the exact artifact that was verified.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Admission digest enforcement",
+        "Direct API writes that bypass the controller and reintroduce mutable tags.",
+        "This is defense in depth, not a replacement for reconciliation-time verification.",
+      ],
+    },
+  ]}
+/>
+
+## Trust surfaces
+
+<DecisionTable
+  kind="reference"
+  title="What gets verified"
+  columns={["Image surface", "Configuration field", "Why it is separate"]}
+  rows={[
+    {
+      cells: [
+        "Main OpenBao server image",
+        "`spec.imageVerification`",
+        "The application image can have a different signer and release cadence from the operator helper images.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Init, backup, restore, and upgrade images",
+        "`spec.operatorImageVerification`",
+        "Helper images are published by the operator project and often need their own trust policy.",
+      ],
+    },
+    {
+      cells: [
+        "Helm chart and release artifacts",
+        "Out-of-cluster verification",
+        "These should be verified during installation and upgrade planning even though the controller does not reconcile them in-cluster.",
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Trust-source choices"
+  columns={["Path", "Use it when", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "Keyless identity matching",
+        "You consume official project images and want issuer-plus-subject verification without maintaining your own public key distribution.",
+        "Custom registries and forks should set explicit trust material rather than relying on official-image defaults.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Public-key verification",
+        "Your organization signs images with its own key or needs an offline verification path.",
+        "Rotate the public key deliberately and make sure the key distribution path is auditable.",
+      ],
+    },
+    {
+      cells: [
+        "Warning-only rollout",
+        "You are onboarding verification in a non-production environment and need visibility before enforcing block behavior.",
+        "This should be a transition state, not the final production posture.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Failure behavior
+
+<DecisionTable
+  title="Verification failure policy"
+  columns={["Policy", "Controller behavior", "When to use it"]}
+  rows={[
+    {
+      cells: [
+        "Block",
+        "Stops reconciliation for the managed workload and records the failure in status.",
+        "Use this for production. If you do not trust the artifact, do not roll it out.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Warn",
+        "Records and logs the verification failure but continues with the original image reference.",
+        "Use this only while you are standing up signing infrastructure or testing policy adoption.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Hardened profile expectations">
+
+The Hardened profile is opinionated here. The intent is that image verification stays on, mutable-tag rollouts are not the norm, and official-image defaults are only used when the operator can still tie trust back to the expected signer identity.
+
+</Callout>
+
+## Verify published release artifacts
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable verification for both workload image surfaces"
+  code={`spec:
+  imageVerification:
+    enabled: true
+    failurePolicy: Block
+    imagePullSecrets:
+      - name: cluster-registry-creds
+  operatorImageVerification:
+    enabled: true
+    failurePolicy: Block
+    imagePullSecrets:
+      - name: cluster-registry-creds`}
+>
+  Treat the main OpenBao image and operator helper images as separate trust surfaces. They may share policy, but they should not share assumptions blindly.
+</CommandBlock>
+
+<Callout type="note" title="Private-registry verification needs controller Secret read">
+
+Verification pull Secrets are read by the controller, not by the kubelet. In multi-tenant mode, the provisioner keeps that access name-scoped by granting `get` only on the tenant Secrets referenced from enabled `spec.imageVerification.imagePullSecrets` and `spec.operatorImageVerification.imagePullSecrets`.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify a published operator image outside the cluster"
+  code={`IMAGE="ghcr.io/dc-tec/openbao-operator@sha256:<digest>"
+
+cosign verify \\
+  --new-bundle-format=true \\
+  --certificate-identity "https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/X.Y.Z" \\
+  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \\
+  "\${IMAGE}"`}
+>
+  Use the matching tag or release metadata for the version you are about to deploy, and verify by digest rather than by mutable tag.
+</CommandBlock>
+
+<NextActions
+  title="Continue workload protections"
+  items={[
+    {
+      label: "TLS and identity",
+      description: "Connect artifact trust back to the workload trust path that presents the service to clients.",
+      docId: "security/workload/tls",
+    },
+    {
+      label: "Production posture",
+      description: "See how the Hardened profile treats verification and warning-only modes.",
+      docId: "security/fundamentals/profiles",
+    },
+    {
+      label: "Air-gapped and private registries",
+      description: "Switch to the configuration guide when you need the operational path for disconnected environments.",
+      docId: "user-guide/openbaocluster/configuration/air-gapped",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/workload/tls.md b/website/versioned_docs/version-0.3.0/security/workload/tls.md
new file mode 100644
index 000000000..9d35c8109
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/workload/tls.md
@@ -0,0 +1,196 @@
+---
+title: TLS and Workload Identity
+hide_title: true
+pageType: concept
+journey: security
+description: How peer trust, certificate rotation, and workload-facing TLS identity work across operator-managed, external, and ACME-backed deployments.
+---
+
+<PageHeader
+  title="TLS and workload identity"
+  lede="How pods trust each other, how clients verify the service, where certificate authority material lives, and how each TLS mode changes workload identity and certificate handling."
+/>
+
+
+
+<DecisionTable
+  title="Choose the TLS mode deliberately"
+  columns={["Mode", "Use it when", "What the operator owns", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "External",
+        "You already have a trusted PKI, cert-manager, or platform certificate workflow.",
+        "The operator consumes existing Secrets and watches for rotation, but does not mint the trust chain.",
+        "This is the preferred Hardened production path because CA authority stays outside the operator.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "ACME",
+        "The service is exposed publicly and OpenBao should obtain certificates directly from an ACME provider.",
+        "The operator wires the listener path, but OpenBao handles the certificate lifecycle itself.",
+        "This works best when the service owns the public endpoint and you can meet the ACME challenge requirements.",
+      ],
+    },
+    {
+      cells: [
+        "OperatorManaged",
+        "You need a fast internal evaluation path or temporary development certificates.",
+        "The operator generates and rotates the CA and leaf certificates inside the cluster.",
+        "This is not the Hardened production posture because the operator holds certificate authority material.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Certificate rotation and reload path"
+  caption="When the certificate source changes, the operator updates the mounted material and the workload reloads it without rebuilding or reinstalling the cluster."
+  code={`sequenceDiagram
+    participant Source as Certificate source
+    participant Operator as Operator
+    participant Secret as Kubernetes Secret
+    participant Pod as OpenBao Pod
+
+    Source->>Operator: New certificate or renewal event
+    Operator->>Secret: Update mounted TLS material
+    Secret->>Pod: Projected volume refresh
+    Pod->>Pod: Reload listener configuration
+
+    Note over Pod: New certificate becomes active without a full cluster redeploy`}
+/>
+
+## Trust paths that matter
+
+<DecisionTable
+  kind="reference"
+  title="TLS surfaces"
+  columns={["Path", "What is being protected", "Primary concern"]}
+  rows={[
+    {
+      cells: [
+        "Client to service",
+        "Application and operator clients verifying the OpenBao listener.",
+        "The public or internal certificate presented by the service must chain to a trust source your clients already accept.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Pod to pod",
+        "Raft and internal service traffic between OpenBao members.",
+        "The SAN set and CA distribution need to match pod and service DNS accurately so peers can authenticate each other.",
+      ],
+    },
+    {
+      cells: [
+        "Edge proxy to backend",
+        "Gateway, ingress, or mesh traffic between the edge and the cluster.",
+        "Choose passthrough versus termination deliberately so you know where the private key lives and where client identity is enforced.",
+      ],
+    },
+  ]}
+/>
+
+## Where key material lives
+
+<DecisionTable
+  kind="reference"
+  title="Key and CA ownership"
+  columns={["Mode", "Server private key", "CA or trust root", "Operational consequence"]}
+  rows={[
+    {
+      cells: [
+        "External",
+        "Kubernetes Secret supplied by your PKI workflow",
+        "External CA or organizational PKI",
+        "Certificate lifecycle aligns with the rest of your platform and is easier to audit centrally.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "ACME",
+        "Generated inside OpenBao",
+        "Public ACME issuer",
+        "The operator never needs the private key, but the cluster must satisfy the ACME issuance path.",
+      ],
+    },
+    {
+      cells: [
+        "OperatorManaged",
+        "Kubernetes Secret managed by the operator",
+        "Operator-generated internal CA",
+        "Fast to stand up, but the trust root now lives inside the same management plane you are trying to keep small and reviewable.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Exposure guidance
+
+<DecisionTable
+  title="Edge exposure choices"
+  columns={["Pattern", "Use it when", "Why it is preferred or risky"]}
+  rows={[
+    {
+      cells: [
+        "TLS passthrough",
+        "You want OpenBao to terminate TLS and preserve end-to-end certificate identity.",
+        "This is usually the cleanest production path because the application keeps control of the server certificate and the edge stays as a transport router.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Edge termination",
+        "You need policy enforcement, client-auth handling, or platform certificate lifecycle at the edge.",
+        "This can be valid, but you must be explicit about how trust is re-established between the proxy and OpenBao.",
+      ],
+    },
+    {
+      cells: [
+        "Temporary self-signed or operator-generated edge trust",
+        "Short-lived evaluation environments only.",
+        "This path is easy to start but tends to leak into production unless you set a deliberate migration plan.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Callout type="note" title="Configuration ownership">
+
+Use the configuration guides below when you need the exact cluster fields:
+
+- <SiteLink docId="user-guide/openbaocluster/configuration/external-access">External access</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/configuration/gateway-api">Gateway API support</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/configuration/network">Network configuration</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/configuration/unseal">Unseal configuration</SiteLink>
+
+</Callout>
+
+<NextActions
+  title="Continue workload protections"
+  items={[
+    {
+      label: "Supply-chain verification",
+      description: "Review how the operator verifies and pins the images behind these workloads.",
+      docId: "security/workload/supply-chain",
+    },
+    {
+      label: "Production posture",
+      description: "See how TLS mode choice feeds into the Hardened security profile.",
+      docId: "security/fundamentals/profiles",
+    },
+    {
+      label: "External access",
+      description: "Switch to the task page when you need the concrete service and gateway configuration.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/security/workload/workload-security.md b/website/versioned_docs/version-0.3.0/security/workload/workload-security.md
new file mode 100644
index 000000000..27d7d8ea4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/security/workload/workload-security.md
@@ -0,0 +1,276 @@
+---
+title: Pod and Runtime Security
+hide_title: true
+pageType: concept
+journey: security
+description: Pod hardening, projected-token handling, and runtime guardrails for operator-managed OpenBao workloads and lifecycle Jobs.
+---
+
+<PageHeader
+  title="Keep OpenBao Pods inside the restricted runtime baseline from the first reconcile."
+  lede="The operator assumes runtime hardening is the default, not an optional add-on. OpenBao Pods, init containers, and transient lifecycle Jobs are expected to run non-root, use explicit writable volumes, and consume only the identities and Linux privileges they actually need."
+/>
+
+
+
+<DecisionTable
+  title="Runtime protections at a glance"
+  columns={["Control", "Default posture", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Non-root execution",
+        "OpenBao Pods and helper containers run with `runAsNonRoot` and a stable UID/GID baseline on standard Kubernetes.",
+        "This narrows the blast radius of container breakout attempts and keeps the workload aligned with the Restricted Pod Security Standard.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Read-only root filesystem",
+        "The root filesystem is immutable and mutable paths are mounted explicitly.",
+        "The workload cannot silently write arbitrary state into the container image layer.",
+      ],
+    },
+    {
+      cells: [
+        "Explicit audit file storage",
+        "File audit devices write only to the configured audit storage mount when `spec.auditFileStorage` is used.",
+        "Audit records stay on a known writable surface that can be collected and reviewed separately from the container filesystem.",
+      ],
+    },
+    {
+      cells: [
+        "Dropped Linux capabilities and seccomp",
+        "Capabilities are dropped and `RuntimeDefault` seccomp applies by default.",
+        "The process keeps only the syscall and privilege surface needed to run the service.",
+      ],
+    },
+    {
+      cells: [
+        "Explicit projected Kubernetes token",
+        "The pod does not rely on default token automounting and uses a projected token only where the workload needs Kubernetes API access.",
+        "This keeps API identity explicit, short-lived, and absent from containers that do not need it.",
+      ],
+    },
+    {
+      cells: [
+        "Job resource guardrails",
+        "Backup and restore Jobs run with explicit resource requests and limits.",
+        "A lifecycle job should not starve the steady-state OpenBao Pods or neighboring workloads on the same node.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Runtime boundary inside an operator-managed Pod"
+  caption="Mutable state, API identity, and rendered configuration are each introduced through explicit mounts instead of through an implicitly writable container image."
+  code={`flowchart LR
+    Controller["Controller"] --> StatefulSet["StatefulSet template"]
+    StatefulSet --> Init["Config init container"]
+    StatefulSet --> Bao["OpenBao container"]
+    StatefulSet --> Volumes["Writable volumes"]
+    StatefulSet --> Token["Projected API token"]
+    StatefulSet --> Config["Rendered config.hcl"]
+
+    Init --> Config
+    Bao --> Volumes
+    Bao --> Token
+    Bao --> Config
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+
+    class Controller,StatefulSet process;
+    class Init,Token,Config read;
+    class Bao,Volumes write;`}
+/>
+
+## Pod hardening baseline
+
+<DecisionTable
+  kind="reference"
+  title="Baseline pod controls"
+  columns={["Surface", "Expected setting", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "User and group",
+        "Non-root by default on standard Kubernetes; OpenShift may assign UID/GID through SCC.",
+        "Hardened clusters may use `spec.securityContext` for safe non-root or OpenShift-compatible overrides only.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Filesystem",
+        "Read-only root filesystem with explicit writable mounts for data, logs, and temporary paths.",
+        "If a plugin or sidecar needs extra write paths, treat that as a deliberate exception to review.",
+      ],
+    },
+    {
+      cells: [
+        "Privilege escalation",
+        "`allowPrivilegeEscalation: false` with dropped capabilities.",
+        "Setuid or unexpected ambient privileges should not become a recovery crutch.",
+      ],
+    },
+    {
+      cells: [
+        "Seccomp",
+        "`RuntimeDefault`.",
+        "If your platform cannot support this baseline, resolve the platform issue rather than weakening the cluster silently.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Hardened security context overrides">
+
+The Hardened profile rejects pod-level `spec.securityContext` overrides that weaken runtime guarantees. Do not set
+`runAsNonRoot: false`, root UID/GID values, root supplemental groups, `seccompProfile.type: Unconfined`, pod sysctls,
+or Windows pod security options for Hardened OpenBao clusters.
+
+</Callout>
+
+<Callout type="note" title="Init container behavior">
+
+The config-rendering init container inherits the same pod-level hardening contract and does not receive a Kubernetes API token mount by default. Its job is to render dynamic configuration such as Pod IP and hostname into `config.hcl`, not to act as a privileged bootstrap helper.
+
+</Callout>
+
+## Audit file storage mount
+
+When `spec.auditFileStorage` is configured, the operator mounts one RWX PVC into
+each OpenBao Pod and isolates each Pod with a pod-specific `subPathExpr`. The
+default path is `/openbao/audit`; file audit devices must write under the
+effective mount path.
+
+<DecisionTable
+  kind="reference"
+  title="Audit mount security checks"
+  columns={["Check", "Expected posture", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Writable identity",
+        "The storage provider honors `fsGroup` or the existing claim is pre-owned for the OpenBao runtime identity.",
+        "OpenBao cannot enable the file audit device if the mounted directory is not writable by the Pod security context.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Read-only collection",
+        "Collectors mount the audit PVC read-only.",
+        "The collector path ships records onward instead of becoming another writer that can alter audit history.",
+      ],
+    },
+    {
+      cells: [
+        "Runtime hardening",
+        "Keep the OpenBao root filesystem read-only and avoid hostPath exceptions for audit collection.",
+        "Audit storage is a deliberate writable path; do not broaden it into general host or node access.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Storage permissions are part of the security boundary">
+
+On standard Kubernetes, OpenBao Pods run as UID `100` and GID `1000` with `fsGroup: 1000`. On OpenShift, SCCs may assign IDs dynamically. Verify the RWX provider and any pre-created PVCs make the audit directory writable for the effective runtime identity before enabling the file audit device.
+
+</Callout>
+
+## Identity and token exposure
+
+<DecisionTable
+  kind="reference"
+  title="Where runtime identity exists"
+  columns={["Path", "How it works", "Why it stays narrow"]}
+  rows={[
+    {
+      cells: [
+        "OpenBao Pod token",
+        "A projected ServiceAccount token is mounted only where the OpenBao container needs Kubernetes API access for peer discovery and service registration.",
+        "The pod does not inherit a default automounted token, so identity is explicit rather than ambient.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Init container",
+        "No default token mount.",
+        "Rendering config is not a reason to grant Kubernetes API identity.",
+      ],
+    },
+    {
+      cells: [
+        "Backup, restore, and upgrade Jobs",
+        "Each workflow uses its own operator-managed ServiceAccount and projected token path.",
+        "Lifecycle Jobs should not reuse the long-running workload identity or borrow permissions accidentally.",
+      ],
+    },
+  ]}
+/>
+
+## Namespace and job guardrails
+
+<DecisionTable
+  kind="reference"
+  title="Controls around the workload"
+  columns={["Control", "What it does", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Tenant namespace PSS labels",
+        "Provisioned namespaces are labeled for Restricted Pod Security enforcement, audit, and warning by the Provisioner unless namespace label ownership is delegated to platform policy.",
+        "Insecure sidecars or helper workloads should fail at the namespace boundary rather than weakening the cluster quietly; external mode keeps that baseline as a platform responsibility.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Job resource defaults",
+        "Backup and restore Jobs have explicit CPU and memory requests and limits.",
+        "Operational workflows remain bounded and do not become an easy noisy-neighbor path.",
+      ],
+    },
+    {
+      cells: [
+        "Operator-owned writable paths",
+        "Mutable state is confined to PVCs, temporary volumes, and generated files the operator expects.",
+        "The runtime contract stays reviewable because writes happen on known surfaces.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Avoid runtime exceptions as a convenience">
+
+If a deployment needs extra host access, extra capabilities, or a writable root filesystem, treat that as a security design change. In practice it usually means the surrounding platform integration should be fixed instead of weakening the OpenBao workload contract.
+
+</Callout>
+
+<NextActions
+  title="Continue workload protections"
+  items={[
+    {
+      label: "TLS and identity",
+      description: "Review how peer trust, certificate rotation, and edge exposure build on top of this runtime baseline.",
+      docId: "security/workload/tls",
+    },
+    {
+      label: "Supply-chain verification",
+      description: "See how the operator decides which images it will trust before these Pods ever start.",
+      docId: "security/workload/supply-chain",
+    },
+    {
+      label: "Tenant isolation",
+      description: "Connect namespace hardening back to the shared-service isolation model.",
+      docId: "security/multi-tenancy/tenant-isolation",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/index.mdx b/website/versioned_docs/version-0.3.0/user-guide/index.mdx
new file mode 100644
index 000000000..2bca90e74
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/index.mdx
@@ -0,0 +1,87 @@
+---
+title: Get Started
+slug: /get-started
+hide_title: true
+pageType: landing
+journey: get-started
+description: Choose a deployment model, install OpenBao Operator, onboard the target namespace, create your first cluster, and leave with a clear day 2 plan.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Get Started"
+  title="Get started with OpenBao Operator"
+  lede="Choose a deployment model, install the operator, onboard the target namespace, and create a first cluster."
+  actions={[
+    {label: 'Choose a deployment model', docId: 'user-guide/operator/deployment-decision-guide', variant: 'primary'},
+    {label: 'Jump to installation', docId: 'user-guide/operator/installation', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Finish this journey with"
+    items={[
+      'the right tenancy and namespace model',
+      'a repeatable install path and the right target namespace onboarding step',
+      'a first cluster shape that will not trap later decisions',
+      'a clear next move into backups, upgrades, and exposure',
+    ]}
+  />
+</PageHero>
+
+<JourneyRail
+  current={1}
+  title="Follow this path in order"
+  items={[
+    {
+      label: 'Choose a deployment model',
+      description: 'Decide tenancy mode, security profile, TLS posture, and install method.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Use Helm or manifests with the right namespace, identity, and admission model.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, introduce the namespace through OpenBaoTenant as part of cluster onboarding.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Apply a starting profile that matches local evaluation or hardened production.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Move into production checklist items, upgrades, backups, and exposure.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Supporting decisions"
+  items={[
+    {
+      label: 'Single-tenant mode',
+      description: 'Use this path when one team directly owns one namespace and intentionally bypasses the default tenant onboarding step.',
+      docId: 'user-guide/operator/single-tenant-mode',
+    },
+    {
+      label: 'Tenancy & governance',
+      description: 'Review OpenBaoTenant namespace introduction, default guardrails, and shared-operator boundaries.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+    {
+      label: 'Operator identity and access',
+      description: 'Review the rendered controller identity, JWT audience, and OpenBao-side bindings when you customize the install.',
+      docId: 'user-guide/operator/identity-and-access',
+    },
+    {
+      label: 'Validated deployments',
+      description: 'Start from a tested architecture, recipe, or runbook when you want a known-good baseline.',
+      docId: 'user-guide/validated-deployments/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/air-gapped.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/air-gapped.md
new file mode 100644
index 000000000..2d72ef015
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/air-gapped.md
@@ -0,0 +1,214 @@
+---
+title: Air-Gapped and Private Registries
+hide_title: true
+pageType: task
+journey: configure
+description: Mirror operator, workload, and helper images; set repository defaults; and wire pull secrets for disconnected or private-registry environments.
+---
+
+<PageHeader
+  title="Air-gapped and private-registry image planning"
+  lede="An air-gapped or private-registry deployment involves operator, workload, and helper executor images. Use this page to make those image defaults explicit and wire pull access for disconnected or private-registry environments."
+/>
+
+
+
+<DecisionTable
+  title="Plan every image surface explicitly"
+  columns={["Surface", "Defaults from", "Override it here", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "Operator controller and provisioner images",
+        "The Helm chart image values used during installation.",
+        "Set `image.repository`, `image.tag`, and install-level `imagePullSecrets` on the chart.",
+        "In multi-tenant mode, both controller and provisioner deployments must be able to pull from the mirrored registry.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Default OpenBao workload image",
+        "The cluster version plus the `RELATED_IMAGE_OPENBAO` repository default.",
+        "Set the repository default on the operator install or set `spec.image` per cluster.",
+        "If `spec.image` is omitted, the operator still derives the final image from `spec.version` and the mirrored repository default.",
+      ],
+    },
+    {
+      cells: [
+        "Helper executor images",
+        "The `OPERATOR_INIT_IMAGE_REPOSITORY`, `OPERATOR_BACKUP_IMAGE_REPOSITORY`, and `OPERATOR_UPGRADE_IMAGE_REPOSITORY` defaults.",
+        "Set install-wide defaults or override `spec.initContainer.image`, `spec.backup.image`, and `spec.upgrade.image` per cluster.",
+        "Restore jobs use their own image surface in the restore workflow and should be reviewed there before a DR event.",
+      ],
+    },
+    {
+      cells: [
+        "Registry authentication",
+        "The operator install uses chart-level `imagePullSecrets`; each cluster uses `spec.imagePullSecrets`. Image verification uses its own `imagePullSecrets` fields.",
+        "Create Docker registry Secrets in the namespace that will pull the images.",
+        "Do not assume the operator namespace and tenant namespaces can share pull secrets implicitly. If verification must contact a private registry, the controller also needs read access to the named tenant Secret.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Set install-wide defaults
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Install the operator with mirrored image defaults"
+  code={`image:
+  repository: my-registry.corp/openbao-operator
+  tag: "<operator-version>"
+imagePullSecrets:
+  - name: operator-registry-creds
+
+controller:
+  extraEnv:
+    - name: RELATED_IMAGE_OPENBAO
+      value: "my-registry.corp/openbao/openbao"
+    - name: OPERATOR_INIT_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-init"
+    - name: OPERATOR_BACKUP_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-backup"
+    - name: OPERATOR_UPGRADE_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-upgrade"
+
+provisioner:
+  extraEnv:
+    - name: RELATED_IMAGE_OPENBAO
+      value: "my-registry.corp/openbao/openbao"
+    - name: OPERATOR_INIT_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-init"
+    - name: OPERATOR_BACKUP_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-backup"
+    - name: OPERATOR_UPGRADE_IMAGE_REPOSITORY
+      value: "my-registry.corp/openbao-upgrade"`}
+>
+  In multi-tenant mode, keep the controller and provisioner defaults aligned so both reconciler paths resolve helper images from the same mirrored repositories.
+</CommandBlock>
+
+<Callout type="note" title="Pin one published operator version across every mirrored image surface">
+
+Use the same released operator version for the controller, provisioner, init, backup, and upgrade images. For example, once `0.1.0` is published, mirror and pin `0.1.0` consistently instead of mixing tags or treating `next` as an artifact reference.
+
+</Callout>
+
+<Callout type="note" title="Use install defaults and cluster overrides together">
+
+Install-wide defaults provide the baseline image contract. Use cluster-level overrides when a specific `OpenBaoCluster` needs a different tag, mirror, or promotion cadence.
+
+</Callout>
+
+## Override images per cluster
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Override mirrored workload images per cluster"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+  namespace: openbao
+spec:
+  version: "2.5.0"
+  image: "my-registry.corp/openbao/openbao:2.5.0"
+  imagePullSecrets:
+    - name: cluster-registry-creds
+  imageVerification:
+    enabled: true
+    imagePullSecrets:
+      - name: cluster-registry-creds
+  operatorImageVerification:
+    enabled: true
+    imagePullSecrets:
+      - name: cluster-registry-creds
+  initContainer:
+    image: "my-registry.corp/openbao-init:<operator-version>"
+  backup:
+    image: "my-registry.corp/openbao-backup:<operator-version>"
+  upgrade:
+    image: "my-registry.corp/openbao-upgrade:<operator-version>"`}
+>
+  Set explicit per-cluster images when the registry path or promotion cadence differs from the install-wide defaults. Otherwise, let the operator derive them from the mirrored repositories and the requested version.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the pull secret in the tenant namespace"
+  code={`kubectl create secret docker-registry cluster-registry-creds \\
+  --namespace openbao \\
+  --docker-server=my-registry.corp \\
+  --docker-username=<user> \\
+  --docker-password=<password>`}
+>
+  The Secret must exist in the same namespace as the OpenBaoCluster that references it.
+</CommandBlock>
+
+<Callout type="note" title="Separate kubelet pulls from verification pulls">
+
+`spec.imagePullSecrets` lets Kubernetes pull the rendered Pods and Jobs. `spec.imageVerification.imagePullSecrets` and `spec.operatorImageVerification.imagePullSecrets` let the controller authenticate to the registry while resolving and verifying signatures. In multi-tenant mode, the provisioner grants the controller `get` only on those named tenant Secrets.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Disconnected-environment checks"
+  columns={["Check", "Expected state", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Every runtime image is mirrored",
+        "Operator, OpenBao, init, backup, and upgrade images exist in the internal registry before install or rollout.",
+        "Disconnected operation requires every runtime image to be mirrored, not only the main OpenBao image.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Pull secrets exist in every runtime namespace",
+        "The operator namespace and every tenant namespace that runs workloads have the correct registry credential Secret.",
+        "Install success and workload reconcile success are separate checks. Tenant namespaces still need the correct pull secret.",
+      ],
+    },
+    {
+      cells: [
+        "Version and tag promotion is explicit",
+        "Image tags and repository mirrors are tracked as part of the release process.",
+        "Disconnected environments require explicit tag promotion records because drift is harder to detect later.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="tip" title="Keep image verification and registry strategy separate in your head">
+
+Use this guide to understand where images come from and how they are pulled. Signature verification, digest pinning, and trust roots are handled in the supply-chain security model, not by the mirror configuration alone.
+
+</Callout>
+
+<NextActions
+  title="Related platform-readiness work"
+  items={[
+    {
+      label: "Supply-chain verification",
+      description: "Verify mirrored images deliberately instead of assuming an internal registry alone makes them trustworthy.",
+      docId: "security/workload/supply-chain",
+    },
+    {
+      label: "Server configuration",
+      description: "Return to the cluster baseline when plugin images, audit devices, or runtime settings also need to be declared.",
+      docId: "user-guide/openbaocluster/configuration/server",
+    },
+    {
+      label: "Restore from backup",
+      description: "Review restore-job image and auth assumptions before a real incident forces you to discover them under pressure.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/external-access.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/external-access.md
new file mode 100644
index 000000000..71ecc6590
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/external-access.md
@@ -0,0 +1,253 @@
+---
+title: External Access
+slug: /configure/external-access
+hide_title: true
+pageType: task
+journey: configure
+description: Choose how clients reach OpenBao, decide where TLS terminates, and map that choice to Gateway API, Ingress, or direct service exposure.
+---
+
+<PageHeader
+  title="Choose an external access path"
+  lede="OpenBao can be exposed through Gateway API, Ingress, or a direct L4 Service. Use this page to choose where TLS terminates, who owns certificate lifecycle, and how each edge path fits the intended operating posture."
+/>
+
+
+
+<DecisionTable
+  title="Choose the access path deliberately"
+  columns={["Path", "Use it when", "What the operator creates", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "Gateway API",
+        "You want the strongest long-term edge model, clearer multi-tenancy, and first-class passthrough support.",
+        "Routes and supporting integration objects for the configured mode.",
+        "Controller feature support still matters, especially for `TLSRoute` and `BackendTLSPolicy`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Ingress",
+        "You already have an ingress controller path and only need standard Kubernetes ingress semantics.",
+        "An `Ingress` resource targeting the public OpenBao Service.",
+        "This is usually a termination-oriented model and is less expressive than Gateway API for shared-platform routing.",
+      ],
+    },
+    {
+      cells: [
+        "Direct Service exposure",
+        "You want the simplest L4 path, often through a cloud load balancer or private network boundary.",
+        "A `LoadBalancer` or `NodePort`-style Service configuration.",
+        "You own more of the perimeter behavior yourself and lose the richer route-level policy surface.",
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Where TLS should terminate"
+  columns={["Pattern", "Use it when", "Why it fits or does not fit"]}
+  rows={[
+    {
+      cells: [
+        "Passthrough",
+        "You want OpenBao to remain the TLS endpoint and preserve end-to-end certificate identity.",
+        "This is the cleanest production default because the application keeps control of the server certificate and private key usage.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Edge termination with backend TLS",
+        "You need HTTP-aware controls, policy enforcement, or centralized certificate handling at the edge.",
+        "This is valid, but you must be explicit about how trust is re-established between the edge and OpenBao.",
+      ],
+    },
+    {
+      cells: [
+        "Temporary operator-managed trust",
+        "You are standing up a development or internal evaluation environment quickly.",
+        "This fits development and internal evaluation paths. Use `External` or `ACME` for the Hardened production baseline.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Exposure paths"
+  caption="The service boundary is a choice between where traffic enters, where TLS terminates, and how much of the edge behavior the operator is expected to own."
+  code={`flowchart LR
+    Client["Client"] --> Edge["Gateway / Ingress / L4 LB"]
+    Edge --> OpenBao["OpenBao client Service"]
+    OpenBao --> Pods["Voter and optional read-replica Pods"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client read;
+    class Edge process;
+    class OpenBao,Pods write;`}
+/>
+
+<Callout type="note" title="The default client endpoint is shared">
+
+When steady read replicas are enabled, the operator keeps the main external endpoint attached to the shared client Service. That Service can fan out to both voter and read-replica Pods, relying on OpenBao to serve read-only requests locally and forward write requests to the active leader.
+
+The dedicated read-replica Service remains available for explicit consumers, but the operator does not create a second Gateway or Ingress route for it automatically. Keep the primary hostname as the default client path, and treat the dedicated read Service as an opt-in endpoint for workloads that should land only on the steady read pool.
+
+</Callout>
+
+## Representative configurations
+
+<Tabs groupId="external-access-gateway-ingress-service">
+  <TabItem value="gateway" label="Gateway API">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Expose OpenBao through Gateway API"
+  code={`spec:
+  gateway:
+    enabled: true
+    tlsPassthrough: true
+    hostname: bao.example.com
+    gatewayRef:
+      name: main-gateway
+      namespace: gateway-system`}
+>
+  Start here when Gateway API is your edge standard. For most production clusters, use TLS passthrough unless you have a specific need for termination at the Gateway.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="ingress" label="Ingress">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Expose OpenBao with a standard Ingress"
+  code={`spec:
+  ingress:
+    enabled: true
+    host: "bao.example.com"
+    annotations:
+      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
+  network:
+    trustedIngressPeers:
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: ingress-nginx`}
+>
+  Use this when you already operate an ingress-controller standard and do not need the richer Gateway API route model. Declare the ingress-controller peer so the operator-managed NetworkPolicy can keep OpenBao API ingress source-scoped.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="service" label="Service">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Expose OpenBao directly through an L4 Service"
+  code={`spec:
+  service:
+    type: LoadBalancer
+    annotations:
+      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`}
+>
+  Use this when you want the simplest network boundary and your platform already treats a load balancer or private network edge as the primary perimeter.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+## Match the TLS mode to the exposure path
+
+<DecisionTable
+  kind="reference"
+  title="TLS mode pairings"
+  columns={["TLS mode", "Good exposure fit", "Why"]}
+  rows={[
+    {
+      cells: [
+        "External",
+        "Gateway passthrough, Ingress re-encryption, or direct Service exposure",
+        "This keeps CA ownership outside the operator and works cleanly with both internal and externally terminated edges.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "ACME",
+        "Gateway passthrough or direct public exposure",
+        "OpenBao must remain the TLS endpoint to complete ACME challenge and certificate lifecycle correctly.",
+      ],
+    },
+    {
+      cells: [
+        "OperatorManaged",
+        "Development or internal evaluation paths only",
+        "This keeps startup simple, but it also makes the operator the certificate authority. Use `External` or `ACME` for the Hardened production baseline.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## External TLS Secret contract
+
+<Callout type="note" title="What `tls.mode: External` actually expects">
+
+For the cluster-facing TLS path, the operator reads fixed same-namespace Secret names:
+
+- `<cluster-name>-tls-ca` with key `ca.crt`
+- `<cluster-name>-tls-server` with keys `tls.crt` and `tls.key`
+
+The server certificate must chain to the CA bundle and cover the internal service name `openbao-cluster-<cluster-name>.local`, plus any configured ingress hostname, gateway hostname, and `spec.tls.extraSANs`.
+
+</Callout>
+
+<Callout type="tip" title="Do not confuse edge TLS Secrets with the cluster server TLS Secrets">
+
+`spec.ingress.tlsSecretName` only controls the Secret referenced by the managed Ingress resource. It does not rename the Secrets that the OpenBao Pods use for their own listener certificate and CA trust.
+
+</Callout>
+
+<Callout type="note" title="Traefik v3 backend trust">
+
+If you use Traefik v3 with backend TLS validation, configure a `ServersTransport` that trusts the generated CA Secret for the cluster. This is an implementation detail of the ingress path, not a reason to change the underlying TLS model.
+
+</Callout>
+
+<NextActions
+  title="Continue service boundary setup"
+  items={[
+    {
+      label: "Gateway API support",
+      description: "Use the detailed Gateway API page when Gateway is the primary edge path.",
+      docId: "user-guide/openbaocluster/configuration/gateway-api",
+    },
+    {
+      label: "Read replicas",
+      description: "See the steady-state read-pool contract, status conditions, and day-2 lifecycle before exposing a dedicated read Service.",
+      docId: "user-guide/openbaocluster/configuration/read-replicas",
+    },
+    {
+      label: "Network configuration",
+      description: "Align ingress peers, DNS, API-server egress, and external service egress with the exposure path you chose.",
+      docId: "user-guide/openbaocluster/configuration/network",
+    },
+    {
+      label: "Unseal configuration",
+      description: "Use the exact Secret and mounted-file contract page when external TLS and unseal credentials both depend on the same trust workflow.",
+      docId: "user-guide/openbaocluster/configuration/unseal",
+    },
+    {
+      label: "TLS and workload identity",
+      description: "Go deeper on certificate ownership and trust boundaries when you need the security model behind these choices.",
+      docId: "security/workload/tls",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/gateway-api.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/gateway-api.md
new file mode 100644
index 000000000..c54dac7c1
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/gateway-api.md
@@ -0,0 +1,239 @@
+---
+title: Gateway API Support
+hide_title: true
+pageType: task
+journey: configure
+description: Configure Gateway API as the primary edge path for OpenBao, including passthrough versus termination, readiness checks, and controller compatibility.
+---
+
+<PageHeader
+  title="Gateway API integration"
+  lede="Gateway API is the recommended edge model for explicit route ownership, listener mode, and cross-namespace attachment. For most production deployments, start with TLS passthrough so OpenBao remains the TLS endpoint."
+/>
+
+<Callout type="note" title="Use the Gateway API Standard channel">
+
+The operator emits Gateway API `v1` resources for `HTTPRoute`, `TLSRoute`, and `BackendTLSPolicy`. Install a Gateway API Standard bundle that serves those versions, such as Gateway API `v1.5.1` or newer. Treat the experimental bundle as a reference-only deviation for clusters that intentionally depend on experimental Gateway API resources outside the operator-managed surface.
+
+</Callout>
+
+<DecisionTable
+  title="Choose the Gateway mode"
+  columns={["Mode", "Use it when", "What the operator creates", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "TLS passthrough",
+        "You want OpenBao to remain the TLS endpoint and keep end-to-end certificate identity.",
+        "`TLSRoute`-based integration that forwards encrypted traffic to the cluster.",
+        "Your controller and GatewayClass need usable `TLSRoute` support, and ACME depends on this model.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "TLS termination",
+        "You need HTTP-aware policy, WAF behavior, or centralized certificate handling at the Gateway.",
+        "`HTTPRoute` plus optional `BackendTLSPolicy` for re-encrypted traffic to OpenBao.",
+        "Be explicit about backend trust and do not assume termination alone preserves the same trust model.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Gateway API modes"
+  caption="Passthrough keeps OpenBao as the TLS endpoint. Termination shifts certificate presentation to the Gateway and then re-establishes trust on the backend hop."
+  code={`flowchart TB
+    subgraph Pass ["TLS passthrough"]
+      ClientA["Client"] --> GatewayA["Gateway"]
+      GatewayA --> BaoA["OpenBao"]
+    end
+
+    subgraph Term ["TLS termination"]
+      ClientB["Client"] --> GatewayB["Gateway"]
+      GatewayB --> Policy["BackendTLSPolicy"]
+      Policy --> BaoB["OpenBao"]
+    end
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class ClientA,ClientB read;
+    class GatewayA,GatewayB,Policy process;
+    class BaoA,BaoB write;`}
+/>
+
+## Recommended path: TLS passthrough
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Expose OpenBao through a passthrough Gateway listener"
+  code={`spec:
+  gateway:
+    enabled: true
+    tlsPassthrough: true
+    hostname: bao.example.com
+    gatewayRef:
+      name: main-gateway
+      namespace: gateway-system`}
+>
+  This is the default production recommendation because OpenBao remains the TLS endpoint. It fits the trust model used by External TLS and ACME particularly well.
+</CommandBlock>
+
+<ExpandableCallout type="example" title="Example Gateway listener for passthrough">
+
+<CommandBlock
+  language="yaml"
+  label="inspect"
+  title="Gateway listener with `TLS` passthrough"
+  code={`apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: main-gateway
+  namespace: gateway-system
+spec:
+  gatewayClassName: traefik
+  listeners:
+    - name: websecure-passthrough
+      port: 443
+      protocol: TLS
+      tls:
+        mode: Passthrough`}
+/>
+
+</ExpandableCallout>
+
+<Callout type="warning" title="ACME requires passthrough">
+
+If `tls.mode` is `ACME`, do not terminate TLS at the Gateway. OpenBao must remain the TLS endpoint to complete the ACME lifecycle correctly.
+
+</Callout>
+
+## Alternative path: Gateway-side termination
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Expose OpenBao with Gateway termination"
+  code={`spec:
+  gateway:
+    enabled: true
+    hostname: bao.example.com
+    gatewayRef:
+      name: main-gateway
+      namespace: gateway-system`}
+>
+  Use Gateway-side termination when you need HTTP-aware policy, WAF behavior, or centralized certificate handling. In that model the operator can create a `BackendTLSPolicy` so the backend hop stays encrypted and validated.
+</CommandBlock>
+
+<ExpandableCallout type="note" title="What the operator adds for backend TLS">
+
+When backend TLS is enabled, the operator creates a `BackendTLSPolicy` that pins backend validation to the cluster's CA ConfigMap and expected service hostname.
+
+</ExpandableCallout>
+
+## Compatibility and readiness
+
+<DecisionTable
+  kind="reference"
+  title="What must be true"
+  columns={["Check", "Why it matters", "What to confirm"]}
+  rows={[
+    {
+      cells: [
+        "Gateway reference exists",
+        "The operator cannot integrate with a missing or mistyped target.",
+        "The referenced `Gateway` object is present in the namespace you point to.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "GatewayClass exists and is accepted",
+        "A route works only when the controller owning the GatewayClass is present and healthy.",
+        "The selected `GatewayClass` exists and reports acceptance.",
+      ],
+    },
+    {
+      cells: [
+        "Required feature support exists",
+        "Passthrough needs `TLSRoute`; termination may need `BackendTLSPolicy` support.",
+        "If the controller publishes `status.supportedFeatures`, verify the required features are present.",
+      ],
+    },
+    {
+      cells: [
+        "Listener mode matches the chosen path",
+        "A passthrough route attached to a terminating listener will never behave correctly.",
+        "The selected listener protocol and mode are compatible with the route type the operator is going to create.",
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Conditions to watch"
+  columns={["Condition", "What it means", "Typical next move"]}
+  rows={[
+    {
+      cells: [
+        "`GatewayIntegrationReady=True`",
+        "The operator verified the Gateway reference, class, listener path, and available controller support well enough for the chosen mode.",
+        "Continue with end-to-end validation and client connectivity checks.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`GatewayIntegrationReady=Unknown`",
+        "The controller has not published enough status, or feature support cannot be verified from the available information.",
+        "Wait for more Gateway status or inspect whether the controller publishes supported features at all.",
+      ],
+    },
+    {
+      cells: [
+        "`GatewayIntegrationReady=False`",
+        "The operator found a concrete incompatibility or missing dependency.",
+        "Read the condition reason first: missing reference, unsupported feature, incompatible listener, or not-programmed gateway are the common cases.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Blue-green upgrades keep the route stable">
+
+During blue-green cutover, the operator keeps the Gateway route attached to the stable external Service and updates the Service selector behind it. When steady read replicas are enabled, that same external Service can fan out to both voter and read-replica Pods during normal operation, relying on OpenBao to serve reads locally and forward writes to the active leader. During blue-green cutover the selector is temporarily narrowed to the active voter revision, so the route object stays steady while the selected backend set changes underneath.
+
+The operator does not create a second Gateway route for the dedicated read-replica Service yet. If you need an explicit read-only hostname, keep that as a separate edge concern for now.
+
+</Callout>
+
+<NextActions
+  title="Continue service boundary setup"
+  items={[
+    {
+      label: "Network configuration",
+      description: "Align trusted ingress peers and external dependency egress with the Gateway path you just chose.",
+      docId: "user-guide/openbaocluster/configuration/network",
+    },
+    {
+      label: "Read replicas",
+      description: "Review the shared client endpoint and optional dedicated read Service before exposing the cluster through a Gateway.",
+      docId: "user-guide/openbaocluster/configuration/read-replicas",
+    },
+    {
+      label: "External access",
+      description: "Switch back to the broader exposure decision page if you still need to compare Gateway with Ingress or direct Service exposure.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      label: "TLS and workload identity",
+      description: "Review the underlying TLS ownership model when deciding between passthrough and termination.",
+      docId: "security/workload/tls",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/index.mdx b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/index.mdx
new file mode 100644
index 000000000..12bb7acef
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/index.mdx
@@ -0,0 +1,102 @@
+---
+title: Configure
+slug: /configure
+hide_title: true
+pageType: landing
+journey: configure
+description: Configure OpenBaoCluster profiles, bootstrap behavior, storage, exposure, networking, and observability for a repeatable service baseline.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Configure"
+  title="Cluster configuration"
+  lede="OpenBaoCluster profile, bootstrap model, exposure pattern, storage, networking, and observability defaults that define the cluster baseline."
+  actions={[
+    {label: 'Open cluster overview', docId: 'user-guide/openbaocluster/overview', variant: 'primary'},
+    {label: 'Review security profiles', docId: 'user-guide/openbaocluster/configuration/security-profiles', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="A cluster baseline includes"
+    items={[
+      'the right security profile for the environment',
+      'bootstrap and server settings you can explain and repeat',
+      'storage, network, and external access choices that match the service boundary',
+      'observability and recovery dependencies wired for day 2 operations',
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Configure routes"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Read this first',
+      description: 'Start with the OpenBaoCluster contract so the rest of the section reads as cluster design rather than isolated field settings.',
+      docId: 'user-guide/openbaocluster/overview',
+    },
+    {
+      eyebrow: '02',
+      title: 'Cluster baseline',
+      description: 'Choose the security profile, bootstrap model, and server defaults you want to keep operating long term.',
+      docId: 'user-guide/openbaocluster/configuration/security-profiles',
+    },
+    {
+      eyebrow: '03',
+      title: 'Unseal and trust',
+      description: 'Choose the unseal root of trust and use the exact Secret and mounted-file contract the operator validates.',
+      docId: 'user-guide/openbaocluster/configuration/unseal',
+    },
+    {
+      eyebrow: '04',
+      title: 'Service boundary',
+      description: 'Define how traffic reaches the service, how the network is constrained, and which edge integration owns the exposed path.',
+      docId: 'user-guide/openbaocluster/configuration/external-access',
+    },
+    {
+      eyebrow: '05',
+      title: 'Read scaling',
+      description: 'Add a steady-state read-replica pool when you need a second workload tier, explicit read offload, or separate read-pool storage and placement.',
+      docId: 'user-guide/openbaocluster/configuration/read-replicas',
+    },
+    {
+      eyebrow: '06',
+      title: 'Platform readiness',
+      description: 'Set storage, observability, and environment-specific constraints such as private registries early in the cluster design.',
+      docId: 'user-guide/openbaocluster/configuration/resources-storage',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related decisions"
+  items={[
+    {
+      label: 'Prepare for day 2',
+      description: 'Move from first-cluster setup into upgrades, backups, and production checklist work.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+    {
+      label: 'Open Operate',
+      description: 'Use the operating guides for upgrades, backups, maintenance, and recovery once the cluster is live.',
+      docId: 'user-guide/openbaocluster/operations/index',
+    },
+    {
+      label: 'Open Security',
+      description: 'Review the security model, workload protections, and tenant boundaries that back these configuration choices.',
+      docId: 'security/index',
+    },
+    {
+      label: 'Configure unseal',
+      description: 'Open the exact Secret and credentials contract when the next step is choosing or validating the unseal trust path.',
+      docId: 'user-guide/openbaocluster/configuration/unseal',
+    },
+    {
+      label: 'Start from a validated deployment',
+      description: 'Use a tested architecture or recipe when you want a validated baseline instead of assembling the topology yourself.',
+      docId: 'user-guide/validated-deployments/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/network.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/network.md
new file mode 100644
index 000000000..5a20eadb0
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/network.md
@@ -0,0 +1,289 @@
+---
+title: Network Configuration
+hide_title: true
+pageType: task
+journey: configure
+description: Configure the operator-managed NetworkPolicy contract, including DNS, Kubernetes API egress, trusted ingress peers, and external dependency paths for backups and restore.
+---
+
+<PageHeader
+  title="Network policy and traffic contracts"
+  lede="The operator starts from a deny-by-default posture and then adds the ingress and egress paths the cluster needs to function. Use this page to configure DNS, Kubernetes API access, edge peers, and external dependency traffic for backup and restore workflows."
+/>
+
+
+
+<DiagramFrame
+  title="Default network posture"
+  caption="The namespace starts from deny-by-default, then allows the operator, peer traffic, DNS, Kubernetes API access, and whichever external systems you configure deliberately."
+  code={`flowchart TB
+    subgraph External ["External systems"]
+        Edge["Gateway / ingress"]
+        Storage["Backup or restore storage"]
+        Transit["Transit / KMS / PKI"]
+    end
+
+    subgraph Cluster ["Kubernetes cluster"]
+        API["Kubernetes API"]
+        DNS["DNS"]
+        Operator["Operator"]
+        Bao["OpenBao Pods"]
+        Jobs["Backup / restore Jobs"]
+    end
+
+    Edge --> Bao
+    Operator --> Bao
+    Bao --> Bao
+    Bao --> DNS
+    Bao --> API
+    Jobs --> DNS
+    Jobs --> Storage
+    Bao --> Transit
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class API,DNS,Storage,Transit read;
+    class Operator,Edge process;
+    class Bao,Jobs write;`}
+/>
+
+<DecisionTable
+  title="Traffic the operator expects by default"
+  columns={["Direction", "Path", "Why it exists"]}
+  rows={[
+    {
+      cells: [
+        "Ingress",
+        "Operator to OpenBao on the service listener",
+        "Health checks, initialization, unseal coordination, and lifecycle orchestration all depend on this control-plane path.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Ingress",
+        "OpenBao peer-to-peer traffic",
+        "Raft members need to exchange cluster traffic on the peer port.",
+      ],
+    },
+    {
+      cells: [
+        "Egress",
+        "DNS and Kubernetes API",
+        "Pods and Jobs need name resolution and selected Kubernetes API access under strict policy.",
+      ],
+    },
+    {
+      cells: [
+        "Conditional ingress or egress",
+        "Gateway, ingress-controller, storage, transit, or PKI paths",
+        "These are environment-specific and should be configured explicitly rather than allowed broadly.",
+      ],
+    },
+  ]}
+/>
+
+## DNS and Kubernetes API egress
+
+<DecisionTable
+  kind="reference"
+  title="Core network settings"
+  columns={["Field", "Use it for", "When it matters"]}
+  rows={[
+    {
+      cells: [
+        "`network.dnsNamespace`",
+        "Tell the operator where your DNS service actually runs.",
+        "Use this when the cluster DNS namespace is not `kube-system`, such as on OpenShift.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`network.dnsEndpointIPs`",
+        "Allow direct DNS egress to resolver IPs instead of only to pod-backed Services.",
+        "Use this for node-local caches or host-networked DNS topologies where service-based rules are insufficient.",
+      ],
+    },
+    {
+      cells: [
+        "`network.apiServerCIDR`",
+        "Override the default service-VIP allow-list for Kubernetes API access.",
+        "Use this when you know the exact API-service CIDR you want to allow.",
+      ],
+    },
+    {
+      cells: [
+        "`network.apiServerEndpointIPs`",
+        "Allow egress directly to backing API-server endpoint IPs.",
+        "Use this when your CNI evaluates policy post-DNAT and the service VIP alone is not enough.",
+      ],
+    },
+  ]}
+/>
+
+<Tabs groupId="configure-network-core">
+  <TabItem value="dns" label="DNS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure DNS for non-default or node-local resolver paths"
+  code={`spec:
+  network:
+    dnsNamespace: "openshift-dns"
+    dnsEndpointIPs:
+      - "169.254.20.10"`}
+>
+  Set `dnsEndpointIPs` when the resolver is enforced by IP rather than by Service-backed pod traffic. This setting also applies to backup and restore Jobs.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="api" label="Kubernetes API">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Pin Kubernetes API egress explicitly when needed"
+  code={`spec:
+  network:
+    apiServerCIDR: "10.43.0.1/32"
+    apiServerEndpointIPs:
+      - "192.168.166.2"`}
+>
+  Prefer the smallest safe scope. Endpoint IPs are usually only needed when the NetworkPolicy implementation evaluates the post-DNAT destination instead of the service VIP.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+## Add the environment-specific paths
+
+<Tabs groupId="configure-network-extra-paths">
+  <TabItem value="trusted-ingress" label="Trusted ingress peers">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Allow an ingress controller or Gateway data plane to reach the cluster"
+  code={`spec:
+  network:
+    trustedIngressPeers:
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: traefik
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: ingress-system
+        podSelector:
+          matchLabels:
+            app.kubernetes.io/name: traefik`}
+>
+  Use this when the source is a user-managed ingress controller or Gateway data plane. It is usually clearer than writing a raw `ingressRules` block for the same case. Managed `spec.ingress.enabled: true` configurations require at least one trusted ingress peer.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="egress" label="External egress">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Allow egress to transit, storage, or other external systems"
+  code={`spec:
+  network:
+    egressRules:
+      - to:
+          - namespaceSelector:
+              matchLabels:
+                kubernetes.io/metadata.name: openbao-infra
+        ports:
+          - protocol: TCP
+            port: 8200
+      - to:
+          - ipBlock:
+              cidr: 192.168.100.0/24
+        ports:
+          - protocol: TCP
+            port: 443`}
+>
+  Use this for transit unseal, object storage, private PKI, or any other external dependency that should not be reachable through a broad allow-all rule.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="ingress" label="Raw ingress rules">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Add a raw ingress rule when you need full control"
+  code={`spec:
+  network:
+    ingressRules:
+      - from:
+          - namespaceSelector:
+              matchLabels:
+                kubernetes.io/metadata.name: monitoring
+        ports:
+          - protocol: TCP
+            port: 8200`}
+>
+  Reach for raw `ingressRules` when the source is not a normal ingress-controller path and you need exact port or peer matching.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+## Read the operator conditions
+
+<DecisionTable
+  kind="reference"
+  title="Conditions that matter"
+  columns={["Condition", "What it tells you", "Typical next move"]}
+  rows={[
+    {
+      cells: [
+        "`APIServerNetworkReady=False`",
+        "The operator could not build a safe Kubernetes API allow-list.",
+        "Fix the API CIDR or endpoint IP configuration first.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`APIServerNetworkReady=Unknown`",
+        "The service-VIP path exists, but your environment may still need explicit endpoint IPs.",
+        "Check whether your CNI enforces egress post-DNAT and add `apiServerEndpointIPs` if required.",
+      ],
+    },
+    {
+      cells: [
+        "`BackupConfigurationReady=False` or `RestoreConfigurationReady=False` with `NetworkEgressRulesRequired`",
+        "The lifecycle Jobs cannot reach the storage target safely under current policy.",
+        "Add explicit storage egress rules before relying on backup or restore workflows.",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue service boundary setup"
+  items={[
+    {
+      label: "Gateway API support",
+      description: "Use the detailed Gateway API guide when that is the primary edge model.",
+      docId: "user-guide/openbaocluster/configuration/gateway-api",
+    },
+    {
+      label: "Backup operations",
+      description: "Review the object-storage and job-identity path that depends on these network rules.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "Network security",
+      description: "Go deeper on the security model behind the deny-by-default posture and namespace isolation.",
+      docId: "security/infrastructure/network-security",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/observability.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/observability.md
new file mode 100644
index 000000000..2922d10db
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/observability.md
@@ -0,0 +1,440 @@
+---
+title: Observability
+hide_title: true
+pageType: task
+journey: configure
+description: Configure operator metrics, cluster telemetry, dashboards, alerts, and logs for routine operations and incident response.
+---
+
+<PageHeader
+  title="Observability for operator and workload"
+  lede="OpenBao Operator has two observability layers: the operator control plane itself, and the OpenBao workload it renders. Use this page to wire both layers into your monitoring stack, choose the scrape model your platform already supports, and focus on the signals that matter for upgrades, backups, and recovery."
+/>
+
+
+
+<DecisionTable
+  title="Observe the right surface"
+  columns={["Surface", "Configure it through", "Use it for", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "Operator metrics",
+        "Helm or Kustomize settings on the operator installation",
+        "Controller and provisioner reconcile health, errors, and platform-level backup or upgrade counters.",
+        "The endpoint is HTTPS and RBAC-protected. Your scraper needs both network reachability and permission to GET `/metrics`.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "OpenBao workload telemetry",
+        "The `spec.observability.metrics` block on each `OpenBaoCluster`, plus optional `spec.telemetry` overrides.",
+        "Application-level metrics from the OpenBao Pods themselves.",
+        "Configure this separately from operator metrics. Enabling one layer does not configure the other.",
+      ],
+    },
+    {
+      cells: [
+        "OpenBao audit logs",
+        "`spec.audit` plus `spec.auditFileStorage`, then a collector that reads the audit PVC.",
+        "Security and compliance event trails from the OpenBao audit device.",
+        "Audit records are sensitive. The PVC is a handoff buffer, not the final retention boundary.",
+      ],
+    },
+    {
+      cells: [
+        "Logs and health probes",
+        "Operator install values such as log level and health probe settings.",
+        "Fast incident triage when the issue is not obvious from metrics alone.",
+        "Use debug logging intentionally and temporarily, then return to the normal log level.",
+      ],
+    },
+    {
+      cells: [
+        "Dashboards and alerts",
+        "Grafana assets under `config/grafana/` and your own Prometheus or Alertmanager rules.",
+        "A small, repeatable operator cockpit for upgrades, backups, and cluster readiness.",
+        "Use dashboards for context and alerts for time-sensitive failures.",
+      ],
+    },
+  ]}
+/>
+
+## Wire operator metrics
+
+<Tabs groupId="operator-observability-prometheus-vmagent-plain">
+  <TabItem value="prometheus-operator" label="Prometheus Operator">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable operator metrics with ServiceMonitor resources"
+  code={`metrics:
+  enabled: true
+  rbac:
+    enabled: true
+    subjects:
+      - name: prometheus-k8s
+        namespace: monitoring
+  serviceMonitor:
+    enabled: true
+    namespace: monitoring
+    interval: 30s
+    scrapeTimeout: 10s
+    tlsConfig:
+      insecureSkipVerify: true`}
+>
+  This is the cleanest path when Prometheus Operator is already your cluster standard. It creates ServiceMonitors for the controller and, in multi-tenant mode, the provisioner metrics Services.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="victoria-metrics" label="VictoriaMetrics Operator">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable operator metrics with VMServiceScrape resources"
+  code={`metrics:
+  enabled: true
+  rbac:
+    enabled: true
+    subjects:
+      - name: vmagent
+        namespace: monitoring
+  victoriaMetrics:
+    enabled: true
+    namespace: monitoring
+    interval: 30s
+    scrapeTimeout: 10s
+    tlsConfig:
+      insecureSkipVerify: true`}
+>
+  Use this when VictoriaMetrics is your standard scrape controller. The same HTTPS and RBAC constraints still apply to the metrics endpoint.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="plain-prometheus" label="Plain Prometheus">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Scrape the operator metrics services directly"
+  code={`scrape_configs:
+  - job_name: openbao-operator-controller
+    scheme: https
+    metrics_path: /metrics
+    bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+    tls_config:
+      insecure_skip_verify: true
+    static_configs:
+      - targets:
+          - <controller-metrics-service>.<operator-namespace>.svc:8443
+
+  - job_name: openbao-operator-provisioner
+    scheme: https
+    metrics_path: /metrics
+    bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+    tls_config:
+      insecure_skip_verify: true
+    static_configs:
+      - targets:
+          - <provisioner-metrics-service>.<operator-namespace>.svc:8443`}
+>
+  Use this path when you do not run a scrape operator. Keep the ServiceAccount permission to GET `/metrics` and the TLS assumptions explicit.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+<Callout type="note" title="Network policy still applies to scrapers">
+
+If operator network policy is enabled, the monitoring namespace must carry the labels expected by `networkPolicy.metricsAllowedNamespaceLabels` so the scraper can actually reach the HTTPS metrics service.
+
+</Callout>
+
+## Enable OpenBao workload telemetry deliberately
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Turn on workload telemetry for an OpenBaoCluster"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  observability:
+    metrics:
+      enabled: true
+      serviceMonitor:
+        enabled: true
+        interval: "30s"
+        scrapeTimeout: "10s"`}
+>
+  This enables the OpenBao telemetry stanza with safe defaults and creates an active-node metrics Service plus a Prometheus Operator ServiceMonitor when that is the scrape model you use. Reach for `spec.telemetry` when you need lower-level OpenBao telemetry tuning.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure authenticated workload scraping"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  observability:
+    metrics:
+      enabled: true
+      serviceMonitor:
+        enabled: true
+        interval: "30s"
+        scrapeTimeout: "10s"
+        labels:
+          release: kube-prometheus-stack
+        authorization:
+          credentialsSecret:
+            name: openbao-metrics-token
+            key: token
+        tlsConfig:
+          serverName: prod-cluster-metrics.openbao.svc
+          caConfigMap:
+            name: prod-cluster-metrics-ca
+            key: ca.crt`}
+>
+  Use this shape for production Prometheus Operator scraping. The Secret should contain a scoped OpenBao token that can read `sys/metrics`, and the CA reference should validate the OpenBao serving certificate.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Scrape every OpenBao node through a metrics-only listener"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  observability:
+    metrics:
+      enabled: true
+      scrapeProfile: AllNodes
+      metricsOnlyListener:
+        port: 8202
+        unauthenticatedMetricsAccess: true
+      serviceMonitor:
+        enabled: true
+        labels:
+          release: kube-prometheus-stack`}
+>
+  Use this profile when you need standby-node and per-node Raft visibility. The operator renders a dedicated metrics listener, a headless metrics Service, and ServiceMonitor relabeling for the pod and node names.
+</CommandBlock>
+
+The default `Active` scrape profile targets the active OpenBao pod on the API
+listener using `/v1/sys/metrics?format=prometheus`. The `AllNodes` profile
+targets every OpenBao pod through the metrics-only listener. Keep the metrics
+Service reachable only from your monitoring namespace with NetworkPolicy when
+unauthenticated metrics access is enabled.
+
+## Collect OpenBao audit logs
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Write audit records to a collector handoff PVC"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  auditFileStorage:
+    mode: ExistingPVC
+    existingClaimName: prod-cluster-audit-rwx
+  audit:
+    - type: file
+      path: file
+      description: "File audit log for collection"
+      fileOptions:
+        file_path: "/openbao/audit/audit.jsonl"
+        format: "json"`}
+>
+  Use this when a log collector such as Alloy should read OpenBao audit records from a shared filesystem. Each OpenBao Pod writes beneath its own PVC subdirectory while the rendered file path inside the Pod stays stable.
+</CommandBlock>
+
+Mount the audit PVC read-only into the collector and ship records to the log
+system that owns search, retention, and compliance controls. The
+[OpenBao Observability Reference Architecture](https://github.com/dc-tec/openbao-observability)
+shows the intended companion pattern for Alloy, Loki, and Grafana assets.
+
+<DecisionTable
+  kind="reference"
+  title="Audit collection boundaries"
+  columns={["Boundary", "Recommendation", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "OpenBao Pods",
+        "Write only to paths under `spec.auditFileStorage.mountPath`.",
+        "The operator validates file audit paths so records land on the mounted audit PVC instead of the read-only container filesystem.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Collector",
+        "Mount the audit PVC read-only and scope the collector to the cluster namespace.",
+        "Audit records can contain sensitive request metadata and must not become writable from the collection path.",
+      ],
+    },
+    {
+      cells: [
+        "Archive",
+        "Move records from the handoff PVC to external retention-controlled storage.",
+        "PVC storage is useful for buffering and replay, but it is not a tamper-proof compliance archive.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Audit files are sensitive logs">
+
+Restrict who can create Pods that mount the audit PVC, who can `exec` into OpenBao or collector Pods, and who can administer the backing storage. Kubernetes RBAC on the PVC object does not protect file contents once another workload can mount the volume.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Promote a small set of signals first"
+  columns={["Concern", "What to watch", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Availability",
+        "`openbao_cluster_ready_replicas` and cluster conditions such as `Available` or `Degraded`",
+        "This tells you whether the cluster is serving traffic rather than only whether Pods exist.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Steady read pool",
+        "`openbao_cluster_read_replicas_desired`, `_ready`, `_registered`, `_healthy`, plus read-replica conditions such as `ReadServingAvailable` and `ReadReplicasAutopilotHealthy`",
+        "This tells you whether the steady read tier exists, has actually joined, and is still healthy enough for the topology you placed it in.",
+      ],
+    },
+    {
+      cells: [
+        "Backup freshness",
+        "`openbao_backup_last_success_timestamp`, `openbao_backup_consecutive_failures`, and the backup status conditions",
+        "These signals show whether the snapshots you plan to restore are current and successful.",
+      ],
+    },
+    {
+      cells: [
+        "Upgrade safety",
+        "`openbao_upgrade_in_progress`, `openbao_upgrade_failure_total`, and rollback counters",
+        "These signals distinguish orchestrated upgrade activity from normal steady state.",
+      ],
+    },
+    {
+      cells: [
+        "Controller health",
+        "`openbao_reconcile_errors_total` and sustained reconcile duration spikes",
+        "This exposes control-plane failures before they become cluster-wide drift or stalled operations.",
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Start with focused alert rules"
+  code={`apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: openbao-operator-alerts
+spec:
+  groups:
+    - name: openbao-operator
+      rules:
+        - alert: OpenBaoClusterDown
+          expr: openbao_cluster_ready_replicas == 0
+          for: 1m
+        - alert: OpenBaoBackupStale
+          expr: time() - openbao_backup_last_success_timestamp > 86400
+          for: 15m
+        - alert: OpenBaoReadReplicaPoolDegraded
+          expr: openbao_cluster_read_replicas_desired > openbao_cluster_read_replicas_healthy
+          for: 10m
+        - alert: OpenBaoReadReplicaPoolNotRegistered
+          expr: openbao_cluster_read_replicas_desired > openbao_cluster_read_replicas_registered
+          for: 10m
+        - alert: OpenBaoReconcileErrors
+          expr: rate(openbao_reconcile_errors_total[5m]) > 0.1
+          for: 10m`}
+>
+  Keep the first alert set small. Availability, backup freshness, sustained read-pool degradation, and sustained reconcile failure are the highest-value starting signals.
+</CommandBlock>
+
+<Callout type="note" title="Alert rules are not operator-managed">
+
+The OpenBaoCluster controller manages the workload `ServiceMonitor` when `spec.observability.metrics` enables it. `PrometheusRule` resources are user-applied observability objects, so the ServiceAccount or GitOps controller applying the alert rules needs `monitoring.coreos.com` `prometheusrules` permissions in that namespace.
+
+</Callout>
+
+## Dashboards, logs, and health
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Install the bundled Grafana dashboards"
+  code={`kubectl apply -k config/grafana -n monitoring`}
+>
+  The per-feature dashboards under `config/grafana/dashboards/` are the better starting point. The old monolithic dashboard still exists, but it is no longer the recommended default.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Raise log detail temporarily during investigation"
+  code={`controller:
+  extraArgs:
+    - --zap-log-level=debug
+    - --zap-stacktrace-level=error`}
+>
+  Use debug logging only long enough to capture the behavior you need. Reset to the normal log level once the incident or rollout check is complete.
+</CommandBlock>
+
+<Callout type="tip" title="Keep operator metrics and workload telemetry separate in your dashboards">
+
+Build dashboards that show both surfaces together and still make it obvious whether a failure is in the operator control plane or in the OpenBao workload itself.
+
+</Callout>
+
+<Callout type="note" title="The overview dashboard now includes the steady read pool">
+
+`config/grafana/dashboards/overview.json` now shows desired, ready, registered, and Autopilot-healthy read-replica counts next to the existing cluster-level signals. Use that view for the first operational pass, then build more topology-specific dashboards if your placement strategy needs them.
+
+</Callout>
+
+<NextActions
+  title="Keep the operational loop tight"
+  items={[
+    {
+      label: "Configure backups",
+      description: "Configure backup telemetry before restore depends on it.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "Plan upgrades",
+      description: "Use upgrade metrics and rollback signals to make rollout behavior observable before the first version change.",
+      docId: "user-guide/openbaocluster/operations/upgrades",
+    },
+    {
+      label: "Troubleshoot the cluster",
+      description: "Move from baseline telemetry into symptom-driven incident routing when the service stops behaving normally.",
+      docId: "user-guide/openbaocluster/operations/troubleshooting",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/read-replicas.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/read-replicas.md
new file mode 100644
index 000000000..99ce0971a
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/read-replicas.md
@@ -0,0 +1,307 @@
+---
+title: Read Replicas
+slug: /configure/read-replicas
+hide_title: true
+pageType: task
+journey: configure
+description: Configure steady-state non-voter read replicas, their endpoint model, and the status and lifecycle signals that keep the pool operationally safe.
+---
+
+<PageHeader
+  title="Configure read replicas"
+  lede="Read replicas add a steady-state non-voter pool for read scaling and placement isolation. The operator keeps the main client endpoint stable, can create a dedicated read Service, and stages the pool deliberately during destructive workflows."
+/>
+
+<DecisionTable
+  title="What enabling read replicas changes"
+  columns={["Surface", "Operator behavior", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Workload topology",
+        "Creates a second StatefulSet for the steady-state non-voter read pool.",
+        "The read pool becomes a first-class workload tier with its own lifecycle, storage, and template overrides.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Primary client endpoint",
+        "Keeps the main client Service shared across voter and read-replica Pods.",
+        "Clients can stay on one hostname while OpenBao handles standby or non-voter read traffic and forwards leader-only operations as needed.",
+      ],
+    },
+    {
+      cells: [
+        "Dedicated read endpoint",
+        "Optionally creates a separate read Service that selects only steady read replicas.",
+        "Use it when a workload should opt into explicit read offload instead of relying on the shared primary endpoint.",
+      ],
+    },
+    {
+      cells: [
+        "Destructive workflows",
+        "Stages the steady read pool down for restore and blue-green cutover, then restores it before the workflow completes.",
+        "This keeps peer removal, promotion, and restore semantics deterministic instead of mixing steady non-voters into destructive phases.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Endpoint model for read replicas"
+  caption="The main endpoint stays stable and can reach any client-serving Pod. The optional read Service exists for explicit consumers that want only the read pool."
+  code={`flowchart LR
+    Client["Client"] --> Main["<cluster>-public"]
+    Client --> Read["<cluster>-read (optional)"]
+    Main --> Voters["Voter Pods"]
+    Main --> Reads["Read-replica Pods"]
+    Read --> Reads
+    Reads --> Leader["OpenBao forwards writes to the leader"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client read;
+    class Main,Read process;
+    class Voters,Reads,Leader write;`}
+/>
+
+<Callout type="note" title="The primary endpoint stays shared by default">
+
+OpenBao `2.5.x` supports standby and non-voter read scaling together with request forwarding. The operator follows that contract by keeping the primary endpoint attached to the shared client Service instead of trying to classify requests at the edge. A separate read Service is still available when you want an explicit read-pool consumer path.
+
+</Callout>
+
+## Configure the read pool
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Add a steady-state read-replica pool"
+  code={`spec:
+  replicas: 3
+  readReplicas:
+    replicas: 2
+    service:
+      enabled: true
+      type: ClusterIP
+    template:
+      metadata:
+        labels:
+          workload.openbao.org/tier: read
+      resources:
+        requests:
+          cpu: "250m"
+          memory: "512Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      scheduling:
+        topologySpreadConstraints:
+          - maxSkew: 1
+            topologyKey: topology.kubernetes.io/zone
+            whenUnsatisfiable: ScheduleAnyway
+            labelSelector:
+              matchLabels:
+                openbao.org/cluster: prod-cluster
+        tolerations:
+          - key: "workload"
+            operator: "Equal"
+            value: "read"
+            effect: "NoSchedule"
+    storage:
+      size: 2Gi
+      storageClassName: fast-ssd`}
+>
+  Use the read pool when you want a steady non-voter tier. `template` and `storage` overrides apply only to the read StatefulSet. Cluster-wide concerns such as TLS, unseal, plugins, and audit remain shared with the voter pool.
+</CommandBlock>
+
+<Callout type="warning" title="Read-pool storage stays validated against the voter pool">
+
+Read-replica storage is intentionally narrower than a full second cluster spec. The operator rejects a read-pool PVC request that is smaller than the voter storage request, and an effective read `storageClassName` becomes immutable once read PVCs exist.
+
+</Callout>
+
+## Decide how clients should use the endpoints
+
+<DecisionTable
+  kind="reference"
+  title="Client endpoint choices"
+  columns={["Endpoint", "Use it when", "What to expect"]}
+  rows={[
+    {
+      cells: [
+        "Primary endpoint",
+        "Most clients should keep using the existing cluster address.",
+        "Requests can land on voters or read replicas. OpenBao then decides whether to serve the request on the target node or forward it to the active leader.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Dedicated read Service",
+        "You want explicit read offload, separate SLOs, or an endpoint that must never land on the voter pool directly.",
+        "Traffic reaches only the steady read StatefulSet. Write-class requests still rely on OpenBao forwarding semantics rather than Kubernetes request inspection.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="tip" title="Do not try to split reads and writes at the edge">
+
+The operator does not inspect HTTP methods or paths to decide which Pod should receive a request. Gateway API, Ingress, or a load balancer should send traffic to the chosen Service, and OpenBao should handle standby-read and request-forwarding behavior itself.
+
+</Callout>
+
+## Watch the read-pool status separately
+
+<DecisionTable
+  kind="reference"
+  title="Read-replica conditions"
+  columns={["Condition", "What it proves", "Typical next move"]}
+  rows={[
+    {
+      cells: [
+        "`ReadReplicasReady`",
+        "The read StatefulSet has the expected number of Ready Pods.",
+        "If false, inspect the read StatefulSet, read Pod events, and any template or storage overrides.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`ReadServingAvailable`",
+        "At least one Ready read replica is actually serving reads.",
+        "If false, inspect `/sys/health` on the read Pods and verify the pool is unsealed and has joined correctly.",
+      ],
+    },
+    {
+      cells: [
+        "`RaftMembershipReady`",
+        "The expected steady non-voter peers are registered in Raft membership.",
+        "If false, inspect membership and safe scale-down behavior before assuming the topology is stable.",
+      ],
+    },
+    {
+      cells: [
+        "`ReadReplicasAutopilotHealthy`",
+        "Autopilot considers the steady read-replica peers healthy from the integrated-storage timing perspective.",
+        "If false, inspect Autopilot state, inter-node latency, and the read pool placement before assuming the pool is a good fit for that topology. If `Unknown`, confirm the `openbao-operator` policy can `read` `sys/storage/raft/autopilot/state`.",
+      ],
+    },
+    {
+      cells: [
+        "`ReadReplicaStorageConfigured`",
+        "The read-pool PVC surface matches the declared storage contract.",
+        "If false, inspect read PVC provisioning, binding, and the effective storage class or size.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Storage status is pool-aware">
+
+`status.readReplicas.storage` records the read-pool PVC state separately from the voter pool. The existing top-level storage condition remains voter-scoped so its meaning does not change under existing automation.
+
+</Callout>
+
+<Callout type="note" title="Read-pool health and read-pool usefulness are different questions">
+
+`ReadReplicasReady`, `ReadServingAvailable`, and `RaftMembershipReady` prove that the operator-created
+topology converged. `ReadReplicasAutopilotHealthy` adds a stricter integrated-storage view of whether
+those non-voters are healthy under the current timing and replication conditions.
+
+</Callout>
+
+<Callout type="warning" title="There is no published RTT limit for read replicas">
+
+OpenBao does not publish a hard maximum network-latency number for steady non-voters. Cross-zone or
+cross-region placement can work, but it is an environment-specific validation question rather than a
+fixed supported RTT budget. Validate the actual placement with your own latency, replication, and
+Autopilot checks instead of relying on a generic rule of thumb.
+
+</Callout>
+
+<Callout type="tip" title="Healthy-cluster request behavior may still rely on forwarding">
+
+In local validation, healthy-cluster reads against read replicas still relied on OpenBao request-forwarding
+behavior for the tested KV path. Treat the shared primary endpoint and dedicated read Service as endpoint
+selection choices, not as a promise that every read is served locally from the target Pod.
+
+</Callout>
+
+<Callout type="warning" title="Do not assume no-quorum read continuity">
+
+Local validation under a stricter leader-voter partition plus added cross-node latency produced
+request stalls and timeouts rather than a clean “reads continue locally” outcome. Treat no-quorum
+read behavior as environment-specific and validate it directly in the failure topology you care
+about before you rely on it for continuity planning.
+
+</Callout>
+
+## Know the day-2 behavior before enabling the pool
+
+<DecisionTable
+  kind="reference"
+  title="Operational behavior"
+  columns={["Workflow", "What the operator does", "Why it is deliberate"]}
+  rows={[
+    {
+      cells: [
+        "Scale up or change template",
+        "Reconciles the read StatefulSet independently from the voter StatefulSet.",
+        "Read-pool rollout and voter rollout do not need to mutate together.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Disable `spec.readReplicas`",
+        "Removes steady non-voters safely, scales the read StatefulSet to zero, then deletes the read StatefulSet, read Service, and read ConfigMap.",
+        "The topology change is non-destructive to retained PVCs, so disabling the feature does not silently delete storage.",
+      ],
+    },
+    {
+      cells: [
+        "Rolling upgrade",
+        "Upgrades the read pool before allowing voter partition rollout to proceed.",
+        "This preserves read continuity and keeps voter-side disruption behind a converged read pool.",
+      ],
+    },
+    {
+      cells: [
+        "Blue-green upgrade or restore",
+        "Stages steady read replicas down first, performs the destructive work, restores the read pool, and only then marks the workflow complete.",
+        "Steady non-voters are kept out of promotion and restore-critical phases so membership cleanup and completion semantics remain deterministic.",
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the rollout design"
+  items={[
+    {
+      label: "External access",
+      description: "See how the shared primary endpoint and optional read Service fit Gateway, Ingress, and direct Service exposure.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      label: "Gateway API",
+      description: "Review how the current Gateway integration keeps one route on the shared client Service.",
+      docId: "user-guide/openbaocluster/configuration/gateway-api",
+    },
+    {
+      label: "Plan upgrades",
+      description: "Understand how rolling and blue-green workflows stage or restore the steady read pool.",
+      docId: "user-guide/openbaocluster/operations/upgrades",
+    },
+    {
+      label: "Restore from backup",
+      description: "See how restore drains the steady read pool before the restore Job and restores it before completion.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/resources-storage.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/resources-storage.md
new file mode 100644
index 000000000..88748f5f9
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/resources-storage.md
@@ -0,0 +1,268 @@
+---
+title: Resources and Storage
+hide_title: true
+pageType: task
+journey: configure
+description: Choose storage class, PVC size, and workload resource requests for the cluster data path and capacity baseline.
+---
+
+<PageHeader
+  title="Storage and workload sizing"
+  lede="The operator renders the workload, but storage class and capacity choices still belong to the platform baseline. Use this page to set resource requests, understand PVC growth behavior, and make storage decisions explicit."
+/>
+
+
+
+<DecisionTable
+  title="What the operator manages for an OpenBaoCluster"
+  columns={["Surface", "What it does", "What still belongs to you"]}
+  rows={[
+    {
+      cells: [
+        "StatefulSet and Pod template",
+        "Renders the OpenBao Pods, init container, probes, mounts, labels, and rollout behavior.",
+        "Choose resource requests, limits, and the cluster shape that the generated Pods should follow.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Services, ConfigMaps, and Secrets",
+        "Creates the workload-facing Service surfaces plus the rendered configuration and runtime Secrets required by the chosen profile.",
+        "Own the service-boundary decision, TLS ownership model, and any external secrets or certificate material that are not operator-managed.",
+      ],
+    },
+    {
+      cells: [
+        "Data PVCs",
+        "Creates one PVC per replica from the StatefulSet claim template and patches existing PVC size when you increase storage.",
+        "Choose the correct StorageClass up front and verify that the underlying CSI driver supports the expansion behavior you expect.",
+      ],
+    },
+    {
+      cells: [
+        "Audit file storage PVC",
+        "Creates or mounts one RWX PVC when `spec.auditFileStorage` is configured.",
+        "Choose storage that supports multi-node mounts, encryption at rest, and writable ownership for the OpenBao Pod security context.",
+      ],
+    },
+    {
+      cells: [
+        "Default NetworkPolicy",
+        "Applies the operator-managed baseline traffic rules for Pods in the cluster.",
+        "Add any extra ingress or egress rules your environment requires and validate them against backup, restore, and edge traffic.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Managed resource footprint"
+  caption="The OpenBaoCluster spec drives a rendered workload. The operator owns the generated Kubernetes resources, but the platform choices behind storage, capacity, and external dependencies still need to be deliberate."
+  code={`flowchart LR
+    CR["OpenBaoCluster"] --> STS["StatefulSet"]
+    CR --> SVC["Services"]
+    CR --> CFG["ConfigMaps and Secrets"]
+    CR --> NET["NetworkPolicy"]
+    STS --> PVC["Per-replica data PVCs"]
+    STS --> Pods["OpenBao Pods"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class CR read;
+    class STS,SVC,CFG,NET,PVC,Pods write;`}
+/>
+
+## Set the baseline explicitly
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Set storage and workload requests up front"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+  namespace: openbao
+spec:
+  version: "2.5.0"
+  profile: Hardened
+  replicas: 3
+  resources:
+    requests:
+      cpu: "500m"
+      memory: "1Gi"
+    limits:
+      cpu: "1000m"
+      memory: "2Gi"
+  storage:
+    size: "50Gi"
+    storageClassName: "fast-ssd"`}
+>
+  Set explicit requests and an explicit `storageClassName` in production. Defaults are acceptable for evaluation, but they provide less predictable long-term storage behavior.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Storage rules that become expensive later"
+  columns={["Choice", "Operator behavior", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "`spec.storage.storageClassName`",
+        "The effective storage class becomes immutable after the first PVCs are created.",
+        "Pick it before first reconcile if you care about IOPS, topology, encryption, or cost. Do not plan on fixing it in place later.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`spec.storage.size`",
+        "The operator supports expansion only. Decreasing size is rejected.",
+        "Plan growth, not shrinkage. If the first size is too small, you can grow it, but you cannot safely reverse it through the API.",
+      ],
+    },
+    {
+      cells: [
+        "Default StorageClass",
+        "If you omit `storageClassName`, Kubernetes uses the cluster default when PVCs are created.",
+        "That may be acceptable in development, but in production it is better to make the storage path explicit and auditable.",
+      ],
+    },
+    {
+      cells: [
+        "Filesystem expansion",
+        "Some CSI drivers finish expansion only after a restart. The operator surfaces that and can use a controlled restart path when maintenance is enabled.",
+        "A size increase is not complete until the PVC and cluster conditions confirm it.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+## Size audit file storage
+
+`spec.auditFileStorage` is separate from the Raft data path. Use it only when
+file audit devices need a filesystem handoff for a collector.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create a managed RWX audit PVC"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  auditFileStorage:
+    mode: ManagedPVC
+    size: "20Gi"
+    storageClassName: "rwx-encrypted"
+  audit:
+    - type: file
+      path: file
+      fileOptions:
+        file_path: "/openbao/audit/audit.jsonl"
+        format: "json"`}
+>
+  Set the size for expected collector lag, replay needs, and failure recovery. Long-term retention belongs in the downstream log or archive system.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Audit storage requirements"
+  columns={["Requirement", "What to verify", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "ReadWriteMany",
+        "The PVC must include `ReadWriteMany` and reach `Bound`.",
+        "`AuditFileStorageReady=False` reports missing, pending, or non-RWX claims before the workload can be considered ready.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Writable ownership",
+        "The mounted path must be writable by the OpenBao runtime user or group.",
+        "On standard Kubernetes the Pods run as UID `100` and GID `1000` with `fsGroup: 1000`. Verify that the CSI driver honors that, or pre-provision ownership for existing claims.",
+      ],
+    },
+    {
+      cells: [
+        "Encryption and node placement",
+        "The backing storage must match the sensitivity of audit records.",
+        "Audit records can contain request metadata. Keep storage encryption, node access, and platform-admin access in the security review.",
+      ],
+    },
+    {
+      cells: [
+        "Capacity and cleanup",
+        "The PVC must absorb collector outages without filling the filesystem.",
+        "Define alerting and cleanup outside the operator. The operator does not rotate, prune, or archive audit files.",
+      ],
+    },
+  ]}
+/>
+
+## Inspect the rendered storage state
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the data PVCs for a cluster"
+  code={`kubectl get pvc -n <namespace> -l openbao.org/cluster=<name>`}
+>
+  Check the requested size, bound StorageClass, and whether any PVC reports `FileSystemResizePending`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check audit storage readiness"
+  code={`kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[?(@.type=="AuditFileStorageReady")]}{.status}{"\\t"}{.reason}{"\\t"}{.message}{"\\n"}{end}'
+
+kubectl get pvc -n <namespace> <audit-pvc-name> \\
+  -o jsonpath='{.status.phase}{"\\t"}{.spec.accessModes}{"\\n"}'`}
+>
+  Use the condition for the operator view and the PVC command for the underlying Kubernetes storage state.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster storage condition"
+  code={`kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\\t"}{.reason}{"\\n"}{end}'`}
+>
+  A healthy cluster should eventually report `StorageConfigured=True`. If it does not, fix the storage-path mismatch before continuing with upgrades or backups.
+</CommandBlock>
+
+<Callout type="note" title="Controlled restarts still matter after a PVC expansion">
+
+If your CSI driver requires a restart to finish filesystem resize, use the maintenance workflow instead of bouncing Pods ad hoc. The operator can only take the controlled restart path when `spec.maintenance.enabled=true`.
+
+</Callout>
+
+<NextActions
+  title="Continue platform readiness"
+  items={[
+    {
+      label: "Observability",
+      description: "Wire metrics, dashboards, and alerting before the first storage or rollout problem becomes a blind incident.",
+      docId: "user-guide/openbaocluster/configuration/observability",
+    },
+    {
+      label: "Air-gapped and private registries",
+      description: "Use the disconnected-environment guide when image sources, pull secrets, or mirrored helper images are part of the platform contract.",
+      docId: "user-guide/openbaocluster/configuration/air-gapped",
+    },
+    {
+      label: "Configure backups",
+      description: "Configure backups against the storage path the cluster will use in steady state.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/security-profiles.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/security-profiles.md
new file mode 100644
index 000000000..183e35945
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/security-profiles.md
@@ -0,0 +1,344 @@
+---
+title: Security Profiles
+slug: /configure/security-profiles
+hide_title: true
+pageType: task
+journey: configure
+description: Choose the cluster posture first, including bootstrap, unseal, TLS, and image-verification expectations for development versus Hardened production.
+---
+
+<PageHeader
+  title="Choose a security profile"
+  lede="`spec.profile` is the top-level decision that shapes bootstrap, unseal, TLS, image verification, and failure tolerance. Use this page to choose the cluster posture and then align the rest of the baseline with it."
+/>
+
+
+
+<DecisionTable
+  title="Choose the profile deliberately"
+  columns={["Profile", "Use it when", "What it assumes", "Avoid it when"]}
+  rows={[
+    {
+      cells: [
+        "Hardened",
+        "The cluster is intended to become a real production service.",
+        "External unseal, self-initialization, verified TLS, and supply-chain guardrails are part of the normal path.",
+        "You cannot meet the external trust, identity, or networking requirements yet.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Development",
+        "You need a fast local or evaluation path and accept weaker security defaults temporarily.",
+        "Bootstrap material may live in Kubernetes Secrets, TLS can be operator-managed, and verification can be relaxed.",
+        "You are trying to define the baseline that will survive into production.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="How the profile shapes the baseline"
+  caption="The profile determines whether the cluster can rely on operator-generated trust material and stored bootstrap credentials or whether those paths are explicitly disallowed."
+  code={`flowchart LR
+    Profile["spec.profile"] --> Bootstrap["Bootstrap path"]
+    Profile --> Unseal["Unseal root of trust"]
+    Profile --> TLS["TLS source"]
+    Profile --> Verify["Image verification"]
+    Profile --> Risk["Status and admission guardrails"]
+
+    Bootstrap --> SelfInit["Self-initialization or standard init"]
+    Unseal --> KMS["External KMS / transit / static"]
+    TLS --> External["External / ACME / operator-managed"]
+    Verify --> Policy["Block or warn"]
+    Risk --> Conditions["Conditions and validation policy"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Profile process;
+    class Bootstrap,Unseal,TLS,Verify,Risk read;
+    class SelfInit,KMS,External,Policy,Conditions write;`}
+/>
+
+## What actually changes with the profile
+
+<DecisionTable
+  kind="reference"
+  title="Profile effects"
+  columns={["Surface", "Development", "Hardened"]}
+  rows={[
+    {
+      cells: [
+        "Bootstrap credential handling",
+        "Manual init is allowed and can leave a root token in a Secret when self-init is disabled.",
+        "Self-initialization is the expected path, and root-token persistence is reserved for exceptional workflows.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Unseal",
+        "Static unseal in a Secret is allowed for fast evaluation.",
+        "Use an external trust source such as cloud KMS or transit. Static unseal is limited to development and other deliberate exceptions.",
+      ],
+    },
+    {
+      cells: [
+        "TLS",
+        "Operator-managed TLS is acceptable for development and internal evaluation.",
+        "Use `External` or `ACME`; the certificate authority should not be operator-generated in production.",
+      ],
+    },
+    {
+      cells: [
+        "Image verification",
+        "Can be introduced gradually and warning-only rollouts are possible.",
+        "Use image verification as the steady-state posture. Warning-only behavior fits rollout or transition periods, and official-image defaults still verify when trust material is omitted.",
+      ],
+    },
+    {
+      cells: [
+        "Networking and jobs",
+        "You can tolerate more permissive local defaults while standing up the cluster.",
+        "Backup and other lifecycle paths should assume explicit egress and identity wiring before go-live.",
+      ],
+    },
+  ]}
+/>
+
+## Representative starting points
+
+<Tabs groupId="configure-profile-hardened-development">
+  <TabItem value="hardened" label="Hardened">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Start from the supported production baseline"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+spec:
+  profile: Hardened
+  replicas: 3
+  version: "2.4.4"
+  selfInit:
+    enabled: true
+  tls:
+    enabled: true
+    mode: External
+  unseal:
+    type: awskms
+    awskms:
+      region: us-east-1
+      kmsKeyID: alias/openbao-unseal
+  imageVerification:
+    enabled: true
+    failurePolicy: Block
+  operatorImageVerification:
+    enabled: true
+    failurePolicy: Block`}
+>
+  Hardened is the supported production path. It assumes an external trust source for unseal, non-operator-managed TLS, and a self-initializing bootstrap flow.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="development" label="Development">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use the lightest safe evaluation baseline"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: dev-cluster
+spec:
+  profile: Development
+  version: "2.4.4"
+  replicas: 1
+  tls:
+    enabled: true
+  unseal:
+    type: static`}
+>
+  Development is for local testing, proof-of-concept work, and environments where you explicitly accept stored bootstrap material and weaker trust boundaries.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+<Callout type="warning" title="Switch the baseline before production use">
+
+If other systems will depend on the cluster, move from Development to Hardened before that production usage begins.
+
+</Callout>
+
+## Choose the unseal root of trust
+
+<DecisionTable
+  title="Unseal options by posture"
+  columns={["Path", "Use it when", "Why it fits or does not fit"]}
+  rows={[
+    {
+      cells: [
+        "Cloud KMS",
+        "You run in AWS, GCP, Azure, or another managed platform with a usable external key service.",
+        "This is usually the cleanest Hardened path because the root of trust stays outside Kubernetes.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Transit",
+        "You already run a central OpenBao cluster or equivalent external trust service.",
+        "This works well for multi-cluster or hybrid environments where central trust management is intentional.",
+      ],
+    },
+    {
+      cells: [
+        "PKCS#11 or KMIP",
+        "You need HSM-backed or enterprise key-management integration.",
+        "Valid for production, but usually more specialized and operationally heavier than cloud KMS or transit.",
+      ],
+    },
+    {
+      cells: [
+        "Static Secret",
+        "You need a local development path and understand the blast radius.",
+        "This is convenient but keeps decryption material inside the same cluster state you are trying to protect.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Tabs groupId="configure-unseal-common-patterns">
+  <TabItem value="aws-kms" label="AWS KMS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use AWS KMS for Hardened unseal"
+  code={`spec:
+  profile: Hardened
+  serviceAccount:
+    annotations:
+      eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/openbao-awskms"
+  unseal:
+    type: awskms
+    awskms:
+      kmsKeyID: "arn:aws:kms:us-east-1:123456789012:key/..."
+      region: "us-east-1"`}
+/>
+
+  </TabItem>
+  <TabItem value="gcp-kms" label="GCP KMS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use GCP Cloud KMS for Hardened unseal"
+  code={`spec:
+  profile: Hardened
+  serviceAccount:
+    annotations:
+      iam.gke.io/gcp-service-account: "openbao@my-project.iam.gserviceaccount.com"
+  unseal:
+    type: gcpckms
+    gcpCloudKMS:
+      project: "my-project"
+      region: "us-central1"
+      keyRing: "openbao-ring"
+      cryptoKey: "openbao-key"`}
+/>
+
+  </TabItem>
+  <TabItem value="azure-kv" label="Azure Key Vault">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use Azure Key Vault for Hardened unseal"
+  code={`spec:
+  profile: Hardened
+  serviceAccount:
+    annotations:
+      azure.workload.identity/client-id: "87654321-4321-4321-4321-210987654321"
+  podMetadata:
+    labels:
+      azure.workload.identity/use: "true"
+  unseal:
+    type: azurekeyvault
+    azureKeyVault:
+      vaultName: "my-vault"
+      keyName: "openbao-key"`}
+/>
+
+  </TabItem>
+  <TabItem value="transit" label="Transit">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a central OpenBao transit key for unseal"
+  code={`spec:
+  profile: Hardened
+  unseal:
+    type: transit
+    credentialsSecretRef:
+      name: transit-unseal-creds
+    transit:
+      address: "https://central-openbao.example.com"
+      keyName: "tenant-1-key"
+      mountPath: "transit"`}
+>
+  The referenced Secret should hold the transit token and any optional CA or client-certificate material required by that upstream cluster.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+## Optional runtime hardening
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable AppArmor when the nodes support it"
+  code={`spec:
+  workloadHardening:
+    appArmorEnabled: true`}
+>
+  AppArmor is opt-in because support depends on the underlying node OS and cluster runtime. Pair this with the broader workload baseline in <SiteLink docId="security/workload/workload-security">Pod and runtime security</SiteLink>.
+</CommandBlock>
+
+<NextActions
+  title="Continue cluster baseline"
+  items={[
+    {
+      label: "Unseal configuration",
+      description: "Use the provider-by-provider Secret and mounted-file contract page once you know which root of trust you want.",
+      docId: "user-guide/openbaocluster/configuration/unseal",
+    },
+    {
+      label: "Self-initialization",
+      description: "Configure the bootstrap requests and operator OIDC flow that follow from the profile choice.",
+      docId: "user-guide/openbaocluster/configuration/self-init",
+    },
+    {
+      label: "External access",
+      description: "Choose the TLS and exposure pattern that matches the baseline you just picked.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      label: "Workload protections",
+      description: "Review the runtime and supply-chain controls expected behind the Hardened posture.",
+      docId: "security/workload/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/self-init.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/self-init.md
new file mode 100644
index 000000000..9b4a27ec5
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/self-init.md
@@ -0,0 +1,349 @@
+---
+title: Self-Initialization
+hide_title: true
+pageType: task
+journey: configure
+description: Configure bootstrap requests, operator OIDC setup, and verification for self-initializing OpenBao clusters with an auto-revoked bootstrap credential.
+---
+
+<PageHeader
+  title="Declarative cluster bootstrap"
+  lede="Self-initialization applies auth methods, policies, audit devices, and other bootstrap state from the `OpenBaoCluster` manifest and then revokes the bootstrap root token. Use this page to configure the bootstrap contract and the access paths that must exist after initialization."
+/>
+
+
+
+<DecisionTable
+  title="Choose the bootstrap path deliberately"
+  columns={["Path", "Use it when", "What happens to the root token", "Watch for"]}
+  rows={[
+    {
+      cells: [
+        "Self-initialization",
+        "You want declarative bootstrap and a production-ready baseline.",
+        "The root token is auto-revoked after the requests complete successfully.",
+        "You must define at least one usable auth path for humans or automation before the cluster comes up.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Standard init",
+        "You need a temporary compatibility path for development or controlled manual setup.",
+        "A root token can be created and stored in a Secret.",
+        "This is easier to start with, but it leaves you with a stronger credential-management burden afterward.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Self-init bootstrap flow"
+  caption="The cluster initializes, applies the declared requests, and then revokes the bootstrap credential instead of treating it as a permanent operating dependency."
+  code={`flowchart LR
+    Cluster["OpenBaoCluster"] --> Init["Cluster initializes"]
+    Init --> Requests["Apply selfInit requests"]
+    Requests --> Auth["Auth methods and policies"]
+    Requests --> Audit["Audit devices and engines"]
+    Requests --> Revoke["Revoke root token"]
+    Revoke --> Ready["Cluster ready for day 2"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Cluster,Init read;
+    class Requests,Revoke process;
+    class Auth,Audit,Ready write;`}
+/>
+
+<Callout type="warning" title="Plan the access path before enabling self-init">
+
+If self-init is enabled and no usable auth method exists for operators or humans, the root token is revoked and the cluster can become effectively unreachable unless it is recreated.
+
+</Callout>
+
+<DecisionTable
+  title="Bootstrap both access surfaces together"
+  columns={["Access surface", "Where it lives", "What must be true before first reconcile"]}
+  rows={[
+    {
+      cells: [
+        "Operator lifecycle auth",
+        "`spec.selfInit.oidc.enabled`",
+        "Enable it when you want the operator to bootstrap JWT auth for backup, restore, and upgrade work.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Human login path",
+        "`spec.selfInit.requests`",
+        "Create at least one usable auth method and policy path for people before the root token is revoked.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="tip" title="Define operator and human access in the same bootstrap contract">
+
+If the cluster will self-initialize, define the human login path in `selfInit.requests` as part of the same manifest that enables operator auth.
+
+</Callout>
+
+## Enable self-init
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Start from the minimum self-init block"
+  code={`spec:
+  selfInit:
+    enabled: true
+    requests:
+      - name: enable-audit
+        operation: update
+        path: sys/audit/file
+        auditDevice:
+          type: file
+          fileOptions:
+            filePath: /tmp/audit.log`}
+>
+  `requests` defines the bootstrap state. Include the minimum auth, policy, and audit configuration the cluster needs immediately after initialization.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Pair operator OIDC bootstrap with a human auth path"
+  code={`spec:
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-userpass-auth
+        operation: update
+        path: sys/auth/userpass
+        authMethod:
+          type: userpass
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      # Add your user, JWT role, or Kubernetes auth role here so a real human
+      # login path exists before the root token is revoked.`}
+>
+  The exact human auth method is your choice, but it belongs inside the same `selfInit` contract. For a complete worked example, see the [development self-init userpass recipe](../../validated-deployments/recipes/local/development-self-init-userpass.md).
+</CommandBlock>
+
+## What belongs in `requests`
+
+<DecisionTable
+  kind="reference"
+  title="Structured request surfaces"
+  columns={["Surface", "Use it for", "Typical example"]}
+  rows={[
+    {
+      cells: [
+        "`authMethod`",
+        "Enable and configure auth backends.",
+        "JWT or Kubernetes auth for operators and clients.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`policy`",
+        "Create ACL policies that your auth methods will bind to.",
+        "Policies for apps, operators, or bootstrap-only roles.",
+      ],
+    },
+    {
+      cells: [
+        "`secretEngine`",
+        "Enable mounts such as KV or transit.",
+        "Initial application secret storage or cryptography services.",
+      ],
+    },
+    {
+      cells: [
+        "`auditDevice`",
+        "Turn on audit logging at bootstrap time.",
+        "File or stdout audit devices required by your environment.",
+      ],
+    },
+    {
+      cells: [
+        "`data`",
+        "Fallback for raw API payloads when no structured field exists.",
+        "Specialized configuration that is not covered by the higher-level request fields yet.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Callout type="danger" title="Do not embed raw secrets in requests">
+
+Avoid placing passwords, tokens, or key material directly in the manifest. Use Kubernetes Secrets where supported and treat bootstrap content like the rest of your GitOps security surface.
+
+</Callout>
+
+## Bootstrap operator OIDC roles
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable operator OIDC bootstrap"
+  code={`spec:
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+      # Optional:
+      # issuer: "https://..."
+      # audience: "openbao-internal"`}
+>
+  This bootstraps operator-only JWT auth roles for lifecycle work such as backup, upgrade, and restore. It does not create human login paths by itself.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="What must stay aligned"
+  columns={["Surface", "Why it matters", "What to align"]}
+  rows={[
+    {
+      cells: [
+        "OIDC issuer and JWKS discovery",
+        "The operator must discover the Kubernetes issuer and keys to bootstrap JWT auth cleanly.",
+        "Ensure the operator ServiceAccount can GET the OIDC discovery and JWKS non-resource URLs.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "JWT audience",
+        "The role binding inside OpenBao and the projected token audience must match.",
+        "Keep `spec.selfInit.oidc.audience` aligned with the installation-scoped `OPENBAO_JWT_AUDIENCE` value.",
+      ],
+    },
+    {
+      cells: [
+        "Rendered controller identity",
+        "Custom namespace or name-prefix changes affect the ServiceAccount subject the JWT role expects.",
+        "If you manage roles manually, bind them to the rendered controller ServiceAccount identity rather than to a guessed default.",
+      ],
+    },
+  ]}
+/>
+
+## Common bootstrap patterns
+
+<Tabs groupId="self-init-patterns">
+  <TabItem value="auth-method" label="Auth method">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable a JWT auth method"
+  code={`- name: enable-jwt
+  operation: update
+  path: sys/auth/jwt-operator
+  authMethod:
+    type: jwt
+    description: "Kubernetes JWT auth"
+    config:
+      default_lease_ttl: "1h"
+      max_lease_ttl: "24h"`}
+/>
+
+  </TabItem>
+  <TabItem value="policy" label="Policy">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create an ACL policy at bootstrap"
+  code={`- name: app-policy
+  operation: update
+  path: sys/policies/acl/app-policy
+  policy:
+    policy: |
+      path "secret/data/app/*" {
+        capabilities = ["read", "list"]
+      }`}
+/>
+
+  </TabItem>
+  <TabItem value="secret-engine" label="Secret engine">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable a KV v2 mount"
+  code={`- name: enable-kv-v2
+  operation: update
+  path: sys/mounts/secret
+  secretEngine:
+    type: kv
+    description: "General purpose KV store"
+    options:
+      version: "2"`}
+/>
+
+  </TabItem>
+  <TabItem value="audit-device" label="Audit device">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable audit logging at bootstrap"
+  code={`- name: enable-file-audit
+  operation: update
+  path: sys/audit/file
+  auditDevice:
+    type: file
+    fileOptions:
+      filePath: /var/log/openbao/audit.log`}
+/>
+
+  </TabItem>
+</Tabs>
+
+## Verify the cluster finished bootstrap
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the self-init status bit"
+  code={`kubectl get openbaocluster <name> -o jsonpath='{.status.selfInitialized}'`}
+>
+  A healthy bootstrap should report `true`. If it does not, inspect the cluster status conditions and controller logs before retrying with additional requests.
+</CommandBlock>
+
+<NextActions
+  title="Continue cluster baseline"
+  items={[
+    {
+      label: "Server configuration",
+      description: "Move from bootstrap into the steady-state server settings and autopilot defaults you want to keep.",
+      docId: "user-guide/openbaocluster/configuration/server",
+    },
+    {
+      label: "Operator authentication",
+      description: "Review the operator-side auth contract if you are relying on OIDC bootstrap.",
+      docId: "user-guide/operator/authn",
+    },
+    {
+      label: "Backup operations",
+      description: "See how the operator OIDC role is used by later lifecycle workflows.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/server.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/server.md
new file mode 100644
index 000000000..f5670d057
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/server.md
@@ -0,0 +1,401 @@
+---
+title: Server Configuration
+hide_title: true
+pageType: task
+journey: configure
+description: Configure server-runtime defaults such as UI, listener behavior, audit devices, plugins, and Raft autopilot, and use the dedicated pages for adjacent configuration areas.
+---
+
+<PageHeader
+  title="Configure the server runtime"
+  lede="Use this page for the settings that shape how the OpenBao server runs: listener and lease behavior, Raft autopilot, audit devices, and plugin registration. Exposure, observability, and mirrored-image settings are documented separately."
+/>
+
+
+
+<DecisionTable
+  title="What this page owns"
+  columns={["Surface", "Use it for", "Do not use it for"]}
+  rows={[
+    {
+      cells: [
+        "`spec.configuration`",
+        "Listener behavior, UI, cache and lease settings, and Raft/autopilot tuning.",
+        "Edge exposure patterns or gateway wiring.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`spec.audit`",
+        "Declarative audit-device setup that should exist when the cluster starts.",
+        "General telemetry or metrics wiring.",
+      ],
+    },
+    {
+      cells: [
+        "`spec.auditFileStorage`",
+        "Shared filesystem handoff for file audit devices.",
+        "Long-term audit retention, tamper-proof archival, or log collection pipelines.",
+      ],
+    },
+    {
+      cells: [
+        "`spec.plugins` and plugin download settings",
+        "Explicit OpenBao plugin registration and plugin fetch behavior.",
+        "Mirrored base images or disconnected-registry strategy for the whole deployment.",
+      ],
+    },
+    {
+      cells: [
+        "Raft autopilot",
+        "Membership safety, dead-peer cleanup, and quorum behavior.",
+        "Application-level backup, upgrade, or restore workflows.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Use the focused pages for adjacent concerns">
+
+- <SiteLink docId="user-guide/openbaocluster/configuration/external-access">External access</SiteLink> owns exposure and ingress patterns.
+- <SiteLink docId="user-guide/openbaocluster/configuration/observability">Observability</SiteLink> owns telemetry, scraping, and monitoring surfaces.
+- <SiteLink docId="user-guide/openbaocluster/configuration/air-gapped">Air-gapped and private registries</SiteLink> owns mirrored-image and disconnected-environment strategy.
+
+</Callout>
+
+## Core server runtime
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Start from the core server settings"
+  code={`spec:
+  configuration:
+    ui: true
+    cacheSize: 134217728
+    disableCache: false
+    defaultLeaseTTL: "720h"
+    maxLeaseTTL: "8760h"
+    listener:
+      proxyProtocolBehavior: "use_proxy_protocol"
+    raft:
+      performanceMultiplier: 2`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Common server knobs"
+  columns={["Field", "Why you change it", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "`ui`",
+        "Enable or disable the web UI intentionally.",
+        "This is a service-boundary decision only if you also expose the route appropriately.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`listener`",
+        "Adjust listener behavior such as proxy-protocol handling.",
+        "Keep listener-level TLS assumptions aligned with the external-access path you selected.",
+      ],
+    },
+    {
+      cells: [
+        "`defaultLeaseTTL` / `maxLeaseTTL`",
+        "Set sensible lease bounds for the workloads that depend on the cluster.",
+        "Very long leases change the operational contract for the workloads that depend on the cluster.",
+      ],
+    },
+    {
+      cells: [
+        "`raft.performanceMultiplier`",
+        "Compensate for high-latency or slower control-plane environments.",
+        "Change this deliberately and verify that measured latency or failure behavior requires the larger value.",
+      ],
+    },
+  ]}
+/>
+
+## Audit devices and plugins
+
+<Tabs groupId="server-config-audit-plugins">
+  <TabItem value="audit" label="Audit devices">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable a file audit device with shared storage"
+  code={`spec:
+  auditFileStorage:
+    mode: ManagedPVC
+    size: "10Gi"
+    storageClassName: "rwx-storage"
+  audit:
+    - type: file
+      path: secure-audit
+      description: "Secure audit logging"
+      fileOptions:
+        file_path: "/openbao/audit/audit.jsonl"
+        format: "json"`}
+>
+  Use `auditFileStorage` when a collector reads file audit records from Kubernetes storage. The file path must live under the audit storage mount path.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Audit file storage choices"
+  columns={["Choice", "Use it for", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "`ManagedPVC`",
+        "Let the operator create one dedicated RWX PVC for the cluster.",
+        "Set `size` and, in production, `storageClassName`. The PVC is labeled as sensitive audit storage.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`ExistingPVC`",
+        "Mount a platform-managed RWX PVC in the same namespace.",
+        "Use this when the platform team owns storage class, encryption, retention staging, or backup policy for the handoff path.",
+      ],
+    },
+    {
+      cells: [
+        "`mountPath`",
+        "Change the path mounted into each OpenBao Pod.",
+        "The default is `/openbao/audit`. File audit device paths are rejected unless they stay under the effective mount path.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Adding audit file storage changes locked Pod-template fields">
+
+The operator mounts the PVC into voter and read-replica StatefulSets. If you enable audit file storage on an existing cluster, `AuditFileStorageReady=False` with `AuditFileStorageStatefulSetRecreateRequired` means the existing StatefulSets must be recreated or replaced by a new workload revision so the volume and mount can be applied. Preserve the data PVCs when you perform that maintenance.
+
+</Callout>
+
+<Callout type="note" title="Audit storage is a handoff buffer">
+
+Treat the audit PVC as a local collector handoff and replay buffer. Ship audit records to your external log system or immutable archive for retention, search, and compliance evidence.
+
+</Callout>
+
+  </TabItem>
+  <TabItem value="plugins" label="Plugins">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Register OCI-based plugins declaratively"
+  code={`spec:
+  configuration:
+    plugin:
+      autoDownload: true
+      downloadBehavior: "continue"
+  plugins:
+    - type: secret
+      name: aws
+      image: "ghcr.io/openbao/openbao-plugin-secrets-aws"
+      version: "v0.0.1"
+      binaryName: "openbao-plugin-secrets-aws"
+      sha256sum: "b98cb1cbfd0f567d7b614efb0621aaba10c4deda865f5e5b3d155609ada2482e"`}
+>
+  Use an `image` plugin when OpenBao should download the plugin from an OCI registry as part of server startup. The operator renders `plugin_directory = "/openbao/plugins"` and mounts a writable, pod-local volume at that path for OCI auto-download.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Register preinstalled plugins"
+  code={`spec:
+  plugins:
+    - type: secret
+      name: local-example
+      command: "openbao-plugin-secrets-example"
+      version: "v1.0.0"
+      binaryName: "openbao-plugin-secrets-example"
+      sha256sum: "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"`}
+>
+  Use a `command` plugin when the binary is already available inside the OpenBao runtime image or another explicitly managed runtime path.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Plugin fields"
+  columns={["Surface", "Use it for", "Operational note"]}
+  rows={[
+    {
+      cells: [
+        "`spec.plugins[].image`",
+        "OCI-based plugin binaries that OpenBao downloads at startup.",
+        "Set `spec.configuration.plugin.autoDownload: true`; OpenBao pods need registry egress or access to a reachable mirror.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`spec.plugins[].command`",
+        "Plugin binaries already present in the OpenBao runtime environment.",
+        "The operator does not create a plugin-download volume for command-only plugins.",
+      ],
+    },
+    {
+      cells: [
+        "`spec.configuration.plugin.autoRegister`",
+        "Automatic plugin catalog registration.",
+        "`args` and `env` on each plugin are only used when auto-register is enabled.",
+      ],
+    },
+    {
+      cells: [
+        "`spec.configuration.plugin.downloadBehavior`",
+        "Startup behavior when an OCI plugin download fails.",
+        "Use `fail` to stop startup or `continue` to log and keep starting; plugin auto-download settings require OpenBao 2.5.0 or newer.",
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Downloaded plugins are runtime cache">
+
+OCI-downloaded plugins are stored under `/openbao/plugins` on an ephemeral pod-local volume. Treat that directory as a writable startup cache, not durable storage. If the cluster runs in a private or disconnected environment, mirror the plugin image and make sure OpenBao's runtime OCI client can authenticate to that registry; Kubernetes `imagePullSecrets` only cover Kubernetes image pulls.
+
+</Callout>
+
+  </TabItem>
+</Tabs>
+
+## Raft autopilot defaults
+
+<DiagramFrame
+  title="Autopilot ownership"
+  caption="The operator keeps autopilot aligned with the cluster profile and replica count so peer cleanup and quorum behavior stay in bounds as the cluster changes."
+  code={`flowchart LR
+    Cluster["OpenBaoCluster"] --> Profile["Profile and replicas"]
+    Profile --> Operator["Operator"]
+    Operator --> Autopilot["Autopilot settings"]
+    Autopilot --> Raft["Raft membership behavior"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Cluster,Profile read;
+    class Operator process;
+    class Autopilot,Raft write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Autopilot defaults"
+  columns={["Setting", "Default", "Why it exists"]}
+  rows={[
+    {
+      cells: [
+        "`cleanupDeadServers`",
+        "`true`",
+        "Dead peers should not linger indefinitely in a Kubernetes-managed environment.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "`deadServerLastContactThreshold`",
+        "`5m`",
+        "The operator uses a shorter threshold than the generic upstream default because cluster nodes and Pods are expected to churn faster in Kubernetes.",
+      ],
+    },
+    {
+      cells: [
+        "`serverStabilizationTime`",
+        "`10s`",
+        "New servers should prove they are healthy before becoming stable voters.",
+      ],
+    },
+    {
+      cells: [
+        "`minQuorum`",
+        "Calculated from profile and replica count",
+        "Hardened favors HA safety; Development favors flexibility for small clusters.",
+      ],
+    },
+  ]}
+/>
+
+<Tabs groupId="server-config-autopilot">
+  <TabItem value="override" label="Override defaults">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Customize autopilot explicitly"
+  code={`spec:
+  profile: Hardened
+  replicas: 5
+  configuration:
+    raft:
+      autopilot:
+        minQuorum: 4
+        deadServerLastContactThreshold: "10m"
+        lastContactThreshold: "30s"
+        maxTrailingLogs: 2000
+        serverStabilizationTime: "30s"`}
+>
+  Start with the operator defaults and override them only after measuring behavior that requires a change.
+</CommandBlock>
+
+  </TabItem>
+  <TabItem value="disable-cleanup" label="Disable cleanup">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Disable automatic dead-peer cleanup"
+  code={`spec:
+  configuration:
+    raft:
+      autopilot:
+        cleanupDeadServers: false`}
+>
+  If you disable cleanup, you are taking manual ownership of peer removal. This is usually a temporary operational exception rather than the steady-state configuration.
+</CommandBlock>
+
+  </TabItem>
+</Tabs>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the full configuration schema"
+  code={`kubectl explain openbaocluster.spec.configuration`}
+>
+  Use this when you need the exact field tree. Keep this page for defaults and decision boundaries rather than exhaustive field-by-field reference.
+</CommandBlock>
+
+<NextActions
+  title="Continue cluster baseline"
+  items={[
+    {
+      label: "Observability",
+      description: "Move to the telemetry and scraping page when you need monitoring rather than server-runtime tuning.",
+      docId: "user-guide/openbaocluster/configuration/observability",
+    },
+    {
+      label: "Air-gapped and private registries",
+      description: "Use the disconnected-environment guide for mirrored images and private registry behavior.",
+      docId: "user-guide/openbaocluster/configuration/air-gapped",
+    },
+    {
+      label: "Operate",
+      description: "Carry the resulting baseline into upgrades, backups, and troubleshooting once the cluster is live.",
+      docId: "user-guide/openbaocluster/operations/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/unseal.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/unseal.md
new file mode 100644
index 000000000..22b659c9c
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/configuration/unseal.md
@@ -0,0 +1,307 @@
+---
+title: Unseal Configuration
+slug: /configure/unseal
+hide_title: true
+pageType: task
+journey: configure
+description: Configure the unseal root of trust and the Secret or mounted-file contract the operator validates for each supported unseal mode.
+---
+
+<PageHeader
+  title="Unseal trust and credential contracts"
+  lede="The unseal path defines where the root of trust lives, how credentials reach the Pods, and which Secret keys or mounted files each mode requires. Use this page to map a chosen unseal mode to the exact operator contract."
+/>
+
+
+
+<Callout type="important" title="Hardened posture prefers external trust">
+
+For production-oriented clusters, use an external trust source such as cloud KMS, transit, KMIP, OCI KMS, or PKCS#11. Reserve static unseal for development and controlled exceptions because it keeps decryption material inside Kubernetes.
+
+</Callout>
+
+<DecisionTable
+  title="Choose the unseal path deliberately"
+  columns={["Path", "Use it when", "Main operator expectation"]}
+  rows={[
+    {
+      cells: [
+        "Static",
+        "You need the lightest development or evaluation path.",
+        "The operator manages a per-cluster Secret unless you deliberately override that path.",
+      ],
+      emphasis: "caution",
+    },
+    {
+      cells: [
+        "Transit",
+        "You already run a central OpenBao trust root or another intentional upstream unseal service.",
+        "The credentials Secret must carry the transit token and any referenced TLS files.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Cloud KMS",
+        "You want the root of trust outside Kubernetes and your platform already provides a KMS path.",
+        "Prefer workload identity or ambient credentials; only use Secrets when that identity path is unavailable or intentionally overridden.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "KMIP / PKCS#11",
+        "You need HSM-backed or enterprise key-management integration.",
+        "The Secret contract is mostly file- or PIN-oriented and must match the rendered configuration exactly.",
+      ],
+    },
+  ]}
+/>
+
+## General rules
+
+<Callout type="note" title="What the operator validates before Pods can use Secret-backed credentials">
+
+- `spec.unseal.credentialsSecretRef` must reference a Secret in the same namespace as the `OpenBaoCluster`.
+- Transit unseal addresses must use HTTPS and must not include userinfo, query, fragment, localhost, loopback, link-local, or numeric host forms.
+- Users configuring transit `credentialsSecretRef` must also be authorized to `get` the referenced Secret.
+- Transit unseal credentials cannot reference operator-managed system Secrets such as `<cluster>-root-token`, `<cluster>-unseal-key`, `<cluster>-tls-ca`, or `<cluster>-tls-server`.
+- Any unseal field that points to a mounted credential file must use a path under `/etc/bao/seal-creds`.
+- The Secret key name must match the filename used in the mounted path.
+- When you use private ACME trust rooted under `/etc/bao/seal-creds`, include `pki-ca.crt` in the same Secret so probes and day-2 operations can trust the ACME issuer too.
+
+</Callout>
+
+<CommandBlock
+  language="yaml"
+  label="reference"
+  title="How mounted credential paths map to Secret keys"
+  code={`spec:
+  unseal:
+    credentialsSecretRef:
+      name: unseal-creds
+    transit:
+      tlsCACert: "/etc/bao/seal-creds/ca.crt"
+      tlsClientCert: "/etc/bao/seal-creds/client.crt"
+      tlsClientKey: "/etc/bao/seal-creds/client.key"
+    gcpCloudKMS:
+      credentials: "/etc/bao/seal-creds/credentials.json"
+    kmip:
+      clientCert: "/etc/bao/seal-creds/kmip-client.crt"
+      clientKey: "/etc/bao/seal-creds/kmip-client.key"
+      caCert: "/etc/bao/seal-creds/kmip-ca.crt"`}
+>
+  In this example, the Secret named `unseal-creds` must contain keys named `ca.crt`, `client.crt`, `client.key`, `credentials.json`, `kmip-client.crt`, `kmip-client.key`, and `kmip-ca.crt`.
+</CommandBlock>
+
+## Provider credential contracts
+
+<DecisionTable
+  kind="reference"
+  title="Secret requirements by provider"
+  columns={["Provider", "When a Secret is needed", "Required keys or file contract", "Notes"]}
+  rows={[
+    {
+      cells: [
+        "Static",
+        "Usually not needed because the operator generates the Secret automatically.",
+        "Generated Secret `<cluster-name>-unseal-key` with key `key`.",
+        "Use this only for development or controlled exceptions. If you replace it manually, keep the same key name.",
+      ],
+    },
+    {
+      cells: [
+        "Transit",
+        "Needed whenever you do not rely only on an inline token and Secret-backed files are referenced.",
+        "`token`, plus any mounted files referenced by `tlsCACert`, `tlsClientCert`, and `tlsClientKey`.",
+        "Use an orphan or periodic token with only update permissions on the transit encrypt/decrypt paths. If client cert auth is used, the certificate and key must both be present and form a valid key pair.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "AWS KMS",
+        "Required if you are not using IRSA, ambient credentials, or another default AWS credential chain.",
+        "`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.",
+        "Prefer workload identity when that path is available and intended.",
+      ],
+    },
+    {
+      cells: [
+        "GCP Cloud KMS",
+        "Required if `spec.unseal.gcpCloudKMS.credentials` points at a mounted file instead of using Workload Identity or ADC.",
+        "A Secret key matching the configured file name, usually `credentials.json`, containing valid JSON credentials.",
+        "The path must live under `/etc/bao/seal-creds`.",
+      ],
+    },
+    {
+      cells: [
+        "Azure Key Vault",
+        "Required if you are not using Managed Identity or Azure Workload Identity.",
+        "`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`.",
+        "Managed identity is the preferred Hardened path when your platform supports it.",
+      ],
+    },
+    {
+      cells: [
+        "OCI KMS",
+        "Required if `spec.unseal.ocikms.authTypeAPIKey=true`.",
+        "`config`, plus the Secret key referenced by `key_file` inside the OCI SDK config.",
+        "The OCI config must define `user`, `fingerprint`, `tenancy`, `region`, and `key_file` in profile `[DEFAULT]`, and `key_file` must point under `/etc/bao/seal-creds`.",
+      ],
+    },
+    {
+      cells: [
+        "KMIP",
+        "Needed whenever client cert, key, or CA files are sourced from mounted credentials.",
+        "Secret keys matching the filenames referenced by `clientCert`, `clientKey`, and optional `caCert` under `/etc/bao/seal-creds`.",
+        "The client certificate and key must form a valid pair; the CA bundle must be valid PEM when set. The KMIP key must already exist and be usable for encrypt/decrypt before the cluster starts.",
+      ],
+    },
+    {
+      cells: [
+        "PKCS#11",
+        "Needed when `spec.unseal.pkcs11.pin` is omitted or PKCS#11 runtime env/config files are sourced from Secret data.",
+        "`BAO_HSM_PIN`, plus every key referenced by `spec.unseal.pkcs11.runtime.env[*].secretKey` and `spec.unseal.pkcs11.runtime.fileEnv[*].secretKey`.",
+        "The operator also requires either `slot` or `tokenLabel`, but not both. The OpenBao image must include HSM support and the configured vendor PKCS#11 module.",
+      ],
+    },
+  ]}
+/>
+
+## KMIP provider contract
+
+KMIP is a network-backed seal path. The operator renders the OpenBao KMIP seal stanza, projects mTLS files from `credentialsSecretRef`, and validates mounted certificate material before the workload starts. It does not create KMIP key material or configure the KMIP server.
+
+For production clusters, prepare the KMIP side first:
+
+- Create or register the wrapping key in the KMIP service.
+- Activate the key and allow encrypt/decrypt operations for the OpenBao client identity.
+- Issue a client certificate with `clientAuth` extended key usage.
+- Issue or trust a server certificate whose DNS name matches `spec.unseal.kmip.serverName`.
+- Set `tls12Ciphers` when the KMIP appliance requires a constrained TLS 1.2 cipher suite.
+
+<CommandBlock
+  language="yaml"
+  label="example"
+  title="KMIP unseal with Secret-backed mTLS files"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: bao-kmip
+  namespace: openbao
+spec:
+  unseal:
+    type: kmip
+    credentialsSecretRef:
+      name: kmip-client
+    kmip:
+      endpoint: kmip.example.com:5696
+      kmsKeyID: "1"
+      clientCert: /etc/bao/seal-creds/client.crt
+      clientKey: /etc/bao/seal-creds/client.key
+      caCert: /etc/bao/seal-creds/ca.crt
+      serverName: kmip.example.com
+      encryptAlg: AES_GCM
+      tls12Ciphers: TLS_RSA_WITH_AES_128_CBC_SHA256`}
+>
+  The Secret `kmip-client` must contain `client.crt`, `client.key`, and `ca.crt`. The operator validates that the client certificate and key form a valid pair and that the CA bundle parses as PEM before OpenBao starts.
+</CommandBlock>
+
+## PKCS#11 runtime wiring
+
+PKCS#11 deployments need two separate pieces before OpenBao can initialize or unseal: external key material in the HSM and a runtime that can load the vendor PKCS#11 module. OpenBao does not create PKCS#11 key material for you; create the key through the HSM vendor tooling before the cluster starts.
+
+Use `spec.unseal.pkcs11.runtime` for vendor runtime settings that would otherwise require a custom entrypoint wrapper:
+
+- `libraryPath` sets `LD_LIBRARY_PATH` for vendor libraries that depend on sibling shared objects.
+- `env` maps environment variables to literal values stored in `credentialsSecretRef`.
+- `fileEnv` maps environment variables to mounted file paths under `/etc/bao/seal-creds`.
+
+The operator manages the OpenBao seal-owned environment variables (`BAO_SEAL_TYPE`, `BAO_HSM_LIB`, `BAO_HSM_PIN`, and related `BAO_HSM_*` values) from `spec.unseal.pkcs11`; do not duplicate those names in `runtime.env` or `runtime.fileEnv`.
+
+### HSM deployment checklist
+
+For PKCS#11-backed production clusters, validate the HSM integration outside the operator before creating the `OpenBaoCluster`:
+
+- Use an OpenBao image with HSM support plus the vendor PKCS#11 module and dependent shared libraries.
+- Pre-create the wrapping key in the HSM. OpenBao expects the key to exist and to allow the configured operation.
+- Choose a mechanism that matches the HSM object type. `AES_GCM` uses a secret key; `RSA_PKCS_OAEP` uses an RSA key pair and may require `rsaOAEPHash`.
+- Store the token PIN and vendor runtime material in `credentialsSecretRef`; avoid putting `pin` directly in GitOps-managed manifests.
+- Use `runtime.libraryPath` when the vendor module depends on sibling shared objects.
+- Use `runtime.env` for vendor settings that are literal values and `runtime.fileEnv` for vendor settings that expect file paths.
+- Only keys referenced by `runtime.fileEnv` are projected into the Pod as files. The PIN and `runtime.env` values remain Secret-backed environment variables and are not mounted under `/etc/bao/seal-creds`.
+
+The wrapper fails fast when `BAO_SEAL_TYPE=pkcs11` but the configured `BAO_HSM_LIB` is missing or points at a directory. Missing Secret keys are rejected during operator prerequisite validation before the workload reaches an opaque OpenBao startup failure.
+
+<CommandBlock
+  language="yaml"
+  label="example"
+  title="PKCS#11 unseal with vendor runtime env"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: bao-hsm
+  namespace: openbao
+spec:
+  image: registry.example.com/openbao-hsm-vendor:2.5.4
+  unseal:
+    type: pkcs11
+    credentialsSecretRef:
+      name: pkcs11-runtime
+    pkcs11:
+      lib: /usr/local/lib/libpkcs11.so
+      tokenLabel: OpenBao
+      keyLabel: bao-root-key-aes
+      mechanism: AES_GCM
+      runtime:
+        libraryPath: /usr/local/lib
+        env:
+          - name: CRYPTOSERVER
+            secretKey: cryptoserver
+        fileEnv:
+          - name: CS_PKCS11_R3_CFG
+            secretKey: cs_pkcs11_R3.cfg`}
+>
+  The Secret `pkcs11-runtime` must include `BAO_HSM_PIN`, `cryptoserver`, and `cs_pkcs11_R3.cfg`. The operator projects only the `fileEnv` key `cs_pkcs11_R3.cfg` under `/etc/bao/seal-creds`, sets `CS_PKCS11_R3_CFG=/etc/bao/seal-creds/cs_pkcs11_R3.cfg`, and fails fast if `/usr/local/lib/libpkcs11.so` is not present in the container.
+</CommandBlock>
+
+## Static unseal details
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create or replace the static unseal Secret manually"
+  code={`kubectl -n <namespace> create secret generic <cluster-name>-unseal-key \\
+  --from-literal=key='<UNSEAL_KEY>' \\
+  --dry-run=client -o yaml | kubectl apply -f -`}
+>
+  The operator-generated static Secret uses the name `<cluster-name>-unseal-key` and the data key `key`.
+</CommandBlock>
+
+<Callout type="warning" title="Private ACME trust piggybacks on the unseal credentials Secret">
+
+If `spec.configuration.acmeCARoot` points under `/etc/bao/seal-creds`, the Secret referenced by `spec.unseal.credentialsSecretRef` must also contain `pki-ca.crt`. This is how the operator and helper clients trust a private ACME issuer during probes and day-2 operations.
+
+</Callout>
+
+<NextActions
+  title="Continue baseline setup"
+  items={[
+    {
+      label: "Security profiles",
+      description: "Return to the posture guide when you need to decide whether this unseal path fits Development or Hardened operation.",
+      docId: "user-guide/openbaocluster/configuration/security-profiles",
+    },
+    {
+      label: "Self-initialization",
+      description: "Configure bootstrap and operator OIDC once the trust root and unseal path are chosen.",
+      docId: "user-guide/openbaocluster/configuration/self-init",
+    },
+    {
+      label: "Recover a sealed cluster",
+      description: "Use the recovery runbook when the unseal contract is already failing in a live cluster.",
+      docId: "user-guide/openbaocluster/recovery/sealed-cluster",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/getting-started.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/getting-started.md
new file mode 100644
index 000000000..7afd2fc59
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/getting-started.md
@@ -0,0 +1,262 @@
+---
+title: Create Your First Cluster
+slug: /get-started/first-cluster
+hide_title: true
+description: Start with the closest safe OpenBaoCluster baseline, verify the important readiness signals, and move cleanly into day 2 work.
+pageType: task
+journey: get-started
+journeyStep: 4
+---
+
+<PageHeader
+  title="Create the first cluster"
+  lede="Start with the closest safe baseline, verify that the cluster becomes healthy, and then move directly into the next operating concern. In the default multi-tenant mode, the target namespace is already onboarded before this step."
+/>
+
+<Checklist
+    title="Cluster manifest checklist"
+    items={[
+      'confirm the operator install is healthy in the namespace model you chose',
+      'confirm the target namespace is already onboarded through OpenBaoTenant when you are in multi-tenant mode',
+      'choose a StorageClass explicitly for production before the first reconcile',
+      'decide whether this cluster is only for evaluation or intended to become production',
+    ]}
+  />
+
+
+<Callout type="note" title="Choose the namespace handoff first">
+
+- In the default multi-tenant mode, create the target namespace, finish [OpenBaoTenant onboarding](../openbaotenant/onboarding.md), then apply `OpenBaoCluster`.
+- In single-tenant mode, skip `OpenBaoTenant` and create the cluster only in the controller's watched namespace.
+
+</Callout>
+
+<Callout type="tip" title="Same-sync GitOps is now safe in multi-tenant mode">
+
+If your GitOps workflow applies `OpenBaoTenant` and `OpenBaoCluster` together, the controller requeues cleanly until tenant onboarding is finished. You still get the clearest rollout signal by watching `OpenBaoTenant.status.provisioned` and the tenant `RoleBinding` first.
+
+</Callout>
+
+<JourneyRail
+  title="The first five moves"
+  current={4}
+  items={[
+    {
+      label: 'Choose a deployment model',
+      description: 'Choose tenancy, security posture, install method, and the main exceptions for the environment.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Render the right namespace, identity, and admission posture.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, introduce the namespace through OpenBaoTenant, then create a cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Start with the closest cluster baseline and verify the important readiness signals.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Move immediately into backups, access, upgrades, and production hardening.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Pick the first-cluster intent"
+  columns={['Intent', 'Start with', 'Do not skip', 'Go deeper']}
+  rows={[
+    {
+      cells: [
+        'Local evaluation',
+        'Development profile with operator-managed TLS and minimal storage choices.',
+        'Use this for disposable evaluation clusters rather than a production baseline.',
+        'Security profiles',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Hardened production baseline',
+        'Hardened profile, self-init, External or ACME TLS, and explicit storage.',
+        'User access bootstrap, unseal configuration, and backups before the first risky upgrade.',
+        'Validated deployments',
+      ],
+    },
+    {
+      cells: [
+        'Dedicated team namespace',
+        'The hardened baseline plus the single-tenant operator install path.',
+        'Namespace ownership, rendered controller identity, and `WATCH_NAMESPACE` alignment.',
+        'Single-tenant mode',
+      ],
+    },
+  ]}
+/>
+
+## Start with the closest manifest
+
+<Tabs groupId="first-cluster-intent">
+
+<TabItem value="evaluation" label="Local evaluation">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Start a development-profile cluster for local evaluation"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: dev-cluster
+  namespace: openbao-demo
+spec:
+  version: "2.5.0"
+  replicas: 3
+  profile: Development
+  tls:
+    enabled: true
+    mode: OperatorManaged
+    rotationPeriod: "720h"
+  storage:
+    size: "10Gi"`}
+/>
+
+<Callout type="note" title="Namespace choice still follows tenancy mode">
+
+If you are on the default multi-tenant path, `openbao-demo` must already be onboarded through `OpenBaoTenant`.
+If you are on the single-tenant path, replace `openbao-demo` with the namespace watched by the controller.
+
+</Callout>
+
+<Callout type="warning" title="Evaluation only">
+
+The `Development` profile stores sensitive material in Kubernetes Secrets and relaxes production controls.
+Use it for local testing and CI, not for real environments.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="production" label="Hardened baseline">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a hardened baseline as the starting production shape"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+  namespace: openbao-prod
+spec:
+  version: "2.5.0"
+  replicas: 3
+  profile: Hardened
+  tls:
+    enabled: true
+    mode: External
+  storage:
+    size: "50Gi"
+    storageClassName: "fast-ssd"
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      # add at least one human login path before first exposure
+      # for example: userpass, JWT, or Kubernetes auth
+  unseal:
+    # configure cloud or transit auto-unseal before first reconcile`}
+/>
+
+<Callout type="warning" title="Do not apply the hardened example unchanged">
+
+Complete these before the first production reconcile:
+
+1. finish the full `selfInit` contract so it includes both `oidc.enabled: true` for operator lifecycle auth and at least one human login path in `selfInit.requests`, using [Self-Initialization](../openbaocluster/configuration/self-init.md) and [Operator Authentication](../operator/authn.md)
+2. finish `unseal` with an external trust path such as cloud KMS, transit, KMIP, OCI KMS, or PKCS#11 in [Unseal Configuration](../openbaocluster/configuration/unseal.md)
+3. finish the namespace handoff for your tenancy mode so `openbao-prod` is already onboarded in multi-tenant mode or is the watched namespace in single-tenant mode
+
+</Callout>
+
+<Callout type="danger" title="Do not treat human auth as a post-bootstrap step">
+
+`spec.selfInit.oidc.enabled: true` gives the operator a JWT-based control path. It does not create a human login path.
+If the cluster will self-initialize, include at least one human auth method in `selfInit.requests` before the first reconcile so the cluster is usable after the root token is revoked.
+
+</Callout>
+
+<Callout type="tip" title="Use a validated baseline when possible">
+
+If you are going straight to production, prefer a tested architecture or recipe under [Validated Deployments](../validated-deployments/index.mdx) rather than inventing the entire first manifest from scratch.
+
+</Callout>
+
+</TabItem>
+
+</Tabs>
+
+## Apply and verify
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the cluster manifest"
+  code={`kubectl apply -f cluster.yaml`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect cluster phase and readiness"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o wide`}
+>
+  Watch `status.phase`, `readyReplicas`, and whether the cluster reaches `Available=True`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Watch the cluster pods stabilize"
+  code={`kubectl get pods -l openbao.org/cluster=<name> -n <namespace> -w`}
+>
+  A healthy first cluster converges without repeated crash loops or long-lived pending state.
+</CommandBlock>
+
+<Callout type="note" title="What to look for next">
+
+Confirm the cluster is available, TLS and storage match the shape you intended, and hardened clusters can realistically progress toward `ProductionReady=True`.
+
+</Callout>
+
+<NextActions
+  title="Once the first cluster is healthy"
+  items={[
+    {
+      label: 'Prepare for day 2',
+      description: 'Choose the next operating concern instead of leaving the cluster in a half-configured state.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+    {
+      label: 'Expose the cluster',
+      description: 'Pick the access path and TLS posture that match the security profile you chose.',
+      docId: 'user-guide/openbaocluster/configuration/external-access',
+    },
+    {
+      label: 'Configure backups',
+      description: 'Wire snapshots before the first risky change so restore is not first attempted during an incident.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+  ]}
+/>
+
+## Official OpenBao background
+
+- [OpenBao self-initialization](https://openbao.org/docs/configuration/self-init/)
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/next-steps.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/next-steps.md
new file mode 100644
index 000000000..2d9a274b3
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/next-steps.md
@@ -0,0 +1,155 @@
+---
+title: Prepare for Day 2
+slug: /get-started/next-steps
+hide_title: true
+description: Choose the next operating concern after the first cluster is healthy so backups, access, and hardening become part of the operating baseline.
+pageType: landing
+journey: get-started
+journeyStep: 5
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Step 5"
+  title="Next steps after initial setup"
+  lede="Follow-up work after the first cluster becomes healthy, including hardening, exposure, backups, and day 2 procedures."
+  actions={[
+    {label: 'Open the production checklist', docId: 'user-guide/openbaocluster/operations/production-checklist', variant: 'primary'},
+    {label: 'Open Operate', docId: 'user-guide/openbaocluster/operations/index', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Move on from Get Started once"
+    items={[
+      'the access path and TLS posture are chosen',
+      'backup and restore work has an owner',
+      'the first upgrade will not be improvised',
+      'someone knows which docs section owns the next change',
+    ]}
+  />
+</PageHero>
+
+<JourneyRail
+  title="The first five moves"
+  current={5}
+  items={[
+    {
+      label: 'Choose a deployment model',
+      description: 'Choose tenancy, security posture, install method, and the main exceptions for the environment.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Render the right namespace, identity, and admission posture.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, introduce the namespace through OpenBaoTenant, then create a cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Start with the closest cluster baseline and verify the important readiness signals.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Choose the next operating concern instead of leaving the cluster in a half-configured state.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Recommended first order after the cluster is healthy"
+  columns={['If this is your situation', 'Do this next', 'Why first']}
+  rows={[
+    {
+      cells: [
+        'Default production rollout',
+        'Production checklist',
+        'It turns a merely working cluster into one with explicit security, durability, and readiness gates before teams depend on it.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'You have not yet proven backup or restore',
+        'Backups',
+        'Test object storage, backup auth, and restore assumptions before the first risky upgrade.',
+      ],
+    },
+    {
+      cells: [
+        'You need user or edge access now',
+        'External access',
+        'Settle TLS mode, exposure path, and user auth assumptions before traffic and clients grow around a temporary shortcut.',
+      ],
+    },
+    {
+      cells: [
+        'You are already planning the first version change',
+        'Upgrades',
+        'Upgrade strategy and pre-upgrade snapshot expectations need to be deliberate, not improvised after the version field changes.',
+      ],
+    },
+  ]}
+/>
+
+<RouteList
+  title="Pick the next operating concern"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Finish the production checklist',
+      description: 'Close the gap between a working cluster and an environment you can responsibly expose and support.',
+      docId: 'user-guide/openbaocluster/operations/production-checklist',
+    },
+    {
+      eyebrow: '02',
+      title: 'Expose the cluster safely',
+      description: 'Choose Gateway API, Ingress, or service exposure with the TLS posture your profile actually supports.',
+      docId: 'user-guide/openbaocluster/configuration/external-access',
+    },
+    {
+      eyebrow: '03',
+      title: 'Configure backups and restore readiness',
+      description: 'Wire snapshots before the first risky change so restore is practiced before an incident or failed rollout.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      eyebrow: '04',
+      title: 'Plan upgrades and routine operations',
+      description: 'Choose the upgrade strategy, then move into maintenance, troubleshooting, and operating runbooks.',
+      docId: 'user-guide/openbaocluster/operations/upgrades',
+    },
+    {
+      eyebrow: '05',
+      title: 'Onboard tenant namespaces',
+      description: 'Use OpenBaoTenant when the platform team owns the operator and teams consume OpenBao as a service.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+  ]}
+/>
+
+<NextActions
+  title="When you need deeper context"
+  items={[
+    {
+      label: 'Browse validated deployments',
+      description: 'Use tested architectures, recipes, and runbooks when you want a validated implementation path.',
+      docId: 'user-guide/validated-deployments/index',
+    },
+    {
+      label: 'Open Security',
+      description: 'Review trust boundaries, guardrails, and profile assumptions before you standardize on this cluster shape.',
+      docId: 'security/index',
+    },
+    {
+      label: 'Open Architecture',
+      description: 'Use the internal model when you need to understand why the operator behaves the way it does.',
+      docId: 'architecture/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/backups.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/backups.md
new file mode 100644
index 000000000..169326017
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/backups.md
@@ -0,0 +1,709 @@
+---
+title: Backup Operations
+description: Configure backup jobs, object-storage auth, retention, and verification for snapshot-based recovery.
+slug: /operate/backups
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Backup operations and snapshot policy"
+  lede="OpenBao Operator runs backups as transient Jobs that authenticate separately from the main workload, stream Raft snapshots directly to object storage, and record schedule and failure state on the cluster. Use this page to configure auth, storage, schedules, retention, and verification."
+/>
+
+
+
+<DiagramFrame
+  title="Backup execution path"
+  caption="A schedule or manual trigger launches a stateless Job. The Job authenticates to OpenBao, streams the Raft snapshot directly, and uploads it to object storage without sending snapshot bytes through the controller."
+  code={`flowchart LR
+    Trigger["Cron or manual trigger"] --> Job["Backup Job"]
+    Job --> Auth["Authenticate to OpenBao"]
+    Auth --> Snapshot["Stream Raft snapshot"]
+    Snapshot --> Upload["Upload to object storage"]
+    Upload --> Status["Update backup status and retention"]
+
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#f8fafc;
+
+    class Trigger read;
+    class Job,Auth,Snapshot,Upload process;
+    class Status write;`}
+/>
+
+<DecisionTable
+  title="Choose the backup auth path"
+  columns={['Path', 'Use it when', 'Operator behavior', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'JWT auth',
+        'You can enable `selfInit.oidc` or already run the JWT auth method on the cluster.',
+        'The operator uses a projected ServiceAccount token and can auto-configure the backup auth role when OIDC bootstrap is enabled.',
+        'Keep the JWT audience aligned between the controller env vars and the OpenBao role.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Static token',
+        'JWT auth is not available yet and you need a compatibility path.',
+        'The backup Job reads a long-lived token from a Secret in the cluster namespace.',
+        'This is a compatibility path. Treat the token as a sensitive credential and rotate it deliberately.',
+      ],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+## Prerequisites
+
+- Provision a bucket or container in a supported provider:
+  - S3 or S3-compatible storage such as MinIO or Ceph
+  - Google Cloud Storage
+  - Azure Blob Storage
+- Grant the backup identity write access to that storage location.
+- Allow egress to the storage endpoint. This is required for the `Hardened` profile.
+- Decide whether the backup and restore Jobs will use a Secret, explicit workload identity metadata, or provider-default credentials.
+
+<Callout type="note" title="Separate identity surfaces">
+
+The main OpenBao Pods and backup Jobs use different ServiceAccounts.
+Cloud KMS unseal identity on the main workload does not automatically apply to backup or restore Jobs.
+Check `CloudUnsealIdentityReady` for the main Pods and `BackupConfigurationReady` for the generated backup Job identity path.
+
+</Callout>
+
+## First successful backup path
+
+<DecisionTable
+  title="Recommended first backup path"
+  columns={['Step', 'What to do', 'What proves success']}
+  rows={[
+    {
+      cells: [
+        '1. Pick the auth path',
+        'Use JWT auth when `spec.selfInit.oidc.enabled=true` or deliberately create the equivalent restore/backup roles yourself. Fall back to a static token only when JWT auth is not available.',
+        'You know whether the Job will authenticate with a projected ServiceAccount token or a Secret-backed token.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '2. Configure storage target',
+        'Choose S3, GCS, or Azure and make the credentials or workload identity path explicit.',
+        'The cluster spec contains a complete `spec.backup.target` and the referenced Secret or workload identity metadata already exists.',
+      ],
+    },
+    {
+      cells: [
+        '3. Wait for backup readiness',
+        'Apply the updated `OpenBaoCluster` and check status before assuming the CronJob can run.',
+        '`BackupConfigurationReady=True` and no storage or identity validation failures remain.',
+      ],
+    },
+    {
+      cells: [
+        '4. Force one manual run',
+        'Trigger a backup from the generated CronJob before the first upgrade window.',
+        'A real snapshot lands in object storage and `status.backup.lastSuccessfulBackup` advances.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="tip" title="For most first-time production users">
+
+The cleanest first backup path is:
+
+1. enable `spec.selfInit.oidc.enabled: true`
+2. configure `spec.backup.target`
+3. wait for `BackupConfigurationReady=True`
+4. trigger one manual backup and confirm the object exists in storage
+
+</Callout>
+
+## Configure backup auth and storage
+
+<Tabs groupId="backup-auth-path">
+
+<TabItem value="jwt-auth" label="JWT auth (Recommended)">
+
+Use JWT auth when you want automatic token rotation and the cleanest separation between the cluster workload and backup jobs.
+
+<Callout type="success" title="Automated setup">
+
+When `spec.selfInit.oidc.enabled` is `true`, the operator automatically configures:
+
+1. the JWT auth method (`auth/jwt-operator`)
+2. OIDC discovery
+3. the backup policy (`openbao-operator-backup`)
+4. the backup role (`openbao-operator-backup`)
+
+No manual OpenBao auth configuration is required.
+
+</Callout>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable OIDC bootstrap for automatic backup auth"
+  code={`spec:
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true`}
+/>
+
+<Callout type="note" title="JWT audience">
+
+The backup Job uses the audience from `OPENBAO_JWT_AUDIENCE` (default: `openbao-internal`).
+Set the same value in the OpenBao role `bound_audiences` and pass the env var to the operator
+through `controller.extraEnv` and `provisioner.extraEnv` in Helm.
+
+</Callout>
+
+<Tabs groupId="backup-provider-jwt">
+
+<TabItem value="s3" label="S3">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure S3 or S3-compatible storage"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    target:
+      provider: s3
+      endpoint: "https://s3.amazonaws.com"
+      bucket: "openbao-backups"
+      region: "us-east-1"
+      pathPrefix: "clusters/backup-cluster"
+      usePathStyle: false
+      # Optional explicit web identity path:
+      # roleArn: "arn:aws:iam::123456789012:role/openbao-backup"
+      # Optional provider metadata for the generated ServiceAccount:
+      # workloadIdentity:
+      #   serviceAccountAnnotations:
+      #     eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/openbao-backup"
+      credentialsSecretRef:
+        name: s3-credentials`}
+/>
+
+<Callout type="note" title="S3 credentials">
+
+Create a Secret with these keys when you are not using provider-default identity:
+
+- `accessKeyId`
+- `secretAccessKey`
+- `sessionToken` (optional)
+- `region` (optional)
+- `caCert` (optional)
+
+You can also omit `credentialsSecretRef` and rely on:
+
+- `roleArn` for the operator-managed web identity flow
+- ambient workload identity or default credentials
+- `workloadIdentity.serviceAccountAnnotations` when your platform integration is driven by ServiceAccount metadata
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="gcs" label="GCS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure Google Cloud Storage"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    target:
+      provider: gcs
+      bucket: "openbao-backups"
+      pathPrefix: "clusters/backup-cluster"
+      gcs:
+        project: "my-gcp-project"
+      # Optional Workload Identity metadata for the generated ServiceAccount:
+      # workloadIdentity:
+      #   serviceAccountAnnotations:
+      #     iam.gke.io/gcp-service-account: "backup@my-project.iam.gserviceaccount.com"
+      credentialsSecretRef:
+        name: gcs-credentials`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the GCS credentials Secret"
+  code={`kubectl create secret generic gcs-credentials \\
+  --from-file=credentials.json=/path/to/service-account-key.json`}
+>
+  Omit `credentialsSecretRef` when you intentionally rely on Application Default Credentials or Workload Identity instead of a static service-account key.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="azure" label="Azure">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure Azure Blob Storage"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    target:
+      provider: azure
+      bucket: "openbao-backups"
+      pathPrefix: "clusters/backup-cluster"
+      azure:
+        storageAccount: "mystorageaccount"
+        container: "openbao-backups"
+      # Optional workload identity metadata:
+      # workloadIdentity:
+      #   serviceAccountAnnotations:
+      #     azure.workload.identity/client-id: "00000000-0000-0000-0000-000000000000"
+      #   podLabels:
+      #     azure.workload.identity/use: "true"
+      credentialsSecretRef:
+        name: azure-credentials`}
+/>
+
+<Callout type="note" title="Azure credentials">
+
+Create a Secret with one of the following:
+
+- `accountKey`
+- `connectionString`
+
+For managed identity or Azure Workload Identity, omit `credentialsSecretRef`.
+If your cluster integration requires Kubernetes metadata, use:
+
+- `target.workloadIdentity.serviceAccountAnnotations`
+- `target.workloadIdentity.podLabels`
+
+</Callout>
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+<TabItem value="static-token" label="Static token (Legacy)">
+
+Use this path only when JWT auth is not available. The backup Job reads a long-lived OpenBao token from a Secret.
+
+<Callout type="note" title="Same-namespace requirement">
+
+All referenced Secrets must exist in the same namespace as the `OpenBaoCluster`. Cross-namespace references are not allowed.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the backup token Secret"
+  code={`kubectl create secret generic backup-token \\
+  --from-literal=token=hvs.yourtoken...`}
+/>
+
+<Tabs groupId="backup-provider-static">
+
+<TabItem value="s3" label="S3">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure S3 backup with a static token"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    tokenSecretRef:
+      name: backup-token
+    target:
+      provider: s3
+      endpoint: "https://s3.amazonaws.com"
+      bucket: "openbao-backups"
+      region: "us-east-1"
+      credentialsSecretRef:
+        name: s3-credentials`}
+/>
+
+</TabItem>
+
+<TabItem value="gcs" label="GCS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure GCS backup with a static token"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    tokenSecretRef:
+      name: backup-token
+    target:
+      provider: gcs
+      bucket: "openbao-backups"
+      gcs:
+        project: "my-gcp-project"
+      credentialsSecretRef:
+        name: gcs-credentials`}
+/>
+
+</TabItem>
+
+<TabItem value="azure" label="Azure">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure Azure backup with a static token"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: backup-cluster
+spec:
+  backup:
+    schedule: "0 3 * * *"
+    tokenSecretRef:
+      name: backup-token
+    target:
+      provider: azure
+      bucket: "openbao-backups"
+      azure:
+        storageAccount: "mystorageaccount"
+      credentialsSecretRef:
+        name: azure-credentials`}
+/>
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+## Minimal working example
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a minimal JWT-backed S3 backup baseline"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: my-cluster
+  namespace: openbao-prod
+spec:
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+  backup:
+    schedule: "0 3 * * *"
+    target:
+      provider: s3
+      endpoint: "https://s3.amazonaws.com"
+      bucket: "openbao-backups"
+      region: "us-east-1"
+      pathPrefix: "clusters/my-cluster"
+      credentialsSecretRef:
+        name: s3-credentials`}
+>
+  This is the smallest supported production-oriented starting point. The namespace must already contain the referenced Secret, and the backup Job still needs network egress to the object storage endpoint.
+</CommandBlock>
+
+## Advanced backup settings
+
+### Provider-specific options
+
+<Tabs groupId="backup-provider-options">
+
+<TabItem value="s3-options" label="S3">
+
+<DecisionTable
+  kind="reference"
+  title="S3-specific options"
+  columns={['Option', 'Default', 'What it changes']}
+  rows={[
+    {
+      cells: ['`region`', '`us-east-1`', 'Sets the AWS region or any placeholder value needed by an S3-compatible implementation.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`usePathStyle`', '`false`', 'Switch to path-style addressing for MinIO and some S3-compatible endpoints.'],
+    },
+    {
+      cells: ['`roleArn`', 'none', 'Enables the explicit AWS web identity path managed by the operator.'],
+    },
+    {
+      cells: ['`pathPrefix`', 'cluster-scoped default', 'Controls the object prefix used for backup keys so clusters stay separated inside a shared bucket.'],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Set S3 provider-specific options"
+  code={`spec:
+  backup:
+    target:
+      provider: s3
+      region: "eu-west-1"
+      usePathStyle: true
+      roleArn: "arn:aws:iam::123456789012:role/backup-role"
+      pathPrefix: "clusters/prod-a"`}
+/>
+
+</TabItem>
+
+<TabItem value="gcs-options" label="GCS">
+
+<DecisionTable
+  kind="reference"
+  title="GCS-specific options"
+  columns={['Option', 'What it changes']}
+  rows={[
+    {
+      cells: ['`project`', 'Pins the GCP project when credentials or ADC do not already provide it.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`endpoint`', 'Overrides the storage endpoint for emulators such as `fake-gcs-server`.'],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Set GCS provider-specific options"
+  code={`spec:
+  backup:
+    target:
+      provider: gcs
+      endpoint: "http://fake-gcs-server:4443"
+      gcs:
+        project: "my-gcp-project"`}
+/>
+
+</TabItem>
+
+<TabItem value="azure-options" label="Azure">
+
+<DecisionTable
+  kind="reference"
+  title="Azure-specific options"
+  columns={['Option', 'What it changes']}
+  rows={[
+    {
+      cells: ['`storageAccount`', 'Selects the Azure storage account. This is required when `provider: azure` is used.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`container`', 'Overrides the container name when it should differ from `bucket`.'],
+    },
+    {
+      cells: ['`endpoint`', 'Overrides the blob endpoint for testing tools such as Azurite.'],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Set Azure provider-specific options"
+  code={`spec:
+  backup:
+    target:
+      provider: azure
+      endpoint: "http://127.0.0.1:10000"
+      azure:
+        storageAccount: "mystorageaccount"
+        container: "backups"`}
+/>
+
+</TabItem>
+
+</Tabs>
+
+### Workload identity metadata
+
+Use `target.workloadIdentity` when your cloud identity integration depends on ServiceAccount annotations or pod labels on the generated backup and restore workloads.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Attach identity metadata to backup and restore workloads"
+  code={`spec:
+  backup:
+    target:
+      workloadIdentity:
+        serviceAccountAnnotations:
+          iam.gke.io/gcp-service-account: "backup@my-project.iam.gserviceaccount.com"
+          azure.workload.identity/client-id: "00000000-0000-0000-0000-000000000000"
+        podLabels:
+          azure.workload.identity/use: "true"`}
+>
+  `serviceAccountAnnotations` are applied to the generated backup and restore ServiceAccounts.
+  `podLabels` are applied to backup and restore Job pods without replacing operator-managed labels.
+</CommandBlock>
+
+<Callout type="tip" title="Emulator support">
+
+GCS and Azure support custom endpoints for local testing with `fake-gcs-server` and Azurite.
+When those endpoints use self-signed certificates, include the CA certificate in the credentials Secret.
+
+</Callout>
+
+### Retention policy
+
+Retention cleanup runs after a successful backup and works across S3, GCS, and Azure.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Keep a limited number of recent snapshots"
+  code={`spec:
+  backup:
+    retention:
+      maxCount: 7
+      maxAge: "168h"`}
+/>
+
+### Performance tuning
+
+<DecisionTable
+  kind="reference"
+  title="Multipart upload tuning"
+  columns={['Parameter', 'Default', 'When to change it']}
+  rows={[
+    {
+      cells: ['`partSize`', '`10MB`', 'Increase it for high-bandwidth links and large datasets when larger chunks reduce upload overhead.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`concurrency`', '`3`', 'Increase for throughput, or reduce it when memory pressure or object-store throttling becomes the limiting factor.'],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Tune upload chunking and parallelism"
+  code={`spec:
+  backup:
+    target:
+      partSize: 20971520
+      concurrency: 5`}
+/>
+
+### Pre-upgrade snapshots
+
+Take a snapshot immediately before the rolling update or blue-green cutover begins.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Require a snapshot before upgrades start"
+  code={`spec:
+  upgrade:
+    preUpgradeSnapshot: true
+  backup:
+    target: { ... }`}
+/>
+
+<Callout type="note" title="Upgrade safety">
+
+`preUpgradeSnapshot: true` only works when `spec.backup.target` is already configured.
+Confirm backup status before you start the upgrade rather than assuming the pre-upgrade snapshot can be taken on demand.
+
+</Callout>
+
+## Verify and operate
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check backup readiness"
+  code={`kubectl get openbaocluster my-cluster -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{\"\\n\"}{end}'`}
+>
+  Confirm `BackupConfigurationReady=True` before you rely on the schedule or trigger a manual run.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect backup status on the cluster"
+  code={`kubectl get openbaocluster my-cluster \\
+  -o jsonpath='{.status.backup}'`}
+>
+  Check `lastSuccessfulBackup`, `nextScheduledBackup`, and failure counters before you rely on the policy as a recovery control.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Trigger a manual backup from the generated CronJob"
+  code={`kubectl create job --from=cronjob/my-cluster-backup manual-backup-1`}
+>
+  Use a manual run to prove the full path: identity, cluster auth, storage reachability, and object naming before the first production upgrade.
+</CommandBlock>
+
+## Official OpenBao background
+
+- [OpenBao Backups](https://openbao.org/docs/concepts/storage/#backups)
+- [Operator Raft Command](https://openbao.org/docs/commands/operator/raft/)
+- [JWT/OIDC Auth Method](https://openbao.org/docs/auth/jwt/)
+
+<NextActions
+  title="Next operating steps"
+  items={[
+    {
+      label: 'Restore from backup',
+      description: 'Use the restore guide when you need to consume one of the snapshots this page configures.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+    {
+      label: 'Plan upgrades',
+      description: 'Validate backups as part of pre-upgrade snapshots and cutover safety.',
+      docId: 'user-guide/openbaocluster/operations/upgrades',
+    },
+    {
+      label: 'Open the production checklist',
+      description: 'Use the checklist to confirm backups, restore readiness, and day 2 controls before calling the cluster production-ready.',
+      docId: 'user-guide/openbaocluster/operations/production-checklist',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/deletion.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/deletion.md
new file mode 100644
index 000000000..753cd6adc
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/deletion.md
@@ -0,0 +1,170 @@
+---
+title: Decommission a Cluster
+description: Choose the deletion policy for a cluster teardown and verify what happens to PVCs, secrets, and backups.
+slug: /operate/decommission
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Decommission a cluster"
+  lede="Deleting an `OpenBaoCluster` removes the control plane, but the deletion policy determines whether PVC-backed data stays behind, whether critical secrets are preserved, and what still requires manual cleanup after the control plane is gone."
+/>
+
+<Checklist
+    title="Use this page to"
+    items={[
+      'tear down a dev, staging, or production cluster intentionally',
+      'change the deletion policy from the default retain behavior',
+      'remove PVC-backed data as part of a deliberate teardown',
+      'confirm whether snapshot backups still need manual cleanup afterward',
+    ]}
+  />
+
+
+<DecisionTable
+  title="Choose the deletion policy"
+  columns={['Policy', 'Use it when', 'What gets deleted', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Retain',
+        'You want the safest default, especially for production clusters or any teardown where data may need to be recovered later.',
+        'Compute resources are removed, but PVCs and the key secrets needed to recover the data remain.',
+        'You must clean up retained data and secrets manually if the teardown is truly final.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'DeletePVCs',
+        'You are tearing down an ephemeral or disposable environment and want the operator to remove PVC-backed data too.',
+        'Compute resources, secrets, and PVCs are deleted.',
+        'This is permanent data loss for the local cluster storage path.',
+      ],
+    },
+    {
+      cells: [
+        'DeleteAll',
+        'You want the most aggressive in-cluster cleanup the current implementation supports.',
+        'Compute resources and PVCs are deleted, but external object-storage backups are still left behind.',
+        'The API accepts the value, but external backup deletion is not implemented yet.',
+      ],
+    },
+  ]}
+/>
+
+## Understand what is retained
+
+The default `Retain` behavior preserves the things you need if the deletion turns out not to be final:
+
+- PVC-backed data
+- the unseal key Secret
+- the root token Secret
+- any external backups already stored in object storage
+
+<Callout type="note" title="Why the unseal key is retained">
+
+The unseal key material is what makes the retained PVC data usable later. If the operator let Kubernetes garbage-collect that Secret automatically, you could keep the encrypted data and still lose the ability to recover it.
+
+</Callout>
+
+## Configure the teardown policy
+
+<Tabs groupId="deletion-policy">
+
+<TabItem value="retain" label="Retain (Default)">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Keep data and critical secrets after cluster deletion"
+  code={`spec:
+  deletionPolicy: Retain`}
+/>
+
+</TabItem>
+
+<TabItem value="delete-pvcs" label="DeletePVCs">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Delete PVC-backed data during teardown"
+  code={`spec:
+  deletionPolicy: DeletePVCs`}
+/>
+
+<Callout type="warning" title="This removes the local storage path">
+
+Once the PVCs are deleted, the underlying volume data is gone unless you have an external snapshot or storage-level recovery path outside the operator.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="delete-all" label="DeleteAll">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Request the most aggressive supported cleanup"
+  code={`spec:
+  deletionPolicy: DeleteAll`}
+/>
+
+<Callout type="warning" title="External backup deletion is still manual">
+
+`DeleteAll` currently removes PVC-backed data but does not delete snapshot objects already written to S3, GCS, or Azure Blob Storage.
+
+</Callout>
+
+</TabItem>
+
+</Tabs>
+
+## Delete the cluster
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Delete the OpenBaoCluster"
+  code={`kubectl delete openbaocluster <name> -n <namespace>`}
+/>
+
+If the cluster still serves production traffic, confirm your cutover, backup, and recovery assumptions before you continue.
+
+## Verify the cleanup result
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check for retained or remaining resources"
+  code={`kubectl get pvc -n <namespace> -l openbao.org/cluster=<name>
+kubectl get secret -n <namespace> -l openbao.org/cluster=<name>
+kubectl get jobs -n <namespace> -l openbao.org/cluster=<name>`}
+>
+  Under `Retain`, leftover PVCs and critical secrets are expected. Under `DeletePVCs` or `DeleteAll`, the PVC-backed path should be gone, but external backups still need their own manual cleanup decision.
+</CommandBlock>
+
+<NextActions
+  title="Continue the teardown or recovery path"
+  items={[
+    {
+      label: 'Open restore operations',
+      description: 'Use the restore workflow if the goal changed from teardown to rebuilding from a snapshot.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+    {
+      label: 'Review known limitations',
+      description: 'Confirm the current pre-GA limitations around external backup deletion and other lifecycle edges.',
+      docId: 'reference/known-limitations',
+    },
+    {
+      label: 'Run planned maintenance',
+      description: 'Go back to the maintenance controls if the cluster is not actually ready for final teardown.',
+      docId: 'user-guide/openbaocluster/operations/maintenance',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/index.mdx b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/index.mdx
new file mode 100644
index 000000000..5f2a2d623
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/index.mdx
@@ -0,0 +1,132 @@
+---
+title: Operate
+slug: /operate
+hide_title: true
+pageType: landing
+journey: operate
+description: Upgrade, back up, maintain, troubleshoot, recover, and restore OpenBao clusters with a clear operating model.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Operate"
+  title="Cluster operations"
+  lede="Use these guides for the day 2 lifecycle of an OpenBao cluster, including production readiness, backups, upgrades, maintenance, troubleshooting, and decommissioning."
+  actions={[
+    {label: 'Open the production checklist', docId: 'user-guide/openbaocluster/operations/production-checklist', variant: 'primary'},
+    {label: 'Open recovery and restore', docId: 'user-guide/openbaocluster/recovery/index', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Use this section to"
+    items={[
+      'close the gap between a working cluster and a supportable service',
+      'put backups and upgrade planning in place before risky change',
+      'use maintenance and pause controls with the intended operating model',
+      'move into recovery and restore when troubleshooting is no longer enough',
+    ]}
+  />
+</PageHero>
+
+<JourneyRail
+  title="How this section is organized"
+  items={[
+    {
+      label: 'Reliability and change',
+      description: 'Use the production checklist, backups, and upgrade planning to keep planned change safe.',
+      docId: 'user-guide/openbaocluster/operations/production-checklist',
+    },
+    {
+      label: 'Cluster controls',
+      description: 'Use maintenance, pause, and decommission workflows to change controller behavior safely.',
+      docId: 'user-guide/openbaocluster/operations/maintenance',
+    },
+    {
+      label: 'Troubleshooting and recovery',
+      description: 'Start with symptoms and status, then move into recovery and restore when the incident crosses that line.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+  ]}
+/>
+
+<RouteList
+  title="Reliability and change"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Production checklist',
+      description: 'Use the checklist to confirm an environment is production-ready and supportable.',
+      docId: 'user-guide/openbaocluster/operations/production-checklist',
+    },
+    {
+      eyebrow: '02',
+      title: 'Configure backups',
+      description: 'Set up snapshot streaming, backup identity, and restore readiness as part of the operating baseline.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      eyebrow: '03',
+      title: 'Plan upgrades',
+      description: 'Use RollingUpdate or BlueGreen with a clear understanding of prerequisites, cutover, and retry behavior.',
+      docId: 'user-guide/openbaocluster/operations/upgrades',
+    },
+  ]}
+/>
+
+<RouteList
+  title="Cluster controls"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Run planned maintenance',
+      description: 'Use maintenance workflows for controlled disruption, scaling, and planned cluster interventions.',
+      docId: 'user-guide/openbaocluster/operations/maintenance',
+    },
+    {
+      eyebrow: '02',
+      title: 'Pause reconciliation',
+      description: 'Temporarily stop operator-driven changes when you need manual intervention or a controlled investigation window.',
+      docId: 'user-guide/openbaocluster/operations/pausing',
+    },
+    {
+      eyebrow: '03',
+      title: 'Decommission a cluster',
+      description: 'Remove a cluster with the deletion policy that matches data, PVCs, and external backups.',
+      docId: 'user-guide/openbaocluster/operations/deletion',
+    },
+  ]}
+/>
+
+<RouteList
+  title="Troubleshooting and recovery"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Troubleshoot the cluster',
+      description: 'Use conditions, events, and common failure patterns to understand the problem before it becomes a wider incident.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+    {
+      eyebrow: '02',
+      title: 'Recovery and restore',
+      description: 'Use safe mode, no-leader, sealed-cluster, and restore workflows when normal operations are no longer enough.',
+      docId: 'user-guide/openbaocluster/recovery/index',
+    },
+  ]}
+/>
+
+<NextActions
+  title="Supporting context"
+  items={[
+    {
+      label: 'Recovery & Restore',
+      description: 'Use the incident runbooks when symptoms turn into an active recovery event.',
+      docId: 'user-guide/openbaocluster/recovery/index',
+    },
+    {
+      label: 'Operation lifecycle architecture',
+      description: 'Read the architecture deep dive when you need to understand locks, manager ownership, or serialized operations.',
+      docId: 'architecture/operation-lifecycle',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/maintenance.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/maintenance.md
new file mode 100644
index 000000000..40060f69f
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/maintenance.md
@@ -0,0 +1,228 @@
+---
+title: Run Planned Maintenance
+description: Drain nodes, scale the cluster, enable maintenance mode, and restart Pods with the expected quorum and admission-policy behavior.
+slug: /operate/maintenance
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Run planned maintenance safely"
+  lede="Planned maintenance is where Kubernetes disruption rules, Raft quorum, and admission-policy guardrails meet. Use this page to prepare drains and restarts, scale safely, and confirm the cluster returns to normal operation."
+/>
+
+
+
+<DecisionTable
+  title="Choose the right control"
+  columns={['Control', 'Use it when', 'Operator behavior', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Node drain with PDB protection',
+        'You are changing the Kubernetes substrate and want the normal workload to keep serving.',
+        'The PodDisruptionBudget blocks voluntary disruption that would take too many voters offline at once.',
+        'The PDB only protects against voluntary evictions, not hard node failures.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Replica scaling',
+        'You need more capacity, stronger fault tolerance, or a deliberate reduction after a change.',
+        'The operator grows or shrinks the StatefulSet and manages peer membership as the replica count changes.',
+        'Do not treat scale-down as a harmless cost-saving action on a production Raft cluster.',
+      ],
+    },
+    {
+      cells: [
+        'Maintenance mode',
+        'Admission policy requires the `openbao.org/maintenance=true` signal before restarts or controlled deletes.',
+        'The operator annotates managed resources so callers with maintenance permission on the owning OpenBaoCluster can perform planned restarts or deletes.',
+        'Grant the custom `maintenance` verb on the owning OpenBaoCluster before using this path.',
+      ],
+    },
+    {
+      cells: [
+        'Pause reconciliation',
+        'You need a short-lived window where the operator stops mutating the cluster while you inspect or repair it.',
+        'The operator stops normal reconciliation until you resume it.',
+        'Pausing stops normal reconciliation, but safe-mode incidents still require the dedicated recovery flow.',
+      ],
+    },
+  ]}
+/>
+
+## Drain nodes without breaking quorum
+
+For clusters with three or more replicas, the operator creates a `PodDisruptionBudget` with `maxUnavailable: 1`. That is the main guardrail that keeps a normal node drain from evicting too many Pods at once.
+
+<DecisionTable
+  kind="reference"
+  title="Pod disruption behavior by replica count"
+  columns={['Replicas', 'PDB created', 'What it means']}
+  rows={[
+    {
+      cells: [
+        '1',
+        'No',
+        'There is no redundancy. Any disruption takes the service down.',
+      ],
+    },
+    {
+      cells: [
+        '2',
+        'No',
+        'A two-node Raft cluster cannot tolerate one unavailable voter cleanly enough for a safe `maxUnavailable: 1` policy.',
+      ],
+    },
+    {
+      cells: [
+        '3',
+        'Yes',
+        'The PDB keeps two voters available while one Pod is evicted.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '5',
+        'Yes',
+        'The operator still uses a conservative one-at-a-time disruption model.',
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the disruption budget before a drain"
+  code={`kubectl get pdb -n <namespace>
+kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data`}
+>
+  If more than one OpenBao Pod is concentrated on the same node, the drain may take longer because Kubernetes has to evict the Pods sequentially.
+</CommandBlock>
+
+<Callout type="note" title="The PDB covers only voluntary disruption">
+
+Node drains, autoscaler evictions, and direct eviction API calls are guarded. Node crashes, OOM kills, or kernel failures are not. Those rely on normal Raft quorum behavior instead of disruption-budget enforcement.
+
+</Callout>
+
+## Scale the cluster deliberately
+
+Use scaling as an intentional operational change, not a quick patch to quiet a temporary issue.
+
+<Tabs groupId="maintenance-scaling">
+
+<TabItem value="scale-up" label="Scale up">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Increase the replica count"
+  code={`spec:
+  replicas: 5`}
+>
+  The operator creates the new Pods, waits for them to join the Raft cluster, and updates the PDB to match the new size.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="scale-down" label="Scale down">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Reduce the replica count"
+  code={`spec:
+  replicas: 3`}
+>
+  The operator removes voters from the highest ordinal first, waits for the Raft configuration to converge, and only then deletes the excess Pods.
+</CommandBlock>
+
+<Callout type="warning" title="Do not scale below three replicas in production">
+
+Reducing a production cluster below three replicas removes the redundancy that makes ordinary node and Pod failures survivable.
+
+</Callout>
+
+</TabItem>
+
+</Tabs>
+
+## Use maintenance mode for controlled restarts
+
+Enable maintenance mode when your admission policies require a deliberate maintenance signal before managed Pods or the StatefulSet can be restarted, deleted, or otherwise touched during planned work.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Enable maintenance mode"
+  code={`spec:
+  maintenance:
+    enabled: true`}
+>
+  In this mode, the operator annotates managed Pods and the StatefulSet with `openbao.org/maintenance=true`. Callers still need normal Kubernetes RBAC on the target resource plus the custom `maintenance` verb on the owning `OpenBaoCluster`.
+</CommandBlock>
+
+This mode is also required for some day 2 changes that need a controlled restart path, such as finishing filesystem expansion after increasing `spec.storage.size`.
+
+## Trigger a rolling restart
+
+Use `spec.runtime.restartAt` when you need the workload to roll because an external dependency changed, such as a certificate chain, secret material, or another input that should force a controlled refresh.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Request a rolling restart"
+  code={`spec:
+  runtime:
+    restartAt: "2026-01-19T00:00:00Z"`}
+/>
+
+This request is independent from maintenance authorization. Set maintenance only when you need disruptive work on managed resources or an operator flow that explicitly requires the maintenance gate.
+
+Use `spec.runtime.restartAt` for new configurations. The older `spec.maintenance.restartAt` path remains temporarily for compatibility.
+
+When a leader Pod must be restarted or evicted, the operator handles graceful step-down automatically before termination so the cluster can elect a new leader cleanly.
+
+## Verify the cluster before and after the window
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Inspect health before and after maintenance"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{.status.phase}{"\\n"}'
+kubectl get pods -n <namespace> -l openbao.org/cluster=<name>
+kubectl exec -n <namespace> -it <pod-name> -- bao operator raft list-peers`}
+>
+  The important end state is a clean phase, Ready Pods, and a Raft peer set that matches the intended topology after the maintenance action finishes.
+</CommandBlock>
+
+## External references
+
+- [Raft integrated storage](https://openbao.org/docs/internals/integrated-storage)
+
+<NextActions
+  title="Move to the next control"
+  items={[
+    {
+      label: 'Pause reconciliation',
+      description: 'Use the lighter-weight control when you need the operator to stop mutating the cluster during a short repair window.',
+      docId: 'user-guide/openbaocluster/operations/pausing',
+    },
+    {
+      label: 'Decommission a cluster',
+      description: 'Choose the teardown policy that matches the cluster and storage cleanup you intend to perform.',
+      docId: 'user-guide/openbaocluster/operations/deletion',
+    },
+    {
+      label: 'Open recovery and restore',
+      description: 'Escalate into the incident paths when planned maintenance turns into a leader, seal, or rollback problem.',
+      docId: 'user-guide/openbaocluster/recovery/index',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/pausing.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/pausing.md
new file mode 100644
index 000000000..de5cb14fa
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/pausing.md
@@ -0,0 +1,121 @@
+---
+title: Pause Reconciliation
+description: Stop the operator from mutating a cluster temporarily while you inspect, repair, or stage a narrow maintenance action.
+slug: /operate/pause-reconciliation
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Pause reconciliation for a short manual window"
+  lede="Pausing tells the operator to stop normal reconciliation for a specific cluster while you inspect or repair it. Use it for short, deliberate manual work; recovery workflows and long-running manual management should use their own paths."
+/>
+
+<Checklist
+    title="Use this control when"
+    items={[
+      'you need the operator to stop applying changes during a short repair window',
+      'you are debugging a live cluster and do not want reconciliation to race your inspection',
+      'you plan to resume normal management after the manual intervention finishes',
+      'the cluster is not already in a dedicated safe-mode or recovery workflow',
+    ]}
+  />
+
+
+<DecisionTable
+  title="What pausing changes"
+  columns={['Surface', 'What happens while paused', 'What does not change']}
+  rows={[
+    {
+      cells: [
+        'Managed resources',
+        'The operator stops reconciling StatefulSets, Services, ConfigMaps, Secrets, and similar managed objects.',
+        'Kubernetes native controllers such as StatefulSet behavior still exist and may react independently.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Self-healing',
+        'The operator does not actively repair drift or push the workload back to the desired spec.',
+        'A broken workload does not become safe just because reconciliation stopped.',
+      ],
+    },
+    {
+      cells: [
+        'Deletion',
+        'Finalizer and deletion paths can still run if the custom resource is deleted.',
+        'Pausing is not a hard freeze of every lifecycle path.',
+      ],
+    },
+  ]}
+/>
+
+## Pause the cluster
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Pause reconciliation for one cluster"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "paused": true
+  }
+}'`}
+/>
+
+Use this only for the cluster you are actively working on. A paused cluster can drift further away from its desired state while the operator is quiet.
+
+## Verify that the pause is active
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the paused flag"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{.spec.paused}{"\\n"}'`}
+>
+  If updates appear to do nothing, check this field first before assuming the controller is broken.
+</CommandBlock>
+
+## Resume reconciliation
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Resume normal reconciliation"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "paused": false
+  }
+}'`}
+>
+  You can also remove the field entirely. The important outcome is that the operator can reconcile the cluster again and converge any pending drift.
+</CommandBlock>
+
+<Callout type="warning" title="Pause is not safe mode">
+
+If the operator entered break-glass or safe mode because of quorum loss or another critical failure, simply flipping `spec.paused` back to `false` is not the recovery step. Use the dedicated safe-mode or recovery workflow instead.
+
+</Callout>
+
+<NextActions
+  title="Choose the next step"
+  items={[
+    {
+      label: 'Run planned maintenance',
+      description: 'Use the broader maintenance workflow when the change involves drains, restarts, scaling, or maintenance mode.',
+      docId: 'user-guide/openbaocluster/operations/maintenance',
+    },
+    {
+      label: 'Open safe mode recovery',
+      description: 'Switch to the break-glass path when the cluster is no longer in an ordinary troubleshooting state.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+    {
+      label: 'Troubleshoot the cluster',
+      description: 'Go back to the symptom-driven troubleshooting route when you still need to diagnose the failure before changing anything else.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/production-checklist.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/production-checklist.md
new file mode 100644
index 000000000..4daf1c924
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/production-checklist.md
@@ -0,0 +1,189 @@
+---
+title: Production Checklist
+description: Verify security, durability, observability, and readiness for an OpenBao cluster that will serve real traffic.
+slug: /operate/production-checklist
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Production readiness checklist"
+  lede="Use this checklist after the first cluster path succeeds and before teams depend on the service. It covers security posture, data protection, observability, and the operator-reported signals that should be clean before production use."
+/>
+
+<DecisionTable
+  title="Production gates"
+  columns={['Gate', 'What must be true', 'Why it matters', 'Go deeper']}
+  rows={[
+    {
+      cells: [
+        'Security posture',
+        'The cluster runs the hardened path: secure profile, external seal, deliberate TLS, and self-init with real auth methods.',
+        'The defaults that help evaluation can become long-lived risk in production.',
+        'Security profiles, self-init, and workload TLS configuration.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Durability',
+        'Storage, replica count, and scheduled backups are all deliberate and already tested.',
+        'Upgrades, restore workflows, and voter recovery all assume the data path is stable.',
+        'Backups, storage, and topology spread.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Observability',
+        'Metrics, logs, and alerts reach the systems operators actually watch.',
+        'Incidents are slower and riskier when the first debugging session starts after go-live.',
+        'Observability and network egress configuration.',
+      ],
+    },
+    {
+      cells: [
+        'Cluster readiness',
+        'The status conditions show healthy convergence and no unresolved integration blockers.',
+        'Start a production launch from a stable status surface rather than an optimistic assumption.',
+        'Use the final verification commands on this page.',
+      ],
+    },
+  ]}
+/>
+
+## Lock down the security baseline
+
+- Set `spec.profile: Hardened` so the workload starts from the strict controller posture rather than the evaluation defaults.
+- Use a non-static external seal such as Transit, cloud KMS, `ocikms`, `kmip`, or `pkcs11`. Do not keep long-lived unseal keys in Kubernetes Secrets for the production path.
+- Confirm your Kubernetes cluster already encrypts Secrets at rest. The operator cannot compensate for an unencrypted control plane.
+- Use `ACME` or `External` TLS for public or shared edges. Avoid `OperatorManaged` certificates for public-facing production entry points.
+- Enable `spec.selfInit` and configure real user authentication in `spec.selfInit.requests` so the first operator-driven bootstrap does not end in a lockout.
+- If you rely on operator lifecycle auth for backups and upgrades, enable `spec.selfInit.oidc.enabled: true` or deliberately provision the equivalent JWT roles yourself.
+
+<Callout type="warning" title="Install success is not the production gate">
+
+A cluster that initializes successfully still needs security hardening, backup readiness, and clean status conditions before it is ready for production.
+
+</Callout>
+
+## Enforce the tenant guardrails
+
+- Verify the ValidatingAdmissionPolicies and related guardrails are installed and enforced, including:
+  - `openbao-validate-openbaocluster`
+  - `openbao-validate-openbao-tenant`
+  - `openbao-validate-openbaorestore`
+  - `openbao-lock-controller-statefulset-mutations`
+  - `openbao-lock-managed-resource-mutations`
+  - `openbao-enforce-managed-image-digests`
+  - `openbao-restrict-provisioner-rbac`
+  - `openbao-restrict-provisioner-namespace-mutations`
+  - `openbao-restrict-provisioner-tenant-governance`
+  - `openbao-restrict-controller-rbac`
+  - `openbao-restrict-controller-secret-writes`
+- Confirm that the operator namespace, tenant onboarding flow, and shared-controller trust boundaries match the tenancy model you chose during `Get Started`.
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the control-plane baseline"
+  code={`kubectl get validatingadmissionpolicy | grep openbao
+kubectl get deploy -n <operator-namespace>
+kubectl get openbaotenant -A`}
+>
+  The exact number of policies and controller Deployments depends on the features you enabled, but the OpenBao guardrail set must be visible before you bring real tenants onto the platform.
+</CommandBlock>
+
+## Make the cluster durable
+
+- Set explicit CPU and memory `requests` and `limits`. A cluster that only works under zero pressure is not production-ready.
+- Choose a low-latency StorageClass and set `spec.storage.storageClassName` explicitly for new clusters. The effective storage class is not something you want to discover by accident after PVC creation.
+- Use at least three replicas for a highly available Raft cluster and verify the Kubernetes nodes span the intended zones or failure domains.
+- Configure scheduled backups and test a restore path before the first risky upgrade.
+- If you use file audit devices, configure `spec.auditFileStorage` on encrypted RWX storage and verify the mounted path is writable by the OpenBao runtime identity.
+- Confirm `spec.network.egressRules` allow the cluster to reach the services it really depends on: cloud KMS, OIDC discovery, backup storage, and any external gateway edges.
+
+<Callout type="note" title="Backups are part of the production gate">
+
+Include backup success and restore confidence in the launch checklist rather than deferring them to later follow-up work.
+
+</Callout>
+
+## Prove observability and operational response
+
+- Configure metrics scraping through Prometheus Operator (`ServiceMonitor`) or VictoriaMetrics Operator (`VMServiceScrape`).
+- Grant the scraping identity permission to read `sys/metrics` and keep TLS verification strict in production.
+- Ship OpenBao audit files from the audit storage PVC into the external log system or immutable archive that owns retention.
+- Make sure structured logs including `cluster_name` and `cluster_namespace` reach the log system your operators actually use.
+- Alert on backup staleness, degradation, reconciliation failures, and other conditions that warrant human intervention before tenants feel the failure.
+
+## Verify the cluster before routing traffic
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Inspect the final readiness surface"
+  code={`kubectl describe openbaocluster <name> -n <namespace>
+kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{.status.phase}{"\\n"}{range .status.conditions[*]}{.type}={.status}{"\\n"}{end}'`}
+>
+  Run both commands from the target namespace so you can see the reconciler status, recent events, and the final condition set in one pass.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Signals to see before go-live"
+  columns={['Signal', 'Healthy state', 'Why it is important']}
+  rows={[
+    {
+      cells: [
+        'Phase',
+        'Running',
+        'The cluster has converged past bootstrap and is not stuck in an intermediate lifecycle state.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Available',
+        'True',
+        'The workload is up and the operator believes the service is available to consumers.',
+      ],
+    },
+    {
+      cells: [
+        'ProductionReady',
+        'True',
+        'This is the clearest signal that the cluster passed the production-readiness gate.',
+      ],
+    },
+    {
+      cells: [
+        'Integration-specific conditions',
+        'Healthy for the features you enabled, such as CloudUnsealIdentityReady, GatewayIntegrationReady, APIServerNetworkReady, AuditFileStorageReady, or BackupConfigurationReady.',
+        'These conditions expose dependency problems that may not show up as plain pod readiness failures.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue operating"
+  items={[
+    {
+      label: 'Configure backups',
+      description: 'Lock in the snapshot path as part of upgrade and maintenance planning.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      label: 'Plan upgrades',
+      description: 'Choose the right rollout strategy for the next production version change.',
+      docId: 'user-guide/openbaocluster/operations/upgrades',
+    },
+    {
+      label: 'Troubleshoot the cluster',
+      description: 'Use the incident routing guide when health, TLS, gateway, or network assumptions drift after launch.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/troubleshooting.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/troubleshooting.md
new file mode 100644
index 000000000..a63f26147
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/troubleshooting.md
@@ -0,0 +1,275 @@
+---
+title: Troubleshoot the Cluster
+description: Route common failure symptoms to the right fix quickly and know when to switch from troubleshooting into recovery.
+slug: /operate/troubleshooting
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Troubleshoot by symptom"
+  lede="Use this page to capture the failing surface, route the symptom to the right fix, and decide when recovery is the better path."
+/>
+
+
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Capture the failure surface first"
+  code={`kubectl describe openbaocluster <name> -n <namespace>
+kubectl get pods -n <namespace>
+kubectl describe pod <pod> -n <namespace>`}
+>
+  Start here to identify the failing surface. The cluster status, recent events, and the specific pod failures usually tell you whether the problem is inside the workload, at the edge, or in cluster policy.
+</CommandBlock>
+
+<DecisionTable
+  title="Choose the first troubleshooting route"
+  columns={['Symptom', 'Start here', 'Likely surface', 'Escalate when']}
+  rows={[
+    {
+      cells: [
+        'Probe failures with x509 or hostname mismatch',
+        'Check the service hostname, SNI source, and the SANs on the serving certificate.',
+        'TLS and probe configuration.',
+        'Pods still cannot become Ready after the hostname and certificate path are corrected.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'ACME challenge or join failures',
+        'Check DNS, SAN coverage, and whether the chosen ACME endpoint is actually reachable from the right network.',
+        'ACME domain planning or private/public edge reachability.',
+        'The cluster cannot issue or validate certs and the workload remains blocked behind the edge.',
+      ],
+    },
+    {
+      cells: [
+        'Gateway integration stays degraded',
+        'Inspect passthrough mode, Gateway listener compatibility, and Gateway programming state.',
+        'Gateway API integration.',
+        'Traffic still cannot reach the workload after the Gateway listener model is corrected.',
+      ],
+    },
+    {
+      cells: [
+        'Kubernetes API calls fail in a hardened cluster',
+        'Check `apiServerCIDR`, `apiServerEndpointIPs`, and the actual egress behavior of your CNI.',
+        'Cluster network policy and API egress.',
+        'The operator cannot reconcile core resources because it cannot talk to the Kubernetes API reliably.',
+      ],
+    },
+    {
+      cells: [
+        'Node hardening or capability mismatch',
+        'Check AppArmor and other workload hardening assumptions against the cluster capabilities.',
+        'Node capability mismatch.',
+        'The runtime cannot support the hardened profile you selected and the workload cannot start cleanly.',
+      ],
+    },
+  ]}
+/>
+
+<RouteList
+  title="Common failure routes"
+  items={[
+    {
+      title: 'Probe TLS failures',
+      description: 'Readiness or liveness probes fail because the serving cert does not match the name the probe actually uses.',
+      actionLabel: 'Open',
+      to: '#probe-tls-failures',
+    },
+    {
+      title: 'ACME domain and reachability',
+      description: 'Certificates do not issue, the private ACME name does not resolve, or the public CA cannot hit the endpoint you exposed.',
+      actionLabel: 'Open',
+      to: '#acme-domain-and-reachability',
+    },
+    {
+      title: 'Gateway passthrough mismatch',
+      description: 'The Gateway listener mode or controller capability does not match the TLS mode the cluster expects.',
+      actionLabel: 'Open',
+      to: '#gateway-passthrough-mismatch',
+    },
+    {
+      title: 'Kubernetes API egress',
+      description: 'The hardened network policy path blocks the controller or workload from reaching the API server.',
+      actionLabel: 'Open',
+      to: '#kubernetes-api-egress',
+    },
+    {
+      title: 'Node hardening mismatch',
+      description: 'AppArmor or another hardening requirement is not available on the target cluster.',
+      actionLabel: 'Open',
+      to: '#node-hardening-mismatch',
+    },
+    {
+      title: 'Switch to recovery',
+      description: 'Normal troubleshooting is no longer enough because leadership, restore, or rollback paths are now in play.',
+      actionLabel: 'Open',
+      to: '#switch-to-recovery',
+    },
+  ]}
+/>
+
+## Probe TLS failures
+
+### Symptom
+
+Pod events show probe failures such as `x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs`.
+
+### What it usually means
+
+The serving certificate includes DNS SANs only, but the probe is connecting through loopback or another name the cert does not cover.
+
+### Check first
+
+- `spec.gateway.hostname`
+- `spec.ingress.host`
+- whether an external Service exists
+- whether the selected hostname is present in the certificate SANs
+
+### Fix
+
+Make sure the operator has a real hostname it can use for probe SNI and that the certificate includes that hostname. If the certificate comes from an external PKI, reissue it with the correct SAN set instead of weakening probe verification.
+
+## ACME domain and reachability
+
+### Private ACME CA does not resolve
+
+If `ConditionDegraded=True` with reason `ACMEDomainNotResolvable`, the configured `spec.tls.acme.domains` likely does not resolve from cluster DNS.
+
+Use an internal domain such as `<cluster>-acme.<namespace>.svc` for private in-cluster ACME issuers and make sure CoreDNS understands any non-`.svc` override you chose for local clusters.
+
+### ACME join or certificate verification fails
+
+If Raft join shows `certificate signed by unknown authority` or server-name mismatch errors:
+
+- make sure `spec.tls.acme.domains` contains names that are actually present in the issued cert
+- for private ACME CAs, set `spec.configuration.acmeCARoot`
+- mount `pki-ca.crt` alongside that root so the operator can use it for `retry_join` and probe verification
+
+### Public ACME cannot reach the endpoint
+
+If the logs show `Timeout during connect`, `secondary validation`, or repeated `tls-alpn-01` failures:
+
+- expose the hardened hostname on a dedicated public passthrough listener on port `443`
+- do not source-restrict the ACME validation path to a single client IP
+- keep restricted admin edges separate from the public challenge edge if you need both
+
+## Gateway passthrough mismatch
+
+If `ConditionDegraded=True` with reason `ACMEGatewayNotConfiguredForPassthrough`, or `GatewayIntegrationReady=False` with reasons such as `GatewayListenerIncompatible`, `GatewayFeatureUnsupported`, or `GatewayNotProgrammed`, start at the Gateway listener model.
+
+For `tls.mode: ACME`:
+
+- set `spec.gateway.tlsPassthrough: true`
+- make sure the referenced Gateway has a `TLS` listener with `tls.mode: Passthrough`
+- verify the Gateway controller actually supports the required route feature
+
+TLS termination at the Gateway breaks OpenBao's ability to complete ACME challenges. Fix the passthrough model first instead of debugging the workload Pods.
+
+## Kubernetes API egress
+
+If `APIServerNetworkReady=False` with reason `APIServerNetworkConfigurationInvalid`, or if API calls fail in a hardened cluster:
+
+- set `spec.network.apiServerCIDR` when the in-cluster service VIP cannot be discovered or you want an explicit allow-list
+- add `spec.network.apiServerEndpointIPs` when your CNI enforces egress on post-DNAT traffic and the service-VIP path still fails
+- treat `APIServerEndpointIPsRecommended` as advice, not automatically as a hard failure
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the current API-network conditions"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\\t"}{.reason}{"\\n"}{end}'`}
+>
+  This gives you the condition reasons in one pass so you can see whether the controller is failing on service-VIP discovery, endpoint-IP guidance, or a more direct API connectivity problem.
+</CommandBlock>
+
+## Node hardening mismatch
+
+If `ConditionNodeSecurityCapabilityMismatch=True` with reason `AppArmorUnsupported`, the hardened profile expects a node capability your environment does not provide.
+
+For evaluation or constrained dev clusters only, you can disable AppArmor:
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Disable AppArmor for unsupported dev clusters"
+  code={`spec:
+  workloadHardening:
+    appArmorEnabled: false`}
+>
+  Do not use this as a quiet production workaround. The right production fix is to run on nodes that satisfy the hardening profile you selected.
+</CommandBlock>
+
+## Switch to recovery
+
+Normal troubleshooting stops being the right tool when the incident is no longer about a single configuration defect and is now about getting the service back into a safe known state.
+
+<DecisionTable
+  kind="reference"
+  title="When to move from troubleshooting into recovery"
+  columns={['Trigger', 'Go next', 'Why']}
+  rows={[
+    {
+      cells: [
+        'The cluster cannot elect or keep a leader',
+        'No-leader recovery',
+        'This is no longer just a config issue. You need a controlled Raft recovery path.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'The cluster remains sealed and the normal unseal path is not recovering it',
+        'Sealed-cluster recovery',
+        'The incident has crossed into availability recovery, not ordinary convergence repair.',
+      ],
+    },
+    {
+      cells: [
+        'A blue-green or rollback path failed and the controller needs operator action',
+        'Failed rollback recovery',
+        'Version change failure modes need a dedicated incident path to avoid making the situation worse.',
+      ],
+    },
+    {
+      cells: [
+        'The fastest safe recovery is to restore from a snapshot',
+        'Restore operations',
+        'You are now operating a destructive recovery workflow and should stop iterating on local fixes.',
+      ],
+    },
+  ]}
+/>
+
+## External references
+
+- [TCP listener configuration](https://openbao.org/docs/configuration/listener/tcp/)
+- [ACME TLS listener RFC](https://openbao.org/docs/rfcs/acme-tls-listeners/)
+- [Operator Raft command](https://openbao.org/docs/commands/operator/raft/)
+
+<NextActions
+  title="Escalate or go deeper"
+  items={[
+    {
+      label: 'Open recovery and restore',
+      description: 'Use the incident-focused recovery pages when normal troubleshooting no longer reduces risk.',
+      docId: 'user-guide/openbaocluster/recovery/index',
+    },
+    {
+      label: 'Review backup operations',
+      description: 'Confirm snapshot-path health before restore becomes part of the incident response.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      label: 'Review network security',
+      description: 'Go deeper on hardened egress rules and API-server access when the incident is rooted in cluster policy.',
+      docId: 'security/infrastructure/network-security',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/upgrades.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/upgrades.md
new file mode 100644
index 000000000..91483fdae
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/operations/upgrades.md
@@ -0,0 +1,306 @@
+---
+title: Plan Upgrades
+description: Choose the right rollout strategy, stage upgrade auth deliberately, and verify the cluster before and after a version change.
+slug: /operate/upgrades
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Upgrade planning and rollout"
+  lede="The operator supports rolling and blue-green upgrades, but both paths depend on cluster health, backup posture, and explicit authentication for the executor Jobs. Use this page to choose the strategy, stage the right config, and verify the rollout cleanly."
+/>
+
+
+
+<DecisionTable
+  title="Choose the upgrade strategy"
+  columns={['Strategy', 'Use it when', 'Operator behavior', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'RollingUpdate',
+        'You want the default production path with the lowest resource overhead.',
+        'The operator upgrades pods one by one, handles leader step-down when needed, and waits for each ordinal to converge before finishing.',
+        'Failures hold the rollout until you fix the cause and send an explicit retry request.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'BlueGreen',
+        'You need staged validation, manual promotion, or stronger cutover boundaries for a risky change.',
+        'The operator creates a parallel Green revision, validates it, promotes it, and then cleans up the old Blue revision.',
+        'This path uses more cluster resources and introduces additional in-flight phases to watch.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Do not switch strategies on an existing cluster">
+
+Switching an existing cluster between `RollingUpdate` and `BlueGreen` is not a supported in-place transition today. Choose the strategy before the next rollout and keep it stable for that cluster.
+
+</Callout>
+
+<DiagramFrame
+  title="Upgrade control flow"
+  caption="Every upgrade starts with validation. After that, the controller either executes a partitioned rolling rollout or creates a parallel Green revision for promotion and cleanup."
+  code={`flowchart LR
+    Validate["Validate target version and config"] --> Snapshot["Optional pre-upgrade snapshot"]
+    Snapshot --> Strategy{"Choose strategy"}
+    Strategy --> Rolling["Rolling update"]
+    Strategy --> Green["Deploy green revision"]
+    Rolling --> Verify["Verify health and convergence"]
+    Green --> Promote["Promote green and cut over"]
+    Promote --> Verify
+    Verify --> Complete["Complete"]
+    Verify --> Hold["Hold for retry or operator action"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Validate,Snapshot read;
+    class Strategy,Rolling,Green,Promote process;
+    class Verify,Complete,Hold write;`}
+/>
+
+## Prepare the rollout
+
+- Confirm the cluster is initialized, healthy, and already safe to change. An upgrade is not the time to discover a broken backup path or an unstable seal configuration.
+- Set `spec.version` to the target semantic version. The operator blocks downgrades and validates semver format.
+- If you override `spec.image`, keep it aligned with `spec.version`. Semantic-version tags must match, and digest-pinned images still require `spec.version` as the authoritative intent.
+- Make sure the upgrade executor Job can authenticate:
+  - with the default JWT role created from `selfInit.oidc`, or
+  - with an explicit `spec.upgrade.jwtAuthRole`
+- If you want pre-upgrade snapshots, configure `spec.backup` first and make sure the backup auth path is already working.
+- In the `Hardened` profile, explicitly allow egress to object storage or other external dependencies the upgrade path needs.
+
+<Callout type="note" title="Upgrade auth is separate from backup auth">
+
+The upgrade executor Job uses JWT auth to talk to OpenBao. Pre-upgrade snapshots use the backup configuration and backup identity path. Do not assume one automatically covers the other.
+
+</Callout>
+
+## Use the default rolling path
+
+Use `RollingUpdate` when you want the lowest operational complexity and you do not need a second revision running in parallel.
+
+<Tabs groupId="rolling-update-setup">
+
+<TabItem value="default-jwt-bootstrap" label="JWT via self-init OIDC">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use the default rolling path with OIDC bootstrap"
+  code={`spec:
+  version: "2.5.0"
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+  upgrade:
+    strategy: RollingUpdate`}
+/>
+
+</TabItem>
+
+<TabItem value="explicit-upgrade-role" label="Explicit upgrade role">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a dedicated JWT role for upgrade Jobs"
+  code={`spec:
+  version: "2.5.0"
+  upgrade:
+    strategy: RollingUpdate
+    jwtAuthRole: platform-upgrade`}
+/>
+
+</TabItem>
+
+<TabItem value="private-registry" label="Private registry image">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Keep the image and semantic version aligned"
+  code={`spec:
+  version: "2.5.0"
+  image: "registry.example.com/openbao/openbao:2.5.0"
+  upgrade:
+    strategy: RollingUpdate
+    jwtAuthRole: platform-upgrade`}
+/>
+
+</TabItem>
+
+</Tabs>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Patch the cluster to the target version"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "version": "2.5.0",
+    "upgrade": {
+      "strategy": "RollingUpdate"
+    }
+  }
+}'`}
+/>
+
+<Callout type="note" title="Rolling upgrades can step down more than once">
+
+If leadership moves while the rollout is in progress, you may see multiple step-down Jobs across the same upgrade. That is expected and does not mean the controller restarted the entire workflow.
+
+</Callout>
+
+<Callout type="note" title="Read replicas change the rollout ordering">
+
+When steady read replicas are configured, the operator upgrades the read pool first and only then starts the voter partition rollout. For blue-green, the operator stages the steady read pool down before cutover, restores it afterward, and only then returns the workflow to `Idle`.
+
+</Callout>
+
+## Use blue-green when you need a controlled cutover
+
+Choose `BlueGreen` when you need parallel validation, a manual promotion point, or stronger rollback boundaries before the new revision takes over production traffic.
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure a blue-green upgrade with automatic rollback"
+  code={`spec:
+  version: "2.5.0"
+  upgrade:
+    strategy: BlueGreen
+    preUpgradeSnapshot: true
+    blueGreen:
+      autoPromote: true
+      autoRollback:
+        enabled: true
+        onJobFailure: true
+        onValidationFailure: true`}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Add a pre-promotion verification hook"
+  code={`spec:
+  upgrade:
+    strategy: BlueGreen
+    blueGreen:
+      verification:
+        prePromotionHook:
+          image: curlimages/curl
+          command: ["curl", "-f", "https://green-cluster:8200/v1/sys/health"]`}
+>
+  Use the hook to prove the Green revision is really healthy before promotion. If the hook fails, the operator either holds or rolls back depending on the `autoRollback` settings.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Control in-flight upgrades"
+  columns={['Control', 'What it does', 'Use it when']}
+  rows={[
+    {
+      cells: [
+        'spec.upgrade.requests.retry',
+        'Restarts a failed rolling upgrade after you fix the underlying cause.',
+        'The operator preserved `status.upgrade.failure.reason` (and the deprecated `lastError*` compatibility fields) and is waiting for an explicit retry.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'spec.upgrade.requests.promote',
+        'Approves promotion when `blueGreen.autoPromote=false` and the Green revision is already healthy.',
+        'You want a manual checkpoint before switching traffic.',
+      ],
+    },
+    {
+      cells: [
+        'blueGreen.autoRollback',
+        'Aborts or rolls back automatically when validation or execution fails in supported phases.',
+        'You want the operator to recover from bad Green revisions without waiting for a human to react.',
+      ],
+    },
+  ]}
+/>
+
+## Verify the rollout outcome
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Inspect the upgrade result"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o yaml
+kubectl get pods -n <namespace>
+kubectl get jobs -n <namespace>`}
+>
+  Look for an idle cluster rather than just a patched spec. The right end state is healthy pods, no unresolved upgrade failure state, and a condition surface that matches the cluster features you enabled.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Expected signals after the upgrade"
+  columns={['Surface', 'Healthy signal', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Cluster phase',
+        'Phase returns to Running.',
+        'The lifecycle is no longer in an in-flight upgrade state.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Availability',
+        'Available=True and the workload Pods are Ready.',
+        'The new revision is actually serving instead of only existing on paper.',
+      ],
+    },
+    {
+      cells: [
+        'Upgrade status',
+        'No unresolved `status.upgrade.failure.reason` (or deprecated `lastErrorReason`) and no stalled blue-green phase.',
+        'The controller does not think operator action is still required.',
+      ],
+    },
+    {
+      cells: [
+        'Protection path',
+        'Backup status and external dependency conditions remain healthy.',
+        'A successful version change keeps the next restore or backup window intact.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Keep the change safe"
+  items={[
+    {
+      label: 'Review the production checklist',
+      description: 'Use the readiness gate before you call the upgraded cluster your new baseline.',
+      docId: 'user-guide/openbaocluster/operations/production-checklist',
+    },
+    {
+      label: 'Open backup operations',
+      description: 'Make sure the snapshot path remains healthy before and after the next change window.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      label: 'Troubleshoot the cluster',
+      description: 'Use the incident guide when TLS, gateway, auth, or runtime assumptions fail after the rollout.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/overview.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/overview.md
new file mode 100644
index 000000000..299fc505d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/overview.md
@@ -0,0 +1,165 @@
+---
+title: Cluster Overview
+slug: /configure/cluster-overview
+hide_title: true
+pageType: concept
+journey: configure
+description: Understand what OpenBaoCluster owns, what the operator protects automatically, and how to read the Configure section as one cluster-shaping system.
+---
+
+<PageHeader
+  title="OpenBaoCluster as the service contract"
+  lede="`OpenBaoCluster` is the declarative contract for the running OpenBao service on Kubernetes. It sets the cluster shape, service boundary, storage path, and day 2 capabilities the operator will keep reconciling. Use this page to orient the rest of Configure and understand which areas to tune next."
+/>
+
+<Checklist
+    title="Use this page to understand"
+    items={[
+      "a clear view of what the operator owns versus what the platform still expects from you",
+      "the right mental model for spec as desired state and status as the observed operating surface",
+      "a shorter list of pages to read next instead of a flat wall of configuration topics",
+      "how to shape the first cluster around the main operating decisions",
+    ]}
+  />
+
+
+<Callout type="note" title="Profile is an explicit part of the contract">
+
+Set `spec.profile` deliberately. `Hardened` and `Development` are not stylistic presets; they change the security posture, bootstrap requirements, and what the operator will allow the cluster to do.
+
+</Callout>
+
+<DecisionTable
+  title="What OpenBaoCluster is responsible for"
+  columns={["Area", "What the spec controls", "What still belongs to you"]}
+  rows={[
+    {
+      cells: [
+        "Cluster shape",
+        "Version, replica count, security profile, bootstrap path, and the baseline runtime configuration the operator should keep in sync.",
+        "Choose values that match the environment and failure model you actually intend to run.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Service boundary",
+        "Services, Gateway or Ingress integration, and cluster network configuration.",
+        "Own the edge design, DNS, certificate authority, and network assumptions outside the cluster itself.",
+      ],
+    },
+    {
+      cells: [
+        "Platform readiness",
+        "Storage size, workload requests, telemetry enablement, and mirrored-image defaults that affect runtime behavior.",
+        "Provide the correct StorageClass, registry access, monitoring stack, and cluster capacity around the workload.",
+      ],
+    },
+    {
+      cells: [
+        "Day 2 workflow hooks",
+        "Backup scheduling, restore auth bootstrap, upgrade strategy, maintenance mode, and pause behavior.",
+        "Actually operate those flows: verify backups, plan upgrades, and respond to recovery conditions as part of the service lifecycle.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="GitOps contract"
+  caption="The spec is the desired cluster shape. The operator renders and maintains the Kubernetes workload, then reports the observed operating state back on status."
+  code={`flowchart LR
+    Git["Git or deployment source"] --> Spec["OpenBaoCluster.spec"]
+    Spec --> Operator["OpenBao Operator"]
+    Operator --> Workload["StatefulSet, Services, ConfigMaps, Secrets, Jobs"]
+    Workload --> Status["OpenBaoCluster.status"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Git,Spec read;
+    class Operator process;
+    class Workload,Status write;`}
+/>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Recognize the major spec surfaces in one manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: prod-cluster
+  namespace: openbao
+spec:
+  version: "2.5.0"
+  profile: Hardened
+  replicas: 3
+
+  storage:
+    size: "50Gi"
+    storageClassName: "fast-ssd"
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+
+  service:
+    type: ClusterIP
+
+  observability:
+    metrics:
+      enabled: true
+
+  backup:
+    schedule: "0 3 * * *"`}
+>
+  This example shows the major configuration surfaces that map to the rest of the section: baseline, service boundary, platform readiness, and day 2 operations.
+</CommandBlock>
+
+<RouteList
+  title="Read Configure in layers"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Cluster baseline",
+      description: "Choose the profile, bootstrap path, and server defaults that define how the cluster starts and what posture it can realistically sustain.",
+      docId: "user-guide/openbaocluster/configuration/security-profiles",
+    },
+    {
+      eyebrow: "02",
+      title: "Service boundary",
+      description: "Define how traffic reaches OpenBao, where TLS terminates, and which network assumptions the workload is allowed to make.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      eyebrow: "03",
+      title: "Platform readiness",
+      description: "Finish storage, observability, and registry decisions before the cluster becomes expensive to move or hard to inspect.",
+      docId: "user-guide/openbaocluster/configuration/resources-storage",
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue cluster shaping"
+  items={[
+    {
+      label: "Security profiles",
+      description: "Start with the production posture and bootstrap model, then refine edge and observability details.",
+      docId: "user-guide/openbaocluster/configuration/security-profiles",
+    },
+    {
+      label: "External access",
+      description: "Move to the service boundary once the baseline cluster shape is clear.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      label: "Prepare for day 2",
+      description: "Return to the operating path once configuration choices are explicit enough to support upgrades, backups, and recovery.",
+      docId: "user-guide/openbaocluster/next-steps",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/failed-rollback.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/failed-rollback.md
new file mode 100644
index 000000000..6bca243ba
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/failed-rollback.md
@@ -0,0 +1,194 @@
+---
+title: Recover from Failed Rollback
+description: Diagnose blue-green rollback failures, decide whether to retry, pause and repair, or restore from backup, and resume automation only when the cluster is safe again.
+slug: /recover/failed-rollback
+hide_title: true
+pageType: runbook
+journey: operate
+---
+
+<PageHeader
+  title="Recover from failed rollback"
+  lede="A failed rollback means blue-green automation stopped because continuing automatically could worsen Raft safety or cluster availability. Start with the status surface and the last failed rollback Job, then decide whether the right next step is a retry, a controlled pause for manual repair, or a restore from backup."
+/>
+
+<Checklist
+    title="Use this runbook when"
+    items={[
+      'a blue-green rollback enters break glass mode',
+      'the rollback consensus repair job failed and automation stopped',
+      'you need to decide whether the rollback can safely retry or needs manual repair',
+      'you need to restore from a recovery snapshot because rollback repair is no longer enough',
+    ]}
+  />
+
+
+<Callout type="failure" title="Do not try to downgrade around the failure">
+
+Do not force `spec.version` back to an older release to escape the incident. Downgrades are blocked for a reason. Repair the rollback surface first, then either let the operator continue safely or move into the dedicated restore workflow.
+
+</Callout>
+
+<DecisionTable
+  title="Choose the rollback recovery path"
+  columns={['Situation', 'Use this path', 'Why']}
+  rows={[
+    {
+      cells: [
+        'The rollback failed for a transient reason and the cluster is healthy again.',
+        'Retry the rollback by acknowledging the current break-glass nonce.',
+        'The operator already knows what work to retry; you only need to confirm the cluster is safe to continue.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'The cluster still needs manual Raft, workload, or infrastructure repair.',
+        'Pause reconciliation, repair manually, then resume with the nonce acknowledgment.',
+        'This keeps the operator from racing your repairs while you stabilize the cluster.',
+      ],
+    },
+    {
+      cells: [
+        'The cluster state is beyond safe rollback repair.',
+        'Restore from a recovery snapshot.',
+        'Restore is the explicit recovery path when continuing the rollback is no longer trustworthy.',
+      ],
+    },
+  ]}
+/>
+
+## Inspect break glass and blue-green state
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Capture the rollback failure surface"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{.status.breakGlass}' | jq
+kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{.status.blueGreen.phase}{"\\n"}{.status.blueGreen.lastJobFailure}{"\\n"}'
+kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\\n"}{end}'`}
+>
+  The expected break-glass pattern here is `reason=RollbackConsensusRepairFailed` while the blue-green phase is still in `RollingBack`.
+</CommandBlock>
+
+Break-glass reasons during rollback now map to two distinct failure surfaces:
+
+- `RollbackConsensusRepairFailed` usually means the rollback repair Job failed while the phase is still `RollingBack`.
+- `RollbackCleanupPeerRemovalFailed` usually means the cleanup Job that removes stale green peers failed while the phase is `RollbackCleanup`.
+
+## Inspect the failed rollback job and live cluster state
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the rollback job, Pods, and Raft peers"
+  code={`kubectl get jobs -n <namespace> -l openbao.org/cluster=<name>
+kubectl logs -n <namespace> job/<job-from-status>
+kubectl get pods -n <namespace> -l openbao.org/cluster=<name> -o wide
+kubectl exec -n <namespace> -it <pod-name> -- bao operator raft list-peers`}
+>
+  Look for network isolation between blue and green Pods, stuck or sealed Pods, peer membership that no longer matches the intended rollback topology, or executor-job failures that prevented the rollback from completing.
+</CommandBlock>
+
+If the break-glass reason is `RollbackCleanupPeerRemovalFailed`, verify that no stale green peers remain in Raft membership before you acknowledge the nonce. A retry will create a fresh rollback-cleanup attempt, so the live peer list needs to match the rollback intent first.
+
+<Callout type="note" title="Use maintenance mode before disruptive manual repair">
+
+If your repair requires deleting or restarting managed Pods and your admission policy expects the maintenance annotation, enable maintenance mode first and follow <SiteLink docId="user-guide/openbaocluster/operations/maintenance">Run Planned Maintenance</SiteLink>.
+
+</Callout>
+
+## Apply the recovery path that matches the diagnosis
+
+<Tabs groupId="failed-rollback-path">
+
+<TabItem value="retry" label="Retry the rollback">
+
+Use this when the failure was transient and the cluster is healthy again.
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Acknowledge the current break-glass nonce"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "breakGlassAck": "<NONCE_FROM_STATUS>"
+  }
+}'`}
+/>
+
+Then watch the replacement rollback Job and `status.blueGreen.phase` until the rollback either completes or enters a new break-glass event with a new nonce.
+
+</TabItem>
+
+<TabItem value="pause" label="Pause and repair">
+
+Use this when the cluster needs manual repair before any automation should continue.
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Pause reconciliation before manual repair"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "paused": true
+  }
+}'`}
+/>
+
+After you repair the cluster, resume reconciliation and acknowledge the current nonce in the same change:
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Resume reconciliation after repair"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "paused": false,
+    "breakGlassAck": "<NONCE_FROM_STATUS>"
+  }
+}'`}
+/>
+
+</TabItem>
+
+<TabItem value="restore" label="Restore from backup">
+
+Use this when the rollback surface is no longer safe to repair in place.
+
+1. stop any further automation
+2. identify the snapshot selected for recovery
+3. follow <SiteLink docId="user-guide/openbaorestore/recovery-restore-after-upgrade">Recover After Upgrade Restore</SiteLink>
+
+</TabItem>
+
+</Tabs>
+
+## Reduce repeat rollback failures
+
+- enable pre-upgrade snapshots with `spec.upgrade.preUpgradeSnapshot=true` or `spec.upgrade.blueGreen.preUpgradeSnapshot=true`
+- verify backup destination and backup auth before the upgrade window starts
+- monitor `status.blueGreen.phase`, `status.blueGreen.lastJobFailure`, and cluster health throughout the rollout
+
+<NextActions
+  title="Continue with the right recovery path"
+  items={[
+    {
+      label: 'Enter safe mode',
+      description: 'Inspect and acknowledge the break-glass nonce only after the rollback surface is actually repaired.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+    {
+      label: 'Recover after upgrade restore',
+      description: 'Use the override-lock restore path when the rollback or upgrade state blocks the ordinary restore workflow.',
+      docId: 'user-guide/openbaorestore/recovery-restore-after-upgrade',
+    },
+    {
+      label: 'Run planned maintenance',
+      description: 'Use the maintenance workflow when you need explicit, admission-safe manual repair windows.',
+      docId: 'user-guide/openbaocluster/operations/maintenance',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/index.mdx b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/index.mdx
new file mode 100644
index 000000000..6e312d4f4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/index.mdx
@@ -0,0 +1,132 @@
+---
+title: Recovery & Restore
+slug: /recover
+hide_title: true
+pageType: landing
+journey: operate
+description: Choose the right incident recovery or backup-driven restore path when routine troubleshooting is no longer enough.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Operate / Recovery & Restore"
+  title="Recovery and restore"
+  lede="Incident recovery and backup-driven restore workflows for clusters that need focused recovery steps or an explicit `OpenBaoRestore` request."
+  actions={[
+    {label: 'Run a restore', docId: 'user-guide/openbaorestore/restore', variant: 'primary'},
+    {label: 'Enter safe mode', docId: 'user-guide/openbaocluster/recovery/safe-mode', variant: 'secondary'},
+  ]}
+>
+  <Checklist
+    title="Use recovery to"
+    items={[
+      'decide whether the cluster still has a normal repair path',
+      'move from incident diagnosis into a narrow recovery runbook',
+      'restore state from backup with a clear view of the destructive impact',
+      'return the cluster to normal operations only after the status surface is clean again',
+    ]}
+  />
+</PageHero>
+
+<DecisionTable
+  title="Choose the right path"
+  columns={['Situation', 'Start here', 'Why']}
+  rows={[
+    {
+      cells: [
+        'The cluster lost leadership, sealed unexpectedly, or entered break-glass mode after a failed change.',
+        'Incident recovery',
+        'You still want to repair the live cluster state rather than replace it.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'The safest route is to reintroduce known-good state from object storage.',
+        'Restore from backup',
+        'Restore is explicit, destructive, and auditable instead of being hidden inside normal reconciliation.',
+      ],
+    },
+    {
+      cells: [
+        'You are still diagnosing the failure and do not know whether repair or restore is necessary.',
+        'Troubleshoot the cluster first',
+        'Do not jump into a destructive path before you know whether a narrower fix is still available.',
+      ],
+    },
+  ]}
+/>
+
+<RouteList
+  title="Incident recovery"
+  items={[
+    {
+      eyebrow: '01',
+      title: 'Enter safe mode',
+      description: 'Stabilize the cluster and stop risky automation when the operator needs explicit human acknowledgment.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+    {
+      eyebrow: '02',
+      title: 'Recover from no leader',
+      description: 'Repair quorum and leadership when Raft can no longer elect or keep a leader.',
+      docId: 'user-guide/openbaocluster/recovery/no-leader',
+    },
+    {
+      eyebrow: '03',
+      title: 'Recover a sealed cluster',
+      description: 'Diagnose trust, seal, network, or identity failures that leave Pods running but not serving.',
+      docId: 'user-guide/openbaocluster/recovery/sealed-cluster',
+    },
+    {
+      eyebrow: '04',
+      title: 'Recover from failed rollback',
+      description: 'Use the dedicated upgrade-recovery path when blue-green rollback automation stops in break glass mode.',
+      docId: 'user-guide/openbaocluster/recovery/failed-rollback',
+    },
+  ]}
+/>
+
+<RouteList
+  title="Restore from backup"
+  items={[
+    {
+      eyebrow: '05',
+      title: 'Run a restore',
+      description: 'Apply an `OpenBaoRestore` request when you intentionally need to overwrite cluster state from a snapshot.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+    {
+      eyebrow: '06',
+      title: 'Restore overview',
+      description: 'Understand why restore is modeled as an explicit CRD-backed operation and what safety boundaries it enforces.',
+      docId: 'user-guide/openbaorestore/overview',
+    },
+    {
+      eyebrow: '07',
+      title: 'Recover after upgrade restore',
+      description: 'Use the override-lock path only when a failed upgrade or rollback blocks the normal restore workflow.',
+      docId: 'user-guide/openbaorestore/recovery-restore-after-upgrade',
+    },
+  ]}
+/>
+
+<NextActions
+  items={[
+    {
+      label: 'Troubleshoot the cluster',
+      description: 'Go back to the symptom-driven incident guide when you still need to narrow the failure before choosing recovery.',
+      docId: 'user-guide/openbaocluster/operations/troubleshooting',
+    },
+    {
+      label: 'Check backup readiness',
+      description: 'Recovery depends on the snapshot path already being healthy before the incident starts.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      label: 'Open status and events',
+      description: 'Use the reference material when you need exact condition and event semantics during triage.',
+      docId: 'reference/status-and-events',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/no-leader.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/no-leader.md
new file mode 100644
index 000000000..c1b7fc1a5
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/no-leader.md
@@ -0,0 +1,218 @@
+---
+title: Recover from No Leader
+description: Diagnose whether quorum loss comes from pod health, network isolation, stale peers, or a last-resort manual Raft recovery path.
+slug: /recover/no-leader
+hide_title: true
+pageType: runbook
+journey: operate
+---
+
+<PageHeader
+  title="Diagnose no-leader conditions before manual Raft recovery"
+  lede="A no-leader incident can come from crash-looping pods, blocked cluster traffic, or stale peers that still count toward quorum. Use this runbook to narrow the failure mode and decide whether a manual quorum-recovery path is actually required."
+/>
+
+<Checklist
+    title="Use this runbook when"
+    items={[
+      'the cluster cannot elect or keep a leader',
+      'Raft commands time out or report no leader elected',
+      'pods are running but the cluster still cannot form quorum',
+      'you need to decide whether a stale peer, network break, or manual recovery path is required',
+    ]}
+  />
+
+
+<DecisionTable
+  title="Match the failure mode"
+  columns={['Signal', 'Start with', 'Why']}
+  rows={[
+    {
+      cells: [
+        'Pods are crash-looping or never become ready.',
+        'Fix pod health, storage, or config first.',
+        'Quorum cannot recover while one or more members are not healthy enough to participate in Raft.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`raft list-peers` hangs or returns transport errors.',
+        'Check network reachability and DNS on the cluster port.',
+        'A healthy Raft set still fails if members cannot talk to each other on the internal cluster address.',
+      ],
+    },
+    {
+      cells: [
+        'A failed or stale member still appears in the peer list.',
+        'Remove the dead peer from a healthy node.',
+        'The cluster may be counting a non-existent member toward quorum.',
+      ],
+    },
+    {
+      cells: [
+        'No node can form quorum and there is no healthy leader to remove peers from.',
+        'Use manual quorum recovery with `peers.json` as a last resort.',
+        'This is destructive. Use it only when automatic recovery is no longer possible.',
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="No-leader decision flow"
+  caption="Check pod health first, then verify the cluster network, then decide whether this is a stale-peer cleanup or a manual quorum-recovery event."
+  code={`flowchart TD
+    Start["No leader"] --> Pods{"Pods healthy?"}
+    Pods -- "No" --> FixPods["Repair crashes, PVCs, or config"]
+    Pods -- "Yes" --> Net{"Cluster port reachable?"}
+    Net -- "No" --> FixNet["Repair DNS, NetworkPolicy, or routing"]
+    Net -- "Yes" --> Peers{"Stale peer in raft list?"}
+    Peers -- "Yes" --> RemovePeer["Remove dead peer from healthy node"]
+    Peers -- "No" --> Quorum{"Any node can still form quorum?"}
+    Quorum -- "Yes" --> Inspect["Inspect logs and conditions again"]
+    Quorum -- "No" --> Manual["Manual quorum recovery with peers.json"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Start,Pods,Net,Peers,Quorum read;
+    class FixPods,FixNet,Inspect process;
+    class RemovePeer,Manual write;`}
+/>
+
+## Inspect pod health and the Raft view
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Capture pod and peer state"
+  code={`kubectl get pods -n <namespace> -l openbao.org/cluster=<name> -o wide
+kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\\n"}{end}'
+kubectl exec -n <namespace> -it <pod-name> -- bao operator raft list-peers`}
+>
+  Run the Raft peer command from each healthy Pod. Different peer views between nodes usually point to a transport or membership problem rather than a generic application issue.
+</CommandBlock>
+
+If Pods are `CrashLoopBackOff`, resolve the pod-level failure first. Quorum recovery does not help when the underlying member still cannot boot, mount storage, or load configuration.
+
+## Verify the cluster network path
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Check the Raft transport path"
+  code={`kubectl exec -n <namespace> -it <pod-a> -- nc -zv <pod-b>.<headless-service> 8201
+kubectl exec -n <namespace> -it <pod-a> -- nslookup <pod-b>.<headless-service>`}
+>
+  Use the actual cluster port if you changed it from the default. Failed DNS or blocked port `8201` is enough to make a healthy cluster look like a quorum failure.
+</CommandBlock>
+
+Check these first when the transport path is broken:
+
+- `NetworkPolicy` rules that allow cluster-to-cluster traffic
+- service and headless-service DNS resolution
+- sidecar or mesh policies that may block direct Pod-to-Pod communication
+
+## Remove a stale peer when quorum is almost healthy
+
+Use this path only when one healthy node can still answer Raft commands and the peer list clearly shows a dead member that should no longer count toward quorum.
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Remove a dead peer from the Raft set"
+  code={`kubectl exec -n <namespace> -it <healthy-pod> -- \\
+  bao operator raft remove-peer -id "<dead-peer-id>"`}
+/>
+
+After removing the peer, re-run `bao operator raft list-peers` from the same node and watch the `OpenBaoCluster` conditions until a leader is present again.
+
+## Use manual quorum recovery only as a last resort
+
+<Callout type="danger" title="Manual quorum recovery can discard newer state">
+
+Creating `peers.json` forces one survivor to bootstrap a new one-node Raft cluster. If you pick a node that was behind, you can lose data that only existed on another member. Use this path only when normal quorum recovery is no longer possible.
+
+</Callout>
+
+Before you start:
+
+- stop the operator so it does not race your manual changes
+- choose the Pod with the most recent and trustworthy data
+- record which Pods you plan to restart and how you will rejoin them afterward
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Stop operator reconciliation before manual recovery"
+  code={`kubectl scale deploy <controller-deployment> -n <operator-namespace> --replicas=0`}
+/>
+
+<CommandBlock
+  language="json"
+  label="configure"
+  title="Create a one-node peers.json file"
+  code={`[
+  {
+    "id": "<survivor-pod-name>",
+    "address": "<survivor-pod-name>.<headless-service>:8201",
+    "non_voter": false
+  }
+]`}
+>
+  Save this file locally as `peers.json`, replacing the Pod name and address with the survivor you selected.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Copy peers.json to the survivor and restart it"
+  code={`kubectl cp peers.json <namespace>/<survivor-pod-name>:/bao/data/raft/peers.json
+kubectl delete pod -n <namespace> <survivor-pod-name>`}
+/>
+
+When the survivor returns:
+
+1. verify it now reports a leader-capable state
+2. unseal it if required
+3. delete the remaining Pods so they rejoin against the new leader
+4. restart the operator deployment
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Resume normal operations after manual recovery"
+  code={`kubectl exec -n <namespace> -it <survivor-pod-name> -- bao operator raft list-peers
+kubectl delete pod -n <namespace> <other-pod-1> <other-pod-2>
+kubectl scale deploy <controller-deployment> -n <operator-namespace> --replicas=1`}
+/>
+
+## Close out the incident deliberately
+
+If the operator entered break glass during the failure, inspect the break-glass status and only acknowledge it after quorum, sealing, and workload health are all stable again.
+
+See <SiteLink docId="user-guide/openbaocluster/recovery/safe-mode">Enter Safe Mode</SiteLink> for the acknowledgment flow.
+
+<NextActions
+  title="Continue with the right recovery path"
+  items={[
+    {
+      label: 'Enter safe mode',
+      description: 'Inspect the break-glass nonce and resume automation only after the cluster is stable again.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+    {
+      label: 'Recover a sealed cluster',
+      description: 'Switch to the seal-focused runbook when Pods are up but trust or unseal dependencies still block service.',
+      docId: 'user-guide/openbaocluster/recovery/sealed-cluster',
+    },
+    {
+      label: 'Run a restore',
+      description: 'Use the restore workflow if live-cluster repair is no longer the safest option.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/safe-mode.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/safe-mode.md
new file mode 100644
index 000000000..094707ee3
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/safe-mode.md
@@ -0,0 +1,155 @@
+---
+title: Enter Safe Mode
+description: Inspect break-glass status, repair the underlying failure, and acknowledge the nonce only after the cluster is safe to resume.
+slug: /recover/safe-mode
+hide_title: true
+pageType: runbook
+journey: operate
+---
+
+<PageHeader
+  title="Safe mode and break-glass recovery"
+  lede="Break glass or safe mode is the operator's explicit stop signal when continuing rollback automation could make availability or Raft safety worse. Use this page to inspect the break-glass state, stabilize the cluster, repair the failure, and then resume automation."
+/>
+
+<Checklist
+    title="Use this runbook when"
+    items={[
+      'the operator reports break glass or safe mode on the cluster',
+      'rollback automation stopped because continuing automatically is unsafe',
+      'you need a clear pause before restarting pods or modifying Raft state',
+      'you are ready to acknowledge a nonce only after the underlying issue is fixed',
+    ]}
+  />
+
+
+<DecisionTable
+  title="What safe mode means"
+  columns={['Signal', 'What the operator is doing', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'Risky automation halted',
+        'The operator stops the affected upgrade or rollback workflow instead of pushing forward blindly.',
+        'This is the point where a human has to evaluate whether the live cluster is still repairable.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'status.breakGlass populated',
+        'The cluster status contains the reason, message, nonce, and suggested next checks.',
+        'Start with that status so the recovery path follows the recorded failure reason and suggested checks.',
+      ],
+    },
+    {
+      cells: [
+        'Manual acknowledgment required',
+        'Automation stays paused until `spec.breakGlassAck` matches the current nonce.',
+        'Acknowledgment is the explicit signal that you have repaired the issue and accept resumed automation.',
+      ],
+    },
+  ]}
+/>
+
+## Inspect the break-glass state
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Read the break-glass status"
+  code={`kubectl get openbaocluster <name> -n <namespace> -o jsonpath='{.status.breakGlass}' | jq`}
+/>
+
+<CommandBlock
+  language="json"
+  label="output"
+  title="Typical break-glass payload"
+  code={`{
+  "active": true,
+  "reason": "RollbackConsensusRepairFailed",
+  "message": "Rollback consensus repair Job upgrade-prod-cluster-rollback-retry-1 failed; manual intervention required.",
+  "nonce": "abc-123-def-456",
+  "steps": [
+    "Inspect rollback Job logs",
+    "Inspect pod status",
+    "Perform any required Raft recovery steps, then acknowledge the nonce"
+  ]
+}`}
+>
+  The `reason`, `message`, and `steps` fields are the fastest way to decide whether you are looking at an upgrade rollback problem, a cleanup failure after rollback, a Raft recovery problem, or a broader cluster-health issue.
+</CommandBlock>
+
+For blue-green rollback incidents, the most common reasons are:
+
+- `RollbackConsensusRepairFailed`: the operator could not complete the rollback repair path while the cluster was still in `RollingBack`.
+- `RollbackCleanupPeerRemovalFailed`: the rollback itself converged far enough to enter `RollbackCleanup`, but the peer-removal cleanup job failed and automation stopped before stale green peers were safely removed.
+
+## Repair the underlying issue
+
+Start with the operator-visible status and the last failed job, then move into the narrower runbook that matches the cluster state.
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Capture the current failure surface"
+  code={`kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\\n"}{end}'
+kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{.status.blueGreen.lastJobFailure}{"\\n"}'
+kubectl logs -n <namespace> job/<job-from-status>
+kubectl get pods -n <namespace> -l openbao.org/cluster=<name> -o wide
+kubectl exec -n <namespace> -it <pod-name> -- bao operator raft list-peers`}
+>
+  These commands tell you whether the failure is still centered on the rollback job, whether the Pods are actually healthy, and whether Raft membership is still coherent enough for a safe retry.
+</CommandBlock>
+
+<Callout type="note" title="Use maintenance mode for controlled manual repair">
+
+If you need to restart or delete managed Pods while admission policies require the `openbao.org/maintenance=true` signal, enable maintenance mode first and follow <SiteLink docId="user-guide/openbaocluster/operations/maintenance">Run Planned Maintenance</SiteLink>.
+
+</Callout>
+
+If the cluster needs a deeper incident path, move directly into the matching runbook instead of staying in generic safe mode:
+
+- <SiteLink docId="user-guide/openbaocluster/recovery/failed-rollback">Recover from failed rollback</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/recovery/no-leader">Recover from no leader</SiteLink>
+- <SiteLink docId="user-guide/openbaocluster/recovery/sealed-cluster">Recover a sealed cluster</SiteLink>
+
+## Acknowledge and resume automation
+
+Only acknowledge the nonce after the cluster is healthy enough for the operator to continue the paused workflow.
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Acknowledge the current nonce"
+  code={`kubectl patch openbaocluster <name> -n <namespace> --type merge -p '{
+  "spec": {
+    "breakGlassAck": "<NONCE_FROM_STATUS>"
+  }
+}'`}
+>
+  If the operator re-enters break glass later, it will issue a new nonce. Always use the current value from `status.breakGlass.nonce`, not a previously copied one.
+</CommandBlock>
+
+<NextActions
+  title="Go deeper"
+  items={[
+    {
+      label: 'Recover from failed rollback',
+      description: 'Use the rollback-specific runbook when the break-glass reason is tied to blue-green rollback repair.',
+      docId: 'user-guide/openbaocluster/recovery/failed-rollback',
+    },
+    {
+      label: 'Recover from no leader',
+      description: 'Switch here when the cluster cannot elect or keep a leader after the rollback failure.',
+      docId: 'user-guide/openbaocluster/recovery/no-leader',
+    },
+    {
+      label: 'Recover a sealed cluster',
+      description: 'Use the seal-focused path when Pods are running but trust or unseal dependencies still block service.',
+      docId: 'user-guide/openbaocluster/recovery/sealed-cluster',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/sealed-cluster.md b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/sealed-cluster.md
new file mode 100644
index 000000000..58831b75d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaocluster/recovery/sealed-cluster.md
@@ -0,0 +1,281 @@
+---
+title: Recover a Sealed Cluster
+description: Separate seal, trust, identity, and reachability failures so you can restore service before moving into deeper quorum recovery.
+slug: /recover/sealed-cluster
+hide_title: true
+pageType: runbook
+journey: operate
+---
+
+<PageHeader
+  title="Diagnose a sealed cluster"
+  lede="A sealed cluster usually means the Pods can start but cannot complete the configured trust or unseal path they need to serve traffic. Use this runbook to start with operator-visible conditions, then narrow the problem by seal mode and move to emergency manual unseal only if needed."
+/>
+
+<Checklist
+    title="Use this runbook when"
+    items={[
+      'Pods are running but remain sealed and not ready',
+      'the cluster reports `OpenBaoSealed=True`',
+      'cloud KMS, transit, TLS, or static-key dependencies might be blocking startup',
+      'you need to decide whether this is a seal problem or a broader quorum problem',
+    ]}
+  />
+
+
+<DecisionTable
+  title="Read the first conditions"
+  columns={['Condition or signal', 'What it usually means', 'Where to look next']}
+  rows={[
+    {
+      cells: [
+        '`OpenBaoSealed=True` while Pods are running',
+        'The workload is up far enough to report status, but the unseal path is still blocked.',
+        'Check the configured seal mode and the corresponding credentials or trust material.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`CloudUnsealIdentityReady=False`',
+        'The workload identity or cloud credentials for a cloud KMS backend are not usable.',
+        'Inspect the identity binding, IAM policy, and KMS reachability.',
+      ],
+    },
+    {
+      cells: [
+        '`TLSReady=False`',
+        'The cluster may not trust the configured certificates or may be missing required TLS material.',
+        'Inspect the rendered TLS Secrets and pod logs for `x509` errors.',
+      ],
+    },
+    {
+      cells: [
+        'The cluster unseals but still does not become active.',
+        'This may no longer be a seal problem.',
+        <>Move to <SiteLink docId="user-guide/openbaocluster/recovery/no-leader">Recover from No Leader</SiteLink>.</>,
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Sealed-cluster triage"
+  caption="Confirm the cluster is actually sealed, identify the configured seal mode, then narrow the failure to credentials, trust, or network before using any emergency manual path."
+  code={`flowchart TD
+    Start["Pods running but sealed"] --> Conditions["Check operator conditions"]
+    Conditions --> Mode{"Which seal mode?"}
+    Mode -- "Static" --> Static["Verify Secret exists and key name is correct"]
+    Mode -- "Transit" --> Transit["Verify transit auth, TLS, and network path"]
+    Mode -- "Cloud KMS" --> KMS["Verify workload identity, IAM, and endpoint reachability"]
+    Mode -- "KMIP / PKCS#11" --> External["Verify device, library, certs, and connectivity"]
+    Static --> Healthy{"Unseals?"}
+    Transit --> Healthy
+    KMS --> Healthy
+    External --> Healthy
+    Healthy -- "No" --> Manual["Manual unseal only for emergency access"]
+    Healthy -- "Yes, but no leader" --> Leader["Switch to no-leader recovery"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Start,Conditions,Mode read;
+    class Static,Transit,KMS,External process;
+    class Manual,Leader write;`}
+/>
+
+## Inspect the operator-visible state first
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Read the current conditions and seal mode"
+  code={`kubectl get openbaocluster <name> -n <namespace> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\\n"}{end}'
+kubectl get openbaocluster <name> -n <namespace> -o yaml | yq '.spec.unseal'
+kubectl logs -n <namespace> <pod-name> | grep -i unseal`}
+>
+  Focus on `OpenBaoSealed`, `CloudUnsealIdentityReady`, and `TLSReady`. These usually tell you whether the next step is credentials, trust, or network rather than generic application debugging.
+</CommandBlock>
+
+## Diagnose by seal mode
+
+<Tabs groupId="sealed-cluster-diagnostics">
+
+<TabItem value="static" label="Static">
+
+Use this path when the cluster reads its unseal key from a Kubernetes Secret.
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Verify the static unseal Secret"
+  code={`kubectl get secret -n <namespace> <cluster-name>-unseal-key
+kubectl get secret -n <namespace> <cluster-name>-unseal-key -o jsonpath='{.data}'`}
+>
+  The Secret must exist and use the expected key name `key`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create or replace the static unseal Secret"
+  code={`kubectl create secret generic <cluster-name>-unseal-key -n <namespace> \\
+  --from-literal=key=<UNSEAL_KEY> \\
+  --dry-run=client -o yaml | kubectl apply -f -`}
+/>
+
+</TabItem>
+
+<TabItem value="transit" label="Transit">
+
+Use this path when the cluster unseals through another OpenBao deployment.
+
+<DecisionTable
+  title="Transit-specific failure signals"
+  columns={['Signal', 'Likely cause', 'Fix first']}
+  rows={[
+    {
+      cells: [
+        '`permission denied` or auth failures',
+        'The token, auth path, or transit policy is wrong.',
+        'Replace the credentials Secret and verify the transit-side role or policy.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`x509` or trust-chain errors',
+        'The transit CA or client certificate material does not match the endpoint.',
+        'Reconcile the Secret contents and referenced TLS file paths.',
+      ],
+    },
+    {
+      cells: [
+        '`context deadline exceeded`',
+        'The transit endpoint is not reachable from the workload.',
+        'Check DNS, egress rules, and the remote endpoint health.',
+      ],
+    },
+  ]}
+/>
+
+</TabItem>
+
+<TabItem value="cloud-kms" label="Cloud KMS">
+
+Use this path for AWS KMS, GCP Cloud KMS, Azure Key Vault, or OCI KMS unseal backends.
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect cloud-unseal failures in the logs"
+  code={`kubectl logs -n <namespace> <pod-name> | grep -Ei 'unseal|kms|decrypt|accessdenied|forbidden|timeout'`}
+/>
+
+<DecisionTable
+  title="Cloud KMS failure patterns"
+  columns={['Log or condition', 'Likely cause', 'Fix first']}
+  rows={[
+    {
+      cells: [
+        '`CloudUnsealIdentityReady=False` or `AccessDenied`',
+        'The workload identity or IAM policy is not allowed to decrypt.',
+        'Fix the ServiceAccount binding and grant the decrypt permission on the configured key.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`context deadline exceeded`',
+        'The cluster cannot reach the KMS endpoint.',
+        'Check egress rules, proxy behavior, firewall policy, and DNS.',
+      ],
+    },
+    {
+      cells: [
+        'Provider-side `5xx` errors',
+        'The KMS service itself may be degraded.',
+        'Confirm regional health and retry only when the upstream service is stable.',
+      ],
+    },
+  ]}
+/>
+
+</TabItem>
+
+<TabItem value="kmip-pkcs11" label="KMIP / PKCS#11">
+
+Use this path for external HSM or KMIP-backed unseal modes.
+
+Check these first:
+
+- referenced client certificate, key, and CA material
+- library and device mount paths for `pkcs11`
+- network reachability to the KMIP endpoint
+- rendered seal configuration inside the Pod
+
+These modes do not report `CloudUnsealIdentityReady`, so pod logs and rendered configuration are the primary signal surface.
+
+</TabItem>
+
+<TabItem value="manual" label="Manual emergency">
+
+<Callout type="danger" title="Emergency only">
+
+Manual unseal is the escape hatch when automation is broken and you need immediate access. It does not fix the underlying seal path. Use it to regain access, then repair the actual trust or credential dependency.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Manually unseal a Pod"
+  code={`kubectl exec -n <namespace> -it <pod-name> -- sh
+bao operator unseal`}
+>
+  Repeat this on every Pod that needs to join the active cluster. If the cluster then stays sealed again after restart, return to the relevant automated seal mode and fix it there.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+## Verify the cluster is actually serving again
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check seal status and cluster readiness"
+  code={`kubectl get openbaocluster <name> -n <namespace>
+kubectl exec -n <namespace> -it <pod-name> -- bao status`}
+/>
+
+If the cluster unseals but only reaches standby state or still cannot elect a leader, move to <SiteLink docId="user-guide/openbaocluster/recovery/no-leader">Recover from No Leader</SiteLink>.
+
+<NextActions
+  title="Continue with the right recovery path"
+  items={[
+    {
+      label: 'Unseal configuration',
+      description: 'Return to the exact provider and Secret contract when the incident came from wrong credential shape or mounted file paths.',
+      docId: 'user-guide/openbaocluster/configuration/unseal',
+    },
+    {
+      label: 'Recover from no leader',
+      description: 'Switch here when sealing is fixed but the cluster still cannot elect or keep a leader.',
+      docId: 'user-guide/openbaocluster/recovery/no-leader',
+    },
+    {
+      label: 'Enter safe mode',
+      description: 'Inspect and acknowledge break glass only after the seal path and workload health are stable.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+    {
+      label: 'Run a restore',
+      description: 'Use the restore workflow if the live cluster is no longer the safest path to service recovery.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/overview.md b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/overview.md
new file mode 100644
index 000000000..112332ac4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/overview.md
@@ -0,0 +1,157 @@
+---
+title: Restore Overview
+description: Understand when restore is appropriate, why it is modeled as OpenBaoRestore, and which safety boundaries it enforces.
+hide_title: true
+pageType: concept
+journey: operate
+---
+
+<PageHeader
+  title="Restore workflow overview"
+  lede="Restore is modeled as `OpenBaoRestore`, an immutable request object that keeps disaster recovery visible, auditable, and separate from normal cluster reconciliation. Use this page to understand when restore is appropriate and what boundaries it enforces."
+/>
+
+
+
+<DecisionTable
+  title="Use restore when"
+  columns={['Situation', 'Why restore fits', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Disaster recovery',
+        'You need to reintroduce known-good state after severe corruption, cluster loss, or a failed repair path.',
+        'Restore overwrites the target cluster. Validate the snapshot and target as part of request preparation.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Environment cloning',
+        'You want to move a realistic snapshot of production state into staging or another controlled environment.',
+        'Be deliberate about secrets, tokens, and any sensitive data you are copying.',
+      ],
+    },
+    {
+      cells: [
+        'Migration between clusters or regions',
+        'The restore workflow gives you an explicit, auditable way to land snapshot state on a different target cluster.',
+        'The target cluster must already exist and the storage/auth path must work from that environment.',
+      ],
+    },
+    {
+      cells: [
+        'Ordinary troubleshooting',
+        'Use the incident recovery or troubleshooting guides unless snapshot restore is already the selected recovery action.',
+        'Restore remains a destructive action while narrower repair paths are still viable.',
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Restore control flow"
+  caption="A restore request is validated, acquires the cluster operation lock, then launches a restore Job that pulls the snapshot and injects it into the target cluster. The explicit request keeps destructive recovery separate from normal reconciliation."
+  code={`flowchart LR
+    Request["OpenBaoRestore request"] --> Validate["Validate target, source, and auth"]
+    Validate --> Lock["Acquire restore lock"]
+    Lock --> Job["Launch restore Job"]
+    Job --> Pull["Pull snapshot from object storage"]
+    Pull --> Apply["Restore into target OpenBao cluster"]
+    Apply --> Status["Record terminal status and release lock"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Request,Validate read;
+    class Lock,Job,Pull,Apply process;
+    class Status write;`}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="What OpenBaoRestore guarantees"
+  columns={['Contract', 'Why it exists']}
+  rows={[
+    {
+      cells: [
+        'Explicit request object',
+        'Restore is visible and auditable instead of being hidden inside cluster status or imperative scripts.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Immutable spec',
+        'Changing restore intent requires a new request so the audit trail stays stable and the controller does not reinterpret a running job.',
+      ],
+    },
+    {
+      cells: [
+        'Operation lock ownership',
+        'Restore blocks conflicting upgrades and backups while destructive work is in flight.',
+      ],
+    },
+    {
+      cells: [
+        'Separate restore identity',
+        'The restore Job authenticates separately from the main workload so recovery credentials are deliberate rather than inherited accidentally.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Restore overwrites cluster state">
+
+Restore is not a read-only diagnostic step. It replaces the target cluster state with the contents of the selected snapshot and may still leave the cluster needing follow-up work such as unseal or Raft repair.
+
+</Callout>
+
+## Minimal restore request
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create a minimal OpenBaoRestore request"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoRestore
+metadata:
+  name: prod-restore
+  namespace: security
+spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: s3
+      endpoint: https://s3.amazonaws.com
+      bucket: openbao-backups
+      region: us-east-1
+      credentialsSecretRef:
+        name: s3-credentials
+    key: clusters/prod/backup-2026-03-20.snap
+  jwtAuthRole: openbao-operator-restore`}
+>
+  The target `OpenBaoCluster` and the `OpenBaoRestore` request live in the same namespace. To change the restore intent later, create a new resource instead of editing the running one.
+</CommandBlock>
+
+<NextActions
+  title="Continue with the restore path"
+  items={[
+    {
+      label: 'Run a restore',
+      description: 'Use the task page when you are ready to configure the source, auth path, and verification steps in full.',
+      docId: 'user-guide/openbaorestore/restore',
+    },
+    {
+      label: 'Recover after upgrade restore',
+      description: 'Use the override-lock runbook if a failed upgrade blocks the normal restore workflow.',
+      docId: 'user-guide/openbaorestore/recovery-restore-after-upgrade',
+    },
+    {
+      label: 'Restore manager architecture',
+      description: 'See how validation, operation locks, and restore job execution fit together inside the controller.',
+      docId: 'architecture/restore-manager',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/recovery-restore-after-upgrade.md b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/recovery-restore-after-upgrade.md
new file mode 100644
index 000000000..56c8961af
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/recovery-restore-after-upgrade.md
@@ -0,0 +1,128 @@
+---
+title: Recover After Upgrade Restore
+description: Use the override-lock restore path when a failed upgrade or rollback blocks the normal restore workflow.
+hide_title: true
+pageType: runbook
+journey: operate
+---
+
+<PageHeader
+  title="Override-lock restore after a failed upgrade"
+  lede="This runbook covers the case where the normal restore path is blocked by an existing cluster operation lock, usually after a failed rollback or another crashed automation loop. Use it for recovery when the restore request cannot proceed through the normal lock path."
+/>
+
+<Checklist
+    title="Use this runbook when"
+    items={[
+      'the cluster is stuck behind an operation lock after a failed upgrade or rollback',
+      'a normal OpenBaoRestore request is blocked by that lock',
+      'you accept that the current cluster state will be overwritten by the snapshot',
+      'you already identified the last known good snapshot you are willing to restore',
+    ]}
+  />
+
+
+<Callout type="danger" title="This bypasses the existing operation lock">
+
+This path ignores the current lock owner, overwrites cluster state with the selected snapshot, and is meant for disaster recovery under operator supervision. Do not use it when the normal restore workflow is still available.
+
+</Callout>
+
+<DecisionTable
+  title="Know what this override changes"
+  columns={['Field', 'What it does', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        '`force: true`',
+        'Allows restore to proceed on an unhealthy cluster.',
+        'You are explicitly acknowledging that normal safety checks are being relaxed for recovery.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`overrideOperationLock: true`',
+        'Clears the existing cluster operation lock so restore can proceed.',
+        'This field marks the request as an override path rather than a routine restore.',
+      ],
+    },
+    {
+      cells: [
+        '`spec.breakGlassAck` on OpenBaoCluster',
+        'May still be required later if the cluster remains in break-glass mode after restore.',
+        'The restore override is separate from the cluster break-glass acknowledgment flow.',
+      ],
+    },
+  ]}
+/>
+
+## Create the override restore request
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Force restore past an existing operation lock"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoRestore
+metadata:
+  name: emergency-restore-001
+  namespace: security
+spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: s3
+      endpoint: https://s3.amazonaws.com
+      bucket: openbao-backups
+      region: us-east-1
+      credentialsSecretRef:
+        name: s3-credentials
+    key: clusters/prod/last-good-snapshot.snap
+  jwtAuthRole: openbao-operator-restore
+  force: true
+  overrideOperationLock: true`}
+>
+  `force` is required when restore targets an unhealthy cluster. `overrideOperationLock` bypasses the stuck upgrade or backup lock. Together they define the override request.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the override restore"
+  code={`kubectl apply -f emergency-restore.yaml`}
+/>
+
+## Verify the restore and plan the follow-up
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Inspect restore and cluster state"
+  code={`kubectl get openbaorestore <name> -n <namespace> -o yaml
+kubectl describe openbaocluster <cluster> -n <namespace>
+kubectl get jobs -n <namespace>`}
+>
+  A completed restore means the restore workflow finished. The target cluster may still require unseal, Raft repair, or break-glass acknowledgment before it is ready for service again.
+</CommandBlock>
+
+<NextActions
+  title="Finish the recovery"
+  items={[
+    {
+      label: 'Recover a sealed cluster',
+      description: 'Use this when the restored workload starts but cannot unseal cleanly.',
+      docId: 'user-guide/openbaocluster/recovery/sealed-cluster',
+    },
+    {
+      label: 'Recover from no leader',
+      description: 'Use this when the restored snapshot leaves the cluster needing Raft peer or quorum repair.',
+      docId: 'user-guide/openbaocluster/recovery/no-leader',
+    },
+    {
+      label: 'Enter safe mode',
+      description: 'Go here when the operator still requires explicit break-glass acknowledgment after the restore completes.',
+      docId: 'user-guide/openbaocluster/recovery/safe-mode',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/restore.md b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/restore.md
new file mode 100644
index 000000000..d783cd7a0
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaorestore/restore.md
@@ -0,0 +1,351 @@
+---
+title: Restore from Backup
+description: Create an OpenBaoRestore request, configure snapshot access and restore auth, and verify the restore workflow.
+hide_title: true
+pageType: task
+journey: operate
+---
+
+<PageHeader
+  title="Restore from a snapshot"
+  lede="The operator restores snapshot state through an explicit `OpenBaoRestore` request. That request validates the target, acquires the restore operation lock, launches a dedicated restore Job, and records the outcome for audit. Use this page when snapshot restore is the right recovery workflow for the target cluster."
+/>
+
+
+
+<Callout type="danger" title="Restore overwrites the target cluster">
+
+Restore replaces the target cluster state with the contents of the selected snapshot. All current secrets, policies, auth methods, and keys in that cluster are treated as replaceable state. Verify the target namespace, target cluster, and snapshot key as part of the restore request.
+
+</Callout>
+
+<DecisionTable
+  title="First successful restore path"
+  columns={['Step', 'What to do first', 'What proves you are ready']}
+  rows={[
+    {
+      cells: [
+        '1. Prove the backup path first',
+        'Confirm the snapshot exists and that the backup storage and auth path already succeeded in the backup workflow.',
+        'You know the exact snapshot key and can point to a successful backup object in storage.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '2. Prepare the target cluster deliberately',
+        'Keep the target `OpenBaoCluster` in the same namespace, make sure it already exists, and confirm the restore Job can reach it.',
+        'The target cluster resource exists, the namespace is correct, and the restore Job can reach object storage.',
+      ],
+    },
+    {
+      cells: [
+        '3. Choose restore auth',
+        'Prefer JWT auth through `spec.selfInit.oidc.enabled=true` or a deliberate restore role. Use a static token only as a compatibility fallback.',
+        'You know whether the restore Job will use `jwtAuthRole` or `tokenSecretRef` and the referenced auth path already exists.',
+      ],
+    },
+    {
+      cells: [
+        '4. Watch the restore and cluster together',
+        'Apply the `OpenBaoRestore`, then inspect both the restore resource and the target cluster until the destructive step and follow-up recovery state are clear.',
+        'The restore reaches a terminal phase and you know whether the next step is normal service, unseal recovery, or Raft repair.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Choose the restore auth path"
+  columns={['Path', 'Use it when', 'Operator behavior', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'JWT auth',
+        'You already use `selfInit.oidc` or can provision a dedicated restore JWT role on the target cluster.',
+        'The restore Job uses a projected ServiceAccount token and authenticates with a short-lived, scoped identity.',
+        'Keep the JWT audience and bound ServiceAccount subject aligned with the restore role.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Static token',
+        'JWT auth is not available yet and you need a compatibility path for recovery.',
+        'The restore Job reads a long-lived OpenBao token from a Secret in the same namespace.',
+        'Store the token as a high-sensitivity credential and rotate it intentionally.',
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Restore execution path"
+  caption="The controller validates the request, acquires the restore lock, launches a restore Job, downloads the selected snapshot, and then forces the snapshot into the target cluster leader."
+  code={`flowchart LR
+    Request["OpenBaoRestore"] --> Validate["Validate target, source, and auth"]
+    Validate --> Lock["Acquire restore lock"]
+    Lock --> Job["Launch restore Job"]
+    Job --> Auth["Authenticate to target cluster"]
+    Auth --> Download["Download snapshot"]
+    Download --> Restore["POST /sys/storage/raft/snapshot-force"]
+    Restore --> Status["Record terminal phase and release lock"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Request,Validate read;
+    class Lock,Job,Auth,Download,Restore process;
+    class Status write;`}
+/>
+
+## Prepare the restore request
+
+- Make sure the snapshot you want already exists in object storage and has been validated as usable.
+- Create or keep the target `OpenBaoCluster` in the same namespace as the restore request. The target cluster must exist and be initialized, even if it is otherwise empty.
+- Verify the restore Job can reach the object storage endpoint. In hardened environments, this usually means explicit `spec.network.egressRules`.
+- Choose the restore auth path before the incident starts. The restore Job does not automatically inherit the cloud identity or auth material from the main OpenBao Pods.
+
+<Callout type="note" title="Same-namespace requirement">
+
+The `OpenBaoRestore`, the target `OpenBaoCluster`, and any referenced token Secrets all live in the same namespace. Cross-namespace references are intentionally blocked for security reasons.
+
+</Callout>
+
+<Callout type="tip" title="For most first-time restores">
+
+If the target cluster already uses `spec.selfInit.oidc.enabled=true`, start with `jwtAuthRole: openbao-operator-restore` and the same object-storage provider shape you already validated in the backup flow.
+That keeps the restore path aligned with the backup path you have already proven.
+
+</Callout>
+
+<Callout type="note" title="Restore drains and restores steady read replicas deliberately">
+
+When the target cluster has steady read replicas enabled, restore first drains that pool to zero, then launches the restore Job. After the snapshot is forced into the cluster, the operator restores the steady read pool and only marks the `OpenBaoRestore` as `Completed` once the read-replica conditions are healthy again.
+
+</Callout>
+
+## Configure the snapshot source
+
+<Tabs groupId="restore-source-provider">
+
+<TabItem value="s3" label="S3">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure an S3 or S3-compatible restore source"
+  code={`spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: s3
+      endpoint: https://s3.amazonaws.com
+      bucket: openbao-backups
+      region: us-east-1
+      usePathStyle: false
+      credentialsSecretRef:
+        name: s3-credentials
+    key: clusters/prod/backup-2026-03-20.snap`}
+>
+  The Secret can provide `accessKeyId`, `secretAccessKey`, `sessionToken`, `region`, and an optional `caCert` for custom trust chains.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="gcs" label="GCS">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure a Google Cloud Storage restore source"
+  code={`spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: gcs
+      bucket: openbao-backups
+      gcs:
+        project: my-gcp-project
+      credentialsSecretRef:
+        name: gcs-credentials
+    key: clusters/prod/backup-2026-03-20.snap`}
+>
+  The Secret typically contains `credentials.json`. You can also use a provider-default identity path when your environment already supports it.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="azure" label="Azure">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Configure an Azure Blob Storage restore source"
+  code={`spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: azure
+      bucket: openbao-backups
+      azure:
+        storageAccount: mystorageaccount
+        container: openbao-backups
+      credentialsSecretRef:
+        name: azure-credentials
+    key: clusters/prod/backup-2026-03-20.snap`}
+>
+  The Secret can provide an `accountKey` or a `connectionString`. For workload identity or managed identity, omit the credentials Secret and rely on the platform-native path intentionally.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+## Configure restore auth
+
+<Tabs groupId="restore-auth-path">
+
+<TabItem value="jwt" label="JWT auth (Recommended)">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a JWT role for restore"
+  code={`spec:
+  jwtAuthRole: openbao-operator-restore`}
+>
+  When `spec.selfInit.oidc.enabled=true` on the target cluster, the operator can create and use the default restore role automatically. Otherwise, create the role deliberately and keep the JWT audience aligned with `OPENBAO_JWT_AUDIENCE`.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="token" label="Static token">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Use a static token Secret for restore"
+  code={`apiVersion: v1
+kind: Secret
+metadata:
+  name: restore-token
+  namespace: security
+  labels:
+    openbao.org/cluster: prod-cluster
+    openbao.org/credential-purpose: restore-token
+stringData:
+  token: <restore-token>
+---
+spec:
+  tokenSecretRef:
+    name: restore-token`}
+>
+  Use this path if JWT auth is not available. The Secret must be in the same namespace as the restore request and must be labeled for the target cluster and restore-token purpose before the operator will launch the restore Job.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+## Apply the restore request
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create a full restore request"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoRestore
+metadata:
+  name: prod-restore
+  namespace: security
+spec:
+  cluster: prod-cluster
+  source:
+    target:
+      provider: s3
+      endpoint: https://s3.amazonaws.com
+      bucket: openbao-backups
+      region: us-east-1
+      credentialsSecretRef:
+        name: s3-credentials
+    key: clusters/prod/backup-2026-03-20.snap
+  jwtAuthRole: openbao-operator-restore`}
+>
+  The restore spec is immutable. If you need to change the target, snapshot key, or auth path, create a new `OpenBaoRestore` resource instead of editing the existing one.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the restore"
+  code={`kubectl apply -f restore.yaml`}
+/>
+
+## Watch the restore phases
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Inspect restore status"
+  code={`kubectl get openbaorestore <name> -n <namespace> -o yaml
+kubectl get jobs -n <namespace>
+kubectl describe openbaocluster <cluster> -n <namespace>`}
+>
+  Watch the restore resource and the target cluster together. The restore phase tells you what the restore controller is doing, while the cluster status shows what still needs follow-up after the destructive step finishes.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Restore phases to expect"
+  columns={['Phase', 'What it means']}
+  rows={[
+    {
+      cells: [
+        'Pending / Validating',
+        'The operator is checking the target cluster, storage source, auth path, and conflicting operations before it starts destructive work.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Running',
+        'The restore Job owns the cluster operation lock and is actively downloading or applying the snapshot.',
+      ],
+    },
+    {
+      cells: [
+        'Completed',
+        'The restore workflow finished and the operator recorded the result. The cluster may still need unseal or follow-up recovery work.',
+      ],
+    },
+    {
+      cells: [
+        'Failed',
+        'The restore did not succeed. Inspect the restore resource, related Job, and target cluster state before retrying with a new request.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="After the restore"
+  items={[
+    {
+      label: 'Recover a sealed cluster',
+      description: 'Go here when the restored cluster starts but remains sealed because the trust or unseal path still needs attention.',
+      docId: 'user-guide/openbaocluster/recovery/sealed-cluster',
+    },
+    {
+      label: 'Recover from no leader',
+      description: 'Go here when the restored cluster needs Raft peer or leadership repair before it can return to service.',
+      docId: 'user-guide/openbaocluster/recovery/no-leader',
+    },
+    {
+      label: 'Recover after upgrade restore',
+      description: 'Use the override-lock path if a failed upgrade or rollback blocks the normal restore request.',
+      docId: 'user-guide/openbaorestore/recovery-restore-after-upgrade',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/multi-tenancy.md b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/multi-tenancy.md
new file mode 100644
index 000000000..6afdefeeb
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/multi-tenancy.md
@@ -0,0 +1,218 @@
+---
+title: Multi-Tenant Security
+description: Default shared-operator security model, including namespace introduction, split controllers, RBAC boundaries, and tenant guardrails.
+slug: /tenant-onboarding/multi-tenant-security
+hide_title: true
+pageType: concept
+journey: security
+---
+
+<PageHeader
+  title="Shared-operator boundaries"
+  lede="Review namespace introduction, split controllers, RBAC boundaries, and tenant guardrails in the default multi-tenant model."
+/>
+
+
+
+<Callout type="success" title="Default production model">
+
+Multi-tenant mode is the recommended production operating model for OpenBao Operator.
+Use [Single-Tenant Mode](../operator/single-tenant-mode.md) for dedicated environments where one team directly owns one namespace and does not need the default tenant-onboarding boundary.
+
+</Callout>
+
+<DiagramFrame
+  title="Control-plane split"
+  caption="Namespace introduction and tenant guardrails stay with the Provisioner. Workload reconciliation stays with the tenant-scoped Controller. That separation prevents one long-running identity from both granting and consuming tenant access."
+  code={`graph LR
+    subgraph Cluster["Shared Kubernetes cluster"]
+      Admin["Platform admin or namespace owner"] --> Tenant["OpenBaoTenant"]
+      Tenant --> Provisioner["Provisioner controller"]
+      Provisioner --> Guardrails["Namespace RBAC and guardrails"]
+      Guardrails --> Controller["Tenant-scoped controller access"]
+      Controller --> ClusterObj["OpenBaoCluster and workload resources"]
+      ClusterObj --> Jobs["Backup, restore, and upgrade jobs"]
+    end
+
+    classDef actor fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef control fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef data fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Admin actor;
+    class Tenant,Provisioner,Controller control;
+    class Guardrails,ClusterObj,Jobs data;`}
+/>
+
+<DecisionTable
+  title="Control-plane security boundaries"
+  columns={['Surface', 'Primary owner', 'Why it stays separate', 'If you shortcut it']}
+  rows={[
+    {
+      cells: [
+        'Namespace introduction',
+        'Provisioner',
+        'The Provisioner can introduce tenant RBAC and guardrails without becoming the steady-state workload reconciler.',
+        'You blur the boundary between granting namespace access and consuming it.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Workload reconciliation',
+        'Controller',
+        'The Controller stays namespace-scoped and only acts where onboarding already introduced access.',
+        'A cluster-wide controller increases blast radius for config and Secret-facing mistakes.',
+      ],
+    },
+    {
+      cells: [
+        'Tenant user access',
+        'Tenant-scoped roles',
+        'Users can manage clusters without automatically gaining Secret read access.',
+        'Operators and tenant users start sharing too much of the same trust surface.',
+      ],
+    },
+    {
+      cells: [
+        'Backup and restore execution',
+        'Job-specific identities',
+        'Day 2 jobs need narrower, time-bounded capabilities than the main controller.',
+        'The controller role quietly becomes a universal credential for routine and destructive operations.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Onboarding is a real handoff, not just a prerequisite list item">
+
+In multi-tenant mode, the controller does not start mutating `OpenBaoCluster` resources in a namespace until the Provisioner has written the tenant `RoleBinding`. If `OpenBaoTenant` and `OpenBaoCluster` arrive together, reconciliation pauses and requeues until that handoff exists instead of failing with transient status-patch errors.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Default tenant roles"
+  columns={['Role', 'Scope', 'Use it for', 'What it does not allow']}
+  rows={[
+    {
+      cells: [
+        '`openbaocluster-admin-role`',
+        'Cluster',
+        'Platform-level administration and exceptional cluster ownership.',
+        'Reserve this role for platform-level administration and exceptional cluster ownership.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`openbaocluster-editor-role`',
+        'Namespace',
+        'Managing `OpenBaoCluster` resources in an onboarded tenant namespace.',
+        'It does not grant broad Secret read access.',
+      ],
+    },
+    {
+      cells: [
+        '`openbaotenant-editor-role`',
+        'Namespace',
+        'Self-service onboarding through `OpenBaoTenant` in the same namespace.',
+        'It does not allow arbitrary cross-namespace onboarding.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Isolation layers to validate"
+  columns={['Layer', 'Default model', 'Validate this', 'Go deeper']}
+  rows={[
+    {
+      cells: [
+        'RBAC',
+        'Namespace-scoped operator access introduced by `OpenBaoTenant`, with editor roles that avoid direct Secret reads.',
+        'Check RoleBindings and `kubectl auth can-i` results for tenant users and operator identities.',
+        'RBAC architecture',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Network policy',
+        'OpenBao workloads default toward restricted ingress, and backup or restore jobs use their own network contract.',
+        'Confirm cross-tenant traffic is blocked and backup egress is intentionally scoped.',
+        'Network security',
+      ],
+    },
+    {
+      cells: [
+        'Quota and namespace guardrails',
+        'Onboarding applies default tenant quotas, limit ranges, and guardrail labels before the first cluster lands.',
+        'Inspect the tenant namespace for the expected quota, limit range, and labels after onboarding.',
+        'Onboard the target namespace',
+      ],
+    },
+    {
+      cells: [
+        'Backup storage isolation',
+        'Use object-storage credentials or prefixes that do not overlap with other tenants.',
+        'Make sure backup credentials cannot list or read other tenants\' snapshot paths.',
+        'Backup operations',
+      ],
+    },
+  ]}
+/>
+
+## Validate the shared-operator boundary
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect tenant guardrails after onboarding"
+  code={`kubectl get openbaotenant <name> -n <namespace> -o yaml
+kubectl get rolebinding,resourcequota,limitrange,networkpolicy -n <target-namespace>`}
+>
+  This gives you the fast check: the onboarding request is provisioned, the namespace-scoped RBAC exists, and the expected tenant guardrails were actually introduced. The tenant `RoleBinding` is also the controller handoff marker for workload reconciliation.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check tenant access stays scoped"
+  code={`kubectl auth can-i create openbaoclusters.openbao.org -n <target-namespace> --as <tenant-user>
+kubectl auth can-i get secrets -n <target-namespace> --as <tenant-user>`}
+>
+  Expect the normal tenant editor path to allow cluster lifecycle work without granting broad Secret reads by default.
+</CommandBlock>
+
+<Callout type="note" title="Supplemental policy engines are optional">
+
+Kyverno or Gatekeeper can still add cluster-wide guardrails, but they are not the primary tenant-isolation mechanism here.
+The primary controls are the split-controller model, namespace introduction through `OpenBaoTenant`, built-in RBAC, and admission policy enforcement.
+
+</Callout>
+
+<NextActions
+  title="Go deeper"
+  items={[
+    {
+      label: 'Tenancy & governance',
+      description: 'Return to the higher-level OpenBaoTenant model when you need the control-plane rationale rather than the security checklist.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'Use the task page when you are actually creating the first tenant onboarding request.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'RBAC architecture',
+      description: 'Review the exact Kubernetes permission boundaries behind the Provisioner and Controller split.',
+      docId: 'security/infrastructure/rbac',
+    },
+    {
+      label: 'Network security',
+      description: 'Go deeper on workload and job network policy assumptions in shared clusters.',
+      docId: 'security/infrastructure/network-security',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/onboarding.md b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/onboarding.md
new file mode 100644
index 000000000..392cc7b99
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/onboarding.md
@@ -0,0 +1,251 @@
+---
+title: Onboard the Target Namespace
+description: Introduce the target namespace through OpenBaoTenant for the first cluster in the default multi-tenant path.
+slug: /get-started/onboard-target-namespace
+hide_title: true
+pageType: task
+journey: get-started
+journeyStep: 3
+---
+
+<PageHeader
+  title="Onboard the target namespace"
+  lede="In the default multi-tenant model, you onboard a namespace with `OpenBaoTenant` before creating the first cluster there. This task installs the RBAC and tenant guardrails the operator depends on."
+/>
+
+<Callout type="note" title="Skip this in single-tenant mode">
+
+If you intentionally chose [Single-Tenant Mode](../operator/single-tenant-mode.md), the controller watches one namespace directly and you do not use `OpenBaoTenant` for the first cluster path.
+
+</Callout>
+
+<Callout type="tip" title="OpenBaoTenant introduces a namespace; it does not create one">
+
+Create the Kubernetes namespace through your normal platform workflow first, then apply `OpenBaoTenant` so the operator can install the namespace-scoped guardrails it depends on.
+
+</Callout>
+
+<Callout type="note" title="Platform-managed Pod Security labels">
+
+By default, tenant onboarding applies Restricted Pod Security labels to the target namespace. On Rancher or other clusters where namespace labels are owned by platform admission, install the chart with `tenancy.namespacePodSecurityLabels.mode=external`. In that mode the Provisioner still writes tenant RBAC, quotas, limits, and Secret allowlists, but it does not mutate `Namespace` objects. The platform policy layer must enforce the namespace Pod Security baseline.
+
+</Callout>
+
+<Callout type="note" title="GitOps can submit tenant and cluster together">
+
+If your GitOps pipeline applies `OpenBaoTenant` and `OpenBaoCluster` in the same sync, the cluster controllers pause cleanly until tenant onboarding is finished. The handoff is complete once the Provisioner has written the tenant `RoleBinding` and `OpenBaoTenant` reports `status.provisioned: true`.
+
+</Callout>
+
+<JourneyRail
+  title="The first five moves"
+  current={3}
+  items={[
+    {
+      label: 'Choose a deployment model',
+      description: 'Set tenancy, security posture, install method, and the main exceptions.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Render the right namespace, identity, and admission posture.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'Use OpenBaoTenant to introduce the namespace and let the operator create its default governance boundary.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Start with the closest cluster baseline and verify the important readiness signals.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Move immediately into backups, access, upgrades, and production hardening.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Choose the onboarding model"
+  columns={['Model', 'Who creates OpenBaoTenant', 'Use it when', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Self-service',
+        'The namespace owner creates the `OpenBaoTenant` in the same target namespace.',
+        'Teams already control their own namespaces and you want the default low-friction onboarding path.',
+        '`metadata.namespace` and `spec.targetNamespace` must match.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Centrally managed',
+        'A platform admin creates the `OpenBaoTenant` from the operator namespace.',
+        'You want a stricter approval path or need custom quota and limit-range values for a namespace.',
+        'Use the rendered operator namespace, not a guessed default.',
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="What onboarding introduces"
+  caption="OpenBaoTenant is the explicit namespace introduction point. The Provisioner reacts to that request and installs the namespace-scoped RBAC and default guardrails the operator depends on in the multi-tenant model."
+  code={`graph LR
+    Request["OpenBaoTenant"] --> Provisioner["Provisioner controller"]
+    Provisioner --> RBAC["Namespace Role and RoleBinding"]
+    Provisioner --> Quota["ResourceQuota and LimitRange"]
+    Provisioner --> Labels["Tenant guardrail labels"]
+    RBAC --> Cluster["OpenBaoCluster can now be managed in the namespace"]
+
+    classDef request fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef control fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef data fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Request request;
+    class Provisioner control;
+    class RBAC,Quota,Labels,Cluster data;`}
+/>
+
+## Apply the onboarding request
+
+<Tabs groupId="tenant-onboarding-model">
+
+<TabItem value="self-service" label="Self-service">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create OpenBaoTenant in the target namespace"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: team-a-onboarding
+  namespace: team-a-prod
+spec:
+  targetNamespace: team-a-prod`}
+>
+  In the self-service path, `metadata.namespace` and `spec.targetNamespace` must match. Self-service onboarding uses the default tenant guardrails and does not allow custom `quota` or `limitRange` values.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="centralized" label="Centrally managed">
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Create OpenBaoTenant from the operator namespace"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: team-b-authorization
+  namespace: <rendered-operator-namespace>
+spec:
+  targetNamespace: team-b-prod
+  # Optional centrally managed guardrails:
+  # quota:
+  # limitRange:`}
+>
+  Use the rendered operator namespace from your install, not a hard-coded assumption, when platform admins create onboarding requests on behalf of teams.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the onboarding request"
+  code={`kubectl apply -f tenant-onboarding.yaml`}
+/>
+
+<Callout type="warning" title="Cross-namespace self-service is blocked">
+
+If a namespace owner creates `OpenBaoTenant` in one namespace and targets a different namespace, the controller rejects it with a security violation instead of silently broadening access.
+
+</Callout>
+
+## Verify onboarding
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Inspect the OpenBaoTenant status"
+  code={`kubectl get openbaotenant <name> -n <namespace> -o yaml`}
+>
+  Confirm `status.provisioned: true` and a healthy `Provisioned` condition. In multi-tenant mode, that is the signal that the namespace-scoped RBAC handoff is complete and cluster reconciliation can proceed.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify the tenant RBAC handoff exists"
+  code={`kubectl get rolebinding openbao-operator-tenant-rolebinding -n <target-namespace>`}
+>
+  This is the concrete handoff marker the controller waits for before it starts mutating `OpenBaoCluster` resources in that namespace.
+</CommandBlock>
+
+<DecisionTable
+  kind="reference"
+  title="Typical onboarding failures"
+  columns={['Symptom', 'Most likely cause', 'Check first']}
+  rows={[
+    {
+      cells: [
+        'Provisioning is rejected with a security violation',
+        'A self-service request targeted a namespace different from `metadata.namespace`',
+        'The requested namespace pair and the onboarding model in use',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Provisioning never completes or clusters keep requeueing without creating workload resources',
+        'The Provisioner is missing, unhealthy, or cannot write the tenant guardrails and tenant RoleBinding',
+        'Operator install health, the Provisioner deployment, and the tenant `RoleBinding` in the target namespace',
+      ],
+    },
+    {
+      cells: [
+        'Provisioning reports an admission or Unauthorized error while updating the target namespace',
+        'A platform policy layer owns namespace labels while the chart is still in default Pod Security label enforcement mode',
+        'Use `tenancy.namespacePodSecurityLabels.mode=external` when platform policy owns those labels',
+      ],
+    },
+    {
+      cells: [
+        'Custom quotas are ignored',
+        'The request came from the self-service path, which uses default guardrails only',
+        'Whether the `OpenBaoTenant` was created from the operator namespace',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the main path"
+  items={[
+    {
+      label: 'Create your first cluster',
+      description: 'Apply the first OpenBaoCluster only after the target namespace is provisioned and ready.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Review tenancy & governance',
+      description: 'Use the concept page when you need the mental model behind OpenBaoTenant rather than just the task steps.',
+      docId: 'user-guide/openbaotenant/overview',
+    },
+    {
+      label: 'Review multi-tenant security',
+      description: 'Go deeper on namespace isolation, RBAC, network policy, and guardrail assumptions in the shared-operator model.',
+      docId: 'user-guide/openbaotenant/multi-tenancy',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/overview.md b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/overview.md
new file mode 100644
index 000000000..c9abad665
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/openbaotenant/overview.md
@@ -0,0 +1,114 @@
+---
+title: Tenancy & Governance
+description: OpenBaoTenant namespace introduction, default guardrails, and the shared-operator boundary in the multi-tenant model.
+slug: /tenant-onboarding
+hide_title: true
+pageType: concept
+journey: get-started
+---
+
+<PageHeader
+  title="OpenBaoTenant namespace introduction"
+  lede="`OpenBaoTenant` introduces namespaces in the default multi-tenant model. Use this page for the RBAC, guardrails, and control-plane behavior that follow from that onboarding step."
+/>
+
+
+
+<DiagramFrame
+  title="OpenBaoTenant as the namespace introduction point"
+  caption="The Provisioner reacts to OpenBaoTenant, introduces the namespace boundary, and only then can the rest of the operator safely manage cluster resources there."
+  code={`graph LR
+    Tenant["Target namespace owner or platform admin"] --> Request["OpenBaoTenant"]
+    Request --> Provisioner["Provisioner controller"]
+    Provisioner --> Guardrails["RBAC, quota, limit range, guardrail labels"]
+    Guardrails --> Cluster["OpenBaoCluster lifecycle in the tenant namespace"]
+
+    classDef actor fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef control fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef data fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Tenant actor;
+    class Request,Provisioner control;
+    class Guardrails,Cluster data;`}
+/>
+
+<DecisionTable
+  title="What OpenBaoTenant owns"
+  columns={['Surface', 'Why it exists', 'What it is not']}
+  rows={[
+    {
+      cells: [
+        'Namespace introduction',
+        'The operator only acts on namespaces that were introduced explicitly.',
+        'It is not broad namespace discovery or a cluster-wide wildcard.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Tenant RBAC',
+        'The Provisioner creates the namespace-scoped RBAC the operator needs to manage OpenBao resources there.',
+        'It is not a request to grant arbitrary Secret access to tenant users.',
+      ],
+    },
+    {
+      cells: [
+        'Default guardrails',
+        'Tenant quotas, limit ranges, and namespace guardrail labels can be introduced as part of onboarding.',
+        'It is not per-cluster tuning for the OpenBao workload itself.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Choose the governance model"
+  columns={['Model', 'Who creates the request', 'Best fit', 'Tradeoff']}
+  rows={[
+    {
+      cells: [
+        'Self-service',
+        'Namespace owners create OpenBaoTenant in their own namespace.',
+        'High-trust platform environments where teams already own namespace boundaries.',
+        'The request can only target the same namespace and uses default guardrails.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Centrally managed',
+        'Platform admins create OpenBaoTenant from the operator namespace.',
+        'Stricter environments that want review, auditability, or custom tenant guardrails.',
+        'The platform team owns more of the namespace introduction workflow.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="API contract">
+
+`spec.targetNamespace` is immutable after creation.
+If the target namespace changes, delete and recreate the `OpenBaoTenant` instead of trying to mutate it in place.
+
+</Callout>
+
+<NextActions
+  title="Continue from the concept into the task"
+  items={[
+    {
+      label: 'Onboard the target namespace',
+      description: 'Use the step-by-step task page when you are ready to create the OpenBaoTenant request.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Return to the main path once the namespace introduction is complete.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Open multi-tenant security',
+      description: 'Go deeper on the isolation model when you need the security reasoning behind the shared-operator path.',
+      docId: 'user-guide/openbaotenant/multi-tenancy',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/authn.md b/website/versioned_docs/version-0.3.0/user-guide/operator/authn.md
new file mode 100644
index 000000000..84fce4a88
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/authn.md
@@ -0,0 +1,352 @@
+---
+title: Operator Authentication
+description: Projected JWT auth path, audience contract, and custom-install checks for controller identity wiring.
+slug: /get-started/operator-authentication
+hide_title: true
+pageType: concept
+journey: get-started
+---
+
+<PageHeader
+  title="Operator authentication paths"
+  lede="Default JWT authentication, the audience contract behind it, and the checks to run when you customize controller identity wiring."
+/>
+
+
+
+<DiagramFrame
+  title="Default operator auth path"
+  caption="Kubernetes issues a projected token for the controller. The operator sends that JWT with each OpenBao maintenance request using inline authentication."
+  code={`sequenceDiagram
+    autonumber
+    participant K8s as Kubernetes API
+    participant Controller as Operator controller
+    participant Bao as OpenBao cluster
+
+    K8s->>Controller: Mount projected token (aud=openbao-internal)
+    Controller->>Bao: Maintenance request with inline auth headers
+    Bao->>Bao: Validate auth/jwt-operator role
+    Bao-->>Controller: Maintenance response
+
+    Note over Controller,Bao: Human login is a separate bootstrap path`}
+/>
+
+<DecisionTable
+  title="JWT default path"
+  columns={['Property', 'What you get', 'Why it matters']}
+  rows={[
+    {
+      cells: [
+        'No stored root token',
+        'The controller authenticates with a projected ServiceAccount token instead of a long-lived Secret.',
+        'You avoid carrying a static high-privilege credential in Kubernetes just to let the operator do day 2 work.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Automatic rotation',
+        'Kubernetes rotates the projected token on its own schedule.',
+        'Controller auth ages out naturally instead of depending on manual token rotation discipline.',
+      ],
+    },
+    {
+      cells: [
+        'Audience binding',
+        'The token is scoped to `OPENBAO_JWT_AUDIENCE`, which defaults to `openbao-internal`.',
+        'A token issued for OpenBao auth should not be replayable against unrelated services.',
+      ],
+    },
+    {
+      cells: [
+        'Scoped maintenance policy',
+        'The JWT role grants the operator maintenance policy to each authenticated request, not blanket admin privileges.',
+        'The controller gets the capabilities it needs for health checks, step-down, and autopilot without widening normal access.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Inline authentication is the default">
+
+For supported OpenBao versions, JWT-backed operator requests use OpenBao inline authentication by default.
+The controller, backup jobs, restore jobs, and upgrade jobs still use the same projected ServiceAccount JWTs,
+role names, audiences, and policies. The transport changes from a separate login request plus `X-Vault-Token`
+to inline auth headers on the actual OpenBao request.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="JWT transport strategy"
+  columns={['Strategy', 'How it authenticates', 'When to use it']}
+  rows={[
+    {
+      cells: [
+        '`inline`',
+        'Sends the projected ServiceAccount JWT through OpenBao inline auth headers on each operator-owned request.',
+        'Default for supported OpenBao versions. Use this for normal operation.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        '`standard`',
+        'Performs the legacy JWT login request and then sends the returned OpenBao token as `X-Vault-Token`.',
+        'Operational compatibility switch when an intermediary drops custom inline auth headers or enforces header-size limits.',
+      ],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Use the standard JWT strategy"
+  code={`kubectl -n openbao-operator-system set env deployment/openbao-operator-controller-manager \\
+  OPENBAO_JWT_AUTH_STRATEGY=standard`}
+>
+  Leave the variable unset, or set it to `inline`, for the default inline-auth path. The operator propagates this setting to backup, restore, and upgrade executor jobs.
+</CommandBlock>
+
+<Callout type="warning" title="Redact inline auth headers">
+
+Inline authentication sends the projected ServiceAccount JWT in
+`X-Vault-Inline-Auth-Parameter-jwt`. Treat this header like `X-Vault-Token` and
+`Authorization`: do not log it in ingress, proxy, service mesh, debug, or audit
+shipping pipelines. Logging request metadata such as method, path, status, and
+duration is safe; logging full HTTP headers is not.
+
+</Callout>
+
+<Callout type="note" title="Controller and human authentication are separate">
+
+`spec.selfInit.oidc.enabled: true` bootstraps the controller auth path only.
+It does not create a human login method by itself.
+If you use self-init, create human access in the same bootstrap contract through `selfInit.requests` so the cluster has an operator path and a human path from the start.
+
+</Callout>
+
+<Callout type="warning" title="Bootstrap does not mean ongoing policy reconciliation">
+
+`spec.selfInit.oidc.enabled: true` bootstraps the controller JWT auth method, policy, and role.
+After bootstrap, the operator uses that auth surface but does not continue mutating OpenBao
+policies on its own. When a later operator release needs an additional controller capability,
+the human operator must update the `openbao-operator` policy explicitly.
+
+</Callout>
+
+<DecisionTable
+  title="Bootstrap authentication surfaces"
+  columns={['Surface', 'Where it is defined', 'Why it exists']}
+  rows={[
+    {
+      cells: [
+        'Operator lifecycle auth',
+        '`spec.selfInit.oidc.enabled` or an equivalent manually managed JWT role',
+        'Lets the operator perform backup, restore, upgrade, and maintenance work with a short-lived scoped identity.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Human login path',
+        '`spec.selfInit.requests` or another deliberate bootstrap path in the same cluster bring-up plan',
+        'Ensures someone can actually sign in after the root token is revoked.',
+      ],
+    },
+  ]}
+/>
+
+## Self-init and manual bootstrap
+
+<DecisionTable
+  title="Choose the bootstrap path"
+  columns={['Path', 'Use it when', 'Operator behavior', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Self-init with OIDC',
+        'You want the supported production path and the cluster is allowed to bootstrap its own operator auth surface.',
+        'The operator configures JWT auth, discovery, the `openbao-operator` policy, and the bound role automatically.',
+        'Bootstrap a human login path in `selfInit.requests` at the same time so the cluster is usable after root-token revocation.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Manual JWT configuration',
+        'You are carrying a compatibility workflow, a custom install shape, or a controlled bootstrap sequence.',
+        'You create the JWT auth method, policy, and role binding yourself.',
+        'Rendered ServiceAccount name, namespace, and audience drift are the usual breakpoints.',
+      ],
+      emphasis: 'caution',
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Who owns policy changes after bootstrap"
+  columns={['Install shape', 'Who creates the initial policy', 'Who updates it later']}
+  rows={[
+    {
+      cells: [
+        'Self-init with OIDC',
+        'The bootstrap contract created by the operator during self-init.',
+        'The human operator. Self-init does not keep mutating OpenBao policies after the cluster is initialized.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Manual JWT configuration',
+        'The cluster administrator.',
+        'The cluster administrator.',
+      ],
+    },
+  ]}
+/>
+
+<CommandBlock
+  language="hcl"
+  label="configure"
+  title="Controller policy scope"
+  code={`path "sys/health" {
+  capabilities = ["read"]
+}
+
+path "sys/step-down" {
+  capabilities = ["sudo", "update"]
+}
+
+path "sys/storage/raft/configuration" {
+  capabilities = ["read"]
+}
+
+path "sys/storage/raft/remove-peer" {
+  capabilities = ["update"]
+}
+
+path "sys/storage/raft/autopilot/configuration" {
+  capabilities = ["read", "update"]
+}
+
+path "sys/storage/raft/autopilot/state" {
+  capabilities = ["read"]
+}`}
+>
+  Keep the controller policy focused on maintenance work. Backup, restore, and upgrade jobs authenticate through their own roles instead of inheriting the controller scope.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Manual JWT role example for a custom controller identity"
+  code={`bao write auth/jwt-operator/role/openbao-operator \\
+  role_type="jwt" \\
+  bound_audiences="openbao-internal" \\
+  user_claim="sub" \\
+  bound_subject="system:serviceaccount:platform-security:demo-openbao-operator-controller" \\
+  token_policies="openbao-operator" \\
+  token_ttl="1h"`}
+>
+  Replace the namespace, ServiceAccount name, and audience with the values from your rendered install, not the example defaults.
+</CommandBlock>
+
+## What must stay aligned
+
+<DecisionTable
+  kind="reference"
+  title="Custom-install checks"
+  columns={['Surface', 'Must match', 'What breaks when it drifts']}
+  rows={[
+    {
+      cells: [
+        'Controller identity',
+        'Rendered controller ServiceAccount name and operator namespace',
+        'The OpenBao JWT role or admission-policy identity references the wrong controller subject.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Projected token mount',
+        'The controller Deployment still mounts the `openbao-token` projected volume',
+        'The controller loses its default path to authenticate to OpenBao at all.',
+      ],
+    },
+    {
+      cells: [
+        'JWT audience',
+        '`OPENBAO_JWT_AUDIENCE`, the projected token audience, and the OpenBao role `bound_audiences`',
+        'A valid ServiceAccount token is rejected because it was issued for a different audience contract.',
+      ],
+    },
+    {
+      cells: [
+        'Discovery access',
+        'The controller can reach `/.well-known/openid-configuration` and the JWKS endpoint',
+        'OpenBao cannot validate the projected token even though the controller identity itself is correct.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Typical auth failures"
+  columns={['Symptom', 'Most likely cause', 'Check first']}
+  rows={[
+    {
+      cells: [
+        '`permission denied` when the controller calls OpenBao',
+        'JWT audience mismatch or an incorrect bound subject',
+        'Rendered identity and `OPENBAO_JWT_AUDIENCE` alignment',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Self-init completes but controller auth never settles',
+        'OIDC discovery is unreachable or incomplete',
+        'Kubernetes API discovery reachability and cluster condition output',
+      ],
+    },
+    {
+      cells: [
+        'Backup or restore auth fails even though controller auth works',
+        'Executor jobs use separate roles and ServiceAccounts',
+        'Operator authorization and the job-specific auth path',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Continue the support path"
+  items={[
+    {
+      label: 'Operator authorization',
+      description: 'Review which policies belong to controller, backup, restore, and upgrade work.',
+      docId: 'user-guide/operator/authz',
+    },
+    {
+      label: 'Operator identity and access',
+      description: 'Trace which Kubernetes identity maps to which OpenBao-side auth boundary.',
+      docId: 'user-guide/operator/identity-and-access',
+    },
+    {
+      label: 'Return to installation',
+      description: 'Go back to the install page once the rendered identity and audience contract feel mechanical.',
+      docId: 'user-guide/operator/installation',
+    },
+  ]}
+/>
+
+## Official OpenBao background
+
+- [JWT/OIDC auth method](https://openbao.org/docs/auth/jwt/)
+- [Kubernetes auth method](https://openbao.org/docs/auth/kubernetes/)
+- [Token concepts](https://openbao.org/docs/concepts/tokens/)
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/authz.md b/website/versioned_docs/version-0.3.0/user-guide/operator/authz.md
new file mode 100644
index 000000000..81016ccb5
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/authz.md
@@ -0,0 +1,322 @@
+---
+title: Operator Authorization
+description: Policy surfaces for controller, backup, restore, and upgrade work, with destructive capabilities scoped to the right identities.
+slug: /get-started/operator-authorization
+hide_title: true
+pageType: concept
+journey: get-started
+---
+
+<PageHeader
+  title="Operator authorization surfaces"
+  lede="Use separate policy surfaces for controller, backup, restore, and upgrade work. Each path authenticates separately and receives only the capabilities it needs."
+/>
+
+
+
+<DiagramFrame
+  title="Policies stay attached to job-specific identities"
+  caption="Each operator path maps to its own JWT role and policy set, with separate controller, backup, restore, and upgrade identities."
+  code={`graph LR
+    subgraph K8s["Kubernetes identities"]
+      Controller["Controller SA"]
+      Backup["Backup Job SA"]
+      Restore["Restore Job SA"]
+      Upgrade["Upgrade Job SA"]
+    end
+
+    subgraph Bao["OpenBao auth and policy"]
+      RoleController["Role: openbao-operator"]
+      RoleBackup["Role: openbao-operator-backup"]
+      RoleRestore["Role: openbao-operator-restore"]
+      RoleUpgrade["Role: openbao-operator-upgrade"]
+
+      PolicyController["Policy: controller maintenance"]
+      PolicyBackup["Policy: snapshot read"]
+      PolicyRestore["Policy: snapshot-force"]
+      PolicyUpgrade["Policy: rolling or blue-green upgrade"]
+    end
+
+    Controller --> RoleController --> PolicyController
+    Backup --> RoleBackup --> PolicyBackup
+    Restore --> RoleRestore --> PolicyRestore
+    Upgrade --> RoleUpgrade --> PolicyUpgrade
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef caution fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+
+    class Controller,Backup,Restore,Upgrade read;
+    class RoleController,RoleBackup,RoleRestore,RoleUpgrade write;
+    class PolicyController,PolicyBackup,PolicyUpgrade write;
+    class PolicyRestore caution;`}
+/>
+
+<DecisionTable
+  title="Policy surfaces by lifecycle capability"
+  columns={['Policy surface', 'Used by', 'Typical capabilities', 'Why it stays separate']}
+  rows={[
+    {
+      cells: [
+        'Controller maintenance',
+        'The main controller Deployment',
+        '`sys/health`, `sys/step-down`, and autopilot configuration reads or updates',
+        'Keep this path available for routine reconciliation and maintenance without adding destructive restore powers.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Backup',
+        'The generated backup Job',
+        '`sys/storage/raft/snapshot` read access',
+        'Snapshot reads are narrower than controller maintenance and remain easier to reason about independently.',
+      ],
+    },
+    {
+      cells: [
+        'Restore',
+        'The generated restore Job',
+        '`sys/storage/raft/snapshot-force` update access',
+        'Restore can replace the full cluster state and belongs only on the workload that performs restore.',
+      ],
+      emphasis: 'caution',
+    },
+    {
+      cells: [
+        'Upgrade',
+        'The generated upgrade Job',
+        'Step-down, autopilot state, snapshot read, and optional peer-management operations for blue-green flows',
+        'Upgrade paths often need time-bounded orchestration permissions without widening steady-state controller access.',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="danger" title="Restore is a destructive role">
+
+The restore capability can replace data, policies, and keys across the cluster.
+Do not bind the restore policy to the controller or to a broad multi-purpose ServiceAccount just because it is convenient during setup.
+
+</Callout>
+
+## Default policy surfaces
+
+<Tabs groupId="operator-policy-surfaces">
+
+<TabItem value="controller" label="Controller">
+
+<CommandBlock
+  language="hcl"
+  label="configure"
+  title="Controller maintenance policy"
+  code={`path "sys/health" {
+  capabilities = ["read"]
+}
+
+path "sys/step-down" {
+  capabilities = ["sudo", "update"]
+}
+
+path "sys/storage/raft/configuration" {
+  capabilities = ["read"]
+}
+
+path "sys/storage/raft/remove-peer" {
+  capabilities = ["update"]
+}
+
+path "sys/storage/raft/autopilot/configuration" {
+  capabilities = ["read", "update"]
+}
+
+path "sys/storage/raft/autopilot/state" {
+  capabilities = ["read"]
+}`}
+>
+  This is the steady-state controller scope. Keep backup, restore, and blue-green peer management in separate roles unless you are intentionally changing the model.
+</CommandBlock>
+
+<Callout type="warning" title="Existing clusters must update the controller policy manually">
+
+The operator does not rewrite OpenBao policies after bootstrap. If an operator upgrade adds a new
+controller-side capability, such as `read` on `sys/storage/raft/autopilot/state`, update the
+`openbao-operator` policy manually on existing clusters. Until that policy includes the new path,
+features that depend on it will report `Unknown` rather than a concrete health state.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="backup" label="Backup">
+
+<CommandBlock
+  language="hcl"
+  label="configure"
+  title="Backup policy"
+  code={`path "sys/storage/raft/snapshot" {
+  capabilities = ["read"]
+}`}
+>
+  Backup only needs snapshot streaming. Storage-provider credentials are a separate boundary outside this OpenBao policy.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="restore" label="Restore">
+
+<CommandBlock
+  language="hcl"
+  label="configure"
+  title="Restore policy"
+  code={`path "sys/storage/raft/snapshot-force" {
+  capabilities = ["update"]
+}`}
+>
+  Keep this policy tightly bound to the generated restore Job identity and only for the period where restore is actually needed.
+</CommandBlock>
+
+</TabItem>
+
+<TabItem value="upgrade" label="Upgrade">
+
+<CommandBlock
+  language="hcl"
+  label="configure"
+  title="Rolling and blue-green upgrade policy surfaces"
+  code={`# Rolling upgrade baseline
+path "sys/health" {
+  capabilities = ["read"]
+}
+
+path "sys/step-down" {
+  capabilities = ["sudo", "update"]
+}
+
+path "sys/storage/raft/autopilot/state" {
+  capabilities = ["read"]
+}
+
+# Blue-green adds peer-management paths
+path "sys/storage/raft/join" {
+  capabilities = ["update"]
+}
+
+path "sys/storage/raft/configuration" {
+  capabilities = ["read", "update"]
+}
+
+path "sys/storage/raft/remove-peer" {
+  capabilities = ["update"]
+}
+
+path "sys/storage/raft/promote" {
+  capabilities = ["update"]
+}
+
+path "sys/storage/raft/demote" {
+  capabilities = ["update"]
+}`}
+>
+  Rolling upgrades need less authority than blue-green cutovers. Keep those strategies separate in your head when you review the required policy surface.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+## Policy upgrade notes
+
+<DecisionTable
+  kind="reference"
+  title="When the controller policy surface changes"
+  columns={['Situation', 'What the operator does', 'What you must do']}
+  rows={[
+    {
+      cells: [
+        'A new operator release adds a controller-side capability',
+        'Uses the new capability if the `openbao-operator` policy already includes it, otherwise reports `Unknown` or a permission error for the dependent feature.',
+        'Update the `openbao-operator` policy manually on existing clusters. The operator does not rewrite OpenBao policies after bootstrap.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'A cluster was bootstrapped with self-init in an earlier release',
+        'Keeps using the already-created JWT role and policy.',
+        'Treat the policy as cluster security configuration that you own after bootstrap. Review release notes and add any newly required paths deliberately.',
+      ],
+    },
+    {
+      cells: [
+        'JWT auth and policies are fully manually managed',
+        'Never mutates that auth surface.',
+        'Carry the full policy diff yourself as part of operator upgrades.',
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Common authorization failures"
+  columns={['Symptom', 'Likely boundary', 'Check first']}
+  rows={[
+    {
+      cells: [
+        'JWT login succeeds but the request returns `permission denied`',
+        'The workload authenticated correctly but the policy is missing the needed path capability',
+        'Which job or controller path is making the request, then the matching policy surface',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Backup works but restore fails',
+        'The restore Job identity or restore policy is missing or misbound',
+        'Restore ServiceAccount, restore role binding, and `snapshot-force` policy',
+      ],
+    },
+    {
+      cells: [
+        'Rolling upgrade works but blue-green cutover stalls',
+        'Peer-management permissions were not added for the upgrade strategy in use',
+        'Upgrade strategy and the corresponding upgrade policy paths',
+      ],
+    },
+    {
+      cells: [
+        'Controller can do too much',
+        'A shortcut merged job-specific capabilities into the controller role',
+        'Manual auth configuration drift from the intended separation model',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Go deeper"
+  items={[
+    {
+      label: 'Operator authentication',
+      description: 'Return to the JWT audience and bound-subject model when auth fails before policy even matters.',
+      docId: 'user-guide/operator/authn',
+    },
+    {
+      label: 'Backup operations',
+      description: 'See how the backup Job uses its own auth and storage credentials during normal operation.',
+      docId: 'user-guide/openbaocluster/operations/backups',
+    },
+    {
+      label: 'Restore manager architecture',
+      description: 'Review why restore stays isolated from the controller and how the operator drives it.',
+      docId: 'architecture/restore-manager',
+    },
+  ]}
+/>
+
+## Official OpenBao background
+
+- [Policy concepts](https://openbao.org/docs/concepts/policies/)
+- [Policy command reference](https://openbao.org/docs/commands/policy/)
+- [Token concepts](https://openbao.org/docs/concepts/tokens/)
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/deployment-decision-guide.md b/website/versioned_docs/version-0.3.0/user-guide/operator/deployment-decision-guide.md
new file mode 100644
index 000000000..6a5885091
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/deployment-decision-guide.md
@@ -0,0 +1,178 @@
+---
+title: Deployment Decision Guide
+description: Choose the tenancy model, security posture, bootstrap flow, and install path for a new deployment.
+slug: /get-started/deployment-decision-guide
+hide_title: true
+pageType: task
+journey: get-started
+journeyStep: 1
+---
+
+<PageHeader
+  title="Choose the deployment path"
+  lede="Choose the tenancy model, security posture, bootstrap flow, and install path for a new deployment. The default path is multi-tenant, Hardened, self-init, and the standard install flow."
+/>
+
+<Checklist
+    title="Default starting point"
+    items={[
+      'multi-tenant mode',
+      'Hardened profile',
+      'self-init enabled',
+      'External or ACME TLS',
+      'admission policies enabled',
+      'RollingUpdate until you need blue-green cutover control',
+    ]}
+    tone="success"
+  />
+
+
+<JourneyRail
+  title="The first five moves"
+  current={1}
+  items={[
+    {
+      label: 'Choose a deployment model',
+      description: 'Set tenancy, security posture, install method, and any planned exceptions.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Render the right namespace, identity, and admission posture.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, use OpenBaoTenant, then create the first cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Start with the closest cluster baseline and verify the important readiness signals.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Move immediately into backups, access, upgrades, and production hardening.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+<DecisionTable
+  title="Default deployment decisions and exceptions"
+  columns={['Decision area', 'Default', 'Use an alternative when', 'Go deeper']}
+  rows={[
+    {
+      cells: [
+        'Tenancy model',
+        'Multi-tenant',
+        'One team directly owns one namespace and does not need the default tenant-onboarding model.',
+        'Single-tenant mode',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Security profile',
+        'Hardened',
+        'This environment is strictly local development, CI, or short-lived evaluation.',
+        'Security profiles',
+      ],
+    },
+    {
+      cells: [
+        'Bootstrap flow',
+        'Self-init',
+        'You are intentionally carrying a compatibility or controlled manual-bootstrap workflow.',
+        'Self-initialization',
+      ],
+    },
+    {
+      cells: [
+        'TLS mode',
+        'External or ACME',
+        'You are in a non-Hardened environment and temporary operator-managed TLS convenience matters more than production trust requirements.',
+        'TLS and identity',
+      ],
+    },
+    {
+      cells: [
+        'Installation path',
+        'Helm',
+        'You need raw-manifest overlays, source-based rendering, or install-time identity customization.',
+        'Operator installation',
+      ],
+    },
+    {
+      cells: [
+        'Upgrade strategy',
+        'RollingUpdate',
+        'You need parallel validation, manual promotion, or stronger cutover control than rolling upgrades provide.',
+        'Cluster upgrades',
+      ],
+    },
+  ]}
+/>
+
+<Callout type="warning" title="Operator auth is not human auth">
+
+`spec.selfInit.oidc.enabled: true` bootstraps operator authentication only.
+Decide which human login path will be created as part of `spec.selfInit.requests` during bootstrap, then finalize the cluster design.
+
+</Callout>
+
+<RouteList
+  title="Exceptions that change the default path"
+  items={[
+    {
+      eyebrow: 'A',
+      title: 'Single-tenant mode',
+      description: 'Use this when one team owns one namespace and wants direct namespace-scoped operator control.',
+      docId: 'user-guide/operator/single-tenant-mode',
+      actionLabel: 'Review',
+    },
+    {
+      eyebrow: 'B',
+      title: 'Operator identity and access',
+      description: 'Use this when you customize names, namespaces, JWT audience, or raw-manifest identity wiring.',
+      docId: 'user-guide/operator/identity-and-access',
+      actionLabel: 'Review',
+    },
+    {
+      eyebrow: 'C',
+      title: 'Validated deployments',
+      description: 'Use a tested architecture or recipe when you want a validated starting point instead of building the path from scratch.',
+      docId: 'user-guide/validated-deployments/index',
+      actionLabel: 'Open',
+    },
+  ]}
+/>
+
+<Checklist
+  title="Check these decisions"
+  items={[
+    'Am I running multi-tenant or single-tenant mode?',
+    'Is this environment Hardened or Development?',
+    'If I stay multi-tenant, who creates the first OpenBaoTenant and in which namespace?',
+    'How will humans authenticate after the first cluster comes up?',
+    'Does Helm or raw manifests own the rendered operator identity?',
+    'What is my backup plan before the first production upgrade?',
+  ]}
+/>
+
+<NextActions
+  title="Continue the guided path"
+  items={[
+    {
+      label: 'Install the operator',
+      description: 'Use the supported install flow and verify the rendered controller identity.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, introduce the namespace through OpenBaoTenant, then create the first cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/identity-and-access.md b/website/versioned_docs/version-0.3.0/user-guide/operator/identity-and-access.md
new file mode 100644
index 000000000..c247fd6fc
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/identity-and-access.md
@@ -0,0 +1,105 @@
+---
+title: Operator Identity And Access
+description: Map controller, workload, backup, restore, and upgrade identities so rendered installs and OpenBao-side bindings stay aligned.
+slug: /get-started/operator-identity
+hide_title: true
+pageType: concept
+journey: get-started
+---
+
+<PageHeader
+  title="Operator identity surfaces"
+  lede="The controller, workload pods, and day 2 executor jobs use different identities. Use this page to map each Kubernetes ServiceAccount to the corresponding OpenBao auth and authorization surface."
+/>
+
+
+
+<DecisionTable
+  kind="reference"
+  title="Identity map"
+  columns={['Actor', 'Kubernetes identity', 'OpenBao auth', 'Primary boundary']}
+  rows={[
+    {
+      cells: ['Provisioner', 'Provisioner ServiceAccount in the operator namespace', 'None', 'Kubernetes RBAC only'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Controller', 'Controller ServiceAccount in the operator namespace', 'Projected JWT token bound to the `openbao-operator` role', 'Kubernetes RBAC plus OpenBao maintenance policy'],
+    },
+    {
+      cells: ['Main OpenBao Pods', 'Per-cluster ServiceAccount in the tenant namespace', 'OpenBao server runtime auth and configured seal/unseal integration', 'Kubernetes workload identity plus OpenBao runtime configuration'],
+    },
+    {
+      cells: ['Backup Job', 'Generated backup ServiceAccount in the tenant namespace', 'Projected JWT token or explicit backup token Secret', 'Snapshot policy plus backup-target credentials'],
+    },
+    {
+      cells: ['Restore Job', 'Generated restore ServiceAccount in the tenant namespace', 'Projected JWT token or explicit restore token Secret', 'Restore policy plus restore-source credentials'],
+    },
+    {
+      cells: ['Upgrade Job', 'Generated upgrade ServiceAccount in the tenant namespace', 'Projected JWT token', 'Upgrade policy for rolling or blue-green operations'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Install-sensitive checks"
+  columns={['Surface', 'What must match', 'Why it breaks when it drifts']}
+  rows={[
+    {
+      cells: ['Controller identity', 'Rendered controller ServiceAccount name and operator namespace', 'The JWT role binding and admission-policy subjects stop pointing at the real controller.'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Projected token mount', 'The controller Deployment still mounts the `openbao-token` projected volume', 'The controller loses its default JWT auth path to OpenBao.'],
+    },
+    {
+      cells: ['JWT audience', '`OPENBAO_JWT_AUDIENCE`, the projected token audience, and the OpenBao role `bound_audiences`', 'A valid controller identity still fails auth when the audience contract drifts.'],
+    },
+    {
+      cells: ['Executor identities', 'Backup, restore, and upgrade Jobs use their own generated ServiceAccounts', 'Main workload identity does not automatically carry into day 2 executor jobs.'],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Common failure modes"
+  columns={['Symptom', 'Most likely boundary', 'Check first']}
+  rows={[
+    {
+      cells: ['`permission denied` when the controller talks to OpenBao', 'Controller JWT auth or OpenBao role binding', 'Operator authentication'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Custom raw-manifest install fails after namespace or prefix changes', 'Rendered identity drift', 'Operator installation render verification'],
+    },
+    {
+      cells: ['Backup or restore auth fails while the main cluster stays healthy', 'Executor Job identity drift', 'Operator authorization plus backup or restore configuration'],
+    },
+    {
+      cells: ['Tenant onboarding works, but controller access does not', 'Kubernetes RBAC or RoleBinding introduction', 'RBAC architecture'],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Go deeper"
+  items={[
+    {
+      label: 'Operator authentication',
+      description: 'See how the projected JWT token, audience, and role binding form the default auth path.',
+      docId: 'user-guide/operator/authn',
+    },
+    {
+      label: 'Operator authorization',
+      description: 'Review which policies belong to controller, backup, restore, and upgrade work.',
+      docId: 'user-guide/operator/authz',
+    },
+    {
+      label: 'RBAC architecture',
+      description: 'Move into Kubernetes permission boundaries when the problem is namespace or RoleBinding scoped.',
+      docId: 'security/infrastructure/rbac',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/installation.md b/website/versioned_docs/version-0.3.0/user-guide/operator/installation.md
new file mode 100644
index 000000000..0fe264f01
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/installation.md
@@ -0,0 +1,522 @@
+---
+title: Operator Installation
+description: Install OpenBao Operator with the intended tenancy mode, rendered identity, and verification checks.
+slug: /get-started/install
+hide_title: true
+pageType: task
+journey: get-started
+journeyStep: 2
+---
+
+<!-- id: installation-guide -->
+
+<PageHeader
+  title="Install the operator for the intended tenancy mode"
+  lede="Choose a supported install path, keep the rendered namespace and identity explicit, and verify the controller wiring for the tenancy mode you intend to run."
+/>
+
+<Checklist
+    title="Installation preflight"
+    items={[
+      'confirm Kubernetes compatibility and cluster-admin access for CRDs, RBAC, and admission policies',
+      'decide whether Helm or raw manifests own the install lifecycle',
+      'decide whether you are staying multi-tenant or intentionally switching to single-tenant mode',
+      'if you stay multi-tenant, know who will create the first OpenBaoTenant and in which namespace',
+      'pin a released operator version for production instead of relying on floating tags',
+    ]}
+  />
+
+
+<JourneyRail
+  title="Installation sequence"
+  current={2}
+  items={[
+    {
+      label: 'Choose a deployment path',
+      description: 'Decide tenancy mode, security profile, TLS posture, and install method.',
+      docId: 'user-guide/operator/deployment-decision-guide',
+    },
+    {
+      label: 'Install the operator',
+      description: 'Use Helm or manifests with the right namespace, identity, and admission model.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, let OpenBaoTenant introduce the namespace, then create the cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Apply a starting profile that matches local evaluation or hardened production.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Prepare for day 2',
+      description: 'Move into production checklist items, backups, exposure, and observability.',
+      docId: 'user-guide/openbaocluster/next-steps',
+    },
+  ]}
+/>
+
+## Prerequisites
+
+<Callout type="tip" title="Requirements">
+
+- **Kubernetes**: v1.33+ (see [Compatibility](../../reference/compatibility.md))
+- **kubectl**: Installed and configured
+- **Permissions**: Cluster-admin access for CRDs, RBAC, and ValidatingAdmissionPolicies
+- **Helm** (optional): v3.12+ for Helm-based installation
+
+</Callout>
+
+<Callout type="note" title="Deployment Modes">
+
+The operator supports two deployment modes:
+
+- **Multi-Tenant** (default): Platform teams providing OpenBao-as-a-Service
+- **Single-Tenant**: Individual teams deploying OpenBao for their application
+
+See [Single-Tenant Mode](single-tenant-mode.md) for single-tenant deployments.
+
+</Callout>
+
+## Install profiles
+
+Use this table to choose the supported install path before changing values or overlays. For most environments, the default answer is Helm plus multi-tenant mode unless your namespace ownership model requires a different shape.
+
+<DecisionTable
+  title="Supported installation paths"
+  columns={['Intent', 'Recommended path', 'Change these settings', 'Verify these outputs']}
+  rows={[
+    {
+      cells: ['Default shared production install', 'Helm, multi-tenant mode', 'release namespace, chart version, controller/provisioner sizing', 'controller and provisioner pods in the rendered operator namespace'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['Dedicated team namespace', 'Helm, tenancy.mode=single', 'tenancy.targetNamespace, optional release namespace', 'only the controller pod runs; WATCH_NAMESPACE matches the target namespace'],
+    },
+    {
+      cells: ['Dedicated team namespace with custom Helm identity', 'Helm, tenancy.mode=single plus custom release name or fullnameOverride', 'release name or fullnameOverride, tenancy.targetNamespace, optional release namespace', 'rendered controller ServiceAccount name, single-tenant RoleBinding subject, admission-policy identity variables, JWT audience'],
+    },
+    {
+      cells: ['Raw multi-tenant install with default identity', 'config/default', 'operator namespace only if you want to fork the default base', 'rendered namespace, controller and provisioner ServiceAccount names, admission policies'],
+    },
+    {
+      cells: ['Raw multi-tenant install with custom identity', 'config/overlays/custom-identity', 'namespace, optional namePrefix', 'rendered ServiceAccount names, RoleBinding subjects, admission-policy identity variables, JWT audience'],
+    },
+    {
+      cells: ['Raw single-tenant install', 'config/overlays/single-tenant', 'operator namespace in the overlay, target namespace in target_namespace_config.yaml', 'rendered operator namespace, WATCH_NAMESPACE, single-tenant RoleBinding subject'],
+    },
+    {
+      cells: ['Raw single-tenant install with custom identity', 'config/overlays/single-tenant-custom-identity', 'namespace, optional namePrefix, target namespace in target_namespace_config.yaml', 'rendered operator namespace, controller ServiceAccount name, WATCH_NAMESPACE, single-tenant RoleBinding subject, admission-policy identity variables'],
+    },
+  ]}
+/>
+
+<Callout type="note" title="Single-tenant customization boundary">
+
+Use `config/overlays/single-tenant` when you only need a custom operator namespace or target namespace.
+Use `config/overlays/single-tenant-custom-identity` when you also need a custom operator identity, such as an extra `namePrefix`.
+
+</Callout>
+
+<Callout type="info" title="Default recommendation">
+
+Start with Helm, keep the default multi-tenant mode, pin the chart release for production,
+and leave admission policies enabled. Move away from that path only for explicit raw-manifest
+control or single-tenant namespace ownership requirements.
+
+</Callout>
+
+## Installation
+
+<Tabs groupId="helm-recommended-openshift-yaml-manifests-developer-source">
+
+<TabItem value="helm-recommended" label="Helm (recommended)">
+
+Install the operator using the official Helm chart. For production, pin the chart release explicitly with `--version`.
+
+<Callout type="note" title="Rendered operator namespace">
+
+The examples below use the default release namespace `openbao-operator-system`. If you install the chart into another namespace, replace it consistently in the commands and later verification steps.
+
+</Callout>
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Install the Helm chart"
+  code={`helm upgrade --install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \\
+  --version <chart-version> \\
+  --namespace openbao-operator-system \\
+  --create-namespace`}
+/>
+
+### Common configuration
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Pin the chart release and right-size the controller"
+  code={`helm upgrade --install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \\
+  --version <chart-version> \\
+  --namespace openbao-operator-system \\
+  --create-namespace \\
+  --set controller.replicas=2 \\
+  --set controller.resources.limits.memory=512Mi`}
+/>
+
+1. Pin the chart release with `--version` for production deployments.
+2. Run multiple replicas for high availability.
+3. Adjust resource limits based on cluster size.
+
+<Callout type="note" title="Chart release pinning vs image override">
+
+For normal installs, pin the chart with `--version` and let the chart's `appVersion` select the matching operator image.
+Use `image.tag` only when you intentionally need a non-default operator image for that chart, such as prerelease validation or a controlled override.
+
+</Callout>
+
+### Single-tenant with custom Helm identity
+
+Helm already supports the equivalent of the raw-manifest custom-identity overlays through the release name and `fullnameOverride`.
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Install in single-tenant mode with a custom identity"
+  code={`helm upgrade --install team-bao oci://ghcr.io/dc-tec/charts/openbao-operator \\
+  --version <chart-version> \\
+  --namespace platform-operators \\
+  --create-namespace \\
+  --set tenancy.mode=single \\
+  --set tenancy.targetNamespace=openbao \\
+  --set fullnameOverride=team-bao-operator`}
+/>
+
+Confirm with `helm template` or `helm get manifest` that:
+
+1. the controller `ServiceAccount` name matches the rendered Helm fullname
+2. the single-tenant `RoleBinding` subject points at that rendered controller `ServiceAccount`
+3. admission-policy variables reference the same rendered operator namespace and controller `ServiceAccount` name
+4. `OPENBAO_JWT_AUDIENCE` on the controller still matches the projected `openbao-token` audience
+
+<Callout type="note">
+
+The chart does not expose per-component custom `ServiceAccount` names. Use the release name or `fullnameOverride` to customize the operator identity while keeping the rendered RBAC and admission-policy references aligned.
+
+</Callout>
+
+### Artifact Hub
+
+Discover package metadata and install snippets on Artifact Hub:
+
+- [Search `openbao-operator` package](https://artifacthub.io/packages/search?repo=openbao-operator)
+
+<Callout type="note">
+
+Artifact Hub indexing can lag shortly after a release is published.
+
+</Callout>
+
+### Full values reference
+
+| Parameter | Description | Default |
+| :--- | :--- | :--- |
+| `image.repository` | Operator image repository | `ghcr.io/dc-tec/openbao-operator` |
+| `image.tag` | Image tag (defaults to appVersion) | `""` |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
+| `imagePullSecrets` | Registry credentials | `[]` |
+| `platform` | Target platform (`auto`, `kubernetes`, `openshift`) | `auto` |
+| `tenancy.mode` | `multi` or `single` | `multi` |
+| `tenancy.targetNamespace` | Target namespace (single-tenant only) | `""` |
+| `controller.replicas` | Controller replica count | `1` |
+| `controller.resources` | Controller resource requests/limits | See values.yaml |
+| `provisioner.replicas` | Provisioner replica count | `1` |
+| `provisioner.resources` | Provisioner resource requests/limits | See values.yaml |
+| `admissionPolicies.enabled` | Enable ValidatingAdmissionPolicies | `true` |
+| `metrics.enabled` | Enable metrics endpoints | `true` |
+
+[Full values.yaml](https://github.com/dc-tec/openbao-operator/blob/main/charts/openbao-operator/values.yaml)
+
+<Callout type="info" title="Air-gapped environments">
+
+To use private registries for the operator and its sidecars (init, backup, upgrade), see the [Air-Gapped / Private Registries](../openbaocluster/configuration/air-gapped.md) guide.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="openshift" label="OpenShift">
+
+For Red Hat OpenShift clusters, the operator defaults to platform auto-detection.
+You can optionally force the platform mode to ensure compatibility with Security Context Constraints (SCC):
+
+<CommandBlock
+  language="bash"
+  label="configure"
+  title="Force OpenShift platform mode"
+  code={`helm upgrade --install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \\
+  --version <chart-version> \\
+  --namespace openbao-operator-system \\
+  --create-namespace \\
+  --set platform=openshift`}
+/>
+
+<Callout type="tip" title="What this setting does">
+
+This setting instructs the chart/operator to omit pinned `runAsUser` / `fsGroup` IDs in generated Pods, allowing OpenShift's SCC admission controller to inject namespace-scoped IDs automatically.
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="yaml-manifests" label="YAML Manifests">
+
+Apply the installer manifest directly from a pinned GitHub Release:
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the pinned installer manifest"
+  code={`kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/install.yaml`}
+/>
+
+<Callout type="note">
+
+Replace `X.Y.Z` with the exact release you intend to run. Use `latest` only for throwaway evaluation, not for production installs.
+
+</Callout>
+
+Raw-manifest installs have three supported starting points:
+
+- `config/default`: default multi-tenant install
+- `config/overlays/custom-identity`: multi-tenant install with custom operator namespace or `namePrefix`
+- `config/overlays/single-tenant`: direct single-tenant install without the provisioner
+- `config/overlays/single-tenant-custom-identity`: direct single-tenant install without the provisioner plus custom operator identity support
+
+<Callout type="tip" title="Custom namespace or prefix">
+
+For raw-manifest installs with a custom operator namespace or extra name prefix, start from `config/overlays/custom-identity`. Set `namespace` there and optionally add `namePrefix`. The controller and provisioner ServiceAccount identities, RoleBinding subjects, and admission-policy identity checks follow the installed ServiceAccounts automatically.
+
+</Callout>
+
+<Callout type="tip" title="Single-tenant raw manifests">
+
+For direct single-tenant installs, start from `config/overlays/single-tenant`. That overlay owns the operator namespace and target namespace wiring instead of relying on manual `WATCH_NAMESPACE` patches.
+
+</Callout>
+
+<Callout type="tip" title="Single-tenant with custom identity">
+
+If you need single-tenant mode and a custom operator identity, such as an extra `namePrefix`, start from `config/overlays/single-tenant-custom-identity`. That overlay keeps the single-tenant namespace wiring and the controller admission-policy identity rewrites aligned in one supported path.
+
+</Callout>
+
+<Callout type="note" title="Operator JWT auth">
+
+If you use custom raw-manifest identities together with manual OpenBao JWT configuration or self-init OIDC bootstrap, verify the rendered controller ServiceAccount name and namespace first. See [Operator Authentication](./operator-authentication#what-must-stay-aligned).
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="developer-source" label="Developer (Source)">
+
+For local development and contribution:
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Install from source for development"
+  code={`# Install CRDs
+make install
+
+# Deploy operator (uses Kustomize)
+make deploy IMG=ghcr.io/dc-tec/openbao-operator:dev`}
+/>
+
+</TabItem>
+
+</Tabs>
+
+## Render verification
+
+Use this checklist for raw-manifest installs.
+
+### Multi-tenant with custom identity
+
+Render the overlay:
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Render the custom-identity overlay"
+  code={`kubectl kustomize config/overlays/custom-identity`}
+/>
+
+Confirm:
+
+1. the rendered operator namespace is the namespace you expect
+2. the controller and provisioner `ServiceAccount` names match your intended install identity
+3. `RoleBinding` and `ClusterRoleBinding` subjects point at those rendered ServiceAccounts
+4. admission-policy variables reference the same rendered namespace and ServiceAccount names
+5. `OPENBAO_JWT_AUDIENCE` on the controller matches the projected `openbao-token` audience
+
+See [Operator Authentication](./operator-authentication#what-must-stay-aligned) for the OpenBao-side JWT binding checks.
+
+### Single-tenant raw manifests
+
+Render the overlay:
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Render the single-tenant overlay"
+  code={`kubectl kustomize config/overlays/single-tenant`}
+/>
+
+Confirm:
+
+1. the rendered operator namespace matches `config/overlays/single-tenant/kustomization.yaml`
+2. `WATCH_NAMESPACE` on the controller matches `config/overlays/single-tenant/target_namespace_config.yaml`
+3. the single-tenant `RoleBinding` namespace matches the same target namespace
+4. the controller `ServiceAccount` subject in that `RoleBinding` points at the rendered operator namespace
+
+If you customize the single-tenant overlay beyond those supported fields, treat the render output as the source of truth.
+
+### Single-tenant with custom identity
+
+Render the overlay:
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Render the single-tenant custom-identity overlay"
+  code={`kubectl kustomize config/overlays/single-tenant-custom-identity`}
+/>
+
+Confirm:
+
+1. the rendered operator namespace matches `config/overlays/single-tenant-custom-identity/kustomization.yaml`
+2. the rendered controller `ServiceAccount` name matches the same overlay after any `namePrefix`
+3. `WATCH_NAMESPACE` on the controller matches `config/overlays/single-tenant-custom-identity/target_namespace_config.yaml`
+4. the single-tenant `RoleBinding` subject points at the rendered controller `ServiceAccount`
+5. controller admission-policy variables reference the same rendered namespace and `ServiceAccount` name
+
+## Verify installation
+
+Check that the operator pods are running:
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check that the operator pods are running"
+  code={`kubectl get pods -n <operator-namespace>`}
+/>
+
+Expected output (multi-tenant mode):
+
+<CommandBlock
+  language="text"
+  label="output"
+  title="Expected output in multi-tenant mode"
+  code={`NAME                                              READY   STATUS    RESTARTS   AGE
+<controller-pod>                                  1/1     Running   0          1m
+<provisioner-pod>                                 1/1     Running   0          1m`}
+/>
+
+<Callout type="success" title="Verify the operator namespace before continuing">
+
+Use this install checkpoint to verify more than pods in `Running`:
+
+- the controller and provisioner pods match the tenancy mode you chose
+- the rendered namespace and ServiceAccount names match your install plan
+- admission policies are installed when they are supposed to be
+- in the default multi-tenant path, you know which namespace will receive the first `OpenBaoTenant`
+- your next step is tenant onboarding or cluster creation, not more install debugging
+
+</Callout>
+
+## Upgrading
+
+### Helm upgrades
+
+<Callout type="warning" title="CRD updates">
+
+Helm does not automatically upgrade CRDs. For releases with CRD changes:
+
+1. Apply CRDs from the release assets first:
+    ```bash
+    kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/crds.yaml
+    ```
+2. Then upgrade the Helm release:
+    ```bash
+    helm upgrade openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \
+      --version X.Y.Z \
+      --namespace openbao-operator-system
+    ```
+
+</Callout>
+
+### YAML manifest upgrades
+
+```bash
+kubectl apply -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/install.yaml
+```
+
+For custom raw-manifest installs, use your rendered namespace, ServiceAccount names, and policy names rather than assuming the repository defaults.
+
+## Uninstallation
+
+<Tabs groupId="helm-yaml-manifests">
+
+<TabItem value="helm" label="Helm">
+
+```bash
+helm uninstall openbao-operator --namespace openbao-operator-system
+```
+
+<Callout type="danger" title="CRDs Retained">
+
+Helm does not delete CRDs by design. To fully remove:
+```bash
+kubectl delete crd openbaoclusters.openbao.org openbaorestores.openbao.org openbaotenants.openbao.org
+```
+
+</Callout>
+
+</TabItem>
+
+<TabItem value="yaml-manifests" label="YAML Manifests">
+
+```bash
+kubectl delete -f https://github.com/dc-tec/openbao-operator/releases/download/X.Y.Z/install.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+## Next steps
+
+<NextActions
+  items={[
+    {
+      label: 'Onboard the target namespace',
+      description: 'In the default multi-tenant path, create OpenBaoTenant, then create the first cluster.',
+      docId: 'user-guide/openbaotenant/onboarding',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Move straight into the first cluster guide after onboarding is complete or when you intentionally chose single-tenant mode.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Review single-tenant mode',
+      description: 'Use the namespace-scoped branch when one team directly owns one namespace and one cluster lifecycle.',
+      docId: 'user-guide/operator/single-tenant-mode',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/operator/single-tenant-mode.md b/website/versioned_docs/version-0.3.0/user-guide/operator/single-tenant-mode.md
new file mode 100644
index 000000000..4f33630f8
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/operator/single-tenant-mode.md
@@ -0,0 +1,239 @@
+---
+title: Single-Tenant Mode
+description: Single-tenant operator deployment for one team that owns one namespace and does not use the default tenant-onboarding model.
+slug: /get-started/single-tenant-mode
+hide_title: true
+pageType: task
+journey: get-started
+---
+
+<PageHeader
+  title="Single-tenant deployment model"
+  lede="Single-tenant mode removes the Provisioner and lets the controller watch one target namespace directly. Use it for dedicated team environments that do not need the default tenant-onboarding path."
+/>
+
+
+
+<DecisionTable
+  title="When to choose single-tenant mode"
+  columns={['Question', 'Multi-tenant default', 'Choose single-tenant when', 'Go deeper']}
+  rows={[
+    {
+      cells: [
+        'Namespace ownership',
+        'Platform teams or shared operators manage multiple target namespaces.',
+        'One team directly owns one namespace and does not need the `OpenBaoTenant` onboarding flow.',
+        'Tenant onboarding and RBAC',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Control-plane shape',
+        'Controller plus Provisioner',
+        'Controller only is the right operational model for this environment.',
+        'Architecture overview',
+      ],
+    },
+    {
+      cells: [
+        'Operational tradeoff',
+        'More default platform structure in exchange for clearer shared-operator boundaries.',
+        'A simpler dedicated setup matters more than cross-namespace platform workflows.',
+        'Deployment decision guide',
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Single-tenant control path"
+  caption="The controller watches one target namespace directly. There is no Provisioner and no tenant onboarding layer in front of the cluster resources."
+  code={`graph LR
+    subgraph OperatorNS["Operator namespace"]
+      Controller["Controller"]
+    end
+
+    subgraph TargetNS["Target namespace"]
+      Cluster["OpenBaoCluster"]
+      STS["StatefulSet"]
+      SVC["Services"]
+      Secret["Workload-facing Secrets"]
+    end
+
+    Controller --> Cluster
+    Cluster --> STS
+    Cluster --> SVC
+    Cluster --> Secret
+
+    classDef control fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+    classDef data fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+
+    class Controller control;
+    class Cluster,STS,SVC,Secret data;`}
+/>
+
+## Install the single-tenant branch
+
+<Tabs groupId="single-tenant-install-path">
+
+<TabItem value="helm" label="Helm">
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Install the operator in single-tenant mode with Helm"
+  code={`helm upgrade --install openbao-operator oci://ghcr.io/dc-tec/charts/openbao-operator \\
+  --version <chart-version> \\
+  --namespace openbao-operator-system \\
+  --create-namespace \\
+  --set tenancy.mode=single \\
+  --set tenancy.targetNamespace=openbao`}
+>
+  Replace `openbao-operator-system` and `openbao` with the namespaces you actually intend to keep operating. In this mode the target namespace is the controller watch scope, not just an example value.
+</CommandBlock>
+
+<Callout type="note" title="Single-tenant still needs a real target namespace">
+
+Create the target namespace through your normal platform workflow before you apply the first `OpenBaoCluster`.
+Single-tenant mode skips `OpenBaoTenant`, but it does not invent the namespace for you.
+
+</Callout>
+
+<DecisionTable
+  kind="reference"
+  title="Helm settings to care about"
+  columns={['Setting', 'What it controls', 'Default or note']}
+  rows={[
+    {
+      cells: ['`tenancy.mode`', 'Switches the operator to the controller-only path', '`single` for this branch'],
+      emphasis: 'recommended',
+    },
+    {
+      cells: ['`tenancy.targetNamespace`', 'Sets the watched namespace and target RoleBinding scope', 'Defaults to the release namespace when unset'],
+    },
+    {
+      cells: ['`fullnameOverride` or release name', 'Changes the rendered controller identity', 'Recheck JWT auth and RoleBinding subjects after custom naming'],
+    },
+    {
+      cells: ['`admissionPolicies.enabled`', 'Controls ValidatingAdmissionPolicies for the install', 'Keep enabled unless your platform does not support them'],
+    },
+  ]}
+/>
+
+</TabItem>
+
+<TabItem value="manifests" label="Raw manifests">
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the single-tenant overlay"
+  code={`kubectl apply -k config/overlays/single-tenant`}
+>
+  Use `config/overlays/single-tenant-custom-identity` instead when you need both the single-tenant branch and a custom operator identity.
+</CommandBlock>
+
+<CommandBlock
+  language="yaml"
+  label="configure"
+  title="Set the target namespace"
+  code={`apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: single-tenant-settings
+  annotations:
+    config.kubernetes.io/local-config: "true"
+data:
+  WATCH_NAMESPACE: my-openbao`}
+>
+  The target namespace must match both the controller `WATCH_NAMESPACE` value and the generated RoleBinding namespace.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Render the overlay"
+  code={`kubectl kustomize config/overlays/single-tenant`}
+>
+  Confirm that the controller ServiceAccount subject, RoleBinding namespace, and `WATCH_NAMESPACE` value all point at the same intended target.
+</CommandBlock>
+
+</TabItem>
+
+</Tabs>
+
+<Callout type="note" title="What changes in this branch">
+
+Single-tenant mode removes the Provisioner, skips `OpenBaoTenant`, and gives the controller direct namespace-scoped access instead.
+That is simpler for a dedicated team, but it also means the operator is no longer modeling the default shared-platform boundary for you.
+
+</Callout>
+
+## Verify the install
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Check that only the controller is running"
+  code={`kubectl get pods -n <operator-namespace>`}
+>
+  In single-tenant mode, expect the controller deployment to be running and no Provisioner pod to exist.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Confirm the watched namespace matches the intended target"
+  code={`kubectl get deploy -n <operator-namespace> openbao-operator-controller \\
+  -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="WATCH_NAMESPACE")].value}'`}
+>
+  Confirm this value matches the target namespace you plan to use for the first `OpenBaoCluster`.
+</CommandBlock>
+
+## Migration guidance
+
+<DecisionTable
+  title="When to migrate between tenancy modes"
+  columns={['Move', 'Use it when', 'Main work before or after', 'Watch for']}
+  rows={[
+    {
+      cells: [
+        'Multi-tenant to single-tenant',
+        'A dedicated team is taking full ownership of one namespace and no longer needs tenant onboarding.',
+        'Re-render the operator, remove `OpenBaoTenant` usage, and verify the direct RoleBinding scope.',
+        'Direct namespace permissions replace the previous tenant boundary.',
+      ],
+      emphasis: 'recommended',
+    },
+    {
+      cells: [
+        'Single-tenant to multi-tenant',
+        'You need shared platform ownership or want to return to the default onboarding model.',
+        'Re-enable the Provisioner and model namespace access through `OpenBaoTenant` resources.',
+        'Manual single-tenant RoleBindings must not linger after the switch.',
+      ],
+    },
+  ]}
+/>
+
+<NextActions
+  title="Return to the main path"
+  items={[
+    {
+      label: 'Install the operator',
+      description: 'Go back to the install guide once the tenancy branch and rendered namespaces are clear.',
+      docId: 'user-guide/operator/installation',
+    },
+    {
+      label: 'Create your first cluster',
+      description: 'Move into the first cluster guide after the controller watch scope and target namespace are verified.',
+      docId: 'user-guide/openbaocluster/getting-started',
+    },
+    {
+      label: 'Review operator identity and access',
+      description: 'Double-check auth and RoleBinding surfaces when you are also customizing names or namespaces.',
+      docId: 'user-guide/operator/identity-and-access',
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3.md
new file mode 100644
index 000000000..a8d738a36
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3.md
@@ -0,0 +1,173 @@
+---
+title: EKS Development / Shared Edge
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated cloud baseline for a development-profile OpenBao deployment on Amazon EKS with AWS KMS auto-unseal, a shared terminating edge, JWT bootstrap, and S3 backups.
+---
+
+<PageHeader
+  title="EKS development baseline with AWS integrations"
+  lede="This cloud baseline keeps the posture intentionally Development while validating the AWS integrations needed for cloud bring-up: KMS auto-unseal, workload identity, shared-edge exposure, JWT bootstrap, and snapshot upload to S3."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a Development-profile cluster can bootstrap on EKS with AWS KMS auto-unseal and no static root-token workflow",
+      "JWT bootstrap and human admin JWT access both work under the cloud control-plane conditions EKS introduces",
+      "a shared terminating Gateway can expose the development cluster without requiring passthrough or public ACME",
+      "backup Jobs can authenticate separately from the main workload and write snapshots to S3 successfully",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+Cloud reference architecture. This is a realistic EKS validation and bring-up topology, but it is intentionally a Development lane rather than a production target.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Profile",
+        "`spec.profile: Development`",
+        "The lane is meant for cloud bring-up, demos, and operational validation, not for a production-ready posture.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Seal path",
+        "AWS KMS via workload identity",
+        "The main workload uses cloud auto-unseal through AWS KMS rather than local or static secret material.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "Shared terminating Gateway API edge",
+        "The lane keeps public routing simple and avoids ACME passthrough complexity during bring-up.",
+      ],
+    },
+    {
+      cells: [
+        "Backup path",
+        "S3 with a separate backup identity",
+        "Backup execution stays separate from the main KMS identity surface.",
+      ],
+    },
+    {
+      cells: [
+        "Validation scope",
+        "Manual EKS validation plus operator lifecycle behavior",
+        "The baseline covers the cloud integration path used in the validated EKS development environment.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The main workload uses one cloud identity for KMS, backup Jobs use another for S3, and the public edge remains a shared terminating layer rather than a dedicated passthrough stack."
+  code={`flowchart LR
+    Client["Operator or admin"] -->|"HTTPS"| Edge["Shared Gateway API edge"]
+    Edge -->|"Re-encrypted HTTPS"| Public["OpenBao public Service"]
+    Public --> Bao["OpenBao Pods"]
+
+    Operator["OpenBao Operator"] -->|"JWT bootstrap"| Bao
+    Admin["Admin ServiceAccount token"] -->|"JWT login"| Bao
+    Bao -->|"AWS KMS"| KMS["AWS KMS key"]
+    Backup["Backup Job"] -->|"S3 snapshot upload"| S3["S3 bucket"]
+    Bao -->|"IRSA / workload identity"| MainIAM["Main workload IAM role"]
+    Backup -->|"IRSA / workload identity"| BackupIAM["Backup IAM role"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,Admin read;
+    class Edge,Operator,Backup process;
+    class Public,Bao,KMS,S3,MainIAM,BackupIAM write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it optimizes", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Shared terminating edge",
+        "Simple cloud bring-up with a familiar ingress model.",
+        "The lane is for proving integrations quickly, not for rehearsing production passthrough behavior.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Separate KMS and backup identities",
+        "Unseal permissions and object-storage permissions stay decoupled.",
+        "This is the cloud-specific security boundary the lane needs to prove before a hardened rollout.",
+      ],
+    },
+    {
+      cells: [
+        "Development profile",
+        "Fast bring-up and low-friction validation on real infrastructure.",
+        "The lane should prove AWS integrations without also forcing the full public-ACME hardening path.",
+      ],
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep `spec.profile: Development` and treat the lane as bring-up coverage, not a production recommendation",
+    "keep the shared terminating edge and do not switch the same lane to passthrough midstream",
+    "keep separate IAM paths for KMS and S3 so backup behavior is actually validated",
+    "keep JWT bootstrap enabled for both operator-owned auth and human admin access",
+    "use a bucket, region, and Gateway path that are all reachable from the exact EKS environment you are validating",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The EKS development lane covered bootstrap, AWS KMS auto-unseal, JWT bootstrap on EKS, human admin JWT login, Gateway exposure through the shared edge, and successful S3 backups.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This baseline does not cover the hardened public-endpoint path, ACME passthrough, or a final production posture. It covers the AWS control-plane integrations used in the validated development environment.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Deployment recipe",
+      description: "Apply the exact EKS development lane with KMS, shared-edge exposure, and S3 backup wiring.",
+      docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3",
+    },
+    {
+      label: "Backup operations",
+      description: "Review the generic backup model behind the lane's S3 configuration and retention behavior.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "EKS Hardened",
+      description: "Move to the hardened cloud baseline when you need public ACME and a dedicated passthrough edge.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme.md
new file mode 100644
index 000000000..7f012817d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme.md
@@ -0,0 +1,182 @@
+---
+title: EKS Hardened / Public ACME
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated hardened cloud baseline for OpenBao on Amazon EKS with AWS KMS auto-unseal, a dedicated public passthrough Gateway, OpenBao-managed ACME, and S3 backups.
+---
+
+<PageHeader
+  title="Hardened EKS baseline with public ACME"
+  lede="This cloud baseline is the hardened EKS topology validated by the project. It uses AWS KMS for auto-unseal, a dedicated public passthrough Gateway, OpenBao-managed ACME, and S3 backups through a separate identity."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a Hardened-profile cluster can bootstrap on EKS with KMS auto-unseal and signed helper images",
+      "OpenBao-managed ACME can issue and serve the public certificate while the Gateway remains pure passthrough",
+      "JWT bootstrap, admin JWT login, and S3 backups all work under the same hardened cloud posture",
+      "the dedicated public edge can stay separate from the terminating admin edge used for the rest of the platform",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+Cloud reference architecture. This is the production-style Amazon EKS baseline validated by the project.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Profile",
+        "`spec.profile: Hardened`",
+        "The baseline uses the hardened production-style posture rather than the development baseline defaults.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Seal path",
+        "AWS KMS via workload identity",
+        "The main workload uses a cloud-native unseal path rather than static or external secret material.",
+      ],
+    },
+    {
+      cells: [
+        "TLS model",
+        "`spec.tls.mode: ACME`",
+        "OpenBao remains the TLS endpoint and owns the public certificate lifecycle directly.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "Dedicated public Gateway API passthrough",
+        "The hardened hostname stays isolated from the shared terminating admin edge and preserves `tls-alpn-01` behavior.",
+      ],
+    },
+    {
+      cells: [
+        "Backup path",
+        "S3 with a separate backup identity",
+        "Backup execution remains separate from KMS unseal and public-edge concerns.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The hardened hostname lives on its own passthrough edge, OpenBao handles ACME itself, and the cluster still keeps backup and unseal identity surfaces separate."
+  code={`flowchart LR
+    Client["OpenBao client"] -->|"HTTPS (SNI)"| Edge["Dedicated public passthrough Gateway"]
+    Edge -->|"TLS passthrough"| Public["OpenBao public Service / ACME endpoint"]
+    Public --> Bao["OpenBao Pods"]
+
+    Shared["Shared admin edge"] -->|"Terminating HTTPS"| AdminTools["ArgoCD / Grafana / Prometheus"]
+    Operator["OpenBao Operator"] -->|"JWT bootstrap"| Bao
+    Admin["Admin ServiceAccount token"] -->|"JWT login"| Bao
+    Bao -->|"AWS KMS"| KMS["AWS KMS key"]
+    Backup["Backup Job"] -->|"S3 snapshot upload"| S3["S3 bucket"]
+    Cache["Shared ACME cache PVC"] <--> Bao
+    Bao -->|"IRSA / workload identity"| MainIAM["Main workload IAM role"]
+    Backup -->|"IRSA / workload identity"| BackupIAM["Backup IAM role"]
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,Admin read;
+    class Edge,Shared,Operator,Backup process;
+    class Public,Bao,KMS,S3,Cache,AdminTools,MainIAM,BackupIAM write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it protects", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Dedicated passthrough Gateway",
+        "The public OpenBao hostname keeps end-to-end TLS ownership inside OpenBao.",
+        "The hardened hostname should not inherit the operational compromises of a shared terminating admin edge.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "OpenBao-managed ACME",
+        "Certificate issuance stays part of the OpenBao control surface.",
+        "The lane is meant to prove the operator plus OpenBao certificate path, not an external certificate controller.",
+      ],
+    },
+    {
+      cells: [
+        "Shared ACME cache",
+        "Multi-replica certificate state remains consistent across Pods.",
+        "The lane is not valid for HA ACME without an RWX-capable cache path.",
+      ],
+    },
+    {
+      cells: [
+        "Separate admin edge",
+        "Public ACME reachability does not force the rest of the platform onto the same public exposure contract.",
+        "The hardened lane needs this separation to stay operationally realistic.",
+      ],
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep the hardened hostname publicly reachable on port `443` for ACME validation",
+    "keep the public OpenBao hostname on a dedicated passthrough Gateway instead of the shared terminating edge",
+    "keep the ACME shared cache on RWX-capable storage for multi-replica safety",
+    "keep signed helper images and hardened verification enabled",
+    "keep backup and unseal IAM roles separate so the security model you validated is the one you actually operate",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The hardened EKS lane covered bootstrap, KMS auto-unseal, OpenBao-managed public ACME certificate issuance, Gateway passthrough, JWT bootstrap, human admin JWT login, and successful S3 backups.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This baseline does not cover source-restricted public hostnames, externally managed TLS, or a terminating Gateway in front of OpenBao. Those choices require a different topology.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Deployment recipe",
+      description: "Apply the exact EKS hardened lane with KMS, public ACME, dedicated passthrough, and S3 backup wiring.",
+      docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme",
+    },
+    {
+      label: "TLS and workload identity",
+      description: "Review the generic TLS ownership and workload-identity model behind the lane.",
+      docId: "security/workload/tls",
+    },
+    {
+      label: "Platform controls",
+      description: "Cross-check the hardened cloud lane against the admission, RBAC, and network controls the rest of the docs recommend.",
+      docId: "security/infrastructure/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/index.md
new file mode 100644
index 000000000..8e6178aea
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/cloud/index.md
@@ -0,0 +1,62 @@
+---
+title: Cloud Baselines
+hide_title: true
+pageType: landing
+description: Validated cloud baselines for OpenBao Operator, pairing each tested topology with the recipe that reproduces it.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Cloud Baselines"
+  title="Validated cloud baselines"
+  lede="Amazon EKS validated baselines are listed here, each linked to its matching deployment recipe."
+  actions={[
+    {label: "Open EKS Development", docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3", variant: "primary"},
+    {label: "Open EKS Hardened", docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Use cloud baselines to"
+    items={[
+      "compare validated development and hardened EKS topologies",
+      "see the exact trust boundary, edge model, and storage assumptions before deployment",
+      "move from architecture to deployment recipe without losing the lane context",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Validated cloud lanes"
+  items={[
+    {
+      eyebrow: "01",
+      title: "EKS Development",
+      description: "EKS development baseline with shared terminating edge, AWS KMS auto-unseal, JWT bootstrap, and S3 backups.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3",
+      actionLabel: "Open lane",
+    },
+    {
+      eyebrow: "02",
+      title: "EKS Hardened",
+      description: "EKS hardened baseline with dedicated passthrough edge, AWS KMS auto-unseal, OpenBao-managed ACME, and S3 backups.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+      actionLabel: "Open lane",
+    },
+  ]}
+/>
+
+<NextActions
+  title="Related catalogs"
+  items={[
+    {
+      label: "Cloud recipe catalog",
+      description: "Browse the cloud deployment procedures directly if you already know which lane you want.",
+      docId: "user-guide/validated-deployments/recipes/cloud/index",
+    },
+    {
+      label: "Validated deployments overview",
+      description: "Return to the section entry if you still need to compare cloud and local baselines.",
+      docId: "user-guide/validated-deployments/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/index.md
new file mode 100644
index 000000000..2b0a6b3be
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/index.md
@@ -0,0 +1,35 @@
+---
+title: Reference Architecture Catalog
+hide_title: true
+pageType: landing
+description: Catalog of validated reference architectures, grouped by cloud and local environment.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Architecture Catalog"
+  title="Validated architecture catalog"
+  lede="Reference architectures are grouped by validated deployment baseline. Review topology, invariants, and assumptions here before following a recipe."
+  actions={[
+    {label: "Open cloud baselines", docId: "user-guide/validated-deployments/architectures/cloud/index", variant: "primary"},
+    {label: "Open local baselines", docId: "user-guide/validated-deployments/architectures/local/index", variant: "secondary"},
+  ]}
+/>
+
+<RouteList
+  title="Architecture catalogs"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Cloud baselines",
+      description: "Amazon EKS topologies with matching recipes.",
+      docId: "user-guide/validated-deployments/architectures/cloud/index",
+    },
+    {
+      eyebrow: "02",
+      title: "Local baselines",
+      description: "Validated k3d lanes for development, hardened rehearsal, and cross-cluster DR.",
+      docId: "user-guide/validated-deployments/architectures/local/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/index.md
new file mode 100644
index 000000000..6ae1fe1b9
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/index.md
@@ -0,0 +1,82 @@
+---
+title: Local Baselines
+hide_title: true
+pageType: landing
+description: Validated local baselines for k3d, including development, hardened rehearsal, and cross-cluster DR lanes.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Local Baselines"
+  title="Validated local baselines"
+  lede="Validated k3d baselines are listed here for development, hardened rehearsal, and cross-cluster DR."
+  actions={[
+    {label: "Open k3d Development", docId: "user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs", variant: "primary"},
+    {label: "Open k3d Cross-Cluster DR", docId: "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Use local baselines to"
+    items={[
+      "rehearse a development or hardened lane on workstation-grade infrastructure",
+      "exercise a boundary such as external TLS passthrough, internal ACME, or shared Transit unseal",
+      "practice restore and cutover behavior in the validated cross-cluster DR lane",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Validated local lanes"
+  items={[
+    {
+      eyebrow: "01",
+      title: "k3d Development",
+      description: "Development profile with shared terminating edge, RustFS backups, and JWT bootstrap for rehearsal and integration work.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs",
+      actionLabel: "Open lane",
+    },
+    {
+      eyebrow: "02",
+      title: "k3d Hardened / External TLS",
+      description: "Hardened external-certificate baseline with Transit auto-unseal, external TLS Secrets, and user-managed passthrough.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls",
+      actionLabel: "Open lane",
+    },
+    {
+      eyebrow: "03",
+      title: "k3d Hardened / ACME",
+      description: "Hardened ACME baseline with Transit auto-unseal, OpenBao-managed ACME, and local hostname resolution.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme",
+      actionLabel: "Open lane",
+    },
+    {
+      eyebrow: "04",
+      title: "k3d Cross-Cluster DR",
+      description: "Cross-cluster DR baseline with shared Transit, shared snapshot storage, and restore rehearsal across source and target clusters.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs",
+      actionLabel: "Open lane",
+    },
+  ]}
+/>
+
+<Callout type="note" title="Lane-specific runbook scope">
+
+Generic backup and restore procedures belong in the main `Operate` docs. The cross-cluster DR restore procedure stays here because it depends on the DR-lane assumptions used in this catalog.
+
+</Callout>
+
+<NextActions
+  title="Related catalogs"
+  items={[
+    {
+      label: "Local recipe catalog",
+      description: "Browse the local deployment procedures directly if you already know which lane you want to reproduce.",
+      docId: "user-guide/validated-deployments/recipes/local/index",
+    },
+    {
+      label: "Generic restore guide",
+      description: "Use the main restore docs for the canonical workflow outside the specific DR proving lane.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs.md
new file mode 100644
index 000000000..a17cdac73
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs.md
@@ -0,0 +1,186 @@
+---
+title: k3d Cross-Cluster DR
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated local disaster-recovery baseline for OpenBao on k3d with a shared Transit seal root, RustFS snapshot transfer, and manual cutover across source and target clusters.
+---
+
+<PageHeader
+  title="Local cross-cluster DR baseline"
+  lede="This local DR baseline keeps the source, target, and shared trust services separated so backup, restore, unseal, and cutover all cross the same kinds of boundaries used in a real disaster-recovery event."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a snapshot can leave the source cluster, cross an object-storage boundary, and restore into a different target cluster",
+      "the restored target can unseal only because it shares the same external Transit root of trust as the source",
+      "restore verification can confirm both credential cutover and data cutover before any manual failover happens",
+      "the operator's backup and restore workflows still work when source and target are split across real ingress and storage boundaries",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+This local disaster-recovery reference architecture uses k3d to validate the DR invariants for backup, restore, unseal, and manual cutover before moving to a cloud recovery pair.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Cluster split",
+        "One infra cluster, one source cluster, one target cluster",
+        "Restore crosses a real cluster boundary instead of staying inside one namespace or one API server.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Seal path",
+        "Shared external Transit key",
+        "The target can only unseal restored data because it shares the same external seal root of trust as the source.",
+      ],
+    },
+    {
+      cells: [
+        "Transfer boundary",
+        "RustFS S3-compatible bucket",
+        "Snapshots move through a real object-storage boundary that both clusters can reach independently.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "Dedicated passthrough endpoints for infra, source, and target",
+        "The lane validates real ingress reachability without collapsing TLS termination into a single local shortcut.",
+      ],
+    },
+    {
+      cells: [
+        "Cutover model",
+        "Manual restore and manual client or DNS cutover",
+        "The baseline covers restore correctness and does not include automatic failover orchestration.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The source cluster writes snapshots to shared storage, the target cluster restores from that storage, and both sides depend on the same external Transit key to make restored data usable."
+  code={`flowchart LR
+    Client["Operator or admin"] -->|"HTTPS (SNI)"| SourceEdge["Source passthrough edge"]
+    Client -->|"HTTPS (SNI)"| TargetEdge["Target passthrough edge"]
+
+    SourceEdge -->|"TLS passthrough"| SourceBao["Source OpenBao"]
+    TargetEdge -->|"TLS passthrough"| TargetBao["Target OpenBao"]
+
+    SourceOp["Source Operator"] -->|"backup orchestration"| SourceBao
+    TargetOp["Target Operator"] -->|"restore orchestration"| TargetBao
+    SourceBao -->|"snapshot upload"| RustFS["Shared RustFS bucket"]
+    RestoreJob["Restore Job"] -->|"snapshot download"| RustFS
+    RestoreJob -->|"snapshot restore"| TargetBao
+
+    SourceBao -->|"Transit encrypt/decrypt"| Trust["Shared Transit provider"]
+    TargetBao -->|"Transit encrypt/decrypt"| Trust
+    InfraEdge["Infra passthrough edge"] -->|"TLS passthrough"| Trust
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,RestoreJob read;
+    class SourceEdge,TargetEdge,InfraEdge,SourceOp,TargetOp process;
+    class SourceBao,TargetBao,Trust,RustFS write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it protects", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Shared seal root",
+        "Restored data is still decryptable after it lands in the target cluster.",
+        "This is the core DR invariant. Without a shared external seal root, the target can restore bits and still fail to unseal.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Separate infra cluster for trust services",
+        "The shared Transit dependency stays independent from source and target failure domains.",
+        "The lane should treat trust services as an external dependency, not as part of either OpenBao cluster.",
+      ],
+    },
+    {
+      cells: [
+        "Shared RustFS bucket",
+        "The restore uses the same object-transfer shape as a real remote-storage path.",
+        "The lane exercises snapshot handoff through shared object storage instead of a local disk copy.",
+      ],
+    },
+    {
+      cells: [
+        "Manual cutover",
+        "Operators verify the target before traffic moves.",
+        "The lane proves correctness and operator workflow, not automated failover policy.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep the source and target on the same OpenBao version for the restore event",
+    "keep the source and target pointed at the same Transit address, CA bundle, SNI, and key name",
+    "keep shared object storage reachable from both clusters before you start a backup or restore",
+    "keep the target cluster created ahead of time with restore auth configured",
+    "perform cutover only after credential and data verification succeeds on the restored target",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The local DR lane proved source backup to RustFS, restore into a separate target cluster, target unseal with the shared Transit key, and post-restore checks that source credentials and source data replaced the target bootstrap state.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This baseline does not define automatic failover or a cloud DR reference. It covers a validated manual recovery flow with explicit preconditions for backup, restore, and cutover.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Bootstrap recipe",
+      description: "Stand up the infra, source, and target clusters that make up the DR validation environment.",
+      docId: "user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap",
+    },
+    {
+      label: "DR restore runbook",
+      description: "Run the destructive restore workflow and verify that source state replaced target state cleanly.",
+      docId: "user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs",
+    },
+    {
+      label: "Restore from backup",
+      description: "Review the generic restore behavior behind the lane-specific runbook.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs.md
new file mode 100644
index 000000000..9ffc0dbf4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs.md
@@ -0,0 +1,180 @@
+---
+title: k3d Development / Shared Edge
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated local baseline for a development-profile OpenBao deployment on k3d with operator-managed TLS, a shared terminating edge, RustFS backups, and blue/green upgrades.
+---
+
+<PageHeader
+  title="Local development lane with shared edge and RustFS"
+  lede="This validated local baseline covers development work on k3d with a shared terminating edge, operator-managed TLS, RustFS backups, and blue/green upgrades. Use it to exercise the cluster lifecycle with a low-friction local topology."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a Development-profile cluster can bootstrap cleanly on k3d without extra cloud dependencies",
+      "the shared terminating edge can front OpenBao alongside the rest of the local platform toolchain",
+      "operator-managed TLS, self-init, JWT bootstrap, and RustFS backups can coexist in one repeatable lane",
+      "blue/green upgrades can be rehearsed locally before moving to a hardened or cloud baseline",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+This local reference architecture uses k3d as a development environment for operator bring-up, UI checks, backup rehearsal, and upgrade behavior. It is a validated local lane rather than a production target.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Profile",
+        "`spec.profile: Development`",
+        "The lane is intentionally optimized for speed and validation coverage, not a production-ready posture.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "TLS model",
+        "`spec.tls.mode: OperatorManaged`",
+        "The operator owns the internal server certificate path so the lane can stay self-contained.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "Shared terminating Gateway API edge",
+        "The same local edge can front OpenBao, ArgoCD, Grafana, and other tools without a dedicated passthrough stack.",
+      ],
+    },
+    {
+      cells: [
+        "Backup target",
+        "RustFS via the S3-compatible API",
+        "The baseline covers snapshot behavior against a real object-storage boundary without cloud credentials.",
+      ],
+    },
+    {
+      cells: [
+        "Upgrade model",
+        "`upgrade.strategy: BlueGreen`",
+        "The lane doubles as a low-risk rehearsal environment for upgrade orchestration and cutover behavior.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The shared terminating edge stays simple, the operator owns TLS and bootstrap, and the backup path leaves the cluster through a separate RustFS boundary."
+  code={`flowchart LR
+    Client["Operator or admin"] -->|"HTTPS"| Edge["Shared Gateway API edge"]
+    Edge -->|"Re-encrypted HTTPS"| Public["OpenBao public Service"]
+    Public --> Bao["OpenBao Pods"]
+
+    Operator["OpenBao Operator"] -->|"JWT bootstrap"| Bao
+    Admin["Admin ServiceAccount token"] -->|"JWT login"| Bao
+    Demo["Optional demo userpass login"] --> Bao
+    Backup["Backup Job"] -->|"S3-compatible snapshots"| RustFS["RustFS bucket"]
+    Upgrade["Blue/green upgrade flow"] --> Bao
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,Admin,Demo read;
+    class Edge,Operator,Backup,Upgrade process;
+    class Public,Bao,RustFS write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it optimizes", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Shared terminating edge",
+        "Fast local bring-up with one ingress surface for multiple tools.",
+        "This keeps the lane practical for day-to-day operator work and avoids dedicating a separate passthrough edge to a dev profile.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "RustFS for backups",
+        "A real S3-compatible transfer boundary with no cloud dependency.",
+        "The lane exercises snapshot upload and retention behavior against an S3-compatible API.",
+      ],
+    },
+    {
+      cells: [
+        "Blue/green upgrades",
+        "Upgrade behavior can be rehearsed locally before a hardened rollout.",
+        "The development lane is where you want fast iteration on rollout logic and status transitions.",
+      ],
+    },
+    {
+      cells: [
+        "Optional demo login",
+        "UI access stays easy during development and demos.",
+        "It is a convenience for local validation only and should never be mistaken for a production auth pattern.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep `spec.profile: Development` and do not treat the lane as a production hardening reference",
+    "keep the shared terminating Gateway in front of the cluster instead of switching to passthrough mid-lane",
+    "keep the RustFS endpoint reachable from the tenant namespace and use a dedicated backup Secret",
+    "treat the demo `userpass` login as local-only convenience and remove it from any shared environment",
+    "disable AppArmor only when the local runtime requires it and document that as a node limitation, not a preferred default",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The local development lane exercised self-init bootstrap, JWT admin login, optional demo UI login, shared-edge exposure, scheduled and manual backup behavior to RustFS, and blue/green upgrade rehearsal.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This lane does not define a production reference or a hardened security posture. It is a local validation environment for shared-edge routing, backup behavior, and upgrade rehearsal.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Deployment recipe",
+      description: "Reproduce the exact development lane with tenant onboarding, self-init, shared-edge exposure, and RustFS backups.",
+      docId: "user-guide/validated-deployments/recipes/local/development-self-init-userpass",
+    },
+    {
+      label: "Backup operations",
+      description: "Review the generic backup model behind the RustFS portion of this validated lane.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "Get Started",
+      description: "Use the operator onboarding path when you need the product-wide default workflow instead of a validated local lane.",
+      docId: "user-guide/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme.md
new file mode 100644
index 000000000..f7a6dacbb
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme.md
@@ -0,0 +1,179 @@
+---
+title: k3d Hardened / ACME
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated local baseline for a hardened OpenBao deployment on k3d with Transit auto-unseal, an internal ACME issuer, and user-managed TLS passthrough.
+---
+
+<PageHeader
+  title="Local hardened lane with private ACME"
+  lede="This validated local baseline keeps the hardened posture, keeps the unseal root external, and keeps OpenBao as the TLS endpoint while an internal ACME CA validates certificate issuance through a user-managed passthrough edge."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a Hardened cluster can bootstrap locally while keeping the seal dependency outside the tenant namespace",
+      "OpenBao-managed ACME issuance works when the validator reaches the passthrough edge with the expected hostname",
+      "Transit auto-unseal and ACME trust material can coexist in one shared trust-services dependency",
+      "local rehearsal covers ACME readiness and probe behavior before a public-cloud baseline",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+This local reference architecture uses k3d to rehearse hardened deployments that keep TLS passthrough in OpenBao and use a private ACME trust chain. It is a local validation lane rather than a production target.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Profile",
+        "`spec.profile: Hardened`",
+        "The lane only matters if the operator enforces the hardened policy surface while ACME and Transit are both active.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Seal path",
+        "Shared external OpenBao Transit provider",
+        "The seal root stays outside the cluster, which keeps the lane aligned with a real external dependency model.",
+      ],
+    },
+    {
+      cells: [
+        "TLS model",
+        "`spec.tls.mode: ACME` with an internal ACME CA",
+        "OpenBao remains the TLS endpoint while the lane avoids dependence on public ACME during local validation.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "User-managed Traefik TCP passthrough",
+        "TLS must reach OpenBao untouched for ACME, so the edge must pass traffic through instead of terminating it.",
+      ],
+    },
+    {
+      cells: [
+        "Validation scope",
+        "Local ACME lifecycle coverage plus hardened bootstrap",
+        "The baseline covers ACME readiness, trust material, and bootstrap behavior together.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The same external trust-services dependency supplies both Transit auto-unseal and the private ACME directory, while the ingress layer remains pure passthrough."
+  code={`flowchart LR
+    Client["OpenBao client"] -->|"HTTPS (SNI)"| Edge["Traefik IngressRouteTCP"]
+    Edge -->|"TLS passthrough"| ACMESvc["OpenBao ACME Service"]
+    ACMESvc --> Bao["OpenBao Pods"]
+
+    Operator["OpenBao Operator"] -->|"JWT bootstrap"| Bao
+    Admin["Admin ServiceAccount token"] -->|"JWT login"| Bao
+    Bao -->|"Transit encrypt/decrypt"| Trust["Shared trust-services OpenBao"]
+    Bao -->|"ACME directory + tls-alpn-01"| Trust
+    DNS["ACME hostname resolution"] --> Edge
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,Admin read;
+    class Edge,Operator,DNS process;
+    class ACMESvc,Bao,Trust write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it protects", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Private ACME issuer",
+        "The lane can prove ACME behavior without assuming public DNS and internet reachability.",
+        "Local hardened rehearsal should prove OpenBao-managed issuance, not public CA operations.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Hostname resolves back to the passthrough edge",
+        "The validator actually reaches the endpoint OpenBao serves for `tls-alpn-01`.",
+        "Successful name resolution is the invariant; the local CoreDNS rewrite is only one implementation of it.",
+      ],
+    },
+    {
+      cells: [
+        "Shared trust-services dependency",
+        "Transit and ACME both depend on the same external trust boundary.",
+        "This keeps the local lane close to the production-style trust split without requiring cloud services.",
+      ],
+    },
+    {
+      cells: [
+        "Passthrough stays user-managed",
+        "OpenBao remains the TLS endpoint.",
+        "The lane intentionally avoids making shared terminating ingress behavior part of the hardened ACME contract.",
+      ],
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep `spec.profile: Hardened` and keep the trust-services endpoint reachable for both Transit and ACME",
+    "keep the ACME hostname resolving back to the passthrough edge from the validating environment",
+    "keep the passthrough route targeting the dedicated `-acme` Service on port `443`",
+    "mount both the Transit CA bundle and the ACME issuer CA bundle in the Secret expected by the lane",
+    "disable AppArmor only when the local runtime forces it and treat that as a local node concession",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The validated local lane exercised hardened bootstrap with self-init, Transit auto-unseal through shared trust services, OpenBao-managed ACME issuance from a private CA, human admin JWT login, and external access over user-managed passthrough.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This lane does not prove public ACME behavior or replace a cloud ingress baseline. It is a local rehearsal environment for the hardened ACME control path.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Deployment recipe",
+      description: "Apply the exact steps that reproduce the validated hardened ACME lane in the local environment.",
+      docId: "user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls",
+    },
+    {
+      label: "TLS and workload identity",
+      description: "Review the generic TLS ownership and identity model behind the lane.",
+      docId: "security/workload/tls",
+    },
+    {
+      label: "EKS Hardened",
+      description: "Compare the local private-ACME rehearsal path with the public-ACME cloud baseline.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls.md
new file mode 100644
index 000000000..7a7a431ac
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls.md
@@ -0,0 +1,172 @@
+---
+title: k3d Hardened / External TLS
+hide_title: true
+pageType: concept
+journey: validated-deployments
+description: Validated local baseline for a hardened OpenBao deployment on k3d with Transit auto-unseal, external TLS Secrets, and user-managed passthrough access.
+---
+
+<PageHeader
+  title="Local hardened lane with external TLS"
+  lede="This validated local baseline covers a hardened deployment with external TLS, an external seal dependency, and user-managed TCP passthrough."
+/>
+
+<Checklist
+    title="Validated coverage"
+    items={[
+      "a Hardened cluster can bootstrap locally without falling back to operator-managed TLS or static unseal",
+      "Transit auto-unseal can stay outside the cluster while self-init and JWT bootstrap still succeed",
+      "externally managed TLS Secrets and passthrough traffic can remain separate from the operator's edge integration model",
+      "the local environment can rehearse a production-style trust split",
+    ]}
+  />
+
+
+<Callout type="note" title="Baseline scope">
+
+This local reference architecture uses k3d to rehearse a hardened deployment with an external seal provider and externally managed certificates. It is a local validation lane rather than a production target.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline summary"
+  columns={["Surface", "Choice", "Why it matters"]}
+  rows={[
+    {
+      cells: [
+        "Profile",
+        "`spec.profile: Hardened`",
+        "The lane is valuable only if the operator enforces the production-style posture and rejects the relaxed development shortcuts.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "Seal path",
+        "External Transit provider",
+        "The unseal root stays outside the cluster so the baseline exercises a real external dependency rather than static secrets.",
+      ],
+    },
+    {
+      cells: [
+        "TLS model",
+        "`spec.tls.mode: External` with externally provisioned Secrets",
+        "Certificate lifecycle stays separate from the operator, which is the point of the lane.",
+      ],
+    },
+    {
+      cells: [
+        "Edge model",
+        "User-managed Traefik TCP passthrough",
+        "The validated path keeps passthrough isolated from any shared terminating listener and treats edge routing as a deliberate external dependency.",
+      ],
+    },
+    {
+      cells: [
+        "Validation scope",
+        "Local validation environment plus hardened E2E lifecycle coverage",
+        "The baseline covers bootstrap, unseal, admin JWT login, and passthrough access in a repeatable local rehearsal path.",
+      ],
+    },
+  ]}
+/>
+
+<DiagramFrame
+  title="Baseline topology"
+  caption="The lane keeps the unseal root external, keeps TLS external, and keeps the passthrough path user-managed. That separation is the reason this local baseline is useful."
+  code={`flowchart LR
+    Client["OpenBao client"] -->|"HTTPS (SNI)"| Edge["Traefik IngressRouteTCP"]
+    Edge -->|"TLS passthrough"| Public["OpenBao public Service"]
+    Public --> Bao["OpenBao Pods"]
+
+    Operator["OpenBao Operator"] -->|"JWT bootstrap"| Bao
+    Admin["Admin ServiceAccount token"] -->|"JWT login"| Bao
+    Bao -->|"Transit encrypt/decrypt"| Transit["Shared Transit provider"]
+    CertMgr["cert-manager"] -->|"TLS Secret issuance"| TLS["External TLS Secrets"]
+    TLS --> Bao
+
+    classDef read fill:transparent,stroke:#79c0ab,stroke-width:2px,color:#e6f4ef;
+    classDef process fill:transparent,stroke:#fdd0a4,stroke-width:2px,color:#e6f4ef;
+    classDef write fill:transparent,stroke:#87d6be,stroke-width:2px,color:#e6f4ef;
+
+    class Client,Admin read;
+    class Edge,Operator,CertMgr process;
+    class Public,Bao,Transit,TLS write;`}
+/>
+
+## Why this lane exists
+
+<DecisionTable
+  kind="reference"
+  title="Key design choices"
+  columns={["Choice", "What it protects", "Why it stays in the lane"]}
+  rows={[
+    {
+      cells: [
+        "Transit stays external",
+        "The seal root is not stored or derived from the cluster itself.",
+        "A hardened rehearsal lane should prove the dependency on an external seal provider instead of hiding it.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "TLS stays external",
+        "Certificate issuance and trust material do not collapse into operator-managed defaults.",
+        "This keeps the certificate contract aligned with the kind of deployment that already has an external PKI owner.",
+      ],
+    },
+    {
+      cells: [
+        "Passthrough is user-managed",
+        "The OpenBao server remains the TLS endpoint.",
+        "The lane intentionally avoids turning shared ingress behavior into part of the hardened contract.",
+      ],
+    },
+  ]}
+/>
+
+<Checklist
+  tone="warning"
+  title="Baseline requirements"
+  items={[
+    "keep `spec.profile: Hardened`",
+    "keep the shared Transit provider reachable and trusted",
+    "keep `tls.mode: External` and provide the expected CA and server Secrets",
+    "keep the passthrough route managed outside `spec.gateway`",
+    "disable AppArmor only when the local runtime requires it and treat that as a local-environment concession, not a preferred default",
+  ]}
+/>
+
+<Callout type="success" title="Validated coverage">
+
+The validated local lane exercised hardened bootstrap with self-init, Transit auto-unseal through a shared external OpenBao service, JWT login for a human admin `ServiceAccount`, and passthrough external access with externally managed TLS Secrets.
+
+</Callout>
+
+<Callout type="warning" title="Out of scope">
+
+This lane does not define a cloud reference or a GitOps reference. It is a local rehearsal environment for hardened bootstrap, external TLS, and passthrough access with explicit external dependencies.
+
+</Callout>
+
+<NextActions
+  title="Next steps"
+  items={[
+    {
+      label: "Deployment recipe",
+      description: "Follow the exact steps that reproduce this validated lane in the local environment.",
+      docId: "user-guide/validated-deployments/recipes/local/hardened-transit-external-tls",
+    },
+    {
+      label: "External access",
+      description: "Compare the lane's user-managed passthrough choice with the generic service-boundary guidance in the main docs.",
+      docId: "user-guide/openbaocluster/configuration/external-access",
+    },
+    {
+      label: "TLS and identity",
+      description: "Review the security model behind external certificates and server-side TLS ownership.",
+      docId: "security/workload/tls",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/index.mdx b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/index.mdx
new file mode 100644
index 000000000..00dc84adc
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/index.mdx
@@ -0,0 +1,79 @@
+---
+title: Validated Deployments
+slug: /validated-deployments
+hide_title: true
+pageType: landing
+description: Validated OpenBao Operator baselines grouped by lane, with paired reference architecture and deployment recipe pages.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments"
+  title="Validated deployment baselines"
+  lede="Reference architectures and matching deployment recipes grouped by validated deployment baseline."
+  actions={[
+    {label: "Open cloud baselines", docId: "user-guide/validated-deployments/architectures/cloud/index", variant: "primary"},
+    {label: "Open local baselines", docId: "user-guide/validated-deployments/architectures/local/index", variant: "secondary"},
+  ]}
+>
+  <Checklist
+    title="Use validated deployments to"
+    items={[
+      "start from a topology that the project exercised end to end",
+      "compare cloud and local baselines with architecture and recipe pages kept together",
+      "pick a lane with clear invariants, assumptions, and validation scope",
+      "adapt a known baseline as the starting point for environment-specific changes",
+    ]}
+  />
+</PageHero>
+
+<RouteList
+  title="Choose a validated baseline"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Cloud baselines",
+      description: "Amazon EKS development and hardened baselines with paired architecture and recipe pages.",
+      docId: "user-guide/validated-deployments/architectures/cloud/index",
+    },
+    {
+      eyebrow: "02",
+      title: "Local baselines",
+      description: "k3d baselines for workstation validation, hardened rehearsal, and cross-cluster DR.",
+      docId: "user-guide/validated-deployments/architectures/local/index",
+    },
+    {
+      eyebrow: "03",
+      title: "Cross-cluster DR lane",
+      description: "Validated DR architecture for restore rehearsal, shared Transit, and snapshot cutover verification.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs",
+    },
+  ]}
+/>
+
+<Callout type="note" title="Scope of this section">
+
+Main operator guides remain the source of truth for install, backup, restore, upgrade, and recovery behavior. These pages document the validated environment shapes used for specific baselines.
+
+</Callout>
+
+<NextActions
+  title="After you choose a baseline"
+  items={[
+    {
+      label: "Open configure",
+      description: "Adapt storage, edge, and observability choices for your environment.",
+      docId: "user-guide/openbaocluster/configuration/index",
+    },
+    {
+      label: "Open Operate",
+      description: "Use the main operating guides for backups, upgrades, troubleshooting, and recovery after the baseline is running.",
+      docId: "user-guide/openbaocluster/operations/index",
+    },
+    {
+      label: "Open Get Started",
+      description: "Return to the general operator path for install and onboarding guidance.",
+      docId: "user-guide/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3.md
new file mode 100644
index 000000000..72b7d40fa
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3.md
@@ -0,0 +1,314 @@
+---
+title: EKS Development / Shared Edge Recipe
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Reproduce the validated development baseline on Amazon EKS with AWS KMS auto-unseal, a shared terminating Gateway, JWT bootstrap, and S3 backups.
+---
+
+<PageHeader
+  title="Reproduce the validated EKS development lane"
+  lede="This recipe applies the EKS development baseline with KMS auto-unseal, shared-edge exposure, JWT bootstrap, and S3 backups. Use it when you need the exact validated cloud bring-up path for this topology."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an onboarded tenant namespace and admin ServiceAccount",
+      "a Development-profile cluster that unseals with AWS KMS through workload identity",
+      "JWT admin login and shared-edge access working on the public hostname you chose",
+      "manual and scheduled S3 backups using a backup identity that stays separate from the main workload identity",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This recipe matches the EKS development lane validated in the project cloud environment. The tested path covered KMS unseal, JWT bootstrap, Gateway exposure, and successful S3 backups.
+
+</Callout>
+
+<Callout type="note" title="Use the main docs for generic operator behavior">
+
+Use <SiteLink docId="user-guide/openbaotenant/onboarding">tenant onboarding</SiteLink>, <SiteLink docId="user-guide/openbaocluster/configuration/gateway-api">Gateway API support</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/operations/backups">backup operations</SiteLink> for the product-wide guidance. This recipe documents the validated lane.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "EKS has IRSA or an equivalent workload identity path enabled",
+        "Both KMS unseal and S3 backup identities depend on cloud workload identity behavior.",
+        "The main workload or backup jobs will fail authentication even if the manifests themselves look correct.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "The shared Gateway terminates HTTPS and can re-encrypt to OpenBao",
+        "The lane uses a terminating edge instead of passthrough.",
+        "If you switch to passthrough or plain HTTP forwarding, you are no longer reproducing the validated baseline.",
+      ],
+    },
+    {
+      cells: [
+        "Separate AWS identities exist for unseal and backup",
+        "The validated lane treats those permissions as distinct surfaces.",
+        "You will miss the exact failure modes and permission boundaries the lane is supposed to prove.",
+      ],
+    },
+    {
+      cells: [
+        "This remains a Development profile",
+        "The lane is intentionally optimized for bring-up and validation speed.",
+        "Treating it as a production profile will create the wrong expectations around `ProductionReady` and endpoint posture.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Inputs to replace before apply"
+  columns={["Placeholder", "Example", "Purpose"]}
+  rows={[
+    {cells: ["`<namespace>`", "`openbaocluster-dev`", "Tenant namespace for the cluster."]},
+    {cells: ["`<cluster-name>`", "`openbaocluster-dev`", "`OpenBaoCluster` name."]},
+    {cells: ["`<openbao-version>`", "`2.5.1`", "OpenBao version."]},
+    {cells: ["`<aws-region>`", "`eu-central-1`", "AWS region for KMS and S3."]},
+    {cells: ["`<kms-key-arn>`", "`arn:aws:kms:...`", "KMS key ARN for auto-unseal."]},
+    {cells: ["`<main-role-arn>`", "`arn:aws:iam::...:role/openbao-unseal`", "IRSA role for the main OpenBao Pods."]},
+    {cells: ["`<backup-role-arn>`", "`arn:aws:iam::...:role/openbao-backup`", "IRSA role for backup Jobs."]},
+    {cells: ["`<backup-bucket>`", "`openbao-backups`", "S3 bucket for snapshots."]},
+    {cells: ["`<gateway-name>`", "`shared-gateway`", "Existing terminating Gateway."]},
+    {cells: ["`<gateway-namespace>`", "`default`", "Namespace of the Gateway."]},
+    {cells: ["`<external-host>`", "`bao-dev.example.com`", "External hostname for the development cluster."]},
+    {cells: ["`<operator-namespace>`", "`openbao-operator-system`", "Namespace that hosts the central `OpenBaoTenant` resource."]},
+  ]}
+/>
+
+## Step 1: Onboard the tenant namespace
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the namespace, onboarding request, and admin ServiceAccount"
+  code={`apiVersion: v1
+kind: Namespace
+metadata:
+  name: <namespace>
+  labels:
+    openbao.org/tenant: "true"
+---
+apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: <cluster-name>-tenant
+  namespace: <operator-namespace>
+spec:
+  targetNamespace: <namespace>
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: openbao-admin
+  namespace: <namespace>`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Wait for tenant provisioning"
+  code={`kubectl -n <operator-namespace> describe openbaotenant <cluster-name>-tenant`}
+>
+  The steady-state expectation is `Provisioned=True`.
+</CommandBlock>
+
+## Step 2: Apply the validated EKS development cluster
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the Development-profile EKS manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+spec:
+  profile: Development
+  replicas: 3
+  version: "<openbao-version>"
+
+  workloadHardening:
+    appArmorEnabled: false
+
+  configuration:
+    logLevel: "info"
+    ui: true
+    logging:
+      format: "json"
+    defaultLeaseTTL: "720h"
+    maxLeaseTTL: "8760h"
+    cacheSize: 134217728
+    disableCache: false
+    raft:
+      performanceMultiplier: 2
+
+  tls:
+    enabled: true
+    mode: External
+
+  storage:
+    size: "10Gi"
+    storageClassName: gp3
+  deletionPolicy: DeleteAll
+
+  imageVerification:
+    enabled: false
+    failurePolicy: Block
+  operatorImageVerification:
+    enabled: false
+    failurePolicy: Block
+
+  serviceAccount:
+    annotations:
+      eks.amazonaws.com/role-arn: "<main-role-arn>"
+
+  unseal:
+    type: awskms
+    awskms:
+      region: "<aws-region>"
+      kmsKeyID: "<kms-key-arn>"
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-jwt-auth
+        operation: update
+        path: sys/auth/jwt
+        authMethod:
+          type: jwt
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      - name: create-admin-jwt-role
+        operation: update
+        path: auth/jwt/role/admin
+        data:
+          role_type: jwt
+          user_claim: sub
+          bound_audiences:
+            - openbao-internal
+          bound_subject: system:serviceaccount:<namespace>:openbao-admin
+          token_policies:
+            - admin
+          policies:
+            - admin
+          ttl: 1h
+
+  gateway:
+    enabled: true
+    listenerName: websecure
+    gatewayRef:
+      name: <gateway-name>
+      namespace: <gateway-namespace>
+    hostname: "<external-host>"
+    backendTLS:
+      enabled: true
+    tlsPassthrough: false
+    path: /
+
+  backup:
+    schedule: "*/30 * * * *"
+    target:
+      provider: s3
+      endpoint: "https://s3.<aws-region>.amazonaws.com"
+      bucket: "<backup-bucket>"
+      pathPrefix: "clusters/<cluster-name>"
+      region: "<aws-region>"
+      roleArn: "<backup-role-arn>"
+      usePathStyle: false
+    retention:
+      maxCount: 7
+      maxAge: "168h"
+
+  upgrade:
+    preUpgradeSnapshot: true
+    strategy: RollingUpdate`}
+/>
+
+<Callout type="note" title="AppArmor on EKS">
+
+The validated EKS lane set `spec.workloadHardening.appArmorEnabled: false`. Remove that override only if your node OS and runtime support AppArmor cleanly.
+
+</Callout>
+
+## Verify the lane
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster conditions"
+  code={`kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The steady-state expectation is `Available=True`, `CloudUnsealIdentityReady=True`, `BackupConfigurationReady=True`, `GatewayIntegrationReady=True` or `Unknown`, `OpenBaoInitialized=True`, and `OpenBaoSealed=False`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the external endpoint and JWT admin login"
+  code={`curl -kI https://<external-host>/v1/sys/health
+
+JWT="$(kubectl -n <namespace> create token openbao-admin --audience openbao-internal --duration=1h)"
+
+curl -sS -k \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"role\\":\\"admin\\",\\"jwt\\":\\"\${JWT}\\"}" \\
+  "https://<external-host>/v1/auth/jwt/login"`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Trigger and inspect a manual backup"
+  code={`kubectl -n <namespace> annotate openbaocluster <cluster-name> \\
+  openbao.org/trigger-backup="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite
+
+kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{.status.backup.lastBackupName}{"\\n"}{.status.backup.lastBackupTime}{"\\n"}{.status.backup.lastFailureReason}{"\\n"}{.status.backup.lastFailureMessage}{"\\n"}'`}
+/>
+
+<NextActions
+  title="Keep moving"
+  items={[
+    {
+      label: "Reference architecture",
+      description: "Review the lane summary, topology, and invariants behind the EKS development path.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3",
+    },
+    {
+      label: "Backup operations",
+      description: "Use the operator-wide backup guide for retention, credentials, and restore planning beyond this validated lane.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "EKS Hardened",
+      description: "Move to the hardened cloud baseline when you are ready for ACME, passthrough, and a production-style edge.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme.md
new file mode 100644
index 000000000..c446900f0
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme.md
@@ -0,0 +1,353 @@
+---
+title: EKS Hardened / Public ACME Recipe
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Reproduce the validated hardened baseline on Amazon EKS with AWS KMS auto-unseal, a dedicated public passthrough Gateway, OpenBao-managed ACME, and S3 backups.
+---
+
+<PageHeader
+  title="Reproduce the validated hardened EKS baseline"
+  lede="This recipe applies the hardened cloud baseline with KMS auto-unseal, a dedicated public passthrough Gateway, OpenBao-managed ACME, JWT bootstrap, and S3 backups."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an onboarded tenant namespace and admin ServiceAccount",
+      "a Hardened-profile cluster that unseals with AWS KMS and serves the public hostname through passthrough",
+      "public ACME issuance completed by OpenBao itself with a shared ACME cache",
+      "manual and scheduled S3 backups using a backup identity distinct from the main workload identity",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This recipe matches the hardened Amazon EKS lane validated in the project cloud environment. The tested path covered KMS auto-unseal, public ACME issuance, dedicated passthrough ingress, JWT bootstrap, and successful S3 backups.
+
+</Callout>
+
+<Callout type="warning" title="Public reachability is a hard requirement">
+
+A public ACME CA such as Let's Encrypt must reach the hardened hostname on port `443`. Do not source-restrict the hardened passthrough hostname to a single client IP and still expect this lane to work.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "EKS has IRSA or an equivalent workload identity path enabled",
+        "Both KMS auto-unseal and S3 backups depend on cloud workload identity behavior.",
+        "The cluster can fail KMS or backup auth long before any OpenBao-specific logic becomes relevant.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "A dedicated public passthrough Gateway exists for the hardened hostname",
+        "The public OpenBao hostname must stay separate from the terminating admin edge.",
+        "Using a shared terminating edge or the wrong listener changes the lane's TLS contract completely.",
+      ],
+    },
+    {
+      cells: [
+        "The Gateway controller supports `TLSRoute` and public passthrough",
+        "OpenBao has to remain the TLS endpoint while ACME validation reaches it on `443`.",
+        "The route can look syntactically correct while the public edge never forwards TLS correctly.",
+      ],
+    },
+    {
+      cells: [
+        "RWX storage is available for the shared ACME cache",
+        "HA ACME depends on multi-replica access to shared certificate state.",
+        "ACME readiness will fail or remain unstable if the cache path is not truly shared.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Inputs to replace before apply"
+  columns={["Placeholder", "Example", "Purpose"]}
+  rows={[
+    {cells: ["`<namespace>`", "`openbaocluster-hardened`", "Tenant namespace for the cluster."]},
+    {cells: ["`<cluster-name>`", "`openbaocluster-hardened`", "`OpenBaoCluster` name."]},
+    {cells: ["`<openbao-version>`", "`2.5.1`", "OpenBao version."]},
+    {cells: ["`<aws-region>`", "`eu-central-1`", "AWS region for KMS and S3."]},
+    {cells: ["`<kms-key-arn>`", "`arn:aws:kms:...`", "KMS key ARN for auto-unseal."]},
+    {cells: ["`<main-role-arn>`", "`arn:aws:iam::...:role/openbao-unseal`", "IRSA role for the main OpenBao Pods."]},
+    {cells: ["`<backup-role-arn>`", "`arn:aws:iam::...:role/openbao-backup`", "IRSA role for backup Jobs."]},
+    {cells: ["`<backup-bucket>`", "`openbao-backups`", "S3 bucket for snapshots."]},
+    {cells: ["`<external-host>`", "`bao.example.com`", "Public hostname for the hardened cluster."]},
+    {cells: ["`<gateway-name>`", "`openbao-hardened-gateway`", "Dedicated passthrough Gateway."]},
+    {cells: ["`<gateway-namespace>`", "`default`", "Namespace of the Gateway."]},
+    {cells: ["`<gateway-class-name>`", "`traefik-passthrough`", "GatewayClass used by the dedicated passthrough edge."]},
+    {cells: ["`<acme-cache-storage-class>`", "`efs-acme`", "RWX StorageClass for the shared ACME cache."]},
+    {cells: ["`<operator-namespace>`", "`openbao-operator-system`", "Namespace that hosts the central `OpenBaoTenant` resource."]},
+  ]}
+/>
+
+## Step 1: Create the dedicated public passthrough Gateway
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Expose the hardened hostname through a dedicated TLS passthrough Gateway"
+  code={`apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: <gateway-name>
+  namespace: <gateway-namespace>
+spec:
+  gatewayClassName: <gateway-class-name>
+  listeners:
+    - name: websecure-passthrough
+      hostname: <external-host>
+      port: 443
+      protocol: TLS
+      tls:
+        mode: Passthrough
+      allowedRoutes:
+        namespaces:
+          from: All`}
+/>
+
+<Callout type="note" title="Validated edge shape">
+
+The validated EKS design used a dedicated Traefik release for the hardened hostname with a public `LoadBalancer`, only port `443` exposed, `externalTrafficPolicy: Local`, and `TLSRoute` support enabled.
+
+</Callout>
+
+## Step 2: Onboard the tenant namespace
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the namespace, onboarding request, and admin ServiceAccount"
+  code={`apiVersion: v1
+kind: Namespace
+metadata:
+  name: <namespace>
+  labels:
+    openbao.org/tenant: "true"
+---
+apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: <cluster-name>-tenant
+  namespace: <operator-namespace>
+spec:
+  targetNamespace: <namespace>
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: openbao-admin
+  namespace: <namespace>`}
+/>
+
+## Step 3: Apply the validated hardened EKS cluster
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the Hardened-profile EKS manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+spec:
+  profile: Hardened
+  replicas: 3
+  version: "<openbao-version>"
+
+  configuration:
+    logLevel: "info"
+    ui: true
+    logging:
+      format: "json"
+    defaultLeaseTTL: "720h"
+    maxLeaseTTL: "8760h"
+    cacheSize: 134217728
+    disableCache: false
+    raft:
+      performanceMultiplier: 2
+
+  imageVerification:
+    enabled: true
+    failurePolicy: Block
+  operatorImageVerification:
+    enabled: true
+    failurePolicy: Block
+
+  tls:
+    enabled: true
+    mode: ACME
+    acme:
+      directoryURL: "https://acme-v02.api.letsencrypt.org/directory"
+      domains:
+        - "<external-host>"
+      email: "platform@example.com"
+      sharedCache:
+        mode: ManagedPVC
+        size: "1Gi"
+        storageClassName: <acme-cache-storage-class>
+
+  storage:
+    size: "10Gi"
+    storageClassName: gp3
+  deletionPolicy: DeleteAll
+
+  serviceAccount:
+    annotations:
+      eks.amazonaws.com/role-arn: "<main-role-arn>"
+
+  unseal:
+    type: awskms
+    awskms:
+      region: "<aws-region>"
+      kmsKeyID: "<kms-key-arn>"
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-jwt-auth
+        operation: update
+        path: sys/auth/jwt
+        authMethod:
+          type: jwt
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      - name: create-admin-jwt-role
+        operation: update
+        path: auth/jwt/role/admin
+        data:
+          role_type: jwt
+          user_claim: sub
+          bound_audiences:
+            - openbao-internal
+          bound_subject: system:serviceaccount:<namespace>:openbao-admin
+          token_policies:
+            - admin
+          policies:
+            - admin
+          ttl: 1h
+
+  gateway:
+    enabled: true
+    listenerName: websecure-passthrough
+    gatewayRef:
+      name: <gateway-name>
+      namespace: <gateway-namespace>
+    hostname: "<external-host>"
+    tlsPassthrough: true
+
+  backup:
+    schedule: "0 */6 * * *"
+    target:
+      provider: s3
+      endpoint: "https://s3.<aws-region>.amazonaws.com"
+      bucket: "<backup-bucket>"
+      pathPrefix: "clusters/<cluster-name>"
+      region: "<aws-region>"
+      roleArn: "<backup-role-arn>"
+      usePathStyle: false
+    retention:
+      maxCount: 7
+      maxAge: "168h"
+
+  upgrade:
+    preUpgradeSnapshot: true
+    strategy: RollingUpdate
+
+  network:
+    egressRules:
+      - to:
+          - ipBlock:
+              cidr: 0.0.0.0/0
+        ports:
+          - protocol: TCP
+            port: 443`}
+/>
+
+<Callout type="tip" title="Helper image defaults">
+
+For released operator builds, prefer the default operator-managed helper images or explicitly pin official signed helper images that match your operator release.
+
+</Callout>
+
+## Verify the lane
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster conditions"
+  code={`kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The steady-state expectation is `Available=True`, `ACMEIntegrationReady=True`, `ACMECacheReady=True`, `CloudUnsealIdentityReady=True`, `BackupConfigurationReady=True`, `ProductionReady=True`, `OpenBaoInitialized=True`, and `OpenBaoSealed=False`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify Gateway programming and the public certificate"
+  code={`kubectl -n <gateway-namespace> get gateway <gateway-name> -o yaml
+curl -I https://<external-host>`}
+>
+  The Gateway should report `Accepted=True` and `Programmed=True`. The public endpoint should present a valid certificate and an OpenBao response code such as `307`, `429`, or another application-level reply.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify JWT admin login and trigger a manual backup"
+  code={`JWT="$(kubectl -n <namespace> create token openbao-admin --audience openbao-internal --duration=1h)"
+
+curl -sS \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"role\\":\\"admin\\",\\"jwt\\":\\"\${JWT}\\"}" \\
+  "https://<external-host>/v1/auth/jwt/login"
+
+kubectl -n <namespace> annotate openbaocluster <cluster-name> \\
+  openbao.org/trigger-backup="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite
+
+kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{.status.backup.lastBackupName}{"\\n"}{.status.backup.lastBackupTime}{"\\n"}{.status.backup.lastFailureReason}{"\\n"}{.status.backup.lastFailureMessage}{"\\n"}'`}
+/>
+
+<NextActions
+  title="Keep moving"
+  items={[
+    {
+      label: "Reference architecture",
+      description: "Review the hardened lane summary, topology, and invariants behind this cloud baseline.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+    },
+    {
+      label: "Troubleshoot the cluster",
+      description: "Use the generic incident routing page if ACME, Gateway, or KMS readiness fails to settle.",
+      docId: "user-guide/openbaocluster/operations/troubleshooting",
+    },
+    {
+      label: "Backup operations",
+      description: "Return to the operator-wide backup guide for retention and restore planning beyond this validated lane.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/index.md
new file mode 100644
index 000000000..51bd083db
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/cloud/index.md
@@ -0,0 +1,35 @@
+---
+title: Cloud Recipe Catalog
+hide_title: true
+pageType: landing
+description: Cloud deployment recipes for the validated Amazon EKS lanes.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Cloud Recipe Catalog"
+  title="Validated cloud recipes"
+  lede="Deployment recipes for the validated Amazon EKS baselines are listed here. Keep the matching reference architecture nearby during deployment."
+  actions={[
+    {label: "Open EKS Development recipe", docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3", variant: "primary"},
+    {label: "Open EKS Hardened recipe", docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme", variant: "secondary"},
+  ]}
+/>
+
+<RouteList
+  title="Cloud recipes"
+  items={[
+    {
+      eyebrow: "01",
+      title: "EKS Development recipe",
+      description: "Step through the development-profile EKS lane with AWS KMS, Gateway exposure, and S3 backups.",
+      docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3",
+    },
+    {
+      eyebrow: "02",
+      title: "EKS Hardened recipe",
+      description: "Deploy the hardened EKS lane with passthrough edge, AWS KMS, ACME, and the hardened production posture.",
+      docId: "user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/index.md
new file mode 100644
index 000000000..464430246
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/index.md
@@ -0,0 +1,35 @@
+---
+title: Deployment Recipe Catalog
+hide_title: true
+pageType: landing
+description: Catalog of validated deployment recipes, grouped by cloud and local environment.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Recipe Catalog"
+  title="Validated recipe catalog"
+  lede="Deployment recipes are grouped by validated baseline. Keep the matching reference architecture nearby while you deploy."
+  actions={[
+    {label: "Open cloud recipe catalog", docId: "user-guide/validated-deployments/recipes/cloud/index", variant: "primary"},
+    {label: "Open local recipe catalog", docId: "user-guide/validated-deployments/recipes/local/index", variant: "secondary"},
+  ]}
+/>
+
+<RouteList
+  title="Recipe catalogs"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Cloud recipes",
+      description: "Deployment procedures for the validated EKS development and hardened lanes.",
+      docId: "user-guide/validated-deployments/recipes/cloud/index",
+    },
+    {
+      eyebrow: "02",
+      title: "Local recipes",
+      description: "Deployment procedures for the validated k3d development, hardened, and cross-cluster DR baselines.",
+      docId: "user-guide/validated-deployments/recipes/local/index",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/development-self-init-userpass.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/development-self-init-userpass.md
new file mode 100644
index 000000000..090ce236b
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/development-self-init-userpass.md
@@ -0,0 +1,358 @@
+---
+title: k3d Development / Shared Edge Recipe
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Reproduce the validated local development lane with self-init, operator-managed TLS, a shared terminating edge, demo login, JWT admin access, and RustFS backups.
+---
+
+<PageHeader
+  title="Reproduce the validated local development baseline"
+  lede="This recipe stands up the local development baseline with tenant onboarding, operator-managed TLS, a shared terminating edge, JWT bootstrap, an optional demo login, and an S3-compatible backup path backed by RustFS."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an onboarded tenant namespace and admin ServiceAccount",
+      "a Development-profile cluster that self-initializes and exposes the UI through the shared edge",
+      "JWT admin login working for a real ServiceAccount token",
+      "a RustFS-backed backup configuration you can verify before the first upgrade rehearsal",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This recipe follows the development lifecycle, backup, and blue/green patterns exercised in the local validation environment and the in-repo E2E suites. The optional `userpass` login remains local-only convenience layered on top of the validated cluster path.
+
+</Callout>
+
+<Callout type="note" title="Use the main docs for the product-wide source of truth">
+
+Use <SiteLink docId="user-guide/openbaotenant/onboarding">tenant onboarding</SiteLink>, <SiteLink docId="user-guide/openbaocluster/configuration/external-access">external access</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/operations/backups">backup operations</SiteLink> when you need the generic operator behavior. This recipe only captures the exact validated local lane.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "Multi-tenant operator install with admission enabled",
+        "The validated path starts from the default tenant-onboarding model.",
+        "Namespace provisioning and generated RBAC will drift from the lane you are trying to reproduce.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "A shared terminating Gateway already exists",
+        "The lane intentionally reuses one local edge for OpenBao and the rest of the toolchain.",
+        "You will not validate the same routing contract if you fall back to port-forwarding or user-managed passthrough.",
+      ],
+    },
+    {
+      cells: [
+        "RustFS is reachable as an S3-compatible endpoint",
+        "Backups are part of the lane, not an optional afterthought.",
+        "The cluster may look healthy while the part of the lane that matters for restore rehearsal never actually works.",
+      ],
+    },
+    {
+      cells: [
+        "Demo login stays local-only",
+        "The `userpass` bootstrap is included only to make UI validation and demos faster.",
+        "Reusing it outside a disposable environment turns a convenience into a security mistake.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Inputs to replace before apply"
+  columns={["Placeholder", "Example", "Purpose"]}
+  rows={[
+    {cells: ["`<namespace>`", "`openbaocluster-demo`", "Tenant namespace for the cluster."]},
+    {cells: ["`<cluster-name>`", "`openbaocluster-demo`", "`OpenBaoCluster` name."]},
+    {cells: ["`<openbao-version>`", "`2.5.1`", "OpenBao version."]},
+    {cells: ["`<gateway-name>`", "`shared-gateway`", "Existing terminating Gateway used by the local toolchain."]},
+    {cells: ["`<gateway-namespace>`", "`default`", "Namespace of the Gateway."]},
+    {cells: ["`<external-host>`", "`bao-demo.example.com`", "External hostname for the shared-edge route."]},
+    {cells: ["`<operator-namespace>`", "`openbao-operator-system`", "Namespace that hosts the central `OpenBaoTenant` resource."]},
+  ]}
+/>
+
+## Step 1: Onboard the tenant namespace
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the namespace, onboarding request, and admin ServiceAccount"
+  code={`apiVersion: v1
+kind: Namespace
+metadata:
+  name: <namespace>
+  labels:
+    openbao.org/tenant: "true"
+---
+apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: <cluster-name>-tenant
+  namespace: <operator-namespace>
+spec:
+  targetNamespace: <namespace>
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: openbao-admin
+  namespace: <namespace>`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Wait for tenant provisioning"
+  code={`kubectl -n <operator-namespace> describe openbaotenant <cluster-name>-tenant`}
+>
+  The steady-state expectation is `Provisioned=True`. Do not move to the cluster manifest until the namespace is actually prepared for the operator.
+</CommandBlock>
+
+## Step 2: Create the backup credentials Secret
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the RustFS credentials Secret"
+  code={`kubectl -n <namespace> create secret generic rustfs-secret \\
+  --from-literal=accessKeyId='rustfsadmin' \\
+  --from-literal=secretAccessKey='rustfsadmin'`}
+>
+  If your local RustFS instance uses different credentials, replace both values here and in the object-storage service itself.
+</CommandBlock>
+
+## Step 3: Apply the validated development cluster manifest
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the Development-profile cluster"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+spec:
+  profile: Development
+  replicas: 3
+  version: "<openbao-version>"
+
+  tls:
+    enabled: true
+    mode: OperatorManaged
+    rotationPeriod: "720h"
+
+  configuration:
+    logLevel: "info"
+    ui: true
+    logging:
+      format: "json"
+    defaultLeaseTTL: "720h"
+    maxLeaseTTL: "8760h"
+    cacheSize: 134217728
+    disableCache: false
+    raft:
+      performanceMultiplier: 2
+
+  storage:
+    size: "10Gi"
+  deletionPolicy: DeleteAll
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-userpass-auth
+        operation: update
+        path: sys/auth/userpass
+        authMethod:
+          type: userpass
+      - name: enable-jwt-auth
+        operation: update
+        path: sys/auth/jwt
+        authMethod:
+          type: jwt
+      - name: enable-demo-kv
+        operation: update
+        path: sys/mounts/secret
+        secretEngine:
+          type: kv
+          description: "Demo KV v2 engine"
+          options:
+            version: "2"
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      - name: create-demo-ui-user
+        operation: update
+        path: auth/userpass/users/demo-admin
+        data:
+          password: "demo-password"
+          token_policies:
+            - admin
+      - name: create-admin-jwt-role
+        operation: update
+        path: auth/jwt/role/admin
+        data:
+          role_type: jwt
+          user_claim: sub
+          bound_audiences:
+            - openbao-internal
+          bound_subject: system:serviceaccount:<namespace>:openbao-admin
+          token_policies:
+            - admin
+          policies:
+            - admin
+          ttl: 1h
+
+  gateway:
+    enabled: true
+    listenerName: websecure
+    gatewayRef:
+      name: <gateway-name>
+      namespace: <gateway-namespace>
+    hostname: "<external-host>"
+    backendTLS:
+      enabled: true
+    tlsPassthrough: false
+    path: /
+
+  backup:
+    schedule: "*/30 * * * *"
+    target:
+      provider: s3
+      endpoint: "http://rustfs-svc.rustfs.svc.cluster.local:9000"
+      bucket: "openbao-backups"
+      pathPrefix: "clusters/<cluster-name>"
+      usePathStyle: true
+      credentialsSecretRef:
+        name: rustfs-secret
+    retention:
+      maxCount: 7
+      maxAge: "168h"
+
+  upgrade:
+    preUpgradeSnapshot: true
+    strategy: BlueGreen`}
+/>
+
+<Callout type="warning" title="Demo-only credentials">
+
+The `demo-admin` user exists only to make local validation easy. Keep it out of any shared or long-lived environment.
+
+</Callout>
+
+<Callout type="note" title="AppArmor on local clusters">
+
+If kubelet rejects the Pods because AppArmor is unavailable, add:
+
+```yaml
+spec:
+  workloadHardening:
+    appArmorEnabled: false
+```
+
+</Callout>
+
+## Verify the lane
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster conditions"
+  code={`kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The steady-state expectation is `Available=True`, `TLSReady=True`, `UserAccessBootstrap=True`, `BackupConfigurationReady=True`, `GatewayIntegrationReady=True`, `OpenBaoInitialized=True`, and `OpenBaoSealed=False`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Confirm the cluster did not persist a root token Secret"
+  code={`kubectl -n <namespace> get secret <cluster-name>-root-token`}
+>
+  This should return `NotFound`. A self-init lane should not leave the root token stored as a Kubernetes Secret.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify the demo UI login through the local service"
+  code={`kubectl -n <namespace> port-forward svc/<cluster-name> 8200:8200
+export VAULT_ADDR="https://127.0.0.1:8200"
+
+curl -sS -k \\
+  -H 'Content-Type: application/json' \\
+  -d '{"password":"demo-password"}' \\
+  \${VAULT_ADDR%/}/v1/auth/userpass/login/demo-admin`}
+>
+  Local browsers and CLIs may warn about the operator-managed CA. That is expected in this lane.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify JWT admin login"
+  code={`JWT="$(kubectl -n <namespace> create token openbao-admin --audience openbao-internal --duration=1h)"
+
+curl -sS -k \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"role\\":\\"admin\\",\\"jwt\\":\\"\${JWT}\\"}" \\
+  \${VAULT_ADDR%/}/v1/auth/jwt/login`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Trigger and inspect a manual backup"
+  code={`kubectl -n <namespace> annotate openbaocluster <cluster-name> \\
+  openbao.org/trigger-backup="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite
+
+kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{.status.backup.lastBackupName}{"\\n"}{.status.backup.lastBackupTime}{"\\n"}{.status.backup.lastFailureReason}{"\\n"}{.status.backup.lastFailureMessage}{"\\n"}'`}
+>
+  A successful lane should produce a backup object key and no failure reason or failure message.
+</CommandBlock>
+
+<NextActions
+  title="Keep moving"
+  items={[
+    {
+      label: "Reference architecture",
+      description: "Review the lane summary, topology, and invariants behind the recipe you just applied.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs",
+    },
+    {
+      label: "Backup operations",
+      description: "Expand the RustFS-specific recipe choices into the generic backup model used by the operator.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "k3d Hardened / External TLS",
+      description: "Move to the hardened local rehearsal lane when you need external certificates and an external unseal root.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls.md
new file mode 100644
index 000000000..40c8ae8ea
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls.md
@@ -0,0 +1,323 @@
+---
+title: k3d Hardened / ACME Recipe
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Reproduce the validated local hardened ACME lane with Transit auto-unseal, a private ACME issuer, self-init, and user-managed TLS passthrough.
+---
+
+<PageHeader
+  title="Reproduce the validated hardened ACME baseline"
+  lede="This recipe stands up the local hardened ACME baseline with tenant onboarding, a shared trust-services dependency for Transit and ACME, an internal ACME CA, and a user-managed passthrough route that preserves `tls-alpn-01` behavior."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an onboarded tenant namespace and admin ServiceAccount",
+      "a trust Secret that carries both the Transit CA bundle and the private ACME issuer trust root",
+      "a hardened cluster that self-initializes, unseals with Transit, and serves ACME traffic through passthrough",
+      "conditions and services that confirm ACME is working before you move to a public cloud lane",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This recipe follows the local ACME lifecycle covered by the in-repo ACME suite and the project validation environment. The tested path covers private ACME trust material, Transit auto-unseal, ACME readiness, and human admin JWT access.
+
+</Callout>
+
+<Callout type="note" title="Use the main docs for generic behavior">
+
+Use <SiteLink docId="user-guide/openbaocluster/configuration/external-access">external access</SiteLink>, <SiteLink docId="user-guide/openbaocluster/configuration/network">network configuration</SiteLink>, and <SiteLink docId="security/workload/tls">TLS and workload identity</SiteLink> for the product-wide explanation. This recipe captures the exact validated local lane.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "Multi-tenant operator install with admission enabled",
+        "The validated path starts from the standard tenant-onboarding flow.",
+        "Namespace provisioning and hardened policy enforcement will drift from the tested lane.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "The external trust-services endpoint exposes both Transit and an ACME directory",
+        "One dependency owns both the seal root and the private certificate issuance path.",
+        "You will not reproduce the lane if Transit and ACME trust material come from unrelated systems.",
+      ],
+    },
+    {
+      cells: [
+        "The external hostname resolves back to the passthrough edge",
+        "`tls-alpn-01` only works when the validator reaches the hostname that OpenBao serves.",
+        "ACME will fail even though the cluster itself is healthy and the route object exists.",
+      ],
+    },
+    {
+      cells: [
+        "The ingress layer supports TLS passthrough on port `443`",
+        "OpenBao must terminate TLS itself in this lane.",
+        "Any edge termination in front of OpenBao breaks the ACME contract immediately.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Inputs to replace before apply"
+  columns={["Placeholder", "Example", "Purpose"]}
+  rows={[
+    {cells: ["`<namespace>`", "`openbaocluster-acme`", "Tenant namespace for the cluster."]},
+    {cells: ["`<cluster-name>`", "`openbaocluster-acme`", "`OpenBaoCluster` name."]},
+    {cells: ["`<openbao-version>`", "`2.5.0`", "OpenBao version."]},
+    {cells: ["`<transit-address>`", "`https://trust-services.openbao-infra.svc:8200`", "Transit provider URL."]},
+    {cells: ["`<acme-directory-url>`", "`https://trust-services.openbao-infra.svc:8200/v1/pki/acme/directory`", "ACME directory URL."]},
+    {cells: ["`<transit-key>`", "`openbao-unseal`", "Transit key name."]},
+    {cells: ["`<external-host>`", "`bao-acme.example.com`", "External hostname used for clients and ACME validation."]},
+    {cells: ["`<operator-namespace>`", "`openbao-operator-system`", "Namespace that hosts the central `OpenBaoTenant` resource."]},
+  ]}
+/>
+
+## Step 1: Onboard the tenant namespace
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the namespace, onboarding request, and admin ServiceAccount"
+  code={`apiVersion: v1
+kind: Namespace
+metadata:
+  name: <namespace>
+  labels:
+    openbao.org/tenant: "true"
+---
+apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: <cluster-name>-tenant
+  namespace: <operator-namespace>
+spec:
+  targetNamespace: <namespace>
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: openbao-admin
+  namespace: <namespace>`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Wait for tenant provisioning"
+  code={`kubectl -n <operator-namespace> describe openbaotenant <cluster-name>-tenant`}
+>
+  The steady-state expectation is `Provisioned=True`.
+</CommandBlock>
+
+## Step 2: Create the Transit and ACME trust Secret
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the Secret used by Transit and the private ACME issuer"
+  code={`kubectl -n <namespace> create secret generic trust-services-token \\
+  --from-literal=token='<transit-token>' \\
+  --from-file=ca.crt=/path/to/trust-services-ca.crt \\
+  --from-file=pki-ca.crt=/path/to/acme-issuer-ca.crt`}
+>
+  The validated path expects `token`, `ca.crt`, and `pki-ca.crt` in the same Secret so Transit and ACME trust material stay aligned.
+</CommandBlock>
+
+## Step 3: Expose the ACME challenge Service with passthrough
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the user-managed passthrough route"
+  code={`apiVersion: traefik.io/v1alpha1
+kind: IngressRouteTCP
+metadata:
+  name: bao-acme
+  namespace: <namespace>
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - match: HostSNI(\`<external-host>\`)
+      services:
+        - name: <cluster-name>-acme
+          port: 443
+  tls:
+    passthrough: true`}
+>
+  `tls.mode: ACME` requires passthrough. If the edge terminates TLS first, OpenBao cannot complete ACME challenges.
+</CommandBlock>
+
+## Step 4: Apply the hardened ACME cluster
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the validated hardened ACME manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+spec:
+  profile: Hardened
+  replicas: 3
+  version: "<openbao-version>"
+
+  storage:
+    size: "10Gi"
+  deletionPolicy: Retain
+
+  tls:
+    enabled: true
+    mode: ACME
+    acme:
+      directoryURL: "<acme-directory-url>"
+      domains:
+        - "<cluster-name>-acme.<namespace>.svc"
+        - "<external-host>"
+      email: "admin@example.invalid"
+
+  configuration:
+    logLevel: "info"
+    ui: true
+    logging:
+      format: "json"
+    acmeCARoot: "/etc/bao/seal-creds/ca.crt"
+
+  unseal:
+    type: transit
+    credentialsSecretRef:
+      name: trust-services-token
+    transit:
+      address: "<transit-address>"
+      mountPath: "transit"
+      keyName: "<transit-key>"
+      tlsCACert: "/etc/bao/seal-creds/ca.crt"
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-jwt-auth
+        operation: update
+        path: sys/auth/jwt
+        authMethod:
+          type: jwt
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      - name: create-admin-jwt-role
+        operation: update
+        path: auth/jwt/role/admin
+        data:
+          role_type: jwt
+          user_claim: sub
+          bound_audiences:
+            - openbao-internal
+          bound_subject: system:serviceaccount:<namespace>:openbao-admin
+          token_policies:
+            - admin
+          policies:
+            - admin
+          ttl: 1h
+
+  upgrade:
+    strategy: RollingUpdate`}
+/>
+
+<Callout type="note" title="Internal `.svc` domain">
+
+The internal `.svc` hostname in `spec.tls.acme.domains` gives the local lane a stable service name for certificate issuance and cluster-internal joins while the external hostname stays present in the SAN set.
+
+</Callout>
+
+<Callout type="note" title="AppArmor on local clusters">
+
+If kubelet rejects the Pods because AppArmor is unavailable, add:
+
+```yaml
+spec:
+  workloadHardening:
+    appArmorEnabled: false
+```
+
+</Callout>
+
+## Verify the lane
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster conditions"
+  code={`kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The steady-state expectation is `Available=True`, `ACMEIntegrationReady=True`, `ACMECacheReady=True`, `UserAccessBootstrap=True`, `ProductionReady=True`, `OpenBaoInitialized=True`, and `OpenBaoSealed=False`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify that the ACME Service exists and no external TLS Secret is required"
+  code={`kubectl -n <namespace> get svc <cluster-name>-acme
+kubectl -n <namespace> get secret <cluster-name>-tls-server`}
+>
+  The service should exist. The Secret lookup should return `NotFound`, because OpenBao manages the leaf certificate itself in this lane.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify JWT admin login"
+  code={`kubectl -n <namespace> port-forward svc/<cluster-name> 8200:8200
+export VAULT_ADDR="https://127.0.0.1:8200"
+JWT="$(kubectl -n <namespace> create token openbao-admin --audience openbao-internal --duration=1h)"
+
+curl -sS -k \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"role\\":\\"admin\\",\\"jwt\\":\\"\${JWT}\\"}" \\
+  \${VAULT_ADDR%/}/v1/auth/jwt/login`}
+/>
+
+<NextActions
+  title="Keep moving"
+  items={[
+    {
+      label: "Reference architecture",
+      description: "Review the lane summary, topology, and invariants behind this local ACME path.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme",
+    },
+    {
+      label: "Troubleshoot the cluster",
+      description: "Use the incident routing page if ACME domain reachability or certificate readiness does not settle.",
+      docId: "user-guide/openbaocluster/operations/troubleshooting",
+    },
+    {
+      label: "EKS Hardened",
+      description: "Move to the cloud baseline when you need public ACME, KMS auto-unseal, and a dedicated passthrough Gateway.",
+      docId: "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-external-tls.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-external-tls.md
new file mode 100644
index 000000000..55938fb2d
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/hardened-transit-external-tls.md
@@ -0,0 +1,400 @@
+---
+title: k3d Hardened / External TLS Recipe
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Reproduce the validated local hardened lane with Transit auto-unseal, externally managed TLS Secrets, self-init, and user-managed passthrough access.
+---
+
+<PageHeader
+  title="Reproduce the validated hardened local lane"
+  lede="This recipe stands up the local hardened lane with tenant onboarding, external Transit unseal, externally managed TLS Secrets, and user-managed TCP passthrough. Use it when you want the exact validated path for this topology."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an onboarded tenant namespace and admin ServiceAccount",
+      "a hardened cluster that self-initializes and never persists a root token Secret",
+      "Transit auto-unseal working against the external provider you chose for the lane",
+      "externally managed TLS Secrets and end-to-end passthrough traffic working together",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This recipe follows the hardened external-TLS lifecycle covered by the in-repo E2E suite and the local validation environment. The tested path includes tenant onboarding, external TLS Secrets, Transit auto-unseal, self-init, and successful JWT admin login.
+
+</Callout>
+
+<Callout type="note" title="Canonical operator behavior still lives in the main docs">
+
+Use the main guides for the product-wide source of truth on <SiteLink docId="user-guide/openbaocluster/configuration/security-profiles">security profiles</SiteLink>, <SiteLink docId="user-guide/openbaotenant/onboarding">tenant onboarding</SiteLink>, and <SiteLink docId="user-guide/openbaocluster/configuration/external-access">external access</SiteLink>. This recipe only captures the exact validated lane.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "Multi-tenant operator install with admission enabled",
+        "The validated lane starts from the standard tenant-onboarding path.",
+        "Namespace onboarding and guarded hardened behavior will not match the tested path.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "cert-manager is available",
+        "The lane expects external TLS Secrets to be provisioned before the workload depends on them.",
+        "The cluster will not reach `TLSReady=True` if the Secrets never appear.",
+      ],
+    },
+    {
+      cells: [
+        "Transit is reachable from the tenant namespace",
+        "The lane keeps the seal root external on purpose.",
+        "The cluster may initialize but fail to unseal or rejoin correctly after restart.",
+      ],
+    },
+    {
+      cells: [
+        "You know the ingress namespace",
+        "The network policy must trust the namespace that forwards passthrough traffic.",
+        "Traffic may never reach the public Service even though the cluster itself is healthy.",
+      ],
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Inputs to replace before apply"
+  columns={["Placeholder", "Example", "Purpose"]}
+  rows={[
+    {cells: ["`<namespace>`", "`openbaocluster-hardened`", "Tenant namespace for the cluster."]},
+    {cells: ["`<cluster-name>`", "`openbaocluster-hardened`", "`OpenBaoCluster` name."]},
+    {cells: ["`<openbao-version>`", "`2.5.0`", "OpenBao version."]},
+    {cells: ["`<transit-address>`", "`https://transit-provider.openbao-infra.svc:8200`", "Transit provider URL."]},
+    {cells: ["`<transit-key>`", "`openbao-unseal`", "Transit key name."]},
+    {cells: ["`<external-host>`", "`bao-hardened.example.com`", "External DNS name for clients."]},
+    {cells: ["`<ingress-namespace>`", "`default`", "Namespace of the ingress controller that forwards traffic to OpenBao."]},
+    {cells: ["`<transit-namespace>`", "`openbao-infra`", "Namespace hosting the Transit provider."]},
+    {cells: ["`<operator-namespace>`", "`openbao-operator-system`", "Namespace hosting the central `OpenBaoTenant` resource."]},
+  ]}
+/>
+
+## Step 1: Onboard the tenant namespace
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the namespace, onboarding request, and admin ServiceAccount"
+  code={`apiVersion: v1
+kind: Namespace
+metadata:
+  name: <namespace>
+  labels:
+    openbao.org/tenant: "true"
+---
+apiVersion: openbao.org/v1alpha1
+kind: OpenBaoTenant
+metadata:
+  name: <cluster-name>-tenant
+  namespace: <operator-namespace>
+spec:
+  targetNamespace: <namespace>
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: openbao-admin
+  namespace: <namespace>`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify tenant provisioning"
+  code={`kubectl -n <operator-namespace> describe openbaotenant <cluster-name>-tenant`}
+>
+  The steady-state expectation is `Provisioned=True`. Do not continue until the tenant onboarding path is actually complete.
+</CommandBlock>
+
+## Step 2: Create the Transit credential Secret
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Create the Secret used by transit auto-unseal"
+  code={`kubectl -n <namespace> create secret generic transit-provider-token \\
+  --from-literal=token='<transit-token>' \\
+  --from-file=ca.crt=/path/to/transit-provider-ca.crt`}
+>
+  For the validated path, the Secret contains `token` for `VAULT_TOKEN` and `ca.crt` for `VAULT_CACERT`.
+</CommandBlock>
+
+## Step 3: Create the external TLS Secrets
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Issue the TLS CA and server Secrets with cert-manager"
+  code={`apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: <cluster-name>-selfsigned-issuer
+  namespace: <namespace>
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: <cluster-name>-tls-ca
+  namespace: <namespace>
+spec:
+  secretName: <cluster-name>-tls-ca
+  commonName: <cluster-name>-ca
+  isCA: true
+  issuerRef:
+    kind: Issuer
+    name: <cluster-name>-selfsigned-issuer
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: <cluster-name>-ca-issuer
+  namespace: <namespace>
+spec:
+  ca:
+    secretName: <cluster-name>-tls-ca
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: <cluster-name>-tls-server
+  namespace: <namespace>
+spec:
+  secretName: <cluster-name>-tls-server
+  dnsNames:
+    - <external-host>
+    - openbao-cluster-<cluster-name>.local
+    - <cluster-name>.<namespace>.svc
+    - "*.<cluster-name>.<namespace>.svc"
+    - <cluster-name>-public.<namespace>.svc
+  issuerRef:
+    kind: Issuer
+    name: <cluster-name>-ca-issuer`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Wait for the TLS Secrets to become ready"
+  code={`kubectl -n <namespace> wait certificate/<cluster-name>-tls-ca --for=condition=Ready --timeout=5m
+kubectl -n <namespace> wait certificate/<cluster-name>-tls-server --for=condition=Ready --timeout=5m`}
+>
+  If you already use a corporate issuer, replace the issuer objects but keep the Secret names `<cluster-name>-tls-ca` and `<cluster-name>-tls-server`.
+</CommandBlock>
+
+## Step 4: Apply the OpenBaoCluster
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the validated hardened cluster manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoCluster
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+spec:
+  profile: Hardened
+  replicas: 3
+  version: "<openbao-version>"
+
+  storage:
+    size: "10Gi"
+  deletionPolicy: Retain
+
+  tls:
+    enabled: true
+    mode: External
+
+  configuration:
+    logLevel: "info"
+    ui: true
+    logging:
+      format: "json"
+
+  unseal:
+    type: transit
+    credentialsSecretRef:
+      name: transit-provider-token
+    transit:
+      address: "<transit-address>"
+      mountPath: "transit"
+      keyName: "<transit-key>"
+      tlsCACert: "/etc/bao/seal-creds/ca.crt"
+
+  selfInit:
+    enabled: true
+    oidc:
+      enabled: true
+    requests:
+      - name: enable-jwt-auth
+        operation: update
+        path: sys/auth/jwt
+        authMethod:
+          type: jwt
+      - name: create-admin-policy
+        operation: update
+        path: sys/policies/acl/admin
+        policy:
+          policy: |
+            path "*" {
+              capabilities = ["create", "read", "update", "delete", "list", "sudo"]
+            }
+      - name: create-admin-jwt-role
+        operation: update
+        path: auth/jwt/role/admin
+        data:
+          role_type: jwt
+          user_claim: sub
+          bound_audiences:
+            - openbao-internal
+          bound_subject: system:serviceaccount:<namespace>:openbao-admin
+          token_policies:
+            - admin
+          policies:
+            - admin
+          ttl: 1h
+
+  upgrade:
+    strategy: RollingUpdate
+
+  network:
+    trustedIngressPeers:
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: <ingress-namespace>
+    egressRules:
+      - to:
+          - namespaceSelector:
+              matchLabels:
+                kubernetes.io/metadata.name: <transit-namespace>
+        ports:
+          - protocol: TCP
+            port: 8200`}
+/>
+
+<Callout type="warning" title="API server endpoint IPs">
+
+If your CNI enforces egress on post-DNAT traffic, you may also need `spec.network.apiServerEndpointIPs`. See <SiteLink docId="user-guide/openbaocluster/configuration/network">Network configuration</SiteLink>.
+
+</Callout>
+
+<Callout type="note" title="AppArmor on local clusters">
+
+If kubelet rejects the Pods because AppArmor is unavailable, add:
+
+```yaml
+spec:
+  workloadHardening:
+    appArmorEnabled: false
+```
+
+</Callout>
+
+## Step 5: Expose the passthrough path
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Create the validated Traefik passthrough route"
+  code={`apiVersion: traefik.io/v1alpha1
+kind: IngressRouteTCP
+metadata:
+  name: bao-hardened
+  namespace: <namespace>
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - match: HostSNI(\`<external-host>\`)
+      services:
+        - name: <cluster-name>-public
+          port: 8200
+  tls:
+    passthrough: true`}
+>
+  This lane uses a user-managed Traefik `IngressRouteTCP`, not `spec.gateway`. Keep the passthrough route separate from any shared terminating edge.
+</CommandBlock>
+
+## Verify the lane
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the cluster conditions"
+  code={`kubectl -n <namespace> get openbaocluster <cluster-name> \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The steady-state expectation is `Available=True`, `TLSReady=True`, `UserAccessBootstrap=True`, `ProductionReady=True`, and `OpenBaoInitialized=True`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Confirm the cluster did not persist a root token Secret"
+  code={`kubectl -n <namespace> get secret <cluster-name>-root-token`}
+>
+  This should return `NotFound`. A hardened self-init lane should not leave the root token stored as a Kubernetes Secret.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Exchange a Kubernetes JWT for an OpenBao admin token"
+  code={`kubectl -n <namespace> port-forward svc/<cluster-name> 8200:8200
+export VAULT_ADDR="https://127.0.0.1:8200"
+JWT="$(kubectl -n <namespace> create token openbao-admin --audience openbao-internal --duration=1h)"
+
+curl -sS -k \\
+  -H 'Content-Type: application/json' \\
+  -d "{\"role\":\"admin\",\"jwt\":\"\${JWT}\"}" \\
+  "\${VAULT_ADDR%/}/v1/auth/jwt/login"`}
+>
+  The validated local path uses self-signed certificates, so the example uses `-k`. In a real environment with trusted certificates, remove that shortcut.
+</CommandBlock>
+
+<Callout type="note" title="What matters most in this lane">
+
+The important exposure contract here is successful end-to-end passthrough plus the `trustedIngressPeers` rule. `GatewayIntegrationReady` is not the primary signal because the route is intentionally managed outside `spec.gateway`.
+
+</Callout>
+
+<NextActions
+  title="After the lane is running"
+  items={[
+    {
+      label: "Plan upgrades",
+      description: "Move into the generic operating path once the validated lane is healthy.",
+      docId: "user-guide/openbaocluster/operations/upgrades",
+    },
+    {
+      label: "Configure backups",
+      description: "Add snapshot coverage before you use the lane as a hardened rehearsal environment.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "k3d Hardened / ACME",
+      description: "Compare this lane with the local hardened ACME lane when you want OpenBao-managed certificate issuance instead of external TLS Secrets.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/index.md
new file mode 100644
index 000000000..7c08f94f2
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/index.md
@@ -0,0 +1,47 @@
+---
+title: Local Recipe Catalog
+hide_title: true
+pageType: landing
+description: Local deployment recipes for the validated k3d lanes.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Local Recipe Catalog"
+  title="Validated local recipes"
+  lede="Deployment recipes for the validated k3d baselines are listed here. Read them with the matching baseline."
+  actions={[
+    {label: "Open k3d Development recipe", docId: "user-guide/validated-deployments/recipes/local/development-self-init-userpass", variant: "primary"},
+    {label: "Open k3d Cross-Cluster DR bootstrap", docId: "user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap", variant: "secondary"},
+  ]}
+/>
+
+<RouteList
+  title="Local recipes"
+  items={[
+    {
+      eyebrow: "01",
+      title: "k3d Development recipe",
+      description: "Bootstrap the development-profile local lane with self-init, userpass, shared edge, and RustFS backups.",
+      docId: "user-guide/validated-deployments/recipes/local/development-self-init-userpass",
+    },
+    {
+      eyebrow: "02",
+      title: "k3d Hardened / External TLS recipe",
+      description: "Deploy the hardened local lane with Transit auto-unseal, self-init, and externally managed TLS Secrets.",
+      docId: "user-guide/validated-deployments/recipes/local/hardened-transit-external-tls",
+    },
+    {
+      eyebrow: "03",
+      title: "k3d Hardened / ACME recipe",
+      description: "Deploy the hardened local lane that relies on OpenBao-managed ACME and validated hostname resolution.",
+      docId: "user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls",
+    },
+    {
+      eyebrow: "04",
+      title: "k3d Cross-Cluster DR bootstrap",
+      description: "Bootstrap the source and target clusters for the validated DR lane.",
+      docId: "user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap.md
new file mode 100644
index 000000000..77498f9ad
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap.md
@@ -0,0 +1,203 @@
+---
+title: k3d Cross-Cluster DR Bootstrap
+hide_title: true
+pageType: task
+journey: validated-deployments
+description: Stand up the validated local disaster-recovery environment with separate infra, source, and target clusters, shared Transit, RustFS storage, and passthrough ingress.
+---
+
+<PageHeader
+  title="Bootstrap the local cross-cluster DR baseline"
+  lede="This recipe prepares the validated local disaster-recovery lane: a shared trust-services cluster, a source cluster, and a target cluster, all wired so the restore event crosses the same trust, storage, and ingress boundaries used in a real DR rehearsal."
+/>
+
+<Checklist
+    title="Recipe outcomes"
+    items={[
+      "an infra cluster that hosts shared trust services and the shared Transit key",
+      "a healthy source cluster and target cluster with distinct namespaces and external endpoints",
+      "shared RustFS storage available to both clusters for snapshot transfer",
+      "known pre-restore state on both sides so the restore event can be verified later",
+    ]}
+  />
+
+
+<Callout type="success" title="Validated coverage">
+
+This bootstrap path matches the local DR lane that was proven end to end on March 16, 2026, including source backup, restore into the target cluster, target unseal, and credential plus data verification after restore.
+
+</Callout>
+
+<DecisionTable
+  title="Baseline assumptions"
+  columns={["Assumption", "Why it exists", "What breaks if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "You can create three k3d-backed contexts",
+        "The lane depends on an infra cluster plus separate source and target clusters.",
+        "If you collapse everything into one cluster, you stop proving the cluster-boundary part of DR.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "You have bootstrap automation or manifests for the three-cluster lab",
+        "The validated lane was assembled from repeatable infra, gateway, and operator setup rather than ad hoc kubectl edits.",
+        "Without repeatable bootstrap artifacts, the restore result is hard to trust or reproduce.",
+      ],
+    },
+    {
+      cells: [
+        "Shared Transit and shared storage are available before cluster apply",
+        "Source and target clusters both depend on them from the start.",
+        "The restore will fail later if these dependencies are improvised after the source cluster is already in use.",
+      ],
+    },
+    {
+      cells: [
+        "Cutover remains manual",
+        "The bootstrap only prepares the recovery pair; it does not automate failover.",
+        "Treating the lane as automatic DR creates false confidence in behavior it does not validate.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Baseline defaults"
+  columns={["Value", "Default", "Purpose"]}
+  rows={[
+    {cells: ["Infra context", "`k3d-openbao-dr-infra`", "Shared trust-services cluster."]},
+    {cells: ["Source context", "`k3d-openbao-dr-source`", "Primary cluster that creates the snapshot."]},
+    {cells: ["Target context", "`k3d-openbao-dr-target`", "Recovery target cluster."]},
+    {cells: ["Source hostname", "`bao-dr-source.example.com`", "Source passthrough endpoint."]},
+    {cells: ["Target hostname", "`bao-dr-target.example.com`", "Target passthrough endpoint."]},
+    {cells: ["Transit endpoint", "`https://host.k3d.internal`", "Shared trust-services endpoint."]},
+    {cells: ["Snapshot bucket", "`openbao-dr-backups`", "Shared RustFS bucket."]},
+    {cells: ["Transit key", "`openbao-dr-shared-unseal`", "Shared seal root used by both clusters."]},
+  ]}
+/>
+
+## Step 1: Bootstrap the three-cluster lab
+
+<CommandBlock
+  language="text"
+  label="configure"
+  title="Run the bootstrap automation or manifests for this baseline"
+  code={`The validated bootstrap needs to create and wire:
+- one infra cluster for shared trust services
+- one source cluster
+- one target cluster
+- the Gateway API Standard bundle in each cluster
+- a dedicated passthrough edge in each cluster
+- a shared RustFS instance and bucket
+- a shared external OpenBao trust-services endpoint in the infra cluster
+- one operator install in the source cluster
+- one operator install in the target cluster`}
+>
+  The exact command is specific to your k3d automation. The lane contract is the resulting topology, not the name of one local helper script.
+</CommandBlock>
+
+<Callout type="tip" title="Validated defaults">
+
+The validated local proof used the public signed `edge` images by default:
+
+- `ghcr.io/dc-tec/openbao-operator:edge`
+- `ghcr.io/dc-tec/openbao-backup:edge`
+
+</Callout>
+
+## Step 2: Apply the source and target clusters
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Apply the source and target OpenBaoCluster manifests"
+  code={`kubectl --context <source-context> apply -f source-openbaocluster.yaml
+kubectl --context <target-context> apply -f target-openbaocluster.yaml`}
+>
+  The source and target manifests must both reference the same Transit endpoint, CA bundle, SNI, and key name. That shared seal root is the invariant the restore event depends on.
+</CommandBlock>
+
+## Verify the bootstrap
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check source and target readiness"
+  code={`kubectl --context k3d-openbao-dr-source -n openbaocluster-dr-source \\
+  get openbaocluster openbaocluster-dr-source \\
+  -o jsonpath='{.status.phase}{"\\n"}{.status.readyReplicas}{"\\n"}{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'
+
+kubectl --context k3d-openbao-dr-target -n openbaocluster-dr-target \\
+  get openbaocluster openbaocluster-dr-target \\
+  -o jsonpath='{.status.phase}{"\\n"}{.status.readyReplicas}{"\\n"}{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  The important steady-state expectation on both sides is `phase=Running`, `readyReplicas=1`, `Available=True`, `OpenBaoInitialized=True`, and `OpenBaoSealed=False`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the source and target health endpoints"
+  code={`curl -ksS --resolve bao-dr-source.example.com:10443:127.0.0.1 \\
+  https://bao-dr-source.example.com:10443/v1/sys/health
+
+curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+  https://bao-dr-target.example.com:11443/v1/sys/health`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify the pre-restore source and target state"
+  code={`SOURCE_TOKEN="$(
+  curl -ksS --resolve bao-dr-source.example.com:10443:127.0.0.1 \\
+    -H 'Content-Type: application/json' \\
+    -d '{"password":"source-demo-password"}' \\
+    https://bao-dr-source.example.com:10443/v1/auth/userpass/login/demo-admin \\
+  | jq -r '.auth.client_token'
+)"
+
+TARGET_TOKEN="$(
+  curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+    -H 'Content-Type: application/json' \\
+    -d '{"password":"target-demo-password"}' \\
+    https://bao-dr-target.example.com:11443/v1/auth/userpass/login/demo-admin \\
+  | jq -r '.auth.client_token'
+)"
+
+curl -ksS --resolve bao-dr-source.example.com:10443:127.0.0.1 \\
+  -H "X-Vault-Token: \${SOURCE_TOKEN}" \\
+  https://bao-dr-source.example.com:10443/v1/secret/data/dr-control
+
+curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+  -H "X-Vault-Token: \${TARGET_TOKEN}" \\
+  https://bao-dr-target.example.com:11443/v1/secret/data/dr-control`}
+>
+  The validated lane starts with `phase1-source` on the source side and `phase1-target` on the target side so the restore event can prove that target state was really replaced.
+</CommandBlock>
+
+<NextActions
+  title="Continue the DR rehearsal"
+  items={[
+    {
+      label: "DR restore runbook",
+      description: "Run the destructive restore event once the source and target are both healthy and the pre-restore state is known.",
+      docId: "user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs",
+    },
+    {
+      label: "Reference architecture",
+      description: "Review the DR invariants again before you move the source snapshot into the target cluster.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs",
+    },
+    {
+      label: "Restore from backup",
+      description: "Use the generic restore guide for the operator-wide restore behavior behind this lane-specific runbook.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs.md
new file mode 100644
index 000000000..5f8dc57f4
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs.md
@@ -0,0 +1,217 @@
+---
+title: k3d Cross-Cluster DR Restore
+hide_title: true
+pageType: runbook
+journey: validated-deployments
+description: Restore the validated local disaster-recovery target from a source snapshot stored in RustFS while preserving the shared Transit seal-root assumptions the lane depends on.
+---
+
+<PageHeader
+  title="Restore the target in the local DR lane"
+  lede="This runbook restores the target cluster in the validated local DR lane from a source snapshot stored in RustFS. It assumes the source and target already share the same external Transit key and that you are ready to overwrite the target bootstrap state."
+/>
+
+<Checklist
+    title="Runbook outcomes"
+    items={[
+      "a fresh source snapshot written to shared RustFS storage",
+      "an `OpenBaoRestore` object that completes on the target cluster",
+      "a restored target that unseals with the shared Transit key",
+      "post-restore proof that source credentials and source data replaced the target bootstrap state",
+    ]}
+  />
+
+
+<Callout type="danger" title="Destructive operation">
+
+This workflow overwrites the target cluster state. Existing auth methods, policies, and data on the target are replaced by the snapshot contents.
+
+</Callout>
+
+<DecisionTable
+  title="Restore prerequisites"
+  columns={["Requirement", "Why it exists", "What happens if it is wrong"]}
+  rows={[
+    {
+      cells: [
+        "Source and target share the same Transit root of trust",
+        "Restored data must decrypt under the same external seal key after it lands on the target side.",
+        "The restore can complete and the target can still remain sealed.",
+      ],
+      emphasis: "recommended",
+    },
+    {
+      cells: [
+        "The target cluster already exists and exposes restore auth",
+        "The restore Job needs a live target to authenticate against and mutate.",
+        "The `OpenBaoRestore` object will fail before it can apply the snapshot.",
+      ],
+    },
+    {
+      cells: [
+        "The snapshot key comes from a fresh successful backup",
+        "The runbook is supposed to prove actual source-state transfer, not a stale object lookup.",
+        "You may restore the wrong data set and draw the wrong conclusion about the lane.",
+      ],
+    },
+    {
+      cells: [
+        "Cutover is still manual",
+        "Verification must happen before any client-facing change.",
+        "You can move traffic to a target that restored incorrectly or still needs operator attention.",
+      ],
+      emphasis: "caution",
+    },
+  ]}
+/>
+
+<DecisionTable
+  kind="reference"
+  title="Baseline defaults"
+  columns={["Value", "Default", "Purpose"]}
+  rows={[
+    {cells: ["Source context", "`k3d-openbao-dr-source`", "Primary cluster that creates the backup."]},
+    {cells: ["Target context", "`k3d-openbao-dr-target`", "Recovery target cluster."]},
+    {cells: ["Source namespace", "`openbaocluster-dr-source`", "Namespace containing the source cluster."]},
+    {cells: ["Target namespace", "`openbaocluster-dr-target`", "Namespace containing the target cluster."]},
+    {cells: ["Restore name", "`openbaocluster-dr-target-restore`", "`OpenBaoRestore` name."]},
+  ]}
+/>
+
+## Step 1: Trigger a fresh source backup
+
+<CommandBlock
+  language="bash"
+  label="apply"
+  title="Trigger the source backup"
+  code={`kubectl --context k3d-openbao-dr-source -n openbaocluster-dr-source annotate \\
+  openbaocluster openbaocluster-dr-source \\
+  openbao.org/trigger-backup="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite`}
+/>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Wait for the source cluster to finish backing up"
+  code={`kubectl --context k3d-openbao-dr-source -n openbaocluster-dr-source \\
+  get openbaocluster openbaocluster-dr-source \\
+  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}'`}
+>
+  Wait until `BackingUp=False` again before you capture the snapshot key.
+</CommandBlock>
+
+## Step 2: Capture the snapshot key
+
+<CommandBlock
+  language="bash"
+  label="inspect"
+  title="Read the backup object key from source status"
+  code={`SNAPSHOT_KEY="$(
+  kubectl --context k3d-openbao-dr-source -n openbaocluster-dr-source \\
+    get openbaocluster openbaocluster-dr-source \\
+    -o jsonpath='{.status.backup.lastBackupName}'
+)"
+
+printf '%s\\n' "\${SNAPSHOT_KEY}"`}
+/>
+
+## Step 3: Apply the restore on the target cluster
+
+<CommandBlock
+  language="yaml"
+  label="apply"
+  title="Apply the validated OpenBaoRestore manifest"
+  code={`apiVersion: openbao.org/v1alpha1
+kind: OpenBaoRestore
+metadata:
+  name: openbaocluster-dr-target-restore
+  namespace: openbaocluster-dr-target
+spec:
+  cluster: openbaocluster-dr-target
+  force: true
+  image: ghcr.io/dc-tec/openbao-backup:edge
+  source:
+    target:
+      provider: s3
+      endpoint: "http://rustfs.openbaocluster-dr-target.svc:19000"
+      bucket: "openbao-dr-backups"
+      usePathStyle: true
+      credentialsSecretRef:
+        name: rustfs-secret
+    key: "<snapshot-key>"
+  jwtAuthRole: openbao-operator-restore`}
+>
+  Replace `<snapshot-key>` with the exact value from the previous step before you apply the manifest.
+</CommandBlock>
+
+## Verify the restore
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Watch the restore object and inspect final status"
+  code={`kubectl --context k3d-openbao-dr-target -n openbaocluster-dr-target \\
+  get openbaorestore openbaocluster-dr-target-restore -w
+
+kubectl --context k3d-openbao-dr-target -n openbaocluster-dr-target \\
+  get openbaorestore openbaocluster-dr-target-restore \\
+  -o jsonpath='{.status.phase}{"\\n"}{range .status.conditions[*]}{.type}={.status}{" reason="}{.reason}{"\\n"}{end}{.status.snapshotKey}{"\\n"}'`}
+>
+  The steady-state expectation is `phase=Completed`, `RestoreConfigurationReady=True`, and `RestoreComplete=True` with reason `RestoreSucceeded`.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Check the target health endpoint after restore"
+  code={`curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+  https://bao-dr-target.example.com:11443/v1/sys/health`}
+>
+  The restored target should return a normal OpenBao health response and the cluster lineage should now match the source snapshot.
+</CommandBlock>
+
+<CommandBlock
+  language="bash"
+  label="verify"
+  title="Verify credential cutover and restored data"
+  code={`curl -ksS -o /tmp/target-login.json -w '%{http_code}\\n' \\
+  --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+  -H 'Content-Type: application/json' \\
+  -d '{"password":"target-demo-password"}' \\
+  https://bao-dr-target.example.com:11443/v1/auth/userpass/login/demo-admin
+
+SOURCE_TOKEN="$(
+  curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+    -H 'Content-Type: application/json' \\
+    -d '{"password":"source-demo-password"}' \\
+    https://bao-dr-target.example.com:11443/v1/auth/userpass/login/demo-admin \\
+  | jq -r '.auth.client_token'
+)"
+
+curl -ksS --resolve bao-dr-target.example.com:11443:127.0.0.1 \\
+  -H "X-Vault-Token: \${SOURCE_TOKEN}" \\
+  https://bao-dr-target.example.com:11443/v1/secret/data/dr-control`}
+>
+  The old target password should fail. The source password should succeed, and the `dr-control` marker should now show `phase1-source`.
+</CommandBlock>
+
+<NextActions
+  title="After the restore"
+  items={[
+    {
+      label: "Reference architecture",
+      description: "Review the DR invariants again before you consider any manual cutover or cloud equivalent.",
+      docId: "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs",
+    },
+    {
+      label: "Troubleshoot the cluster",
+      description: "Use the generic operator incident guide if restore succeeds but the target is still degraded or sealed.",
+      docId: "user-guide/openbaocluster/operations/troubleshooting",
+    },
+    {
+      label: "Restore overview",
+      description: "Return to the generic restore model when you need the operator-wide explanation behind this lane-specific runbook.",
+      docId: "user-guide/openbaorestore/overview",
+    },
+  ]}
+/>
diff --git a/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/index.md b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/index.md
new file mode 100644
index 000000000..5fa633011
--- /dev/null
+++ b/website/versioned_docs/version-0.3.0/user-guide/validated-deployments/runbooks/index.md
@@ -0,0 +1,45 @@
+---
+title: Validated Procedure Catalog
+hide_title: true
+pageType: landing
+description: Catalog of validated procedures that still need lane-specific treatment, with generic backup and restore workflows handed off to the main operator docs.
+---
+
+<PageHero
+  variant="landing"
+  eyebrow="Validated Deployments / Procedure Catalog"
+  title="Validated runbooks"
+  lede="Runbooks that still depend on a specific validated baseline are listed here. Generic backup and restore guidance lives in the main `Operate` and `Recovery & Restore` sections."
+  actions={[
+    {label: "Open DR restore runbook", docId: "user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs", variant: "primary"},
+    {label: "Open generic restore guide", docId: "user-guide/openbaorestore/restore", variant: "secondary"},
+  ]}
+/>
+
+<RouteList
+  title="Lane-specific procedure"
+  items={[
+    {
+      eyebrow: "01",
+      title: "Cross-cluster DR restore",
+      description: "Restore procedure for the validated k3d DR environment with shared Transit and shared snapshot storage.",
+      docId: "user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs",
+    },
+  ]}
+/>
+
+<NextActions
+  title="Main operator docs for generic procedures"
+  items={[
+    {
+      label: "Backup operations",
+      description: "Canonical backup scheduling, credential, retention, and verification guidance.",
+      docId: "user-guide/openbaocluster/operations/backups",
+    },
+    {
+      label: "Restore from backup",
+      description: "Canonical restore workflow for `OpenBaoRestore`, storage sources, and destructive restore behavior.",
+      docId: "user-guide/openbaorestore/restore",
+    },
+  ]}
+/>
diff --git a/website/versioned_sidebars/version-0.3.0-sidebars.json b/website/versioned_sidebars/version-0.3.0-sidebars.json
new file mode 100644
index 000000000..f7cf3eb72
--- /dev/null
+++ b/website/versioned_sidebars/version-0.3.0-sidebars.json
@@ -0,0 +1,746 @@
+{
+  "operatorDocs": [
+    "index",
+    {
+      "type": "category",
+      "label": "Get Started",
+      "link": {
+        "type": "doc",
+        "id": "user-guide/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Core Path",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/operator/deployment-decision-guide",
+              "label": "1. Choose a deployment model"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/operator/installation",
+              "label": "2. Install the operator"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaotenant/onboarding",
+              "label": "3. Onboard the target namespace"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/getting-started",
+              "label": "4. Create your first cluster"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/next-steps",
+              "label": "5. Prepare for day 2"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Supporting Decisions",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/operator/single-tenant-mode",
+              "label": "Single-tenant mode"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/operator/identity-and-access",
+              "label": "Operator identity and access"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/operator/authn",
+              "label": "Operator authentication"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/operator/authz",
+              "label": "Operator authorization"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Tenant Onboarding",
+      "items": [
+        {
+          "type": "doc",
+          "id": "user-guide/openbaotenant/overview",
+          "label": "Tenancy & Governance"
+        },
+        {
+          "type": "doc",
+          "id": "user-guide/openbaotenant/multi-tenancy",
+          "label": "Multi-tenant security"
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Configure",
+      "link": {
+        "type": "doc",
+        "id": "user-guide/openbaocluster/configuration/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Read This First",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/overview",
+              "label": "Cluster overview"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Cluster Baseline",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/security-profiles",
+              "label": "Security profiles"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/self-init",
+              "label": "Self-initialization"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/unseal",
+              "label": "Unseal configuration"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/server",
+              "label": "Server configuration"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Service Boundary",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/external-access",
+              "label": "External access"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/network",
+              "label": "Network configuration"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/gateway-api",
+              "label": "Gateway API support"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Read Scaling",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/read-replicas",
+              "label": "Read replicas"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Platform Readiness",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/resources-storage",
+              "label": "Resources and storage"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/observability",
+              "label": "Observability"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/configuration/air-gapped",
+              "label": "Air-gapped and private registries"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Operate",
+      "link": {
+        "type": "doc",
+        "id": "user-guide/openbaocluster/operations/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Reliability & Change",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/production-checklist",
+              "label": "Production checklist"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/backups",
+              "label": "Configure backups"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/upgrades",
+              "label": "Plan upgrades"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Cluster Controls",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/maintenance",
+              "label": "Run planned maintenance"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/pausing",
+              "label": "Pause reconciliation"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/deletion",
+              "label": "Decommission a cluster"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Troubleshooting & Recovery",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/operations/troubleshooting",
+              "label": "Troubleshoot the cluster"
+            },
+            {
+              "type": "doc",
+              "id": "user-guide/openbaocluster/recovery/index",
+              "label": "Recovery & Restore"
+            },
+            {
+              "type": "category",
+              "label": "Incident Recovery",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaocluster/recovery/safe-mode",
+                  "label": "Enter safe mode"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaocluster/recovery/no-leader",
+                  "label": "Recover from no leader"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaocluster/recovery/sealed-cluster",
+                  "label": "Recover a sealed cluster"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaocluster/recovery/failed-rollback",
+                  "label": "Recover from failed rollback"
+                }
+              ]
+            },
+            {
+              "type": "category",
+              "label": "Restore from Backup",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaorestore/restore",
+                  "label": "Run a restore"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaorestore/overview",
+                  "label": "Restore overview"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/openbaorestore/recovery-restore-after-upgrade",
+                  "label": "Recover after upgrade restore"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Validated Deployments",
+      "link": {
+        "type": "doc",
+        "id": "user-guide/validated-deployments/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Cloud Baselines",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/validated-deployments/architectures/cloud/index",
+              "label": "Cloud overview"
+            },
+            {
+              "type": "category",
+              "label": "EKS Development",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/cloud/amazon-eks-development-awskms-s3",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/cloud/amazon-eks-development-awskms-s3",
+                  "label": "Deployment recipe"
+                }
+              ]
+            },
+            {
+              "type": "category",
+              "label": "EKS Hardened",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/cloud/amazon-eks-hardened-awskms-acme",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/cloud/amazon-eks-hardened-awskms-acme",
+                  "label": "Deployment recipe"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Local Baselines",
+          "items": [
+            {
+              "type": "doc",
+              "id": "user-guide/validated-deployments/architectures/local/index",
+              "label": "Local overview"
+            },
+            {
+              "type": "category",
+              "label": "k3d Development",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/local/k3d-development-shared-edge-rustfs",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/local/development-self-init-userpass",
+                  "label": "Deployment recipe"
+                }
+              ]
+            },
+            {
+              "type": "category",
+              "label": "k3d Hardened / External TLS",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-external-tls",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/local/hardened-transit-external-tls",
+                  "label": "Deployment recipe"
+                }
+              ]
+            },
+            {
+              "type": "category",
+              "label": "k3d Hardened / ACME",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/local/k3d-hardened-transit-acme",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/local/hardened-transit-acme-tls",
+                  "label": "Deployment recipe"
+                }
+              ]
+            },
+            {
+              "type": "category",
+              "label": "k3d Cross-Cluster DR",
+              "items": [
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/architectures/local/k3d-cross-cluster-dr-transit-rustfs",
+                  "label": "Reference architecture"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/recipes/local/k3d-cross-cluster-dr-bootstrap",
+                  "label": "Bootstrap recipe"
+                },
+                {
+                  "type": "doc",
+                  "id": "user-guide/validated-deployments/runbooks/cross-cluster-dr-restore-rustfs",
+                  "label": "DR restore runbook"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Security",
+      "link": {
+        "type": "doc",
+        "id": "security/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Security Model",
+          "items": [
+            {
+              "type": "doc",
+              "id": "security/fundamentals/index",
+              "label": "Security model overview"
+            },
+            {
+              "type": "doc",
+              "id": "security/fundamentals/threat-model",
+              "label": "Threat model"
+            },
+            {
+              "type": "doc",
+              "id": "security/fundamentals/profiles",
+              "label": "Production posture"
+            },
+            {
+              "type": "doc",
+              "id": "security/fundamentals/secrets-management",
+              "label": "Secrets and trust material"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Platform Controls",
+          "items": [
+            {
+              "type": "doc",
+              "id": "security/infrastructure/index",
+              "label": "Platform controls overview"
+            },
+            {
+              "type": "doc",
+              "id": "security/infrastructure/rbac",
+              "label": "RBAC architecture"
+            },
+            {
+              "type": "doc",
+              "id": "security/infrastructure/admission-policies",
+              "label": "Admission policies"
+            },
+            {
+              "type": "doc",
+              "id": "security/infrastructure/network-security",
+              "label": "Network security"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Workload Protections",
+          "items": [
+            {
+              "type": "doc",
+              "id": "security/workload/index",
+              "label": "Workload protections overview"
+            },
+            {
+              "type": "doc",
+              "id": "security/workload/workload-security",
+              "label": "Pod and runtime security"
+            },
+            {
+              "type": "doc",
+              "id": "security/workload/tls",
+              "label": "TLS and identity"
+            },
+            {
+              "type": "doc",
+              "id": "security/workload/supply-chain",
+              "label": "Supply-chain verification"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Tenant Isolation",
+          "items": [
+            {
+              "type": "doc",
+              "id": "security/multi-tenancy/index",
+              "label": "Tenant isolation overview"
+            },
+            {
+              "type": "doc",
+              "id": "security/multi-tenancy/tenant-isolation",
+              "label": "Isolation model"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Architecture",
+      "link": {
+        "type": "doc",
+        "id": "architecture/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Read This First",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/operator-invariants",
+              "label": "Operator invariants"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/components",
+              "label": "Component design"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/lifecycle/index",
+              "label": "Lifecycle architecture"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Workload Managers",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/workload-managers",
+              "label": "Workload managers"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/cert-manager",
+              "label": "Cert manager"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/init-manager",
+              "label": "Init manager"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Operations Managers",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/upgrade-manager",
+              "label": "Upgrade manager"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/backup-manager",
+              "label": "Backup manager"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/restore-manager",
+              "label": "Restore manager"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Provisioning",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/provisioner-manager",
+              "label": "Provisioner manager"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Supporting Services",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/operation-lifecycle",
+              "label": "Operation lifecycle coordination"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Lifecycle Flows",
+          "items": [
+            {
+              "type": "doc",
+              "id": "architecture/lifecycle/day0-provisioning",
+              "label": "Day 0 provisioning"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/lifecycle/day1-creation",
+              "label": "Day 1 creation"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/lifecycle/day2-operations",
+              "label": "Day 2 operations"
+            },
+            {
+              "type": "doc",
+              "id": "architecture/lifecycle/dayN-backups",
+              "label": "Day N backups and restore"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Reference",
+      "link": {
+        "type": "doc",
+        "id": "reference/index"
+      },
+      "items": [
+        {
+          "type": "category",
+          "label": "Quick Checks",
+          "items": [
+            {
+              "type": "doc",
+              "id": "reference/compatibility",
+              "label": "Compatibility matrix"
+            },
+            {
+              "type": "doc",
+              "id": "reference/operator-upgrade-compatibility",
+              "label": "Upgrade compatibility"
+            },
+            {
+              "type": "doc",
+              "id": "reference/status-and-events",
+              "label": "Status conditions and events"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "API Surface",
+          "items": [
+            {
+              "type": "doc",
+              "id": "reference/api",
+              "label": "API reference"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Lifecycle & Support Contract",
+          "items": [
+            {
+              "type": "doc",
+              "id": "reference/support-policy",
+              "label": "Support policy"
+            },
+            {
+              "type": "doc",
+              "id": "reference/deprecation-policy",
+              "label": "Deprecation policy"
+            }
+          ]
+        },
+        {
+          "type": "category",
+          "label": "Constraints & Caveats",
+          "items": [
+            {
+              "type": "doc",
+              "id": "reference/known-limitations",
+              "label": "Known limitations"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Design",
+      "link": {
+        "type": "doc",
+        "id": "design/index"
+      },
+      "items": [
+        {
+          "type": "doc",
+          "id": "design/claims-and-service-offerings",
+          "label": "Claims and Service Offerings"
+        }
+      ]
+    },
+    "roadmap"
+  ]
+}
diff --git a/website/versions.json b/website/versions.json
index 434e9e81e..5360d73ab 100644
--- a/website/versions.json
+++ b/website/versions.json
@@ -1,4 +1,5 @@
 [
+  "0.3.0",
   "0.2.0",
   "0.1.0"
 ]