@kitsy/cnos-docs 1.5.1 → 1.6.1

package/docs/api/browser.mdx

@@ -14,3 +14,5 @@ console.log(cnos('public.app.apiBaseUrl'));
 Only promoted browser-safe values are available here.
 
 Framework integrations such as `@kitsy/cnos-vite`, `@kitsy/cnos-next`, and `@kitsy/cnos-webpack` are responsible for embedding that browser payload during the build.
+
+The browser runtime does not fetch config over the network. It reads from data already embedded into the bundle/runtime globals by the framework integration, so it follows the same bundle and service-worker caching behavior as the rest of your frontend assets.

package/docs/api/runtime.mdx

@@ -32,8 +32,12 @@ The runtime currently exposes:
 - `cnos.toNamespace(namespace)`
 - `cnos.toEnv()`
 - `cnos.toPublicEnv()`
+- `cnos.toServerProjection()`
 - `cnos.format(message)`
 - `cnos.log(message)`
+- `cnos.loadProjection(path)`
+- `cnos.refreshSecrets()`
+- `cnos.refreshSecret(key)`
 
 Example:
 
@@ -54,6 +58,15 @@ cnos.log('Starting server at ${value.server.port}');
 
 `cnos.format(...)` and `cnos.log(...)` interpolate `${logical.key}` placeholders through the active runtime. Missing keys are left unchanged.
 
+For server packaging, the runtime can also bootstrap from a projection artifact:
+
+```ts
+import cnos from '@kitsy/cnos';
+
+await cnos.loadProjection('./.cnos-server.json');
+await cnos.ready();
+```
+
 ## 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/build.mdx

@@ -1,23 +1,26 @@
 ---
-title: cnos build env
-description: Build flat env-file artifacts from CNOS.
+title: cnos build
+description: Build derived CNOS projection artifacts for server, browser, env, and public surfaces.
 ---
 
-# cnos build env
+# cnos build
 
-Use `build env` when a repo still expects `.env.*` files but CNOS is the source of truth.
+Use `build` when a repo needs a deterministic artifact derived from CNOS.
 
 ```bash
+cnos build server --to .cnos-server.json
+cnos build browser --to .cnos-browser.json
 cnos build env --profile local --to .env.local
 cnos build env --profile stage --to .env.stage
-cnos build env --public --framework vite --to .env.production
+cnos build public --framework vite --to .env.production
+cnos build env --profile local-domain --format docker-env --to .docker/runtime/current.env
 ```
 
-`build env`:
+Targets:
 
-- resolves the selected CNOS workspace/profile
-- renders a deterministic flat `KEY=VALUE` file
-- writes the target path
-- does not start a child process
+- `build server` writes a server runtime projection with resolved values plus secret refs
+- `build browser` writes a public-only browser projection
+- `build env` writes explicit env mappings in formats like `dotenv`, `shell`, `json`, `yaml`, `docker-env`, or `toml`
+- `build public` writes promoted public env with optional framework prefixes like Vite and Next
 
-This is the preferred bridge for build systems and CI pipelines that still consume env files.
+All build artifacts are derived output. `.cnos` remains the source of truth.

package/docs/getting-started/quick-start.mdx

@@ -45,3 +45,10 @@ For frontend builds:
 - Vite: `@kitsy/cnos-vite`
 - Webpack/static bundles: `@kitsy/cnos-webpack`
 - Next.js: `@kitsy/cnos-next`
+
+For webpack/static bundles, build-time settings can come from CNOS too:
+
+```bash
+cnos set value dev.server.port 8800
+npm run dev
+```

package/docs/guides/backend.mdx

@@ -10,6 +10,15 @@ Backend projects usually use one of two patterns:
 - `cnos run -- <command>` for zero-code-change adoption
 - `import cnos from '@kitsy/cnos'` for direct runtime reads
 
+For an existing Express or Node service that already uses `.env`, start with the env bridge:
+
+```bash
+cnos build env --profile local --to .env.local
+cnos build env --profile stage --to .env.stage
+```
+
+Then keep your current `dotenv` setup while moving runtime reads to CNOS.
+
 Example:
 
 ```ts
@@ -24,6 +33,12 @@ const token = cnos.secret('app.token');
 Env export bridge:
 
 ```bash
-cnos export env --to .env.local
-cnos export env --profile stage --to .env.stage
+cnos build env --to .env.local
+cnos build env --profile stage --to .env.stage
+```
+
+Projection-first packaging:
+
+```bash
+cnos build server --profile prod --to .cnos-server.json
 ```

package/docs/guides/ci-cd.mdx

@@ -8,9 +8,10 @@ description: Use CNOS in build and deploy pipelines without committing generated
 Common patterns:
 
 ```bash
-cnos export env --profile stage --to .env.stage
-cnos export env --public --framework vite --profile stage --to .env.stage
+cnos build env --profile stage --to .env.stage
+cnos build public --framework vite --profile stage --to .env.stage
 cnos run --profile stage -- pnpm build
+cnos build server --profile prod --to dist/.cnos-server.json
 ```
 
 For CI-backed vaults:
@@ -19,3 +20,18 @@ For CI-backed vaults:
 cnos vault create github-ci --provider github-secrets --no-passphrase
 cnos secret set app.token APP_TOKEN --vault github-ci
 ```
+
+GitHub Actions example:
+
+```yaml
+- name: Install deps
+  run: pnpm install --frozen-lockfile
+
+- name: Build CNOS env
+  run: cnos build env --profile stage --to .env.stage
+
+- name: Build app
+  run: pnpm build
+```
+
+Use `cnos run` when you do not need an intermediate env file. Use `cnos build env` or `cnos build public` when the build tool or deploy step expects a file artifact.

package/docs/guides/containers-and-actions.mdx

@@ -0,0 +1,136 @@
+---
+title: Containers, Kubernetes, and GitHub Actions
+description: Use CNOS-generated artifacts in Docker, Docker Compose, Kubernetes, and GitHub Actions without making .env files the source of truth.
+---
+
+# Containers, Kubernetes, and GitHub Actions
+
+CNOS should stay the source of truth. Containers and pipelines should consume derived artifacts.
+
+Use these patterns:
+
+- `cnos build env` when the runtime expects flat env vars
+- `cnos build server` when a server runtime should consume a CNOS projection artifact
+- `cnos run` when a child process should get CNOS directly at launch time
+
+## Docker
+
+Generate a Docker-friendly env file:
+
+```bash
+cnos build env --profile local-domain --format docker-env --to .docker/runtime/current.env
+```
+
+That file is a derived artifact. Keep it gitignored.
+
+For a production-style local preview flow:
+
+```bash
+pnpm build:local-domain:all
+cnos build env --profile local-domain --format docker-env --to .docker/runtime/current.env
+docker compose up --build
+```
+
+Use this when:
+- your image or emulator runtime expects env vars
+- you want one fixed runtime env file per profile
+- the build already consumed the same CNOS profile
+
+## Docker Compose
+
+Recommended compose pattern:
+
+```yaml
+services:
+  app:
+    env_file:
+      - ./.docker/runtime/current.env
+```
+
+This keeps runtime env injection explicit and lets the same CNOS profile drive:
+- the build step
+- the container runtime
+- local emulators
+
+For browser builds behind nginx or another proxy:
+- build the app first with `cnos run --profile <name> -- pnpm build`
+- then feed compose/runtime with `cnos build env --format docker-env`
+
+## Kubernetes
+
+Use CNOS to render the env payload before applying manifests:
+
+```bash
+cnos build env --profile stage --format yaml --to k8s/generated/app-config.yaml
+```
+
+Or generate a flat env file and convert it into a ConfigMap or Secret with your existing tooling:
+
+```bash
+cnos build env --profile stage --format dotenv --to .artifacts/stage.env
+kubectl create configmap app-config --from-env-file=.artifacts/stage.env --dry-run=client -o yaml
+```
+
+Rules:
+- do not make Kubernetes manifests the source of truth for application config
+- do not embed decrypted CNOS secret values into build artifacts by default
+- prefer runtime secret providers or platform-native secrets for secret plaintext
+
+## GitHub Actions
+
+Two good patterns exist.
+
+### 1. Build with direct CNOS injection
+
+```yaml
+- name: Install deps
+  run: pnpm install --frozen-lockfile
+
+- name: Build with CNOS
+  run: cnos run --profile stage -- pnpm build
+```
+
+### 2. Materialize an env artifact first
+
+```yaml
+- name: Build CNOS env file
+  run: cnos build env --profile stage --to .env.stage
+
+- name: Build app
+  run: pnpm build
+```
+
+For browser-only frameworks:
+
+```yaml
+- name: Build public env for Vite
+  run: cnos build public --framework vite --profile stage --to .env.stage
+```
+
+For Next:
+
+```yaml
+- name: Build public env for Next
+  run: cnos build public --framework next --profile prod --to .env.production
+```
+
+For server packaging:
+
+```yaml
+- name: Build server projection
+  run: cnos build server --profile prod --to dist/.cnos-server.json
+```
+
+## Secret handling
+
+Keep this split clear:
+
+- non-secret config can become a build or runtime artifact
+- decrypted secret plaintext should not become a build artifact by default
+
+Use:
+- CNOS vault refs
+- platform env injection
+- runtime secret hydration
+
+Do not rely on generated env files for secret rotation-sensitive server secrets unless you deliberately accept that tradeoff.

package/docs/guides/frontend-next.mdx

@@ -5,6 +5,12 @@ description: Use CNOS public projection with Next.js builds and browser-safe run
 
 # Frontend with Next.js
 
+If the app already depends on `NEXT_PUBLIC_*`, keep that contract while CNOS becomes the source of truth:
+
+```bash
+cnos build public --framework next --profile prod --to .env.production
+```
+
 ```ts
 import { withCnosNext } from '@kitsy/cnos-next';
 
@@ -12,3 +18,10 @@ export default withCnosNext({});
 ```
 
 Browser-safe values remain under `public.promote` and are exposed as `NEXT_PUBLIC_*` plus browser-runtime data for `@kitsy/cnos/browser`.
+
+Migration path:
+
+1. keep `NEXT_PUBLIC_*` via generated env or Next env injection
+2. add `withCnosNext()`
+3. move browser-safe reads to `@kitsy/cnos/browser`
+4. move server-only reads to `@kitsy/cnos` or `@kitsy/cnos/configure`

package/docs/guides/frontend-vite.mdx

@@ -5,6 +5,13 @@ description: Project browser-safe CNOS values into Vite and use the browser runt
 
 # Frontend with Vite
 
+If your app already uses `VITE_*`, keep that shape first and let CNOS generate it.
+
+```bash
+cnos build public --framework vite --profile local --to .env.local
+cnos dev env --public --framework vite --profile local --to .env.local -- pnpm dev
+```
+
 Promote browser-safe values:
 
 ```yaml
@@ -32,3 +39,10 @@ import cnos from '@kitsy/cnos/browser';
 console.log(cnos('public.app.apiBaseUrl'));
 console.log(import.meta.env.VITE_APP_API_BASE_URL);
 ```
+
+Migration path:
+
+1. keep `VITE_*` working through generated env files
+2. add `createCnosVitePlugin()`
+3. move browser reads to `@kitsy/cnos/browser`
+4. stop treating handwritten `.env.local` as the source of truth

package/docs/guides/frontend-webpack.mdx

@@ -7,6 +7,26 @@ description: Use CNOS public projection with webpack builds, webpack-dev-server,
 
 CNOS integrates with webpack through `@kitsy/cnos-webpack`. This covers the common static-bundle case where webpack produces a browser build that is then deployed as static assets.
 
+## Highlight: change webpack dev-server config from CNOS
+
+Once webpack reads build-time config through `createCnos()`, changing a setting such as the dev-server port is just a config write:
+
+```powershell
+cnos set value dev.server.port 8800
+npm run dev
+```
+
+Typical result:
+
+```text
+set value.dev.server.port in .cnos\values\dev.yml
+Cnos value.dev.server.port: 8800
+[webpack-dev-server] Project is running at:
+[webpack-dev-server] Loopback: http://localhost:8800/
+```
+
+This is the main benefit of the CNOS webpack path: you change config in `.cnos`, not scattered build scripts or ad hoc env files.
+
 Promote browser-safe values:
 
 ```yaml
@@ -88,6 +108,18 @@ The webpack plugin:
 - keeps server-only `value.*` and `secret.*` out of the browser bundle
 - uses no prefix by default for webpack public env unless you configure `public.frameworks.webpack` or pass `prefix`
 
+## Bundle and cache behavior
+
+CNOS does not add a runtime fetch layer to the browser bundle.
+
+- `@kitsy/cnos-webpack` resolves public config at build time
+- browser-safe values are embedded into the existing webpack bundle through `DefinePlugin` and `globalThis.__CNOS_BROWSER_DATA__`
+- `@kitsy/cnos/browser` is a small reader over that embedded payload
+- if your app does not import `@kitsy/cnos/browser`, webpack can leave it out of the browser bundle
+- if your app does import `@kitsy/cnos/browser`, it is bundled like any other app dependency and follows your existing webpack and service-worker caching strategy
+
+So if your site already uses `sw.js` for offline behavior, CNOS does not disable or bypass that. CNOS becomes part of the same built assets your service worker already caches.
+
 If you need build-time server config such as `devServer.port`, read it in the webpack config through `createCnos()` so dev and production builds use the same CNOS source of truth.
 
 ## Plugin order

package/docs/guides/generated-env-files.mdx

@@ -15,6 +15,7 @@ Use generated env files as a **bridge**, not as the source of truth.
 cnos build env --profile local --to .env.local
 cnos build env --profile stage --to .env.stage
 cnos build env --profile prod --to .env.prod
+cnos build env --profile local-domain --format docker-env --to .docker/runtime/current.env
 ```
 
 ## Watched dev loop
@@ -36,3 +37,4 @@ cnos build env --public --framework next --profile prod --to .env.production
 - keep generated `.env.*` files gitignored
 - migrate app code toward direct CNOS reads over time
 - keep secrets on runtime/vault flows instead of materializing them into env files by default
+- use `docker-env` when Docker or Docker Compose expects a runtime env file

package/docs/guides/migration.mdx

@@ -5,7 +5,16 @@ description: Move existing env-based projects onto CNOS without losing current w
 
 # Migrating from .env
 
-Use the migration assistant:
+CNOS migration works best as a bridge, not a flag day.
+
+The pattern is:
+
+1. Keep `.cnos` as the new source of truth.
+2. Keep your current app/build/runtime working.
+3. Generate whatever bridge artifact the existing stack needs.
+4. Migrate direct env reads to CNOS app by app.
+
+Use the migration assistant when you want help mapping existing env usage:
 
 ```bash
 cnos migrate --scan src --dry-run
@@ -13,20 +22,112 @@ cnos migrate --apply
 cnos migrate --apply --rewrite
 ```
 
-Bridge to existing tooling:
+## Plain Node or Express with `.env`
+
+If your service currently starts with `dotenv`, keep that flow first.
 
 ```bash
-cnos build env --to .env.local
+cnos build env --profile local --to .env.local
 cnos build env --profile stage --to .env.stage
-cnos dev env --profile local --to .env.local -- pnpm dev
 ```
 
-For webpack or other static bundles, pair this with `@kitsy/cnos-webpack` or `@kitsy/cnos/build` so browser-safe `public.*` values are injected at build time without keeping handwritten `.env` files as the source of truth.
+Then your existing `dotenv` bootstrap keeps working.
+
+Move server code gradually:
+
+```ts
+import cnos from '@kitsy/cnos';
+
+await cnos.ready();
+
+const port = cnos.readOr('value.server.port', 3000);
+const token = cnos.secret('app.token');
+```
+
+For runtime packaging instead of env files:
+
+```bash
+cnos build server --profile prod --to .cnos-server.json
+```
+
+## Vite Frontend
+
+If you already use `VITE_*` env variables, keep that contract first.
+
+```bash
+cnos build public --framework vite --profile local --to .env.local
+cnos dev env --public --framework vite --profile local --to .env.local -- pnpm dev
+```
+
+Then add `@kitsy/cnos-vite` and migrate browser reads to:
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+cnos('public.app.apiBaseUrl');
+```
+
+## Next.js
+
+If you already use `NEXT_PUBLIC_*`, keep that contract while adopting CNOS.
+
+```bash
+cnos build public --framework next --profile prod --to .env.production
+```
+
+Then wire `@kitsy/cnos-next` so Next gets public data from CNOS directly and browser code can read `public.*` through `@kitsy/cnos/browser`.
+
+## Webpack Static Frontend
+
+If you already have a `webpack.config.js`, you do not need to invent a new runtime.
+
+- read build-time settings such as dev-server port through `createCnos()`
+- inject browser-safe config through `@kitsy/cnos-webpack`
+- keep generated `.env.*` files only if your repo still expects them
+
+Example bridge:
+
+```bash
+cnos build public --profile local --to .env.local
+```
+
+Longer-term path:
+
+- `CnosWebpackPlugin` for browser-safe values
+- `createCnos()` inside webpack config for build-time settings
+
+## pnpm Monorepo
+
+For monorepos, do not copy `.cnos` into every package.
+
+- keep one repo-root `.cnos/`
+- add `.cnosrc.yml` to each consuming app/package
+- optionally add a repo-root `.cnosrc.yml` if the root also consumes CNOS
+
+Example:
+
+```yaml
+# apps/travel/.cnosrc.yml
+root: ../../.cnos
+workspace: travel
+```
+
+Server-side packages can use projections:
+
+```bash
+cnos build server --workspace travel --profile prod --to apps/travel/.cnos-server.json
+```
+
+Legacy env-based packages can still use:
+
+```bash
+cnos build env --workspace travel --profile local --to apps/travel/.env.local
+```
 
 Recommended migration sequence:
 
 1. Keep `.cnos` as the source of truth.
-2. Generate `.env.*` artifacts for legacy tools.
+2. Generate `.env.*`, browser, or server projection artifacts for legacy tools.
 3. Migrate server code to `@kitsy/cnos`.
 4. Migrate browser code to `@kitsy/cnos/browser`.
-5. Remove env-file dependencies app by app.
+5. Remove handwritten env-file dependencies app by app.

package/docs/guides/workspaces.mdx

@@ -5,18 +5,88 @@ description: Use CNOS workspaces to model multiple apps inside one repo.
 
 # Workspaces and Monorepos
 
-In single-project mode, CNOS stays simple.
+For monorepos, keep one authoritative `.cnos/` tree at the repo root and put a `.cnosrc.yml` anchor in each consuming app or package.
 
-For monorepos:
+Repo root as both author and consumer:
 
-```bash
-cnos init --workspace api
-cnos use --workspace api
-cnos list values
+```yaml
+# .cnosrc.yml
+root: ./.cnos
+```
+
+Child app:
+
+```yaml
+# apps/travel/.cnosrc.yml
+root: ../../.cnos
+workspace: travel
+```
+
+`.cnosrc.yml` is the only discovery anchor. CNOS does not walk upward looking for `.cnos` directories. It looks for `.cnosrc.yml` within a bounded package-root search window, then resolves the real `.cnos` root from there.
+
+Typical manifest shape:
+
+```yaml
+workspaces:
+  default: root
+  items:
+    root: {}
+    travel:
+      extends: [root]
+    food:
+      extends: [root]
+```
+
+This lets you keep shared values in `root` and override only what each app needs in `travel`, `food`, or other child workspaces.
+
+Read from an app package without passing a root manually:
+
+```ts
+import cnos from '@kitsy/cnos';
+
+await cnos.ready();
+console.log(cnos('value.app.name'));
 ```
 
 Override per command when needed:
 
 ```bash
-cnos list values --workspace webapp
+cnos list values --workspace travel
+cnos build server --workspace travel --profile prod --to apps/travel/.cnos-server.json
 ```
+
+## Runtime Projection
+
+The authoring tree stays at repo root. Runtime consumers do not need the full `.cnos/` layout.
+
+For server packaging:
+
+```bash
+cnos build server --workspace api-gateway --profile prod --to apps/api-gateway/.cnos-server.json
+```
+
+`@kitsy/cnos` then auto-loads in this order:
+
+1. `__CNOS_PROJECTION__`
+2. `.cnos-server.json`
+3. full authoring resolution through `.cnosrc.yml`
+
+Browser packages keep using public projection through Vite, Next, webpack, or `@kitsy/cnos/build`.
+
+## Detach and Reattach
+
+Detach a child package into a standalone CNOS root:
+
+```bash
+cnos workspace detach --package-root apps/travel
+```
+
+This materializes the effective config into `apps/travel/.cnos`, rewrites `apps/travel/.cnosrc.yml` to point to that local root, and stops inheriting from the parent repo.
+
+Reattach it later:
+
+```bash
+cnos workspace attach --package-root apps/travel
+```
+
+This imports the standalone child config back into the parent workspace model, archives the detached `.cnos`, and restores the package anchor.

package/manifest.yml

@@ -29,6 +29,8 @@ sidebar:
         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/profiles

package/package.json

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