@descix/cli 1.0.18 → 1.0.19

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 ============
 
@@ -1951,12 +1953,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 +2927,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 +3288,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 +3740,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 +4452,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';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "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;
-}