@kitsy/cnos-docs 1.6.0 → 1.6.1

package/docs/cli/build.mdx

@@ -13,6 +13,7 @@ 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 public --framework vite --to .env.production
+cnos build env --profile local-domain --format docker-env --to .docker/runtime/current.env
 ```
 
 Targets:

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/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/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.6.0",
+  "version": "1.6.1",
   "description": "Source-of-truth CNOS documentation content for Astro Starlight and other static docs consumers.",
   "type": "module",
   "exports": {