@kitsy/cnos-docs 1.10.0 → 1.11.1

package/docs/api/runtime.mdx

@@ -37,6 +37,8 @@ The runtime currently exposes:
 - `cnos.log(message)`
 - `cnos.loadProjection(path)`
 - `cnos.registerRuntimeProvider(namespace, provider)`
+- `cnos.registerSecretVaultProvider(factory)`
+- `cnos.registerSecretVaultProviders(factories)`
 - `cnos.refreshSecrets()`
 - `cnos.refreshSecret(key)`
 
@@ -111,6 +113,20 @@ cnos.registerRuntimeProvider('request', (key) => {
 
 That lets server-side derived values depend on live request, session, or app-framework context without adding a second config layer.
 
+## Secret Vault Providers
+
+Vault selection is declared in `.cnos/cnos.yml`; runtime code only declares which provider implementations were compiled into the bundle.
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+Provider packages and batteries-included wrappers should register capabilities before `ready()`. CNOS does not dynamically load provider packages from manifest config.
+
 ## Typed values
 
 CNOS values are not limited to strings. If the underlying config stores numbers, booleans, arrays, or objects, runtime reads return those values as-is.

package/docs/cli/spec.mdx

@@ -1,75 +1,75 @@
----
-title: cnos spec
-description: Author and inspect CNOS config specs stored under schema.
----
-
-# cnos spec
-
-`cnos spec` manages manifest-global config specification entries stored under `schema:` in `.cnos/cnos.yml`.
-
-Use `cnos define`, `cnos value set`, and `cnos secret set` for concrete config values and secret refs.
-
-## Commands
-
-```bash
-cnos spec list
-cnos spec show value.server.port
-cnos spec set value.server.port --type number --required --summary "HTTP server port"
-cnos spec delete value.legacy.flag
-cnos spec doctor
-```
-
-## list
-
-```bash
-cnos spec list
-cnos spec list --prefix value.server.
-```
-
-## show
-
-```bash
-cnos spec show value.server.port
-cnos spec show value.server.port --json
-```
-
-## set
-
-`cnos spec set` supports two modes:
-
-- Non-interactive: pass one or more field flags.
-- Interactive: no field flags in a TTY.
-
-Examples:
-
-```bash
-cnos spec set value.server.port --type number --required --summary "HTTP server port"
-cnos spec set value.app.stage --enum '["local","stage","prod"]'
-cnos spec set value.legacy.flag --clear-deprecated
-```
-
-Field flags use JSON-first parsing for `--default`, `--example`, and `--enum`.
-
-For `secret.*` keys, `--default`, `--example`, and `--enum` are rejected to avoid plaintext secret material in the manifest.
-
-## delete
-
-```bash
-cnos spec delete value.legacy.flag
-cnos spec remove value.legacy.flag --json
-```
-
-## doctor
-
-```bash
-cnos spec doctor
-cnos spec doctor --json
-cnos spec doctor --fill-missing
-cnos spec doctor --review-all
-```
-
-`--fill-missing` and `--review-all` are interactive write modes. In Phases 1-3 they:
-
-- require a TTY,
-- require a writable local root (remote roots are read-only),
-- reject `--json`.
+---
+title: cnos spec
+description: Author and inspect CNOS config specs stored under schema.
+---
+
+# cnos spec
+
+`cnos spec` manages manifest-global config specification entries stored under `schema:` in `.cnos/cnos.yml`.
+
+Use `cnos define`, `cnos value set`, and `cnos secret set` for concrete config values and secret refs.
+
+## Commands
+
+```bash
+cnos spec list
+cnos spec show value.server.port
+cnos spec set value.server.port --type number --required --summary "HTTP server port"
+cnos spec delete value.legacy.flag
+cnos spec doctor
+```
+
+## list
+
+```bash
+cnos spec list
+cnos spec list --prefix value.server.
+```
+
+## show
+
+```bash
+cnos spec show value.server.port
+cnos spec show value.server.port --json
+```
+
+## set
+
+`cnos spec set` supports two modes:
+
+- Non-interactive: pass one or more field flags.
+- Interactive: no field flags in a TTY.
+
+Examples:
+
+```bash
+cnos spec set value.server.port --type number --required --summary "HTTP server port"
+cnos spec set value.app.stage --enum '["local","stage","prod"]'
+cnos spec set value.legacy.flag --clear-deprecated
+```
+
+Field flags use JSON-first parsing for `--default`, `--example`, and `--enum`.
+
+For `secret.*` keys, `--default`, `--example`, and `--enum` are rejected to avoid plaintext secret material in the manifest.
+
+## delete
+
+```bash
+cnos spec delete value.legacy.flag
+cnos spec remove value.legacy.flag --json
+```
+
+## doctor
+
+```bash
+cnos spec doctor
+cnos spec doctor --json
+cnos spec doctor --fill-missing
+cnos spec doctor --review-all
+```
+
+`--fill-missing` and `--review-all` are interactive write modes. They currently:
+
+- require a TTY,
+- require a writable local root (remote roots are read-only),
+- reject `--json`.

package/docs/guides/go-runtime.mdx

@@ -0,0 +1,206 @@
+---
+title: Go Runtime
+description: Use CNOS directly from Go services through projections, native .cnos resolution, and Git-backed remote roots.
+---
+
+# Go Runtime
+
+CNOS now ships a first-party Go runtime client in [`packages/go`](https://github.com/kitsyai/cnos/tree/main/packages/go).
+
+The Go client reads the same runtime bootstrap contracts that the Node runtime already understands:
+
+- `__CNOS_GRAPH__`
+- `__CNOS_PROJECTION__`
+- explicit `.cnos-server.json`
+- autodiscovered `.cnos-server.json` next to `.cnosrc.yml`
+
+That means a Go service can consume CNOS values and secrets directly without dropping back to `cnos build env -> .env`.
+
+When no projection is present, the Go runtime now falls back to native authoring-time resolution from `.cnos/` or `cnos/`. That path understands:
+
+- `.cnosrc.yml` anchor discovery
+- `git+https://...#ref` and `git+ssh://...#ref` remote roots
+- `.cnos-workspace.yml`
+- workspace inheritance and optional global roots
+- profile activation and inheritance
+- filesystem values and secrets
+- dotenv layers
+- process env mappings
+- public promotion
+- runtime-derived values
+- manifest vault mappings for environment and local vault secrets
+
+## Build the projection
+
+For deployment or local packaging:
+
+```bash
+cnos build server --profile prod --to .cnos-server.json
+```
+
+For process bootstrap during development:
+
+```bash
+cnos run -- ./your-go-service
+```
+
+## Import the runtime
+
+Current module path:
+
+```go
+import cnos "github.com/kitsyai/cnos/packages/go"
+```
+
+Then load the runtime:
+
+```go
+runtime, err := cnos.Load(cnos.Options{})
+if err != nil {
+	panic(err)
+}
+```
+
+Or use the package-level singleton for the closest Node-style runtime flow:
+
+```go
+if err := cnos.Ready(); err != nil {
+	panic(err)
+}
+
+value, ok, err := cnos.Read("value.app.version")
+if err != nil {
+	panic(err)
+}
+_ = value
+_ = ok
+```
+
+`Load()` checks sources in this order:
+
+1. `ProjectionData` passed through `LoadProjection`
+2. explicit path from `cnos.Options{ProjectionPath: ...}`
+3. `__CNOS_GRAPH__`
+4. `__CNOS_PROJECTION__`
+5. `.cnos-server.json` in the current working directory
+6. `.cnos-server.json` beside a discovered `.cnosrc.yml`
+7. native authoring-time resolution from `cnos.Options{Root: ...}` or a discovered `.cnosrc.yml`
+
+If the process already has `__CNOS_GRAPH__`, `__CNOS_PROJECTION__`, or a nearby `.cnos-server.json`, the package singleton bootstraps automatically and `Ready()` is optional.
+
+## Read values and secrets
+
+```go
+port, _, err := runtime.Value("server.port")
+if err != nil {
+	panic(err)
+}
+
+token, _, err := runtime.Secret("app.token")
+if err != nil {
+	panic(err)
+}
+```
+
+The Go runtime reconstructs the same logical keys used in CNOS:
+
+- `value.*`
+- `secret.*`
+- `public.*`
+- `meta.profile`
+- `meta.workspace`
+- `meta.cnos_version`
+
+Inspect/provenance is also available directly in Go:
+
+```go
+inspect, err := runtime.Inspect("value.app.version")
+if err != nil {
+	panic(err)
+}
+_ = inspect
+```
+
+## Derived values stay live
+
+Runtime-dependent derived formulas in the server projection are evaluated at read time, not frozen during build.
+
+Example CNOS config:
+
+```yaml
+app:
+  origin:
+    $derive: "https://${value.app.host}:${process.env.PORT}"
+```
+
+In Go:
+
+```go
+origin, _, err := runtime.Value("app.origin")
+if err != nil {
+	panic(err)
+}
+```
+
+If `PORT` changes in the host process, the next read re-evaluates the formula.
+
+## Custom runtime namespaces
+
+Custom server-only runtime namespaces work the same way as in Node. Register a provider for any namespace that was declared in the CNOS manifest and carried into the server projection.
+
+```go
+host := ""
+
+if err := runtime.RegisterRuntimeProvider("request", func(path string) any {
+	if path == "headers.host" && host != "" {
+		return host
+	}
+	return nil
+}); err != nil {
+	panic(err)
+}
+```
+
+The built-in `process.*` namespace covers `env.*`, `cwd`, `platform`, `arch`, and `pid`. `process.node.version` is still Node-only.
+
+## Secret hydration
+
+The Go runtime supports built-in secret-ref providers used by server projections:
+
+- `environment`
+- `github-secrets`
+- `local`
+
+Remote providers such as GCP Secret Manager, AWS Secrets Manager, HashiCorp Vault, and Azure Key Vault are compiled into the Go binary by registering provider factories:
+
+```go
+runtime, err := cnos.Load(cnos.Options{
+	SecretVaultProviders: []cnos.SecretVaultProviderFactory{gcpFactory},
+})
+```
+
+The manifest remains the configuration source for which named vault uses which provider. Go does not dynamically load provider packages from `.cnos.yml`.
+
+For local vaults, the Go client reuses the same CNOS auth conventions:
+
+- `__CNOS_VAULT_KEY_<VAULT>__`
+- `~/.cnos/secrets/sessions/<vault>.json`
+- `keychain:cnos/<vault>`
+- `CNOS_SECRET_PASSPHRASE_<VAULT>`
+- `CNOS_SECRET_PASSPHRASE`
+
+It also understands the encrypted secret payload generated by:
+
+```bash
+cnos run --auth -- ./your-go-service
+```
+
+That lets a Go process start with already-resolved secret values even when it is not re-authenticating to the local vault itself.
+
+## Current limits
+
+The remaining Go-specific gaps are:
+
+- browser/public runtime behavior
+
+Use it as the server-runtime companion to `cnos build server`, `cnos run`, local `.cnos/` authoring flows, and Git-backed shared config repos.

package/docs/guides/secrets.mdx

@@ -46,3 +46,21 @@ By default:
 - repo files store only refs
 - local secret material stays outside the repo
 - reads are masked unless `--reveal` is explicitly requested
+
+Remote provider packages are compiled into the runtime and selected through `vaults.<name>.provider` in the manifest. CNOS does not dynamically load provider packages from config.
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+See [Vault Providers](/guides/vault-providers) for the provider package contract, conformance testkit, and security rules.

package/docs/guides/vault-providers.mdx

@@ -0,0 +1,263 @@
+---
+title: Vault Provider Packages
+description: Build and test compiled-in CNOS secret vault providers.
+---
+
+# Vault Provider Packages
+
+Remote vault providers are compiled into the application runtime. CNOS never loads provider packages dynamically from `.cnos/cnos.yml`.
+
+## Package names
+
+Official providers use this package shape:
+
+- `@kitsy/cnos-vault-gcp`
+- `@kitsy/cnos-vault-aws`
+- `@kitsy/cnos-vault-hashicorp`
+- `@kitsy/cnos-vault-azure`
+- `@kitsy/cnos-vault-firebase`
+
+Each package must export a factory named `create<Vendor>VaultProvider()`. The factory returns a `SecretVaultProviderFactory` whose `provider` field exactly matches the manifest provider name.
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+## Manifest contract
+
+Provider selection belongs in config:
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+Secret refs should normally inherit from the named vault:
+
+```yaml
+db:
+  password:
+    vault: prod-gcp
+    ref: db.password
+```
+
+Do not set a different `provider` on a ref that also names a vault. CNOS rejects provider/vault mismatches so Node, Go, and projections all agree.
+
+## Runtime contract
+
+Every provider must implement the `SecretVaultProvider` interface:
+
+- `authenticate(authConfig)` resolves credentials supplied by CNOS.
+- `batchGet(refs)` is the startup and refresh path.
+- `get(ref)` exists for compatibility and narrow single-ref use, but provider tests must prove startup and `refreshSecrets()` do not call it.
+- `set(ref, value)` and `delete(ref)` may be writable or may reject. Declare the expected capability in testkit setup.
+- `list()` returns known refs when the backing platform supports listing.
+- `healthCheck()` is optional for remote providers.
+
+Startup hydration and full refresh are batch-only. Individual application reads use the CNOS in-memory cache and must not perform remote I/O.
+
+## Auth and projection safety
+
+Provider auth should prefer platform identity:
+
+- GCP: Application Default Credentials or attached service account.
+- AWS: IAM role or standard AWS credential chain.
+- Azure: managed identity or default credential chain.
+- HashiCorp Vault: token sources such as `env:`, `file:`, or keychain.
+- Firebase: direct provider support plus explicit `environment` fallback for injected secrets.
+
+Server projections may include safe metadata such as `projectId`, `region`, `endpoint`, `address`, `namespace`, or `tenant`. They must not include raw secrets, private keys, bearer tokens, credential blobs, or client secrets. CNOS sanitizes projected `auth.config`, but provider authors should design manifest config so credential material is referenced by source (`env:NAME`, `file:PATH`, `keychain:NAME`) rather than stored inline.
+
+## Conformance tests
+
+Provider packages should use `@kitsy/cnos-vault-testkit`:
+
+```ts
+import {
+  defineSecretVaultProviderConformanceSuite,
+  defineSecretVaultRuntimeConformanceSuite,
+} from '@kitsy/cnos-vault-testkit';
+
+defineSecretVaultProviderConformanceSuite('gcp-secret-manager', () => ({
+  factory: createGcpSecretManagerVaultProvider(),
+  definition,
+  auth,
+  refs,
+}));
+
+defineSecretVaultRuntimeConformanceSuite('gcp-secret-manager', () => ({
+  factory: createGcpSecretManagerVaultProvider(),
+  vaultId: 'prod-gcp',
+  definition,
+  refs,
+  processEnv,
+}));
+```
+
+The shared suite verifies provider auth, batch reads, missing refs, runtime startup hydration, projection bootstrap, refresh batching, safe projection metadata, and explicit environment fallback behavior.
+
+## Google Secret Manager
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let the official Google SDK resolve Application Default Credentials or an attached service account:
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    mapping:
+      db-password: db.password
+```
+
+CNOS resolves `secret.db.password` from `projects/acme-prod/secrets/db-password/versions/latest`. Set `auth.config.version` to read a pinned version, or `auth.config.location` for regional Secret Manager resources. A full ref such as `projects/acme-prod/secrets/db-password/versions/5` is also accepted.
+
+## Firebase Secrets
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createFirebaseSecretsVaultProvider } from '@kitsy/cnos-vault-firebase';
+
+cnos.registerSecretVaultProvider(createFirebaseSecretsVaultProvider());
+await cnos.ready();
+```
+
+Firebase Secrets are backed by Google Secret Manager. Use `auth.method: iam` and let the official Google SDK resolve Application Default Credentials or an attached service account:
+
+```yaml
+vaults:
+  prod-firebase:
+    provider: firebase-secrets
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    mapping:
+      DB_PASSWORD: db.password
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+CNOS resolves `secret.db.password` from `projects/acme-prod/secrets/DB_PASSWORD/versions/latest`. Set `auth.config.version` to read a pinned version, or `auth.config.location` for regional Secret Manager resources. A full ref such as `projects/acme-prod/secrets/DB_PASSWORD/versions/5` is also accepted.
+
+Firebase and Google Cloud Functions can inject secrets as environment variables. Model that as an explicit `environment` fallback in the vault definition; CNOS never silently falls back to env when a remote provider fails.
+
+## AWS Secrets Manager
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createAwsSecretsManagerVaultProvider } from '@kitsy/cnos-vault-aws';
+
+cnos.registerSecretVaultProvider(createAwsSecretsManagerVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let AWS SDK v3 resolve credentials from IAM roles, web identity, environment credentials, or the standard AWS provider chain:
+
+```yaml
+vaults:
+  prod-aws:
+    provider: aws-secrets-manager
+    auth:
+      method: iam
+      config:
+        region: us-east-1
+    mapping:
+      db/password: db.password
+```
+
+CNOS resolves `secret.db.password` from the AWS secret ID `db/password`. Set `auth.config.versionId` or `auth.config.versionStage` for pinned or staged reads. Secret refs may also be direct AWS secret names or ARNs when no mapping is required.
+
+## HashiCorp Vault
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createHashicorpVaultProvider } from '@kitsy/cnos-vault-hashicorp';
+
+cnos.registerSecretVaultProvider(createHashicorpVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: token` and source the Vault token from env, file, or keychain. CNOS resolves the token and passes it to Vault as `X-Vault-Token`:
+
+```yaml
+vaults:
+  prod-vault:
+    provider: hashicorp-vault
+    auth:
+      method: token
+      token:
+        from:
+          - env:VAULT_TOKEN
+      config:
+        address: https://vault.example.com
+        mount: secret
+        namespace: admin/team-a
+        version: 2
+    mapping:
+      db/password#password: db.password
+```
+
+For KV v2, CNOS reads `secret.data.db/password` and extracts the `password` field. Use `path#field` refs or mapping keys to select fields from a Vault secret object. Set `auth.config.version: 1` for KV v1 mounts, and `auth.config.path` to apply a shared path prefix.
+
+## Azure Key Vault
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createAzureKeyVaultProvider } from '@kitsy/cnos-vault-azure';
+
+cnos.registerSecretVaultProvider(createAzureKeyVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let Azure Identity resolve credentials from managed identity, workload identity, environment credentials, or the standard `DefaultAzureCredential` chain:
+
+```yaml
+vaults:
+  prod-azure:
+    provider: azure-key-vault
+    auth:
+      method: iam
+      config:
+        vaultUrl: https://acme-prod.vault.azure.net
+        tenantId: 00000000-0000-0000-0000-000000000000
+    mapping:
+      db-password: db.password
+```
+
+CNOS resolves `secret.db.password` from the Azure secret name `db-password`. Set `auth.config.version` for a pinned version, or use a full Azure secret URL such as `https://acme-prod.vault.azure.net/secrets/db-password/version-id` as the ref when no mapping is required.

package/docs/reference/manifest.mdx

@@ -18,3 +18,23 @@ Key sections:
 - `writePolicy`
 
 Use the main repo spec for the exhaustive schema until this reference grows into the full field-by-field version.
+
+## Vaults
+
+`vaults` declare named secret backends. Secret refs can name a vault and omit `provider`; CNOS resolves the provider from the vault definition.
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: my-prod-project
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+Fallbacks are explicit and ordered. CNOS never silently falls back to environment variables unless a fallback provider is declared.

package/manifest.yml

@@ -1,149 +1,153 @@
-product: cnos
-title: CNOS Documentation
-tagline: Configuration orchestration for apps, monorepos, and deployment pipelines
-version: "1.9.2"
-
-sidebar:
-  - group: Getting Started
-    items:
-      - path: getting-started/index
-        label: Overview
-      - path: getting-started/installation
-        label: Installation
-      - path: getting-started/quick-start
-        label: Quick Start
-      - path: getting-started/your-first-project
-        label: Your First Project
-
-  - group: Guides
-    items:
-      - path: guides/backend
-        label: Backend Projects
-      - path: guides/frontend-vite
-        label: Frontend with Vite
-      - path: guides/frontend-webpack
-        label: Frontend with Webpack
-      - path: guides/frontend-next
-        label: Frontend with Next.js
-      - path: guides/ssr
-        label: SSR Projects
-      - path: guides/ci-cd
-        label: CI/CD Pipelines
-      - path: guides/containers-and-actions
-        label: Containers and Actions
-      - path: guides/workspaces
-        label: Workspaces and Monorepos
-      - path: guides/remote-roots
-        label: Remote Roots
-      - path: guides/profiles
-        label: Profiles and Environments
-      - path: guides/derived-values
-        label: Derived Values
-      - path: guides/secrets
-        label: Secrets and Vaults
-      - path: guides/migration
-        label: Migrating from .env
-      - path: guides/generated-env-files
-        label: Generated Env Files
-
-  - group: CLI Reference
-    collapsed: true
-    items:
-      - path: cli/index
-        label: Overview
-      - path: cli/init
-        label: cnos init
-      - path: cli/onboard
-        label: cnos onboard
-      - path: cli/use
-        label: cnos use
-      - path: cli/profile
-        label: cnos profile
-      - path: cli/workspace
-        label: cnos workspace
-      - path: cli/value
-        label: cnos value
-      - path: cli/secret
-        label: cnos secret
-      - path: cli/define
-        label: cnos define
-      - path: cli/spec
-        label: cnos spec
-      - path: cli/list
-        label: cnos list
-      - path: cli/read
-        label: cnos read
-      - path: cli/inspect
-        label: cnos inspect
-      - path: cli/validate
-        label: cnos validate
-      - path: cli/export
-        label: cnos export
-      - path: cli/build
-        label: cnos build env
-      - path: cli/cache
-        label: cnos cache
-      - path: cli/dev
-        label: cnos dev env
-      - path: cli/run
-        label: cnos run
-      - path: cli/diff
-        label: cnos diff
-      - path: cli/dump
-        label: cnos dump
-      - path: cli/doctor
-        label: cnos doctor
-      - path: cli/ui
-        label: cnos ui
-      - path: cli/promote
-        label: cnos promote
-      - path: cli/vault
-        label: cnos vault
-      - path: cli/codegen
-        label: cnos codegen
-      - path: cli/watch
-        label: cnos watch
-      - path: cli/migrate
-        label: cnos migrate
-      - path: cli/drift
-        label: cnos drift
-      - path: cli/help
-        label: cnos help
-      - path: cli/help-ai
-        label: cnos help-ai
-      - path: cli/version
-        label: cnos version
-
-  - group: API Reference
-    collapsed: true
-    items:
-      - path: api/index
-        label: Overview
-      - path: api/create-cnos
-        label: createCnos()
-      - path: api/runtime
-        label: Singleton Runtime
-      - path: api/browser
-        label: Browser Runtime
-      - path: api/types
-        label: Types
-
-  - group: Reference
-    collapsed: true
-    items:
-      - path: reference/manifest
-        label: Manifest
-      - path: reference/namespaces
-        label: Namespaces
-      - path: reference/resolution
-        label: Resolution
-      - path: reference/security
-        label: Security
-
-  - group: Concepts
-    collapsed: true
-    items:
-      - path: concepts/how-it-works
-        label: How CNOS Works
-      - path: concepts/config-spectrum
-        label: The Config Spectrum
+product: cnos
+title: CNOS Documentation
+tagline: Configuration orchestration for apps, monorepos, and deployment pipelines
+version: "1.9.2"
+
+sidebar:
+  - group: Getting Started
+    items:
+      - path: getting-started/index
+        label: Overview
+      - path: getting-started/installation
+        label: Installation
+      - path: getting-started/quick-start
+        label: Quick Start
+      - path: getting-started/your-first-project
+        label: Your First Project
+
+  - group: Guides
+    items:
+      - path: guides/backend
+        label: Backend Projects
+      - path: guides/go-runtime
+        label: Go Runtime
+      - path: guides/frontend-vite
+        label: Frontend with Vite
+      - path: guides/frontend-webpack
+        label: Frontend with Webpack
+      - path: guides/frontend-next
+        label: Frontend with Next.js
+      - path: guides/ssr
+        label: SSR Projects
+      - path: guides/ci-cd
+        label: CI/CD Pipelines
+      - path: guides/containers-and-actions
+        label: Containers and Actions
+      - path: guides/workspaces
+        label: Workspaces and Monorepos
+      - path: guides/remote-roots
+        label: Remote Roots
+      - path: guides/profiles
+        label: Profiles and Environments
+      - path: guides/derived-values
+        label: Derived Values
+      - path: guides/secrets
+        label: Secrets and Vaults
+      - path: guides/vault-providers
+        label: Vault Providers
+      - path: guides/migration
+        label: Migrating from .env
+      - path: guides/generated-env-files
+        label: Generated Env Files
+
+  - group: CLI Reference
+    collapsed: true
+    items:
+      - path: cli/index
+        label: Overview
+      - path: cli/init
+        label: cnos init
+      - path: cli/onboard
+        label: cnos onboard
+      - path: cli/use
+        label: cnos use
+      - path: cli/profile
+        label: cnos profile
+      - path: cli/workspace
+        label: cnos workspace
+      - path: cli/value
+        label: cnos value
+      - path: cli/secret
+        label: cnos secret
+      - path: cli/define
+        label: cnos define
+      - path: cli/spec
+        label: cnos spec
+      - path: cli/list
+        label: cnos list
+      - path: cli/read
+        label: cnos read
+      - path: cli/inspect
+        label: cnos inspect
+      - path: cli/validate
+        label: cnos validate
+      - path: cli/export
+        label: cnos export
+      - path: cli/build
+        label: cnos build env
+      - path: cli/cache
+        label: cnos cache
+      - path: cli/dev
+        label: cnos dev env
+      - path: cli/run
+        label: cnos run
+      - path: cli/diff
+        label: cnos diff
+      - path: cli/dump
+        label: cnos dump
+      - path: cli/doctor
+        label: cnos doctor
+      - path: cli/ui
+        label: cnos ui
+      - path: cli/promote
+        label: cnos promote
+      - path: cli/vault
+        label: cnos vault
+      - path: cli/codegen
+        label: cnos codegen
+      - path: cli/watch
+        label: cnos watch
+      - path: cli/migrate
+        label: cnos migrate
+      - path: cli/drift
+        label: cnos drift
+      - path: cli/help
+        label: cnos help
+      - path: cli/help-ai
+        label: cnos help-ai
+      - path: cli/version
+        label: cnos version
+
+  - group: API Reference
+    collapsed: true
+    items:
+      - path: api/index
+        label: Overview
+      - path: api/create-cnos
+        label: createCnos()
+      - path: api/runtime
+        label: Singleton Runtime
+      - path: api/browser
+        label: Browser Runtime
+      - path: api/types
+        label: Types
+
+  - group: Reference
+    collapsed: true
+    items:
+      - path: reference/manifest
+        label: Manifest
+      - path: reference/namespaces
+        label: Namespaces
+      - path: reference/resolution
+        label: Resolution
+      - path: reference/security
+        label: Security
+
+  - group: Concepts
+    collapsed: true
+    items:
+      - path: concepts/how-it-works
+        label: How CNOS Works
+      - path: concepts/config-spectrum
+        label: The Config Spectrum

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/cnos-docs",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Source-of-truth CNOS documentation content for Astro Starlight and other static docs consumers.",
   "type": "module",
   "exports": {