@kitsy/cnos-docs 1.6.0 → 1.7.0

package/docs/api/browser.mdx

@@ -16,3 +16,32 @@ 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.
+
+## Cross-App Browser Config
+
+Use the same runtime for shared browser-safe values such as sibling app origins, CDN roots, public feature flags, or analytics ids.
+
+```yaml
+public:
+  promote:
+    - value.apps.docs.origin
+    - value.apps.console.origin
+```
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+const docsOrigin = cnos('public.apps.docs.origin');
+const consoleOrigin = cnos('public.apps.console.origin');
+```
+
+This is intentionally simple:
+
+1. define the values in CNOS
+2. promote them to `public.*`
+3. install the framework integration
+4. read them in browser code with `@kitsy/cnos/browser`
+
+You should not need a second app-specific browser config mechanism on top of CNOS.
+
+Derived public values are supported too, but only when CNOS can resolve them safely at build time. If a promoted key depends on a server-only runtime namespace such as `process.*` or `request.*`, the browser/public build fails instead of emitting unstable data.

package/docs/api/create-cnos.mdx

@@ -13,3 +13,44 @@ const runtime = await createCnos({
   profile: 'stage',
 });
 ```
+
+Common options:
+
+- `cwd`
+- `root`
+- `workspace`
+- `profile`
+- `globalRoot`
+- `cacheMode`
+- `cacheTtlSeconds`
+- `processEnv`
+
+`root` can be a local path or a remote git root URI:
+
+```ts
+const runtime = await createCnos({
+  root: 'git+https://github.com/org/config.git#v2.1.0',
+  workspace: 'travel',
+});
+```
+
+Derived values and runtime namespaces work through the explicit runtime too:
+
+```ts
+import { createCnos } from '@kitsy/cnos/configure';
+
+const runtime = await createCnos({
+  cwd: process.cwd(),
+  profile: 'prod',
+});
+
+runtime.registerRuntimeProvider('request', (key) => {
+  if (key === 'headers.host') {
+    return currentRequest?.headers.host;
+  }
+
+  return undefined;
+});
+
+const origin = runtime.value('app.origin');
+```

package/docs/api/runtime.mdx

@@ -36,6 +36,7 @@ The runtime currently exposes:
 - `cnos.format(message)`
 - `cnos.log(message)`
 - `cnos.loadProjection(path)`
+- `cnos.registerRuntimeProvider(namespace, provider)`
 - `cnos.refreshSecrets()`
 - `cnos.refreshSecret(key)`
 
@@ -67,6 +68,49 @@ await cnos.loadProjection('./.cnos-server.json');
 await cnos.ready();
 ```
 
+## Derived Values
+
+Derived values resolve transparently through the same read APIs.
+
+```yaml
+app:
+  origin:
+    $derive: "${value.app.protocol}://${value.app.host}:${value.app.port}"
+```
+
+```ts
+const origin = cnos.value('app.origin');
+```
+
+Config-only derivations are cached for the active runtime. Runtime-dependent derivations stay live:
+
+```yaml
+server:
+  effective_port:
+    $derive:
+      expr: "coalesce(process.env.PORT, value.server.default_port, '3000')"
+```
+
+```ts
+const port = cnos.value('server.effective_port');
+```
+
+## Runtime Providers
+
+Declare custom runtime namespaces in the manifest, then register a provider at runtime.
+
+```ts
+cnos.registerRuntimeProvider('request', (key) => {
+  if (key === 'headers.host') {
+    return currentRequest?.headers.host;
+  }
+
+  return undefined;
+});
+```
+
+That lets server-side derived values depend on live request, session, or app-framework context without adding a second config layer.
+
 ## 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

@@ -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 .env.local-domain
 ```
 
 Targets:

package/docs/cli/cache.mdx

@@ -0,0 +1,28 @@
+---
+title: cnos cache
+description: Inspect and manage cached remote CNOS roots.
+---
+
+# cnos cache
+
+Use `cache` when a package anchor points at a remote root such as a git-backed config repo.
+
+```bash
+cnos cache list
+cnos cache clear
+cnos cache clear git+https://github.com/org/config.git#v2.1.0
+cnos cache refresh
+cnos cache refresh git+ssh://git@github.com/org/config.git#main
+```
+
+Subcommands:
+
+- `cache list` shows cached remote roots, resolved commits, immutability, and size
+- `cache clear` removes all cached roots or one specific cached root
+- `cache refresh` forces a re-fetch for the current remote root or a specific git root URI
+
+Notes:
+
+- immutable refs such as semantic-version tags and commit SHAs stay cached permanently
+- mutable refs such as branches are refreshed based on CNOS cache policy
+- remote roots are read-only when consumed through CNOS

package/docs/cli/inspect.mdx

@@ -9,3 +9,31 @@ description: Inspect resolved values, provenance, and overrides.
 cnos inspect value.app.name
 cnos inspect secret.app.token --reveal
 ```
+
+`cnos inspect` also shows derived metadata.
+
+```bash
+cnos inspect value.app.origin
+```
+
+Typical output includes:
+
+- resolved value
+- expression or template source
+- dependency keys
+- whether the value is runtime-dependent
+- which runtime namespaces it depends on
+
+Example:
+
+```text
+key: value.app.origin
+value: https://api.kitsy.ai:443
+derivedType: template
+derivedExpression: ${value.app.protocol}://${value.app.host}:${value.app.port}
+runtimeDependent: false
+dependencies:
+  - value.app.host
+  - value.app.port
+  - value.app.protocol
+```

package/docs/cli/value.mdx

@@ -12,6 +12,22 @@ cnos value list --prefix app.
 cnos value delete app.name
 ```
 
+## Derived values
+
+Use `--derive` for template shorthand:
+
+```bash
+cnos value set app.origin --derive '${value.app.protocol}://${value.app.host}'
+```
+
+Use `--derive --expr` for expression form:
+
+```bash
+cnos value set app.effective_port --derive --expr "coalesce(process.env.PORT, value.app.default_port, '3000')"
+```
+
+CNOS stores these as first-class derived values, not as opaque strings.
+
 ## Typed input
 
 `cnos value set` parses the input as YAML before writing it. That means you can store more than strings.
@@ -46,3 +62,4 @@ cnos read value.app.name
 - 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`.
+- Derived values can be authored only under writable data namespaces such as `value.*` and custom writable data namespaces.

package/docs/guides/backend.mdx

@@ -30,6 +30,31 @@ const port = cnos.value('server.port');
 const token = cnos.secret('app.token');
 ```
 
+Derived server config stays inside CNOS too:
+
+```yaml
+server:
+  effective_port:
+    $derive:
+      expr: "coalesce(process.env.PORT, value.server.default_port, '3000')"
+```
+
+```ts
+const port = cnos.value('server.effective_port');
+```
+
+If you need live request or session context, declare a runtime namespace and register a provider:
+
+```ts
+cnos.registerRuntimeProvider('request', (key) => {
+  if (key === 'headers.host') {
+    return currentRequest?.headers.host;
+  }
+
+  return undefined;
+});
+```
+
 Env export bridge:
 
 ```bash

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/derived-values.mdx

@@ -0,0 +1,130 @@
+---
+title: Derived Values
+description: Compute config from other CNOS keys and live runtime namespaces.
+---
+
+# Derived Values
+
+Derived values let you keep config composition inside CNOS instead of re-implementing it in app code.
+
+Template shorthand:
+
+```yaml
+app:
+  origin:
+    $derive: "${value.app.protocol}://${value.app.host}:${value.app.port}"
+```
+
+Expression form:
+
+```yaml
+app:
+  effective_port:
+    $derive:
+      expr: "coalesce(process.env.PORT, value.app.default_port, '3000')"
+```
+
+## Write from the CLI
+
+```bash
+cnos value set app.origin --derive '${value.app.protocol}://${value.app.host}'
+cnos value set app.effective_port --derive --expr "coalesce(process.env.PORT, value.app.default_port, '3000')"
+```
+
+## Built-ins
+
+Supported functions:
+
+- `concat(...)`
+- `coalesce(...)`
+- `when(condition, thenValue, elseValue)`
+- `exists(ref)`
+- `eq(a, b)`
+- `ne(a, b)`
+
+The language is intentionally small and safe. There is no arbitrary JavaScript execution.
+
+## Runtime Namespaces
+
+`process.*` is the built-in runtime namespace. It stays live between reads.
+
+```yaml
+app:
+  effective_port:
+    $derive:
+      expr: "coalesce(process.env.PORT, value.app.default_port, '3000')"
+```
+
+Custom runtime namespaces are declared in the manifest and populated by the host app:
+
+```yaml
+namespaces:
+  runtime:
+    request:
+      description: HTTP request context
+      server_only: true
+```
+
+```ts
+import cnos from '@kitsy/cnos';
+
+await cnos.ready();
+
+cnos.registerRuntimeProvider('request', (key) => {
+  if (key === 'headers.host') {
+    return currentRequest?.headers.host;
+  }
+
+  return undefined;
+});
+```
+
+## Caching Rules
+
+- config-only derivations are cached once per resolution pass
+- runtime-dependent derivations are never cached
+
+That means `value.app.origin` is stable until the next `createCnos()` or `cnos.ready()`, while `value.app.effective_port` can change between reads when `process.env.PORT` changes.
+
+## Browser and Server Behavior
+
+Browser/public outputs always need concrete values.
+
+- config-only derived values can be promoted and embedded normally
+- runtime-dependent derived values that rely on server-only namespaces are rejected for browser/public builds
+
+Server projections split the result:
+
+- `values` contains concrete non-secret values, including config-only derivations
+- `derived` contains live runtime-dependent formulas
+- `runtimeNamespaces` lists which runtime providers the server runtime needs
+
+## Use Cases
+
+Cross-app browser links:
+
+```yaml
+apps:
+  cnos:
+    origin:
+      $derive: "${value.platform.protocol}://${value.apps.cnos.host}"
+
+public:
+  promote:
+    - value.apps.cnos.origin
+```
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+const cnosOrigin = cnos('public.apps.cnos.origin');
+```
+
+Server fallback port:
+
+```yaml
+server:
+  port:
+    $derive:
+      expr: "coalesce(process.env.PORT, value.server.default_port, '3000')"
+```

package/docs/guides/frontend-vite.mdx

@@ -40,6 +40,58 @@ console.log(cnos('public.app.apiBaseUrl'));
 console.log(import.meta.env.VITE_APP_API_BASE_URL);
 ```
 
+Cross-app browser links work the same way. Put the browser-safe origins in CNOS, promote them, and let the Vite plugin handle the embedding:
+
+```yaml
+public:
+  promote:
+    - value.apps.main.origin
+    - value.apps.cnos.origin
+    - value.apps.coop.origin
+```
+
+```yaml
+apps:
+  main:
+    origin: https://kitsy.ai
+  cnos:
+    origin: https://cnos.kitsy.ai
+  coop:
+    origin: https://coop.kitsy.ai
+```
+
+Then in UI code:
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+const cnosOrigin = cnos('public.apps.cnos.origin');
+const coopOrigin = cnos('public.apps.coop.origin');
+```
+
+That is the point of the integration. You promote once, keep using the same logical reads in UI code, and `@kitsy/cnos-vite` makes sure the values are already present in the browser bundle.
+
+Derived public values work the same way as long as they are build-safe:
+
+```yaml
+apps:
+  cnos:
+    origin:
+      $derive: "${value.platform.protocol}://${value.apps.cnos.host}"
+
+public:
+  promote:
+    - value.apps.cnos.origin
+```
+
+```ts
+import cnos from '@kitsy/cnos/browser';
+
+const cnosOrigin = cnos('public.apps.cnos.origin');
+```
+
+If a promoted derived value depends on a server-only runtime namespace such as `process.*` or a custom `request.*`, CNOS rejects the browser/public build instead of leaking an unstable value.
+
 Migration path:
 
 1. keep `VITE_*` working through generated env files

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/remote-roots.mdx

@@ -0,0 +1,86 @@
+---
+title: Remote Roots
+description: Point .cnosrc.yml at a remote git-backed CNOS root and consume it through the local cache.
+---
+
+# Remote Roots
+
+`.cnosrc.yml` can point at either a local `.cnos` directory or a remote git-backed root.
+
+Local:
+
+```yaml
+root: ./.cnos
+```
+
+Remote:
+
+```yaml
+root: git+https://github.com/org/config.git#v2.1.0
+workspace: travel
+```
+
+Remote roots are resolved into the CNOS cache, then loaded exactly like a local manifest root.
+
+## Supported URIs
+
+Recommended production form:
+
+```yaml
+root: git+https://github.com/org/config.git#v2.1.0
+```
+
+Private repo over SSH:
+
+```yaml
+root: git+ssh://git@github.com/org/private-config.git#main
+```
+
+Subpath inside the repo:
+
+```yaml
+root: git+https://github.com/org/monorepo.git#v2.1.0:config/.cnos
+```
+
+## Cache Behavior
+
+- semantic-version tags and commit SHAs are treated as immutable
+- branch refs are treated as mutable
+- runtime reads use a cache TTL
+- `cnos build` refreshes mutable refs before building artifacts
+- `cnos cache refresh` forces a re-fetch when needed
+
+Inspect the cache:
+
+```bash
+cnos cache list
+```
+
+Override TTL for one command when needed:
+
+```bash
+cnos read value.app.name --cache-ttl 0
+cnos watch --cache-ttl 15 -- node server.js
+```
+
+## Read-Only Model
+
+Remote roots are consumed as read-only config.
+
+These work:
+
+```bash
+cnos read value.app.name
+cnos build env --to .env.stage
+cnos run -- node server.js
+```
+
+These are blocked:
+
+```bash
+cnos value set app.name demo
+cnos promote value.app.name --to public
+cnos vault create default
+```
+
+The right workflow is to edit the source config repo and then let consumers refresh the cached root.

package/docs/guides/workspaces.mdx

@@ -22,6 +22,13 @@ root: ../../.cnos
 workspace: travel
 ```
 
+Child app from a remote config repo:
+
+```yaml
+root: git+https://github.com/org/config.git#v2.1.0
+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:

package/docs/reference/namespaces.mdx

@@ -12,6 +12,7 @@ Primary namespaces:
 - `meta.*`
 - `process.*` for server-only ambient runtime state
 - custom data namespaces such as `flags.*` or `config.*` when declared in `.cnos/cnos.yml`
+- custom runtime namespaces declared under `namespaces.runtime`
 
 Derived surfaces:
 
@@ -35,3 +36,36 @@ Custom data namespaces can be:
 - `process.env.PATH`
 
 `process.*` cannot be promoted or exported.
+
+## Runtime Namespaces
+
+Runtime namespaces are not populated from config files. They are declared in the manifest and populated by the host runtime.
+
+```yaml
+namespaces:
+  runtime:
+    request:
+      description: HTTP request context
+      server_only: true
+```
+
+Use them from derived values:
+
+```yaml
+app:
+  current_host:
+    $derive:
+      expr: "coalesce(request.headers.host, value.app.default_host)"
+```
+
+And register providers in server code:
+
+```ts
+cnos.registerRuntimeProvider('request', (key) => {
+  if (key === 'headers.host') {
+    return currentRequest?.headers.host;
+  }
+
+  return undefined;
+});
+```

package/manifest.yml

@@ -1,7 +1,7 @@
 product: cnos
 title: CNOS Documentation
 tagline: Configuration orchestration for apps, monorepos, and deployment pipelines
-version: "1.5"
+version: "1.7"
 
 sidebar:
   - group: Getting Started
@@ -29,10 +29,16 @@ 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/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
@@ -61,6 +67,8 @@ sidebar:
         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

package/package.json

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