@descix/cli 3.0.0 → 3.0.2

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,8 @@
  * Combines CLI and MCP functionality with unified authentication.
  */
 
-import { Command, Option } from 'commander';
+import { Option } from 'commander';
+import { DescixCommand } from '../lib/descix-command.js';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
@@ -73,7 +74,7 @@ function fail(error) {
   process.exit(1);
 }
 
-const program = new Command();
+const program = new DescixCommand();
 
 program
   .name('descix')
@@ -155,6 +156,7 @@ program.hook('preAction', (thisCommand) => {
 
 program
   .command('login')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Authenticate with DeSciX via device login (opens browser)')
   .option('-u, --url <url>', 'API URL override')
   .option('--wallet', 'Use direct wallet connection (advanced, not yet implemented)')
@@ -174,6 +176,7 @@ program
 
 program
   .command('logout')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Clear saved credentials')
   .action(async () => {
     try {
@@ -229,6 +232,7 @@ program
 
 program
   .command('whoami')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Show current authentication status')
   .action(async () => {
     try {
@@ -265,6 +269,7 @@ program
 
 program
   .command('doctor')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Diagnose environment issues (Node, Auth, gcloud, ADC)')
   .action(async () => {
     try {
@@ -1041,6 +1046,7 @@ appCommand
 
 appCommand
   .command('init')
+  .runbookAnchor('#_4-connect-the-repository-to-its-app')
   // ONE PATH TO AN APP (CEO-D-2026-08-14): `app init` is THE app entry point — it creates the
   // app when it does not exist yet and then registers/scaffolds it locally. The separate
   // `app create` command is DELETED (no compat fence): two commands for one outcome is how apps
@@ -1151,6 +1157,7 @@ appCommand
 
 appCommand
   .command('set-listed')
+  .runbookAnchor('#_9-list-it-and-discover-the-rest')
   .description('List or unlist your app in the app store (on: shown in the public store; off: not shown to non-admin visitors)')
   .argument('<state>', 'on or off')
   .requiredOption('-c, --community <id>', 'Community ID')
@@ -1482,7 +1489,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 +1510,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 +1527,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
@@ -1532,9 +1539,10 @@ appCommand
 // Backed by WorkspaceConfig.setStaticSite. It writes ONLY the local workspace.json site.{} slot.
 appCommand
   .command('set-site')
+  .runbookAnchor('#_5-run-it-locally-descix-serve')
   .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 +1566,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 +1588,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 +1626,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 {
@@ -1700,6 +1704,7 @@ const kbCommand = program
 
 kbCommand
   .command('list')
+  .runbookAnchor('#_6-knowledge-bases')
   .description('List knowledge bases for an app')
   .requiredOption('-a, --app <app_id>', 'App ID')
   .option('--cached', 'Show the fast cached vector counter instead of the TRUE live Pinecone count. The cached counter is written ONLY by the CLI/PWA sync path, so it reports 0 for KBs ingested by any other route even when their vectors retrieve. Default is the live count.')
@@ -1996,6 +2001,7 @@ const corpusCommand = kbCommand
 
 corpusCommand
   .command('sync')
+  .runbookAnchor('#_6-knowledge-bases')
   .description('Sync the files a corpus manifest names into the app\'s knowledge base')
   .requiredOption('-a, --app <id>', 'App ID')
   .option('-c, --community <community_id>', 'Community ID (optional; resolved from Products when omitted)')
@@ -2025,6 +2031,7 @@ corpusCommand
 
 corpusCommand
   .command('status')
+  .runbookAnchor('#_6-knowledge-bases')
   .description('Show corpus sync state (files, chunks, last sync, resolved ref)')
   .requiredOption('-a, --app <id>', 'App ID')
   .option('-k, --kb <name>', 'KB name (default: all)')
@@ -2187,6 +2194,7 @@ siteCommand
 // site upload - Deploy to GCS (context-aware, manifest-aware)
 siteCommand
   .command('upload')
+  .runbookAnchor('#_8-deploy-the-site')
   .description('Upload site to GCS and update app metadata (uses .descix/manifests/site.json when present)')
   .option('-c, --community <id>', 'Community ID (auto-detects from context)')
   .option('-a, --app <id>', 'App ID (auto-detects from context)')
@@ -2590,6 +2598,7 @@ siteCommand
 // site status - Get deployment status (context-aware)
 siteCommand
   .command('status')
+  .runbookAnchor('#_8-deploy-the-site')
   .description('Get deployment status and manifest')
   .option('-c, --community <id>', 'Community ID (auto-detects from context)')
   .option('-a, --app <id>', 'App ID (auto-detects from context)')
@@ -3353,6 +3362,7 @@ program
 
 program
   .command('chat [question...]')
+  .runbookAnchor('#_6-knowledge-bases')
   .description('Chat with an app agent. Usage: descix chat "Your question" or descix chat -q "Your question"')
   .option('-c, --community <id>', 'Community ID (optional; server resolves it from Products)')
   .option('-a, --app <id>', 'App ID (required unless run from inside a mapped app directory)')
@@ -3669,6 +3679,7 @@ const configCommand = program
 
 configCommand
   .command('show')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Show current configuration')
   .action(async () => {
     try {
@@ -3680,6 +3691,7 @@ configCommand
 
 configCommand
   .command('init')
+  .runbookAnchor('#_3-pin-production-then-sign-in')
   .description('Pin this workspace to an environment (requires the global --env dev|demo|prod)')
   // `--dev` DELETED, not deprecated: its absence meant PRODUCTION, so the most common
   // invocation (`descix config init`) wrote a prod origin nobody named. There is no default.
@@ -3728,6 +3740,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')
@@ -4055,6 +4112,7 @@ mcpCommand
 
 program
   .command('tell-me-how')
+  .runbookAnchor('#_9-list-it-and-discover-the-rest')
   .description('Discover platform tools using natural language (Intelligent MCP Mesh)')
   .argument('<question>', 'What do you want to accomplish? Use natural language.')
   .option('-s, --scope <scope>', 'Search scope (validated against the published tell_me_how enum): bootstrap, artifact, project, entitlements (default), discovery', 'entitlements')
@@ -4195,6 +4253,7 @@ program
 
 program
   .command('serve')
+  .runbookAnchor('#_5-run-it-locally-descix-serve')
   .description('Start the unified local gateway (one HTTPS origin: App Shell at /, your app at /p/<app>, /apifront to the API)')
   .option('-p, --port <port>', 'Gateway port for this run (default: env.gateway.port, else 5173)')
   .option('-w, --workspace <path>', 'Workspace root override')
@@ -4226,6 +4285,7 @@ const devCertsCommand = program
 
 devCertsCommand
   .command('check')
+  .runbookAnchor('#_5-run-it-locally-descix-serve')
   .description('Check whether the dev-server cert is trusted for https://localhost (exit 0 only when trusted)')
   .option('--json', 'Output raw JSON')
   .action(async (options) => {
@@ -4239,6 +4299,7 @@ devCertsCommand
 
 devCertsCommand
   .command('trust')
+  .runbookAnchor('#_5-run-it-locally-descix-serve')
   .description('Trust the dev-server cert in the macOS keychain (prompts for your password)')
   .action(async () => {
     try {

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/descix-command.js

@@ -0,0 +1,43 @@
+/**
+ * DescixCommand — the CLI's commander Command, carrying ONE extra fact per verb: the
+ * app-developer runbook section that documents it.
+ *
+ * The fact is declared BESIDE the verb's own definition in bin/descix.js
+ * (`.command('serve').runbookAnchor('#_5-run-it-locally-descix-serve')`), so the verb tree and
+ * its runbook pointers can never be two lists. `createCommand` makes every subcommand a
+ * DescixCommand (commander's documented subclassing hook), so `.runbookAnchor()` chains on any
+ * `.command(...)` in the tree.
+ *
+ * The value is the anchor VitePress renders for the runbook heading (leading '#'). Whether it
+ * names a REAL heading is gated by tests/cli-verbs-generated.test.js against the runbook
+ * source (scripts/lib/runbook-anchors.mjs owns the slug rule). A verb with no runbook section
+ * declares nothing — there is no placeholder anchor. Read only by
+ * scripts/lib/cli-verb-tree-hook.mjs, which publishes the tree into
+ * @descix/platform-api/mcp-tools (cli-verbs.generated.json).
+ */
+import { Command } from 'commander';
+
+const ANCHOR_SHAPE = /^#[^\sA-Z#]+$/;
+
+export class DescixCommand extends Command {
+  createCommand(name) {
+    return new DescixCommand(name);
+  }
+
+  /** @param {string} anchor '#<slug>' as rendered by the docs site @returns {this} */
+  runbookAnchor(anchor) {
+    if (this._descixRunbookAnchor !== undefined) {
+      throw new Error(`descix ${this.name()}: runbookAnchor declared twice (${this._descixRunbookAnchor}, ${anchor}) — one verb, one section`);
+    }
+    if (typeof anchor !== 'string' || !ANCHOR_SHAPE.test(anchor)) {
+      throw new Error(`descix ${this.name()}: runbookAnchor must be a rendered anchor like "#_5-run-it-locally-descix-serve"; got ${JSON.stringify(anchor)}`);
+    }
+    this._descixRunbookAnchor = anchor;
+    return this;
+  }
+
+  /** @returns {string|null} the declared anchor, or null when the verb has no runbook section */
+  declaredRunbookAnchor() {
+    return this._descixRunbookAnchor ?? null;
+  }
+}

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": [],