@descix/cli 1.0.17 → 1.0.19

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_Cloud` 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.
 
@@ -24,7 +24,7 @@ AI Agent (Cursor/MCP Client)
    execute_remote_command
        │
        ▼
-   DeSciX_Cloud (Federated Broker)
+   DeSciX Backend (Federated Broker)
        │
        ├──► Service 1 (Powch)
        ├──► Service 2 (SmartModel)
@@ -42,18 +42,33 @@ MCP provides the communication protocol between AI agents and the DeSciX platfor
 **Key Tools:**
 - `tell_me_how` - Semantic tool discovery
 - `execute_remote_command` - Execute any backend command
-- `descix_init` - Initialize local workspace
-- `chat_with_kb` - Query knowledge bases
-- `search_knowledge_base` - Search specific KBs
+- `descix_doctor` - CLI-local startup diagnostic (auth, workspace, tools, warnings)
+- `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
 
@@ -91,13 +106,17 @@ Once signed in, `tell_me_how` is the **primary entry point** for discovering pla
 
 **Rule:** Sign in, then ask `tell_me_how` first, then execute the recommended command.
 
-### 3.2 Three Scopes
+### 3.2 Scopes
+
+The validated `tell_me_how` scope enum has five values:
 
 | Scope | Description | Use Case |
 |-------|-------------|----------|
-| `entitlements` (default) | Only tools user has access to | Production usage |
+| `entitlements` (default) | Only tools the user has access to | Production usage |
 | `project` | Tools filtered by workspace.json | Working within a project |
 | `discovery` | All available tools | Exploring capabilities |
+| `bootstrap` | Deterministic first-call on-ramp: platform summary, caller context, credit balance, essential tool schemas (no vector search; `question` is optional for this scope only) | First contact / first call in a session |
+| `artifact` | Deterministic build/reproduce provenance for a published app (npm package + spec, artifact/notebook URLs, runnable `npx` commands), no vector search | "How do I build on / reproduce this app?" |
 
 ### 3.3 CLI Usage
 
@@ -151,21 +170,23 @@ After `descix quickstart` completes:
 
 ### 4.1 Federated MCP Broker
 
-`DeSciX_Cloud` 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_Cloud (Broker)
-  └── Aggregated tools/list
+DeSciX Backend (Broker)
+  └── 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
@@ -199,14 +220,11 @@ execute_remote_command({
 
 ### 4.3 Service Registration
 
-Services self-register with the broker:
+Services self-register with the broker in one step — registration also vectorizes the README you
+pass, so there is no separate developer-facing vectorize step:
 
 ```bash
-# Register service manifest
-descix microservice register -m ./manifest.json
-
-# Vectorize SERVICE_README for discovery
-descix microservice vectorize -r SERVICE_README.md
+descix microservice register -r SERVICE_README.md
 ```
 
 ### 4.4 The execute_remote_command Pattern
@@ -309,11 +327,13 @@ When `--scope project` is used:
 
 ### 6.1 KB Operations via tell_me_how
 
-The new SDK V2 KB commands are discoverable:
+`tell_me_how` can be asked about KB sync in plain language, but the actionable answer for a
+developer is always the CLI verb, not the raw backend command names (`kb_sync_chunks` etc. are
+internal to the backend, not something the CLI calls directly by name):
 
 ```bash
 descix tell-me-how "How do I sync my knowledge base?"
-# Returns: kb_sync_chunks, kb_get_chunk_ids, kb_delete_chunks
+# The developer-facing command either way: descix kb corpus sync
 ```
 
 ### 6.2 workspace.json from Hydration
@@ -324,7 +344,7 @@ descix tell-me-how "How do I sync my knowledge base?"
 {
   "env": { "apiUrl": "https://dev.descix.net", "products": [ /* one entry per app */ ] },
   "driveConfig": {
-    "base_folder_id": "..."  // For tell_me_how project scope
+    "base_folder_id": "..."  // Only used by `descix drive pull/push` — unrelated to tell_me_how scope
   }
 }
 ```
@@ -334,9 +354,9 @@ descix tell-me-how "How do I sync my knowledge base?"
 Custom services integrate with the same pattern:
 
 1. Create `SERVICE_README_{name}.md`
-2. Register with `descix microservice register`
-3. Vectorize with `descix microservice vectorize`
-4. Tools become discoverable via `tell_me_how`
+2. Register with `descix microservice register -r SERVICE_README_{name}.md` — this both publishes
+   the manifest AND vectorizes the README in one step
+3. Tools become discoverable via `tell_me_how`
 
 ---
 
@@ -355,7 +375,8 @@ Custom services integrate with the same pattern:
 1. **Document all commands in SERVICE_README** - Required for discovery
 2. **Use clear descriptions** - "Use when:" is crucial for semantic matching
 3. **Include examples** - Helps AI agents understand usage
-4. **Register after changes** - Re-vectorize when README updates
+4. **Re-register after README changes** - `descix microservice register -r <file>` re-vectorizes
+   automatically; there is no separate vectorize step
 
 ### 7.3 Common Patterns
 
@@ -407,22 +428,11 @@ cd /path/to/workspace
 
 ### 8.3 "Command not found"
 
-**Cause:** Service not registered or command deprecated.
+**Cause:** Service not registered, or the README wasn't vectorized.
 
 **Solution:**
-1. Verify service is registered: `descix microservice list`
-2. Check if command was deprecated in V2
-3. Use `tell_me_how --scope discovery` to find alternatives
-
----
-
-## 9. File References
-
-| Component | Path |
-|-----------|------|
-| MCP Tools | `DeSciX_Core/descix-cli/bin/mcp-server.js` |
-| tell_me_how Implementation | `DeSciX_Cloud/microservice/services/commandHandlers/ragCommands.js` |
-| execute_remote_command | `DeSciX_Cloud/microservice/services/apiFront.js` |
-| SERVICE_README Template | `DeSciX_Core/descix-cli/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md` |
-| Workspace Config | `DeSciX_Core/descix-cli/lib/workspace-config.js` |
-| Service Registration | `DeSciX_Core/descix-cli/bin/descix.js` |
+1. Re-run `descix microservice register -r SERVICE_README_<name>.md` — it re-publishes the
+   manifest and re-vectorizes the README (`descix microservice list` exists to enumerate
+   registered services, but it is an admin-only command, not something a developer runs)
+2. Check `descix microservice health <name>` to confirm the service itself is reachable
+3. Use `descix tell-me-how --scope discovery "..."` to find alternatives

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

@@ -160,13 +160,12 @@ descix site status -c egpt -a egpt-mydocs      # site status/list need both when
 
 ---
 
-## 7. File References
-
-| Component | Path | Description |
-|-----------|------|-------------|
-| WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | the loader, the v2.1 writer, `registerApp`, `detectContext` |
-| Origin resolution | `DeSciX_Core/descix-cli/lib/origin.js` | flag → `DESCIX_API_URL` → `env.apiUrl` → default |
-| GlobalConfig | `DeSciX_Core/descix-cli/lib/global-config.js` | user-level settings (`~/.descixrc`) |
-| Config commands | `DeSciX_Core/descix-cli/lib/commands/config.js` | `config init/set-env/set-*` |
-| Wallet file | `DeSciX_Core/descix-cli/lib/wallet-file.js` | `.descix/wallet.json` location |
-| Corpus sync | `DeSciX_Core/descix-cli/lib/commands/corpus.js` | manifests, sync-state |
+## 7. Where each concept lives (conceptual, not a file map)
+
+| Concept | Owner |
+|---|---|
+| Workspace loading, the v2.1 writer, app registration, context detection | `WorkspaceConfig`, internal to `@descix/cli` |
+| Origin resolution precedence | flag → `DESCIX_API_URL` → `env.apiUrl` → default (`descix config` commands) |
+| User-level settings (`~/.descixrc`) | `GlobalConfig`, internal to `@descix/cli` |
+| `.descix/wallet.json` | written by `descix login` |
+| Corpus manifests, sync-state | `descix kb corpus` commands, internal to `@descix/cli` |

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,13 +28,16 @@ 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';
+import { assertKnownCommandForHelp } from '../lib/help-guard.js';
 import { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
@@ -454,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 ============
 
@@ -1950,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)
@@ -2928,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)')
@@ -3288,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>')
@@ -3862,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)')
@@ -4592,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
@@ -4650,6 +4515,10 @@ if (!adminMode && isHelpInvocation(program, rawArgv, { valueFlags: ['--env', '--
   }
 }
 
+// A command that does not exist must not appear to have help (see lib/help-guard.js). This runs
+// before the parse, because Commander resolves --help before it resolves the command.
+assertKnownCommandForHelp(program, process.argv.slice(2));
+
 // Parse arguments
 await program.parseAsync(process.argv);
 

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.`;