@kitsy/cnos-docs 1.3.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/api/runtime.mdx

@@ -5,6 +5,8 @@ description: Use the default CNOS runtime singleton from the root package.
 
 # Singleton Runtime
 
+Use the default server/runtime singleton when your process is started through `cnos run`, or when you want the zero-config default entrypoint.
+
 ```ts
 import cnos from '@kitsy/cnos';
 
@@ -14,3 +16,52 @@ cnos('value.app.name');
 cnos.value('app.name');
 cnos.secret('app.token');
 ```
+
+## Available methods
+
+The runtime currently exposes:
+
+- `cnos(key)` as shorthand for `cnos.read(key)`
+- `cnos.read(key)`
+- `cnos.require(key)`
+- `cnos.readOr(key, fallback)`
+- `cnos.value(path)`
+- `cnos.secret(path)`
+- `cnos.meta(path)`
+- `cnos.inspect(key)`
+- `cnos.toNamespace(namespace)`
+- `cnos.toEnv()`
+- `cnos.toPublicEnv()`
+
+Example:
+
+```ts
+import cnos from '@kitsy/cnos';
+
+await cnos.ready();
+
+const appName = cnos.value('app.name');
+const dbPassword = cnos.secret('db.password');
+const profile = cnos.meta('profile');
+const port = cnos.readOr('value.server.port', 3000);
+const flags = cnos.toNamespace('flags');
+```
+
+## 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.
+
+```ts
+const enabled = cnos.value<boolean>('flags.upi_enabled');
+const params = cnos.read<string[]>('value.api.default_query_params');
+```
+
+## What does not exist
+
+The current v1 runtime does not expose helper methods such as:
+
+- `readAsString()`
+- `readAsNumber()`
+- `readAsBoolean()`
+
+Use `read<T>()`, `require<T>()`, or the namespace helpers instead.

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/value.mdx

@@ -11,3 +11,38 @@ cnos value get app.name
 cnos value list --prefix app.
 cnos value delete app.name
 ```
+
+## Typed input
+
+`cnos value set` parses the input as YAML before writing it. That means you can store more than strings.
+
+```bash
+cnos value set server.port 3000
+cnos value set flags.upi_enabled false
+cnos value set api.default_query_params '["ab", "bc"]'
+cnos value set app.theme '{ primary: blue, density: compact }'
+```
+
+Those values are stored and read back as:
+
+- number
+- boolean
+- array
+- object
+
+## Read forms
+
+The most common CLI read forms are:
+
+```bash
+cnos value get app.name
+cnos get value app.name
+cnos get value.app.name
+cnos read value.app.name
+```
+
+## Notes
+
+- Values are private by default.
+- To expose a value to browser/public surfaces, use `cnos promote`.
+- To expose a value as shell env, map it through `envMapping.explicit` or `cnos promote --to env`.

package/docs/cli/vault.mdx

@@ -12,3 +12,5 @@ cnos vault list
 cnos vault logout default
 cnos vault remove default
 ```
+
+For local vaults, `cnos vault create <name>` initializes the encrypted keystore immediately. CNOS prompts for a passphrase if one is not already available through `CNOS_SECRET_PASSPHRASE_<VAULT>`, `CNOS_SECRET_PASSPHRASE`, or the OS keychain. `cnos vault auth <name>` re-authenticates an existing vault and fails on wrong credentials.

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

@@ -9,7 +9,9 @@ description: Go from zero to a running CNOS-backed project in a few minutes.
 cnos init
 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
 ```
 
@@ -29,4 +31,17 @@ import { createCnos } from '@kitsy/cnos/configure';
 
 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/getting-started/your-first-project.mdx

@@ -22,7 +22,7 @@ cnos value set server.port 3000
 Create a profile:
 
 ```bash
-cnos profile create stage --inherit base
+cnos profile create stage
 cnos use --profile stage
 ```
 

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/docs/guides/profiles.mdx

@@ -8,8 +8,14 @@ description: Create explicit overlays for stage, prod, and other environments.
 Profiles are explicit overlays, not implicit defaults.
 
 ```bash
-cnos profile create stage --inherit base
+cnos profile create stage
 cnos use --profile stage
 cnos value set app.apiBaseUrl https://api.stage
 cnos diff base stage
 ```
+
+Profiles inherit values from `base` by default. For a clean profile with no base fallback:
+
+```bash
+cnos profile create isolated --no-inherit
+```

package/docs/guides/secrets.mdx

@@ -13,6 +13,8 @@ cnos vault auth default
 cnos secret set app.token super-secret --vault default
 ```
 
+`cnos vault create default` initializes the local encrypted vault immediately. If CNOS cannot resolve a passphrase from env or keychain, it prompts interactively. `cnos vault auth default` is only for re-authenticating an existing vault and rejects wrong passphrases.
+
 CI-backed vault:
 
 ```bash

package/docs/reference/manifest.mdx

@@ -12,6 +12,7 @@ Key sections:
 - `profiles`
 - `envMapping`
 - `public`
+- `namespaces`
 - `vaults`
 - `schema`
 - `writePolicy`

package/docs/reference/namespaces.mdx

@@ -1,6 +1,6 @@
 ---
 title: Namespaces
-description: Understand value, secret, meta, public, and env projection surfaces.
+description: Understand value, secret, meta, public, env, and custom data namespaces.
 ---
 
 # Namespaces
@@ -10,8 +10,28 @@ Primary namespaces:
 - `value.*`
 - `secret.*`
 - `meta.*`
+- `process.*` for server-only ambient runtime state
+- custom data namespaces such as `flags.*` or `config.*` when declared in `.cnos/cnos.yml`
 
 Derived surfaces:
 
 - `public.*` for promoted browser-safe values
 - explicit env exports through `envMapping.explicit`
+
+Custom data namespaces can be:
+
+- read at runtime with `cnos('flags.upi_enabled')`
+- written through the CLI with `cnos set flags.upi_enabled false`
+- promoted to `public.*` when the namespace is `shareable: true`
+- exported through `envMapping.explicit`
+
+`process.*` is built in and read-only. Typical keys include:
+
+- `process.cwd`
+- `process.platform`
+- `process.arch`
+- `process.node.version`
+- `process.args.raw`
+- `process.env.PATH`
+
+`process.*` cannot be promoted or exported.

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