@kitsy/cnos-docs 1.7.0 → 1.8.0

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

@@ -7,5 +7,5 @@ description: Scaffold a CNOS project structure in the current repo.
 
 ```bash
 cnos init
-cnos init --workspace api
+cnos workspace add api --package-root apps/api --extends base
 ```

package/docs/cli/workspace.mdx

@@ -0,0 +1,70 @@
+---
+title: cnos workspace
+description: Add, list, remove, scaffold, attach, and detach workspaces.
+---
+
+# cnos workspace
+
+Use `cnos workspace` when a repo has more than one app or package consuming the same CNOS root.
+
+## Add a workspace
+
+```bash
+cnos workspace add travel --package-root apps/travel --extends base
+```
+
+This updates `cnos.yml`, creates `.cnos/workspaces/travel`, and writes:
+
+```yaml
+# apps/travel/.cnosrc.yml
+root: ../../.cnos
+workspace: travel
+```
+
+## Onboard an older single-root project into workspace mode
+
+If a repo already has a flat `.cnos/values`, `.cnos/secrets`, `.cnos/env`, and `.cnos/profiles` tree, migrate it like this:
+
+```bash
+cnos workspace add main --onboard-current
+```
+
+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
+
+## List workspaces
+
+```bash
+cnos workspace list
+cnos workspace list --json
+```
+
+## Remove a workspace
+
+```bash
+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:
+
+```bash
+cnos workspace scaffold insights --package-root apps/insights --extends base
+```
+
+This follows the same creation path as `workspace add`.
+
+## 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

@@ -34,6 +34,14 @@ 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:
+
+```bash
+cnos workspace add main --package-root apps/main --extends base
+cnos workspace add insights --package-root apps/insights --extends base
+cnos workspace list
+```
+
 If your repo still expects env files, keep `.cnos` as the source of truth and generate them:
 
 ```bash

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

@@ -26,6 +26,13 @@ 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

package/docs/guides/workspaces.mdx

@@ -46,6 +46,43 @@ workspaces:
 
 This lets you keep shared values in `root` and override only what each app needs in `travel`, `food`, or other child workspaces.
 
+## Day-to-day workspace management
+
+Add a new app workspace:
+
+```bash
+cnos workspace add insights --package-root apps/insights --extends root
+cnos workspace add gallery --package-root apps/gallery --extends root
+```
+
+List what exists:
+
+```bash
+cnos workspace list
+```
+
+Remove one later:
+
+```bash
+cnos workspace remove gallery
+```
+
+## Migrating an older single-root repo into workspace mode
+
+If a repo was initialized earlier with:
+
+```bash
+cnos init
+```
+
+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:
+
+```bash
+cnos workspace add main --onboard-current
+```
+
+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

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"
 
 sidebar:
   - group: Getting Started
@@ -53,6 +53,8 @@ sidebar:
         label: Overview
       - path: cli/init
         label: cnos init
+      - 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.0",
   "description": "Source-of-truth CNOS documentation content for Astro Starlight and other static docs consumers.",
   "type": "module",
   "exports": {