@kitsy/cnos-docs 1.7.0 → 1.8.1

package/docs/api/create-cnos.mdx

@@ -54,3 +54,16 @@ runtime.registerRuntimeProvider('request', (key) => {
 
 const origin = runtime.value('app.origin');
 ```
+
+Workspace selection can come from three places:
+
+1. explicit `workspace` in `createCnos({ ... })`
+2. a package-local `.cnosrc.yml`
+3. the manifest default workspace
+
+Typical monorepo package anchor:
+
+```yaml
+root: ../../.cnos
+workspace: api
+```

package/docs/cli/init.mdx

@@ -1,11 +1,40 @@
 ---
 title: cnos init
-description: Scaffold a CNOS project structure in the current repo.
+description: Scaffold a CNOS project in regular mode or workspace mode.
 ---
 
 # cnos init
 
+Use regular mode first:
+
 ```bash
 cnos init
-cnos init --workspace api
 ```
+
+That creates a flat `.cnos/` tree with `profiles.default: local`.
+
+Create workspace mode explicitly:
+
+```bash
+cnos init --mode workspace
+```
+
+That creates:
+
+- `.cnos/workspaces/base`
+- `.cnosrc.yml` pointing to `./.cnos`
+- `.cnos-workspace.yml` with `workspace: base`
+
+Create child workspaces during init:
+
+```bash
+cnos init --mode workspace --workspaces api,web,agents
+```
+
+This creates `base` plus `api`, `web`, and `agents`, with each child extending `base`.
+
+## Notes
+
+- `base` is the default shared workspace convention.
+- `local` is the default profile.
+- If you already started in regular mode and later need multiple apps, use `cnos workspace enable` instead of reinitializing the repo.

package/docs/cli/onboard.mdx

@@ -0,0 +1,64 @@
+---
+title: cnos onboard
+description: Import existing env or config files into CNOS source storage and value.*.
+---
+
+# cnos onboard
+
+`cnos onboard` helps migrate existing config sources into CNOS without forcing an immediate app-code rewrite.
+
+## Auto-discover dotenv files
+
+```bash
+cnos onboard
+```
+
+By default CNOS scans the repo root for `.env`, `.env.<profile>`, and `.env.*.example` files.
+
+It copies those files into CNOS source storage and prints the proposed `value.*` mappings.
+
+## Explicit source formats
+
+```bash
+cnos onboard --env .env.production
+cnos onboard --yaml config/app.yml
+cnos onboard --json config/settings.json
+cnos onboard --toml config/app.toml
+cnos onboard --config config/app.yml
+```
+
+## Materialize values
+
+Interactive mode prompts before writing values.
+
+For automation:
+
+```bash
+cnos onboard --env .env.production --materialize
+cnos onboard --yaml config/db.yml --source-only
+```
+
+Non-interactive shells default to `--source-only` unless `--materialize` is passed explicitly.
+
+## Prefix imports
+
+```bash
+cnos onboard --yaml config/db.yml --prefix db --materialize
+```
+
+This maps:
+
+- `host` -> `value.db.host`
+- `port` -> `value.db.port`
+
+## Workspace-aware behavior
+
+- Regular mode imports into the implicit `base` layer.
+- Workspace mode imports into the selected workspace.
+- If no workspace is specified in workspace mode, CNOS defaults to `base` when it exists.
+
+Example:
+
+```bash
+cnos onboard --workspace api --env .env.api --materialize
+```

package/docs/cli/workspace.mdx

@@ -0,0 +1,64 @@
+---
+title: cnos workspace
+description: Enable workspace mode, add child workspaces, and manage attach or detach flows.
+---
+
+# cnos workspace
+
+Use `cnos workspace` when one CNOS root needs to serve more than one app or package.
+
+## Enable workspace mode
+
+If the repo started with a flat `.cnos/` tree:
+
+```bash
+cnos workspace enable
+```
+
+CNOS moves:
+
+- `.cnos/values` -> `.cnos/workspaces/base/values`
+- `.cnos/secrets` -> `.cnos/workspaces/base/secrets`
+- `.cnos/env` -> `.cnos/workspaces/base/env`
+- `.cnos/profiles` -> `.cnos/workspaces/base/profiles`
+
+and updates the root anchor to `workspace: base`.
+
+## Add a workspace
+
+```bash
+cnos workspace add travel --package-root apps/travel
+```
+
+If `base` exists, the new workspace automatically gets `extends: [base]`.
+
+Override that when needed:
+
+```bash
+cnos workspace add api --extends shared
+cnos workspace add sandbox --extends none
+```
+
+## List and remove
+
+```bash
+cnos workspace list
+cnos workspace remove gallery
+```
+
+## Scaffold wording
+
+If your team prefers scaffold wording:
+
+```bash
+cnos workspace scaffold insights --package-root apps/insights --extends base
+```
+
+## Detach and attach
+
+```bash
+cnos workspace detach --package-root apps/travel
+cnos workspace attach --package-root apps/travel
+```
+
+Detach makes a child package independent. Attach imports it back into the parent workspace model.

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

@@ -5,16 +5,19 @@ description: Go from zero to a running CNOS-backed project in a few minutes.
 
 # Quick Start
 
+Start with regular mode:
+
 ```bash
 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
 ```
 
+That gives you one flat `.cnos/` tree and `profiles.default: local`.
+
 In app code:
 
 ```ts
@@ -24,31 +27,18 @@ await cnos.ready();
 console.log(cnos('value.app.name'));
 ```
 
-For explicit creation:
+When the repo grows into multiple apps or packages, convert it instead of duplicating `.cnos`:
 
-```ts
-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'));
+```bash
+cnos workspace enable
+cnos workspace add main --package-root apps/main
+cnos workspace add insights --package-root apps/insights
+cnos workspace list
 ```
 
-If your repo still expects env files, keep `.cnos` as the source of truth and generate them:
+If the 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`
-
-For webpack/static bundles, build-time settings can come from CNOS too:
-
-```bash
-cnos set value dev.server.port 8800
-npm run dev
-```

package/docs/getting-started/your-first-project.mdx

@@ -33,3 +33,11 @@ cnos vault create default
 cnos vault auth default
 cnos secret set app.token super-secret --vault default
 ```
+
+If the project later becomes a monorepo, do not create a second `.cnos`. Convert the existing repo and add children:
+
+```bash
+cnos workspace enable
+cnos workspace add api --package-root apps/api
+cnos workspace add admin --package-root apps/admin
+```

package/docs/guides/workspaces.mdx

@@ -5,95 +5,97 @@ description: Use CNOS workspaces to model multiple apps inside one repo.
 
 # Workspaces and Monorepos
 
-For monorepos, keep one authoritative `.cnos/` tree at the repo root and put a `.cnosrc.yml` anchor in each consuming app or package.
+CNOS has two repo shapes:
 
-Repo root as both author and consumer:
+- regular mode: one flat `.cnos/` tree
+- workspace mode: `.cnos/workspaces/<id>/...`
 
-```yaml
-# .cnosrc.yml
-root: ./.cnos
-```
-
-Child app:
-
-```yaml
-# apps/travel/.cnosrc.yml
-root: ../../.cnos
-workspace: travel
-```
-
-Child app from a remote config repo:
+The intended progression is:
 
-```yaml
-root: git+https://github.com/org/config.git#v2.1.0
-workspace: travel
+```bash
+cnos init
+cnos workspace enable
+cnos workspace add api --package-root apps/api
+cnos workspace add web --package-root apps/web
 ```
 
-`.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.
+## Regular mode first
 
-Typical manifest shape:
+`cnos init` creates:
 
-```yaml
-workspaces:
-  default: root
-  items:
-    root: {}
-    travel:
-      extends: [root]
-    food:
-      extends: [root]
+```text
+.cnos/
+  values/
+  secrets/
+  env/
+  profiles/
 ```
 
-This lets you keep shared values in `root` and override only what each app needs in `travel`, `food`, or other child workspaces.
+This is effectively the shared base layer for a single-app repo.
 
-Read from an app package without passing a root manually:
+## Convert to workspace mode
 
-```ts
-import cnos from '@kitsy/cnos';
+When the repo grows:
 
-await cnos.ready();
-console.log(cnos('value.app.name'));
+```bash
+cnos workspace enable
 ```
 
-Override per command when needed:
+CNOS converts the flat tree into:
 
-```bash
-cnos list values --workspace travel
-cnos build server --workspace travel --profile prod --to apps/travel/.cnos-server.json
+```text
+.cnos/
+  workspaces/
+    base/
+      values/
+      secrets/
+      env/
+      profiles/
 ```
 
-## Runtime Projection
+`base` is the default shared workspace convention. It is not resolver magic; it is just the standard scaffolded root workspace.
 
-The authoring tree stays at repo root. Runtime consumers do not need the full `.cnos/` layout.
-
-For server packaging:
+## Add child workspaces
 
 ```bash
-cnos build server --workspace api-gateway --profile prod --to apps/api-gateway/.cnos-server.json
+cnos workspace add api --package-root apps/api
+cnos workspace add web --package-root apps/web
 ```
 
-`@kitsy/cnos` then auto-loads in this order:
+If `base` exists, CNOS defaults those children to `extends: [base]`.
 
-1. `__CNOS_PROJECTION__`
-2. `.cnos-server.json`
-3. full authoring resolution through `.cnosrc.yml`
+Resulting manifest shape:
 
-Browser packages keep using public projection through Vite, Next, webpack, or `@kitsy/cnos/build`.
+```yaml
+workspaces:
+  default: base
+  items:
+    base: {}
+    api:
+      extends: [base]
+    web:
+      extends: [base]
+```
 
-## Detach and Reattach
+## Anchors
 
-Detach a child package into a standalone CNOS root:
+Each consuming app or package should get a `.cnosrc.yml` anchor:
 
-```bash
-cnos workspace detach --package-root apps/travel
+```yaml
+# apps/api/.cnosrc.yml
+root: ../../.cnos
+workspace: api
 ```
 
-This materializes the effective config into `apps/travel/.cnos`, rewrites `apps/travel/.cnosrc.yml` to point to that local root, and stops inheriting from the parent repo.
+CNOS resolves from `.cnosrc.yml`, not by walking upward for `.cnos/` directories.
+
+## Onboard existing config sources
 
-Reattach it later:
+If the repo still has env or config files:
 
 ```bash
-cnos workspace attach --package-root apps/travel
+cnos onboard
+cnos onboard --workspace api --env .env.api --materialize
 ```
 
-This imports the standalone child config back into the parent workspace model, archives the detached `.cnos`, and restores the package anchor.
+Use onboarding to pull source files into CNOS first, then move app code to direct CNOS reads later.

package/manifest.yml

@@ -1,7 +1,7 @@
 product: cnos
 title: CNOS Documentation
 tagline: Configuration orchestration for apps, monorepos, and deployment pipelines
-version: "1.7"
+version: "1.8.1"
 
 sidebar:
   - group: Getting Started
@@ -53,6 +53,10 @@ sidebar:
         label: Overview
       - path: cli/init
         label: cnos init
+      - path: cli/onboard
+        label: cnos onboard
+      - path: cli/workspace
+        label: cnos workspace
       - path: cli/value
         label: cnos value
       - path: cli/secret

package/package.json

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