@kitsy/cnos-docs 1.3.0 → 1.4.0

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/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/getting-started/quick-start.mdx

@@ -9,6 +9,7 @@ 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 run -- node server.js
 ```
@@ -29,4 +30,5 @@ 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'));
 ```

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/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/package.json

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