@kitsy/cnos-docs 1.8.0 → 1.8.1

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 workspace add api --package-root apps/api --extends base
 ```
+
+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

@@ -1,55 +1,51 @@
 ---
 title: cnos workspace
-description: Add, list, remove, scaffold, attach, and detach workspaces.
+description: Enable workspace mode, add child workspaces, and manage attach or detach flows.
 ---
 
 # cnos workspace
 
-Use `cnos workspace` when a repo has more than one app or package consuming the same CNOS root.
+Use `cnos workspace` when one CNOS root needs to serve more than one app or package.
 
-## Add a workspace
+## Enable workspace mode
+
+If the repo started with a flat `.cnos/` tree:
 
 ```bash
-cnos workspace add travel --package-root apps/travel --extends base
+cnos workspace enable
 ```
 
-This updates `cnos.yml`, creates `.cnos/workspaces/travel`, and writes:
+CNOS moves:
 
-```yaml
-# apps/travel/.cnosrc.yml
-root: ../../.cnos
-workspace: travel
-```
+- `.cnos/values` -> `.cnos/workspaces/base/values`
+- `.cnos/secrets` -> `.cnos/workspaces/base/secrets`
+- `.cnos/env` -> `.cnos/workspaces/base/env`
+- `.cnos/profiles` -> `.cnos/workspaces/base/profiles`
 
-## Onboard an older single-root project into workspace mode
+and updates the root anchor to `workspace: base`.
 
-If a repo already has a flat `.cnos/values`, `.cnos/secrets`, `.cnos/env`, and `.cnos/profiles` tree, migrate it like this:
+## Add a workspace
 
 ```bash
-cnos workspace add main --onboard-current
+cnos workspace add travel --package-root apps/travel
 ```
 
-CNOS will:
-
-1. move the existing flat config folders into `.cnos/workspaces/main`
-2. rewrite the root anchor to `workspace: main`
-3. keep the repo in one authoritative `.cnos` root
+If `base` exists, the new workspace automatically gets `extends: [base]`.
 
-## List workspaces
+Override that when needed:
 
 ```bash
-cnos workspace list
-cnos workspace list --json
+cnos workspace add api --extends shared
+cnos workspace add sandbox --extends none
 ```
 
-## Remove a workspace
+## List and remove
 
 ```bash
+cnos workspace list
 cnos workspace remove gallery
 ```
 
-CNOS removes the manifest entry and deletes `.cnos/workspaces/gallery`. It refuses to remove the current default workspace until you change `workspaces.default`.
-
 ## Scaffold wording
 
 If your team prefers scaffold wording:
@@ -58,8 +54,6 @@ If your team prefers scaffold wording:
 cnos workspace scaffold insights --package-root apps/insights --extends base
 ```
 
-This follows the same creation path as `workspace add`.
-
 ## Detach and attach
 
 ```bash

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,39 +27,18 @@ await cnos.ready();
 console.log(cnos('value.app.name'));
 ```
 
-For explicit creation:
-
-```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'));
-```
-
-If your repo grows into multiple apps or packages, switch to workspace mode instead of duplicating `.cnos` trees:
+When the repo grows into multiple apps or packages, convert it instead of duplicating `.cnos`:
 
 ```bash
-cnos workspace add main --package-root apps/main --extends base
-cnos workspace add insights --package-root apps/insights --extends base
+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

@@ -26,13 +26,6 @@ cnos profile create stage
 cnos use --profile stage
 ```
 
-If this later becomes a monorepo, do not create a second `.cnos`. Add workspaces instead:
-
-```bash
-cnos workspace add api --package-root apps/api --extends base
-cnos workspace add admin --package-root apps/admin --extends base
-```
-
 Create a local vault and authenticate it:
 
 ```bash
@@ -40,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,132 +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:
+The intended progression is:
 
-```yaml
-# apps/travel/.cnosrc.yml
-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
+```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.
 
-## Day-to-day workspace management
+## Convert to workspace mode
 
-Add a new app workspace:
+When the repo grows:
 
 ```bash
-cnos workspace add insights --package-root apps/insights --extends root
-cnos workspace add gallery --package-root apps/gallery --extends root
+cnos workspace enable
 ```
 
-List what exists:
+CNOS converts the flat tree into:
 
-```bash
-cnos workspace list
+```text
+.cnos/
+  workspaces/
+    base/
+      values/
+      secrets/
+      env/
+      profiles/
 ```
 
-Remove one later:
+`base` is the default shared workspace convention. It is not resolver magic; it is just the standard scaffolded root workspace.
 
-```bash
-cnos workspace remove gallery
-```
-
-## Migrating an older single-root repo into workspace mode
-
-If a repo was initialized earlier with:
+## Add child workspaces
 
 ```bash
-cnos init
+cnos workspace add api --package-root apps/api
+cnos workspace add web --package-root apps/web
 ```
 
-and the current config still lives directly under `.cnos/values`, `.cnos/secrets`, `.cnos/env`, and `.cnos/profiles`, move that existing config into a real workspace with:
+If `base` exists, CNOS defaults those children to `extends: [base]`.
 
-```bash
-cnos workspace add main --onboard-current
-```
+Resulting manifest shape:
 
-CNOS will move the physical folders into `.cnos/workspaces/main` and rewrite the local anchor so the repo now behaves as a workspace-aware project.
-
-Read from an app package without passing a root manually:
-
-```ts
-import cnos from '@kitsy/cnos';
-
-await cnos.ready();
-console.log(cnos('value.app.name'));
-```
-
-Override per command when needed:
-
-```bash
-cnos list values --workspace travel
-cnos build server --workspace travel --profile prod --to apps/travel/.cnos-server.json
+```yaml
+workspaces:
+  default: base
+  items:
+    base: {}
+    api:
+      extends: [base]
+    web:
+      extends: [base]
 ```
 
-## Runtime Projection
-
-The authoring tree stays at repo root. Runtime consumers do not need the full `.cnos/` layout.
+## Anchors
 
-For server packaging:
+Each consuming app or package should get a `.cnosrc.yml` anchor:
 
-```bash
-cnos build server --workspace api-gateway --profile prod --to apps/api-gateway/.cnos-server.json
+```yaml
+# apps/api/.cnosrc.yml
+root: ../../.cnos
+workspace: api
 ```
 
-`@kitsy/cnos` then auto-loads in this order:
-
-1. `__CNOS_PROJECTION__`
-2. `.cnos-server.json`
-3. full authoring resolution through `.cnosrc.yml`
-
-Browser packages keep using public projection through Vite, Next, webpack, or `@kitsy/cnos/build`.
-
-## Detach and Reattach
-
-Detach a child package into a standalone CNOS root:
-
-```bash
-cnos workspace detach --package-root apps/travel
-```
+CNOS resolves from `.cnosrc.yml`, not by walking upward for `.cnos/` directories.
 
-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.
+## 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.8"
+version: "1.8.1"
 
 sidebar:
   - group: Getting Started
@@ -53,6 +53,8 @@ sidebar:
         label: Overview
       - path: cli/init
         label: cnos init
+      - path: cli/onboard
+        label: cnos onboard
       - path: cli/workspace
         label: cnos workspace
       - path: cli/value

package/package.json

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