@descix/cli 2.0.4 → 3.0.1

package/agent-assets/reference/mcp-integration.md

@@ -303,18 +303,17 @@ User asks question
 When `--scope project` is used:
 
 1. CLI/MCP loads `workspace.json`
-2. Extracts configured communities and apps
-3. Filters `tell_me_how` results to only tools applicable to those apps
+2. Extracts the app this repo holds (`env.app`)
+3. Filters `tell_me_how` results to only tools applicable to that app
 4. Returns focused recommendations
 
 ```javascript
-// workspace.json (v2.1)
+// workspace.json (v3 single-app)
 {
+  "version": "3.0",
   "env": {
-    "apiUrl": "https://dev.descix.net",
-    "products": [
-      { "appId": "daita-agent", "communityId": "daita", "localPath": ".", "kbId": "General" }
-    ]
+    "apiUrl": "https://descix.net",
+    "app": { "appId": "daita-agent", "communityId": "daita", "kbId": "General" }
   }
 }
 
@@ -338,11 +337,11 @@ descix tell-me-how "How do I sync my knowledge base?"
 
 ### 6.2 workspace.json from Hydration
 
-`descix config init --env …` creates `workspace.json`; `descix app init` adds the app's `env.products[]` entry; no verb writes `driveConfig.base_folder_id` — set it in `.descix/workspace.json` when you use `descix drive pull/push`:
+`descix config init --env …` creates `workspace.json`; `descix app init` (from the repo root) writes the app's `env.app`; no verb writes `driveConfig.base_folder_id` — set it in `.descix/workspace.json` when you use `descix drive pull/push`:
 
 ```javascript
 {
-  "env": { "apiUrl": "https://dev.descix.net", "products": [ /* one entry per app */ ] },
+  "env": { "apiUrl": "https://descix.net", "app": { /* THE app this repo holds */ } },
   "driveConfig": {
     "base_folder_id": "..."  // Only used by `descix drive pull/push` — unrelated to tell_me_how scope
   }

package/agent-assets/reference/workspace-config.md

@@ -1,33 +1,44 @@
 # Workspace Configuration Guide
 
-`.descix/workspace.json` is the CLI's only local configuration file. It is **version 2.1**, it is
-written **only by CLI verbs**, and the loader refuses the shapes that hand edits produce. This page
-is the schema and the verb that owns each key.
+`.descix/workspace.json` is the CLI's only local configuration file. It is **version 3.0
+(single-app)**: one repo, one app, and the repo root IS the workspace root. It is written **only by
+CLI verbs**, and the loader refuses the shapes that hand edits produce. This page is the schema and
+the verb that owns each key.
 
 ---
 
-## 1. Format (v2.1 — the only format)
+## 1. Format (v3 — the only format)
+
+An app repo's workspace holds exactly one app, `env.app`:
 
 ```json
 {
-  "version": "2.1",
+  "version": "3.0",
   "type": "workspace",
-  "workspaceRoot": "/path/to/workspace",
+  "workspaceRoot": "/path/to/my-app-repo",
   "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",
-    "products": [
-      { "appId": "egpt-mydocs", "communityId": "egpt", "localPath": ".", "kbId": "General", "site": { "static": "site" } },
-      { "appId": "egpt-tool", "communityId": "egpt", "localPath": "tool", "kbId": "General", "site": { "port": 5174 }, "microservice": { "port": 4001 } }
-    ]
+    "powchUrl": "https://powch.descix.net",
+    "app": {
+      "appId": "egpt-mydocs",
+      "communityId": "egpt",
+      "kbId": "General",
+      "site": { "static": "site" },
+      "microservice": { "port": 4001 }
+    }
   },
   "driveConfig": { "base_folder_id": "1ABC..." }
 }
 ```
 
+Run `descix app init` **from the repo root** — it writes `env.app` and makes that directory the
+workspace root. Inside another DeSciX workspace it refuses (`This directory is nested inside another
+DeSciX workspace`) rather than registering into the parent: keep app repos as sibling checkouts. A
+workspace that already holds a different app refuses a second one — that app gets its own repo.
+
 | Key | Meaning | Owned by |
 |---|---|---|
 | `env.environment` | `DEV`, `DEMO` or `PROD` | `descix config init --env dev\|demo\|prod` |
@@ -36,29 +47,53 @@ is the schema and the verb that owns each key.
 | `env.devCerts` | `dir`, or `cert` + `key` — the TLS pair for the gateway and every app behind it; unset means the SDK's shipped pair. Passkey sign-in needs it trusted: `descix dev-certs check`, then the human runs `descix dev-certs trust` (see `reference/local-dev.md` §3.3) | `descix config set-dev-certs --dir\|--cert\|--key\|--clear` |
 | `env.powchUrl` | Powch's own origin (optional; Powch is cross-origin from the shell by design) | `descix config set-powch-url <url>` |
 | `env.siteUrl` | the App Shell origin the gateway proxies `/` to (optional; default is the API origin) | `descix config set-site-url <url>` |
-| `env.products[]` | one entry per app in this workspace, see below | `descix app init`, `app set-site`, `app set-port`, `app set-localpath`, `app unmap` |
-| `env.platform` | the platform shell's own entry — platform contributors only; an app developer has none | platform runbook |
+| `env.app` | THE app this repo holds, see below | `descix app init`, `app set-site`, `app set-port` |
 | `driveConfig.base_folder_id` | the Drive base folder for `descix drive pull/push` | no verb; set it in `.descix/workspace.json` |
 
-A product entry:
+`env.app`:
 
 | Field | Meaning | Written by |
 |---|---|---|
 | `appId` | the platform app id (`<community>-<short>`) | `descix app init` |
 | `communityId` | the app's community; stored so context detection can name it | `descix app init` |
-| `localPath` | the app directory, relative to `workspaceRoot` (`.` when the workspace root is the app) | `descix app init -p`, `descix app set-localpath` |
 | `kbId` | the default knowledge base (default `General`) | `descix app init --kb` |
-| `site.static` | a directory under `localPath` served from disk at `/p/<appId>/` | `descix app set-site --static <dir>` |
+| `site.static` | a directory relative to the workspace root (the repo root) served from disk at `/p/<appId>/` — `site`, `site/dist`, `.` (the root itself) or `../scratch`; an absolute path is refused at the write and on read | `descix app set-site --static <dir>` |
 | `site.port` | a framework dev server the gateway proxies `/p/<appId>` to (no path rewrite) | `descix app set-site --port <n>` |
+| `site.protocol` | `http` or `https` — the dev server's scheme (dev-server mode only; default `https`) | `descix app set-site --port <n> --protocol <scheme>` |
 | `microservice.port` | the local port the gateway proxies `/s/<appId>` to; `descix microservice init` requires it | `descix app set-port -p <n>` |
 
 Sites and services are started by you (or your framework); the CLI does not store or run a dev command.
 
+### Gateway workspaces
+
+A workspace that serves several local app repos behind one `descix serve` (platform contributors)
+lists them under `env.gateway`, with paths relative to its own root:
+
+```json
+"gateway": { "port": 5599, "shell": "../platform-shell", "appRepos": ["../my-app", "../other-app"] }
+```
+
+| Key | Meaning | Verb |
+|---|---|---|
+| `env.gateway.shell` | the repo whose app the gateway serves at `/` | `descix config gateway set-shell <repo\|none>` |
+| `env.gateway.appRepos[]` | repos whose apps the gateway serves at `/p/<appId>` | `descix config gateway add-repo <repo>`, `descix config gateway remove-repo <repo>` |
+
+Run the verbs from the gateway workspace's root; `<repo>` is relative to that root. Each listed repo
+holds its OWN v3 workspace (`descix app init` in that repo), and that file is the sole authority on
+its app's id, site and microservice — the gateway workspace never restates them. The verbs refuse,
+writing nothing: a run in a single-app workspace (one that holds `env.app`), an absolute path, a
+repo with no `.descix/workspace.json` or no `env.app`, a repo already listed (or already the
+shell), one appId listed twice, and `remove-repo` of a repo that is not listed. `descix serve`
+applies the same checks when it reads the file.
+
 ### Refused shapes
 
 - A `communities` block with no `env` block — the v1 format — fails on load: `v1 workspace format is
-  not supported. Migrate to v2.1.` The file is left untouched; re-create it with `descix config init
+  not supported. Migrate to v3.` The file is left untouched; re-create it with `descix config init
   --env …` and `descix app init`.
+- An `env.platform` or `env.products` block — the multi-app format — fails on load: `v2.1 multi-app
+  workspace format is not supported. Migrate to v3 (single-app).` The file is left untouched; run
+  `descix config init --env …` and `descix app init -a <app_id>` from each app repo's own root.
 - A top-level `apiUrl` key is refused by name; the origin lives at `env.apiUrl` and nowhere else.
 
 ---
@@ -143,14 +178,13 @@ The git path (`descix kb corpus sync`) needs none of this.
 
 ## 6. CLI Context Resolution
 
-`WorkspaceConfig.detectContext()` matches your current directory against every product's resolved
-`localPath` (longest match wins) and returns `{ communityId, appId, kbId }` from that entry —
-`communityId` is `null` for an entry registered by a CLI that did not yet store it.
+`WorkspaceConfig.detectContext()` returns `{ communityId, appId, kbId }` from `env.app` when your
+current directory is the workspace root or anywhere below it.
 `resolveContextWithOptions()` lets explicit `-c` / `-a` / `-k` flags win over detection.
 
 ```bash
-# From inside an app directory — detected
-cd my-app
+# From inside the app repo — detected
+cd my-app-repo
 descix kb corpus sync
 
 # From anywhere — flags
@@ -164,7 +198,7 @@ descix site status -c egpt -a egpt-mydocs      # site status/list need both when
 
 | Concept | Owner |
 |---|---|
-| Workspace loading, the v2.1 writer, app registration, context detection | `WorkspaceConfig`, internal to `@descix/cli` |
+| Workspace loading, the v3 writer, app registration, context detection | `WorkspaceConfig`, internal to `@descix/cli` |
 | Origin resolution precedence | flag → `DESCIX_API_URL` → `env.apiUrl` → default (`descix config` commands) |
 | User-level settings (`~/.descixrc`) | `GlobalConfig`, internal to `@descix/cli` |
 | `.descix/wallet.json` | written by `descix login` |

package/bin/descix.js

@@ -7,7 +7,7 @@
  * Combines CLI and MCP functionality with unified authentication.
  */
 
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
@@ -1482,7 +1482,7 @@ appCommand
 appCommand
   .command('set-port')
   .description('Set the microservice port for this workspace\'s app (writes env.app.microservice.port). Pass "n" to remove.')
-  .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
+  .requiredOption('-a, --app <app_id>', 'App ID (must be this workspace\'s app, env.app)')
   .requiredOption('-p, --port <port>', 'Microservice port number (1-65535), or "n" to remove')
   .action(async (options) => {
     try {
@@ -1503,7 +1503,7 @@ appCommand
       }
 
       // setMicroservicePort mutates the live env entry and saves — and hard-fails (canonical
-      // "not mapped in workspace.json" error) for an unmapped app, surfaced in the catch below.
+      // "is not this workspace's app" error) for any other app id, surfaced in the catch below.
       await workspaceConfig.setMicroservicePort(appId, portNum);
 
       console.log(chalk.green(`\n✓ Microservice port set for ${appId}`));
@@ -1520,9 +1520,9 @@ appCommand
 //
 // Canonical write path for an app's site.{} slot in workspace.json. TWO MODES, one active
 // per write:
-//   static mode (--static):      site.static — the relative dir (under the app's localPath;
-//                                "." = the localPath itself) the gateway's staticSitePlugin
-//                                serves at /p/{appId}/.
+//   static mode (--static):      site.static — the dir relative to the workspace root (the
+//                                repo root; "." = the root itself) the gateway's
+//                                staticSitePlugin serves at /p/{appId}/.
 //   dev-server mode (--port):    site.port [+ site.protocol] — the local dev server the
 //                                gateway proxies /p/{appId} to (vite-style hotserving).
 // Setting one mode CLEARS the other's fields; passing BOTH flags in one invocation is the
@@ -1533,8 +1533,8 @@ appCommand
 appCommand
   .command('set-site')
   .description("Set this workspace app's site config (env.app.site). One active mode per write: --static <dir> (built site served at /p/<app>/) or --port <n> [--protocol http|https] (dev server proxied at /p/<app>); setting one clears the other. Pass both flags together to keep both — the gateway then serves the dev server (site.port wins). --unset clears site.{} entirely.")
-  .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
-  .option('--static <path>', 'Static mode: relative dir under the app localPath (e.g. "site"; "." = the localPath itself). Alone, it clears site.port and site.protocol (one active mode per write).')
+  .requiredOption('-a, --app <app_id>', 'App ID (must be this workspace\'s app, env.app)')
+  .option('--static <path>', 'Static mode: a dir relative to the workspace root (the repo root), e.g. "site" or "../scratch"; "." = the root itself. An absolute path is refused. Alone, it clears site.port and site.protocol (one active mode per write).')
   .option('--port <port>', 'Dev-server mode: proxy /p/<app> to your local dev server on this port (1-65535). Alone, it clears site.static. With --static in the same call, both are kept and the gateway serves the dev server.')
   .option('--protocol <scheme>', 'Dev-server upstream scheme: "http" or "https" (default https when unset). Dev-server mode only — requires site.port. A wrong scheme fails loud at the gateway (502); there is no auto-detection.')
   .option('--unset', 'Remove site.static, site.port and site.protocol for the app, clearing the site.{} slot')
@@ -1558,13 +1558,9 @@ appCommand
 
       const fields = {};
 
-      if (options.static !== undefined) {
-        if (typeof options.static !== 'string' || options.static.trim() === '') {
-          console.error(chalk.red('\n❌ --static requires a non-empty relative path (e.g. "site" or ".").\n'));
-          process.exit(1);
-        }
-        fields.static = options.static;
-      }
+      // The --static path rule has ONE owner (assertSiteStatic, applied in setStaticSite);
+      // a refusal surfaces through the catch below.
+      if (options.static !== undefined) fields.static = options.static;
 
       if (options.port !== undefined) {
         const portNum = parseInt(options.port, 10);
@@ -1584,7 +1580,7 @@ appCommand
       }
 
       // setStaticSite applies ONE-ACTIVE-MODE-PER-WRITE and saves — it hard-fails (canonical
-      // "not mapped in workspace.json" error, or protocol-without-port) in the catch below.
+      // "is not this workspace's app" error, or protocol-without-port) in the catch below.
       await workspaceConfig.setStaticSite(appId, fields);
 
       console.log(chalk.green(`\n✓ site config set for ${appId}`));
@@ -1622,7 +1618,7 @@ appCommand
 appCommand
   .command('open')
   .description('Resolve (and optionally open) an app\'s local gateway dev URL. Hard-fails if the app has no site config.')
-  .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json with a site)')
+  .requiredOption('-a, --app <app_id>', 'App ID (an app this workspace serves, with a site)')
   .option('--open', 'Open the resolved URL in the default browser')
   .action(async (options) => {
     try {
@@ -1663,7 +1659,8 @@ appCommand
 // ============ App: set-default-model (WS-CONFIG-BOOTSTRAP-FIX item #10) ============
 //
 // Updates Community/{c}/Apps/{a}.default_app_model. Per CEO inheritance chain:
-//   options.model > kb.kb_model_override > app.default_app_model > levelConfig.model > DEFAULT_AI_MODEL
+//   request intelligence_level > kb.kb_model_override > app.default_app_model > the level's model
+// (there is no separate default model: the default is the model of DEFAULT_INTELLIGENCE_LEVEL)
 //
 // --clear deletes the field via FieldValue.delete() (NOT null) so the resolver falls through
 // cleanly to per-level platform defaults.
@@ -1672,13 +1669,13 @@ appCommand
   .command('set-default-model')
   .description('Set or clear App.default_app_model (model used when no KB override is set)')
   .requiredOption('-a, --app <app_id>', 'App ID (e.g. unk-cos)')
-  .option('-m, --model <model_name>', 'Gemini model name (e.g. gemini-3.1-flash-lite). Mutually exclusive with --clear.')
+  .option('-m, --model <model_name>', 'Model name (e.g. gemini-3.8-flash). Mutually exclusive with --clear.')
   .option('--clear', 'Delete App.default_app_model via FieldValue.delete() (resets to platform-default inheritance)')
   .addHelpText('after', `
-NOTE: Pinning a "Pro" model (e.g., gemini-2.5-pro, gemini-3.1-pro-preview) as
-an app or KB override will fail at L1 — these models require thinking mode and
-reject L1's thinkingBudget=0. If you intend an L1-compatible override, use a
-"Flash" model (gemini-2.5-flash, gemini-3.1-flash-lite, gemini-3-flash-preview).
+NOTE: A pinned model is paired with a thinking_level, and which levels exist is a
+property of the MODEL. The server refuses, by name, a (model, thinking_level) pair
+it does not support. The current intelligence levels (each names its own model and
+thinking_level) are printed under "Per-level" after this command runs.
 `)
   .action(async (options) => {
     try {
@@ -1820,12 +1817,12 @@ kbCommand
   .description('Set KB.kb_model_override (per-KB model selection)')
   .requiredOption('-a, --app <app_id>', 'App ID')
   .requiredOption('-k, --kb <kb_name>', 'KB name')
-  .requiredOption('-m, --model <model_name>', 'Gemini model name (e.g. gemini-2.5-pro)')
+  .requiredOption('-m, --model <model_name>', 'Model name (e.g. gemini-3.8-flash)')
   .addHelpText('after', `
-NOTE: Pinning a "Pro" model (e.g., gemini-2.5-pro, gemini-3.1-pro-preview) as
-an app or KB override will fail at L1 — these models require thinking mode and
-reject L1's thinkingBudget=0. If you intend an L1-compatible override, use a
-"Flash" model (gemini-2.5-flash, gemini-3.1-flash-lite, gemini-3-flash-preview).
+NOTE: A pinned model is paired with a thinking_level, and which levels exist is a
+property of the MODEL. The server refuses, by name, a (model, thinking_level) pair
+it does not support. The current intelligence levels (each names its own model and
+thinking_level) are printed under "Per-level" after this command runs.
 `)
   .action(async (options) => {
     try {
@@ -3360,11 +3357,15 @@ program
   .option('--apps <ids>', 'Comma-separated app IDs for cross-app query')
   .option('--level <n>', 'Intelligence level (1-5)', parseInt)
   .option('--model <name>', 'Explicit model override')
-  .option('--thinking <budget>', 'Thinking token budget (-1=dynamic, 0=off, N=fixed)', parseInt)
+  .option('--thinking-level <level>', 'Thinking level for this call: minimal, low, medium or high. The server refuses a level the resolved model does not support.')
+  .addOption(new Option('--thinking <budget>').hideHelp())
   .option('--tokens', 'Show token usage in response footer')
   .option('--new', 'Start a new conversation (clear session)')
   .action(async (questionArgs, options) => {
     try {
+      if (options.thinking !== undefined) {
+        throw new Error('--thinking (a token budget) was removed. Use --thinking-level <level>, one of minimal, low, medium, high.');
+      }
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
 
@@ -3390,7 +3391,7 @@ program
           user_input: question,
           intelligence_level: options.level,
           model: options.model,
-          thinking_budget: options.thinking,
+          thinking_level: options.thinkingLevel,
           streaming: false
         });
         const result = response.message || response;
@@ -3497,7 +3498,7 @@ program
         streaming: false,
         intelligence_level: options.level,
         model: options.model,
-        thinking_budget: options.thinking,
+        thinking_level: options.thinkingLevel,
       };
 
       if (useMultiKb) {
@@ -3723,6 +3724,51 @@ configCommand
     }
   });
 
+// The gateway workspace's repo list (env.gateway.shell, env.gateway.appRepos[]). One writer:
+// WorkspaceConfig.setGatewayRepo(), which validates with the gateway's own reader.
+const configGatewayCommand = configCommand
+  .command('gateway')
+  .description('Write a gateway workspace\'s repo list (env.gateway.shell, env.gateway.appRepos[]) — never hand-edit it')
+  .addHelpText('after', '\nRepo paths are relative to the gateway workspace root (sibling checkouts: ../<repo>).\n' +
+    'Each listed repo must carry its own v3 .descix/workspace.json with env.app (descix app init there).\n' +
+    'Refused in a single-app workspace (one that holds env.app).\n');
+
+configGatewayCommand
+  .command('set-shell')
+  .description('Set the repo whose app the gateway serves at / (env.gateway.shell)')
+  .argument('<repo>', 'Repo root relative to the workspace root, or "none" to remove')
+  .action(async (repo) => {
+    try {
+      await configCommands.setGatewayRepo('set-shell', repo === 'none' ? null : repo);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+configGatewayCommand
+  .command('add-repo')
+  .description('List a repo whose app the gateway serves at /p/<appId> (env.gateway.appRepos[])')
+  .argument('<repo>', 'Repo root relative to the workspace root')
+  .action(async (repo) => {
+    try {
+      await configCommands.setGatewayRepo('add-repo', repo);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+configGatewayCommand
+  .command('remove-repo')
+  .description('Remove a listed repo from env.gateway.appRepos[]')
+  .argument('<repo>', 'Repo root relative to the workspace root, as listed')
+  .action(async (repo) => {
+    try {
+      await configCommands.setGatewayRepo('remove-repo', repo);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
 configCommand
   .command('set-dev-certs')
   .description('Point local dev servers at your own TLS cert pair (env.devCerts) — the gateway AND every app behind it')

package/lib/commands/config.js

@@ -308,3 +308,21 @@ export async function setSiteUrl(url) {
     'App Shell URL set — `descix serve` will proxy / here.',
   );
 }
+
+/**
+ * `descix config gateway set-shell | add-repo | remove-repo` — the CLI face of the one writer,
+ * WorkspaceConfig.setGatewayRepo(). A refusal propagates to the bin's fail(), which prints it once.
+ *
+ * @param {'set-shell'|'add-repo'|'remove-repo'} op
+ * @param {string|null} repo
+ */
+export async function setGatewayRepo(op, repo) {
+  const workspaceConfig = await WorkspaceConfig.load();
+  const configPath = await workspaceConfig.setGatewayRepo(op, repo);
+  const gateway = workspaceConfig.env?.gateway || {};
+  console.log(chalk.green(`\n✅ Gateway ${op}: ${repo === null ? '(shell removed)' : repo}\n`));
+  console.log(chalk.white(`   env.gateway.shell:    ${gateway.shell ?? '(none)'}`));
+  console.log(chalk.white(`   env.gateway.appRepos: ${gateway.appRepos?.length ? gateway.appRepos.join(', ') : '(none)'}`));
+  console.log(chalk.gray(`   Saved to: ${configPath}\n`));
+  return configPath;
+}

package/lib/commands/model-config.js

@@ -7,8 +7,9 @@
  *   - descix kb set-override-model -a <app_id> -k <kb_name> -m <model_name> [--env=dev|demo|prod]
  *   - descix kb clear-override-model -a <app_id> -k <kb_name> [--env=dev|demo|prod]
  *
- * Per CEO 2026-05-26 inheritance chain:
- *   options.model || kb.kb_model_override || app.default_app_model || levelConfig.model || utils.DEFAULT_AI_MODEL
+ * Resolver order (the server owns it; this CLI prints the chain the server reports):
+ *   request intelligence_level > kb.kb_model_override (+ its thinking_level) > app.default_app_model > the level's model
+ * There is no separate default model: the default is the model of the platform's default intelligence level.
  *
  * --clear flows use FieldValue.delete() server-side (NOT null) per tripwire #2.
  *
@@ -110,12 +111,10 @@ function identityFromApiClient(apiClient) {
 function printResolution({ app_id, resolution }) {
     if (!resolution) return;
     const dam = resolution.default_app_model === null ? 'null' : `"${resolution.default_app_model}"`;
-    const dai = resolution.default_ai_model ? `"${resolution.default_ai_model}"` : 'null';
 
     console.log(chalk.cyan('\nResolution chain that will apply going forward:'));
     console.log(chalk.gray(`  ${resolution.chain}`));
     console.log(chalk.gray(`  app.default_app_model = ${dam}`));
-    console.log(chalk.gray(`  utils.DEFAULT_AI_MODEL = ${dai}`));
 
     const levels = resolution.intelligence_levels || {};
     const levelKeys = Object.keys(levels).sort();

package/lib/verb-invokes.generated.json

@@ -93,6 +93,9 @@
   "community rename": [
     "rename_community"
   ],
+  "config gateway add-repo": [],
+  "config gateway remove-repo": [],
+  "config gateway set-shell": [],
   "config init": [],
   "config set-dev-certs": [],
   "config set-env": [],

package/lib/workspace-config.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { ENV_ORIGINS, resolveWorkspaceApps } from '@descix/app-sdk/dev';
+import { ENV_ORIGINS, resolveWorkspaceApps, resolveWorkspaceAppsFrom, assertSiteStatic } from '@descix/app-sdk/dev';
 import { resolveOrigin } from './origin.js';
 // The one canonical KB-sync surface, from its owner. The example in requireContext() is a remedy
 // a stuck developer will copy verbatim, so it must resolve to the live verb rather than a literal
@@ -860,9 +860,9 @@ export class WorkspaceConfig {
    * Update the app's site config on env.app (v3 single-app).
    *
    * Parallel to setMicroservicePort(), but operates on the entry's site.{} slot. This is the
-   * canonical write path for site.static — the relative path the dev gateway's
-   * staticSitePlugin serves at /p/{appId}/ (see createViteProxyConfig: site.static is
-   * resolved against the app's localPath; "." means the localPath itself) — and for
+   * canonical write path for site.static — the path, relative to the workspace root (the repo
+   * root; "." means the root itself), that the dev gateway's staticSitePlugin serves at
+   * /p/{appId}/; anything that is not a plain relative path is refused (assertSiteStatic) — and for
    * site.port / site.protocol, the dev-server upstream the gateway proxies /p/{appId} to.
    * Backs the `descix app set-site` command, closing the site.static workspace gap without
    * hand-editing workspace.json (the org rule forbids hand edits — CEO-D-2026-06-02-SSGPOD-SITE-PREPROD).
@@ -898,6 +898,12 @@ export class WorkspaceConfig {
     const settingPort = 'port' in fields && fields.port !== null && fields.port !== undefined;
     const settingProtocol = 'protocol' in fields && fields.protocol !== null && fields.protocol !== undefined;
 
+    // site.static path rule — ONE owner (@descix/app-sdk/dev siteStatic.js), applied before
+    // anything is computed so a refusal writes NOTHING.
+    if (settingStatic) {
+      assertSiteStatic(fields.static, { subject: '--static', remedy: `Nothing was written for ${appId}.` });
+    }
+
     if (settingProtocol && fields.protocol !== 'http' && fields.protocol !== 'https') {
       throw new Error(
         `site.protocol must be "http" or "https" (got ${JSON.stringify(fields.protocol)}). ` +
@@ -950,6 +956,97 @@ export class WorkspaceConfig {
     return this.save();
   }
 
+  /**
+   * THE ONE WRITER of a gateway workspace's repo list: env.gateway.shell and env.gateway.appRepos[]
+   * (DeSciXCore#9). Backs `descix config gateway set-shell | add-repo | remove-repo`, so a gateway
+   * workspace.json is never hand-edited.
+   *
+   * Paths are relative to THIS workspace's root (sibling checkouts: "../<repo>") and are stored in
+   * normalized form; two spellings of one directory are one repo.
+   *
+   * Refused loud, and a refusal writes NOTHING:
+   *  - this workspace holds env.app — a single-app workspace is not a gateway;
+   *  - add-repo of a repo already listed (or already the shell);
+   *  - remove-repo of a repo that is not listed;
+   *  - any resulting listed repo that the gateway could not read: the candidate config is resolved
+   *    by @descix/app-sdk/dev resolveWorkspaceAppsFrom — the SAME function the gateway reads it with
+   *    — so an absolute path, a repo without its own .descix/workspace.json, one with no env.app, a
+   *    bad site.static, or one appId listed twice is refused by the reader's own rule.
+   *
+   * @param {'set-shell'|'add-repo'|'remove-repo'} op
+   * @param {string|null} repo - repo root relative to the workspace root; null with set-shell removes the shell
+   * @returns {Promise<string>} Path to saved config (from save())
+   */
+  async setGatewayRepo(op, repo) {
+    const OPS = ['set-shell', 'add-repo', 'remove-repo'];
+    if (!OPS.includes(op)) throw new Error(`Unknown gateway op "${op}" (expected one of: ${OPS.join(', ')}).`);
+    const root = this.workspaceRoot;
+    if (!root) throw new Error('Workspace root not set. Load the config with WorkspaceConfig.load() first.');
+    const configPath = path.join(root, '.descix', 'workspace.json');
+
+    if (this.env?.app?.appId) {
+      throw new Error(
+        `${configPath} is a single-app workspace (env.app "${this.env.app.appId}"), not a gateway workspace.\n` +
+        'env.gateway.shell and env.gateway.appRepos belong to a gateway workspace, which holds no env.app of\n' +
+        'its own and lists sibling app repos. Run this verb from the gateway workspace\'s root. Nothing was written.'
+      );
+    }
+
+    const removingShell = op === 'set-shell' && (repo === null || repo === undefined);
+    if (!removingShell && (typeof repo !== 'string' || repo.trim() === '')) {
+      throw new Error(`descix config gateway ${op} needs a repo path (relative to ${root}). Nothing was written.`);
+    }
+    // Normalized relative form: "../repo-a/", "./../repo-a" and "../repo-a" are one repo. An absolute
+    // path is passed through untouched so the reader's own rule refuses it below.
+    const normalize = (rel) => (path.isAbsolute(rel) ? rel : (path.normalize(rel).replace(/[\\/]+$/, '') || '.'));
+    const dirOf = (rel) => path.resolve(root, rel);
+    const rel = removingShell ? null : normalize(repo.trim());
+
+    const gateway = { ...(this.env?.gateway || {}) };
+    const appRepos = [...(gateway.appRepos || [])];
+
+    if (op === 'set-shell') {
+      if (rel === null) delete gateway.shell;
+      else gateway.shell = rel;
+    } else if (op === 'add-repo') {
+      if (!path.isAbsolute(rel)) {
+        const listed = appRepos.find((r) => dirOf(r) === dirOf(rel));
+        if (listed) {
+          throw new Error(`"${repo}" is already listed in env.gateway.appRepos (as "${listed}") in ${configPath}. Nothing was written.`);
+        }
+        if (gateway.shell && dirOf(gateway.shell) === dirOf(rel)) {
+          throw new Error(
+            `"${repo}" is this workspace's env.gateway.shell in ${configPath}; the shell is served at / and is not ` +
+            'also listed in appRepos. Nothing was written.'
+          );
+        }
+      }
+      appRepos.push(rel);
+    } else {
+      const at = path.isAbsolute(rel) ? -1 : appRepos.findIndex((r) => dirOf(r) === dirOf(rel));
+      if (at < 0) {
+        throw new Error(
+          `"${repo}" is not listed in env.gateway.appRepos in ${configPath}.\n` +
+          `  Listed: ${appRepos.length ? appRepos.join(', ') : '(none)'}\nNothing was written.`
+        );
+      }
+      appRepos.splice(at, 1);
+    }
+
+    if (appRepos.length) gateway.appRepos = appRepos;
+    else delete gateway.appRepos;
+
+    const candidateEnv = { ...(this.env || {}) };
+    if (Object.keys(gateway).length) candidateEnv.gateway = gateway;
+    else delete candidateEnv.gateway;
+
+    // Validate the WHOLE resulting repo set with the reader's own function before anything is saved.
+    resolveWorkspaceAppsFrom(root, { env: candidateEnv });
+
+    this.env = candidateEnv;
+    return this.save();
+  }
+
   /**
    * Persistently set the target environment in workspace.json.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "2.0.4",
+  "version": "3.0.1",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.3.0",
+    "@descix/app-sdk": "^0.3.3",
     "@descix/sdk": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",
@@ -40,7 +40,7 @@
     "googleapis": "^170.1.0",
     "inquirer": "^12.1.0",
     "ora": "^9.0.0",
-    "@descix/platform-api": "^2.0.0"
+    "@descix/platform-api": "^4.0.0"
   },
   "devDependencies": {
     "acorn": "^8.18.0"