acornops · tjtanjin · Aug 2, 2026 · Aug 2, 2026 · Aug 2, 2026
diff --git a/deploy/configuration-reference.mdx b/deploy/configuration-reference.mdx
@@ -177,7 +177,7 @@ For Kubernetes and VM Compose settings that derive the redirect URI from your co
 https://console.example.com/api/v1/auth/oidc/callback
 ```
 
-That URL is still served by the control plane through the console host's `/api` proxy. If you override `auth.oidc.redirectUri` or `OIDC_REDIRECT_URI`, register the exact override value instead. Registering only `https://api.example.com/api/v1/auth/oidc/callback` will fail unless your deployment is configured to use that URL as the OIDC redirect URI.
+That URL is still served by the control plane through the console host's `/api` proxy. If you override `userAccess.oidc.redirectUri` or `OIDC_REDIRECT_URI`, register the exact override value instead. Registering only `https://api.example.com/api/v1/auth/oidc/callback` will fail unless your deployment is configured to use that URL as the OIDC redirect URI.
 
 Register this exact post-logout redirect URI when your provider supports
 RP-initiated logout:
@@ -193,10 +193,10 @@ Common OIDC settings:
 | Issuer URL | Provider issuer used for discovery and token validation |
 | Public issuer URL | Optional override when internal and public issuer URLs differ |
 | Client ID | OIDC client configured for AcornOps |
-| Client secret | Referenced by `auth.oidc.clientSecret.existingSecret` and `key`; it is not required when OIDC is disabled |
+| Client secret | Referenced by `userAccess.oidc.clientSecret.existingSecret` and `key`; it is not required when OIDC is disabled |
 | Scopes | Defaults to `openid profile email` |
 | Token endpoint auth method | Defaults to client-secret based auth |
-| Admission policy | `auth.oidc.admission` or `OIDC_ADMISSION_POLICY_JSON`; an empty policy allows any authenticated OIDC identity |
+| Admission policy | `userAccess.oidc.admission` or `OIDC_ADMISSION_POLICY_JSON`; an empty policy allows any authenticated OIDC identity |
 | Explicit prelinks | `OIDC_PRELINKED_IDENTITIES_JSON` supplied through the control-plane environment; each mapping requires the exact provider subject, email, display name, and verification boolean |
 | End-session endpoint override | Public browser-facing logout endpoint for split internal/public provider routing |
 | Post-logout redirect URI | Exact callback registered with the provider |
@@ -227,7 +227,7 @@ Admission rules are combined with AND semantics. You can require a literal
 keeps nested and namespaced claims unambiguous:
 
 ```yaml
-auth:
+userAccess:
   oidc:
     enabled: true
     clientSecret:
@@ -264,10 +264,12 @@ Password login is enabled by default alongside OIDC, password reset is enabled b
 
 Operators can:
 
-- disable password login with `auth.password.enabled=false` or `PASSWORD_AUTH_ENABLED=false`,
-- disable password reset with `auth.password.resetEnabled=false` or `PASSWORD_RESET_ENABLED=false`,
-- allow and default self-service signup with `platformSettings.passwordSignup`, then manage the
-  effective runtime value from the audited Platform Admin settings page.
+- disable password login with `userAccess.password.enabled=false` or `PASSWORD_AUTH_ENABLED=false`,
+- disable password reset with `userAccess.password.resetEnabled=false` or `PASSWORD_RESET_ENABLED=false`,
+- allow `password` in `platformSettings.userSignInMethods.allowedMethods` and
+  `defaultMethods`, then manage the effective sign-in methods from the audited
+  Platform Admin settings page. Self-service signup becomes available only
+  when the password email-verification prerequisites are also ready.
 
 Only enable self-service signup in private deployments where account creation has been reviewed.
 

diff --git a/deploy/deployment-reference.mdx b/deploy/deployment-reference.mdx
@@ -45,7 +45,8 @@ Review these value groups before installing or upgrading:
 | Area | Values |
 | --- | --- |
 | Public hosts | `platform.publicUrl`, `platform.consoleUrl`, `exposure.ingress.apiHost`, `exposure.ingress.consoleHost` |
-| Auth | `auth.oidc.*`, `auth.password.*`, `auth.session.*` |
+| Workspace-user access | `userAccess.oidc.*`, `userAccess.password.*`, `userAccess.session.*` |
+| Platform-admin access | `platformAdminAccess.*` |
 | Workspace roles | `workspaceRoles.enabledBuiltIns`, `workspaceRoles.customTemplates` |
 | Run policy and target connectivity | `ai.*`, `assistantRuntime.*`, `agentGateway.*` |
 | Reasoning summaries | `ai.reasoningSummariesEnabled`, `ai.allowedReasoningSummaryModes`, `ai.allowedReasoningEfforts` |
@@ -159,12 +160,18 @@ If `enabledBuiltIns` is omitted, all built-ins are enabled. If it is provided, i
 Example install:
 
 ```bash
+export ACORNOPS_PLATFORM_VERSION="<version-from-stack-versions.yaml>"
+
 helm upgrade --install acornops-platform oci://ghcr.io/acornops/charts/acornops-platform \
+  --version "${ACORNOPS_PLATFORM_VERSION}" \
   --namespace acornops-platform \
   --create-namespace \
   --values values.prod.yaml
 ```
 
+Resolve the version from the `acornopsPlatform` entry in the
+[`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml).
+
 ### Production exposure
 
 Expose only the management console and control-plane public routes:
@@ -210,7 +217,7 @@ Before starting the stack:
 - Keep `TRUST_PROXY=1` when the edge proxy owns TLS and forwarded host headers.
 - Point database and Redis settings at durable services.
 - Review JWKS readiness, request-size, rate-limit, and MCP egress variables.
-- Pin image tags instead of using mutable tags.
+- Pin all image references from the `vm-prod-v1` release matrix instead of using mutable or independently selected tags.
 - Confirm the reverse proxy terminates TLS for the console and API hosts.
 
 Database init jobs run before services start. Treat init failures as deployment blockers.

diff --git a/deploy/index.mdx b/deploy/index.mdx
@@ -28,12 +28,13 @@ Deploy the central platform first. Workspace administrators connect targets afte
 ## Recommended sequence
 
 1. [Prepare the prerequisites](/deploy/prerequisites).
-2. Deploy the central platform on [Kubernetes](/deploy/kubernetes) or with [VM Compose](/deploy/vm-compose).
-3. [Configure platform policy](/deploy/configuration).
-4. Complete the [production readiness checklist](/deploy/production-readiness).
-5. Optionally configure the [platform admin console](/deploy/platform-admin-console) for deployment-wide governance.
-6. Hand workspace onboarding to the intended owners and users.
-7. Use the [operations guide](/deploy/operations) for upgrades, health, and rotation.
+2. Select one complete, published stack from the [`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml). Do not combine independently released component tags.
+3. Deploy the central platform on [Kubernetes](/deploy/kubernetes) or with [VM Compose](/deploy/vm-compose).
+4. [Configure platform policy](/deploy/configuration).
+5. Complete the [production readiness checklist](/deploy/production-readiness).
+6. Optionally configure the [platform admin console](/deploy/platform-admin-console) for deployment-wide governance.
+7. Hand workspace onboarding to the intended owners and users.
+8. Use the [operations guide](/deploy/operations) for upgrades, health, and rotation.
 
 The [deployment reference](/deploy/deployment-reference) and [configuration reference](/deploy/configuration-reference) preserve the complete setting and behavior details.
 

diff --git a/deploy/kubernetes.mdx b/deploy/kubernetes.mdx
@@ -24,15 +24,24 @@ The chart references operator-managed secret values rather than placing them dir
 
 ## Install
 
-Create the Secret expected by your values, then install a pinned platform release:
+Choose `ACORNOPS_PLATFORM_VERSION` from the `acornopsPlatform` entry in the
+[`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml).
+Create the Secret expected by your values, then install that exact chart version:
 
 ```bash
+export ACORNOPS_PLATFORM_VERSION="<version-from-stack-versions.yaml>"
+
 helm upgrade --install acornops-platform oci://ghcr.io/acornops/charts/acornops-platform \
+  --version "${ACORNOPS_PLATFORM_VERSION}" \
   --namespace acornops-platform \
   --create-namespace \
   --values values.prod.yaml
 ```
 
+The chart pins the compatible platform images. Do not override one component
+with an independently released tag unless a newer complete stack matrix lists
+that combination.
+
 Review public hosts, auth, workspace roles, run policy, model settings, target connectivity, gateway controls, internal transport, and network egress before installation.
 
 ## Exposure

diff --git a/deploy/operations.mdx b/deploy/operations.mdx
@@ -9,7 +9,7 @@ This page covers day-two operations for the central platform and connected Kuber
 
 For production-style environments:
 
-1. Select one pinned stack matrix whose execution contract version is exactly 2.
+1. Select one pinned stack from the [`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml) whose execution contract version is exactly 2.
 2. Confirm Postgres and Redis availability, then explicitly recreate the pre-release control-plane and gateway databases for this greenfield schema epoch.
 3. Deploy gateway, control plane, execution engine, deployment metadata, and documentation as one stack. Do not roll any image independently.
 4. Smoke test OIDC sign-in, workspace listing, agent connectivity, built-in tools, approval receipt execution, workspace and individual credential lifecycles, and a read-only run.
@@ -124,7 +124,7 @@ Also register `https://console.example.com/api/v1/auth/oidc/logout/callback`
 as an exact post-logout redirect. If logout reports that only the AcornOps
 session was cleared, verify the provider discovery document exposes
 `end_session_endpoint` or configure the public
-`auth.oidc.logout.endSessionEndpointOverride`. Never use an internal service
+`userAccess.oidc.logout.endSessionEndpointOverride`. Never use an internal service
 hostname for the browser-facing logout endpoint.
 
 Keep query strings out of edge and ingress access logs. OIDC callbacks and

diff --git a/deploy/production-readiness.mdx b/deploy/production-readiness.mdx
@@ -5,6 +5,12 @@ description: "Validate a self-hosted deployment before operational use"
 
 Complete this checklist after installation and after material platform configuration changes.
 
+## Release integrity
+
+- The installed Helm chart or VM image references exactly match one published [`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml).
+- No component was upgraded independently from the rest of its pinned stack.
+- The deployed image digests were recorded after registries resolved the pinned tags.
+
 ## Public access
 
 - The management console loads through the intended console host.

diff --git a/deploy/vm-compose.mdx b/deploy/vm-compose.mdx
@@ -21,6 +21,13 @@ cp env/vm/.env.example env/vm/.env.prod
 
 Review the production environment file. Keep `TRUST_PROXY=1` when the edge proxy terminates TLS and owns forwarded host headers.
 
+Copy all four exact image references from the `vm-prod-v1` entry in the
+[`stack-versions.yaml` release matrix](https://github.com/acornops/acornops-deployment/blob/main/release/stack-versions.yaml)
+into `MANAGEMENT_CONSOLE_IMAGE`, `CONTROL_PLANE_IMAGE`,
+`EXECUTION_ENGINE_IMAGE`, and `LLM_GATEWAY_IMAGE`. Treat them as one tested
+set; a newer tag in an individual repository does not make it part of the
+supported VM stack.
+
 ## Start the platform
 
 ```bash
@@ -31,7 +38,7 @@ Database initialization runs before the services start. Treat initialization fai
 
 ## Production posture
 
-- Pin the complete supported image matrix.
+- Pin the complete supported image matrix from `stack-versions.yaml`.
 - Keep the API and console behind TLS.
 - Keep internal service endpoints private.
 - Use durable state services and volumes.