@descix/cli 1.0.18 → 1.0.20

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

@@ -89,7 +89,6 @@ execute_remote_command({
 This returns:
 - `communities`: Communities the user belongs to (with roles)
 - `apps`: Apps the user owns or can develop
-- `service_slots`: Available service deployment slots
 
 ### Step 2: Present Entitlements to User
 

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

@@ -10,7 +10,7 @@ This document covers how AI agents interact with the DeSciX platform via MCP (Mo
 
 ## 1. Architecture Overview
 
-DeSciX operates as a **Federated MCP Service Mesh**. The DeSciX backend acts as a broker that aggregates tools from all registered microservices into a unified catalog.
+DeSciX operates as a **Federated MCP Service Mesh**. The DeSciX backend acts as a broker: it registers tools from all registered microservices alongside its own native commands, dispatches calls to whichever service owns the command, and advertises a small handshake floor of that set at `tools/list` (see §2.2).
 
 **Key Innovation:** AI agents discover and invoke capabilities across the entire mesh without knowing where individual services are hosted.
 
@@ -46,14 +46,29 @@ MCP provides the communication protocol between AI agents and the DeSciX platfor
 - `ask_question_to_app` - RAG chat with an app's knowledge base (synthesized answer, cited)
 - `query_knowledge_base` - Raw vector search, returns chunks
 
-### 2.2 Cursor/AI Agent Integration
+### 2.2 The Two-Hop: Reaching Commands That Are Not In Your Tool List
 
-When an AI agent (e.g., Cursor) is configured with the DeSciX MCP server:
+**Your MCP tool list is a small floor, not the platform's capability surface.** The platform
+registers many more commands than it advertises at the handshake, so that a session pays ~1k
+tokens of catalog instead of ~8.7k. Everything outside the advertised floor stays registered and
+callable — you reach it with two hops:
 
-1. Agent receives user question
-2. Agent uses `tell_me_how` to find relevant tools
-3. Agent calls `execute_remote_command` with discovered tool
-4. Result returned to user
+1. `tell_me_how({ question })` — names the command and its parameters
+2. `execute_remote_command({ command, params })` — invokes it
+
+**Rule for an agent: if a capability is not a tool in your list, do not conclude the platform
+lacks it, and do not guess a command name — ask `tell_me_how`, then `execute_remote_command`
+what it names.** This is the standing integration pattern for every caller, on every transport.
+
+The advertised floor is a **floor, not a ceiling**: `tools/list` serves it UNION the calling
+identity's granted command names, so a caller may see more, never less. The floor's membership
+and its contract are owned by `describeDiscoveryCoreFence()` /
+`DISCOVERY_CORE_TOOL_NAMES` in `@descix/platform-api`
+(`src/mcp-tools/nativeTools.js`) — read your live `tools/list` rather than a copy of it.
+
+The CLI's stdio MCP server additionally concatenates its CLI-local diagnostics (`descix_doctor`,
+`platform_health`) onto whatever the backend advertises; those are local CLI operations, never
+`/apifront` commands, so `execute_remote_command` does not reach them.
 
 ### 2.3 The `_descix` Context Object
 
@@ -155,21 +170,23 @@ After `descix quickstart` completes:
 
 ### 4.1 Federated MCP Broker
 
-The DeSciX backend aggregates tools from all registered microservices:
+The DeSciX backend registers tools from all registered microservices and makes them callable and
+semantically discoverable — the handshake advertises only the floor (§2.2):
 
 ```
 Microservice A
   └── manifest.json (tools: [tool1, tool2])
         │
         ▼
-    Registers with Core
-        │
+    Registers with Core  ──► callable via execute_remote_command
+        │                    + vectorized for tell_me_how
         ▼
 DeSciX Backend (Broker)
-  └── Aggregated tools/list
+  └── tools/list  ──► handshake floor + this caller's grants
         │
         ▼
-    AI Agent sees: [tool1, tool2, core_tools...]
+    AI Agent's tool list: the floor. tool1/tool2 are reached
+    with tell_me_how -> execute_remote_command.
 ```
 
 ### 4.2 SERVICE_README Vectorization

package/bin/descix.js

@@ -11,7 +11,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
-import { WorkspaceConfig, unmappedAppMessage, resolveWorkspacePath, TOP_LEVEL_API_URL_REMEDY } from '../lib/workspace-config.js';
+import { WorkspaceConfig, unmappedAppMessage, resolveWorkspacePath } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
@@ -28,10 +28,12 @@ import * as configCommands from '../lib/commands/config.js';
 import * as buyCommands from '../lib/commands/buy.js';
 import * as creditsCommands from '../lib/commands/credits.js';
 import * as airdropCommands from '../lib/commands/airdrop.js';
+import { MICROSERVICE_AUTH_MODEL } from '../lib/commands/microservice-auth-model.js';
 import { runInit } from '../lib/commands/init.js';
 // "May I prompt?" has ONE OWNER. No command in this file derives it.
 import { createPromptSession } from '../lib/interactive.js';
-import { registerAllRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
+import { CANONICAL_KB_SYNC } from '../lib/commands/kb-sync-surface.js';
+import { registerAllRetiredVerbs } from '../lib/commands/retired-verbs.js';
 import { runStatus } from '../lib/commands/status.js';
 import { refreshCommunityIdentity, printIdentityReceipt } from '../lib/commands/communityIdentity.js';
 import { runAppInit } from '../lib/commands/appInit.js';
@@ -455,9 +457,9 @@ airdropCommand
 
 // ============ Sync Commands: REMOVED ============
 // `sync assets`, `sync site` and `sync kb` are all gone, so the `sync` GROUP is gone with
-// them: a registered verb with no working children is dead weight. Every retired surface is
-// registered in ONE place below (search registerAllRetiredKbSync), driven off the owner list
-// in lib/commands/retired-kb-sync.js -- this file names no retired verb itself.
+// them: a registered verb with no working children is dead weight. Every retired verb is
+// registered in ONE place below (search registerAllRetiredVerbs), driven off the owner table
+// in lib/commands/retired-verbs.js -- this file names no retired verb itself.
 
 // ============ Community/App Commands ============
 
@@ -1639,35 +1641,41 @@ appCommand
 
 // ============ App: set-site (WS-SSGPOD — site.static workspace gap) ============
 //
-// Canonical write path for an app's site config in workspace.json — specifically site.static,
-// the relative path the dev gateway's staticSitePlugin serves at /p/{appId}/ (resolved against
-// the app's localPath; "." means the localPath itself). Optionally sets site.port for
-// dev-server sites. Parallel to `descix app set-port` (microservice.port); closes the
-// site.static gap so workspace.json never needs hand-editing (CEO-D-2026-06-02-SSGPOD-SITE-PREPROD).
-// Backed by WorkspaceConfig.setStaticSite (parallel to setMicroservicePort).
-// It writes ONLY the local workspace.json site.{} slot.
+// 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}/.
+//   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
+// explicit combined write and keeps both (the gateway then serves the DEV SERVER — site.port
+// wins — and says so on the serve banner). Parallel to `descix app set-port`
+// (microservice.port); no hand-editing of workspace.json (CEO-D-2026-06-02-SSGPOD-SITE-PREPROD).
+// Backed by WorkspaceConfig.setStaticSite. It writes ONLY the local workspace.json site.{} slot.
 appCommand
   .command('set-site')
-  .description("Set a mapped app static-site config (writes env.products[<app>].site.static, the relative dir served at /p/<app>/). Optionally --port; --unset clears site.{}.")
+  .description("Set a mapped app's site config (env.products[<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>', 'Relative static-site path under the app localPath (e.g. "site"; "." = the localPath itself)')
-  .option('--port <port>', 'Site dev-server port (1-65535) for framework dev sites; mutually optional with --static')
-  .option('--unset', 'Remove site.static (and site.port) for the app, clearing the site.{} slot')
+  .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).')
+  .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')
   .action(async (options) => {
     try {
       const appId = options.app;
       const workspaceConfig = await WorkspaceConfig.load();
 
-      // --unset: remove both site.static and site.port (setStaticSite cleans up empty site.{})
+      // --unset: remove all site.{} fields (setStaticSite cleans up the empty slot)
       if (options.unset) {
-        await workspaceConfig.setStaticSite(appId, { static: null, port: null });
-        console.log(chalk.green(`\n✓ site config cleared for ${appId}\n`));
+        await workspaceConfig.setStaticSite(appId, { static: null, port: null, protocol: null });
+        console.log(chalk.green(`\n✓ site config cleared for ${appId} (site.static, site.port, site.protocol removed)\n`));
         return;
       }
 
       // Require at least one field to set — do not silently no-op.
-      if (options.static === undefined && options.port === undefined) {
-        console.error(chalk.red('\n❌ Nothing to set. Provide --static <path> and/or --port <n>, or --unset to clear.\n'));
+      if (options.static === undefined && options.port === undefined && options.protocol === undefined) {
+        console.error(chalk.red('\n❌ Nothing to set. Provide --static <path> (static mode), --port <n> [--protocol http|https] (dev-server mode), or --unset to clear.\n'));
         process.exit(1);
       }
 
@@ -1690,15 +1698,34 @@ appCommand
         fields.port = portNum;
       }
 
-      // setStaticSite 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.
+      if (options.protocol !== undefined) {
+        if (options.protocol !== 'http' && options.protocol !== 'https') {
+          console.error(chalk.red(`\n❌ Invalid --protocol ${JSON.stringify(options.protocol)}. Only "http" or "https" are valid (it names the scheme of your app's own dev server behind /p/${appId}).\n`));
+          process.exit(1);
+        }
+        fields.protocol = options.protocol;
+      }
+
+      // 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.
       await workspaceConfig.setStaticSite(appId, fields);
 
       console.log(chalk.green(`\n✓ site config set for ${appId}`));
-      if (fields.static !== undefined) console.log(chalk.cyan(`  site.static: ${fields.static}`));
-      if (fields.port !== undefined)   console.log(chalk.cyan(`  site.port:   ${fields.port}`));
-      console.log(chalk.gray(`  Written to env.products[${appId}].site in workspace.json.`));
-      console.log(chalk.gray(`  The gateway serves site.static at /p/${appId}/ (staticSitePlugin); \`descix serve\` picks it up.\n`));
+      // Print the RESULTING slot, not just the fields passed: a dev-server write keeps a
+      // previously declared site.protocol (same mode, new port), and a retained field the
+      // output does not show is invisible state — the whole defect class this command fixes.
+      const entryNow = workspaceConfig.env?.platform?.appId === appId
+        ? workspaceConfig.env.platform
+        : (workspaceConfig.env?.products || []).find(p => p.appId === appId);
+      console.log(chalk.cyan(`  site is now:   ${JSON.stringify(entryNow?.site)}`));
+      if (fields.static !== undefined && fields.port === undefined) {
+        console.log(chalk.gray(`  site.port and site.protocol cleared (one active mode per write) — /p/${appId}/ now serves the static dir.`));
+      } else if (fields.port !== undefined && fields.static === undefined) {
+        console.log(chalk.gray(`  site.static cleared (one active mode per write) — /p/${appId} now proxies to your dev server.`));
+      } else if (fields.static !== undefined && fields.port !== undefined) {
+        console.log(chalk.yellow(`  Combined write: BOTH modes kept. The gateway serves the DEV SERVER (site.port wins); site.static is used only after you clear site.port (--static alone, or --unset).`));
+      }
+      console.log(chalk.gray(`  Written to env.products[${appId}].site in workspace.json; \`descix serve\` picks it up.\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -1951,12 +1978,8 @@ kbCommand
   });
 
 // `kb chunk` and `kb sync` (low-level Git-mode steps) are REMOVED. Their implementations
-// runKbChunk/runKbSync are deleted from lib/commands/kb.js. Both names exit non-zero naming
-// `descix kb corpus sync`.
-// EVERY retired kb-sync surface is registered here, by ITERATING the owner list -- no verb
-// name is typed in this file. Adding a surface to RETIRED_KB_SYNC_SURFACES registers it;
-// nothing can be registered without being in that list.
-registerAllRetiredKbSync({ program, kb: kbCommand }, chalk.red);
+// runKbChunk/runKbSync are deleted from lib/commands/kb.js. Both names are rows in
+// lib/commands/retired-verbs.js, registered with the rest of that table below.
 
 
 // app records — APP DATA PLANE structured record store (CEO-D-2026-06-02-APP-DATA-PLANE)
@@ -2929,6 +2952,7 @@ microserviceCommand
 microserviceCommand
   .command('register')
   .description('Register microservice with gateway (-r <local SERVICE_README>; git-mode only — no Drive)')
+  .addHelpText('after', `\nAuthentication:\n  ${MICROSERVICE_AUTH_MODEL}\n`)
   .option('-m, --manifest <path>', 'Path to manifest.json', './manifest.json')
   .option('-r, --readme <path>', 'Path to local SERVICE_README file')
   .option('-c, --community <id>', 'Community ID (auto-detects from context)')
@@ -3289,128 +3313,6 @@ microserviceCommand
     }
   });
 
-// microservice register-delegate - Register delegate key
-microserviceCommand
-  .command('register-delegate')
-  .description('Provision the service delegate key (SERVICE_KEY) that authenticates mesh/loopback calls — run this if your service gets HTTP 401 calling /apifront or another service')
-  .option('-c, --community <id>', 'Community ID (auto-detects from context)')
-  .option('-a, --app <id>', 'App ID (auto-detects from context)')
-  .option('-s, --slot <id>', 'Service slot ID (uses first available if not provided)')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      // Auto-detect context
-      const workspaceConfig = await WorkspaceConfig.load();
-      const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      let communityId = ctx.communityId;
-      let appId = ctx.appId;
-      
-      // Try manifest.json if not detected
-      if (!communityId || !appId) {
-        try {
-          const manifestContent = await fs.readFile('./manifest.json', 'utf-8');
-          const manifest = JSON.parse(manifestContent);
-          if (!communityId) communityId = manifest.service?.community_id;
-          if (!appId) appId = manifest.service?.app_id;
-        } catch {
-          // Not found
-        }
-      }
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, cd into an app directory, or have manifest.json present.\n'));
-        process.exit(1);
-      }
-      
-      console.log(chalk.cyan('\n🔑 Registering Service Delegate Key\n'));
-      
-      // Fetch entitlements
-      const entitlementsResponse = await apiClient.invoke('fetch_my_purchases', {});
-      const entitlements = entitlementsResponse.message || {};
-      const allSlots = entitlements.service_slots || [];
-
-      // Service slots come ONLY from subscriptions right now. NFT-based slots are FUTURE
-      // functionality (app/NFT association is not wired yet) — never select them here.
-      // CEO-D-2026-06-01-MESH-AUTH-DRIVE-REMOVAL (Fix C).
-      const serviceSlots = allSlots.filter(slot => slot.type === 'subscription');
-
-      if (serviceSlots.length === 0) {
-        console.error(chalk.red('❌ No subscription service slot available.'));
-        console.log(chalk.white('   Service slots are provided by a subscription. A subscription is required to'));
-        console.log(chalk.white('   provision a delegate. (NFT-based slots are future functionality and are'));
-        console.log(chalk.white('   not selectable yet.)'));
-        process.exit(1);
-      }
-
-      // Select slot (subscription slots only)
-      let selectedSlot = serviceSlots[0];
-      if (options.slot) {
-        selectedSlot = serviceSlots.find(s => (s.id || s.nft_id) === options.slot);
-        if (!selectedSlot) {
-          console.error(chalk.red(`❌ Subscription slot ${options.slot} not found in your entitlements.`));
-          console.log(chalk.gray('   Only subscription slots are selectable. Run without -s to use the first available.'));
-          process.exit(1);
-        }
-      }
-      
-      console.log(chalk.gray(`  Selected slot: ${selectedSlot.name} (${selectedSlot.type})\n`));
-      
-      // Generate key pair
-      const crypto = await import('crypto');
-      const { publicKey, privateKey } = crypto.generateKeyPairSync('ec', {
-        namedCurve: 'secp256k1',
-        publicKeyEncoding: { type: 'spki', format: 'pem' },
-        privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
-      });
-      
-      console.log(chalk.gray('  Generating key pair...'));
-      
-      // Register with Virtual Registry
-      const registerResponse = await apiClient.invoke('register_delegate', {
-        slot_id: selectedSlot.nft_id || selectedSlot.id,
-        slot_type: selectedSlot.type,
-        public_key: publicKey,
-        app_id: appId,
-        community_id: communityId
-      });
-      
-      console.log(chalk.green('  ✓ Delegate registered with Core\n'));
-      
-      // Save to dev-overrides.json
-      const overridesPath = path.resolve(process.cwd(), 'dev-overrides.json');
-      let overrides = {};
-      
-      try {
-        const content = await fs.readFile(overridesPath, 'utf-8');
-        overrides = JSON.parse(content);
-      } catch (e) {
-        // File doesn't exist, start fresh
-      }
-      
-      overrides.SERVICE_KEY = {
-        privateKey,
-        publicKey,
-        slotId: selectedSlot.nft_id || selectedSlot.id,
-        slotType: selectedSlot.type,
-        appId: appId,
-        communityId: communityId,
-        createdAt: new Date().toISOString()
-      };
-      
-      await fs.writeFile(overridesPath, JSON.stringify(overrides, null, 2));
-      console.log(chalk.green(`✅ Key saved to dev-overrides.json\n`));
-      console.log(chalk.gray(`  Path: ${overridesPath}\n`));
-      
-    } catch (error) {
-      console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
-      process.exit(1);
-    }
-  });
-
 // microservice restart - Kill + relaunch a local microservice (DEV only)
 microserviceCommand
   .command('restart <name>')
@@ -3863,24 +3765,6 @@ configCommand
     }
   });
 
-// `config set-url` is RETIRED, and it is retired LOUDLY rather than deleted outright: a deleted
-// subcommand only earns commander's "unknown command", which names no replacement. It used to
-// assign a top-level `apiUrl` that save() never serialized, then print a success banner over a
-// value that landed nowhere — the file was re-stamped and the origin never moved. Hidden from
-// --help; any invocation exits non-zero naming the three surfaces that actually set the origin.
-configCommand
-  .command('set-url', { hidden: true })
-  .description('retired — see error text')
-  .argument('[url]')
-  .allowUnknownOption()
-  .action(() => {
-    fail(new Error(
-      '"descix config set-url" is retired: it never wrote the origin it reported (a retired top-level\n' +
-      'key that nothing reads). Set the API origin where it is read, env.apiUrl, with one of:\n' +
-      `  ${TOP_LEVEL_API_URL_REMEDY}`
-    ));
-  });
-
 configCommand
   .command('init')
   .description('Pin this workspace to an environment (requires the global --env dev|demo|prod)')
@@ -4593,6 +4477,11 @@ program
     }
   });
 
+// ============ Retired verbs ============
+// Every retired verb is a row in lib/commands/retired-verbs.js, registered here in one call once
+// every parent exists. No retired verb name is typed in this file.
+registerAllRetiredVerbs({ program, kb: kbCommand, config: configCommand, microservice: microserviceCommand });
+
 // ============ Public-vs-admin help listing (CEO ruling, see lib/command-visibility.js) ============
 //
 // The class comes from the server (`get_command_surface`, guest-allowed) at the moment help is

package/lib/command-visibility.js

@@ -135,7 +135,7 @@ export function applyVisibility(program, surfaceCommands) {
     const hasChildren = Array.isArray(cmd.commands) && cmd.commands.length > 0;
     // ADDITIVE ONLY. Some commands are registered `{ hidden: true }` by the CLI itself for
     // reasons that have nothing to do with server admin-gating — see the retired-surface
-    // registrations in lib/commands/retired-kb-sync.js, each a deliberate loud-refusal stub kept
+    // registrations in lib/commands/retired-verbs.js, each a deliberate loud-refusal stub kept
     // out of the default listing so it doesn't clutter it, while still working and refusing
     // clearly when typed. This layer may HIDE a visible command; it must never REVEAL a command
     // the CLI already chose to hide. MEASURED: an early version unconditionally overwrote

package/lib/commands/airdrop.js

@@ -205,12 +205,17 @@ export async function executeQueue(options) {
         if (result.token_contract_address) console.log(`  token_contract:           ${result.token_contract_address}`);
         if (result.abi_source) console.log(`  abi_source:               ${result.abi_source.doc_id} (v${result.abi_source.version || '?'})`);
         console.log(`  transfers_total:          ${chalk.yellow(result.transfers_total)}`);
+        console.log(`  batches_total:            ${result.batches_total}`);
         console.log(`  debit_total:              ${result.debit_total}`);
         console.log(`  credit_total:             ${result.credit_total}`);
-        console.log(`  bonus_total:              ${result.bonus_total}`);
         const nz = result.net_zero_assertion || {};
         const nzLabel = nz.passes ? chalk.green('PASS') : chalk.red('FAIL');
         console.log(`  net_zero_assertion:       ${nzLabel} (Σ=${nz.sum})`);
+        const pbc = result.pre_batch_checks || {};
+        console.log(`  pre_batch_checks:         ${pbc.passes ? chalk.green('PASS') : chalk.red('FAIL — --apply would refuse')}`);
+        for (const r of (pbc.refusals || [])) {
+            console.log(chalk.red(`    ${r.kind} ${r.wallet} (${r.community_id}) holds ${r.held}, needs ${r.required} base units — rows ${(r.pending_ids || []).join(', ')}`));
+        }
         console.log(`  unique_source_wallets:    ${result.unique_source_wallets}`);
         console.log(`  unique_master_wallets:    ${result.unique_master_wallets}`);
         console.log(`  prospective_batch_id:     ${result.prospective_batch_id}`);

package/lib/commands/init.js

@@ -11,10 +11,10 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 // clone.js is imported dynamically inside the invite flow to avoid circular deps
 import { WorkspaceConfig } from '../workspace-config.js';
-// The canonical KB-sync surface is owned by retired-kb-sync.js. Consume the constant: a literal
+// The canonical KB-sync surface is owned by kb-sync-surface.js. Consume the constant: a literal
 // spelled here is a second derivation of the same fact, and the removed verb this replaced
 // reached a developer who had done everything right.
-import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
+import { CANONICAL_KB_SYNC } from './kb-sync-surface.js';
 // "May I prompt?" has ONE OWNER. init does not derive it, and holds no TTY check of its own.
 import { createLazyPromptSession } from '../interactive.js';
 

package/lib/commands/kb-sync-surface.js

@@ -0,0 +1,10 @@
+/**
+ * The canonical KB surfaces, named once. Every refusal, hint and next-step that points a
+ * developer at KB sync or KB creation consumes these constants rather than retyping them.
+ */
+
+/** The single canonical KB sync surface. */
+export const CANONICAL_KB_SYNC = 'descix kb corpus sync';
+
+/** The verb that creates a KB — `kb corpus sync`'s dependency. */
+export const CANONICAL_KB_CREATE = 'descix app init --kb <kb_name>';

package/lib/commands/kb.js

@@ -32,7 +32,7 @@ import * as driveADC from '../google-storage-adc.js';
 // The one canonical KB-sync surface, from its owner. Never spell it as a literal here: these
 // commands' next steps are read by a developer as instructions, so they must name the live verb
 // and nothing else.
-import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
+import { CANONICAL_KB_SYNC } from './kb-sync-surface.js';
 import { loadSyncState, syncStatePath } from '../core/syncState.js';
 
 // ============ Pull Command ============

package/lib/commands/microservice-auth-model.js

@@ -0,0 +1,19 @@
+/**
+ * ONE OWNER for how an app microservice authenticates, as the CLI states it.
+ *
+ * CEO-D-2026-06-02-APP-DATA-PLANE: an app microservice writes on the INJECTED CALLER auth
+ * (`params._descix`) with per-app_id isolation, never a per-service delegate key.
+ * `microservice register --help` prints this text, and the retired delegate-key verb's refusal
+ * (lib/commands/retired-verbs.js) prints it too.
+ */
+
+export const MICROSERVICE_AUTH_RULING = 'CEO-D-2026-06-02-APP-DATA-PLANE';
+
+/** The auth model, printed after `microservice register --help` and in the refusal. */
+export const MICROSERVICE_AUTH_MODEL =
+  `A microservice is issued no key of its own (${MICROSERVICE_AUTH_RULING}).\n` +
+  `  Inbound:  /apifront forwards each call with the caller's identity injected as params._descix,\n` +
+  `            isolated per app_id. Your handler acts on that caller.\n` +
+  `  Outbound: calls from your service to /apifront authenticate as the developer through\n` +
+  `            @descix/cli createServiceApiClient (DEVELOPER_WALLET_ADDRESS + DEVELOPER_SIGNATURE).\n` +
+  `  HTTP 401 on an outbound call: those two developer-credential values are missing or wrong.`;

package/lib/commands/retired-verbs.js

@@ -0,0 +1,106 @@
+/**
+ * ONE OWNER for every retired CLI verb: a table and one refusal.
+ *
+ * A retired verb's implementation is deleted; its NAME stays registered, hidden, so typing it
+ * exits non-zero naming the replacement instead of earning commander's "unknown command". That
+ * is not a compat fence: nothing here works under an old name.
+ *
+ * bin/descix.js calls registerAllRetiredVerbs() once and names no retired verb itself, and no
+ * other module registers a hidden command (tests/retired-verbs-one-path.test.js). Retiring a verb
+ * is one row in RETIRED_VERBS.
+ */
+
+import chalk from 'chalk';
+import { TOP_LEVEL_API_URL_REMEDY } from '../workspace-config.js';
+import { MICROSERVICE_AUTH_MODEL } from './microservice-auth-model.js';
+import { CANONICAL_KB_SYNC, CANONICAL_KB_CREATE } from './kb-sync-surface.js';
+
+const kbSyncRefusal = (invocation) =>
+  `❌ \`${invocation}\` has been REMOVED. There is no replacement flag and no fallback.\n\n` +
+  `Use the one canonical KB sync surface:\n` +
+  `  ${CANONICAL_KB_SYNC} -a <app_id> [-k <kb_name>]\n\n` +
+  `It syncs from a git-tracked corpus manifest (.descix/manifests/), which the removed ` +
+  `path could not do. If the KB does not exist yet, create it first with ` +
+  `\`${CANONICAL_KB_CREATE}\`.`;
+const KB_SYNC_DESCRIPTION = `REMOVED — use \`${CANONICAL_KB_SYNC}\``;
+
+/**
+ * Every retired verb. `invocation` is what a user types; `parent` is the id of the commander
+ * parent it hangs off (a root passed to registerAllRetiredVerbs, or an earlier row); `refusal`
+ * renders the full text printed on refusal.
+ */
+export const RETIRED_VERBS = Object.freeze([
+  // The KB sync surfaces superseded by `descix kb corpus sync`.
+  { id: 'sync', parent: 'program', name: 'sync', invocation: 'descix sync',
+    description: KB_SYNC_DESCRIPTION, refusal: kbSyncRefusal },
+  { id: 'sync.kb', parent: 'sync', name: 'kb', invocation: 'descix sync kb',
+    description: KB_SYNC_DESCRIPTION, refusal: kbSyncRefusal },
+  { id: 'kb.chunk', parent: 'kb', name: 'chunk', invocation: 'descix kb chunk',
+    description: KB_SYNC_DESCRIPTION, refusal: kbSyncRefusal },
+  { id: 'kb.sync', parent: 'kb', name: 'sync', invocation: 'descix kb sync',
+    description: KB_SYNC_DESCRIPTION, refusal: kbSyncRefusal },
+  // It assigned a top-level `apiUrl` that save() never serialized and printed success over it.
+  { id: 'config.set-url', parent: 'config', name: 'set-url', invocation: 'descix config set-url',
+    description: 'retired — see error text',
+    refusal: () =>
+      '"descix config set-url" is retired: it never wrote the origin it reported (a retired top-level\n' +
+      'key that nothing reads). Set the API origin where it is read, env.apiUrl, with one of:\n' +
+      `  ${TOP_LEVEL_API_URL_REMEDY}` },
+  // There is no per-app microservice delegate key (CEO-D-2026-06-02-APP-DATA-PLANE).
+  { id: 'microservice.register-delegate', parent: 'microservice', name: 'register-delegate',
+    invocation: 'descix microservice register-delegate', description: 'removed — see error text',
+    refusal: () =>
+      '"descix microservice register-delegate" has been removed: there is no per-app microservice ' +
+      'delegate key.\n' + MICROSERVICE_AUTH_MODEL },
+]);
+
+/** Implementations deleted with the KB sync surfaces. No exported symbol survives without a caller. */
+export const DELETED_KB_SYNC_SYMBOLS = Object.freeze([
+  'runKbChunk',
+  'runKbSync',
+  'runKbBuild',
+  'runKbStatus',
+  'runKbCompare',
+  'updateKB',
+]);
+
+/** The exact text a retired verb prints. */
+export function retiredVerbRefusal(verb) {
+  return verb.refusal(verb.invocation);
+}
+
+/** THE refusal: print the verb's text and exit non-zero. Never warns, never falls back. */
+export function refuseRetiredVerb(verb) {
+  console.error(chalk.red(`\n${retiredVerbRefusal(verb)}\n`));
+  process.exit(1);
+}
+
+/**
+ * Register every row of RETIRED_VERBS, hidden, under its parent. Each accepts and ignores the old
+ * arguments and options so an old script fails with the refusal rather than a commander parse
+ * error. helpOption(false) is load-bearing: commander answers `--help` BEFORE the action and exits
+ * 0, so without it the most natural way to probe a dead verb is the one way it appears to work.
+ *
+ * @param {Record<string, import('commander').Command>} roots - seed parents by id, e.g. { program, kb, config, microservice }
+ * @returns {Record<string, import('commander').Command>} roots plus each registered verb by id
+ */
+export function registerAllRetiredVerbs(roots) {
+  const byId = { ...roots };
+  for (const verb of RETIRED_VERBS) {
+    const parent = byId[verb.parent];
+    if (!parent) {
+      throw new Error(
+        `retired-verbs: no parent '${verb.parent}' available for '${verb.invocation}'. ` +
+        'Seed it in the roots map or order the table so the parent is registered first.'
+      );
+    }
+    byId[verb.id] = parent
+      .command(verb.name, { hidden: true })
+      .description(verb.description)
+      .allowUnknownOption(true)
+      .helpOption(false)
+      .argument('[args...]', 'ignored')
+      .action(() => refuseRetiredVerb(verb));
+  }
+  return byId;
+}

package/lib/service-api-client.js

@@ -13,8 +13,8 @@
  *
  * Difference from the CLI: a Cloud Run service has no `.descix/wallet.json` and no TTY. So:
  *   - the developer credential is supplied EXPLICITLY (read from the service's config — the
- *     GITIGNORED dev-overrides.json in dev / a SECRET in prod, NEVER checked-in
- *     defaults-config.json, because the signature is a credential), and
+ *     app's defaults-config, the developer's choice, or Secret Manager; a defaults-config
+ *     credential ships inside the image and must never be committed to a public repo), and
  *   - on a session-refresh failure it HARD-FAILS (serviceMode) — it never tries interactive
  *     device login.
  *
@@ -50,15 +50,16 @@ export function createServiceApiClient({ baseUrl, walletAddress, signature, user
   }
   if (!walletAddress || typeof walletAddress !== 'string') {
     throw new Error(
-      'createServiceApiClient: walletAddress is required — the developer credential. Put it in the ' +
-      'GITIGNORED dev-overrides.json (dev) / a secret (prod), never defaults-config.json. No fallback.'
+      'createServiceApiClient: walletAddress is required — the developer credential. ' +
+      'It may live in the app defaults-config (your choice, e.g. a private repo) or in Secret Manager. ' +
+      'A credential in defaults-config ships inside the image; never commit it to a repo that is or will be public. No fallback.'
     );
   }
   if (!signature || typeof signature !== 'string') {
     throw new Error(
       'createServiceApiClient: signature is required — the developer durable credential (from their ' +
-      '.descix/wallet.json). Put it in the GITIGNORED dev-overrides.json (dev) / a secret (prod), ' +
-      'never defaults-config.json. No fallback.'
+      '.descix/wallet.json). It may live in the app defaults-config (your choice, e.g. a private repo) or in Secret Manager. ' +
+      'A credential in defaults-config ships inside the image; never commit it to a repo that is or will be public. No fallback.'
     );
   }
 

package/lib/verb-invokes.generated.json

@@ -103,7 +103,6 @@
   "config set-gateway-port": [],
   "config set-powch-url": [],
   "config set-site-url": [],
-  "config set-url": [],
   "config show": [],
   "credits balance": [
     "get_credit_balance"
@@ -174,10 +173,6 @@
   "microservice register": [
     "register_service"
   ],
-  "microservice register-delegate": [
-    "fetch_my_purchases",
-    "register_delegate"
-  ],
   "microservice reload": [
     "reload_service_manifests"
   ],

package/lib/workspace-config.js

@@ -5,7 +5,7 @@ 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
 // that can go stale where nobody is watching.
-import { CANONICAL_KB_SYNC } from './commands/retired-kb-sync.js';
+import { CANONICAL_KB_SYNC } from './commands/kb-sync-surface.js';
 import { npxCommand } from './invocation.js';
 
 /**
@@ -845,15 +845,27 @@ export class WorkspaceConfig {
   /**
    * Update an app's site config in env.products[] (or env.platform if it is the platform app).
    *
-   * Parallel to setMicroservicePort(), but operates on the entry's site.{} slot's
-   * static-site fields. 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).
+   * 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
+   * 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).
    *
-   * Mutates site.static and/or site.port. Pass static === null to remove site.static; pass
-   * port === null to remove site.port. If site.{} becomes empty after removals it is deleted.
+   * ONE ACTIVE MODE PER WRITE (measured 2026-10-02, EGPT-Evidence: `set-site --port` then
+   * `set-site --static` left BOTH fields, and the gateway silently served the dead dev-server
+   * port). Setting `static` without `port` in the same call CLEARS site.port and
+   * site.protocol; setting `port` without `static` CLEARS site.static. Passing BOTH in one
+   * call is the explicit combined write and keeps both — the gateway then serves the dev
+   * server (site.port wins; createViteProxyConfig), stated on the serve banner.
+   *
+   * site.protocol ("http" | "https", default https when absent) names the scheme of the
+   * dev-server upstream. It is meaningless without site.port, and a write that would leave
+   * protocol without port is refused loud — no auto-detection, no try-both fallback.
+   *
+   * Pass null for a field to remove it (what `--unset` does for all three). Removals clear
+   * only the named field. If site.{} becomes empty after removals it is deleted.
    * Persists via save() at the end — same auto-save pattern as setMicroservicePort().
    * Hard-fails if appId is not mapped in env.platform or env.products.
    *
@@ -861,37 +873,64 @@ export class WorkspaceConfig {
    * @param {Object} fields - Fields to set on site.{}
    * @param {string|null} [fields.static] - Relative static-site path to set, or null to remove site.static
    * @param {number|string|null} [fields.port] - Site dev-server port to set, or null to remove site.port
+   * @param {string|null} [fields.protocol] - Dev-server upstream scheme "http"|"https", or null to remove site.protocol
    * @returns {Promise<string>} Path to saved config (from save())
    */
   async setStaticSite(appId, fields = {}) {
     if (!appId) throw new Error('appId is required');
     if (!fields || typeof fields !== 'object') throw new Error('fields object is required');
 
+    const settingStatic = 'static' in fields && fields.static !== null && fields.static !== undefined;
+    const settingPort = 'port' in fields && fields.port !== null && fields.port !== undefined;
+    const settingProtocol = 'protocol' in fields && fields.protocol !== null && fields.protocol !== undefined;
+
+    if (settingProtocol && fields.protocol !== 'http' && fields.protocol !== 'https') {
+      throw new Error(
+        `site.protocol must be "http" or "https" (got ${JSON.stringify(fields.protocol)}). ` +
+        `It names the scheme of the app's own dev server behind the gateway's /p/${appId} proxy.`
+      );
+    }
+
     const entry = this._liveEnvEntry(appId);
 
-    if (!entry.site) entry.site = {};
+    // Compute the resulting site.{} first, so validation failures write NOTHING.
+    const site = { ...(entry.site || {}) };
 
-    // site.static — set or remove
-    if ('static' in fields) {
-      if (fields.static === null || fields.static === undefined) {
-        delete entry.site.static;
-      } else {
-        entry.site.static = fields.static;
-      }
+    // One active mode per write (see doc comment above).
+    if (settingStatic && !settingPort) {
+      delete site.port;
+      delete site.protocol;
+    }
+    if (settingPort && !settingStatic) {
+      delete site.static;
     }
 
-    // site.port — set or remove (for static+devCommand sites)
+    if ('static' in fields) {
+      if (fields.static === null || fields.static === undefined) delete site.static;
+      else site.static = fields.static;
+    }
     if ('port' in fields) {
-      if (fields.port === null || fields.port === undefined) {
-        delete entry.site.port;
-      } else {
-        entry.site.port = fields.port;
-      }
+      if (fields.port === null || fields.port === undefined) delete site.port;
+      else site.port = fields.port;
+    }
+    if ('protocol' in fields) {
+      if (fields.protocol === null || fields.protocol === undefined) delete site.protocol;
+      else site.protocol = fields.protocol;
     }
 
-    // Clean up an empty site.{} so we never leave a bare {} behind
-    if (Object.keys(entry.site).length === 0) {
+    // protocol describes the dev-server upstream — without a port it describes nothing.
+    if ('protocol' in site && !('port' in site)) {
+      throw new Error(
+        `site.protocol is only valid in dev-server mode: set it together with --port ` +
+        `(or on an app whose site.port is already set). Nothing was written for ${appId}.`
+      );
+    }
+
+    if (Object.keys(site).length === 0) {
+      // Clean up an empty site.{} so we never leave a bare {} behind
       delete entry.site;
+    } else {
+      entry.site = site;
     }
 
     return this.save();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.1.8",
-    "@descix/sdk": "^2.0.0",
+    "@descix/app-sdk": "^0.2.0",
+    "@descix/sdk": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",
     "chalk": "^5.6.2",

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -153,7 +153,7 @@ descix kb corpus sync -a myapp -k General
 
 ### Calling /apifront from your microservice (data plane)
 
-**The microservice IS the CLI's api-client running in the cloud** (CEO-D-2026-06-02-APP-MICROSERVICE-IS-CLI-CLIENT-WALLET-SIG). To call Core commands (`app_records_*`, `get_app_asset`, `get_asset_upload_token`, RAG, ...) the scaffold's `mcpClient` authenticates to `/apifront` **exactly like the CLI**: it holds the **developer's own durable credential** (`wallet_address` + `signature`) and calls `reconnect_by_wallet` to mint a session — then makes calls **as the developer**. There is NO `register-delegate`, NO `SERVICE_KEY`, NO service account, NO OIDC.
+**The microservice IS the CLI's api-client running in the cloud** (CEO-D-2026-06-02-APP-MICROSERVICE-IS-CLI-CLIENT-WALLET-SIG). To call Core commands (`app_records_*`, `get_app_asset`, `get_asset_upload_token`, RAG, ...) the scaffold's `mcpClient` authenticates to `/apifront` **exactly like the CLI**: it holds the **developer's own durable credential** (`wallet_address` + `signature`) and calls `reconnect_by_wallet` to mint a session — then makes calls **as the developer**. There is NO per-service key, NO service account, NO OIDC.
 
 **Provide the developer credential (gitignored / secret — never checked in):**
 1. Copy `dev-overrides.example.json` → `dev-overrides.json` (this file is `.gitignore`d).
@@ -170,7 +170,7 @@ descix microservice register
 # then: cp dev-overrides.example.json dev-overrides.json  and fill in the developer credential
 ```
 
-> `descix microservice register-delegate` still exists for genuine **service-slot** mesh calls (one service calling another's tools as a delegate). It is NOT used for the app **data plane** — that authenticates as the developer per the model above.
+**Inbound calls carry the caller, not a service identity** (CEO-D-2026-06-02-APP-DATA-PLANE). `/apifront` forwards each call to your service with the caller's identity injected as `params._descix`, isolated per `app_id`; your handler acts on that caller. `descix microservice register --help` prints this model.
 
 ---
 
@@ -334,9 +334,10 @@ A single-app (non-monorepo) workspace uses the same v2.1 shape with only `env.pl
 3. Check `.vscode/mcp.json` exists with a `descix` server (this file is skipped, by design, if the DeSciX VS Code extension is installed — it registers MCP natively)
 
 ### "401 Unauthorized on a loopback / mesh call"
-For the app data plane, your service authenticates AS the developer (wallet_address + signature). A 401 means the
-developer credential is missing or wrong: check `DEVELOPER_WALLET_ADDRESS` + `DEVELOPER_SIGNATURE` in the gitignored
-`dev-overrides.json` (dev) / the secret (prod). Then restart the service.
+Outbound, your service authenticates AS the developer (wallet_address + signature) through `createServiceApiClient`. A 401
+means the developer credential is missing or wrong: check `DEVELOPER_WALLET_ADDRESS` + `DEVELOPER_SIGNATURE` in the
+gitignored `dev-overrides.json` (dev) / the secret (prod). Then restart the service. Inbound, the caller's identity
+arrives as `params._descix`; no key is provisioned for your service.
 Discover it via `descix tell-me-how "my service gets 401 on a loopback call"`.
 
 ### "Session expired"

package/templates/scaffolds/microservice/app.js

@@ -8,7 +8,7 @@ import express from 'express';
 import http from 'http';
 import cors from 'cors';
 import { initializeServiceConfig, utils } from './services/utils.js';
-import { killExistingProcess } from '@descix/cloud-core';
+import { killExistingProcess, mountMeshApi } from '@descix/cloud-core';
 import apiRouter from './services/apiFront.js';
 
 const app = express();
@@ -72,8 +72,12 @@ initializeServiceConfig().then(() => {
         res.status(200).send('OK');
     });
 
-    // Mount API Router
-    app.use('/api', apiRouter);
+    // Mount the API router on /api — the surface the platform proxies mesh commands to. The
+    // mount is @descix/cloud-core's: it puts the signed-context verifier in front of the router,
+    // in the mode config resolved at boot. A deployed service boots only with
+    // MESH_CTX_VERIFY_MODE=enforce (defaults-config.json), so an unsigned request is refused
+    // before it reaches a handler. Do not mount /api yourself.
+    mountMeshApi(app, apiRouter);
 
     // Start Server
     if (!port || port === 'auto') {

package/templates/scaffolds/microservice/defaults-config.json

@@ -3,5 +3,6 @@
   "LOCAL_PORT": "auto",
   "CORE_API_URL": "https://localhost:4000/apifront",
   "community_id": "{{COMMUNITY_ID}}",
-  "app_id": "{{APP_ID}}"
+  "app_id": "{{APP_ID}}",
+  "MESH_CTX_VERIFY_MODE": "enforce"
 }

package/templates/scaffolds/microservice/dev-overrides.example.json

@@ -1,5 +1,6 @@
 {
   "_comment": "Copy this file to dev-overrides.json (GITIGNORED) and fill in the developer credential. The microservice authenticates to /apifront AS the developer — exactly like the CLI — using these. In prod these come from a SECRET, never from a checked-in file. defaults-config.json must NOT contain the signature (it is a credential).",
   "DEVELOPER_WALLET_ADDRESS": "0xYOUR_WALLET_ADDRESS",
-  "DEVELOPER_SIGNATURE": "PASTE_YOUR_DURABLE_SIGNATURE_FROM_.descix/wallet.json"
+  "DEVELOPER_SIGNATURE": "PASTE_YOUR_DURABLE_SIGNATURE_FROM_.descix/wallet.json",
+  "_MESH_CTX_VERIFY_MODE_comment": "defaults-config.json sets MESH_CTX_VERIFY_MODE to enforce, the only value a deployed service boots with. On your own machine you may relax it here: \"warn\" (verify and log, never refuse) or \"\" (no verification; every request is stamped meshContextVerified=false). Never set MESH_CTX_PUBLIC_KEY or MESH_CTX_KEY_ID in any config file: the platform key is resolved by @descix/cloud-core and a copy refuses boot."
 }

package/templates/scaffolds/microservice/manifest.json

@@ -6,7 +6,8 @@
     "healthEndpoint": "/health",
     "debugPort": 3003,
     "app_id": "{{APP_ID}}",
-    "community_id": "{{COMMUNITY_ID}}"
+    "community_id": "{{COMMUNITY_ID}}",
+    "runtime": { "profile": "default", "system_packages": [] }
   },
   "commands": {
     "sample_hello": {

package/templates/scaffolds/microservice/package.json

@@ -11,7 +11,7 @@
     "gen-jwt-secret": "node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))'"
   },
   "dependencies": {
-    "@descix/cloud-core": "^1.0.0",
+    "@descix/cloud-core": "^1.2.0",
     "@descix/platform-api": "^2.0.0",
     "@google-cloud/secret-manager": "^5.0.1",
     "@google-cloud/storage": "^7.7.0",
@@ -19,7 +19,7 @@
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
-    "@descix/sdk": "^2.0.0",
+    "@descix/sdk": "^3.0.0",
     "@descix/cli": "^1.0.0"
   },
   "devDependencies": {

package/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md

@@ -25,8 +25,9 @@ descix microservice register                     # register the service manifest
 > + `DEVELOPER_SIGNATURE` (the developer's own wallet credential, from
 > `.descix/wallet.json`) and calls `reconnect_by_wallet` to mint a session —
 > exactly like the CLI. Put the credential in the GITIGNORED `dev-overrides.json`
-> (dev) / a secret (prod), NEVER `defaults-config.json`. There is NO
-> `register-delegate`, NO `SERVICE_KEY`, NO service account for the data plane.
+> (dev) / a secret (prod), NEVER `defaults-config.json`. There is NO per-service
+> key and NO service account for the data plane. Inbound calls carry the caller's
+> identity as `params._descix`, isolated per app_id (CEO-D-2026-06-02-APP-DATA-PLANE).
 > **HTTP 401?** The developer credential is missing or wrong — check those two keys.
 
 ## Prerequisites

package/lib/commands/retired-kb-sync.js

@@ -1,112 +0,0 @@
-/**
- * ONE OWNER for the retirement of every superseded KB-sync surface.
- *
- * CEO 2026-08-29: "there should never be a deprecated path and then everything else is a
- * waterfall of problems." The CLI exposes exactly ONE kb sync surface — `descix kb corpus
- * sync` (git-synced manifest). Every other sync path is DELETED: its implementation is gone
- * and its old name exits NON-ZERO naming the replacement. That is not a compat fence — a
- * compat fence is a path that still WORKS under an old name. These do not work at all.
- *
- * Why a module and not a literal at each site: two derivations of one fact is the general
- * form of mirror drift. The retired set is enumerated ONCE here. bin/descix.js registers by
- * ITERATING this list via registerAllRetiredKbSync() -- it does not name any retired verb
- * itself -- and tests/kb-sync-single-surface.test.js asserts against the same list. So the
- * drift is closed in BOTH directions: a surface added to the list is registered, and a
- * surface cannot be registered without being in the list.
- */
-
-/** The single canonical KB sync surface. Named in every refusal. */
-export const CANONICAL_KB_SYNC = 'descix kb corpus sync';
-
-/** The verb that creates a KB — `kb corpus sync`'s dependency (I4). */
-export const CANONICAL_KB_CREATE = 'descix app init --kb <kb_name>';
-
-/**
- * Every KB-sync surface retired by ws-devplane-cli-kb-surface-single-canonical-sync.
- * `invocation` is what a user types; `parent` is the commander parent it hung off.
- */
-export const RETIRED_KB_SYNC_SURFACES = [
-  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync' },
-  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb' },
-  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk' },
-  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync' },
-];
-
-/** Implementations deleted with those surfaces. No exported symbol survives without a caller (I3). */
-export const DELETED_KB_SYNC_SYMBOLS = [
-  'runKbChunk',
-  'runKbSync',
-  'runKbBuild',
-  'runKbStatus',
-  'runKbCompare',
-  'updateKB',
-];
-
-/**
- * The single refusal message. Fails loud and names the replacement — never warns, never falls back.
- * @param {string} invocation - the retired invocation the user typed, e.g. 'descix kb chunk'
- * @returns {string}
- */
-export function retiredKbSyncMessage(invocation) {
-  return (
-    `\`${invocation}\` has been REMOVED. There is no replacement flag and no fallback.\n\n` +
-    `Use the one canonical KB sync surface:\n` +
-    `  ${CANONICAL_KB_SYNC} -a <app_id> [-k <kb_name>]\n\n` +
-    `It syncs from a git-tracked corpus manifest (.descix/manifests/), which the removed ` +
-    `path could not do. If the KB does not exist yet, create it first with ` +
-    `\`${CANONICAL_KB_CREATE}\`.`
-  );
-}
-
-/**
- * Register a retired invocation so it exits NON-ZERO naming the canonical surface.
- * Accepts and ignores any args/options the old surface took, so an old script fails with
- * this message rather than a confusing commander parse error.
- *
- * @param {import('commander').Command} parent - commander parent to attach to
- * @param {string} name - the retired command name
- * @param {string} invocation - full invocation used in the message
- * @param {(s:string)=>string} red - chalk.red or equivalent
- */
-export function registerRetiredKbSync(parent, name, invocation, red) {
-  return parent
-    .command(name, { hidden: true })
-    .description(`REMOVED — use \`${CANONICAL_KB_SYNC}\``)
-    .allowUnknownOption(true)
-    // helpOption(false) is load-bearing: commander intercepts `--help` BEFORE the action and
-    // exits 0. A retired surface must exit NON-ZERO however it is invoked — `descix kb chunk`
-    // and `descix kb chunk --help` must both fail and name the replacement. Without this, the
-    // most natural way a user probes a dead verb is the one way it appears to still work.
-    .helpOption(false)
-    .argument('[args...]', 'ignored')
-    .action(() => {
-      console.error(red(`\n❌ ${retiredKbSyncMessage(invocation)}\n`));
-      process.exit(1);
-    });
-}
-
-/**
- * Register EVERY retired surface by iterating RETIRED_KB_SYNC_SURFACES.
- *
- * This is what makes the one-owner claim true rather than merely asserted: bin/descix.js
- * calls this once and never names a retired verb itself, so a retired surface cannot be
- * registered without appearing in the list above.
- *
- * @param {Record<string, import('commander').Command>} roots - seed parents, e.g. { program, kb }
- * @param {(s:string)=>string} red - chalk.red or equivalent
- * @returns {Record<string, import('commander').Command>} roots plus each registered surface by id
- */
-export function registerAllRetiredKbSync(roots, red) {
-  const byId = { ...roots };
-  for (const s of RETIRED_KB_SYNC_SURFACES) {
-    const parent = byId[s.parent];
-    if (!parent) {
-      throw new Error(
-        `retired-kb-sync: no parent '${s.parent}' available for '${s.invocation}'. ` +
-        'Seed it in the roots map or order the list so the parent is registered first.'
-      );
-    }
-    byId[s.id] = registerRetiredKbSync(parent, s.name, s.invocation, red);
-  }
-  return byId;
-}