Improved documentation

SCOPE.md

@@ -23,7 +23,7 @@ NetKingdom is a self-optimizing security platform for Kubernetes-based IT infras
 - NetKingdom IAM Profile specification (versioned OIDC/PKCE contract)
 - SSO/MFA Platform: Keycloak with LDAP/Entra federation, enterprise identity (NK-WP-0001)
 - Local Identity: file-based user store + minimal OIDC server for bootstrap phase (NK-WP-0002)
-- Security bootstrapping: credential management, SOPS/age integration, KeePassXC/Vault progression
+- Security bootstrapping: credential management, SOPS/age integration, OpenBao runtime secret authority
 - Architectural decisions (DECISIONS.md): identity source, secrets, GitOps, bootstrap user store
 
 ---

docs/platform-identity-security-architecture.md

@@ -66,8 +66,9 @@ Responsibilities:
 - canonical authorization through flex-auth
 - delegated authorization runtime through Topaz first, with other PDPs as
   adapters
+- runtime secret authority through OpenBao
 - audit and explanation records
-- platform service secrets and rotation
+- platform service secrets, dynamic credentials, leases, and rotation
 
 Owned conceptually by `net-kingdom`; deployed through the Railiance stack.
 
@@ -98,6 +99,7 @@ platform itself.
 | `key-cape` | lightweight IAM implementation of the NetKingdom IAM Profile | a general-purpose IAM platform or authorization engine |
 | Keycloak | expanded-mode IAM and optional Keycloak Authorization Services adapter | the canonical model for all platform authorization |
 | privacyIDEA | MFA/token authority, especially in lightweight/key-cape mode | a policy decision point for application resources |
+| OpenBao | runtime platform secrets service, dynamic credential broker, lease/revocation point, and audit source for secret access | the bootstrap root of trust or an application-specific configuration store |
 | `flex-auth` | authorization control plane, CARING descriptors, policy packages, decision envelopes, audit/explain | an identity provider or backend-specific wrapper |
 | Topaz | first delegated authorization runtime/PDP for flex-auth | the platform control plane or identity provider |
 | Railiance repos | converged infrastructure, cluster, platform services, enablement, and app deployment | the source of security policy semantics |
@@ -156,6 +158,45 @@ Protected services enforce decisions locally. flex-auth is the canonical
 policy and decision boundary; delegated PDPs are runtime implementations
 behind it.
 
+## Secret And Credential Path
+
+```text
+Bootstrap SOPS/age material
+        |
+        v
+OpenBao platform secrets service
+  KV v2 platform configuration
+  dynamic database credentials
+  Kubernetes auth / workload identity
+  future object-storage credential brokering
+  audit devices and lease/revocation records
+        |
+        +-- direct OpenBao clients
+        +-- External Secrets Operator / synced Kubernetes Secrets
+        +-- CSI-mounted secrets where appropriate
+        |
+        v
+Platform and tenant workloads
+```
+
+SOPS/age remains the bootstrap and Git-at-rest protection mechanism. It
+can create the initial cluster secrets and emergency recovery bundles, but
+it should not become the long-lived runtime authority for every workload
+secret.
+
+OpenBao is the runtime platform secrets service once the control plane is
+alive. It owns secret leases, revocation, audit, dynamic credentials, and
+workload-facing secret delivery patterns. Workloads should receive scoped
+secrets or short-lived credentials, not platform-root material. Tenant
+administrators may manage tenant-scoped secrets through approved policy
+paths; they must not gain access to OpenBao root tokens, unseal keys,
+platform mounts, or global secret engine configuration.
+
+OpenBao does not replace identity or authorization. NetKingdom IAM
+identifies actors and workloads; flex-auth decides whether a credential
+or secret request is allowed; OpenBao stores, issues, audits, and revokes
+the resulting secret material.
+
 ## Recursive Trust Rule
 
 Normal tenant administration must never be sufficient to alter the
@@ -173,6 +214,8 @@ Examples of platform-root actions:
 - changing global MFA requirements
 - activating authorization policy that governs platform administration
 - changing flex-auth/Topaz policy import pipelines
+- changing OpenBao root tokens, unseal policy, platform mounts, or global
+  auth methods
 - changing audit retention or tamper-evidence settings
 
 ## Tenant Model
@@ -202,14 +245,17 @@ Production setup should move through explicit trust states:
 
 1. **Bare host trust** - provisioned and verified by Railiance infra.
 2. **Cluster trust** - Kubernetes runtime exists and is verified.
-3. **Secret trust** - age/SOPS and emergency bundles are established.
+3. **Bootstrap secret trust** - age/SOPS and emergency bundles are
+   established.
 4. **Bootstrap identity trust** - local/bootstrap identity can operate
    enough to install full identity services.
-5. **Runtime identity trust** - key-cape or Keycloak becomes the normal
+5. **Runtime secret trust** - OpenBao is deployed, initialized, unsealed,
+   audited, backed up, and ready to issue scoped secrets.
+6. **Runtime identity trust** - key-cape or Keycloak becomes the normal
    IAM Profile issuer.
-6. **Runtime authorization trust** - flex-auth and Topaz are initialized
+7. **Runtime authorization trust** - flex-auth and Topaz are initialized
    with platform and tenant policies.
-7. **Tenant onboarding trust** - Coulomb and later tenants register
+8. **Tenant onboarding trust** - Coulomb and later tenants register
    resources and receive scoped authority.
 
 Each transition needs a verification check and a rollback/recovery path.
@@ -226,7 +272,7 @@ railiance-cluster
   Kubernetes, ingress, cert-manager, network policy
 
 railiance-platform
-  PostgreSQL, object storage, secret management
+  OpenBao, PostgreSQL, object storage, platform service secret delivery
   key-cape or Keycloak
   privacyIDEA where used
   flex-auth
@@ -262,8 +308,12 @@ than bypassing the Railiance stack boundaries.
 ## Open Questions
 
 - Where is the durable audit log stored for platform-root decisions?
+- Where are OpenBao audit logs durably shipped, and how are they included
+  in tamper-evidence and restore drills?
 - Which actions require dual control or human confirmation?
 - How is break-glass use recorded when normal identity is unavailable?
+- Which workloads consume OpenBao directly, via External Secrets Operator,
+  or via CSI-mounted secrets?
 - Which tenant metadata is required before a service can register
   resources with flex-auth?
 - When does the platform switch from key-cape lightweight mode to