@kitsy/cnos-docs 1.4.0 → 1.5.0

package/docs/api/browser.mdx

@@ -12,3 +12,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.

package/docs/cli/build.mdx

@@ -0,0 +1,23 @@
+---
+title: cnos build env
+description: Build flat env-file artifacts from CNOS.
+---
+
+# cnos build env
+
+Use `build env` when a repo still expects `.env.*` files but CNOS is the source of truth.
+
+```bash
+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
+```
+
+`build env`:
+
+- resolves the selected CNOS workspace/profile
+- renders a deterministic flat `KEY=VALUE` file
+- writes the target path
+- does not start a child process
+
+This is the preferred bridge for build systems and CI pipelines that still consume env files.

package/docs/cli/dev.mdx

@@ -0,0 +1,23 @@
+---
+title: cnos dev env
+description: Watch CNOS config, rewrite env artifacts, and restart a child process.
+---
+
+# cnos dev env
+
+Use `dev env` when a local development workflow still expects a `.env.*` file.
+
+```bash
+cnos dev env --profile local --to .env.local -- pnpm dev
+cnos dev env --profile stage --to .env.stage -- node server.js
+cnos dev env --public --framework vite --to .env.local --signal -- pnpm dev
+```
+
+By default `dev env`:
+
+- writes the env artifact before first launch
+- watches CNOS inputs
+- rewrites the target file on change
+- restarts the child process
+
+Use `--signal` when another tool is responsible for reloads and you only want the file to stay current.

package/docs/cli/export.mdx

@@ -10,3 +10,16 @@ cnos export env
 cnos export env --to .env.local
 cnos export env --public --framework vite --to .env.local
 ```
+
+`export env` is the low-level renderer.
+
+Use it when you want:
+
+- stdout output for piping
+- one-off JSON/text export behavior
+- direct control over the raw env projection
+
+For higher-level file-oriented workflows, prefer:
+
+- `cnos build env` for one-shot artifact generation
+- `cnos dev env` for watched dev-time file generation

package/docs/cli/index.mdx

@@ -9,7 +9,7 @@ The CLI is organized around:
 
 - setup: `init`, `onboard`, `use`, `profile`
 - data operations: `read`, `value`, `secret`, `promote`
-- workflows: `run`, `export`, `dump`, `diff`, `doctor`
+- workflows: `build env`, `dev env`, `run`, `export`, `dump`, `diff`, `doctor`
 - advanced tooling: `codegen`, `watch`, `migrate`, `drift`, `vault`
 
 See the individual command pages in this section.

package/docs/cli/watch.mdx

@@ -9,3 +9,13 @@ description: Watch config changes and emit signals or restart processes.
 cnos watch -- node server.js
 cnos watch --signal
 ```
+
+`watch` is the low-level graph watcher.
+
+Use it when you want to react to CNOS graph changes directly.
+
+If your repo still needs `.env.*` files during development, prefer:
+
+```bash
+cnos dev env --profile local --to .env.local -- pnpm dev
+```

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

@@ -11,6 +11,7 @@ cnos value set app.name demo
 cnos value set server.port 3000
 cnos value set api.default_query_params '["ab", "bc"]'
 cnos read value.app.name
+cnos build env --profile local --to .env.local
 cnos run -- node server.js
 ```
 
@@ -32,3 +33,15 @@ const runtime = await createCnos();
 console.log(runtime.value('app.name'));
 console.log(runtime.read<string[]>('value.api.default_query_params'));
 ```
+
+If your repo still expects env files, keep `.cnos` as the source of truth and generate them:
+
+```bash
+cnos build env --profile local --to .env.local
+cnos dev env --profile local --to .env.local -- pnpm dev
+```
+
+For frontend builds:
+- Vite: `@kitsy/cnos-vite`
+- Webpack/static bundles: `@kitsy/cnos-webpack`
+- Next.js: `@kitsy/cnos-next`

package/docs/guides/frontend-webpack.mdx

@@ -0,0 +1,58 @@
+---
+title: Frontend with Webpack
+description: Use CNOS public projection with webpack builds, webpack-dev-server, and browser-safe runtime reads.
+---
+
+# Frontend with Webpack
+
+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.
+
+Promote browser-safe values:
+
+```yaml
+public:
+  promote:
+    - value.app.apiUrl
+    - flags.upi_enabled
+```
+
+Use an async webpack config:
+
+```ts
+import { createCnos } from '@kitsy/cnos/configure';
+import { CnosWebpackPlugin } from '@kitsy/cnos-webpack';
+
+export default async () => {
+  const cnos = await createCnos({
+    profile: process.env.NODE_ENV === 'production' ? 'prod' : 'local',
+  });
+
+  return {
+    devServer: {
+      port: Number(cnos.readOr('value.devServer.port', 3000)),
+    },
+    plugins: [
+      new CnosWebpackPlugin({
+        profile: process.env.NODE_ENV === 'production' ? 'prod' : 'local',
+      }),
+    ],
+  };
+};
+```
+
+Read in browser code:
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+console.log(cnos('public.app.apiUrl'));
+console.log(cnos('public.flags.upi_enabled'));
+console.log(process.env.APP_API_URL);
+```
+
+The webpack plugin:
+- injects `process.env.*` define replacements for promoted public values
+- embeds `globalThis.__CNOS_BROWSER_DATA__` for `@kitsy/cnos/browser`
+- keeps server-only `value.*` and `secret.*` out of the browser bundle
+
+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.

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

@@ -0,0 +1,38 @@
+---
+title: Generated Env Files
+description: Use CNOS to generate legacy .env artifacts while keeping .cnos as the source of truth.
+---
+
+# Generated Env Files
+
+CNOS is runtime-first, but many repos still rely on `.env.local`, `.env.stage`, or similar files.
+
+Use generated env files as a **bridge**, not as the source of truth.
+
+## One-shot build
+
+```bash
+cnos build env --profile local --to .env.local
+cnos build env --profile stage --to .env.stage
+cnos build env --profile prod --to .env.prod
+```
+
+## Watched dev loop
+
+```bash
+cnos dev env --profile local --to .env.local -- pnpm dev
+```
+
+## Public-only frontend artifacts
+
+```bash
+cnos build env --public --framework vite --profile local --to .env.local
+cnos build env --public --framework next --profile prod --to .env.production
+```
+
+## Recommended policy
+
+- keep `.cnos` as the source of truth
+- 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

package/docs/guides/migration.mdx

@@ -16,6 +16,17 @@ cnos migrate --apply --rewrite
 Bridge to existing tooling:
 
 ```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
+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.
+
+Recommended migration sequence:
+
+1. Keep `.cnos` as the source of truth.
+2. Generate `.env.*` 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.

package/manifest.yml

@@ -1,7 +1,7 @@
 product: cnos
 title: CNOS Documentation
 tagline: Configuration orchestration for apps, monorepos, and deployment pipelines
-version: "1.3"
+version: "1.5"
 
 sidebar:
   - group: Getting Started
@@ -21,6 +21,8 @@ sidebar:
         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
@@ -35,6 +37,8 @@ sidebar:
         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
@@ -55,6 +59,10 @@ sidebar:
         label: cnos validate
       - path: cli/export
         label: cnos export
+      - path: cli/build
+        label: cnos build env
+      - path: cli/dev
+        label: cnos dev env
       - path: cli/run
         label: cnos run
       - path: cli/diff

package/package.json

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