@descix/cli 3.0.0 → 3.0.2

package/README.md

@@ -30,7 +30,8 @@ npm install -g @descix/cli
     ```
     An unconfigured workspace resolves to the declared default, PROD, and every network-bound
     command prints the environment, origin and source it resolved on stderr. For a local backend,
-    name the URL: `descix config set-env dev --url https://localhost:4000`.
+    name the URL: per run `descix --api-url https://localhost:4000 <command>`, or persistently
+    `descix config set-env local --url https://localhost:4000` (`set-env` refuses a known name).
 
 3.  **Check your status**:
     ```bash
@@ -111,21 +112,22 @@ The command is idempotent, so re-running it on a half-made app finishes the job.
   **server-side** as `{community}-{short}`; defaults to `--app`.
 - `--overwrite`: when creating, overwrite an existing app record intentionally.
 - `--kb <name>`: knowledge base name (default: `General`).
-- `-p, --path <dir>`: local app directory (default: auto-detected, else the current directory).
 
 **What it does, in order:**
 
 1.  **Creates the app** (only when `-c` is given and the app does not exist): the server composes
     the unique `app_id` and writes `Products/{app_id}` and `Community/{community}/Apps/{app_id}`.
     Every app is guaranteed a default knowledge base at creation.
-2.  **Registers it in `.descix/workspace.json`** if it is not already mapped.
+2.  **Writes it as `env.app` in `.descix/workspace.json`** — the current directory, the repo root,
+    becomes the workspace root. A workspace holds one app: a repo that already holds a different
+    app is refused, and so is a directory nested inside another DeSciX workspace.
 3.  **Scaffolds the app folder**: creates `site/`, `microservice/` and `assets/`, and writes
     `assets/system_instructions.md` and `assets/app_description.md` when they do not exist.
 4.  **Creates the knowledge base record** for Git-mode sync.
 
 It fails loud rather than guessing: initializing an app that does not exist without `-c` names the
 `-c` invocation that would create it; a `-c` that disagrees with the app's real community is
-refused; and `-p` against an already-mapped app names `descix app set-localpath` instead.
+refused.
 
 **Next step** — author a corpus manifest at `.descix/manifests/<kb_name>.json`, then
 `descix kb corpus sync -a <app_id>`.
@@ -147,7 +149,7 @@ descix site upload --env dev
 ### `descix site init`
 
 Copies the site scaffold — `index.html`, `app.js`, `styles.css`, `DeSciXAppSDK.js`, `README.md` —
-into the app's `site/` directory. The app must already be mapped in `.descix/workspace.json`.
+into the app's `site/` directory. The workspace must already hold the app (`env.app`, written by `descix app init`).
 
 - `-f, --force`: overwrite an existing `site/` folder.
 - `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.

package/agent-assets/guides/dynamic-site-pattern.md

@@ -57,13 +57,12 @@ Keeping the scaffold's shape is what lets the service keep inheriting platform b
 
 ## Configuration (`workspace.json`)
 
-One `env.products[]` entry, written by `descix app init` and `descix app set-port` (never by hand):
+The repo's `env.app`, written by `descix app init` (run from the repo root) and `descix app set-port` (never by hand):
 
 ```json
 {
   "appId": "my-community-my-dynamic-app",
   "communityId": "my-community",
-  "localPath": "my-dynamic-app",
   "kbId": "General",
   "microservice": { "port": 4001 }
 }

package/agent-assets/guides/knowledge-only-pattern.md

@@ -39,14 +39,13 @@ example; `kb/General/` also works if that's where content ends up, e.g. from `de
 
 ## Configuration (`workspace.json`)
 
-One `env.products[]` entry, written by `descix app init` (never by hand); no `site` and no
-`microservice` slot:
+The repo's `env.app`, written by `descix app init` (run from the repo root; never by hand); no `site`
+and no `microservice` slot:
 
 ```json
 {
   "appId": "my-community-my-docs",
   "communityId": "my-community",
-  "localPath": "my-docs",
   "kbId": "General"
 }
 ```

package/agent-assets/guides/microservice-pattern.md

@@ -82,14 +82,13 @@ out until something depends on the difference.
 
 ## Configuration (`workspace.json`)
 
-One `env.products[]` entry, written by `descix app init`, `descix app set-port` and (for the optional
-frontend) `descix app set-site` — never by hand:
+The repo's `env.app`, written by `descix app init` (run from the repo root), `descix app set-port` and
+(for the optional frontend) `descix app set-site` — never by hand:
 
 ```json
 {
   "appId": "my-community-my-service",
   "communityId": "my-community",
-  "localPath": "my-service",
   "kbId": "General",
   "site": { "static": "site" },
   "microservice": { "port": 4001 }

package/agent-assets/guides/static-site-pattern.md

@@ -44,20 +44,19 @@ my-site/
 
 ## Configuration (`workspace.json`)
 
-One `env.products[]` entry, written by `descix app init` and `descix app set-site` (never by hand):
+The repo's `env.app`, written by `descix app init` (run from the repo root) and `descix app set-site` (never by hand):
 
 ```json
 {
   "appId": "my-community-my-site",
   "communityId": "my-community",
-  "localPath": "my-site",
   "kbId": "General",
   "site": { "static": "site" }
 }
 ```
 
 For a framework dev server instead of files on disk, `descix app set-site -a <app_id> --port 3000`
-writes `"site": { "port": 3000 }`; the gateway proxies `/p/<app_id>` to it without rewriting paths,
+writes `"site": { "port": 3000 }`; `--static` takes a directory relative to the repo root (`site`, `site/dist`, `.`, `../scratch`) and refuses an absolute path; the gateway proxies `/p/<app_id>` to it without rewriting paths,
 so the framework's base path must be `/p/<app_id>/`.
 
 ## CLI Workflow

package/agent-assets/instructions/onboarding-flow.md

@@ -12,22 +12,21 @@ DeSciX uses **workspace.json** as the sole configuration file.
 
 Location: `{workspace_root}/.descix/workspace.json`
 
-Purpose: Maps local folders to DeSciX apps and stores all configuration.
+Purpose: names THE app this repository holds (v3 single-app: one repo, one app, and the repo root
+is the workspace root) and stores its configuration.
 
 ```json
 {
-  "version": "2.1",
+  "version": "3.0",
+  "type": "workspace",
   "env": {
-    "environment": "DEV",
-    "apiUrl": "https://dev.descix.net",
-    "products": [
-      {
-        "appId": "daita-appsdk",
-        "communityId": "daita",
-        "localPath": "daita/appsdk",
-        "kbId": "General"
-      }
-    ]
+    "environment": "PROD",
+    "apiUrl": "https://descix.net",
+    "app": {
+      "appId": "daita-appsdk",
+      "communityId": "daita",
+      "kbId": "General"
+    }
   },
   "driveConfig": {
     "base_folder_id": "..."
@@ -35,18 +34,19 @@ Purpose: Maps local folders to DeSciX apps and stores all configuration.
 }
 ```
 
-A `communities`-keyed block with no `env` block is the removed v1 shape — the loader refuses it:
-`v1 workspace format is not supported. Migrate to v2.1.`
+The loader refuses the retired shapes by name: a `communities`-keyed block with no `env` block
+(`v1 workspace format is not supported. Migrate to v3.`) and an `env.platform` / `env.products`
+block (`v2.1 multi-app workspace format is not supported. Migrate to v3 (single-app).`).
 
 **Used for:**
-- CLI auto-detection of community/app from current directory
+- CLI auto-detection of the app from the current directory (anywhere under the repo root)
 - `tell_me_how --scope project` to discover project-specific tools
-- MCP server to know which apps are in scope
+- MCP server to know which app is in scope
 - CLI to find the workspace root
 
 ### Key Principle
 
-**workspace.json** is the single configuration file that maps local folders to DeSciX apps and contains all sync configuration. It is created once at the workspace root during onboarding.
+**workspace.json** is the single configuration file for the app this repo holds. `descix app init` creates it at the repo root during onboarding; inside another DeSciX workspace it refuses — app repos are sibling checkouts, never nested.
 
 ---
 
@@ -66,8 +66,8 @@ START
 ├── Is this a fresh workspace (no .descix/workspace.json)?
 │   └── YES → Run Full Setup Flow
 │
-├── Does workspace.json exist but has unconfigured apps?
-│   └── YES → Run App Configuration Flow
+├── Does the user want to work on an app this repo does not hold?
+│   └── YES → Run App Configuration Flow (that app gets its own repo)
 │
 └── Is everything configured?
     └── YES → Ready for development
@@ -109,69 +109,51 @@ Service Slots:
 - {slot_count} available for microservice deployment
 ```
 
-### Step 3: Scan Workspace Folders
+### Step 3: Choose the App This Repo Holds
 
-Identify potential project folders:
-- Look for directories with `package.json`, `Cargo.toml`, `requirements.txt`
-- Ignore: `node_modules`, `.git`, `dist`, `build`, `.descix`
-- Note folders that are already registered in `workspace.json`
-
-### Step 4: Ask User About Folder Mappings
-
-Present options:
+One repo holds one app. Ask which of the user's apps this repository is for — or whether it is a
+new app.
 
 ```
-I see these folders in your workspace:
-- frontend/ (React app with build system)
-- backend/ (Node.js with Express)
-- docs/ (Markdown documentation)
-
-Would you like to map any to your apps?
-
-Suggested mappings based on folder contents:
-- frontend/ → {community}/pwa (Static Site)
-- backend/ → {community}/api (Microservice)
-- docs/ → {community}/docs (Knowledge Only)
-
-Which mappings should I create?
+This repository will hold ONE DeSciX app. Which one?
+- {community_id}/{app_id} ({app_name})
+- ...
+- a new app in {community_id}
 ```
 
-### Step 5: Create Configuration Files
+### Step 4: Create the Configuration
 
-For each mapping, create appropriate config:
+`workspace.json` is written by CLI verbs, never by hand. From the **repo root**:
 
-1. **workspace.json** (root level) — written by CLI verbs, never by hand:
-   ```bash
-   descix config init --env dev                          # creates workspace.json, pins env.apiUrl
-   descix app init -a {app_id} -c {community_id} -p {folder}   # adds env.products[] entry
-   ```
-   Each mapping becomes one `env.products[]` entry (`appId`, `communityId`, `localPath`, `kbId`).
+```bash
+descix config init --env prod                     # creates workspace.json, pins env.apiUrl
+descix app init -a {app_id}                       # an existing app: writes env.app
+descix app init -a {name} -c {community_id}       # a new app: creates it, then writes env.app
+```
 
 ## App Configuration Flow
 
 For apps that exist in entitlements but aren't configured locally:
 
-### Step 1: Identify Unconfigured Apps
+### Step 1: Identify the Other Apps
 
-Compare:
-- Apps from `fetch_my_purchases`
-- Mappings in `workspace.json`
+Compare the apps from `fetch_my_purchases` with `env.app` in this repo's `workspace.json`. Every
+other app lives in its own repository.
 
-### Step 2: Ask About Each Unconfigured App
+### Step 2: Ask About Each One
 
 ```
-You have these apps that aren't linked to local folders:
+You have these apps that this repository does not hold:
 - {community}/{app} - {description}
 
-Would you like to:
-1. Link to an existing folder
-2. Create a new folder for this app
-3. Skip for now
+Each app is its own repository. Would you like to:
+1. Clone or create that app's repo as a sibling of this one, then run `descix app init` from its root
+2. Skip for now
 ```
 
 ### Step 3: Determine Packaging Type
 
-For each folder being configured:
+For the app this repo holds:
 
 1. Read [guides/README.md](../guides/README.md) for the decision tree (Knowledge-Only / Static
    Site / Microservice / Dynamic Site)
@@ -186,7 +168,7 @@ For each folder being configured:
 After determining packaging type, ensure the folder follows the [Standard Folder Structure](./standard-folder-structure.md):
 
 ```
-{app_folder}/
+{repo_root}/
 ├── assets/                          # App identity (required)
 ├── .descix/manifests/<KB>.json      # Corpus manifest — required for RAG, see below
 ├── site/                            # Static site (required)
@@ -252,7 +234,7 @@ Your app structure is now ready. Run `descix app sync-assets` to sync.
 ## Key Principles
 
 ### Never Assume
-- Always ask before creating mappings
+- Always ask which app a repo holds before running `descix app init`
 - Present options, let user choose
 - Explain trade-offs of each packaging type
 
@@ -273,8 +255,8 @@ User hasn't purchased anything yet. Direct them to the PWA store.
 ### "App not in entitlements"
 User is trying to configure an app they don't own. Suggest purchase.
 
-### "Folder already configured"
-Check if configuration matches intended app. Offer to update or skip.
+### "This workspace already holds app '<id>'"
+A repo holds one app. Work on the other app in its own repo (a sibling checkout).
 
 ### Powch sign-in under `descix serve` fails ("User cancelled", or "WebAuthn is not supported on sites with TLS certificate errors")
 The gateway's dev certificate is not trusted. Run `descix dev-certs check`. If it is not trusted,
@@ -327,7 +309,7 @@ You have access to:
   - {app_2} - {app_2_status}
 
 Would you like me to help you:
-1. Link a folder to one of your apps
+1. Connect this repository to one of your apps
 2. Explore what you can do with a specific app
 3. Something else
 ```
@@ -343,9 +325,9 @@ Based on your purchases, here's what you can work with:
 | {name} | {role} | {count} |
 
 **Your Apps:**
-| App | Status | Local Folder |
-|-----|--------|--------------|
-| {app_id} | Configured / Not linked | {folder or "—"} |
+| App | Status | Local Repo |
+|-----|--------|------------|
+| {app_id} | Held by this repo / Not here | {repo or "—"} |
 
 Which app would you like to work on?
 ```
@@ -358,7 +340,7 @@ All done! Your app is configured.
 **Summary:**
 - App: {community}/{app}
 - Type: {packaging_type}
-- Folder: {folder_path}
+- Repo: {repo_root}
 
 **What you can do now:**
 - Use `tell_me_how` to discover tools

package/agent-assets/instructions/standard-folder-structure.md

@@ -101,25 +101,28 @@ descix kb corpus sync  # Walk the manifest's sources, chunk what changed, upsert
 
 ## Configuration Files
 
-### `.descix/workspace.json` (Root) — v2.1, the only supported format
+### `.descix/workspace.json` (Root) — v3 single-app, the only supported format
 
 ```json
 {
-  "version": "2.1",
+  "version": "3.0",
+  "type": "workspace",
   "env": {
-    "environment": "DEV",
-    "apiUrl": "https://dev.descix.net",
-    "products": [
-      { "appId": "my-dao-governance", "communityId": "my-dao", "localPath": "my-dao/governance", "kbId": "General" },
-      { "appId": "my-dao-treasury", "communityId": "my-dao", "localPath": "my-dao/treasury", "kbId": "General" }
-    ]
+    "environment": "PROD",
+    "apiUrl": "https://descix.net",
+    "app": { "appId": "my-dao-governance", "communityId": "my-dao", "kbId": "General" }
   }
 }
 ```
 
-Written by CLI verbs only — `descix config init`, `descix app init`, `descix app set-site`,
-`descix app set-port`. A `communities`-keyed block with no `env` block is the removed v1 shape and
-is refused on load: `v1 workspace format is not supported. Migrate to v2.1.`
+One repo, one app: `env.app` is THE app and the repo root is the workspace root. A second app
+(`my-dao-treasury`) is its own repo, a sibling checkout with its own `workspace.json`.
+
+Written by CLI verbs only — `descix config init`, `descix app init` (from the repo root; refused
+inside another workspace), `descix app set-site`, `descix app set-port`. The loader refuses the
+retired shapes by name: a `communities`-keyed block with no `env` block (`v1 workspace format is not
+supported. Migrate to v3.`) and an `env.platform` / `env.products` block (`v2.1 multi-app workspace
+format is not supported. Migrate to v3 (single-app).`).
 
 **Sync mode:** The CLI only performs **git-mode** operations (local files → corpus manifest →
 Pinecone, via `descix kb corpus sync`). Drive-mode (Drive → GCS → Pinecone, fully server-side) is

package/agent-assets/reference/app-creation.md

@@ -12,7 +12,7 @@ This document describes how apps and communities are created in the DeSciX platf
 
 **"One path to an app"**
 
-- **Apps:** `descix app init -a <name> -c <community> -p <dir>` creates the app on the platform (`create_app_for_community`, which composes the id `<community>-<short>` and guarantees the default KB) and registers it in the local workspace in one idempotent step. The PWA creates apps too; both reach the same server command. Entitlement checks run server-side either way.
+- **Apps:** `descix app init -a <name> -c <community>`, run from the app repo's root, creates the app on the platform (`create_app_for_community`, which composes the id `<community>-<short>` and guarantees the default KB) and writes it as the repo's `env.app` in one idempotent step. The PWA creates apps too; both reach the same server command. Entitlement checks run server-side either way.
 - **Communities:** created by platform admins only (`descix community create` is `[ADMIN]` and writes live Polygon). A developer builds inside an existing community.
 - **Development:** the CLI is the tool for the local workspace, content, and syncing to the cloud.
 
@@ -211,18 +211,19 @@ sequenceDiagram
 ## 4. Local Workspace
 
 There is no PWA "workspace builder" hand-off and no hydration step. The local workspace is built by
-CLI verbs, each writing one part of `.descix/workspace.json` (v2.1 — see `workspace-config.md`):
+CLI verbs, each writing one part of `.descix/workspace.json` (v3 single-app — see `workspace-config.md`). Run them
+from the repo root — it becomes the workspace root:
 
 ```bash
-descix config init --env dev                        # creates .descix/workspace.json, pins env.apiUrl
+descix config init --env prod                       # creates .descix/workspace.json, pins env.apiUrl
 descix login                                        # .descix/wallet.json (add it to .gitignore yourself)
-descix app init -a <name> -c <community> -p .       # env.products[] entry + site/ microservice/ assets/ + default KB
+descix app init -a <name> -c <community>           # env.app + site/ microservice/ assets/ + default KB
 descix app set-site -a <app_id> --static site       # what the gateway serves at /p/<app_id>
 descix app set-port -a <app_id> -p 4001             # required before descix microservice init
 ```
 
 `descix app init` creates `site/`, `microservice/` and `assets/` (with starter
-`system_instructions.md` and `app_description.md`) under the app directory. Knowledge-base content
+`system_instructions.md` and `app_description.md`) under the repo root. Knowledge-base content
 is whatever your corpus manifest names (`.descix/manifests/<KB>.json`); Drive content arrives via
 `descix drive pull -c <community> -a <app_id>` into `kb/<KB>/` and goes back via `descix drive push`.
 The CLI auto-detects the app from the directory you are standing in; `-c`/`-a` flags win over
@@ -304,13 +305,13 @@ async function copyFolderRecursive(sourceFolderId, destParentId, newName) {
 ### App Creation
 
 ```bash
-descix config init --env dev                       # pin the environment first (no default)
+descix config init --env prod                      # pin the environment first
 descix login                                       # device-code sign-in
-descix app init -a <name> -c <community> -p .      # create on the platform + register locally + default KB
+descix app init -a <name> -c <community>           # create on the platform + write env.app + default KB
 ```
 
 An app created in the PWA is initialized locally with the same verb, minus `-c`:
-`descix app init -a <app_id> -p .`.
+`descix app init -a <app_id>`, from the repo root.
 
 ### Post-Creation Commands
 

package/agent-assets/reference/architecture.md

@@ -111,31 +111,28 @@ folder of JSON chunk files to manage.
 
 ```json
 {
-  "version": "2.1",
+  "version": "3.0",
   "type": "workspace",
-  "workspaceRoot": "/path/to/workspace",
+  "workspaceRoot": "/path/to/daita-agent-repo",
   "env": {
-    "environment": "DEV",
-    "apiUrl": "https://dev.descix.net",
+    "environment": "PROD",
+    "apiUrl": "https://descix.net",
     "gateway": { "port": 5599 },
-    "products": [
-      {
-        "appId": "daita-agent",
-        "communityId": "daita",
-        "localPath": "daita/agent",
-        "kbId": "General",
-        "site": { "port": 3000 },
-        "microservice": { "port": 4001 }
-      }
-    ]
+    "app": {
+      "appId": "daita-agent",
+      "communityId": "daita",
+      "kbId": "General",
+      "site": { "port": 3000 },
+      "microservice": { "port": 4001 }
+    }
   },
   "driveConfig": { "base_folder_id": "1ABC..." }
 }
 ```
 
-Every key is written by a CLI verb (`descix config init --env …`, `descix app init`, `descix app set-site`, `descix app set-port`, …) — see `workspace-config.md` for the key → verb table. A `communities` block without `env` (the v1 shape) is refused on load.
+Every key is written by a CLI verb (`descix config init --env …`, `descix app init`, `descix app set-site`, `descix app set-port`, …) — see `workspace-config.md` for the key → verb table. One repo holds one app (`env.app`), and the repo root is the workspace root. A `communities` block without `env` (the v1 shape) and an `env.platform` / `env.products` block (the v2.1 multi-app shape) are refused on load.
 
-**Note:** `.descix.app/context.json` files are no longer used. All app configuration is stored in `workspace.json`. The CLI auto-detects app context from the current working directory by matching against registered app paths.
+**Note:** `.descix.app/context.json` files are no longer used. All app configuration is stored in `workspace.json`. The CLI auto-detects the app (`env.app`) when the current working directory is the repo root or below it.
 
 ---
 
@@ -169,7 +166,7 @@ The DeSciX CLI publishes content with one verb per plane. Each command resolves
 |---------|-------------|
 | `descix site init` | Copy site template to current app's `site/` folder |
 | `descix site upload` | Deploy site to GCS |
-| `descix app set-site -a <app_id> --port <port>` | Register the local dev-server port for the app's site (`env.products[].site.port`) |
+| `descix app set-site -a <app_id> --port <port>` | Register the local dev-server port for the app's site (`env.app.site.port`) |
 | `descix microservice init` | Copy microservice template to current app's `microservice/` folder |
 | `descix microservice register -r SERVICE_README.md` | Register microservice AND vectorize the README for `tell_me_how` discovery, in one step |
 

package/agent-assets/reference/local-dev.md

@@ -44,7 +44,7 @@ Instead of exposing implementation details (like GCS bucket URLs or specific por
 
 **Port:** `--port` → `env.gateway.port` → built-in `5173`, with `strictPort` on. The resolved port and **its source** are printed at startup. Do not assume `:5173`; give a checkout its own with `descix config set-gateway-port <n>`.
 
-**It serves ONE app, standalone — the shell opens ON your app instead of the store.** (Standalone is the INITIAL VIEW, not a reduced mode: the platform views stay reachable by navigation.) The app is detected from the directory you are standing in (the product whose `localPath` contains your cwd; longest match wins), or named with `--app <id>`. Nothing is persisted to `workspace.json`. When it cannot name an app it fails loud and lists the workspace's apps rather than falling back to the store.
+**It serves ONE app, standalone — the shell opens ON your app instead of the store.** (Standalone is the INITIAL VIEW, not a reduced mode: the platform views stay reachable by navigation.) The app is detected from the directory you are standing in (the app whose repo root contains your cwd — your own repo's `env.app`, or on a gateway workspace the `env.gateway` repo you are inside; longest match wins), or named with `--app <id>`. Nothing is persisted to `workspace.json`. When it cannot name an app it fails loud and lists the workspace's apps rather than falling back to the store.
 
 The binding is **served, not compiled**: the gateway answers `GET /__descix/app-binding.json` on the shell's own origin with `{mode:'standalone', appId, appUrl, source}`, and the shell reads it before it mounts. One pre-built cloud shell bundle therefore boots as the store on `descix.net` and as your app locally, with no rebuild. No binding (or a timeout, or a malformed body) means the store — the safe degradation. There is no `__STANDALONE_APP_ID__` build define; an app that builds itself standalone declares it at its own mount, `<AppShell appId="..." standalone>`.
 
@@ -71,10 +71,11 @@ the per-app host; keep `/p/` for the local gateway, where it is the correct and
 Typical app-dev session, in full:
 
 ```bash
-descix config set-env dev
-descix app init -a <app-id> -p ./my-app
-descix app set-site -a <app-id> --static .
-cd my-app && descix serve
+cd my-app-repo                                   # the repo root is the workspace root
+descix config init --env prod                    # pins env.apiUrl
+descix app init -a <app-id>                      # writes env.app
+descix app set-site -a <app-id> --static site    # relative to the repo root
+descix serve
 ```
 
 ### 3.1. Configuration: `.descix/workspace.json`
@@ -90,39 +91,43 @@ The `workspace.json` file is the **single source of truth** for local routing an
 
 | Key | Verb |
 |---|---|
-| `env.apiUrl` | `descix config set-env <dev\|demo\|prod> [--url <url>]` (env is positional) |
+| `env.apiUrl` | `descix config init --env dev\|demo\|prod`, or `descix config set-env <custom-name> --url <url>` (`--url` is refused on a known name) |
 | `env.gateway.port` | `descix config set-gateway-port <n\|none>` |
+| `env.gateway.shell` | `descix config gateway set-shell <repo\|none>` (gateway workspaces only) |
+| `env.gateway.appRepos[]` | `descix config gateway add-repo <repo>` / `remove-repo <repo>` (gateway workspaces only) |
 | `env.devCerts` | `descix config set-dev-certs --dir\|--cert\|--key\|--clear` |
 | `env.powchUrl` | `descix config set-powch-url <url\|none>` |
 | `env.siteUrl` | `descix config set-site-url <url\|none>` |
-| `env.products[]` | `descix app init` / `app set-site` / `app set-port` / `app set-localpath` / `app unmap` |
+| `env.app` | `descix app init` / `app set-site` / `app set-port` |
 
-#### Format (v2.1 — the only format)
+#### Format (v3 — single-app)
 
 ```json
 {
-  "version": "2.1",
+  "version": "3.0",
+  "type": "workspace",
   "env": {
-    "environment": "DEV",
-    "apiUrl": "https://dev.descix.net",
+    "environment": "PROD",
+    "apiUrl": "https://descix.net",
     "gateway": { "port": 5599 },
     "devCerts": { "dir": "/Users/you/.descix/dev-certs-san" },
-    "powchUrl": "https://powch.dev.descix.net/",
-    "platform": {
-      "appId": "daita",
-      "localPath": "DeSciX_Cloud",
-      "site": { "port": 5174 },
-      "microservice": { "port": 4000 }
-    },
-    "products": [
-      { "appId": "my-app", "localPath": "my-app", "site": { "static": "." } },
-      { "appId": "other-app", "localPath": "other", "site": { "port": 5599 }, "microservice": { "port": 4001 } }
-    ]
+    "app": {
+      "appId": "my-app",
+      "communityId": "egpt",
+      "kbId": "General",
+      "site": { "static": "site" },
+      "microservice": { "port": 4001 }
+    }
   }
 }
 ```
 
-`env.platform` is optional — an app developer has no platform checkout and needs none. A top-level `apiUrl` key (the v1 shape) fails loud naming its replacement.
+One repo, one app: `env.app` is THE app, and the repo root is the workspace root (`descix app init`
+from the repo root; inside another workspace it refuses). A gateway workspace that serves several
+local app repos lists them as `env.gateway.shell` and `env.gateway.appRepos[]` (paths relative to its
+root), and each listed repo carries its own v3 workspace — see `reference/workspace-config.md`. A
+top-level `apiUrl` key (the v1 shape) and an `env.platform` / `env.products` block (the v2.1
+multi-app shape) fail loud on load, naming the migration.
 
 #### KB sync is manifest-driven
 
@@ -164,15 +169,14 @@ the survey outranks the paper for exactly the reader who does not yet know the p
 
 | Target | 1. flag / env | 2. workspace | 3. global | 4. default |
 |---|---|---|---|---|
-| **API** | `--api-url` / `--env` / `DESCIX_API_URL` | `env.apiUrl`, then the legacy top-level `apiUrl` | `~/.descix/config.json` `api_url` | **the declared default: PROD** |
-| **Shell** (`/`) | `--site-url` | `env.siteUrl` | **the API origin, when the API is remote** | `env.platform.site.port`, else fail loud |
+| **API** | `--api-url` / `--env` / `DESCIX_API_URL` | `env.apiUrl` | `~/.descix/config.json` `api_url` | **the declared default: PROD** |
+| **Shell** (`/`) | `--site-url` | `env.siteUrl` | **the API origin, when the API is remote** | the `env.gateway.shell` repo's own `site.port`, else fail loud |
 
-**There is no port-derived step for the API.** An environment NAME never becomes an origin, and
-`env.platform.microservice.port` is not consulted: a local backend is a URL you name
-(`descix config set-env dev --url https://localhost:4000`, or `env.apiUrl` direct). **This is
+**There is no port-derived step for the API.** An environment NAME never becomes an origin: a
+local backend is a URL you name — per run with `descix --api-url https://localhost:4000 <command>`,
+or persistently under a custom name with `descix config set-env local --url https://localhost:4000`. **This is
 platform-dev mode** — running your own local backend (Scenario 2 below), not part of standard app
-development, which targets a hosted environment (`descix config set-env dev` with no `--url`, or
-`demo`/`prod`). The single owner of this order is `lib/origin.js::PRECEDENCE`; this table is a
+development, which targets a hosted environment (`descix config init --env dev|demo|prod`). The single owner of this order is `lib/origin.js::PRECEDENCE`; this table is a
 description of it, not a second copy of the rule.
 
 **Every resolution carries its SOURCE, and every network-bound command prints it on stderr** —
@@ -187,7 +191,7 @@ An unconfigured workspace resolving to PROD is the shipped product's declared ta
 fallback; what makes it legitimate is that it is announced. A configured-but-unusable origin is
 a different case and FAILS LOUD naming the remedy, rather than quietly becoming the default.
 
-The derived Shell rule is the important one: point the API at a cloud environment and the shell comes from that same origin, so one origin carries shell + app + `/apifront` with nothing else configured. A stale `env.platform.site` block does not hijack the root once the API is remote. Platform developers opt IN to a local shell by naming it (`--site-url https://localhost:5174` or `env.siteUrl`).
+The derived Shell rule is the important one: point the API at a cloud environment and the shell comes from that same origin, so one origin carries shell + app + `/apifront` with nothing else configured. A local shell repo listed in `env.gateway.shell` does not hijack the root once the API is remote. Platform developers opt IN to a local shell by naming it (`--site-url https://localhost:5174` or `env.siteUrl`).
 
 ### 3.3. The dev certificate and passkey sign-in
 
@@ -233,7 +237,7 @@ human it is unverified.
 
 ### Scenario 1: App Dev (the common case)
 *   **User**: App developer. No platform checkout.
-*   **Setup**: `descix config set-env dev`, `descix app init`, `descix app set-site`, `descix dev-certs check` (if not trusted, the human runs `descix dev-certs trust` once — §3.3), then `cd my-app && descix serve`.
+*   **Setup**: from the app repo's root, `descix config init --env prod`, `descix app init`, `descix app set-site`, `descix dev-certs check` (if not trusted, the human runs `descix dev-certs trust` once — §3.3), then `descix serve`.
 *   **Result**: one HTTPS origin. `/` → the cloud App Shell, `/apifront` → the cloud API, `/p/my-app` → your app, and the shell boots **standalone into your app** — its INITIAL VIEW is your app rather than the store, with the platform views still reachable from there.
 
 ### Scenario 2: Platform Dev ("Dogfooding")