@descix/cli 1.0.1 → 1.0.3

package/bin/descix.js

@@ -12,27 +12,122 @@ import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
 import { WorkspaceConfig } from '../lib/workspace-config.js';
+import { CLI_VERSION } from '../lib/cli-version.js';
+// Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
+import {
+  getSessionInteractionId,
+  findSessionsForApp,
+  saveSessionAuthoritative,
+  clearAppSessions,
+  isStaleThreadError,
+} from '../lib/chat-session.js';
 import { GlobalConfig } from '../lib/global-config.js';
 import * as authCommands from '../lib/commands/auth.js';
 import * as configCommands from '../lib/commands/config.js';
-import { runAppWizard } from '../lib/commands/app-wizard.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 { runInit } from '../lib/commands/init.js';
-import * as folderCommands from '../lib/commands/folder.js';
 import * as updateCommands from '../lib/commands/update.js';
+import { registerAllRetiredKbSync, refuseRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
 import { runStatus } from '../lib/commands/status.js';
 import { runDoctor } from '../lib/commands/doctor.js';
+import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
+import { kbVectorCell, kbCountSource } from '../lib/commands/kb-list-render.js';
+import * as corpusCommands from '../lib/commands/corpus.js';
+import * as modelConfigCommands from '../lib/commands/model-config.js';
+import * as brieferCommand from '../lib/commands/briefer/index.js';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 
+
+/**
+ * Emit human-facing PROGRESS for a command that can also emit JSON.
+ *
+ * When `--json` is set, stdout is a DATA CHANNEL: it must contain the JSON document and
+ * nothing else, or every scripted consumer breaks. Progress then goes to stderr, where a
+ * human piping stdout still sees it. Without `--json`, stdout is the human channel and
+ * progress belongs there.
+ *
+ * ONE OWNER of that decision. Before this existed, each --json command re-decided it by
+ * calling console.log directly, and both of them got it wrong: `mcp execute --json` prefixed
+ * the document with "Executing <tool>..." and `app media-upload --json` prefixed it with a
+ * header, a per-file listing and a per-file +/x line. Both exited 0, so a consumer saw a
+ * success code and an unparseable stream. Measured 2026-08-21/22 (seat BEAST): two seats had
+ * independently hand-rolled prefix-stripping workarounds (`tail -n +2`, `raw.find('[')`)
+ * rather than reporting it.
+ *
+ * @param {Object} options - the command's parsed options (read for .json)
+ * @param {...any} args - passed through to console.log / console.error
+ */
+function progress(options, ...args) {
+  if (options && options.json) console.error(...args);
+  else console.log(...args);
+}
+
+/**
+ * THE ONE OWNER of "a command threw, and the process must stop saying why".
+ *
+ * WHY THIS EXISTS (measured 2026-08-30 on the SHIPPED artifact): 27 command actions ended in a
+ * bare `catch (error) { process.exit(1); }`. `DESCIX_API_URL=not-a-url descix credits balance`
+ * exited 1 with ZERO BYTES on stdout AND stderr — the origin owner had built an
+ * OriginInvalidError carrying the full remedy text and this handler threw it away. The contract
+ * row "a configured-but-invalid origin FAILS LOUD naming the fix" was met in the module and
+ * unmet on the artifact, because a message nobody prints is not a message.
+ *
+ * That is this contract's own bug class — silence — reaching the developer through the
+ * contract's own remedy path. A handler that discards the reason is indistinguishable from a
+ * crash, and it trains developers to believe the CLI has no error messages.
+ *
+ * @param {Error} error - the error that ended the command
+ */
+function fail(error) {
+  const message = (error && error.message) ? error.message : String(error);
+  console.error(chalk.red(`\n${message}\n`));
+  process.exit(1);
+}
+
 const program = new Command();
 
 program
   .name('descix')
   .description('DeSciX CLI - Unified command-line interface')
-  .version('1.0.0');
+  .version(CLI_VERSION)
+  .option('--env <name>', 'Target environment: dev, demo, prod (overrides API URL)')
+  .option('--api-url <url>', 'Direct API URL override (e.g., https://demo.descix.net)');
+
+// ============ Global Environment Override ============
+// Maps --env flag to DESCIX_API_URL before any command runs.
+// detectApiUrl() in api-client.js checks process.env.DESCIX_API_URL first.
+
+// Derive ephemeral --env URL map from the canonical WorkspaceConfig.ENV_MAP
+const ENV_URL_MAP = Object.fromEntries(
+  Object.entries(WorkspaceConfig.ENV_MAP).map(([k, v]) => [k, v.url])
+);
+
+program.hook('preAction', (thisCommand) => {
+  const opts = thisCommand.opts();
+
+  // --api-url takes highest priority
+  if (opts.apiUrl) {
+    process.env.DESCIX_API_URL = opts.apiUrl;
+    return;
+  }
+
+  // --env maps to known URLs
+  if (opts.env) {
+    const envName = opts.env.toLowerCase();
+    if (!(envName in ENV_URL_MAP)) {
+      console.error(chalk.red(`Unknown environment: ${opts.env}. Use: dev, demo, prod`));
+      process.exit(1);
+    }
+    // Every named environment resolves to a URL (including dev → cloud DEV).
+    // A local backend is a URL you name, not an environment.
+    process.env.DESCIX_API_URL = ENV_URL_MAP[envName];
+  }
+});
 
 // ============ Authentication Commands (No Auth Required) ============
 
@@ -41,33 +136,18 @@ program
   .command('login')
   .description('Authenticate with DeSciX via device login (opens browser)')
   .option('-u, --url <url>', 'API URL override')
-  .option('--dev', 'Use development server (https://localhost:4000)')
   .option('--wallet', 'Use direct wallet connection (advanced, not yet implemented)')
+  .option('--no-oauth', 'Skip the OAuth long-lived token leg (wallet-signature login only)')
+  .option('--scope <scope>', 'OAuth scope to request (default: mcp:read mcp:tools mcp:write mcp:admin)')
   .action(async (options) => {
     try {
-      // Handle --dev flag
-      if (options.dev) {
-        const workspaceConfig = await WorkspaceConfig.tryLoad(process.cwd());
-        if (workspaceConfig) {
-          workspaceConfig.apiUrl = 'https://localhost:4000';
-          workspaceConfig.environment = 'development';
-          await workspaceConfig.save(process.cwd());
-        } else {
-          const gc = await GlobalConfig.load();
-          gc.api_url = 'https://localhost:4000';
-          gc.environment = 'development';
-          await gc.save();
-        }
-        console.log(chalk.cyan('✓ Configured for development (https://localhost:4000)\n'));
-      }
-      
       if (options.wallet) {
         await authCommands.loginWallet();
       } else {
         await authCommands.loginDevice(options);
       }
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -78,7 +158,20 @@ program
     try {
       await authCommands.logout();
     } catch (error) {
-      process.exit(1);
+      fail(error);
+    }
+  });
+
+program
+  .command('admin-login')
+  .description('Bootstrap CLI credentials for platform admins (requires admin group membership)')
+  .requiredOption('-e, --email <email>', 'Admin email (must be in platform admin Google Group)')
+  .option('-u, --url <url>', 'API URL override')
+  .action(async (options) => {
+    try {
+      await authCommands.adminLogin(options);
+    } catch (error) {
+      fail(error);
     }
   });
 
@@ -121,7 +214,7 @@ program
       await requireAuth(apiClient);
       await authCommands.whoami();
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -132,7 +225,7 @@ program
     try {
       await authCommands.reconnect();
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -161,6 +254,53 @@ program
     }
   });
 
+program
+  .command('health')
+  .description('Check platform service health (env-aware: local-port in DEV, gcloud+HTTPS in DEMO/PROD)')
+  .option('--env <name>', 'Target environment: dev|demo|prod (default: dev). Also accepted at top level: descix --env=demo health ...')
+  .option('-m, --microservice <name>', 'Check a specific service/app by appId')
+  .option('-j, --json', 'Output raw JSON')
+  .action(async (options) => {
+    try {
+      // Resolve --env in priority order: subcommand explicit > program parent > 'dev'.
+      // Commander would otherwise silently default to 'dev' even when the parent
+      // --env=demo is supplied (because the subcommand owns its own flag space).
+      const parentEnv = program.opts().env || null;
+      const env = options.env || parentEnv || 'dev';
+      await runHealth({ ...options, env });
+    } catch (error) {
+      console.error(chalk.red(`\nHealth check error: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ============ Briefer Command (Code-Grounded Mental Model Regen) ============
+// WS-DESCIX-BRIEFER-CLI M1: CLI scaffolding + extractor contract.
+// See DeSciX/DeSciX_Core/descix-cli/lib/commands/briefer/ for implementation.
+// Scope doc: docs/design/ws-descix-briefer-cli.md
+// Briefer target: DeSciX/V2_docs/architecture/platform-must-know-briefer.md
+
+program
+  .command('briefer')
+  .description('Regenerate platform-must-know-briefer.md from live code + gcloud + Firestore (HARD-FAIL on drift)')
+  .option('--env <name>', 'Target environment: dev|demo|prod (also accepted at the top level: descix --env=demo briefer ...)')
+  .option('--out <path>', 'Override output path (default: workspace-root/DeSciX/V2_docs/architecture/platform-must-know-briefer.md)')
+  .option('--check', 'Drift-detection mode: regen to memory, diff against canonical, non-zero exit on drift')
+  .option('-v, --verbose', 'Print per-source paths, citations, and timings')
+  .action(async (options) => {
+    try {
+      // Resolve --env in priority order: subcommand explicit > program parent > 'dev'.
+      // Commander would otherwise silently default to 'dev' even when the parent
+      // --env=demo is supplied (because the subcommand owns its own flag space).
+      const parentEnv = program.opts().env || null;
+      const env = options.env || parentEnv || 'dev';
+      await brieferCommand.runBriefer({ ...options, env });
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Briefer command failed: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ============ Buy Commands (Crypto Payments) ============
 
 const buyCommand = program
@@ -179,7 +319,7 @@ buyCommand
     try {
       await buyCommands.createQuote(options);
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -190,7 +330,7 @@ buyCommand
     try {
       await buyCommands.checkStatus(quoteId);
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -206,7 +346,7 @@ buyCommand
         initialInterval: parseInt(options.interval)
       });
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -217,195 +357,112 @@ buyCommand
     buyCommands.listChains();
   });
 
-// ============ Sync Commands ============
+// ============ AI Credits Commands (WS-HEADLESS-MVP-A2, CEO-D-2026-07-01 D2) ============
+// Platform-wide USD AI-credits: metered RAG/agent calls debit this balance.
+// NOT community tokens (those are under `descix buy`).
 
-const syncCommand = program
-  .command('sync')
-  .description('Content sync operations (context-aware)');
-
-// Context-aware sync: assets
-syncCommand
-  .command('assets')
-  .description('Sync app assets (icon, description, system_instructions) - context-aware')
-  .option('--push', 'Push local assets to Drive (default)')
-  .option('--pull', 'Pull assets from Drive to local')
-  .option('--status', 'Show sync status without syncing')
-  .option('-c, --community <id>', 'Community ID (uses context if not provided)')
-  .option('-a, --app <id>', 'App ID (uses context if not provided)')
+const creditsCommand = program
+  .command('credits')
+  .description('Platform-wide USD AI credits (metered AI consumption)');
+
+creditsCommand
+  .command('balance')
+  .description('Show your AI-credits balance')
+  .action(async () => {
+    try {
+      await creditsCommands.showBalance();
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+creditsCommand
+  .command('history')
+  .description('Show your credit ledger (purchases, debits, grants)')
+  .option('--limit <n>', 'Max entries (default 50)')
   .action(async (options) => {
     try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      // Load workspace context
-      const workspaceConfig = await WorkspaceConfig.load();
-      const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
-      const appId = ctx.appId;
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
-        process.exit(1);
-      }
-      
-      if (options.status) {
-        console.log(chalk.cyan(`\n📊 Asset Sync Status: ${communityId}/${appId}\n`));
-        // TODO: Implement status check
-        console.log(chalk.gray('  Status check not yet implemented for assets.\n'));
-        return;
-      }
-      
-      if (options.pull) {
-        console.log(chalk.cyan(`\n📥 Pulling assets from Drive: ${communityId}/${appId}\n`));
-        // TODO: Implement pull
-        console.log(chalk.gray('  Pull not yet implemented. Use descix update app for push.\n'));
-        return;
-      }
-      
-      // Default: push
-      await updateCommands.updateApp(options);
-      
+      await creditsCommands.showHistory(options);
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
-      process.exit(1);
+      fail(error);
     }
   });
 
-// Context-aware sync: kb
-syncCommand
-  .command('kb')
-  .description('Sync knowledge base files - context-aware')
-  .argument('[stage]', 'Specific stage: stage1, stage2, stage3, all (default: all)')
-  .option('--push', 'Push local to Drive (Stage 1)')
-  .option('--pull', 'Pull from Drive to local (Stage 1)')
-  .option('--status', 'Show sync status')
-  .option('-c, --community <id>', 'Community ID (uses context if not provided)')
-  .option('-a, --app <id>', 'App ID (uses context if not provided)')
-  .option('-k, --kb <name>', 'KB name (default: General)')
-  .action(async (stage, options) => {
+creditsCommand
+  .command('buy')
+  .description('Buy AI credits with USD (Stripe checkout)')
+  .requiredOption('--usd <amount>', 'USD amount of credits to buy')
+  // The default is the origin this invocation is already talking to, NOT a fixed production
+  // host — see commands/credits.js. Naming a prod origin here made --help itself the misreport.
+  .option('--return-base <url>', 'Base URL for the checkout success/cancel landing (default: the API origin in use)')
+  .action(async (options) => {
     try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      // Load workspace context
-      const workspaceConfig = await WorkspaceConfig.load();
-      const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
-      const appId = ctx.appId;
-      const kbId = options.kb || ctx.kbId || 'General';
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
-        process.exit(1);
-      }
-      
-      if (options.status) {
-        console.log(chalk.cyan(`\n📊 KB Sync Status: ${communityId}/${appId}/${kbId}\n`));
-        // Call existing status logic
-        const stages = stage === 'stage1' ? [1] : stage === 'stage2' ? [2] : stage === 'stage3' ? [3] : [1, 2, 3];
-        
-        for (const s of stages) {
-          if (s === 2) {
-            const response = await apiClient.invoke('get_drive_gcs_sync_status', {
-              community_id: communityId, app_id: appId, kb_id: kbId
-            });
-            const result = response.message || response;
-            console.log(chalk.yellow('Stage 2: Drive → GCS'));
-            console.log(chalk.gray(`  To Extract: ${result.to_extract || 0}`));
-            console.log(chalk.gray(`  In Sync: ${result.in_sync || 0}\n`));
-          }
-          if (s === 3) {
-            const response = await apiClient.invoke('get_gcs_pinecone_sync_status', {
-              community_id: communityId, app_id: appId, kb_id: kbId
-            });
-            const result = response.message || response;
-            console.log(chalk.yellow('Stage 3: GCS → Pinecone'));
-            console.log(chalk.gray(`  To Vectorize: ${result.to_vectorize || 0}`));
-            console.log(chalk.gray(`  Total Vectors: ${result.total_vectors || 0}\n`));
-          }
-        }
-        return;
-      }
-      
-      // Determine what to sync
-      const stage1Only = stage === 'stage1' || options.push;
-      const stageToRun = stage || 'all';
-      
-      console.log(chalk.cyan(`\n📤 KB Sync: ${communityId}/${appId}/${kbId} (${stageToRun})\n`));
-      
-      await updateCommands.updateKB({ 
-        ...options,
-        kb: kbId,
-        stage1Only: stage1Only,
-        skipStage1: stage === 'stage2' || stage === 'stage3'
-      });
-      
+      await creditsCommands.buyCredits({ usd: options.usd, returnBase: options.returnBase });
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
-      process.exit(1);
+      fail(error);
     }
   });
 
-// Context-aware sync: site
-syncCommand
-  .command('site')
-  .description('Sync CodeSite to GCS - context-aware')
-  .option('--push', 'Deploy to GCS (default)')
-  .option('--preview', 'Deploy to preview URL')
-  .option('--status', 'Show deployment status')
-  .option('--port <number>', 'Register local dev server port')
-  .option('-c, --community <id>', 'Community ID (uses context if not provided)')
-  .option('-a, --app <id>', 'App ID (uses context if not provided)')
+creditsCommand
+  .command('grant')
+  .description('ADMIN: grant AI credits to a user')
+  .requiredOption('--user <user_id>', 'Target user id')
+  .requiredOption('--usd <amount>', 'USD amount to grant')
+  .requiredOption('--reason <text>', 'Audit reason')
   .action(async (options) => {
     try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      // Load workspace context
-      const workspaceConfig = await WorkspaceConfig.load();
-      const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
-      const appId = ctx.appId;
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
-        process.exit(1);
-      }
-      
-      if (options.status) {
-        console.log(chalk.cyan(`\n📊 Site Status: ${communityId}/${appId}\n`));
-        const response = await apiClient.invoke('get_site_manifest', {
-          community_id: communityId, app_id: appId
-        });
-        const result = response.message || response;
-        if (result.manifest) {
-          console.log(chalk.gray(`  Files: ${Object.keys(result.manifest.files || {}).length}`));
-          console.log(chalk.gray(`  URL: ${result.site_url}\n`));
-        } else {
-          console.log(chalk.gray('  No site deployed.\n'));
-        }
-        return;
-      }
-      
-      // Default: push
-      await updateCommands.updateSite({ 
-        ...options,
-        preview: options.preview,
-        port: options.port ? parseInt(options.port) : undefined
-      });
-      
+      await creditsCommands.grantCredits(options);
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
-      process.exit(1);
+      fail(error);
+    }
+  });
+
+creditsCommand
+  .command('refund')
+  .description('ADMIN: remove AI credits from a user (e.g. after a Stripe refund)')
+  .requiredOption('--user <user_id>', 'Target user id')
+  .requiredOption('--usd <amount>', 'USD amount to remove')
+  .requiredOption('--reason <text>', 'Audit reason')
+  .action(async (options) => {
+    try {
+      await creditsCommands.refundCredits(options);
+    } catch (error) {
+      fail(error);
     }
   });
 
+// ============ Airdrop Commands (WS-ADMIN-B1 manual-trigger) ============
+// Per CEO-D-MANUAL-TRIGGER-NO-CRON (2026-04-20), airdrop batch execution is operator-triggered
+// via this CLI command group rather than Cloud Scheduler cron. Server-side access is gated on
+// platform-admin membership (`isPlatformAdmin(user)`); the server emits an on_chain_log row
+// with `caller.operator_email` for audit.
+
+const airdropCommand = program
+  .command('airdrop')
+  .description('Admin airdrop migration operations (WS-ADMIN-B1)');
+
+airdropCommand
+  .command('execute-queue')
+  .description('Manually trigger airdrop_execute_queue on the target env (admin-only)')
+  .option('--community <slug>', 'Community slug for per-community batch scoping (REQUIRED for --apply)')
+  .option('--dry-run', 'Read-only preview: encode calldata, estimate gas, validate net-zero invariant. No PK, no tx, no state mutation.')
+  .option('--apply', 'Live execution: requires --signer-pk-file or interactive prompt-password. Mutually exclusive with --dry-run.')
+  .option('--signer-pk-file <path>', 'Path to file containing admin signer PK (0x + 64 hex). Required for --apply unless prompted interactively.')
+  .option('--batch-size <n>', 'Cap on users processed this run (server caps at AIRDROP_MAX_RUN_USERS)')
+  .action(async (options) => {
+    try {
+      await airdropCommands.executeQueue(options);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+// ============ 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.
+
 // ============ Community/App Commands ============
 
 const communityCommand = program
@@ -441,17 +498,23 @@ communityCommand
 communityCommand
   .command('info')
   .description('Get community information')
-  .requiredOption('-c, --community <id>', 'Community ID')
+  .option('-c, --community <id>', 'Community ID')
+  .option('-n, --name <id>', 'Community ID (alias for -c)')
   .action(async (options) => {
     try {
+      const communityId = options.community || options.name;
+      if (!communityId) {
+        console.error(chalk.red('\n  Error: Community ID is required. Use -c or -n to specify.\n'));
+        process.exit(1);
+      }
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
-      const response = await apiClient.invoke('get_community', { community_id: options.community }, { allowGuest: false });
+
+      const response = await apiClient.invoke('get_community', { community_id: communityId }, { allowGuest: false });
       const result = response.message || response;
       const community = result.community;
-      
-      console.log(chalk.green('\n✅ Community Information:\n'));
+
+      console.log(chalk.green('\n  Community Information:\n'));
       console.log(chalk.cyan(`  Name: ${community.community_name}`));
       console.log(chalk.gray(`  ID: ${community.community_id}`));
       console.log(chalk.gray(`  Token: ${community.token_symbol}`));
@@ -502,90 +565,329 @@ communityCommand
 
 communityCommand
   .command('create')
-  .description('Community creation is via PWA (Workspace Config). Admins: use descix-admin community create')
-  .action(async () => {
-    console.log(chalk.cyan('\n📦 Community creation\n'));
-    console.log(chalk.white('Create communities in the PWA (Workspace Config / Device Setup).'));
-    console.log(chalk.white('Platform admins can use: descix-admin community create -n "Name" -t SYMBOL\n'));
-    console.log(chalk.gray('  descix-admin uses the same workspace root and .descix/wallet.json as this CLI.\n'));
-  });
-
-// Deploy a token contract without creating community
-communityCommand
-  .command('deploy-token')
-  .description('Deploy a new token contract (without creating a community)')
-  .requiredOption('-t, --token <symbol>', 'Token symbol (e.g., POWCH)')
-  .requiredOption('-n, --name <name>', 'Token name (e.g., "Powch Token")')
-  .option('--treasury <address>', 'Treasury wallet address (defaults to platform wallet)')
-  .option('-c, --community <id>', 'Community ID to link the token to (optional)')
+  .description('[ADMIN] Create a new community with token contract (requires platform admin, deploys to live Polygon)')
+  .requiredOption('-n, --name <name>', 'Community display name (e.g. "SMILE")')
+  .requiredOption('-t, --token <symbol>', 'Token symbol (e.g. SMILE)')
+  .option('--icon <url>', 'Icon URL for the community')
+  .option('--yes', 'Skip confirmation prompt (use with caution)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
+
+      const communityId = options.token.toLowerCase();
       const tokenSymbol = options.token.toUpperCase();
-      const tokenName = options.name;
-      
-      console.log(chalk.cyan('\n📦 Deploying token contract...\n'));
-      console.log(chalk.gray(`  Token Symbol: ${tokenSymbol}`));
-      console.log(chalk.gray(`  Token Name: ${tokenName}`));
-      if (options.treasury) {
-        console.log(chalk.gray(`  Treasury: ${options.treasury}`));
-      }
-      if (options.community) {
-        console.log(chalk.gray(`  Community: ${options.community}`));
+
+      console.log(chalk.cyan('\n📦 Community Creation [ADMIN ONLY]\n'));
+      console.log(chalk.yellow('  ⚠  WARNING: This operation is IRREVERSIBLE.'));
+      console.log(chalk.yellow('  ⚠  DEV/DEMO environments use the LIVE Polygon blockchain.'));
+      console.log(chalk.yellow('  ⚠  A real token contract will be deployed on-chain.\n'));
+      console.log(chalk.white(`  Community ID:    ${communityId}`));
+      console.log(chalk.white(`  Community Name:  ${options.name}`));
+      console.log(chalk.white(`  Token Symbol:    ${tokenSymbol}`));
+      console.log(chalk.white(`  Network:         Polygon (live)\n`));
+
+      if (!options.yes) {
+        const readline = await import('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise(resolve => {
+          rl.question(chalk.yellow(`  Create community "${options.name}" with token ${tokenSymbol} on live Polygon? [y/N] `), resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== 'y') {
+          console.log(chalk.gray('\n  Aborted.\n'));
+          return;
+        }
       }
-      console.log();
-      
-      console.log(chalk.yellow('⏳ This may take a few minutes while transactions confirm on-chain...\n'));
-      
-      const response = await apiClient.invoke('deploy_contract', {
-        template_type: 'DAITA_v2',
+
+      console.log(chalk.gray('\n  Creating community skeleton...'));
+
+      const response = await apiClient.invoke('create_community_skeleton', {
+        community_id: communityId,
+        community_name: options.name,
         token_symbol: tokenSymbol,
-        token_name: tokenName,
-        treasury_wallet: options.treasury || null,
-        community_id: options.community || null
+        icon_url: options.icon || null,
       });
-      
-      // Handle response wrapping
+
       const result = response.message || response;
-      
-      if (result.status !== 'OK') {
-        throw new Error(result.message || 'Deployment failed');
-      }
-      
-      const deployment = result.deployment;
-      
-      console.log(chalk.green('✅ Token contract deployed successfully!\n'));
-      console.log(chalk.white('Contract Details:'));
-      console.log(chalk.gray(`  Proxy Address:    ${deployment.proxy_address}`));
-      console.log(chalk.gray(`  Implementation:   ${deployment.implementation_address}`));
-      console.log(chalk.gray(`  Token Symbol:     ${deployment.token_symbol}`));
-      console.log(chalk.gray(`  Token Name:       ${deployment.token_name}`));
-      console.log(chalk.gray(`  Network:          ${deployment.network} (chainId: ${deployment.chain_id})`));
-      console.log(chalk.gray(`  TX Hash:          ${deployment.tx_hash}`));
-      console.log();
-      
-      if (deployment.network === 'polygon') {
-        console.log(chalk.cyan(`View on Polygonscan: https://polygonscan.com/address/${deployment.proxy_address}`));
-      } else if (deployment.network === 'amoy') {
-        console.log(chalk.cyan(`View on Amoy: https://amoy.polygonscan.com/address/${deployment.proxy_address}`));
-      }
-      
-      if (!options.community) {
-        console.log(chalk.yellow('\nNext steps:'));
-        console.log(chalk.gray(`  1. Create community:    descix community create -n "Name" -t ${tokenSymbol} -p ./path --no-token-contract`));
-        console.log(chalk.gray(`  2. Link token:          descix community link-token -c <community-id> -a ${deployment.proxy_address}`));
+
+      console.log(chalk.green(`\n  ✓ Community "${options.name}" created\n`));
+      console.log(chalk.white(`  Community ID:     ${result.community_id}`));
+      console.log(chalk.white(`  Default App:      ${result.app_id}`));
+      console.log(chalk.white(`  Token Symbol:     ${result.token_symbol}`));
+      if (result.contract_address) {
+        console.log(chalk.white(`  Contract:         ${result.contract_address}`));
       }
-      console.log();
-      
+
+      console.log(chalk.cyan('\n  Next steps:'));
+      console.log(chalk.gray(`    descix app init -a ${result.app_id}          # Initialize KB`));
+      console.log(chalk.gray(`    descix kb corpus sync -a ${result.app_id}    # Sync content`));
+      console.log(chalk.gray(`    descix site upload -c ${communityId} -a ${result.app_id} -p ./site  # Deploy site\n`));
+
     } catch (error) {
-      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      console.error(chalk.red(`\n  Error: ${error.message}\n`));
       process.exit(1);
     }
   });
 
-// Link existing token contract to community
+communityCommand
+  .command('delete')
+  .description('[ADMIN] Delete a community with full cascade cleanup (all apps, KBs, vectors, GCS)')
+  .requiredOption('-n, --name <community_id>', 'Community ID to delete')
+  .option('--dry-run', 'Preview what would be deleted without executing')
+  .option('--soft', 'Soft delete only (mark as hidden, no cascade)')
+  .option('--yes', 'Skip confirmation prompt')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+
+      const communityId = options.name;
+      const hardDelete = !options.soft;
+      const dryRun = !!options.dryRun;
+
+      if (dryRun) {
+        console.log(chalk.cyan(`\n--- DRY RUN: delete community ${communityId} ---\n`));
+      }
+
+      // Always call with dry_run first to get the manifest for display
+      const previewResponse = await apiClient.invoke('delete_community', {
+        community_id: communityId,
+        hard_delete: hardDelete,
+        dry_run: true
+      });
+
+      const preview = previewResponse.message || previewResponse;
+      const manifest = preview.community_manifest;
+
+      if (!manifest) {
+        console.error(chalk.red('\n  Error: Could not retrieve community information.\n'));
+        process.exit(1);
+      }
+
+      // Display manifest
+      console.log(chalk.bold('Community deletion manifest:\n'));
+      console.log(chalk.gray(`  Community:       ${manifest.community_name} (${manifest.community_id})`));
+      console.log(chalk.gray(`  Token:           ${manifest.token_symbol}`));
+      console.log(chalk.gray(`  Apps:            ${manifest.app_count}`));
+      if (manifest.apps && manifest.apps.length > 0) {
+        for (const appM of manifest.apps) {
+          if (appM.error) {
+            console.log(chalk.red(`    - ${appM.app_id} (error: ${appM.error})`));
+          } else {
+            const kbCount = appM.pinecone_kb_count || 0;
+            console.log(chalk.gray(`    - ${appM.app_id}: ${kbCount} KB(s), GCS: ${appM.gcs_prefix || 'N/A'}, Products: ${appM.products_doc ? 'yes' : 'no'}`));
+          }
+        }
+      }
+      console.log(chalk.gray(`  Mode:            ${hardDelete ? 'HARD DELETE (permanent)' : 'soft delete (hide only)'}`));
+
+      if (dryRun) {
+        console.log(chalk.yellow('\n  No changes were made. Remove --dry-run to execute.\n'));
+        return;
+      }
+
+      // Confirmation prompt (unless --yes)
+      if (!options.yes && hardDelete) {
+        const readline = await import('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise(resolve => {
+          rl.question(chalk.yellow(`\n  Permanently delete community "${manifest.community_name}" and all ${manifest.app_count} app(s)? This cannot be undone. [y/N] `), resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== 'y') {
+          console.log(chalk.gray('\n  Aborted.\n'));
+          return;
+        }
+      }
+
+      // Execute the actual delete
+      const response = await apiClient.invoke('delete_community', {
+        community_id: communityId,
+        hard_delete: hardDelete,
+        dry_run: false
+      });
+
+      const result = response.message || response;
+
+      if (result.cleanup) {
+        const c = result.cleanup;
+        console.log(chalk.green(`\n  Community ${communityId} deleted.\n`));
+        console.log(chalk.gray(`  Apps deleted:          ${c.apps_deleted?.length || 0} (${c.apps_deleted?.join(', ') || 'none'})`));
+        if (c.apps_failed?.length > 0) {
+          console.log(chalk.red(`  Apps failed:           ${c.apps_failed.length}`));
+          for (const f of c.apps_failed) {
+            console.log(chalk.red(`    - ${f.app_id}: ${f.error}`));
+          }
+        }
+        console.log(chalk.gray(`  Pinecone vectors:      ${c.total_pinecone_deleted}`));
+        console.log(chalk.gray(`  GCS files:             ${c.total_gcs_deleted}`));
+        console.log(chalk.gray(`  Firestore docs:        ${c.total_firestore_deleted}`));
+        console.log(chalk.gray(`  Products entries:      ${c.total_products_deleted}`));
+        console.log(chalk.gray(`  ServiceManifests:      ${c.total_service_manifests_deleted}`));
+        console.log();
+      } else {
+        console.log(chalk.green(`\n  ${result.message || `Community ${communityId} deleted.`}\n`));
+      }
+    } catch (error) {
+      console.error(chalk.red(`\n  Error: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+communityCommand
+  .command('rename')
+  .description('[ADMIN] Rename a community_id across all surfaces (Firestore, Products, Pinecone metadata, ServiceManifests, descix-chain registry). On-chain contract + token symbol are UNTOUCHED. Dry-run first.')
+  .argument('<old_community_id>', 'Current community_id (e.g. unkamon)')
+  .argument('<new_community_id>', 'New canonical community_id (e.g. unk)')
+  .option('--dry-run', 'Preview the full cascade plan without executing')
+  .option('--yes', 'Skip confirmation prompt')
+  .action(async (oldId, newId, options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+      const dryRun = !!options.dryRun;
+
+      // Always fetch the plan first (dry_run:true) for display.
+      const previewResp = await apiClient.invoke('rename_community', {
+        old_community_id: oldId, new_community_id: newId, dry_run: true
+      });
+      const preview = previewResp.message || previewResp;
+      const plan = preview.plan;
+      if (!plan) {
+        console.error(chalk.red('\n  Error: could not retrieve rename plan.\n'));
+        process.exit(1);
+      }
+
+      console.log(chalk.bold(`\nCommunity rename plan: ${oldId} -> ${newId}\n`));
+      console.log(chalk.gray(`  Community doc:         old_exists=${plan.community_doc.old_exists}, new_exists=${plan.community_doc.new_exists}`));
+      console.log(chalk.gray(`  Name / token:          ${plan.community_doc.community_name} / ${plan.community_doc.token_symbol}`));
+      console.log(chalk.gray(`  Apps subcollection:    ${plan.community_doc.apps_subcollection.join(', ') || '(none)'}`));
+      console.log(chalk.gray(`  Roles subcollection:   ${plan.community_doc.roles_subcollection.join(', ') || '(none)'}`));
+      console.log(chalk.gray(`  Community tree docs:   ${plan.community_doc.total_docs_in_tree}`));
+      console.log(chalk.gray(`  Products to update:    ${plan.products.count} (${plan.products.app_ids.join(', ')})`));
+      console.log(chalk.gray(`  User purchases:        ${plan.user_purchases_to_repoint}`));
+      console.log(chalk.gray(`  ServiceManifests:      ${plan.service_manifests_to_retag.join(', ') || '(none)'}`));
+      console.log(chalk.gray(`  Chain product/contract: ${plan.chain.product_doc_old || '(none)'} / ${plan.chain.contract_address || '(none)'} (symbol ${plan.chain.token_symbol}, communityId ${plan.chain.contract_community_id})`));
+      console.log(chalk.cyan(`  Pinecone re-tag:       scanned=${plan.pinecone.scanned}, matched(community=${oldId})=${plan.pinecone.matched}, legacy-id-prefixed=${plan.pinecone.legacyIdMatched}`));
+      console.log(chalk.gray(`    by app: ${JSON.stringify(plan.pinecone.byApp)}`));
+      console.log(chalk.gray(`    prefix counts: ${JSON.stringify(plan.pinecone.prefixCounts)}`));
+
+      if (dryRun) {
+        console.log(chalk.yellow('\n  DRY RUN — no changes made. Remove --dry-run to execute.\n'));
+        return;
+      }
+
+      if (!options.yes) {
+        const readline = await import('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise(resolve => rl.question(
+          chalk.yellow(`\n  Execute rename ${oldId} -> ${newId}? Re-tags ${plan.pinecone.matched} vector(s) and deletes Community/${oldId} after verifying Community/${newId}. [y/N] `),
+          resolve
+        ));
+        rl.close();
+        if (answer.toLowerCase() !== 'y') {
+          console.log(chalk.gray('\n  Aborted.\n'));
+          return;
+        }
+      }
+
+      const resp = await apiClient.invoke('rename_community', {
+        old_community_id: oldId, new_community_id: newId, dry_run: false
+      });
+      const result = resp.message || resp;
+      const ex = result.executed || {};
+      console.log(chalk.green(`\n  ${result.message}\n`));
+      console.log(chalk.gray(`  Community doc copied:  ${ex.community_doc_copied}`));
+      console.log(chalk.gray(`  Old community deleted: ${ex.old_community_deleted}`));
+      console.log(chalk.gray(`  Products updated:      ${ex.products_updated}`));
+      console.log(chalk.gray(`  User purchases:        ${ex.user_purchases_repointed}`));
+      console.log(chalk.gray(`  Pinecone re-tagged:    ${ex.pinecone?.updated} / matched ${ex.pinecone?.matched}`));
+      console.log(chalk.gray(`  ServiceManifests:      ${ex.service_manifests_retagged}`));
+      console.log(chalk.gray(`  Chain re-pointed:      ${ex.chain_repointed} (contract ${ex.chain_contract_address}, symbol unchanged)`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`\n  Error: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// Deploy a token contract without creating community
+communityCommand
+  .command('deploy-token')
+  .description('Deploy a new token contract (without creating a community)')
+  .requiredOption('-t, --token <symbol>', 'Token symbol (e.g., POWCH)')
+  .requiredOption('-n, --name <name>', 'Token name (e.g., "Powch Token")')
+  .option('--treasury <address>', 'Treasury wallet address (defaults to platform wallet)')
+  .option('-c, --community <id>', 'Community ID to link the token to (optional)')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+      
+      const tokenSymbol = options.token.toUpperCase();
+      const tokenName = options.name;
+      
+      console.log(chalk.cyan('\n📦 Deploying token contract...\n'));
+      console.log(chalk.gray(`  Token Symbol: ${tokenSymbol}`));
+      console.log(chalk.gray(`  Token Name: ${tokenName}`));
+      if (options.treasury) {
+        console.log(chalk.gray(`  Treasury: ${options.treasury}`));
+      }
+      if (options.community) {
+        console.log(chalk.gray(`  Community: ${options.community}`));
+      }
+      console.log();
+      
+      console.log(chalk.yellow('⏳ This may take a few minutes while transactions confirm on-chain...\n'));
+      
+      const response = await apiClient.invoke('deploy_contract', {
+        template_type: 'DAITA_v2',
+        token_symbol: tokenSymbol,
+        token_name: tokenName,
+        treasury_wallet: options.treasury || null,
+        community_id: options.community || null
+      });
+      
+      // Handle response wrapping
+      const result = response.message || response;
+      
+      if (result.status !== 'OK') {
+        throw new Error(result.message || 'Deployment failed');
+      }
+      
+      const deployment = result.deployment;
+      
+      console.log(chalk.green('✅ Token contract deployed successfully!\n'));
+      console.log(chalk.white('Contract Details:'));
+      console.log(chalk.gray(`  Proxy Address:    ${deployment.proxy_address}`));
+      console.log(chalk.gray(`  Implementation:   ${deployment.implementation_address}`));
+      console.log(chalk.gray(`  Token Symbol:     ${deployment.token_symbol}`));
+      console.log(chalk.gray(`  Token Name:       ${deployment.token_name}`));
+      console.log(chalk.gray(`  Network:          ${deployment.network} (chainId: ${deployment.chain_id})`));
+      console.log(chalk.gray(`  TX Hash:          ${deployment.tx_hash}`));
+      console.log();
+      
+      if (deployment.network === 'polygon') {
+        console.log(chalk.cyan(`View on Polygonscan: https://polygonscan.com/address/${deployment.proxy_address}`));
+      } else if (deployment.network === 'amoy') {
+        console.log(chalk.cyan(`View on Amoy: https://amoy.polygonscan.com/address/${deployment.proxy_address}`));
+      }
+      
+      if (!options.community) {
+        console.log(chalk.yellow('\nNext steps:'));
+        console.log(chalk.gray(`  1. Create community:    descix community create -n "Name" -t ${tokenSymbol}`));
+        console.log(chalk.gray(`  2. Link token:          descix community link-token -c <community-id> -a ${deployment.proxy_address}`));
+      }
+      console.log();
+      
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Link existing token contract to community
 communityCommand
   .command('link-token')
   .description('Link an existing token contract to a community')
@@ -743,39 +1045,64 @@ appCommand
 
 appCommand
   .command('init')
-  .description('Initialize local workspace and Firestore KB for an app (idempotent)')
-  .requiredOption('-a, --app <app_id>', 'App ID (e.g. daita)')
+  // ONE PATH TO AN APP (CEO-D-2026-08-14): `app init` is THE app entry point — it creates the
+  // app when it does not exist yet and then registers/scaffolds it locally. The separate
+  // `app create` command is DELETED (no compat fence): two commands for one outcome is how apps
+  // ended up half-made — created on the platform, never initialized — which is precisely the
+  // state the DEV audit found (powch, sml, daita-ssgpod carrying zero knowledge bases).
+  // Creation still routes through the single canonical server command create_app_for_community,
+  // which composes the app_id and fails loud on a missing community / duplicate id / bad short
+  // name. The server also guarantees the default KB, so no app can exist without one.
+  .description('Create (if needed) and initialize an app: platform record + default KB + local workspace registration and scaffold. Idempotent. Pass -c to create a new app; omit it to initialize one that already exists.')
+  .requiredOption('-a, --app <app_id>', 'App ID (e.g. daita). With -c this is the app NAME to create.')
+  .option('-c, --community <id>', 'Community ID — REQUIRED to create an app that does not exist yet. The community must already be materialized in this environment.')
+  .option('-s, --short <short_name>', 'SHORT id segment (no hyphens) used when creating; the app_id is composed server-side as {community}-{short}. Defaults to --app.')
+  .option('--overwrite', 'When creating, overwrite an existing app record intentionally')
   .option('--kb <name>', 'Knowledge base name', 'General')
   .option('-p, --path <dir>', 'Local app directory (default: auto-detected or cwd)')
-  .option('-c, --community <community_id>', 'Community to create app in (if not yet in Products registry)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      const appId = options.app;
+      let appId = options.app;
       const kbId = options.kb || 'General';
 
-      // Resolve community_id from Products registry
+      // Resolve community_id from the Products registry to learn whether the app exists yet.
       let communityId;
       try {
         const productCtx = await apiClient.invoke('get_product_context', { app_id: appId });
         communityId = (productCtx.message || productCtx).community_id;
       } catch (e) {
-        // Product not found — fall through to creation below
+        // Not in Products — either we create it below (-c given) or we fail loud.
       }
-      // Product missing or returned null community_id — create if --community was provided
+
       if (!communityId) {
-        if (options.community) {
-          console.log(chalk.gray(`  App '${appId}' not in Products registry. Creating in community '${options.community}'...`));
-          await apiClient.invoke('create_app_for_community', {
-            community_id: options.community,
-            app_name: appId,
-          });
-          communityId = options.community;
-          console.log(chalk.green(`  ✓ Created App + Products + Purchase for ${appId}`));
-        } else {
-          throw new Error(`App '${appId}' not found in Products registry. Use --community to create it.`);
+        if (!options.community) {
+          throw new Error(
+            `App '${appId}' does not exist yet. Pass -c <community> to create it: ` +
+            `descix app init -a ${appId} -c <community> [-s <short>]`
+          );
         }
+        // CREATE leg — the canonical server path. It composes the unique app_id
+        // ({community}-{short}) and is authoritative; we never compose it client-side.
+        const response = await apiClient.invoke('create_app_for_community', {
+          community_id: options.community,
+          app_name: appId,
+          short_name: options.short || undefined,
+          create_skeleton: false,
+          overwrite: options.overwrite,
+        });
+        const created = response.message || response;
+        appId = created.app_id || appId;
+        communityId = created.community_id || options.community;
+        console.log(chalk.green(`\n✅ App created: ${appId}`));
+        console.log(chalk.gray(`  Products:   Products/${appId}`));
+        console.log(chalk.gray(`  Firestore:  Community/${communityId}/Apps/${appId}`));
+      } else if (options.community && options.community !== communityId) {
+        throw new Error(
+          `App '${appId}' already exists in community '${communityId}', not '${options.community}'. ` +
+          `Omit -c to initialize the existing app.`
+        );
       }
 
       // 1. Workspace.json — register app if not already mapped
@@ -783,6 +1110,13 @@ appCommand
       const alreadyMapped = workspaceConfig?.getAppByAppId(appId);
       let appPath = alreadyMapped?.absolutePath;
 
+      if (alreadyMapped && options.path) {
+        throw new Error(
+          `App '${appId}' is already mapped to '${alreadyMapped.localPath}'. ` +
+          `Use 'descix app set-localpath -a ${appId} -p <new-path>' to update.`
+        );
+      }
+
       if (!alreadyMapped) {
         const localPath = options.path || '.';
         const wsRoot = workspaceConfig?.workspaceRoot || process.cwd();
@@ -793,15 +1127,29 @@ appCommand
         console.log(chalk.gray(`  workspace.json updated: ${appId} → ${localPath}`));
       }
 
-      // 2. Create rigid app folder structure (site, kb, microservice)
+      // 2. Create app folder structure (site, microservice, assets)
       if (appPath) {
         const siteDir = path.join(appPath, 'site');
-        const kbDir = path.join(appPath, 'kb', kbId);
         const msDir = path.join(appPath, 'microservice');
+        const assetsDir = path.join(appPath, 'assets');
         await fs.mkdir(siteDir, { recursive: true });
-        await fs.mkdir(kbDir, { recursive: true });
         await fs.mkdir(msDir, { recursive: true });
-        console.log(chalk.gray(`  Created: site/, kb/${kbId}/, microservice/`));
+        await fs.mkdir(assetsDir, { recursive: true });
+
+        // Create template asset files if they don't exist
+        const siPath = path.join(assetsDir, 'system_instructions.md');
+        const descPath = path.join(assetsDir, 'app_description.md');
+        try {
+          await fs.access(siPath);
+        } catch {
+          await fs.writeFile(siPath, `# System Instructions for ${appId}\n\nYou are an AI assistant for the ${appId} application.\n`);
+        }
+        try {
+          await fs.access(descPath);
+        } catch {
+          await fs.writeFile(descPath, `# ${appId}\n\nApplication description goes here.\n`);
+        }
+        console.log(chalk.gray(`  Created: site/, microservice/, assets/`));
       }
 
       // 3. Create KnowledgeBase Firestore doc (Git Mode — no Drive required)
@@ -811,9 +1159,12 @@ appCommand
       console.log(chalk.green(`\n✓ ${appId} initialized`));
       console.log(chalk.gray(`  Community: ${communityId}`));
       console.log(chalk.gray(`  KB: ${kbId} — ${kbResult.created ? 'created' : 'already exists'}\n`));
+      console.log(chalk.gray(`  (every app is guaranteed a default KB at creation; an empty one`));
+      console.log(chalk.gray(`   says so rather than answering from general knowledge)\n`));
       console.log(chalk.cyan('Next steps:'));
-      console.log(chalk.gray(`  Add markdown files to kb/${kbId}/ then run:`));
-      console.log(chalk.white(`  descix update kb -a ${appId}\n`));
+      console.log(chalk.gray(`  Create a corpus manifest at apps/${appId}/.descix/manifests/${kbId}.json`));
+      console.log(chalk.gray(`  then run:`));
+      console.log(chalk.white(`  descix kb corpus sync -a ${appId}\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -821,111 +1172,153 @@ appCommand
   });
 
 appCommand
-  .command('register-folder')
-  .description('Register your base Drive folder (must be shared with dip@descix.net)')
-  .option('-u, --url <folderUrl>', 'Drive folder URL or ID')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      if (!options.url) {
-        console.error(chalk.red('Error: Folder URL or ID required. Use -u or --url'));
-        process.exit(1);
-      }
-      
-      const response = await apiClient.invoke('register_base_folder', {
-        folder_url: options.url
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ Folder registered successfully!\n'));
-      console.log(chalk.cyan(`  Folder ID: ${result.folder_id}`));
-      console.log(chalk.gray(`  Folder Name: ${result.folder_name}\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
+  .command('create')
+  // DELETED SURFACE (CEO-D-2026-08-14, SUPER-DRY: delete the old path, fail loud, no compat
+  // fence). `app create` created the platform record and STOPPED, leaving the caller to
+  // remember `app init` — two commands for one outcome. That is how apps ended up half-made
+  // with no knowledge base at all. `app init` now creates AND initializes in one path.
+  .description('[REMOVED] Use `descix app init -a <name> -c <community>` — it creates and initializes in one step.')
+  // Swallow whatever the old invocation passed so the caller always gets the pointer below
+  // rather than a generic commander arity error that names no replacement.
+  .allowUnknownOption(true)
+  .argument('[ignored...]')
+  .action(() => {
+    console.error(chalk.red('\n❌ `descix app create` has been removed.\n'));
+    console.error(chalk.white('   Use the single canonical path, which creates AND initializes:\n'));
+    console.error(chalk.cyan('     descix app init -a <app-name> -c <community> [-s <short>]\n'));
+    console.error(chalk.gray('   It registers the app (Products + Firestore + entitlement), guarantees'));
+    console.error(chalk.gray('   the default knowledge base, then registers and scaffolds it locally.'));
+    console.error(chalk.gray('   Creating an app without a default KB is no longer possible.\n'));
+    process.exit(1);
   });
 
+// descix app media-upload — upload media/asset files to an app's GCS assets prefix via the
+// API surface (WS-V1-PURGE Phase 1, item 2; media-via-API-surface PLATFORM half).
+// This is the canonical, filesystem-free way to get app media (podcast audio, cover art,
+// etc.) into the platform: request a short-lived signed PUT token from the API surface
+// (`get_asset_upload_token` over /apifront, user-session authed), upload each file straight
+// to GCS, and print the ASSET REFERENCES. An app microservice then fetches an uploaded asset
+// by reference over the Core broker via `get_app_asset` (no shared local filesystem needed).
 appCommand
-  .command('create')
-  .description('Create an app in a community. --quick with -c/-a for CLI-driven creation.')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <name>', 'App name')
-  .option('--quick', 'Create app via CLI (registers in Products, creates Drive skeleton); requires -c and -a')
-  .option('--overwrite', 'Overwrite existing (with --quick)')
+  .command('media-upload')
+  .description('Upload media/asset files to an app\'s GCS assets prefix via the API surface (returns asset references)')
+  .requiredOption('-a, --app <id>', 'App ID (community is resolved server-side from Products)')
+  .requiredOption('-f, --file <path...>', 'One or more local file paths to upload')
+  .option('--prefix <relPath>', 'Optional sub-path under the app assets/ prefix (e.g. "shows/myshow")', '')
+  .option('--json', 'Print the asset references as JSON (for scripting)')
   .action(async (options) => {
     try {
-      if (options.quick && options.community && options.app) {
-        const apiClient = new DeSciXApiClient();
-        await requireAuth(apiClient);
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
 
-        // Ensure Drive base folder is registered in workspace.json
-        let wsConfig;
+      const path = await import('path');
+      const mime = (await import('mime-types')).default;
+
+      const appId = options.app;
+      const localFiles = Array.isArray(options.file) ? options.file : [options.file];
+      const subPrefix = (options.prefix || '').replace(/^\/+|\/+$/g, '');
+
+      // Build the upload descriptor list: object path under assets/ = [subPrefix/]basename.
+      const fileDescriptors = [];
+      for (const localPath of localFiles) {
+        const abs = path.resolve(localPath);
+        let stat;
         try {
-          wsConfig = await WorkspaceConfig.load(process.cwd());
+          stat = await fs.stat(abs);
         } catch {
-          console.error(chalk.red('\n❌ No workspace found. Run `descix init` first.\n'));
+          console.error(chalk.red(`\n❌ File not found: ${abs}\n`));
           process.exit(1);
         }
-        const baseFolderId = wsConfig.driveConfig?.base_folder_id;
-
-        if (!baseFolderId) {
-          console.log(chalk.yellow('\n⚠  No Drive base folder registered in workspace.json.'));
-          console.log(chalk.white('  App creation requires a shared Drive folder for KB and asset storage.'));
-          console.log(chalk.white('  Share a Google Drive folder with dip@descix.net, then provide its URL.\n'));
-
-          const readline = await import('readline');
-          const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-          const folderUrl = await new Promise((resolve) => {
-            rl.question(chalk.cyan('  Drive folder URL or ID: '), (answer) => {
-              rl.close();
-              resolve(answer.trim());
-            });
-          });
+        if (!stat.isFile()) {
+          console.error(chalk.red(`\n❌ Not a file: ${abs}\n`));
+          process.exit(1);
+        }
+        const base = path.basename(abs);
+        const objectPath = subPrefix ? `${subPrefix}/${base}` : base;
+        fileDescriptors.push({
+          path: objectPath,
+          content_type: mime.lookup(abs) || 'application/octet-stream',
+          size: stat.size,
+          _absolutePath: abs
+        });
+      }
 
-          if (!folderUrl) {
-            console.error(chalk.red('\n❌ Drive folder is required for app creation.\n'));
-            process.exit(1);
-          }
+      console.log(chalk.cyan(`\n  Media Upload: ${appId} → GCS assets/\n`));
+      fileDescriptors.forEach(f => progress(options, chalk.gray(`  • ${f.path} (${(f.size / 1024).toFixed(1)}KB, ${f.content_type})`)));
 
-          // Register the folder via backend (validates sharing + extracts folder ID)
-          const regResponse = await apiClient.invoke('register_base_folder', {
-            folder_url: folderUrl
+      // 1. Request a signed-PUT upload token over the API surface.
+      const tokenResponse = await apiClient.invoke('get_asset_upload_token', {
+        app_id: appId,
+        files: fileDescriptors.map(f => ({ path: f.path, content_type: f.content_type, size: f.size }))
+      });
+      const token = tokenResponse.message || tokenResponse;
+      const { signed_urls, objects } = token;
+
+      // 2. PUT each file directly to GCS using its signed URL.
+      progress(options, chalk.gray(`\n  Uploading ${fileDescriptors.length} file(s)...`));
+      const uploaded = [];
+      const errors = [];
+      for (const f of fileDescriptors) {
+        const signedUrl = signed_urls?.[f.path];
+        if (!signedUrl) {
+          errors.push(`No signed URL for: ${f.path}`);
+          progress(options, chalk.red(`  x ${f.path}`));
+          continue;
+        }
+        try {
+          const content = await fs.readFile(f._absolutePath);
+          const resp = await fetch(signedUrl, {
+            method: 'PUT',
+            headers: { 'Content-Type': f.content_type },
+            body: content
           });
-          const regResult = regResponse.message || regResponse;
-          console.log(chalk.green(`  ✓ Folder registered: ${regResult.folder_name} (${regResult.folder_id})`));
-
-          // Persist to workspace.json
-          wsConfig.driveConfig = { base_folder_id: regResult.folder_id };
-          await wsConfig.save();
-          console.log(chalk.green('  ✓ Saved to workspace.json\n'));
+          if (!resp.ok) {
+            errors.push(`Failed ${f.path}: ${resp.status} ${resp.statusText}`);
+            progress(options, chalk.red(`  x ${f.path}`));
+          } else {
+            const obj = (objects || []).find(o => o.path === f.path) || {};
+            // The asset REFERENCE an app handler / get_app_asset consumes: the gs:// URI.
+            const gcsRef = obj.gcs_path
+              ? `gs://${token.bucket}/${obj.gcs_path}`
+              : null;
+            uploaded.push({
+              path: f.path,
+              ref: gcsRef,
+              gcs_path: obj.gcs_path || null,
+              public_url: obj.public_url || null,
+              content_type: f.content_type,
+              size: f.size
+            });
+            progress(options, chalk.green(`  + ${f.path}`));
+          }
+        } catch (err) {
+          errors.push(`Error ${f.path}: ${err.message}`);
+          progress(options, chalk.red(`  x ${f.path}`));
         }
+      }
 
-        const response = await apiClient.invoke('create_app_for_community', {
-          community_id: options.community,
-          app_name: options.app,
-          create_skeleton: true,
-          overwrite: options.overwrite
+      if (errors.length > 0) {
+        progress(options, chalk.yellow(`\n  ${errors.length} error(s):`));
+        errors.forEach(e => progress(options, chalk.red(`  - ${e}`)));
+      }
+
+      if (uploaded.length === 0) {
+        console.error(chalk.red('\n❌ No files uploaded.\n'));
+        process.exit(1);
+      }
+
+      if (options.json) {
+        console.log('\n' + JSON.stringify({ app_id: appId, assets: uploaded }, null, 2) + '\n');
+      } else {
+        console.log(chalk.green(`\n  ✅ Uploaded ${uploaded.length} asset(s).\n`));
+        console.log(chalk.cyan('  Asset references (pass these to your app handler; the service fetches via get_app_asset):'));
+        uploaded.forEach(u => {
+          console.log(chalk.white(`    ${u.path}`));
+          console.log(chalk.gray(`      ref:        ${u.ref}`));
+          console.log(chalk.gray(`      public_url: ${u.public_url}`));
         });
-        const result = response.message || response;
-        console.log(chalk.green('\n✅ App created successfully!\n'));
-        console.log(chalk.cyan(`  App ID:     ${result.app_id}`));
-        console.log(chalk.cyan(`  Community:  ${result.community_id}`));
-        console.log(chalk.gray(`  Products:   Products/${result.app_id}`));
-        console.log(chalk.gray(`  Firestore:  Community/${result.community_id}/Apps/${result.app_id}`));
-        if (result.skeleton_result) {
-          console.log(chalk.gray(`  Drive:      ${result.skeleton_result.folder_id || 'created'}`));
-        }
-        console.log(chalk.cyan('\n  Next: descix app init -a ' + result.app_id + '\n'));
-        return;
+        console.log();
       }
-      console.log(chalk.cyan('\n📦 App creation\n'));
-      console.log(chalk.white('Create apps in the PWA (Device Setup / App Manager) or via CLI:\n'));
-      console.log(chalk.white('  descix app create --quick -c <community> -a <app-name>\n'));
-      console.log(chalk.gray('This registers the app in the Products registry, creates Firestore'));
-      console.log(chalk.gray('documents, grants entitlement, and creates Drive skeleton.\n'));
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
@@ -933,353 +1326,27 @@ appCommand
   });
 
 appCommand
-  .command('upload')
-  .description('Upload local files to app knowledge base')
-  .requiredOption('-c, --community <id>', 'Community ID')
-  .requiredOption('-a, --app <id>', 'App ID')
-  .requiredOption('-p, --path <localPath>', 'Local folder path')
-  .option('-k, --kb <id>', 'Knowledge Base ID', 'General')
+  .command('set-codesite')
+  .description('Set CodeSite URL/path for an app (use "descix site servelocal" for local dev port)')
+  .option('-c, --community <id>', 'Community ID (uses context if not provided)')
+  .option('-a, --app <id>', 'App ID (uses context if not provided)')
+  .requiredOption('-u, --url <url>', 'CodeSite URL (GCS path or HTTPS URL)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
       
-      const fs = await import('fs/promises');
-      const path = await import('path');
-      
-      // Read files from local path
-      const localPath = options.path;
-      const stats = await fs.stat(localPath);
-      if (!stats.isDirectory()) {
-        throw new Error(`Path is not a directory: ${localPath}`);
-      }
-      
-      console.log(chalk.gray(`Reading files from ${localPath}...`));
-      
-      // Recursively read files
-      const files = [];
-      async function readDir(dirPath, basePath = '') {
-        const entries = await fs.readdir(dirPath, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dirPath, entry.name);
-          const relPath = path.join(basePath, entry.name);
-          
-          if (entry.isDirectory()) {
-            await readDir(fullPath, relPath);
-          } else if (entry.isFile()) {
-            const content = await fs.readFile(fullPath, 'utf-8');
-            files.push({
-              name: entry.name,
-              path: relPath,
-              content: Buffer.from(content).toString('base64')  // Base64 encode
-            });
-          }
-        }
-      }
+      // Load workspace context
+      const workspaceConfig = await WorkspaceConfig.load();
+      const ctx = workspaceConfig.resolveContextWithOptions(options);
       
-      await readDir(localPath);
+      const communityId = ctx.communityId;
+      const appId = ctx.appId;
       
-      if (files.length === 0) {
-        throw new Error('No files found in the specified directory');
-      }
-      
-      console.log(chalk.gray(`Found ${files.length} files. Uploading...`));
-      
-      const response = await apiClient.invoke('upload_files_to_kb', {
-        community_id: options.community,
-        app_id: options.app,
-        kb_id: options.kb,
-        files: files
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ Files uploaded successfully!\n'));
-      console.log(chalk.cyan(`  Uploaded: ${result.uploaded || 0} files`));
-      console.log(chalk.gray(`  Total Vectors: ${result.totalVectors || 0}\n`));
-      
-      if (result.errors && result.errors.length > 0) {
-        console.log(chalk.yellow('  Errors:'));
-        result.errors.forEach(err => {
-          console.log(chalk.red(`    - ${err.file}: ${err.error}`));
-        });
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-appCommand
-  .command('upload-tree')
-  .description('Upload folder tree with subfolders as KBs')
-  .requiredOption('-c, --community <id>', 'Community ID')
-  .requiredOption('-a, --app <id>', 'App ID')
-  .requiredOption('-p, --path <localPath>', 'Local folder path')
-  .option('--confirm', 'Confirm each subfolder as KB')
-  .option('--dry-run', 'Show what would be uploaded without uploading')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      const fs = await import('fs/promises');
-      const path = await import('path');
-      const readline = await import('readline');
-      
-      const localPath = options.path;
-      const stats = await fs.stat(localPath);
-      if (!stats.isDirectory()) {
-        throw new Error(`Path is not a directory: ${localPath}`);
-      }
-      
-      console.log(chalk.gray(`Scanning ${localPath}...\n`));
-      
-      // Find top-level subdirectories
-      const entries = await fs.readdir(localPath, { withFileTypes: true });
-      const subdirs = entries.filter(e => e.isDirectory() && !e.name.startsWith('.'));
-      const rootFiles = entries.filter(e => e.isFile() && !e.name.startsWith('.'));
-      
-      if (subdirs.length === 0) {
-        throw new Error('No subdirectories found. Use "app upload" for single KB upload.');
-      }
-      
-      console.log(chalk.cyan(`Found ${subdirs.length} subdirectories:\n`));
-      
-      // Count files in each subdirectory
-      const subdirInfo = [];
-      for (const dir of subdirs) {
-        const dirPath = path.join(localPath, dir.name);
-        const files = await readDirectoryFiles(dirPath);
-        subdirInfo.push({
-          name: dir.name,
-          path: dirPath,
-          fileCount: files.length
-        });
-        console.log(chalk.gray(`  [${subdirInfo.length}] ${dir.name}/ (${files.length} files)`));
-      }
-      
-      if (rootFiles.length > 0) {
-        console.log(chalk.yellow(`\n  Note: ${rootFiles.length} root-level files will go to "General" KB\n`));
-      }
-      
-      if (options.dryRun) {
-        console.log(chalk.cyan('\n✅ Dry run complete. Use without --dry-run to upload.\n'));
-        return;
-      }
-      
-      // Confirm each subdirectory if --confirm flag
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout
-      });
-      
-      const askYesNo = (question, defaultYes = true) => {
-        return new Promise((resolve) => {
-          const suffix = defaultYes ? '(Y/n)' : '(y/N)';
-          rl.question(`${question} ${suffix}: `, (answer) => {
-            const trimmed = answer.trim().toLowerCase();
-            resolve(trimmed === '' ? defaultYes : (trimmed === 'y' || trimmed === 'yes'));
-          });
-        });
-      };
-      
-      const kbsToUpload = [];
-      for (const info of subdirInfo) {
-        if (options.confirm) {
-          const proceed = await askYesNo(`Create KB "${info.name}" and upload ${info.fileCount} files?`, true);
-          if (!proceed) {
-            console.log(chalk.gray(`  Skipping ${info.name}\n`));
-            continue;
-          }
-        }
-        kbsToUpload.push(info);
-      }
-      
-      rl.close();
-      
-      if (kbsToUpload.length === 0) {
-        console.log(chalk.yellow('\n⚠️  No KBs selected for upload.\n'));
-        return;
-      }
-      
-      // Upload each subdirectory as a KB
-      for (const info of kbsToUpload) {
-        console.log(chalk.cyan(`\n📦 Uploading to KB "${info.name}"...`));
-        
-        // Create KB if it doesn't exist
-        try {
-          await apiClient.invoke('create_skeleton_kb', {
-            community_id: options.community,
-            app_id: options.app,
-            kb_name: info.name
-          });
-          console.log(chalk.gray(`  ✓ KB "${info.name}" created`));
-        } catch (err) {
-          // KB might already exist, continue
-          if (!err.message.includes('already exists')) {
-            console.log(chalk.yellow(`  ⚠️  Could not create KB: ${err.message}`));
-          }
-        }
-        
-        // Read files from subdirectory
-        const files = await readDirectoryFiles(info.path);
-        
-        if (files.length === 0) {
-          console.log(chalk.yellow(`  ⚠️  No files found in ${info.name}/`));
-          continue;
-        }
-        
-        // Upload in batches
-        const BATCH_SIZE = 10;
-        let uploaded = 0;
-        let errors = [];
-        
-        for (let i = 0; i < files.length; i += BATCH_SIZE) {
-          const batch = files.slice(i, i + BATCH_SIZE);
-          const batchNum = Math.floor(i / BATCH_SIZE) + 1;
-          const totalBatches = Math.ceil(files.length / BATCH_SIZE);
-          
-          try {
-            process.stdout.write(chalk.gray(`    Batch ${batchNum}/${totalBatches}...`));
-            const response = await apiClient.invoke('upload_files_to_kb', {
-              community_id: options.community,
-              app_id: options.app,
-              kb_id: info.name,
-              files: batch
-            });
-            const result = response.message || response;
-            uploaded += result.uploaded || batch.length;
-            if (result.errors) {
-              errors.push(...result.errors);
-            }
-            console.log(chalk.green(' ✓'));
-          } catch (err) {
-            console.log(chalk.red(` ✗ ${err.message}`));
-            errors.push({ batch: batchNum, error: err.message });
-          }
-        }
-        
-        console.log(chalk.green(`  ✅ Uploaded ${uploaded} files to KB "${info.name}"`));
-        if (errors.length > 0) {
-          console.log(chalk.yellow(`    ⚠️  ${errors.length} errors during upload`));
-        }
-      }
-      
-      // Handle root files if any
-      if (rootFiles.length > 0) {
-        console.log(chalk.cyan(`\n📦 Uploading ${rootFiles.length} root files to "General" KB...`));
-        const rootFilesData = [];
-        for (const file of rootFiles) {
-          const filePath = path.join(localPath, file.name);
-          const content = await fs.readFile(filePath);
-          rootFilesData.push({
-            name: file.name,
-            path: file.name,
-            content: content.toString('base64')
-          });
-        }
-        
-        try {
-          const response = await apiClient.invoke('upload_files_to_kb', {
-            community_id: options.community,
-            app_id: options.app,
-            kb_id: 'General',
-            files: rootFilesData
-          });
-          const result = response.message || response;
-          console.log(chalk.green(`  ✅ Uploaded ${result.uploaded || 0} root files`));
-        } catch (err) {
-          console.log(chalk.yellow(`  ⚠️  Could not upload root files: ${err.message}`));
-        }
-      }
-      
-      console.log(chalk.green('\n✅ Upload tree complete!\n'));
-      
-      // Helper function to read directory files
-      async function readDirectoryFiles(dirPath, basePath = '') {
-        const files = [];
-        const entries = await fs.readdir(dirPath, { withFileTypes: true });
-        
-        for (const entry of entries) {
-          const fullPath = path.join(dirPath, entry.name);
-          const relPath = path.join(basePath, entry.name);
-          
-          if (entry.isDirectory()) {
-            const subFiles = await readDirectoryFiles(fullPath, relPath);
-            files.push(...subFiles);
-          } else if (entry.isFile()) {
-            // Skip hidden files
-            if (entry.name.startsWith('.')) {
-              continue;
-            }
-            const content = await fs.readFile(fullPath);
-            files.push({
-              name: entry.name,
-              path: relPath,
-              content: content.toString('base64')
-            });
-          }
-        }
-        
-        return files;
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-appCommand
-  .command('sync')
-  .description('Sync knowledge base (vectorize files in Drive folder)')
-  .requiredOption('-c, --community <id>', 'Community ID')
-  .requiredOption('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID', 'General')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      const response = await apiClient.invoke('sync_knowledge_base', {
-        community_id: options.community,
-        app_id: options.app,
-        kb_id: options.kb
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ Sync initiated!\n'));
-      console.log(chalk.cyan(`  KB: ${options.community}/${options.app}/${options.kb}`));
-      if (result.note) {
-        console.log(chalk.gray(`  Note: ${result.note}\n`));
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-appCommand
-  .command('set-codesite')
-  .description('Set CodeSite URL/path for an app (use "descix site servelocal" for local dev port)')
-  .option('-c, --community <id>', 'Community ID (uses context if not provided)')
-  .option('-a, --app <id>', 'App ID (uses context if not provided)')
-  .requiredOption('-u, --url <url>', 'CodeSite URL (GCS path or HTTPS URL)')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      // Load workspace context
-      const workspaceConfig = await WorkspaceConfig.load();
-      const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
-      const appId = ctx.appId;
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
-        process.exit(1);
+      if (!communityId || !appId) {
+        console.error(chalk.red('\n❌ Community and App ID required.'));
+        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
+        process.exit(1);
       }
       
       const response = await apiClient.invoke('update_app_metadata', {
@@ -1331,33 +1398,26 @@ appCommand
   });
 
 appCommand
-  .command('set-api-url')
-  .description('Set API base URL for app\'s own backend')
+  .command('set-name')
+  .description('Set app display name')
   .requiredOption('-c, --community <id>', 'Community ID')
   .requiredOption('-a, --app <id>', 'App ID')
-  .requiredOption('-u, --url <url>', 'API base URL (e.g., https://api.example.com)')
+  .requiredOption('--name <name>', 'Display name for the app')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
-      // Validate URL format
-      try {
-        new URL(options.url);
-      } catch {
-        throw new Error('Invalid URL format');
-      }
-      
-      const response = await apiClient.invoke('update_app_metadata', {
+
+      const response = await apiClient.invoke('update_app', {
         community_id: options.community,
         app_id: options.app,
-        api_base_url: options.url
+        app_name: options.name
       });
       const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ API base URL updated!\n'));
+
+      console.log(chalk.green('\n✅ App display name updated!\n'));
       console.log(chalk.cyan(`  App: ${options.community}/${options.app}`));
-      console.log(chalk.gray(`  API URL: ${options.url}\n`));
+      console.log(chalk.gray(`  Name: ${options.name}\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -1365,69 +1425,35 @@ appCommand
   });
 
 appCommand
-  .command('deploy')
-  .description('Deploy a microservice for an app you own (registers manifest.json)')
-  .option('-m, --manifest <path>', 'Path to manifest.json (default: ./manifest.json)')
+  .command('set-api-url')
+  .description('Set API base URL for app\'s own backend')
+  .requiredOption('-c, --community <id>', 'Community ID')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .requiredOption('-u, --url <url>', 'API base URL (e.g., https://api.example.com)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
       
-      // Read manifest.json from current directory or specified path
-      const manifestPath = path.resolve(options.manifest || './manifest.json');
-      
-      console.log(chalk.cyan(`\n📦 Deploying microservice from ${manifestPath}\n`));
-      
-      let manifest;
+      // Validate URL format
       try {
-        const manifestContent = await fs.readFile(manifestPath, 'utf-8');
-        manifest = JSON.parse(manifestContent);
-      } catch (error) {
-        if (error.code === 'ENOENT') {
-          console.error(chalk.red(`❌ manifest.json not found at ${manifestPath}`));
-          console.error(chalk.gray('\nCreate a manifest.json with your service configuration.'));
-          console.error(chalk.gray('See DeSciX_Core/descix-cli/templates/scaffolds/microservice/manifest.json for a template.\n'));
-          process.exit(1);
-        }
-        throw new Error(`Failed to parse manifest.json: ${error.message}`);
-      }
-      
-      // Validate required fields
-      if (!manifest.service?.name) {
-        throw new Error('manifest.service.name is required');
-      }
-      if (!manifest.service?.app_id) {
-        throw new Error('manifest.service.app_id is required (the app you own)');
-      }
-      if (!manifest.service?.community_id) {
-        throw new Error('manifest.service.community_id is required');
-      }
-      if (!manifest.service?.domain) {
-        throw new Error('manifest.service.domain is required');
+        new URL(options.url);
+      } catch {
+        throw new Error('Invalid URL format');
       }
       
-      console.log(chalk.gray(`  Service: ${manifest.service.name}`));
-      console.log(chalk.gray(`  App: ${manifest.service.community_id}/${manifest.service.app_id}`));
-      console.log(chalk.gray(`  Domain: ${manifest.service.domain}`));
-      console.log(chalk.gray(`  Commands: ${Object.keys(manifest.commands || {}).length}\n`));
-      
-      // Call register_service
-      const response = await apiClient.invoke('register_service', { manifest });
+      const response = await apiClient.invoke('update_app_metadata', {
+        community_id: options.community,
+        app_id: options.app,
+        api_base_url: options.url
+      });
       const result = response.message || response;
       
-      console.log(chalk.green('✅ Microservice deployed successfully!\n'));
-      console.log(chalk.cyan(`  Service: ${manifest.service.name}`));
-      console.log(chalk.gray(`  Commands registered: ${Object.keys(manifest.commands || {}).length}`));
-      
-      if (response.app_updated) {
-        console.log(chalk.gray(`  App api_base_url: ${response.api_base_url}`));
-      }
-      
-      console.log(chalk.gray('\n  The service manifest cache will refresh within 5 minutes.'));
-      console.log(chalk.gray('  For immediate effect, an admin can run: descix microservice reload\n'));
-      
+      console.log(chalk.green('\n✅ API base URL updated!\n'));
+      console.log(chalk.cyan(`  App: ${options.community}/${options.app}`));
+      console.log(chalk.gray(`  API URL: ${options.url}\n`));
     } catch (error) {
-      console.error(chalk.red(`\n❌ Deployment failed: ${error.message}\n`));
+      console.error(chalk.red(error.message));
       process.exit(1);
     }
   });
@@ -1495,144 +1521,839 @@ appCommand
     }
   });
 
-// ============ Knowledge Base Commands ============
-
-const kbCommand = program
-  .command('kb')
-  .description('Knowledge base operations');
-
-kbCommand
-  .command('create')
-  .description('Create a new knowledge base in an app')
-  .requiredOption('-c, --community <id>', 'Community ID')
-  .requiredOption('-a, --app <id>', 'App ID')
-  .requiredOption('-k, --kb <id>', 'Knowledge Base ID')
-  .option('--drive-folder <id>', 'Google Drive folder ID (optional, will create if not provided)')
+appCommand
+  .command('delete')
+  .description('Delete an app with full cascade cleanup (Pinecone, GCS, Firestore, Products)')
+  .requiredOption('-a, --app <app_id>', 'App ID to delete')
+  .option('-c, --community <community_id>', 'Community ID (auto-resolved from Products if omitted)')
+  .option('--dry-run', 'Preview what would be deleted without executing')
+  .option('--soft', 'Soft delete only (mark as hidden, no cascade)')
+  .option('--yes', 'Skip confirmation prompt')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
-      const response = await apiClient.invoke('create_skeleton_kb', {
-        community_id: options.community,
-        app_id: options.app,
-        kb_name: options.kb,
-        drive_folder_id: options.driveFolder || null
+
+      const appId = options.app;
+      const hardDelete = !options.soft;
+      const dryRun = !!options.dryRun;
+
+      // Resolve community_id if not provided (apiFront hydrates from Products)
+      let communityId = options.community || null;
+
+      if (dryRun) {
+        console.log(chalk.cyan(`\n--- DRY RUN: delete ${appId} ---\n`));
+      }
+
+      const response = await apiClient.invoke('delete_app', {
+        app_id: appId,
+        community_id: communityId,
+        hard_delete: hardDelete,
+        dry_run: dryRun
       });
+
       const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ Knowledge Base created successfully!\n'));
-      console.log(chalk.cyan(`  KB ID: ${options.kb}`));
-      console.log(chalk.gray(`  App: ${options.community}/${options.app}`));
-      if (result.drive_folder_id) {
-        console.log(chalk.gray(`  Drive Folder: ${result.drive_folder_id}\n`));
-      }
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
 
-// Phase 0 CLI-Centric KB Processing Commands
-kbCommand
-  .command('pull')
-  .description('Pull KB content from Drive and convert to local markdown')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
-  .option('-v, --verbose', 'Show verbose output')
-  .option('--merge-mode <mode>', 'Merge mode: merge|overwrite|force-overwrite (default: merge)')
-  .option('--dry-run', 'Show what would happen without making changes')
+      if (dryRun) {
+        const m = result.deletion_manifest || result;
+        console.log(chalk.bold('Deletion manifest:\n'));
+        if (m.pinecone_only_orphan) {
+          console.log(chalk.yellow(`  ** Pinecone-only orphan: no Firestore/Products records found **\n`));
+        }
+        if (m.app_doc) console.log(chalk.gray(`  Firestore App:     ${m.app_doc}`));
+        if (m.products_doc) console.log(chalk.gray(`  Products Doc:      ${m.products_doc}`));
+        if (m.knowledgebases?.length) {
+          console.log(chalk.gray(`  Knowledge Bases:   ${m.knowledgebases.length}`));
+          for (const kb of m.knowledgebases) {
+            console.log(chalk.gray(`    - ${kb}`));
+          }
+        }
+        if (m.pinecone_note) {
+          console.log(chalk.yellow(`  Pinecone:          ${m.pinecone_note}`));
+        } else {
+          console.log(chalk.gray(`  Pinecone filter:   app_id == ${appId} (${m.pinecone_kb_count} KBs)`));
+        }
+        console.log(chalk.gray(`  GCS prefix:        ${m.gcs_prefix}`));
+        console.log(chalk.gray(`  IPDocs:            ${m.ip_docs_count}`));
+        if (m.service_manifests?.length) {
+          console.log(chalk.gray(`  ServiceManifests:  ${m.service_manifests.join(', ')}`));
+        }
+        console.log(chalk.yellow('\n  No changes were made. Remove --dry-run to execute.\n'));
+        return;
+      }
+
+      // Confirmation prompt (unless --yes)
+      if (!options.yes && hardDelete) {
+        const readline = await import('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise(resolve => {
+          rl.question(chalk.yellow(`\n  Permanently delete ${appId}? This cannot be undone. [y/N] `), resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== 'y') {
+          console.log(chalk.gray('\n  Aborted.\n'));
+          return;
+        }
+      }
+
+      // Display results
+      if (result.cleanup) {
+        const c = result.cleanup;
+        console.log(chalk.green(`\n  App ${appId} deleted.\n`));
+        console.log(chalk.gray(`  Pinecone vectors:  ${c.pinecone_deleted === -1 ? 'filter-deleted' : c.pinecone_deleted} (KBs: ${c.kbs_deleted?.join(', ') || 'none'})`));
+        console.log(chalk.gray(`  GCS files:         ${c.gcs_deleted}`));
+        console.log(chalk.gray(`  Firestore docs:    ${c.firestore_deleted} (IPDocs)`));
+        console.log(chalk.gray(`  Products deleted:  ${c.products_deleted ? 'yes' : 'no'}`));
+        if (c.service_manifests_deleted?.length) {
+          console.log(chalk.gray(`  ServiceManifests:  ${c.service_manifests_deleted.join(', ')}`));
+        }
+        console.log();
+      } else {
+        console.log(chalk.green(`\n  ${result.message || `App ${appId} deleted.`}\n`));
+      }
+    } catch (error) {
+      console.error(chalk.red(`\n  Error: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+appCommand
+  .command('sync-assets')
+  // Canonical asset-sync surface. The legacy Drive-mode `sync assets` DUPLICATE was removed in
+  // WS-MCP-SURFACE-SPLIT Step 3 §5.5; this is now the sole path.
+  .description('Sync local assets (system_instructions.md, app_description.md, icon.png) to platform.')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .option('-k, --kb <name>', 'Target KB for system_instructions', 'General')
+  .option('-p, --path <dir>', 'App directory (default: auto-detected)')
   .action(async (options) => {
     try {
-      let apiClient = null;
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+      const fs = await import('fs');
+      const path = await import('path');
+
+      // Resolve app path via WorkspaceConfig (v2.1 — localPath from workspace.json)
+      let appPath = options.path;
+      if (!appPath) {
+        try {
+          const wsConfig = await WorkspaceConfig.load();
+          const appConfig = wsConfig.getAppByAppId(options.app);
+          if (appConfig?.absolutePath) {
+            appPath = appConfig.absolutePath;
+          }
+        } catch { /* fall through */ }
+      }
+      if (!appPath) {
+        console.error(chalk.red(`App '${options.app}' not found in workspace.json. Use -p to specify path.`));
+        process.exit(1);
+      }
+
+      const assetsDir = path.default.join(appPath, 'assets');
+      const assets = {};
+      let found = 0;
+
+      // system_instructions.md
+      const siPath = path.default.join(assetsDir, 'system_instructions.md');
+      if (fs.default.existsSync(siPath)) {
+        assets.system_instructions = fs.default.readFileSync(siPath, 'utf8');
+        found++;
+        console.log(chalk.gray(`  Found: ${siPath}`));
+      }
+
+      // app_description.md
+      const descPath = path.default.join(assetsDir, 'app_description.md');
+      if (fs.default.existsSync(descPath)) {
+        assets.app_description = fs.default.readFileSync(descPath, 'utf8');
+        found++;
+        console.log(chalk.gray(`  Found: ${descPath}`));
+      }
+
+      // icon.png
+      const iconPath = path.default.join(assetsDir, 'icon.png');
+      if (fs.default.existsSync(iconPath)) {
+        assets.icon_base64 = fs.default.readFileSync(iconPath).toString('base64');
+        found++;
+        console.log(chalk.gray(`  Found: ${iconPath}`));
+      }
+
+      if (found === 0) {
+        console.log(chalk.yellow(`\nNo assets found in ${assetsDir}`));
+        console.log(chalk.gray('Expected: system_instructions.md, app_description.md, icon.png\n'));
+        return;
+      }
+
+      console.log(chalk.gray(`\nSyncing ${found} asset(s) for ${options.app}...`));
+
+      const response = await apiClient.invoke('sync_app_assets', {
+        app_id: options.app,
+        kb_name: options.kb,
+        assets
+      });
+
+      const result = response.message || response;
+      if (result.results) {
+        for (const [key, val] of Object.entries(result.results)) {
+          if (val.updated) {
+            console.log(chalk.green(`  ${key}: synced${val.kb ? ` (KB: ${val.kb})` : ''}`));
+          } else {
+            console.log(chalk.red(`  ${key}: failed — ${val.error || 'unknown'}`));
+          }
+        }
+      }
+      console.log(chalk.green('\nAsset sync complete.\n'));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+appCommand
+  .command('set-localpath')
+  .description('Update the local directory path for a mapped app')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .requiredOption('-p, --path <dir>', 'New local directory path')
+  .action(async (options) => {
+    try {
+      const appId = options.app;
+      const newPath = options.path;
+
+      const workspaceConfig = await WorkspaceConfig.load();
+      const appConfig = workspaceConfig.getAppByAppId(appId);
+      if (!appConfig) {
+        throw new Error(`App '${appId}' is not mapped. Run 'descix app init -a ${appId}' first.`);
+      }
+
+      // Hard-fail if path doesn't exist or is not a directory
+      let stat;
       try {
-        apiClient = new DeSciXApiClient();
-        await apiClient.loadCredentials();
+        stat = await fs.stat(newPath);
       } catch {
-        // Continue without API client
+        throw new Error(`Path does not exist: ${newPath}`);
       }
-      
-      await kbCommands.runKbPull(apiClient, options);
+      if (!stat.isDirectory()) {
+        throw new Error(`Path is not a directory: ${newPath}`);
+      }
+
+      // Update the localPath in workspace.json
+      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
+      const oldPath = appConfig.localPath;
+      appConfig.localPath = newPath;
+
+      // Update env.products entry
+      const products = workspaceConfig.env?.products || [];
+      for (const product of products) {
+        if (product.appId === appId || product.app_id === appId) {
+          product.localPath = newPath;
+          break;
+        }
+      }
+      await workspaceConfig.save(wsRoot);
+
+      console.log(chalk.green(`\n✓ ${appId} local path updated`));
+      console.log(chalk.gray(`  ${oldPath} → ${newPath}\n`));
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+appCommand
+  .command('unmap')
+  .description('Remove an app from the local workspace mapping (does not delete Firestore/Pinecone data)')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .action(async (options) => {
+    try {
+      const appId = options.app;
+
+      const workspaceConfig = await WorkspaceConfig.load();
+      const appConfig = workspaceConfig.getAppByAppId(appId);
+      if (!appConfig) {
+        throw new Error(`App '${appId}' is not mapped.`);
+      }
+
+      // Remove from env.products
+      const products = workspaceConfig.env?.products || [];
+      const idx = products.findIndex(p => p.appId === appId || p.app_id === appId);
+      if (idx === -1) {
+        throw new Error(`App '${appId}' is not found in env.products.`);
+      }
+      products.splice(idx, 1);
+
+      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
+      await workspaceConfig.save(wsRoot);
+
+      console.log(chalk.green(`\n✓ ${appId} removed from workspace mapping`));
+      console.log(chalk.gray(`  Pinecone vectors, Firestore docs, and Drive data are not affected.\n`));
+    } catch (error) {
+      console.error(chalk.red(error.message));
       process.exit(1);
     }
   });
 
+// ============ App: set-port (WS-CLI-MESH-ROUTING-GAP) ============
+//
+// Canonical write path for an app's microservice.port in workspace.json.
+// `descix microservice init` READS env.products[<app>].microservice.port and hard-fails
+// if it is missing; this command is how that port is set, without hand-editing workspace.json.
+// Backed by WorkspaceConfig.setMicroservicePort (parallel to setSitePort).
+appCommand
+  .command('set-port')
+  .description('Set the microservice port for a mapped app (writes env.products[<app>].microservice.port). Pass "n" to remove.')
+  .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
+  .requiredOption('-p, --port <port>', 'Microservice port number (1-65535), or "n" to remove')
+  .action(async (options) => {
+    try {
+      const appId = options.app;
+      const workspaceConfig = await WorkspaceConfig.load();
+
+      // Disable case — setMicroservicePort(appId, null) removes microservice.port / cleans microservice.{}
+      if (options.port === 'n' || options.port === 'N') {
+        await workspaceConfig.setMicroservicePort(appId, null);
+        console.log(chalk.green(`\n✓ Microservice port removed for ${appId}\n`));
+        return;
+      }
+
+      const portNum = parseInt(options.port, 10);
+      if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+        console.error(chalk.red('\n❌ Invalid port number. Provide an integer 1-65535, or "n" to remove.\n'));
+        process.exit(1);
+      }
+
+      // setMicroservicePort mutates the live env entry and saves — and hard-fails (canonical
+      // "not mapped in workspace.json" error) for an unmapped app, surfaced in the catch below.
+      await workspaceConfig.setMicroservicePort(appId, portNum);
+
+      console.log(chalk.green(`\n✓ Microservice port set for ${appId}`));
+      console.log(chalk.cyan(`  Port: ${portNum}`));
+      console.log(chalk.gray(`  Written to env.products[${appId}].microservice.port in workspace.json.`));
+      console.log(chalk.gray(`  The gateway routes the microservice on this port; \`descix microservice init -a ${appId}\` can now scaffold it.\n`));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// ============ 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 setSitePort/setMicroservicePort).
+//
+// NOTE: This is NOT `set-codesite` — that writes the Firestore ip_site_gcs_path_url (a prod
+// concern). set-site 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.{}.")
+  .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')
+  .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.{})
+      if (options.unset) {
+        await workspaceConfig.setStaticSite(appId, { static: null, port: null });
+        console.log(chalk.green(`\n✓ site config cleared for ${appId}\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'));
+        process.exit(1);
+      }
+
+      const fields = {};
+
+      if (options.static !== undefined) {
+        if (typeof options.static !== 'string' || options.static.trim() === '') {
+          console.error(chalk.red('\n❌ --static requires a non-empty relative path (e.g. "site" or ".").\n'));
+          process.exit(1);
+        }
+        fields.static = options.static;
+      }
+
+      if (options.port !== undefined) {
+        const portNum = parseInt(options.port, 10);
+        if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+          console.error(chalk.red('\n❌ Invalid port number. Provide an integer 1-65535.\n'));
+          process.exit(1);
+        }
+        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.
+      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`));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+
+// ============ App: open (WS-SSGPOD — dev URL resolver) ============
+//
+// Resolves an app's LOCAL GATEWAY URL (the URL served by `descix serve`, which mirrors
+// the production LB) and prints it; with --open, launches the default browser.
+// Reuses the SDK resolver resolveAppGatewayUrl() — the same workspace.json read path
+// behind buildWorkspaceProducts() that the PWA bakes into __WORKSPACE_PRODUCTS__ — so
+// the URL matches what the app store routes to:
+//   - env.platform        → https://localhost:{gatewayPort}/
+//   - product (static)    → https://localhost:{gatewayPort}/p/{appId}
+//   - product (dev-server)→ https://localhost:{gatewayPort}/p/{appId}
+// Hard-fails clearly if the app is unmapped or has no site config.
+appCommand
+  .command('open')
+  .description('Resolve (and optionally open) an app\'s local gateway dev URL. Hard-fails if the app has no site config.')
+  .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json with a site)')
+  .option('--open', 'Open the resolved URL in the default browser')
+  .action(async (options) => {
+    try {
+      const appId = options.app;
+      const { resolveAppGatewayUrl } = await import('@descix/app-sdk/dev');
+      const workspaceConfig = await WorkspaceConfig.load();
+      const workspaceRoot = workspaceConfig.workspaceRoot || process.cwd();
+
+      // resolveAppGatewayUrl hard-fails (no site / unmapped / no workspace) — surfaced in catch.
+      const resolved = resolveAppGatewayUrl(workspaceRoot, appId);
+
+      console.log(chalk.green(`\n${appId} → ${resolved.url}`));
+      console.log(chalk.gray(`  kind: ${resolved.kind}`));
+      console.log(chalk.gray(`  via:  ${resolved.via}`));
+      console.log(chalk.gray(`  (start the gateway with \`descix serve\` on port ${resolved.gatewayPort} if it is not already running)\n`));
+
+      if (options.open) {
+        // Use the platform-native opener — no extra npm dependency, no hardcoded fallback.
+        const { spawn } = await import('node:child_process');
+        const platform = process.platform;
+        const opener = platform === 'darwin' ? 'open'
+          : platform === 'win32' ? 'cmd'
+          : 'xdg-open';
+        const args = platform === 'win32' ? ['/c', 'start', '', resolved.url] : [resolved.url];
+        const child = spawn(opener, args, { stdio: 'ignore', detached: true });
+        child.on('error', (err) => {
+          console.error(chalk.yellow(`  Could not launch browser (${err.message}). Open the URL above manually.`));
+        });
+        child.unref();
+      }
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+
+// ============ App: set-default-model (WS-CONFIG-BOOTSTRAP-FIX item #10) ============
+//
+// Updates Community/{c}/Apps/{a}.default_app_model. Per CEO inheritance chain:
+//   options.model > kb.kb_model_override > app.default_app_model > levelConfig.model > DEFAULT_AI_MODEL
+//
+// --clear deletes the field via FieldValue.delete() (NOT null) so the resolver falls through
+// cleanly to per-level platform defaults.
+
+appCommand
+  .command('set-default-model')
+  .description('Set or clear App.default_app_model (model used when no KB override is set)')
+  .requiredOption('-a, --app <app_id>', 'App ID (e.g. unk-cos)')
+  .option('-m, --model <model_name>', 'Gemini model name (e.g. gemini-3.1-flash-lite). Mutually exclusive with --clear.')
+  .option('--clear', 'Delete App.default_app_model via FieldValue.delete() (resets to platform-default inheritance)')
+  .addHelpText('after', `
+NOTE: Pinning a "Pro" model (e.g., gemini-2.5-pro, gemini-3.1-pro-preview) as
+an app or KB override will fail at L1 — these models require thinking mode and
+reject L1's thinkingBudget=0. If you intend an L1-compatible override, use a
+"Flash" model (gemini-2.5-flash, gemini-3.1-flash-lite, gemini-3-flash-preview).
+`)
+  .action(async (options) => {
+    try {
+      // Forward the parent --env flag so the audit log records the target environment.
+      const parentEnv = program.opts().env || null;
+      await modelConfigCommands.runAppSetDefaultModel({ ...options, env: parentEnv });
+    } catch (error) {
+      console.error(chalk.red(`\n\u274c ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ============ Knowledge Base Commands ============
+
+const kbCommand = program
+  .command('kb')
+  .description('Knowledge base operations');
+
 kbCommand
-  .command('chunk')
-  .description('Generate chunks from local markdown files')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
-  .option('-s, --chunk-size <size>', 'Chunk size in characters (default: 512)')
-  .option('-o, --overlap <size>', 'Overlap between chunks (default: 64)')
-  .option('-v, --verbose', 'Show verbose output')
+  .command('list')
+  .description('List knowledge bases for an app')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .option('--cached', 'Show the fast cached vector counter instead of the TRUE live Pinecone count. The cached counter is written ONLY by the CLI/PWA sync path, so it reports 0 for KBs ingested by any other route even when their vectors retrieve. Default is the live count.')
+  .addHelpText('after', `
+By default the Vectors column is the TRUE live Pinecone count (server enumerates each
+KB's vectors by id-prefix). The Source column shows how each count was obtained:
+  live    = counted live from Pinecone (authoritative)
+  cached  = the fast cached counter (--cached; may under-report; verify with a live run)
+  unknown = live count requested but Pinecone enumeration failed — shown as '?', NOT a fake 0
+`)
   .action(async (options) => {
     try {
-      await kbCommands.runKbChunk(options);
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+
+      // Default to the TRUE live Pinecone count. --cached opts into the fast (possibly
+      // stale) cached counter that only the sync path writes.
+      const live = !options.cached;
+      const response = await apiClient.invoke('list_knowledge_bases', {
+        app_id: options.app,
+        live
+      });
+      const result = response.message || response;
+      const kbs = result.knowledge_bases || [];
+
+      if (kbs.length === 0) {
+        console.log(chalk.yellow(`\nNo knowledge bases found for app ${options.app}\n`));
+        return;
+      }
+
+      // Render helpers live in ../lib/commands/kb-list-render.js (unit-tested there).
+      const vectorCell = (kb) => kbVectorCell(kb);
+      const sourceCell = (kb) => kbCountSource(kb, live);
+
+      // Table output
+      const nameW = Math.max(7, ...kbs.map(k => (k.name || '').length));
+      const modelW = Math.max(5, ...kbs.map(k => (k.model || '').length));
+      const vecW = Math.max(7, ...kbs.map(k => vectorCell(k).length));
+
+      console.log('\n' + chalk.bold(
+        'KB Name'.padEnd(nameW + 2) +
+        'Model'.padEnd(modelW + 2) +
+        'Instructions'.padEnd(14) +
+        'Vectors'.padEnd(vecW + 2) +
+        'Source'.padEnd(9) +
+        'Last Sync'
+      ));
+      console.log('-'.repeat(nameW + modelW + 49));
+
+      for (const kb of kbs) {
+        const syncDate = kb.rag_last_sync
+          ? new Date(kb.rag_last_sync._seconds ? kb.rag_last_sync._seconds * 1000 : kb.rag_last_sync).toISOString().split('T')[0]
+          : '-';
+        const src = sourceCell(kb);
+        const srcColor = src === 'live' ? chalk.green : src === 'unknown' ? chalk.yellow : chalk.gray;
+        console.log(
+          chalk.cyan((kb.name || '').padEnd(nameW + 2)) +
+          chalk.gray((kb.model || '').padEnd(modelW + 2)) +
+          (kb.system_instructions === 'present' ? chalk.green('present') : chalk.gray('empty')).padEnd(14 + 10) +
+          vectorCell(kb).padEnd(vecW + 2) +
+          srcColor(src.padEnd(9)) +
+          syncDate
+        );
+      }
+      console.log();
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      console.error(chalk.red(error.message));
       process.exit(1);
     }
   });
 
 kbCommand
-  .command('sync')
-  .description('Sync local chunks to Pinecone via service layer')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
-  .option('-v, --verbose', 'Show verbose output')
+  .command('create')
+  .description('Create a new knowledge base in an app')
+  .requiredOption('-c, --community <id>', 'Community ID')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .requiredOption('-k, --kb <id>', 'Knowledge Base ID')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
       
-      await kbCommands.runKbSync(apiClient, options);
+      const response = await apiClient.invoke('create_skeleton_kb', {
+        community_id: options.community,
+        app_id: options.app,
+        kb_name: options.kb
+      });
+      const result = response.message || response;
+      
+      console.log(chalk.green('\n✅ Knowledge Base created successfully!\n'));
+      console.log(chalk.cyan(`  KB ID: ${options.kb}`));
+      console.log(chalk.gray(`  App: ${options.community}/${options.app}`));
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      console.error(chalk.red(error.message));
       process.exit(1);
     }
   });
 
 kbCommand
-  .command('build')
-  .description('Full KB pipeline: [push staging] → pull → chunk → sync')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
-  .option('-s, --chunk-size <size>', 'Chunk size in characters (default: 2000)')
-  .option('-o, --overlap <size>', 'Overlap between chunks (default: 500)')
-  .option('-v, --verbose', 'Show verbose output')
-  .option('-i, --interactive', 'Enable interactive prompts for conflicts')
-  .option('--skip-staging', 'Skip staging push step')
-  .option('--merge-mode <mode>', 'Pull merge mode: merge|overwrite|force-overwrite (default: merge)')
-  .option('--dry-run', 'Show what would happen without making changes')
+  .command('delete')
+  .description('Delete a knowledge base registry doc (refuses a non-empty KB unless --force)')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .requiredOption('-k, --kb <kb_name>', 'KB name')
+  .option('--force', 'Purge the KB\'s live vectors and delete it even if non-empty. An empty KB deletes without this flag.')
+  .addHelpText('after', `
+Fail-safe: the server reads the TRUE live Pinecone count. A KB with live vectors (or an
+undetermined count) is REFUSED unless --force. With --force the vectors are purged BEFORE
+the registry doc is removed, so a removed doc never strands orphan vectors.`)
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
-      await kbCommands.runKbBuild(apiClient, options);
+
+      const response = await apiClient.invoke('delete_knowledge_base', {
+        app_id: options.app,
+        kb_name: options.kb,
+        force: !!options.force
+      });
+      const result = response.message || response;
+
+      console.log(chalk.green('\n✅ Knowledge base deleted.\n'));
+      console.log(chalk.cyan(`  KB: ${options.kb}`));
+      console.log(chalk.gray(`  App: ${result.community_id || '?'}/${options.app}`));
+      if (result.vectors_purged) {
+        console.log(chalk.gray(`  Vectors purged: ${result.vectors_purged}`));
+      }
+      console.log();
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      console.error(chalk.red(error.message));
       process.exit(1);
     }
   });
 
+
+// ============ KB: set-/clear-override-model (WS-CONFIG-BOOTSTRAP-FIX item #10) ============
+//
+// Updates Community/{c}/Apps/{a}/KnowledgeBases/{k}.kb_model_override.
+// Per CEO practice, KB overrides should be MINIMIZED — only use when a specific KB needs
+// a model different from App.default_app_model (e.g., a tuned model for one KB).
+//
+// clear-override-model deletes the field via FieldValue.delete() (NOT null) per tripwire #2.
+
 kbCommand
-  .command('push')
-  .description('Push staging files to Drive')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
+  .command('set-override-model')
+  .description('Set KB.kb_model_override (per-KB model selection)')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .requiredOption('-k, --kb <kb_name>', 'KB name')
+  .requiredOption('-m, --model <model_name>', 'Gemini model name (e.g. gemini-2.5-pro)')
+  .addHelpText('after', `
+NOTE: Pinning a "Pro" model (e.g., gemini-2.5-pro, gemini-3.1-pro-preview) as
+an app or KB override will fail at L1 — these models require thinking mode and
+reject L1's thinkingBudget=0. If you intend an L1-compatible override, use a
+"Flash" model (gemini-2.5-flash, gemini-3.1-flash-lite, gemini-3-flash-preview).
+`)
+  .action(async (options) => {
+    try {
+      const parentEnv = program.opts().env || null;
+      await modelConfigCommands.runKbSetOverrideModel({ ...options, env: parentEnv });
+    } catch (error) {
+      console.error(chalk.red(`\n\u274c ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+kbCommand
+  .command('clear-override-model')
+  .description('Delete KB.kb_model_override via FieldValue.delete() (resets to App.default_app_model inheritance)')
+  .requiredOption('-a, --app <app_id>', 'App ID')
+  .requiredOption('-k, --kb <kb_name>', 'KB name')
+  .action(async (options) => {
+    try {
+      const parentEnv = program.opts().env || null;
+      await modelConfigCommands.runKbClearOverrideModel({ ...options, env: parentEnv });
+    } catch (error) {
+      console.error(chalk.red(`\n\u274c ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// `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);
+
+
+// app records — APP DATA PLANE structured record store (CEO-D-2026-06-02-APP-DATA-PLANE)
+// Treat your app like a database table: put/query/get/delete structured records
+// with custom metadata. Records live in the app data plane (Firestore document
+// collections), NOT the Pinecone KB. `query` is a STRUCTURED, strongly-consistent
+// metadata-filtered scan (non-ANN) returning full records; for semantic ANN search
+// use `descix chat`.
+//
+// Canonical surface: `descix app records ...` (commands app_records_*).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Attach the four records subcommands (put/query/get/delete) to a parent command.
+ * @param {import('commander').Command} parent - the `records` parent command
+ * @param {string} cmdPrefix - backend command prefix ('app_records')
+ */
+function attachRecordsSubcommands(parent, cmdPrefix) {
+  parent
+    .command('put')
+    .description('Store/replace records in your app data store with custom metadata (your app as a database table). You supply file_id (+ optional chunk_idx); the id is built for you.')
+    .requiredOption('-a, --app <app_id>', 'App ID')
+    .requiredOption('-k, --kb <kb_id>', 'Record collection ID (acts like a table)')
+    .requiredOption('-r, --records <json>', 'JSON array of records: [{ "file_id", "text"?, "chunk_idx"?, ...customMetadata }] — id is built from file_id (+ chunk_idx); pass a full "id" only for back-compat. Example: \'[{"file_id":"e1","text":"...","type":"episode","show":"x"}]\'')
+    .option('--mode <mode>', 'upsert (default) | create — "create" is an atomic all-or-nothing conditional create: it fails if any key already exists and reports who holds it, instead of overwriting', 'upsert')
+    .action(async (options) => {
+      try {
+        const apiClient = new DeSciXApiClient();
+        await requireAuth(apiClient);
+        let records;
+        try { records = JSON.parse(options.records); } catch (e) { throw new Error(`--records must be valid JSON array: ${e.message}`); }
+        if (!Array.isArray(records)) throw new Error('--records must be a JSON array');
+        const response = await apiClient.invoke(`${cmdPrefix}_put`, { app_id: options.app, kb_id: options.kb, records, mode: options.mode });
+        const result = response.message || response;
+        // A refused conditional create is a DEFINITE answer, not a warning: report it as a
+        // failure with the holder hint and a non-zero exit so scripts branch on it correctly.
+        if (result.claimed === false) {
+          console.error(chalk.red(`\n❌ claim refused — ${result.message || 'key already exists'}\n`));
+          process.exit(1);
+        }
+        console.log(chalk.green(`\n✓ ${result.message || 'records put'}\n`));
+      } catch (error) {
+        console.error(chalk.red(`\n❌ ${error.message}\n`));
+        process.exit(1);
+      }
+    });
+
+  parent
+    .command('query')
+    .description('STRUCTURED metadata-filtered scan (non-ANN) returning full records: "all records where type=episode AND show=X"')
+    .requiredOption('-a, --app <app_id>', 'App ID')
+    .requiredOption('-k, --kb <kb_id>', 'Record collection ID')
+    .option('-f, --filter <json>', 'Metadata predicate JSON. Scalar fields: $eq/$ne/$in or a bare value; ARRAY fields: $contains. e.g. \'{"type":"episode","tags":{"$contains":"handoff"}}\'', '{}')
+    .option('--fields <csv>', 'Comma-separated metadata projection (omit or "*" for all metadata)')
+    .option('--limit <n>', 'Cap on returned records', (v) => parseInt(v, 10))
+    .action(async (options) => {
+      try {
+        const apiClient = new DeSciXApiClient();
+        await requireAuth(apiClient);
+        let filter;
+        try { filter = JSON.parse(options.filter); } catch (e) { throw new Error(`--filter must be valid JSON: ${e.message}`); }
+        const fields = options.fields ? options.fields.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+        const params = { app_id: options.app, kb_id: options.kb, filter };
+        if (fields) params.fields = fields;
+        if (options.limit) params.limit = options.limit;
+        const response = await apiClient.invoke(`${cmdPrefix}_query`, params);
+        const result = response.message || response;
+        console.log(chalk.gray(`\n${result.message || ''}`));
+        console.log(JSON.stringify(result.records || [], null, 2));
+        console.log();
+      } catch (error) {
+        console.error(chalk.red(`\n❌ ${error.message}\n`));
+        process.exit(1);
+      }
+    });
+
+  parent
+    .command('get')
+    .description('Fetch specific records by id (point lookup) with an arbitrary metadata projection')
+    .requiredOption('-a, --app <app_id>', 'App ID')
+    .requiredOption('-k, --kb <kb_id>', 'Record collection ID')
+    .requiredOption('-i, --ids <csv>', 'Comma-separated record ids to fetch')
+    .option('--fields <csv>', 'Comma-separated metadata projection (omit or "*" for all metadata)')
+    .action(async (options) => {
+      try {
+        const apiClient = new DeSciXApiClient();
+        await requireAuth(apiClient);
+        const ids = options.ids.split(',').map(s => s.trim()).filter(Boolean);
+        const fields = options.fields ? options.fields.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+        const params = { app_id: options.app, kb_id: options.kb, ids };
+        if (fields) params.fields = fields;
+        const response = await apiClient.invoke(`${cmdPrefix}_get`, params);
+        const result = response.message || response;
+        console.log(chalk.gray(`\n${result.message || ''}`));
+        console.log(JSON.stringify(result.records || [], null, 2));
+        console.log();
+      } catch (error) {
+        console.error(chalk.red(`\n❌ ${error.message}\n`));
+        process.exit(1);
+      }
+    });
+
+  parent
+    .command('delete')
+    .description('Delete records by id (or by file_id grouping key)')
+    .requiredOption('-a, --app <app_id>', 'App ID')
+    .requiredOption('-k, --kb <kb_id>', 'Record collection ID')
+    .option('-i, --ids <csv>', 'Comma-separated record ids to delete')
+    .option('--file-ids <csv>', 'Comma-separated file_id grouping keys to delete')
+    .action(async (options) => {
+      try {
+        const apiClient = new DeSciXApiClient();
+        await requireAuth(apiClient);
+        const ids = options.ids ? options.ids.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const file_ids = options.fileIds ? options.fileIds.split(',').map(s => s.trim()).filter(Boolean) : [];
+        if (ids.length === 0 && file_ids.length === 0) throw new Error('Provide --ids and/or --file-ids');
+        const response = await apiClient.invoke(`${cmdPrefix}_delete`, { app_id: options.app, kb_id: options.kb, ids, file_ids });
+        const result = response.message || response;
+        console.log(chalk.green(`\n✓ ${result.message || 'records deleted'}\n`));
+      } catch (error) {
+        console.error(chalk.red(`\n❌ ${error.message}\n`));
+        process.exit(1);
+      }
+    });
+}
+
+// Canonical: `descix app records ...`
+const appRecordsCommand = appCommand
+  .command('records')
+  .description('Use your app as a queryable database (put/query/get/delete structured records with custom metadata). Backed by the app data plane (Firestore), not the Pinecone KB.');
+attachRecordsSubcommands(appRecordsCommand, 'app_records');
+
+
+// Corpus sub-commands (git-aware RAG sync via manifests)
+const corpusCommand = kbCommand
+  .command('corpus')
+  .description('Git-aware corpus sync via manifests');
+
+corpusCommand
+  .command('sync')
+  .description('Sync corpus files to Pinecone using manifest definitions')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .option('-c, --community <community_id>', 'Community ID (optional; resolved from Products when omitted)')
+  .option('-k, --kb <name>', 'KB name (syncs specific manifest; default: all)')
   .option('-v, --verbose', 'Show verbose output')
-  .option('-i, --interactive', 'Enable interactive prompts for conflicts')
-  .option('--on-conflict <action>', 'Conflict handling: overwrite|skip (default: overwrite)')
-  .option('--no-move', 'Do not move files to .processed after upload')
-  .option('--dry-run', 'Show what would happen without making changes')
+  .option('--ref <ref>', 'Override the git ref for ALL manifest sources (e.g., --ref ws-admin-b1). Precedence: --ref > manifest source.ref > "main".')
+  .option('--rebuild', 'Reconcile Pinecone against the current manifest walk: enumerate remote file_ids, purge any not in the current corpus, then re-sync from scratch. Use to recover from accumulated stale-chunk drift. Prompts before deleting unless --yes is supplied.')
+  .option('--dry-run', 'Enumerate would-be-purged file_ids and would-be-upserted chunks without ANY Pinecone writes. Exit 0 if no drift, 1 if drift. Read-only.')
+  .option('--show-walk', 'Print the resolved ref + the first 50 walked files BEFORE any Pinecone operations. Useful for verifying --ref / manifest source resolution.')
+  .option('--yes', 'Skip the interactive purge confirmation in --rebuild mode. Use in scripting/CI.')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+
+      const result = await corpusCommands.runCorpusSync(apiClient, options);
+      // Dry-run exit code per Deliverable A: 0 if no drift, 1 if drift would be applied.
+      if (result && result.dryRun) {
+        process.exit(result.drift ? 1 : 0);
+      }
+    } catch (error) {
+      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+corpusCommand
+  .command('status')
+  .description('Show corpus sync state (files, chunks, last sync, resolved ref)')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .option('-k, --kb <name>', 'KB name (default: all)')
+  .option('--ref <ref>', 'Preview status as if --ref were applied to a sync (does not change manifests)')
+  .option('-v, --verbose', 'Show verbose output including change detection')
   .action(async (options) => {
     try {
       let apiClient = null;
@@ -1640,48 +2361,96 @@ kbCommand
         apiClient = new DeSciXApiClient();
         await apiClient.loadCredentials();
       } catch {
-        // Continue without API client
+        // Status can work offline
       }
-      
-      await kbCommands.runKbPush(apiClient, {
-        ...options,
-        moveToProcessed: options.move !== false
-      });
+
+      await corpusCommands.runCorpusStatus(apiClient, options);
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
     }
   });
 
+// ============ KB Doctor (M3, 2026-04-20) ============
+// Compare local sync-state vs Pinecone vectorCount and scan recent sync
+// logs for per-file 0-chunk warnings. Exits non-zero on drift > threshold.
 kbCommand
-  .command('status')
-  .description('Show KB sync status (local vs Pinecone)')
+  .command('doctor')
+  .description('Detect drift between local sync-state and live Pinecone vector count')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .requiredOption('-k, --kb <name>', 'KB name')
+  .option('-t, --threshold <ratio>', 'Drift threshold as a fraction (default: 0.05)', parseFloat)
+  .option('--live', 'Compute vectorCount from the TRUE live Pinecone scope (bypass the cached counter, which lies after an interrupted op)')
+  .option('--reconcile', 'Compute the live count AND write it back to rag_vector_count so the cached read is truthful again (implies --live)')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+      await kbCommands.runKbDoctor(apiClient, options);
+    } catch (error) {
+      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
+// ============ Drive Commands ============
+
+const driveCommand = program
+  .command('drive')
+  .description('Drive content authoring: pull from Drive, push staging to Drive');
+
+driveCommand
+  .command('pull')
+  .description('Pull content from Drive and convert to local markdown')
   .option('-c, --community <id>', 'Community ID')
   .option('-a, --app <id>', 'App ID')
   .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
+  .option('--folder <id_or_url>', 'Override Drive folder (raw ID or full Drive URL) — one-time import without modifying workspace.json')
+  .option('-v, --verbose', 'Show verbose output')
+  .option('--merge-mode <mode>', 'Merge mode: merge|overwrite|force-overwrite (default: merge)')
+  .option('--dry-run', 'Show what would happen without making changes')
   .action(async (options) => {
     try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      await kbCommands.runKbStatus(apiClient, options);
+      let apiClient = null;
+      try {
+        apiClient = new DeSciXApiClient();
+        await apiClient.loadCredentials();
+      } catch {
+        // Continue without API client
+      }
+
+      await kbCommands.runKbPull(apiClient, options);
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
     }
   });
 
-kbCommand
-  .command('compare')
-  .description('Show file-level deltas between local and Drive')
+driveCommand
+  .command('push')
+  .description('Push staging files to Drive')
   .option('-c, --community <id>', 'Community ID')
   .option('-a, --app <id>', 'App ID')
   .option('-k, --kb <id>', 'Knowledge Base ID (default: General)')
-  .option('--staging', 'Only show staging → Drive delta')
-  .option('--local', 'Only show local KB ↔ Drive delta')
+  .option('-v, --verbose', 'Show verbose output')
+  .option('-i, --interactive', 'Enable interactive prompts for conflicts')
+  .option('--on-conflict <action>', 'Conflict handling: overwrite|skip (default: overwrite)')
+  .option('--no-move', 'Do not move files to .processed after upload')
+  .option('--dry-run', 'Show what would happen without making changes')
   .action(async (options) => {
     try {
-      await kbCommands.runKbCompare(null, options);
+      let apiClient = null;
+      try {
+        apiClient = new DeSciXApiClient();
+        await apiClient.loadCredentials();
+      } catch {
+        // Continue without API client
+      }
+
+      await kbCommands.runKbPush(apiClient, {
+        ...options,
+        moveToProcessed: options.move !== false
+      });
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
@@ -1712,16 +2481,16 @@ siteCommand
         process.exit(1);
       }
       
-      const appConfig = workspaceConfig.getApp(ctx.communityId, ctx.appId);
+      const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
         console.error(chalk.red('\n❌ App not found in workspace.json.'));
         console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
         process.exit(1);
       }
-      
-      const appPath = appConfig.absolutePath || 
+
+      const appPath = appConfig.absolutePath ||
         path.join(workspaceConfig.getWorkspaceRoot(), appConfig.localPath);
-      
+
       console.log(chalk.cyan('\n📁 Adding site scaffold...\n'));
       
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
@@ -1740,13 +2509,13 @@ siteCommand
     }
   });
 
-// site upload - Deploy to GCS (context-aware, replaces deploy)
+// site upload - Deploy to GCS (context-aware, manifest-aware)
 siteCommand
   .command('upload')
-  .description('Upload site to GCS and update app metadata')
+  .description('Upload site to GCS and update app metadata (uses .descix/manifests/site.json when present)')
   .option('-c, --community <id>', 'Community ID (auto-detects from context)')
   .option('-a, --app <id>', 'App ID (auto-detects from context)')
-  .option('-p, --path <localPath>', 'Local directory to deploy', './site')
+  .option('-p, --path <localPath>', 'Local directory to deploy (ignored when site manifest exists)', './site')
   .option('--preview', 'Deploy to preview path')
   .option('--full', 'Force full upload (ignore delta)')
   .option('--dry-run', 'Show what would be deployed')
@@ -1754,93 +2523,190 @@ siteCommand
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
+
+      // WS-DEPLOY-HARDENING item 7: `site upload` must never target a local backend by
+      // inheritance. detectApiUrl() checks process.env.DESCIX_API_URL first, then
+      // WorkspaceConfig.getApiUrl() (env.apiUrl, else the shipped PROD default), then
+      // GlobalConfig. `--env` and `--api-url` are folded into DESCIX_API_URL by the
+      // preAction hook BEFORE this action runs — so checking DESCIX_API_URL here reflects
+      // whether THIS invocation named its target. A workspace pinned at a local backend
+      // (env.apiUrl = https://localhost:4000) is a standing setting, not a deploy target:
+      // site deploys go to a cloud env, so that combination is a hard failure.
+      const resolvedApiUrl = await apiClient.ensureBaseUrl();
+      const isLocalApiUrl = /^https?:\/\/(localhost|127(?:\.\d{1,3}){3})(?::\d+)?/i.test(resolvedApiUrl) ||
+        /:4000(?:\/|$)/.test(resolvedApiUrl);
+      const explicitlyResolvedViaEnv = !!process.env.DESCIX_API_URL;
+      if (isLocalApiUrl && !explicitlyResolvedViaEnv) {
+        console.error(chalk.red(
+          `\n❌ Refusing site upload against a local backend (${resolvedApiUrl}). ` +
+          `Site deploys target a cloud env — pass --env=<dev|demo|prod> or export DESCIX_API_URL=https://<env>.descix.net\n`
+        ));
+        process.exit(1);
+      }
+
       await requireAuth(apiClient);
-      
+
       // Load workspace context
       const workspaceConfig = await WorkspaceConfig.load();
       const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
+
+      let communityId = ctx.communityId;
       const appId = ctx.appId;
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
+
+      if (!appId) {
+        console.error(chalk.red('\n❌ App ID required.'));
+        console.log(chalk.gray('  Either provide -a flag, or cd into an app directory\n'));
         process.exit(1);
       }
-      
-      // Import GitUtils for file hashing
-      const { GitUtils } = await import('@descix/sdk/integrations/git');
+
+      // Resolve app root from workspace config
+      const appConfig = workspaceConfig.getAppByAppId(appId);
+
+      // Derive communityId from workspace config if not provided.
+      // Fallback: for NFT apps, community_id === app_id (convention).
+      // The backend will validate this via hydrateCommunityIdFromProducts.
+      if (!communityId) {
+        communityId = appConfig?.communityId || appId;
+      }
+      const appRoot = appConfig?.absolutePath || path.resolve('.');
+
+      // Check for site manifest (.descix/manifests/site.json)
+      const { loadSiteManifest } = await import('../lib/core/ManifestLoader.js');
+      const siteManifest = await loadSiteManifest(appRoot);
+
+      // Import mime for content types
       const mime = (await import('mime-types')).default;
-      
-      const localPath = path.resolve(options.path);
-      
-      // Check if directory exists
-      try {
-        const stat = await fs.stat(localPath);
-        if (!stat.isDirectory()) {
-          throw new Error(`Path is not a directory: ${localPath}`);
+      const { GitUtils } = await import('@descix/sdk/integrations/git');
+      const gitUtils = new GitUtils(process.cwd());
+      const gitStatus = await gitUtils.getStatus();
+
+      let fileList;      // Array<{ path, hash, size, content_type }>
+      let localFiles;    // Object for delta comparison { path: { hash, size } }
+      let sourceLabel;   // For display
+
+      if (siteManifest) {
+        // ── Manifest-driven flow ──
+        const { walkSite } = await import('../lib/core/SiteWalker.js');
+
+        // Get env-specific build config from backend (GTM vars + base path)
+        const buildConfigResult = await apiClient.invoke('get_site_build_config', {
+          app_id: appId,
+          community_id: communityId
+        });
+        // Canonical-contract ferry (engineering-culture mandate 2026-06-18): the server's
+        // get_site_build_config owns the build-env schema — forward EVERY VITE_* key it
+        // returns instead of hand-mirroring the field list (drift bug class; a hand mirror
+        // silently dropped VITE_POWCH_FIRST_PARTY_ORIGINS, baking deny-by-default [] into
+        // the Powch PWA and killing the first-party email ToS auto-grant).
+        const buildEnvVars = Object.fromEntries(
+          Object.entries(buildConfigResult.message || {}).filter(([k]) => k.startsWith('VITE_'))
+        );
+        console.log(chalk.cyan(`  Build env: base=${buildConfigResult.message.VITE_BASE_PATH}, gtm=${buildConfigResult.message.VITE_GTM_ID}\n`));
+
+        // Run buildCommand if specified
+        if (siteManifest.buildCommand) {
+          if (options.dryRun) {
+            console.log(chalk.yellow(`\n  Dry run - skipping build (${siteManifest.buildCommand})`));
+            console.log(chalk.gray('  Build env vars that would be injected:'));
+            Object.entries(buildEnvVars).forEach(([k, v]) => console.log(chalk.gray(`    ${k}=${v}`)));
+          } else {
+            console.log(chalk.cyan(`\n  Running build: ${siteManifest.buildCommand}\n`));
+            const { exec } = await import('child_process');
+            const { promisify } = await import('util');
+            const execAsync = promisify(exec);
+            await execAsync(siteManifest.buildCommand, {
+              cwd: appRoot,
+              env: { ...process.env, ...buildEnvVars }
+            });
+            console.log(chalk.green('  Build completed.\n'));
+          }
         }
-      } catch (err) {
-        if (err.code === 'ENOENT') {
-          throw new Error(`Directory not found: ${localPath}`);
+
+        const walkResult = await walkSite(siteManifest, appRoot);
+        sourceLabel = `manifest (${siteManifest._manifestPath})`;
+
+        fileList = walkResult.files.map(f => ({
+          path: f.deployPath,
+          hash: f.hash,
+          size: f.size,
+          content_type: mime.lookup(f.deployPath) || 'application/octet-stream',
+          _absolutePath: f.absolutePath  // kept for upload reads
+        }));
+
+        // Build localFiles object for delta comparison
+        localFiles = {};
+        for (const f of fileList) {
+          localFiles[f.path] = { hash: f.hash, size: f.size };
         }
-        throw err;
+      } else {
+        // ── Legacy flat-directory flow (unchanged) ──
+        const localPath = path.resolve(options.path);
+        sourceLabel = localPath;
+
+        try {
+          const stat = await fs.stat(localPath);
+          if (!stat.isDirectory()) {
+            throw new Error(`Path is not a directory: ${localPath}`);
+          }
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            throw new Error(`Directory not found: ${localPath}`);
+          }
+          throw err;
+        }
+
+        const rawFiles = await gitUtils.getFileHashes(localPath);
+        localFiles = rawFiles;
+        fileList = Object.entries(rawFiles).map(([filePath, info]) => ({
+          path: filePath,
+          hash: info.hash,
+          size: info.size,
+          content_type: mime.lookup(filePath) || 'application/octet-stream',
+          _absolutePath: path.join(localPath, filePath)
+        }));
       }
-      
-      // Get Git status
-      const gitUtils = new GitUtils(process.cwd());
-      const gitStatus = await gitUtils.getStatus();
-      
-      console.log(chalk.cyan(`\n🚀 Site Upload: ${localPath} → GCS\n`));
+
+      console.log(chalk.cyan(`\n  Site Upload: ${appId} → GCS\n`));
+      console.log(chalk.gray(`  Source: ${sourceLabel}`));
       console.log(chalk.gray(`  Target: ${communityId}/${appId}`));
       if (options.preview) console.log(chalk.yellow(`  Mode: PREVIEW`));
       if (gitStatus.isGitRepo) {
         console.log(chalk.gray(`  Git: ${gitStatus.branch} @ ${gitStatus.shortHash}`));
       }
-      
-      // 1. Compute local file hashes
-      const localFiles = await gitUtils.getFileHashes(localPath);
-      const fileList = Object.entries(localFiles).map(([filePath, info]) => ({
-        path: filePath,
-        hash: info.hash,
-        size: info.size,
-        content_type: mime.lookup(filePath) || 'application/octet-stream'
-      }));
-      
+
       console.log(chalk.gray(`\n  Found ${fileList.length} files\n`));
-      
+
       if (fileList.length === 0) {
-        console.log(chalk.yellow('  No files found in directory. Nothing to deploy.\n'));
+        console.log(chalk.yellow('  No files found. Nothing to deploy.\n'));
         return;
       }
-      
+
       // 2. Request deploy token with file list
       const tokenResponse = await apiClient.invoke('get_site_deploy_token', {
         community_id: communityId,
         app_id: appId,
-        files: fileList,
+        files: fileList.map(f => ({ path: f.path, hash: f.hash, size: f.size, content_type: f.content_type })),
         preview: options.preview || false
       });
-      
-      const { signed_urls, existing_manifest, token_id, site_url } = tokenResponse.message;
-      
+
+      const { signed_urls, upload_headers, existing_manifest, token_id, site_url } = tokenResponse.message;
+
       // 3. Determine delta
       let filesToUpload = fileList;
       let filesToDelete = [];
-      
+
       if (!options.full && existing_manifest) {
         const delta = gitUtils.compareSyncState(localFiles, existing_manifest);
-        filesToUpload = fileList.filter(f => 
+        filesToUpload = fileList.filter(f =>
           delta.added.includes(f.path) || delta.modified.includes(f.path)
         );
         filesToDelete = delta.deleted;
-        
+
         console.log(chalk.gray(`  Delta: ${delta.added.length} added, ${delta.modified.length} modified, ${delta.unchanged.length} unchanged, ${delta.deleted.length} deleted`));
       }
-      
+
       if (options.dryRun) {
-        console.log(chalk.yellow('\n📋 Dry run - would upload:'));
+        console.log(chalk.yellow('\n  Dry run - would upload:'));
         if (filesToUpload.length === 0) {
           console.log(chalk.gray('  (no files to upload)'));
         } else {
@@ -1853,56 +2719,66 @@ siteCommand
         console.log(chalk.gray(`\n  Site URL: ${site_url}\n`));
         return;
       }
-      
+
       if (filesToUpload.length === 0) {
-        console.log(chalk.green('\n✅ Site already up to date on GCS.'));
+        console.log(chalk.green('\n  Site already up to date on GCS.'));
         console.log(chalk.gray('  Ensuring app metadata is synchronized...'));
-        // Fall through to confirm_site_deploy to ensure DB is updated with relative path
+        // Fall through to confirm_site_deploy to ensure DB is updated
       } else {
         // 4. Upload files directly to GCS using signed URLs
         console.log(chalk.gray(`\n  Uploading ${filesToUpload.length} files...`));
-        
+
         let uploadedCount = 0;
         let uploadErrors = [];
-        
+
         for (const file of filesToUpload) {
           const signedUrl = signed_urls[file.path];
           if (!signedUrl) {
             uploadErrors.push(`No signed URL for: ${file.path}`);
             continue;
           }
-          
+
           try {
-            const content = await fs.readFile(path.join(localPath, file.path));
-            
+            const content = await fs.readFile(file._absolutePath);
+
+            // Canonical contract (WS-DEPLOY-HARDENING item 4): the server binds Cache-Control
+            // into the v4 signed URL signature (generateSiteUploadUrls/siteAssetCacheControl).
+            // Ferry the exact header bag the server minted — never re-derive the policy
+            // client-side. A mismatched header (including a client-side --no-cache override)
+            // makes GCS return 403 signature-mismatch, so once the server ferries a bound
+            // header for this path, --no-cache is a no-op for it (falls back to legacy
+            // Content-Type-only behavior for paths the server didn't ferry a header for).
+            const ferriedHeaders = upload_headers && upload_headers[file.path];
+            const headers = ferriedHeaders || {
+              'Content-Type': file.content_type,
+              ...(options.noCache ? { 'Cache-Control': 'no-cache' } : {})
+            };
+
             const response = await fetch(signedUrl, {
               method: 'PUT',
-              headers: { 
-                'Content-Type': file.content_type,
-                ...(options.noCache ? { 'Cache-Control': 'no-cache' } : {})
-              },
+              headers,
               body: content
             });
-            
+
             if (!response.ok) {
               uploadErrors.push(`Failed to upload ${file.path}: ${response.status} ${response.statusText}`);
-              console.log(chalk.red(`  ✗ ${file.path}`));
+              console.log(chalk.red(`  x ${file.path}`));
             } else {
               uploadedCount++;
-              console.log(chalk.green(`  ✓ ${file.path}`));
+              console.log(chalk.green(`  + ${file.path}`));
             }
           } catch (err) {
             uploadErrors.push(`Error uploading ${file.path}: ${err.message}`);
-            console.log(chalk.red(`  ✗ ${file.path}`));
+            console.log(chalk.red(`  x ${file.path}`));
           }
         }
-        
+
         if (uploadErrors.length > 0) {
-          console.log(chalk.yellow(`\n⚠️  ${uploadErrors.length} errors during upload:`));
+          console.log(chalk.yellow(`\n  ${uploadErrors.length} errors during upload:`));
           uploadErrors.forEach(e => console.log(chalk.red(`  - ${e}`)));
         }
       }
-      
+
       // 5. Confirm deployment (ALWAYS call this to ensure DB is updated)
       const confirmResponse = await apiClient.invoke('confirm_site_deploy', {
         community_id: communityId,
@@ -1913,7 +2789,7 @@ siteCommand
           app_id: appId,
           community_id: communityId,
           files: localFiles,
-          source_path: options.path
+          source_path: siteManifest ? 'manifest' : options.path
         },
         git_info: gitStatus.isGitRepo ? {
           commit: gitStatus.shortHash,
@@ -1921,25 +2797,25 @@ siteCommand
         } : null,
         preview: options.preview || false
       });
-      
+
       const result = confirmResponse.message;
-      
-      console.log(chalk.green(`\n✅ Site uploaded successfully!\n`));
+
+      console.log(chalk.green(`\n  Site uploaded successfully!\n`));
       console.log(chalk.cyan(`  URL: ${result.site_url}`));
       console.log(chalk.gray(`  Files: ${result.files_count}`));
       console.log(chalk.gray(`  Deployed: ${result.deployed_at}`));
       if (result.preview) {
         console.log(chalk.yellow(`  Mode: PREVIEW`));
       }
-      
+
       if (!options.preview) {
         console.log(chalk.gray(`\n  For local development, run:`));
         console.log(chalk.cyan(`    descix site servelocal <port>\n`));
       }
       console.log('');
-      
+
     } catch (error) {
-      console.error(chalk.red(`\n❌ Upload failed: ${error.message}\n`));
+      console.error(chalk.red(`\n  Upload failed: ${error.message}\n`));
       process.exit(1);
     }
   });
@@ -1954,68 +2830,61 @@ siteCommand
     try {
       const workspaceConfig = await WorkspaceConfig.load();
       const ctx = workspaceConfig.resolveContextWithOptions(options);
-      
-      const communityId = ctx.communityId;
+
       const appId = ctx.appId;
-      
-      if (!communityId || !appId) {
-        console.error(chalk.red('\n❌ Community and App ID required.'));
-        console.log(chalk.gray('  Either provide -c and -a flags, or cd into an app directory\n'));
-        process.exit(1);
-      }
-      
-      const appConfig = workspaceConfig.getApp(communityId, appId);
-      if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+
+      if (!appId) {
+        console.error(chalk.red('\n❌ App ID required.'));
+        console.log(chalk.gray('  Either provide -a flag, or cd into an app directory\n'));
         process.exit(1);
       }
-      
-      // Handle disable case
+
+      // Handle disable case — setSitePort(appId, null) removes site.port / cleans site.{}
       if (port === 'n' || port === 'N') {
-        if (appConfig.site) {
-          delete appConfig.site.port;
-          if (Object.keys(appConfig.site).length === 0) {
-            delete appConfig.site;
-          }
-        }
-        await workspaceConfig.save();
-        console.log(chalk.green(`\n✅ Local site server disabled for ${communityId}/${appId}\n`));
+        await workspaceConfig.setSitePort(appId, null);
+        console.log(chalk.green(`\n✅ Local site server disabled for ${appId}\n`));
         return;
       }
-      
-      // Handle port registration
+
+      // Handle status query (no port argument)
       if (!port) {
-        // Show current status
-        const currentPort = appConfig.site?.port;
+        const appConfig = workspaceConfig.getAppByAppId(appId);
+        if (!appConfig) {
+          console.error(chalk.red('\n❌ App not found in workspace.json.'));
+          console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+          process.exit(1);
+        }
+        // Read site.port from the live env entry (not from the constructed copy)
+        let liveEntry = null;
+        if (workspaceConfig.env?.platform?.appId === appId) {
+          liveEntry = workspaceConfig.env.platform;
+        } else if (Array.isArray(workspaceConfig.env?.products)) {
+          liveEntry = workspaceConfig.env.products.find(p => p.appId === appId) || null;
+        }
+        const currentPort = liveEntry?.site?.port;
         if (currentPort) {
           console.log(chalk.cyan(`\n📍 Local site server: port ${currentPort}`));
-          console.log(chalk.gray(`  App: ${communityId}/${appId}\n`));
+          console.log(chalk.gray(`  App: ${appId}\n`));
         } else {
           console.log(chalk.yellow(`\n⚠️  No local site server configured.`));
           console.log(chalk.gray(`  Usage: descix site servelocal <port>\n`));
         }
         return;
       }
-      
+
       const portNum = parseInt(port);
       if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
         console.error(chalk.red('\n❌ Invalid port number.\n'));
         process.exit(1);
       }
-      
-      if (!appConfig.site) appConfig.site = {};
-      appConfig.site.port = portNum;
-      if (!appConfig.site.devCommand) {
-        appConfig.site.devCommand = 'npm run dev';
-      }
-      
-      await workspaceConfig.save();
+
+      // setSitePort mutates the live env entry and saves — no stale-copy problem
+      await workspaceConfig.setSitePort(appId, portNum);
       console.log(chalk.green(`\n✅ Local site server registered!`));
       console.log(chalk.cyan(`  Port: ${portNum}`));
-      console.log(chalk.gray(`  App: ${communityId}/${appId}`));
-      console.log(chalk.gray(`\n  The PWA will proxy /apps/${communityId}/${appId}/* to localhost:${portNum}\n`));
-      
+      console.log(chalk.gray(`  App: ${appId}`));
+      console.log(chalk.gray(`\n  The gateway will proxy /p/${appId}/* to localhost:${portNum}\n`));
+
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
@@ -2221,42 +3090,99 @@ microserviceCommand
         process.exit(1);
       }
       
-      const appConfig = workspaceConfig.getApp(ctx.communityId, ctx.appId);
+      const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
         console.error(chalk.red('\n❌ App not found in workspace.json.'));
         console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
         process.exit(1);
       }
-      
-      const appPath = appConfig.absolutePath || 
+
+      const appPath = appConfig.absolutePath ||
         path.join(workspaceConfig.getWorkspaceRoot(), appConfig.localPath);
-      
+
+      // Resolve microservice port from workspace.json before scaffold copy.
+      // Hard-fail early if missing — a scaffolded microservice without a known port
+      // cannot be routed by the gateway and cannot start on a deterministic port.
+      const env = workspaceConfig.env || {};
+      let microservicePort = null;
+      if (env.platform?.appId === ctx.appId) {
+        microservicePort = env.platform?.microservice?.port || null;
+      } else if (Array.isArray(env.products)) {
+        const productEntry = env.products.find(p => p.appId === ctx.appId);
+        microservicePort = productEntry?.microservice?.port || null;
+      }
+
+      if (!microservicePort) {
+        console.error(chalk.red(`\n❌ App '${ctx.appId}' has no microservice.port in workspace.json.`));
+        console.error(chalk.red(`   A port is required so the gateway knows where to route traffic.`));
+        console.log(chalk.gray(`\n   Set it with the config verb (never hand-edit workspace.json):`));
+        console.log(chalk.gray(`     descix app set-port -a ${ctx.appId} --port <your-port>\n`));
+        process.exit(1);
+      }
+
       console.log(chalk.cyan('\n📁 Adding microservice scaffold...\n'));
-      
+
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
-      const stats = await copyScaffold('microservice', appPath, { 
-        verbose: true, 
-        force: options.force 
+      const stats = await copyScaffold('microservice', appPath, {
+        verbose: true,
+        force: options.force
       });
-      
+
       // Configuration Injection
       const microserviceDir = path.join(appPath, 'microservice');
       const defaultsPath = path.join(microserviceDir, 'defaults-config.json');
+      const manifestPath = path.join(microserviceDir, 'manifest.json');
       const overridesPath = path.join(microserviceDir, 'dev-overrides.json');
-      
-      // 1. Inject Context into defaults-config.json
+
+      // 1. Inject Context + Port into defaults-config.json
       try {
         const defaultsContent = await fs.readFile(defaultsPath, 'utf-8');
         const defaults = JSON.parse(defaultsContent);
         defaults.community_id = ctx.communityId;
         defaults.app_id = ctx.appId;
+        defaults.LOCAL_PORT = microservicePort;
         await fs.writeFile(defaultsPath, JSON.stringify(defaults, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context into defaults-config.json`));
+        console.log(chalk.gray(`  ✓ Injected context + port into defaults-config.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update defaults-config.json: ${err.message}`));
       }
-      
-      // 2. Inject Credentials into dev-overrides.json
+
+      // 1b. Claim the scaffold's package.json for THIS service.
+      // The template ships as "@descix/service-starter" — a real package name that is not
+      // this developer's. Left unclaimed, every scaffolded service on the machine reports the
+      // same identity to npm and to anything reading package.name, and `npm install` in the
+      // service resolves against a name the developer does not own.
+      try {
+        const pkgPath = path.join(microserviceDir, 'package.json');
+        const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
+        pkg.name = ctx.appId;
+        pkg.description = `${ctx.appId} microservice on the DeSciX mesh`;
+        pkg.version = '0.1.0';
+        await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        console.log(chalk.gray(`  ✓ Claimed package.json as '${ctx.appId}'`));
+      } catch (err) {
+        console.warn(chalk.yellow(`  ⚠ Could not claim package.json: ${err.message}`));
+      }
+
+      // 2. Inject Context + Port into manifest.json
+      try {
+        const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+        manifest.service.app_id = ctx.appId;
+        manifest.service.community_id = ctx.communityId;
+        manifest.service.name = ctx.appId;
+        // No domain is injected. A service does not declare its own domain — the platform derives
+        // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
+        // The literal this replaced was `${ctx.appId}.descix.net`: the PROD host, scaffolded into
+        // every service regardless of the env it would be registered against.
+        manifest.service.debugPort = microservicePort;
+        await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+        console.log(chalk.gray(`  ✓ Injected context + port into manifest.json`));
+      } catch (err) {
+        console.warn(chalk.yellow(`  ⚠ Could not update manifest.json: ${err.message}`));
+      }
+
+      // 3. Inject Credentials into dev-overrides.json
       try {
         const apiClient = new DeSciXApiClient();
         const credentials = await apiClient.loadCredentials();
@@ -2294,10 +3220,132 @@ microserviceCommand
     }
   });
 
+// microservice deploy - Cloud Run deploy (broker-first; no per-app LB for non-core apps)
+// WS-MCP-SURFACE-SPLIT §4b: this is the REAL Admin/local deploy (Admin SDK) — it stays fully
+// functional for operator/CI use (EVP/COS deploy runbooks invoke it). It is intentionally NOT
+// advertised over MCP (not mcp:true), so the PUBLIC surface sees no deploy tool. The public
+// "microservice deploy" is "coming soon" (a no-op) — satisfied here by absence from the MCP
+// listing, NOT by neutering this admin path. Do not stub this out.
+microserviceCommand
+  .command('deploy')
+  .description('[ADMIN/LOCAL] Deploy microservice to Cloud Run (uses deploy-service-env.sh; powch re-provisions platform NEG only). Public MCP deploy is coming soon; this real deploy is Admin/local-only.')
+  .option('-c, --community <id>', 'Community ID (auto-detects from context)')
+  .option('-a, --app <id>', 'App ID (auto-detects from context)')
+  .option('--env <env>', 'Target environment: dev|demo|prod')
+  .option('--dry-run', 'Print deploy plan without executing gcloud')
+  .option('--skip-register', 'Skip manifest registration after deploy (service may self-register on boot)')
+  .action(async (options, command) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+
+      const workspaceConfig = await WorkspaceConfig.load();
+      const ctx = workspaceConfig.resolveContextWithOptions(options);
+      const appId = ctx.appId;
+
+      if (!appId) {
+        console.error(chalk.red('\n❌ App ID required.'));
+        console.log(chalk.gray('  cd into an app directory, or use -a flag\n'));
+        process.exit(1);
+      }
+
+      const parentEnv = command?.parent?.opts?.()?.env;
+      const deployEnv = (options.env || parentEnv || workspaceConfig.env?.environment)?.toLowerCase();
+      if (!deployEnv || !['dev', 'demo', 'prod'].includes(deployEnv)) {
+        console.error(chalk.red('\n❌ --env is required (dev|demo|prod).'));
+        console.log(chalk.gray('  Example: descix --env demo microservice deploy -a powch\n'));
+        process.exit(1);
+      }
+
+      const workspaceRoot = workspaceConfig.getWorkspaceRoot();
+      if (!workspaceRoot) {
+        throw new Error('Could not resolve workspace root (.descix/workspace.json not found)');
+      }
+
+      const deployScript = path.join(
+        workspaceRoot,
+        'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/deploy-service-env.sh'
+      );
+
+      try {
+        await fs.access(deployScript);
+      } catch {
+        throw new Error(`Deploy script not found: ${deployScript}`);
+      }
+
+      console.log(chalk.cyan(`\n🚀 Deploying microservice: ${appId} (${deployEnv})\n`));
+      if (options.dryRun) {
+        console.log(chalk.yellow('  Dry run — gcloud deploy will not execute\n'));
+      }
+
+      const { spawnSync } = await import('child_process');
+      const result = spawnSync('bash', [deployScript, appId, deployEnv], {
+        cwd: path.dirname(deployScript),
+        env: {
+          ...process.env,
+          ECHO_MODE: options.dryRun ? 'true' : 'false'
+        },
+        stdio: 'inherit'
+      });
+
+      if (result.status !== 0) {
+        process.exit(result.status || 1);
+      }
+
+      if (options.skipRegister) {
+        console.log(chalk.gray('\n  Skipped manifest registration (--skip-register).\n'));
+        return;
+      }
+
+      const microserviceDir = workspaceConfig.getMicroservicePath(appId);
+      if (!microserviceDir) {
+        console.log(chalk.yellow('\n⚠️  Deploy complete. Run descix microservice register to register manifest.\n'));
+        return;
+      }
+
+      const manifestPath = path.join(microserviceDir, 'manifest.json');
+      try {
+        await fs.access(manifestPath);
+      } catch {
+        console.log(chalk.yellow('\n⚠️  Deploy complete. No manifest.json — run descix microservice register when ready.\n'));
+        return;
+      }
+
+      console.log(chalk.cyan('\n📦 Registering microservice manifest...\n'));
+      const registerArgs = [
+        process.argv[1],
+        'microservice',
+        'register',
+        '-m', manifestPath,
+        '-a', appId
+      ];
+      if (ctx.communityId) {
+        registerArgs.push('-c', ctx.communityId);
+      }
+
+      const registerResult = spawnSync(process.execPath, registerArgs, {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: process.env
+      });
+
+      if (registerResult.status !== 0) {
+        console.log(chalk.yellow('\n⚠️  Cloud Run deploy succeeded but manifest registration failed.'));
+        console.log(chalk.gray(`  Retry: descix microservice register -m ${manifestPath} -a ${appId}\n`));
+        process.exit(registerResult.status || 1);
+      }
+
+      console.log(chalk.green('\n✅ Microservice deploy complete (Cloud Run + manifest registration).\n'));
+    } catch (error) {
+      console.error(chalk.red(`\n❌ Deploy failed: ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // microservice register - Register with gateway
 microserviceCommand
   .command('register')
-  .description('Register microservice with gateway (requires SERVICE_README)')
+  .description('Register microservice with gateway (-r <local SERVICE_README>; git-mode only — no Drive)')
   .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)')
@@ -2366,63 +3414,23 @@ microserviceCommand
       console.log(chalk.gray(`  App: ${appId}`));
       console.log(chalk.gray(`  Commands: ${Object.keys(manifest.commands || {}).length}\n`));
       
-      // Option 1: Local README file provided via --readme
-      if (options.readme) {
-        const readmePath = path.resolve(options.readme);
-        console.log(chalk.cyan(`📄 Reading local README: ${readmePath}\n`));
-        
-        let readmeContent;
-        try {
-          readmeContent = await fs.readFile(readmePath, 'utf-8');
-        } catch (error) {
-          if (error.code === 'ENOENT') {
-            console.error(chalk.red(`❌ README file not found: ${readmePath}`));
-            process.exit(1);
-          }
-          throw new Error(`Failed to read README: ${error.message}`);
-        }
-        
-        // Register with local README content for vectorization
-        const response = await apiClient.invoke('register_service', { 
-          manifest,
-          readme_content: readmeContent
-        });
-        
-        console.log(chalk.green('✅ Microservice registered successfully!\n'));
-        console.log(chalk.cyan(`  Service: ${serviceName}`));
-        console.log(chalk.gray(`  Commands: ${Object.keys(manifest.commands || {}).length}`));
-        console.log(chalk.gray(`  README vectorized for tell_me_how discovery\n`));
-        
-      // Option 2: Check for SERVICE_README in Drive folder
-      } else if (!options.skipReadmeCheck) {
-        console.log(chalk.cyan(`🔍 Checking for ${readmeFileName} in app Drive folder...\n`));
-        
-        const checkResponse = await apiClient.invoke('check_service_readme_exists', {
-          community_id: communityId,
-          app_id: appId,
-          service_name: serviceName
-        });
-        
-        const readmeExists = checkResponse.message?.exists || checkResponse.exists || false;
-        
-        if (!readmeExists) {
-          // Output AI-friendly instructions for creating the README
-          outputServiceReadmeInstructions(serviceName, appId, communityId, manifest);
-          process.exit(1);
-        }
-        
-        console.log(chalk.green(`✅ Found ${readmeFileName}\n`));
-        
-        // Read README content from Drive
-        const readmeResponse = await apiClient.invoke('get_service_readme_content', {
-          community_id: communityId,
-          app_id: appId,
-          service_name: serviceName
-        });
+      // Option 1: Local README file provided via --readme
+      if (options.readme) {
+        const readmePath = path.resolve(options.readme);
+        console.log(chalk.cyan(`📄 Reading local README: ${readmePath}\n`));
         
-        const readmeContent = readmeResponse.message?.content || readmeResponse.content || '';
+        let readmeContent;
+        try {
+          readmeContent = await fs.readFile(readmePath, 'utf-8');
+        } catch (error) {
+          if (error.code === 'ENOENT') {
+            console.error(chalk.red(`❌ README file not found: ${readmePath}`));
+            process.exit(1);
+          }
+          throw new Error(`Failed to read README: ${error.message}`);
+        }
         
-        // Register with README content for vectorization
+        // Register with local README content for vectorization
         const response = await apiClient.invoke('register_service', { 
           manifest,
           readme_content: readmeContent
@@ -2433,9 +3441,11 @@ microserviceCommand
         console.log(chalk.gray(`  Commands: ${Object.keys(manifest.commands || {}).length}`));
         console.log(chalk.gray(`  README vectorized for tell_me_how discovery\n`));
         
-      // Option 3: Skip README check
-      } else {
-        // Skip README check - register without vectorization
+      // Option 2: Explicit skip — register without README vectorization (git-mode only).
+      // (Drive-folder README fallback removed per CEO-D-2026-06-01-MESH-AUTH-DRIVE-REMOVAL:
+      //  git corpus sync is the only canonical KB sync; -r <local README> is the only
+      //  README source. Nothing reads SERVICE_README from Drive anymore.)
+      } else if (options.skipReadmeCheck) {
         console.log(chalk.yellow('⚠️  Skipping README check (tool discovery will be limited)\n'));
         
         const response = await apiClient.invoke('register_service', { manifest });
@@ -2444,6 +3454,11 @@ microserviceCommand
         console.log(chalk.cyan(`  Service: ${serviceName}`));
         console.log(chalk.gray(`  Commands: ${Object.keys(manifest.commands || {}).length}`));
         console.log(chalk.yellow(`  ⚠️  No README - service won't appear in tell_me_how results\n`));
+        
+      // No -r and no --skip-readme-check: instruct the LOCAL README path (never Drive).
+      } else {
+        outputServiceReadmeInstructions(serviceName, appId, communityId, manifest);
+        process.exit(1);
       }
       
     } catch (error) {
@@ -2484,8 +3499,8 @@ microserviceCommand
             await fs.access(manifestPath);
           } catch {
             // If not in current directory, try to find the microservice path for detected context
-            if (ctx.communityId && ctx.appId && workspaceConfig.workspaceRoot) {
-              const appConfig = workspaceConfig.getApp(ctx.communityId, ctx.appId);
+            if (ctx.appId && workspaceConfig.workspaceRoot) {
+              const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
               if (appConfig) {
                 const microservicePath = path.join(
                   workspaceConfig.workspaceRoot, 
@@ -2694,7 +3709,7 @@ microserviceCommand
 // microservice register-delegate - Register delegate key
 microserviceCommand
   .command('register-delegate')
-  .description('Register service delegate key for Intelligent Mesh')
+  .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)')
@@ -2733,20 +3748,28 @@ microserviceCommand
       // Fetch entitlements
       const entitlementsResponse = await apiClient.invoke('fetch_my_purchases', {});
       const entitlements = entitlementsResponse.message || {};
-      const serviceSlots = entitlements.service_slots || [];
-      
+      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 service slots available.'));
-        console.log(chalk.white('   You need a "Runner NFT" or Subscription to create a service.'));
+        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
+
+      // Select slot (subscription slots only)
       let selectedSlot = serviceSlots[0];
       if (options.slot) {
-        selectedSlot = serviceSlots.find(s => (s.nft_id || s.id) === options.slot);
+        selectedSlot = serviceSlots.find(s => (s.id || s.nft_id) === options.slot);
         if (!selectedSlot) {
-          console.error(chalk.red(`❌ Slot ${options.slot} not found in your entitlements.`));
+          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);
         }
       }
@@ -2805,6 +3828,27 @@ microserviceCommand
     }
   });
 
+// microservice restart - Kill + relaunch a local microservice (DEV only)
+microserviceCommand
+  .command('restart <name>')
+  .description('Restart a local microservice (DEV only; DEMO/PROD use deploy scripts)')
+  .option('--env <env>', 'Target environment: dev | demo | prod', 'dev')
+  .action(async (name, options) => {
+    try {
+      const { restartMicroservice } = await import('../lib/commands/microservice-restart.js');
+      const { runHealth } = await import('../lib/commands/health.js');
+      await restartMicroservice({
+        name,
+        env: options.env,
+        deps: { runHealth }
+      });
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`\n${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
 // ============ Role Commands ============
 
 const roleCommand = program
@@ -2950,131 +3994,225 @@ repCommand
     }
   });
 
-// ============ Chat Session Management ============
-
-/**
- * Get interaction_id from session file
- * @param {string} communityId 
- * @param {string} appId 
- * @returns {Promise<string|null>}
- */
-async function getSessionInteractionId(communityId, appId) {
-    const sessionPath = path.join(os.homedir(), '.descix', 'sessions', `${communityId}_${appId}.json`);
-    try {
-        const data = JSON.parse(await fs.readFile(sessionPath, 'utf-8'));
-        return data.interaction_id || null;
-    } catch {
-        return null;
-    }
-}
-
-/**
- * Save interaction_id to session file
- * @param {string} communityId 
- * @param {string} appId 
- * @param {string} interactionId 
- */
-async function saveSessionInteractionId(communityId, appId, interactionId) {
-    const sessionDir = path.join(os.homedir(), '.descix', 'sessions');
-    await fs.mkdir(sessionDir, { recursive: true });
-    const sessionPath = path.join(sessionDir, `${communityId}_${appId}.json`);
-    await fs.writeFile(sessionPath, JSON.stringify({ 
-        interaction_id: interactionId, 
-        updated: Date.now() 
-    }, null, 2));
-}
-
-/**
- * Clear session file
- * @param {string} communityId 
- * @param {string} appId 
- */
-async function clearSession(communityId, appId) {
-    const sessionPath = path.join(os.homedir(), '.descix', 'sessions', `${communityId}_${appId}.json`);
-    try {
-        await fs.unlink(sessionPath);
-    } catch {
-        // File doesn't exist, that's fine
-    }
-}
-
 // ============ Chat Commands ============
 
 program
   .command('chat [question...]')
   .description('Chat with an app agent. Usage: descix chat "Your question" or descix chat -q "Your question"')
-  .option('-c, --community <id>', 'Community ID (defaults to descix)')
-  .option('-a, --app <id>', 'App ID (defaults to agent)')
+  .option('-c, --community <id>', 'Community ID (optional; server resolves it from Products)')
+  .option('-a, --app <id>', 'App ID (required unless run from inside a mapped app directory)')
   .option('-q, --question <text>', 'Question to ask (alternative to positional argument)')
-  .option('-k, --kb <id>', 'Knowledge Base ID', 'General')
+  .option('-k, --kb <id...>', 'Knowledge Base ID(s) — repeat for multi-KB, use * for all')
+  .option('--apps <ids>', 'Comma-separated app IDs for cross-app query')
+  .option('--level <n>', 'Intelligence level (1-5)', parseInt)
+  .option('--model <name>', 'Explicit model override')
+  .option('--thinking <budget>', 'Thinking token budget (-1=dynamic, 0=off, N=fixed)', parseInt)
+  .option('--tokens', 'Show token usage in response footer')
   .option('--new', 'Start a new conversation (clear session)')
   .action(async (questionArgs, options) => {
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      
+
       // Get question from positional args or -q option
       const question = options.question || (questionArgs && questionArgs.join(' '));
       if (!question) {
         console.error(chalk.red('Error: Question required. Usage: descix chat "Your question" or descix chat -q "Your question"'));
         process.exit(1);
       }
-      
-      // Auto-detect app from current directory if not specified
-      let communityId = options.community;
-      let appId = options.app;
-      
+
+      // Multi-app mode: --apps daita,unk-beast
+      if (options.apps) {
+        const appIds = options.apps.split(',').map(s => s.trim());
+        const apps = appIds.map(id => {
+          const kbNames = options.kb && !options.kb.includes('General') ? options.kb : undefined;
+          return kbNames ? { app_id: id, knowledgebase_names: kbNames } : { app_id: id };
+        });
+
+        console.log(chalk.gray(`Asking ${appIds.join(', ')}...`));
+
+        const response = await apiClient.invoke('ask_multiple_apps', {
+          apps,
+          user_input: question,
+          intelligence_level: options.level,
+          model: options.model,
+          thinking_budget: options.thinking,
+          streaming: false
+        });
+        const result = response.message || response;
+
+        console.log(chalk.green('\n\u2705 Response:\n'));
+        console.log(chalk.white(result.response || result.text || JSON.stringify(result, null, 2)));
+
+        if (result.apps_queried) {
+          console.log(chalk.cyan(`\nApps queried: ${result.apps_queried.join(', ')}`));
+        }
+
+        const sources = result.sources || [];
+        if (sources.length > 0) {
+          console.log(chalk.cyan('\n\ud83d\udcda Sources:'));
+          sources.forEach((src, i) => {
+            const fileName = src.fileName || src.file_path || src.source || src;
+            const fileId = src.fileId || src.id || '';
+            const score = src.score || src.similarity || 0;
+            const scoreStr = score ? ` (score: ${score.toFixed(3)})` : '';
+            const idStr = fileId ? ` [ID: ${fileId}]` : '';
+            console.log(chalk.gray(`   ${i + 1}. ${fileName}${idStr}${scoreStr}`));
+          });
+        }
+
+        // Token usage footer
+        if (options.tokens && result.usage) {
+          const u = result.usage;
+          const thinkStr = u.thinking_tokens ? ` + ${u.thinking_tokens} thinking` : '';
+          console.log(chalk.gray(`\n[${result.model_used || 'unknown'} | ${u.input_tokens} in + ${u.output_tokens} out${thinkStr} = ${u.total_tokens} tokens]`));
+        }
+        console.log('');
+        return;
+      }
+
+      // Single-app mode.
+      // WS-R7-PREREQS (CEO-D-2026-07-04-R7-PREREQS-RESCOPE ruling 3): the hardcoded
+      // communityId||'descix' / appId||'agent' fallbacks are REMOVED. app_id must be
+      // resolvable (flag or workspace context) — FAIL LOUD otherwise. community_id is
+      // server-authoritative: the response carries the Products-resolved value and the
+      // session file is keyed from it.
+      let communityId = options.community || null;
+      let appId = options.app || null;
+
       if (!communityId || !appId) {
         try {
-          const { PathContext } = await import('../lib/core/PathContext.js');
-          const ctx = await PathContext.tryLoad();
-          if (ctx) {
-            const detected = ctx.detectContext();
+          const wsConfig = await WorkspaceConfig.tryLoad();
+          if (wsConfig) {
+            const detected = wsConfig.detectContext();
             if (detected) {
-              communityId = communityId || detected.communityId;
-              appId = appId || detected.appId;
+              communityId = communityId || detected.communityId || null;
+              appId = appId || detected.appId || null;
             }
           }
         } catch {
-          // Fall through to defaults
+          // No workspace context — resolution below decides, no defaults
         }
       }
-      
-      // Fall back to defaults if still not set
-      communityId = communityId || 'descix';
-      appId = appId || 'agent';
-      
-      // Get session interaction_id unless --new flag
+
+      if (!appId) {
+        console.error(chalk.red(
+          'Error: no app resolved. Pass -a/--app <app_id> or run from inside an app directory ' +
+          'mapped in .descix/workspace.json. (The legacy hardcoded descix/agent fallback was ' +
+          'removed — it silently mis-keyed sessions.)'
+        ));
+        process.exit(1);
+      }
+
+      // Session continuity: exact key when the community is known client-side; otherwise
+      // the app's newest session file (app_id is globally unique) carries the thread.
       let previousInteractionId = null;
       if (!options.new) {
-        previousInteractionId = await getSessionInteractionId(communityId, appId);
+        if (communityId) {
+          previousInteractionId = await getSessionInteractionId(communityId, appId);
+        } else {
+          const sessions = await findSessionsForApp(appId);
+          if (sessions.length > 0) {
+            previousInteractionId = await getSessionInteractionId(sessions[0].communityId, appId);
+          }
+        }
       } else {
-        // Clear session if --new flag
-        await clearSession(communityId, appId);
-      }
-      
-      console.log(chalk.gray(`Asking ${communityId}/${appId}...`));
-      
-      const response = await apiClient.invoke('ask_question_to_app', {
+        await clearAppSessions(communityId, appId);
+      }
+
+      // Resolve KB param — single or multi.
+      //
+      // ws-mcp-surface-basics — ONE NORMALIZATION OWNER. `descix chat` and the
+      // ask_question_to_app MCP tool are not two backends: both invoke the SAME
+      // ask_question_to_app command over /apifront/. The only thing that had diverged was the
+      // CLIENT-SIDE default — the CLI substituted a hardcoded 'General' while MCP callers sent
+      // nothing and let the server decide. That hardcoded fallback (anti-pattern #7) is why the
+      // CLI reported "Default KB not found" against apps whose KBs are not named 'General': the
+      // CLI asserted a KB the app never had. When the caller names no KB we now send NO kb param
+      // and the server's resolver (pineconeService.resolveKbNameScope, fed by
+      // utils.DEFAULT_KNOWLEDGEBASE_NAME) is the sole owner of what "default" means.
+      const kbList = options.kb || null;
+      const useMultiKb = !!kbList && (kbList.length > 1 || kbList.includes('*'));
+
+      console.log(chalk.gray(`Asking ${communityId ? communityId + '/' : ''}${appId}...`));
+
+      const invokeParams = {
         app_id: appId,
-        knowledgebase_name: options.kb,
         user_input: question,
         previous_interaction_id: previousInteractionId,
-        streaming: false
-      });
+        streaming: false,
+        intelligence_level: options.level,
+        model: options.model,
+        thinking_budget: options.thinking,
+      };
+
+      if (useMultiKb) {
+        invokeParams.knowledgebase_names = kbList;
+      } else if (kbList) {
+        invokeParams.knowledgebase_name = kbList[0];
+      }
+
+      // Stale-thread self-heal. Exactly ONE retry, and only for the typed 400 — see
+      // isStaleThreadError and the asymmetry note above it. Anything else (including the 403
+      // "this thread is not yours") propagates untouched to the catch below, which prints it
+      // and exits non-zero.
+      let response;
+      let healedFromInteractionId = null;
+      try {
+        response = await apiClient.invoke('ask_question_to_app', invokeParams);
+      } catch (error) {
+        if (!isStaleThreadError(error, previousInteractionId)) throw error;
+
+        healedFromInteractionId = previousInteractionId;
+        await clearAppSessions(communityId, appId);
+
+        // Single retry with no thread — byte-identical to what `--new` would have sent.
+        // NO loop: if this one fails, its error propagates.
+        previousInteractionId = null;
+        invokeParams.previous_interaction_id = null;
+        response = await apiClient.invoke('ask_question_to_app', invokeParams);
+      }
+
+      // Notice goes to STDERR, deliberately. stdout stays exactly the answer (and stays
+      // valid JSON for any `--json`-style consumer), while a human at a terminal always sees
+      // it and a `| jq` pipeline can never swallow it. The user must never be left believing
+      // continuity survived when it did not.
+      if (healedFromInteractionId) {
+        console.error(chalk.yellow(
+          `Note: the previous conversation thread for ${appId} was no longer available ` +
+          `(expired or retired) — it has been discarded and a NEW thread was started. ` +
+          `This answer does not carry any earlier context.`
+        ));
+      }
+
       const result = response.message || response;
-      
-      // Save new interaction_id for next message
+
+      // Save new interaction_id for next message, keyed by the SERVER-resolved
+      // community (authoritative — Products-hydrated). Client-resolved (-c flag /
+      // workspace context) is only accepted when the server did not return one
+      // (older backend); with NEITHER available this FAILS LOUD after printing the
+      // response — the session must never be keyed under a guessed community.
       if (result.interaction_id) {
-        await saveSessionInteractionId(communityId, appId, result.interaction_id);
+        const authoritativeCommunityId = result.community_id || communityId;
+        if (!authoritativeCommunityId) {
+          console.log(chalk.white(result.response || result.text || ''));
+          console.error(chalk.red(
+            '\nError: cannot key the chat session — the server did not return community_id ' +
+            'and none was resolvable client-side. The response above was NOT session-saved. ' +
+            'Pass -c/--community, or update the backend (ask_question_to_app must return the ' +
+            'Products-resolved community_id per CEO-D-2026-07-04-R7-PREREQS-RESCOPE).'
+          ));
+          process.exit(1);
+        }
+        await saveSessionAuthoritative(authoritativeCommunityId, appId, result.interaction_id);
       }
-      
-      console.log(chalk.green('\n✅ Response:\n'));
+
+      console.log(chalk.green('\n\u2705 Response:\n'));
       console.log(chalk.white(result.response || result.text || JSON.stringify(result, null, 2)));
-      
+
       const sources = result.sources || response.sources || response.message?.sources || [];
       if (sources && sources.length > 0) {
-        console.log(chalk.cyan('\n📚 Sources:'));
+        console.log(chalk.cyan('\n\ud83d\udcda Sources:'));
         sources.forEach((src, i) => {
           const fileName = src.fileName || src.file_path || src.source || src;
           const fileId = src.fileId || src.id || '';
@@ -3084,6 +4222,14 @@ program
           console.log(chalk.gray(`   ${i + 1}. ${fileName}${idStr}${scoreStr}`));
         });
       }
+
+      // Token usage footer
+      if (options.tokens && result.usage) {
+        const u = result.usage;
+        const thinkStr = u.thinking_tokens ? ` + ${u.thinking_tokens} thinking` : '';
+        const levelStr = options.level ? `level ${options.level}` : `level ${result.usage?.intelligence_level || '2'}`;
+        console.log(chalk.gray(`\n[${result.model_used || 'unknown'} | ${levelStr} | ${u.input_tokens} in + ${u.output_tokens} out${thinkStr} = ${u.total_tokens} tokens]`));
+      }
       console.log('');
     } catch (error) {
       console.error(chalk.red(error.message));
@@ -3094,14 +4240,19 @@ program
 program
   .command('new-chat')
   .description('Clear chat session for an app (start fresh conversation)')
-  .option('-c, --community <id>', 'Community ID (defaults to descix)')
-  .option('-a, --app <id>', 'App ID (defaults to agent)')
+  .option('-c, --community <id>', 'Community ID (optional; clears only that community key)')
+  .option('-a, --app <id>', 'App ID (required)')
   .action(async (options) => {
     try {
-      const communityId = options.community || 'descix';
-      const appId = options.app || 'agent';
-      await clearSession(communityId, appId);
-      console.log(chalk.green(`Chat session cleared for ${communityId}/${appId}. Next chat will start fresh.`));
+      // WS-R7-PREREQS: hardcoded descix/agent fallbacks REMOVED — an app id is required.
+      const appId = options.app || null;
+      if (!appId) {
+        console.error(chalk.red('Error: -a/--app <app_id> is required (the legacy hardcoded descix/agent fallback was removed).'));
+        process.exit(1);
+      }
+      const cleared = await clearAppSessions(options.community || null, appId);
+      const scope = options.community ? `${options.community}/${appId}` : appId;
+      console.log(chalk.green(`Chat session cleared for ${scope} (${cleared} session file(s)). Next chat will start fresh.`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -3118,16 +4269,26 @@ program
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
       
+      // APP entitlements: use the product_type:'APP' fast-path. The no-filter call
+      // returns the STORE BUNDLE (which has no top-level `apps` key — apps are nested
+      // under each community), so `result.apps` was always undefined → "Apps (0)" even
+      // when the user holds entitlements. The fast-path returns the user's actual
+      // purchased App objects (userManagement.js fetch_my_purchases APP branch).
+      const appResp = await apiClient.invoke('fetch_my_purchases', { product_type: 'APP' });
+      const appResult = appResp.message || appResp;
+      const apps = appResult.apps || [];
+
+      // COMMUNITY entitlements: the standard call exposes the user's owned community
+      // IDs via `my_community_ids` (the top-level `communities` field is the store
+      // catalog, not the user's overlay).
       const response = await apiClient.invoke('fetch_my_purchases', {});
       const result = response.message || response;
-      
-      const communities = result.communities || [];
-      const apps = result.apps || [];
-      
+      const communityIds = result.my_community_ids || [];
+
       console.log(chalk.green('\n✅ Your Purchases:\n'));
-      console.log(chalk.cyan(`Communities (${communities.length}):`));
-      communities.forEach((c, idx) => {
-        console.log(chalk.yellow(`  ${idx + 1}. ${c.community_name} (${c.community_id})`));
+      console.log(chalk.cyan(`Communities (${communityIds.length}):`));
+      communityIds.forEach((cid, idx) => {
+        console.log(chalk.yellow(`  ${idx + 1}. ${cid}`));
       });
       console.log();
       console.log(chalk.cyan(`Apps (${apps.length}):`));
@@ -3154,7 +4315,7 @@ configCommand
     try {
       await configCommands.show();
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -3167,143 +4328,87 @@ configCommand
     try {
       await configCommands.setUrl(url, options);
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
 configCommand
   .command('init')
-  .description('Initialize configuration')
-  .option('--dev', 'Initialize for development (https://localhost:4000)')
+  .description('Initialize configuration for an environment (requires --env)')
+  // `--dev` DELETED, not deprecated: its absence meant PRODUCTION, so the most common
+  // invocation (`descix config init`) wrote a prod origin nobody named. There is no default.
+  .option('--env <name>', 'Environment to initialize: dev, demo or prod')
+  .option('--url <url>', 'Explicit origin (for a self-hosted or port-forwarded gateway)')
   .option('-g, --global', 'Save to global config (~/.descixrc)')
   .action(async (options) => {
     try {
-      const env = options.dev ? 'dev' : 'prod';
-      await configCommands.init(env, options);
+      await configCommands.init(options.env, options);
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
 configCommand
-  .command('set-sync-mode')
-  .description('Set KB sync mode for an app (git or drive)')
-  .argument('<mode>', 'Sync mode: "git" (local-first) or "drive" (PWA-first)')
-  .option('-c, --community <id>', 'Community ID')
-  .option('-a, --app <id>', 'App ID')
-  .action(async (mode, options) => {
+  .command('set-env')
+  .description('Set target environment persistently (updates workspace.json, auto-reconnects)')
+  .argument('<env>', 'Environment: dev, demo, prod, or custom name')
+  .option('-u, --url <url>', 'API URL override (for custom environments)')
+  .action(async (env, options) => {
     try {
-      await configCommands.setSyncMode(mode, options);
+      await configCommands.setEnv(env, options);
     } catch (error) {
-      console.error(chalk.red(`\n❌ ${error.message}\n`));
-      process.exit(1);
+      fail(error);
     }
   });
 
-// ============ Documentation Commands ============
-
-const docsCommand = program
-  .command('docs')
-  .description('Documentation operations');
+configCommand
+  .command('set-gateway-port')
+  .description('Set the port `descix serve` listens on (env.gateway.port)')
+  .argument('<port>', 'Port number 1-65535, or "none" to remove')
+  .action(async (port) => {
+    try {
+      await configCommands.setGatewayPort(port === 'none' ? null : port);
+    } catch (error) {
+      fail(error);
+    }
+  });
 
-docsCommand
-  .command('sync')
-  .description('Sync README/ folder to platform-docs KB for RAG search')
-  .option('--path <path>', 'Path to README folder (default: ./README)', './README')
+configCommand
+  .command('set-dev-certs')
+  .description('Point local dev servers at your own TLS cert pair (env.devCerts) — the gateway AND every app behind it')
+  .option('-d, --dir <path>', 'Directory holding cert.pem + key.pem')
+  .option('-c, --cert <path>', 'Certificate file')
+  .option('-k, --key <path>', 'Private key file')
+  .option('--clear', 'Remove the setting and fall back to the SDK-tracked SAN pair')
   .action(async (options) => {
     try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      const fs = await import('fs/promises');
-      const path = await import('path');
-      
-      const readmePath = path.resolve(options.path || './README');
-      
-      console.log(chalk.cyan(`\n📚 Syncing documentation to platform-docs KB\n`));
-      console.log(chalk.gray(`Reading from: ${readmePath}\n`));
-      
-      // Check if README folder exists
-      try {
-        const stats = await fs.stat(readmePath);
-        if (!stats.isDirectory()) {
-          throw new Error(`Path is not a directory: ${readmePath}`);
-        }
-      } catch (error) {
-        if (error.code === 'ENOENT') {
-          throw new Error(`README folder not found: ${readmePath}`);
-        }
-        throw error;
-      }
-      
-      // Recursively read all .md files
-      const files = [];
-      async function readDir(dirPath, basePath = '') {
-        const entries = await fs.readdir(dirPath, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dirPath, entry.name);
-          const relPath = path.join(basePath, entry.name);
-          
-          if (entry.isDirectory()) {
-            // Skip node_modules and .git
-            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name.startsWith('.')) {
-              continue;
-            }
-            await readDir(fullPath, relPath);
-          } else if (entry.isFile() && entry.name.endsWith('.md')) {
-            const content = await fs.readFile(fullPath, 'utf-8');
-            files.push({
-              name: entry.name,
-              path: relPath,
-              content: Buffer.from(content).toString('base64')  // Base64 encode
-            });
-          }
-        }
-      }
-      
-      await readDir(readmePath);
-      
-      if (files.length === 0) {
-        throw new Error('No .md files found in README folder');
-      }
-      
-      console.log(chalk.gray(`Found ${files.length} markdown files. Uploading...\n`));
-      
-      // Upload files to platform-docs KB
-      const response = await apiClient.invoke('upload_files_to_kb', {
-        community_id: 'descix',
-        app_id: 'platform-docs',
-        kb_id: 'General',
-        files: files
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green(`\n✅ Uploaded ${result.uploaded || 0} files\n`));
-      
-      // Sync to RAG
-      console.log(chalk.gray('Syncing to RAG vectors...\n'));
-      const syncResponse = await apiClient.invoke('sync_knowledge_base', {
-        community_id: 'descix',
-        app_id: 'platform-docs',
-        kb_id: 'General'
-      });
-      const syncResult = syncResponse.message || syncResponse;
-      
-      console.log(chalk.green('✅ Documentation synced to RAG!\n'));
-      console.log(chalk.cyan(`  Total Vectors: ${syncResult.vectorCount || result.totalVectors || 0}\n`));
-      
-      if (result.errors && result.errors.length > 0) {
-        console.log(chalk.yellow('  Errors:'));
-        result.errors.forEach(err => {
-          console.log(chalk.red(`    - ${err.file}: ${err.error}`));
-        });
-      }
-      
-      console.log(chalk.gray('\nQuery documentation with: descix rag query -c descix -a platform-docs -k General -q "your question"\n'));
-      
+      await configCommands.setDevCerts(options);
     } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
+      fail(error);
+    }
+  });
+
+configCommand
+  .command('set-powch-url')
+  .description('Set where Powch lives (env.powchUrl) — its OWN origin; Powch is cross-origin from the shell by design')
+  .argument('<url>', 'Powch origin (e.g. https://powch.dev.descix.net), or "none" to remove')
+  .action(async (url) => {
+    try {
+      await configCommands.setPowchUrl(url === 'none' ? null : url);
+    } catch (error) {
+      fail(error);
+    }
+  });
+
+configCommand
+  .command('set-site-url')
+  .description('Set the App Shell origin `descix serve` proxies / to (env.siteUrl)')
+  .argument('<url>', 'App Shell origin, or "none" to remove')
+  .action(async (url) => {
+    try {
+      await configCommands.setSiteUrl(url === 'none' ? null : url);
+    } catch (error) {
+      fail(error);
     }
   });
 
@@ -3460,8 +4565,9 @@ function outputServiceReadmeInstructions(serviceName, appId, communityId, manife
 
   console.log(chalk.white(`Your microservice needs a ${readmeFileName} file for tool discovery.
 
-📁 Required file: ${readmeFileName}
-📍 Location: Google Drive folder for app '${appId}' in community '${communityId}'
+📁 Required file: ${readmeFileName} (local file in your microservice directory)
+▶️  Pass it explicitly:  descix microservice register -r ./${readmeFileName}
+   (or re-run with --skip-readme-check to register without tool discovery)
 
 This README is vectorized and used by the \`tell_me_how\` command to help
 users and AI agents discover your service's capabilities.
@@ -3537,7 +4643,7 @@ mcpCommand
     try {
       await mcpCommands.init();
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -3549,7 +4655,7 @@ mcpCommand
     try {
       await mcpCommands.test(options);
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -3560,7 +4666,7 @@ mcpCommand
     try {
       await mcpCommands.config();
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -3571,6 +4677,66 @@ mcpCommand
     try {
       await mcpCommands.quickstart();
     } catch (error) {
+      fail(error);
+    }
+  });
+
+mcpCommand
+  .command('execute')
+  .description('Execute a registered MCP tool by name with JSON parameters')
+  .requiredOption('--tool <name>', 'Tool/command name (e.g., beast_get_initiatives, beast_update_stream)')
+  .option('--params <json>', 'JSON parameters for the tool', '{}')
+  .option('-a, --app <app_id>', 'App context (sets app_id in params if not already present)')
+  .option('--json', 'Output raw JSON response')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await apiClient.initialize();
+      await requireAuth(apiClient);
+
+      // Parse JSON params
+      let params;
+      try {
+        params = JSON.parse(options.params);
+      } catch (parseError) {
+        console.error(chalk.red(`Invalid JSON in --params: ${parseError.message}`));
+        console.error(chalk.gray('Example: --params \'{"initiative_id": "agentic-memory"}\''));
+        process.exit(1);
+      }
+
+      // Inject app_id if provided via --app flag and not already in params
+      if (options.app && !params.app_id) {
+        params.app_id = options.app;
+      }
+
+      progress(options, chalk.gray(`Executing ${options.tool}...`));
+
+      const response = await apiClient.invoke(options.tool, params);
+
+      if (options.json) {
+        // Raw JSON output for piping/scripting
+        console.log(JSON.stringify(response, null, 2));
+      } else {
+        // Human-readable output
+        const result = response.message || response;
+
+        if (result.success !== undefined) {
+          console.log(chalk.green(`\nSuccess: ${result.message || 'Command executed successfully'}`));
+        } else {
+          console.log(chalk.green('\nResult:'));
+        }
+
+        // Pretty-print the result, excluding verbose fields
+        const displayResult = typeof result === 'object' ? result : { response: result };
+        console.log(chalk.white(JSON.stringify(displayResult, null, 2)));
+      }
+
+      console.log('');
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      if (error.response) {
+        console.error(chalk.gray(JSON.stringify(error.response, null, 2)));
+      }
       process.exit(1);
     }
   });
@@ -3581,7 +4747,7 @@ program
   .command('tell-me-how')
   .description('Discover platform tools using natural language (Intelligent MCP Mesh)')
   .argument('<question>', 'What do you want to accomplish? Use natural language.')
-  .option('-s, --scope <scope>', 'Search scope: project, entitlements (default), discovery', 'entitlements')
+  .option('-s, --scope <scope>', 'Search scope (validated against the published tell_me_how enum): bootstrap, artifact, project, entitlements (default), discovery', 'entitlements')
   .option('-j, --json', 'Output raw JSON response')
   .action(async (question, options) => {
     try {
@@ -3590,52 +4756,59 @@ program
       
       const { scope, json: jsonOutput } = options;
       
-      // Validate scope
-      const validScopes = ['project', 'entitlements', 'discovery'];
+      // Validate scope against the PUBLISHED enum, never a hand-copy. This list used to be a
+      // third mirror (['project','entitlements','discovery']) of a contract owned in
+      // @descix/platform-api/mcp-tools, and on 2026-08-18 all three copies disagreed: the handler
+      // knew 6 scopes, the published enum 4, this CLI 3 — so 'artifact' and 'bootstrap' were
+      // rejected here despite working on the wire. One owner, read at runtime.
+      const { NATIVE_MCP_TOOLS } = await import('@descix/platform-api/mcp-tools');
+      const validScopes = NATIVE_MCP_TOOLS
+        .find(t => t.name === 'tell_me_how')?.inputSchema?.properties?.scope?.enum;
+      if (!Array.isArray(validScopes) || validScopes.length === 0) {
+        console.error(chalk.red("tell_me_how scope enum missing from @descix/platform-api/mcp-tools — cannot validate."));
+        process.exit(1);
+      }
       if (!validScopes.includes(scope)) {
         console.error(chalk.red(`Invalid scope '${scope}'. Must be one of: ${validScopes.join(', ')}`));
         process.exit(1);
       }
       
-      // Get project context for 'project' scope
+      // Project context for 'project' scope, read from the v2.1 workspace.
+      //
+      // This previously read `primaryCommunity`, `directoryMappings` and `defaultContext` — all
+      // v1-format keys. A v2.1 workspace ({version, workspaceRoot, type, env{...}, driveConfig})
+      // has NONE of them, so this always produced {community_ids:[], app_ids:[]} and the server
+      // rejected every call with "project scope requires project_context with community_ids or
+      // app_ids". `--scope project` was dead on this surface for exactly as long as v2.1 has been
+      // the format.
+      //
+      // v2.1 carries APP IDS ONLY (env.platform.appId, env.products[].appId) — no community ids.
+      // We therefore send app_ids alone and let the server resolve ownership from Products.
+      // Deriving a community_id by splitting an app_id would violate the platform invariant that
+      // app ids are OPAQUE to routing and lookups.
       let project_context = null;
       if (scope === 'project') {
+        let wsConfig;
         try {
           const { WorkspaceConfig } = await import('../lib/workspace-config.js');
-          const wsConfig = await WorkspaceConfig.load(process.cwd());
-          if (wsConfig) {
-            // Extract community_ids from primaryCommunity and directoryMappings
-            const communityIds = new Set();
-            const appIds = new Set();
-            
-            if (wsConfig.primaryCommunity) {
-              communityIds.add(wsConfig.primaryCommunity);
-            }
-            
-            // Extract from directoryMappings
-            for (const mapping of Object.values(wsConfig.directoryMappings || {})) {
-              if (mapping.communityId) communityIds.add(mapping.communityId);
-              if (mapping.appId) appIds.add(mapping.appId);
-            }
-            
-            // Extract from defaultContext
-            if (wsConfig.defaultContext?.communityId) {
-              communityIds.add(wsConfig.defaultContext.communityId);
-            }
-            if (wsConfig.defaultContext?.appId) {
-              appIds.add(wsConfig.defaultContext.appId);
-            }
-            
-            project_context = {
-              community_ids: Array.from(communityIds),
-              app_ids: Array.from(appIds)
-            };
-          }
+          wsConfig = await WorkspaceConfig.load(process.cwd());
         } catch (e) {
           console.error(chalk.yellow(`⚠️  Could not read .descix/workspace.json for project scope`));
           console.error(chalk.gray(`    Run 'descix init' first, or use --scope entitlements`));
           process.exit(1);
         }
+        const appIds = new Set();
+        if (wsConfig?.env?.platform?.appId) appIds.add(wsConfig.env.platform.appId);
+        for (const product of wsConfig?.env?.products || []) {
+          if (product?.appId) appIds.add(product.appId);
+        }
+        // Fail LOUD rather than sending an empty context the server can only reject.
+        if (appIds.size === 0) {
+          console.error(chalk.red("project scope: no apps found in .descix/workspace.json (env.platform.appId / env.products[].appId)."));
+          console.error(chalk.gray("    Use --scope entitlements, or add products to the workspace."));
+          process.exit(1);
+        }
+        project_context = { app_ids: Array.from(appIds) };
       }
       
       console.log(chalk.cyan(`\n🔍 Searching for tools... (scope: ${scope})\n`));
@@ -3707,78 +4880,19 @@ program
     }
   });
 
-// ============ Folder Commands ============
-
-const folderCommand = program
-  .command('folder')
-  .description('Drive folder management');
-
-folderCommand
-  .command('set')
-  .description('Set folder ID for an entity')
-  .option('--user <folderId>', 'Set user base folder')
-  .option('--community <communityId>', 'Set community folder (requires folderId positional)')
-  .option('--app <communityApp>', 'Set app folder: "community app" (requires folderId positional)')
-  .option('--kb <communityAppKb>', 'Set KB folder: "community app kb" (requires folderId positional)')
-  .argument('[folderId]', 'Folder ID (for community/app/kb)')
-  .action(async (folderId, options) => {
-    try {
-      await folderCommands.setFolder({ ...options, folderId });
-    } catch (error) {
-      process.exit(1);
-    }
-  });
-
-folderCommand
-  .command('get')
-  .description('Get folder info for an entity')
-  .option('--user', 'Get user base folder')
-  .option('--community <communityId>', 'Get community folder')
-  .option('--app <communityApp>', 'Get app folder: "community app"')
-  .option('--kb <communityAppKb>', 'Get KB folder: "community app kb"')
-  .action(async (options) => {
-    try {
-      await folderCommands.getFolder(options);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
-
-folderCommand
-  .command('allocate')
-  .description('Allocate a new folder for an entity')
-  .option('--app <communityApp>', 'Allocate app folder: "community app"')
-  .option('--kb <communityAppKb>', 'Allocate KB folder: "community app kb"')
-  .option('-n, --name <name>', 'Custom folder name')
-  .action(async (options) => {
-    try {
-      await folderCommands.allocateFolder(options);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
-
-folderCommand
-  .command('validate <folderId>')
-  .description('Validate folder access')
-  .action(async (folderId, options) => {
-    try {
-      await folderCommands.validateFolder(folderId, options);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
-
 // ============ Update Commands (Context-Driven) ============
 
 const updateCommand = program
   .command('update')
-  .description('Context-driven resource sync (auto-detects from workspace)')
-  .argument('[type]', 'Update type: app, kb, site, all (auto-detects if not specified)')
+  // `update kb` is REMOVED — kb sync has exactly one surface, `descix kb corpus sync`.
+  // `update app` and `update site` are NOT kb-sync surfaces and are untouched, so the
+  // `update` verb itself stays registered. `update all`/`auto` keep doing app and site and
+  // no longer touch the KB; they print where kb sync went rather than failing, because
+  // failing them would delete non-kb functionality this change never targeted.
+  .description('Context-driven resource sync for app and site (auto-detects from workspace). For knowledge bases use `descix kb corpus sync`.')
+  .argument('[type]', 'Update type: app, site, all (auto-detects if not specified)')
   .option('-c, --community <id>', 'Community ID (optional; app_id sufficient for Unified Registry)')
   .option('-a, --app <id>', 'App ID (globally unique; required if not in app directory)')
-  .option('--kb <name>', 'Specific KB to update (for kb type)')
-  .option('--stage1', 'KB: Local to Drive only (skip vectorization)')
   .option('--preview', 'Site: Deploy to preview URL')
   .option('--build <cmd>', 'Site: Run build command first')
   .option('--full', 'Force full sync (ignore delta)')
@@ -3790,7 +4904,7 @@ const updateCommand = program
           await updateCommands.updateApp(options);
           break;
         case 'kb':
-          await updateCommands.updateKB({ ...options, stage1Only: options.stage1 });
+          refuseRetiredKbSync('descix update kb', chalk.red);
           break;
         case 'site':
           await updateCommands.updateSite({ 
@@ -3799,14 +4913,19 @@ const updateCommand = program
           });
           break;
         case 'all':
+          console.log(chalk.gray(`  (knowledge bases are not included: use \`${CANONICAL_KB_SYNC}\`)`));
           await updateCommands.updateAll(options);
           break;
         default:
-          // Auto-detect
+          // Auto-detect. NO blanket "KBs are excluded" line here: auto resolves to exactly
+          // one target, and if that target is the KB the user gets the refusal by name.
+          // Printing the advisory first would announce an exclusion and then refuse for
+          // that exact reason — an advisory that fires on correct behaviour trains people
+          // to ignore advisories.
           await updateCommands.updateAuto(options);
       }
     } catch (error) {
-      process.exit(1);
+      fail(error);
     }
   });
 
@@ -3814,15 +4933,22 @@ const updateCommand = program
 
 program
   .command('serve')
-  .description('Start the unified local gateway (reverse-proxy for PWA, Core, Powch, microservices)')
-  .option('-p, --port <port>', 'Gateway port', '5173')
+  .description('Start the unified local gateway (one HTTPS origin: App Shell at /, your app at /p/<app>, /apifront to the API)')
+  .option('-p, --port <port>', 'Gateway port for this run (default: env.gateway.port, else 5173)')
   .option('-w, --workspace <path>', 'Workspace root override')
+  .option('--site-url <url>', 'App Shell target for this run (default: env.siteUrl, a local platform site, else the API origin)')
+  .option('-a, --app <id>', 'App to serve standalone (default: detected from the directory you are standing in)')
   .action(async (options) => {
     try {
       const { runServe } = await import('../lib/commands/serve.js');
       await runServe({
-        port: parseInt(options.port, 10),
+        // No default here: an unset flag must stay UNSET so the gateway's
+        // resolveGatewayPort can see env.gateway.port. A CLI-side default would
+        // shadow the workspace's own port — the map/server disagreement bug.
+        port: options.port !== undefined ? parseInt(options.port, 10) : undefined,
         workspaceRoot: options.workspace || process.cwd(),
+        siteUrl: options.siteUrl,
+        app: options.app,
       });
     } catch (error) {
       console.error(chalk.red('Gateway error:', error.message));
@@ -3836,7 +4962,6 @@ program
   .command('quickstart')
   .description('One-command setup: auth → workspace → agent files → MCP config')
   .option('-u, --url <url>', 'API URL override')
-  .option('--dev', 'Use development server (https://localhost:4000)')
   .action(async (options) => {
     const { generateAgentFiles, generateMcpConfig } = await import('../lib/agent-files.js');
     const { WalletFileManager } = await import('../lib/wallet-file.js');
@@ -3859,7 +4984,6 @@ program
     if (needsLogin) {
       const loginOptions = {};
       if (options.url) loginOptions.url = options.url;
-      if (options.dev) loginOptions.dev = true;
       await authCommands.loginDevice(loginOptions);
     }