feat(providers): store refresh credentials in credential drivers

.agents/skills/openshell-cli/SKILL.md

@@ -180,6 +180,17 @@ openshell provider refresh rotate my-outlook --credential-key MS_GRAPH_ACCESS_TO
 
 Prefer `--secret-material-env KEY[=ENVVAR]` for secret refresh material. `--material KEY=VALUE` is for non-secret material; `--secret-material-key` marks supplied material keys as secret.
 
+The gateway stores secret refresh material through its active credential driver.
+With Vault selected, refresh tokens, client secrets, and private keys live in
+Vault alongside injectable provider credentials; refresh state contains only
+opaque handles. A credential-backend read or write failure makes refresh fail
+closed rather than falling back to inline storage. Before OpenShell 0.1.0, the
+gateway does not migrate legacy inline refresh material or move secrets between
+credential backends. Reconfigure affected grants after upgrading, and remove or
+reconfigure credentials while the original backend remains available before
+changing backends. Do not run mixed gateway versions against the same refresh
+records.
+
 Gateway-managed refresh credentials use an identity-stable workload handle.
 Routine automatic refresh and `provider refresh rotate` update the access token
 behind that handle, so long-running processes do not need to restart. Running

architecture/gateway.md

@@ -317,19 +317,28 @@ default WAL journal mode), which mirror the same sensitive contents.
 
 Persisted state includes sandboxes, providers, provider credential refresh
 state, SSH sessions, policy revisions, settings, inference configuration, and
-deployment records. Provider refresh material is stored as a separate object
-scoped to the provider instance through `objects.scope`; the provider record
-keeps only the current injectable credential values and optional per-credential
-expiry timestamps. A refresh normally mints one credential, but a strategy may
+deployment records. Provider refresh state is stored as a separate object
+scoped to the provider instance through `objects.scope`. Its non-secret
+configuration remains inline, while refresh tokens, client secrets, private
+keys, and other secret source material are stored through the active credential
+driver and represented by opaque handles. The provider record keeps only the
+current injectable credential handles and optional per-credential expiry
+timestamps. A refresh normally mints one credential, but a strategy may
 co-mint several (AWS STS mints the access key, secret key, and session token in
 one call); the refresh state pins the resolved set of env keys it owns so
 collision checks reserve all of them before the first mint. Provider records
 keep inline credential values only for legacy records created before credential
-driver storage. New provider writes keep driver-owned credential handles. When
-no external credential driver is configured, gateways use server-owned encrypted
-database credential storage for defense in depth. Multi-replica deployments can
-use that default with a shared database and shared key-encryption key, or opt
-into an external backend such as Vault or Kubernetes Secrets.
+driver storage. New provider and refresh-material writes keep driver-owned
+credential handles. When no external credential driver is configured, gateways
+use server-owned encrypted database credential storage for defense in depth.
+Multi-replica deployments can use that default with a shared database and
+shared key-encryption key, or opt into an external backend such as Vault or
+Kubernetes Secrets.
+
+Credential handles remain bound to the driver that created them. Before the
+0.1.0 compatibility boundary, gateways do not migrate inline refresh material
+or move handles between credential drivers; operators reconfigure affected
+grants when upgrading or changing backends.
 
 ### Optimistic Concurrency (CAS)