@kitsy/cnos-docs 1.8.4 → 1.9.1

package/docs/cli/build.mdx

@@ -12,6 +12,7 @@ cnos build server --to .cnos-server.json
 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 env --profile prod --reveal --to .env.production.local
 cnos build public --framework vite --to .env.production
 cnos build env --profile local-domain --format docker-env --to .env.local-domain
 ```
@@ -24,3 +25,18 @@ Targets:
 - `build public` writes promoted public env with optional framework prefixes like Vite and Next
 
 All build artifacts are derived output. `.cnos` remains the source of truth.
+
+## Writing secrets into env artifacts
+
+By default, `build env` masks secret env mappings as `****`.
+
+Use `--reveal` only when you intentionally want concrete secret values in the generated artifact:
+
+```bash
+cnos build env --profile prod --reveal --to .env.production.local
+```
+
+CNOS protects this path in two ways:
+
+- it verifies that the target file is gitignored before writing secrets
+- it prints explicit risk warnings and, in interactive terminals, asks `Do you want to continue?` before continuing

package/docs/cli/define.mdx

@@ -0,0 +1,21 @@
+---
+title: cnos define
+description: Write a value or secret through CNOS write policy.
+---
+
+# cnos define
+
+Use `cnos define` when you want CNOS to choose the correct target file for a `value.*` or `secret.*` write.
+
+## Usage
+
+```bash
+cnos define <value|secret> <path> <rawValue> [--target <local|global>] [--workspace <id>] [--profile <name>]
+```
+
+## Examples
+
+```bash
+cnos define value server.port 3000 --workspace api
+cnos define secret app.token super-secret --workspace api
+```

package/docs/cli/diff.mdx

@@ -6,6 +6,6 @@ description: Compare resolved config across profiles or workspaces.
 # cnos diff
 
 ```bash
-cnos diff base stage
-cnos diff --workspace api --profile base --other-profile stage
+cnos diff local stage
+cnos diff stage prod --workspace api
 ```

package/docs/cli/doctor.mdx

@@ -8,4 +8,9 @@ description: Run diagnostics across workspaces, exports, and security rules.
 ```bash
 cnos doctor
 cnos doctor --json
+cnos doctor --fix-secret-env-mappings
 ```
+
+The security diagnostics now flag explicit `secret.*` env mappings as a risk because they enable plaintext secret emission into private env surfaces.
+
+If those mappings were added by mistake, `cnos doctor --fix-secret-env-mappings` removes them from `envMapping.explicit` in one shot and then reruns diagnostics.

package/docs/cli/help-ai.mdx

@@ -0,0 +1,21 @@
+---
+title: cnos help-ai
+description: Show machine-readable CLI help for agents and automation.
+---
+
+# cnos help-ai
+
+`cnos help-ai` is the canonical machine-readable CLI surface. JSON is the default output format.
+
+## Usage
+
+```bash
+cnos help-ai [command] [--format <json|text>]
+```
+
+## Examples
+
+```bash
+cnos help-ai --format json
+cnos help-ai export env --format json
+```

package/docs/cli/help.mdx

@@ -0,0 +1,22 @@
+---
+title: cnos help
+description: Show human-readable CLI help for the root command set or one topic.
+---
+
+# cnos help
+
+Use `cnos help` when you want the checked-in command list and detailed usage for a topic.
+
+## Usage
+
+```bash
+cnos help [command]
+```
+
+## Examples
+
+```bash
+cnos help
+cnos help define
+cnos help export env
+```

package/docs/cli/index.mdx

@@ -8,8 +8,9 @@ description: Overview of the CNOS CLI surface and command groups.
 The CLI is organized around:
 
 - setup: `init`, `onboard`, `use`, `profile`
-- data operations: `read`, `value`, `secret`, `promote`
-- workflows: `build env`, `dev env`, `run`, `export`, `dump`, `diff`, `doctor`
-- advanced tooling: `codegen`, `watch`, `migrate`, `drift`, `vault`
+- data operations: `read`, `value`, `secret`, `define`, `list`, `promote`
+- workflows: `build env`, `dev env`, `run`, `export`, `dump`, `diff`, `doctor`, `ui`
+- advanced tooling: `codegen`, `watch`, `migrate`, `drift`, `vault`, `cache`
+- help and metadata: `help`, `help-ai`, `version`
 
 See the individual command pages in this section.

package/docs/cli/list.mdx

@@ -0,0 +1,23 @@
+---
+title: cnos list
+description: List resolved config entries across one namespace or the full graph.
+---
+
+# cnos list
+
+`cnos list` gives you a resolved view of stored config, promoted output, and namespace-specific data.
+
+## Usage
+
+```bash
+cnos list [<namespace>|all] [--prefix <path>] [--framework <name>] [--workspace <id>] [--profile <name>]
+```
+
+## Examples
+
+```bash
+cnos list
+cnos list value --prefix app.
+cnos list flags
+cnos list public --framework vite
+```

package/docs/cli/profile.mdx

@@ -0,0 +1,23 @@
+---
+title: cnos profile
+description: Create, list, select, and delete explicit profile overlays.
+---
+
+# cnos profile
+
+Profiles model environment overlays such as `local`, `stage`, and `prod`.
+
+## Usage
+
+```bash
+cnos profile [create <name> | list | use <name> | delete <name>] [options] [--root <path>] [--json]
+```
+
+## Examples
+
+```bash
+cnos profile create stage
+cnos profile create isolated --no-inherit
+cnos profile list
+cnos profile use stage
+```

package/docs/cli/promote.mdx

@@ -8,4 +8,9 @@ description: Promote shareable values into public or env export surfaces.
 ```bash
 cnos promote value.flag.auth.upi_enabled --to public
 cnos promote value.server.port --to env --as PORT
+cnos promote secret.db.password --to env --as POSTGRES_PASSWORD --allow-secret
 ```
+
+`public` promotion never allows `secret.*`.
+
+`env` mapping can allow `secret.*`, but only when you opt in explicitly with `--allow-secret`. This is intentionally narrow: it declares that a private env surface may carry plaintext secrets for runtimes that do not use the CNOS client directly.

package/docs/cli/run.mdx

@@ -12,3 +12,7 @@ cnos run -- node server.js
 cnos run --profile stage -- pnpm build
 cnos run --auth -- node server.js
 ```
+
+Private runs inject explicit `envMapping` entries into the child process, including mapped `secret.*` keys when CNOS can authenticate them. `--public` strips that down to promoted public values only.
+
+Use `--auth` when the child process also bootstraps the CNOS runtime from `__CNOS_GRAPH__` and should receive an encrypted pre-resolved secret payload instead of re-authenticating on first secret read.

package/docs/cli/secret.mdx

@@ -9,5 +9,6 @@ description: Set, get, list, and delete secrets through configured vaults.
 cnos secret set app.token super-secret --vault default
 cnos secret get app.token --vault default --reveal
 cnos secret list
+cnos secret list --reveal
 cnos secret delete app.token
 ```

package/docs/cli/ui.mdx

@@ -0,0 +1,43 @@
+---
+title: cnos ui
+description: Launch the local CNOS UI for browsing config state and provenance.
+---
+
+# cnos ui
+
+```bash
+cnos ui
+cnos ui --port 4400 --api-port 4401
+```
+
+`cnos ui` starts two local services:
+
+- a CNOS API server that reads the active workspace and profile
+- a Vite + React + Tailwind UI that renders those surfaces in the browser
+
+Use it when you want a faster adoption path than raw CLI output for:
+
+- value and meta browsing
+- secret listing, with optional reveal using a supplied vault passphrase
+- env mapping review
+- public promotion review
+- inspect/provenance tracing
+
+Workspace and profile switching now happen inside the UI itself.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--host` | Host for the Vite UI server. Defaults to `127.0.0.1`. |
+| `--port` | Port for the Vite UI server. Defaults to `4310`. |
+| `--api-port` | Port for the CNOS API server. Defaults to `4311`. |
+| `--workspace` | Override the active workspace. |
+| `--profile` | Override the active profile. |
+
+## Notes
+
+- The UI is read-only in this first cut.
+- Secret keys stay masked by default in the browser.
+- Revealing secrets is local-only and uses the supplied passphrase or existing vault auth state.
+- Use `cnos inspect` or `cnos read --reveal` when you need terminal-first detail.

package/docs/cli/use.mdx

@@ -0,0 +1,22 @@
+---
+title: cnos use
+description: Persist repo-local CLI defaults such as workspace, profile, and global root.
+---
+
+# cnos use
+
+`cnos use` reads or writes the repo-local CLI context stored in `.cnos-workspace.yml`.
+
+## Usage
+
+```bash
+cnos use [show] [--workspace <id>] [--profile <name>] [--global-root <path>] [--root <path>] [--json]
+```
+
+## Examples
+
+```bash
+cnos use show
+cnos use --workspace api --profile stage
+cnos use --global-root ~/.cnos
+```

package/docs/cli/vault.mdx

@@ -13,4 +13,6 @@ 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.
+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. Successful auth writes a derived session key under `~/.cnos/secrets/sessions`, so later CNOS commands can reuse it across shells until you run `cnos vault logout <name>` or `cnos vault logout --all`. With `--store-keychain`, CNOS also stores the derived key in the OS keychain.

package/docs/cli/version.mdx

@@ -0,0 +1,21 @@
+---
+title: cnos version
+description: Print the installed CNOS CLI version.
+---
+
+# cnos version
+
+Use this command when you need the installed `@kitsy/cnos-cli` version string.
+
+## Usage
+
+```bash
+cnos version
+```
+
+## Examples
+
+```bash
+cnos version
+cnos --version
+```

package/docs/guides/profiles.mdx

@@ -11,7 +11,7 @@ Profiles are explicit overlays, not implicit defaults.
 cnos profile create stage
 cnos use --profile stage
 cnos value set app.apiBaseUrl https://api.stage
-cnos diff base stage
+cnos diff local stage
 ```
 
 Profiles inherit values from `base` by default. For a clean profile with no base fallback:

package/docs/reference/namespaces.mdx

@@ -22,7 +22,7 @@ Derived surfaces:
 Custom data namespaces can be:
 
 - read at runtime with `cnos('flags.upi_enabled')`
-- written through the CLI with `cnos set flags.upi_enabled false`
+- written through the CLI with `cnos define value flags.upi_enabled false` or namespace-specific commands where supported
 - promoted to `public.*` when the namespace is `shareable: true`
 - exported through `envMapping.explicit`
 

package/docs/reference/security.mdx

@@ -11,4 +11,5 @@ CNOS secret rules:
 - local vault material is encrypted outside the repo
 - reads are masked by default
 - browser and public outputs never expose `secret.*`
-- `vault auth` manages session-based access to local vaults
+- `vault auth` caches a reusable derived session key under `~/.cnos/secrets/sessions` until `cnos vault logout`
+- `--store-keychain` adds an OS keychain auth source that works across shells

package/manifest.yml

@@ -55,12 +55,20 @@ sidebar:
         label: cnos init
       - path: cli/onboard
         label: cnos onboard
+      - path: cli/use
+        label: cnos use
+      - path: cli/profile
+        label: cnos profile
       - path: cli/workspace
         label: cnos workspace
       - path: cli/value
         label: cnos value
       - path: cli/secret
         label: cnos secret
+      - path: cli/define
+        label: cnos define
+      - path: cli/list
+        label: cnos list
       - path: cli/read
         label: cnos read
       - path: cli/inspect
@@ -83,6 +91,8 @@ sidebar:
         label: cnos dump
       - path: cli/doctor
         label: cnos doctor
+      - path: cli/ui
+        label: cnos ui
       - path: cli/promote
         label: cnos promote
       - path: cli/vault
@@ -95,6 +105,12 @@ sidebar:
         label: cnos migrate
       - path: cli/drift
         label: cnos drift
+      - path: cli/help
+        label: cnos help
+      - path: cli/help-ai
+        label: cnos help-ai
+      - path: cli/version
+        label: cnos version
 
   - group: API Reference
     collapsed: true

package/package.json

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