@descix/cli 1.0.6 → 1.0.8

package/bin/descix.js

@@ -11,7 +11,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
-import { WorkspaceConfig, unmappedAppMessage } from '../lib/workspace-config.js';
+import { WorkspaceConfig, unmappedAppMessage, resolveWorkspacePath, TOP_LEVEL_API_URL_REMEDY } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
@@ -29,8 +29,9 @@ 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 updateCommands from '../lib/commands/update.js';
-import { registerAllRetiredKbSync, refuseRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
+// "May I prompt?" has ONE OWNER. No command in this file derives it.
+import { createPromptSession } from '../lib/interactive.js';
+import { registerAllRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
 import { runStatus } from '../lib/commands/status.js';
 import { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
@@ -38,7 +39,7 @@ 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 { isHelpInvocation, getCommandSurface, applyVisibility } from '../lib/command-visibility.js';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
@@ -97,7 +98,8 @@ program
   .description('DeSciX CLI - Unified command-line interface')
   .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)');
+  .option('--api-url <url>', 'Direct API URL override (e.g., https://demo.descix.net)')
+  .option('--admin', 'Show every command in --help, including admin-only ones (also: DESCIX_ADMIN=1). Hiding is a listing convenience only — a hidden command still runs; the server is the real gate.');
 
 // ============ Global Environment Override ============
 // Maps --env flag to DESCIX_API_URL before any command runs.
@@ -114,24 +116,27 @@ const ENV_URL_MAP = Object.fromEntries(
 // stays; the provenance is now RECORDED alongside it, in the same breath, so the owner can name
 // the actual source. Recording it here rather than deriving it in the owner keeps one owner of
 // the fact: the only code that knows a flag was passed is the code that read the flag.
-program.hook('preAction', (thisCommand) => {
-  // Read from the ROOT program, not from the action command. `--env` and `--api-url` are
-  // declared ONCE, globally, and Commander binds them to the root — an identically-named option
-  // redeclared on a subcommand is shadowed and silently never populated (measured on 1.0.4:
-  // `descix config init --env dev` reached its action with `{}` and rejected its own advertised
-  // flag). One declaration, read from where Commander actually puts it.
-  const opts = program.opts();
-
+//
+// ONE OWNER of "apply --api-url / --env to DESCIX_API_URL", called from TWO sites: the
+// `preAction` hook below (which only ever fires before an ACTION runs — never for `--help`,
+// since Commander short-circuits help before reaching any action), and the help-time admin-
+// surface bootstrap near the bottom of this file (which runs BEFORE `program.parseAsync()`, so
+// `program.opts()` is not populated yet and the two flags are read off raw argv instead). Without
+// this second call site, `descix --api-url https://X --help` silently queried the DEFAULT origin
+// for the admin-listing surface while claiming to target X — the same class of misreport
+// `resolveEffectiveOrigin` exists to end, just newly reachable through the one invocation shape
+// (`--help`) that never runs an action.
+function applyGlobalOriginOverride({ apiUrl, env }) {
   // --api-url takes highest priority
-  if (opts.apiUrl) {
-    process.env.DESCIX_API_URL = opts.apiUrl;
-    recordInvocationOrigin(opts.apiUrl, 'flagApiUrl');
+  if (apiUrl) {
+    process.env.DESCIX_API_URL = apiUrl;
+    recordInvocationOrigin(apiUrl, 'flagApiUrl');
     return;
   }
 
   // --env maps to known URLs
-  if (opts.env) {
-    const envName = opts.env.toLowerCase();
+  if (env) {
+    const envName = env.toLowerCase();
     if (!(envName in ENV_URL_MAP)) {
       // THE REFUSAL CARRIES THE CUSTOM-ENVIRONMENT PATH. This validator runs BEFORE any command
       // action, so it is now the only thing a developer typing `--env staging` ever sees — the
@@ -140,7 +145,7 @@ program.hook('preAction', (thisCommand) => {
       // names would strand every self-hosted or port-forwarded gateway with no next step, which
       // is the same dead end as a remedy string for a command that does not run.
       console.error(chalk.red(
-        `Unknown environment: ${opts.env}. Known environments: ${Object.keys(ENV_URL_MAP).join(', ')}.\n\n` +
+        `Unknown environment: ${env}. Known environments: ${Object.keys(ENV_URL_MAP).join(', ')}.\n\n` +
         'For a self-hosted or port-forwarded gateway, name it with its origin instead:\n' +
         `  descix config set-env ${envName} --url https://...`
       ));
@@ -151,6 +156,16 @@ program.hook('preAction', (thisCommand) => {
     process.env.DESCIX_API_URL = ENV_URL_MAP[envName];
     recordInvocationOrigin(ENV_URL_MAP[envName], 'flagEnv');
   }
+}
+
+program.hook('preAction', (thisCommand) => {
+  // Read from the ROOT program, not from the action command. `--env` and `--api-url` are
+  // declared ONCE, globally, and Commander binds them to the root — an identically-named option
+  // redeclared on a subcommand is shadowed and silently never populated (measured on 1.0.4:
+  // `descix config init --env dev` reached its action with `{}` and rejected its own advertised
+  // flag). One declaration, read from where Commander actually puts it.
+  const opts = program.opts();
+  applyGlobalOriginOverride({ apiUrl: opts.apiUrl, env: opts.env });
 });
 
 // ============ Authentication Commands (No Auth Required) ============
@@ -291,39 +306,15 @@ program
       // --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 });
+      const result = await runHealth({ ...options, env });
+      // A health check that reports an unhealthy service and exits 0 is not a gate.
+      if (result && result.all_healthy === false) process.exitCode = 1;
     } 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) ============
 
@@ -429,7 +420,7 @@ creditsCommand
 
 creditsCommand
   .command('grant')
-  .description('ADMIN: grant AI credits to a user')
+  .description('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')
@@ -443,7 +434,7 @@ creditsCommand
 
 creditsCommand
   .command('refund')
-  .description('ADMIN: remove AI credits from a user (e.g. after a Stripe refund)')
+  .description('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')
@@ -589,7 +580,7 @@ communityCommand
 
 communityCommand
   .command('create')
-  .description('[ADMIN] Create a new community with token contract (requires platform admin, deploys to live Polygon)')
+  .description('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')
@@ -612,11 +603,12 @@ communityCommand
       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);
+        const rl = createPromptSession({
+          what: 'descix community create',
+          destructive: true,
+          nonInteractiveForm: ['descix community create ... --yes   # deploys a REAL token contract on live Polygon']
         });
+        const answer = await rl.askRaw(chalk.yellow(`  Create community "${options.name}" with token ${tokenSymbol} on live Polygon? [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -656,7 +648,7 @@ communityCommand
 
 communityCommand
   .command('delete')
-  .description('[ADMIN] Delete a community with full cascade cleanup (all apps, KBs, vectors, GCS)')
+  .description('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)')
@@ -713,11 +705,15 @@ communityCommand
 
       // 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);
+        const rl = createPromptSession({
+          what: 'descix community delete',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            'descix community delete ... --yes   # PERMANENTLY deletes the community and every app in it'
+          ]
         });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Permanently delete community "${manifest.community_name}" and all ${manifest.app_count} app(s)? This cannot be undone. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -761,7 +757,7 @@ communityCommand
 
 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.')
+  .description('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')
@@ -803,12 +799,15 @@ communityCommand
       }
 
       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
-        ));
+        const rl = createPromptSession({
+          what: 'descix community rename',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            'descix community rename ... --yes   # re-tags vectors and DELETES the old community doc'
+          ]
+        });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Execute rename ${oldId} -> ${newId}? Re-tags ${plan.pinecone.matched} vector(s) and deletes Community/${oldId} after verifying Community/${newId}. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -1195,26 +1194,6 @@ appCommand
     }
   });
 
-appCommand
-  .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).
@@ -1349,45 +1328,6 @@ appCommand
     }
   });
 
-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);
-      }
-      
-      const response = await apiClient.invoke('update_app_metadata', {
-        community_id: communityId,
-        app_id: appId,
-        ip_site_gcs_path_url: options.url
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ CodeSite URL updated!\n'));
-      console.log(chalk.cyan(`  App: ${communityId}/${appId}`));
-      console.log(chalk.gray(`  CodeSite URL: ${options.url}\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
 
 appCommand
   .command('set-price')
@@ -1448,6 +1388,43 @@ appCommand
     }
   });
 
+appCommand
+  .command('set-listed')
+  .description('List or unlist your app in the app store (on: shown in the public store; off: not shown to non-admin visitors)')
+  .argument('<state>', 'on or off')
+  .requiredOption('-c, --community <id>', 'Community ID')
+  .requiredOption('-a, --app <id>', 'App ID')
+  .action(async (state, options) => {
+    try {
+      const wanted = { on: true, off: false }[String(state).toLowerCase()];
+      if (wanted === undefined) {
+        throw new Error(`set-listed takes 'on' or 'off', not '${state}'.`);
+      }
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+
+      const response = await apiClient.invoke('update_app', {
+        community_id: options.community,
+        app_id: options.app,
+        listed: wanted
+      });
+      const result = response.message || response;
+      // The receipt is the value the SERVER holds after the write, never the value requested.
+      const stored = result?.app?.listed;
+      if (stored !== wanted) {
+        throw new Error(`update_app returned listed=${JSON.stringify(stored)} for ${options.app}; expected ${wanted}. The store listing did not change.`);
+      }
+
+      console.log(chalk.green(`\n✅ App ${stored ? 'listed' : 'unlisted'}.\n`));
+      console.log(chalk.cyan(`  App: ${options.community}/${options.app}`));
+      console.log(chalk.gray(`  listed: ${stored}`));
+      console.log(chalk.gray('  The store view is cached for up to 5 minutes, so the change can take that long to show.\n'));
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
 appCommand
   .command('set-api-url')
   .description('Set API base URL for app\'s own backend')
@@ -1608,11 +1585,15 @@ appCommand
 
       // 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);
+        const rl = createPromptSession({
+          what: 'descix app delete',
+          destructive: true,
+          nonInteractiveForm: [
+            'Re-run with --dry-run to see the plan without changing anything.',
+            `descix app delete -a ${appId} --yes   # PERMANENTLY deletes the app (hard delete is the default; --soft only hides it)`
+          ]
         });
+        const answer = await rl.askRaw(chalk.yellow(`\n  Permanently delete ${appId}? This cannot be undone. [y/N] `));
         rl.close();
         if (answer.toLowerCase() !== 'y') {
           console.log(chalk.gray('\n  Aborted.\n'));
@@ -1742,36 +1723,49 @@ appCommand
       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.`);
-      }
+      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
 
-      // Hard-fail if path doesn't exist or is not a directory
+      // Read the RAW registry entry, never the RESOLVED one. getAppByAppId() resolves the stored
+      // localPath, so on a workspace already carrying a rejected value it throws here — before
+      // any write is attempted. That is what made this verb refuse exactly when it was needed,
+      // while the rejection told the user to fix it with the config verb and never by hand.
+      // This command is about to REPLACE that value; it has no business resolving it.
+      //
+      // Display value only. setLocalPath() is the SINGLE authority on whether the app is mapped
+      // and refuses if it is not — deciding that here as well would be two derivations of one
+      // fact, and they would not even agree: _buildAppIdMap (behind getAppEntry) requires BOTH
+      // appId and localPath, while the live-entry walk matches on appId alone.
+      const oldPath = workspaceConfig.getAppEntry(appId)?.localPath;
+
+      // VALIDATE AT THE WRITE, through the LOADER'S OWN resolver — not a second copy of its rules.
+      // If resolveWorkspacePath would reject this value on the next read, it is rejected now, and
+      // nothing reaches disk. Writing a value the loader will refuse is what bricks a workspace.
+      const absPath = resolveWorkspacePath(wsRoot, newPath, appId);
+
+      // Hard-fail if path doesn't exist or is not a directory — checked at the path the LOADER
+      // will resolve to, not at a CWD-relative path that only exists from where you happened to
+      // be standing when you typed it.
       let stat;
       try {
-        stat = await fs.stat(newPath);
+        stat = await fs.stat(absPath);
       } catch {
-        throw new Error(`Path does not exist: ${newPath}`);
+        throw new Error(
+          `Path does not exist: ${absPath}\n` +
+          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
+        );
       }
       if (!stat.isDirectory()) {
-        throw new Error(`Path is not a directory: ${newPath}`);
+        throw new Error(
+          `Path is not a directory: ${absPath}\n` +
+          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
+        );
       }
 
-      // 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);
+      // Write through the canonical setter, which covers env.platform AND env.products[]. The
+      // loop this replaces walked env.products ONLY: on the platform app it matched nothing,
+      // wrote nothing, and still printed success — a loud failure turned into a silent lie at
+      // the one entry that matters most.
+      await workspaceConfig.setLocalPath(appId, newPath);
 
       console.log(chalk.green(`\n✓ ${appId} local path updated`));
       console.log(chalk.gray(`  ${oldPath} → ${newPath}\n`));
@@ -1819,7 +1813,7 @@ appCommand
 // 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).
+// Backed by WorkspaceConfig.setMicroservicePort.
 appCommand
   .command('set-port')
   .description('Set the microservice port for a mapped app (writes env.products[<app>].microservice.port). Pass "n" to remove.')
@@ -1864,10 +1858,8 @@ appCommand
 // 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.
+// Backed by WorkspaceConfig.setStaticSite (parallel to setMicroservicePort).
+// It writes ONLY the local workspace.json site.{} slot.
 appCommand
   .command('set-site')
   .description("Set a mapped app static-site config (writes env.products[<app>].site.static, the relative dir served at /p/<app>/). Optionally --port; --unset clears site.{}.")
@@ -2090,32 +2082,6 @@ KB's vectors by id-prefix). The Source column shows how each count was obtained:
     }
   });
 
-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')
-  .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
-      });
-      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(error.message));
-      process.exit(1);
-    }
-  });
 
 kbCommand
   .command('delete')
@@ -2485,7 +2451,7 @@ driveCommand
 
 const siteCommand = program
   .command('site')
-  .description('Site lifecycle management: init, upload, servelocal');
+  .description('Site lifecycle management: init, upload, status, list, delete');
 
 // site init - Copy scaffold to app
 siteCommand
@@ -2541,8 +2507,7 @@ siteCommand
   .option('-a, --app <id>', 'App ID (auto-detects from context)')
   .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')
+  .option('--dry-run', 'Show what would be uploaded and which server files would be removed')
   .option('--no-cache', 'Set Cache-Control: no-cache')
   .action(async (options) => {
     try {
@@ -2715,92 +2680,76 @@ siteCommand
 
       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 =>
-          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`));
-      }
+      // 3. A deploy REPLACES the site: every file of this build is uploaded, and on confirm the
+      // server deletes every site file this build does not contain (confirm_site_deploy).
+      const filesToUpload = fileList;
 
       if (options.dryRun) {
         console.log(chalk.yellow('\n  Dry run - would upload:'));
-        if (filesToUpload.length === 0) {
-          console.log(chalk.gray('  (no files to upload)'));
-        } else {
-          filesToUpload.forEach(f => console.log(chalk.gray(`  + ${f.path} (${(f.size / 1024).toFixed(1)}KB)`)));
-        }
-        if (filesToDelete.length > 0) {
-          console.log(chalk.yellow('\nWould delete:'));
-          filesToDelete.forEach(f => console.log(chalk.gray(`  - ${f}`)));
+        filesToUpload.forEach(f => console.log(chalk.gray(`  + ${f.path} (${(f.size / 1024).toFixed(1)}KB)`)));
+        // The server's last deploy manifest names what it holds; the confirm step lists the
+        // storage prefix itself, so this preview is the manifest's view of what would go.
+        const lastDeployed = Object.keys(existing_manifest?.files || {});
+        const wouldRemove = lastDeployed.filter(p => !(p in localFiles)).sort();
+        if (wouldRemove.length > 0) {
+          console.log(chalk.yellow('\n  Would remove from the server (in the last deploy, not in this build):'));
+          wouldRemove.forEach(f => console.log(chalk.gray(`  - ${f}`)));
         }
         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.gray('  Ensuring app metadata is synchronized...'));
-        // 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...`));
+      // 4. Upload files directly to GCS using signed URLs
+      console.log(chalk.gray(`\n  Uploading ${filesToUpload.length} files...`));
 
-        let uploadedCount = 0;
-        let uploadErrors = [];
+      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;
-          }
+      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(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,
-              body: content
-            });
+        try {
+          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' } : {})
+          };
 
-            if (!response.ok) {
-              uploadErrors.push(`Failed to upload ${file.path}: ${response.status} ${response.statusText}`);
-              console.log(chalk.red(`  x ${file.path}`));
-            } else {
-              uploadedCount++;
-              console.log(chalk.green(`  + ${file.path}`));
-            }
-          } catch (err) {
-            uploadErrors.push(`Error uploading ${file.path}: ${err.message}`);
+          const response = await fetch(signedUrl, {
+            method: 'PUT',
+            headers,
+            body: content
+          });
+
+          if (!response.ok) {
+            uploadErrors.push(`Failed to upload ${file.path}: ${response.status} ${response.statusText}`);
             console.log(chalk.red(`  x ${file.path}`));
+          } else {
+            uploadedCount++;
+            console.log(chalk.green(`  + ${file.path}`));
           }
+        } catch (err) {
+          uploadErrors.push(`Error uploading ${file.path}: ${err.message}`);
+          console.log(chalk.red(`  x ${file.path}`));
         }
+      }
 
-        if (uploadErrors.length > 0) {
-          console.log(chalk.yellow(`\n  ${uploadErrors.length} errors during upload:`));
-          uploadErrors.forEach(e => console.log(chalk.red(`  - ${e}`)));
-        }
+      if (uploadErrors.length > 0) {
+        uploadErrors.forEach(e => console.log(chalk.red(`  - ${e}`)));
+        throw new Error(`${uploadErrors.length} of ${filesToUpload.length} files failed to upload. The deploy was not confirmed and nothing was removed from the server.`);
       }
 
       // 5. Confirm deployment (ALWAYS call this to ensure DB is updated)
@@ -2827,6 +2776,12 @@ siteCommand
       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}`));
+      const pruned = Array.isArray(result.pruned_files) ? result.pruned_files : null;
+      if (pruned === null) {
+        throw new Error('confirm_site_deploy returned no pruned_files list: this server does not replace the site on deploy, so files from earlier builds may still be served.');
+      }
+      console.log(chalk.gray(`  Removed from the server: ${pruned.length}`));
+      pruned.forEach(f => console.log(chalk.gray(`    - ${f}`)));
       console.log(chalk.gray(`  Deployed: ${result.deployed_at}`));
       if (result.preview) {
         console.log(chalk.yellow(`  Mode: PREVIEW`));
@@ -2834,7 +2789,7 @@ siteCommand
 
       if (!options.preview) {
         console.log(chalk.gray(`\n  For local development, run:`));
-        console.log(chalk.cyan(`    descix site servelocal <port>\n`));
+        console.log(chalk.cyan(`    descix serve --app ${appId}\n`));
       }
       console.log('');
 
@@ -2844,75 +2799,6 @@ siteCommand
     }
   });
 
-// site servelocal - Register local dev server port
-siteCommand
-  .command('servelocal [port]')
-  .description('Register local dev server port (or "n" to disable)')
-  .option('-c, --community <id>', 'Community ID (auto-detects from context)')
-  .option('-a, --app <id>', 'App ID (auto-detects from context)')
-  .action(async (port, options) => {
-    try {
-      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('  Either provide -a flag, or cd into an app directory\n'));
-        process.exit(1);
-      }
-
-      // Handle disable case — setSitePort(appId, null) removes site.port / cleans site.{}
-      if (port === 'n' || port === 'N') {
-        await workspaceConfig.setSitePort(appId, null);
-        console.log(chalk.green(`\n✅ Local site server disabled for ${appId}\n`));
-        return;
-      }
-
-      // Handle status query (no port argument)
-      if (!port) {
-        const appConfig = workspaceConfig.getAppByAppId(appId);
-        if (!appConfig) {
-          console.error(chalk.red(`\n❌ ${unmappedAppMessage(appId)}\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: ${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);
-      }
-
-      // 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: ${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);
-    }
-  });
 
 // site list - List deployed files (context-aware)
 siteCommand
@@ -3049,15 +2935,13 @@ siteCommand
       }
       
       if (!options.confirm) {
-        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⚠️  Delete site for ${communityId}/${appId}${options.preview ? ' (preview)' : ''}? (y/N) `), resolve);
+        const rl = createPromptSession({
+          what: 'descix site delete',
+          destructive: true,
+          nonInteractiveForm: [`descix site delete -c ${communityId} -a ${appId} --confirm   # deletes the uploaded site files`]
         });
+
+        const answer = await rl.askRaw(chalk.yellow(`\n⚠️  Delete site for ${communityId}/${appId}${options.preview ? ' (preview)' : ''}? (y/N) `));
         rl.close();
         
         if (answer.toLowerCase() !== 'y') {
@@ -3243,127 +3127,6 @@ 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
@@ -3707,7 +3470,7 @@ microserviceCommand
 // microservice reload - Reload manifests (admin)
 microserviceCommand
   .command('reload')
-  .description('Reload microservice manifests (admin only)')
+  .description('Reload microservice manifests')
   .action(async () => {
     try {
       const apiClient = new DeSciXApiClient();
@@ -3977,45 +3740,6 @@ program
     }
   });
 
-const repCommand = program
-  .command('rep')
-  .description('Reputation operations');
-
-repCommand
-  .command('grant')
-  .description('Grant REP points to a user (admin/dev only)')
-  .requiredOption('-c, --community <id>', 'Community ID')
-  .requiredOption('-u, --user <id>', 'User ID')
-  .requiredOption('-a, --amount <amount>', 'REP amount to grant')
-  .option('--reason <text>', 'Reason for granting REP')
-  .action(async (options) => {
-    try {
-      const apiClient = new DeSciXApiClient();
-      await requireAuth(apiClient);
-      
-      const amount = parseInt(options.amount);
-      if (isNaN(amount) || amount <= 0) {
-        throw new Error('Amount must be a positive integer');
-      }
-      
-      const response = await apiClient.invoke('increment_rep', {
-        community_id: options.community,
-        user_id: options.user,
-        amount: amount,
-        reason: options.reason || 'CLI grant'
-      });
-      const result = response.message || response;
-      
-      console.log(chalk.green('\n✅ REP granted!\n'));
-      console.log(chalk.cyan(`  User: ${options.user}`));
-      console.log(chalk.gray(`  Community: ${options.community}`));
-      console.log(chalk.gray(`  Amount: +${amount} REP`));
-      console.log(chalk.gray(`  New Total: ${result.new_total || result.rep || 'N/A'}\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
 
 // ============ Chat Commands ============
 
@@ -4342,17 +4066,22 @@ configCommand
     }
   });
 
+// `config set-url` is RETIRED, and it is retired LOUDLY rather than deleted outright: a deleted
+// subcommand only earns commander's "unknown command", which names no replacement. It used to
+// assign a top-level `apiUrl` that save() never serialized, then print a success banner over a
+// value that landed nowhere — the file was re-stamped and the origin never moved. Hidden from
+// --help; any invocation exits non-zero naming the three surfaces that actually set the origin.
 configCommand
-  .command('set-url')
-  .description('Set API URL')
-  .argument('<url>', 'API URL (e.g., https://localhost:4000)')
-  .option('-g, --global', 'Save to global config (~/.descixrc)')
-  .action(async (url, options) => {
-    try {
-      await configCommands.setUrl(url, options);
-    } catch (error) {
-      fail(error);
-    }
+  .command('set-url', { hidden: true })
+  .description('retired — see error text')
+  .argument('[url]')
+  .allowUnknownOption()
+  .action(() => {
+    fail(new Error(
+      '"descix config set-url" is retired: it never wrote the origin it reported (a retired top-level\n' +
+      'key that nothing reads). Set the API origin where it is read, env.apiUrl, with one of:\n' +
+      `  ${TOP_LEVEL_API_URL_REMEDY}`
+    ));
   });
 
 configCommand
@@ -4661,57 +4390,12 @@ program
 
 // ============ MCP Commands ============
 
-import * as mcpCommands from '../lib/commands/mcp.js';
 import { runClone } from '../lib/commands/clone.js';
 
 const mcpCommand = program
   .command('mcp')
   .description('MCP server operations');
 
-mcpCommand
-  .command('init')
-  .description('Initialize MCP server for this workspace')
-  .action(async () => {
-    try {
-      await mcpCommands.init();
-    } catch (error) {
-      fail(error);
-    }
-  });
-
-mcpCommand
-  .command('test')
-  .description('Test MCP server with a sample query')
-  .option('-q, --query <text>', 'Test query', 'What is this knowledge base about?')
-  .action(async (options) => {
-    try {
-      await mcpCommands.test(options);
-    } catch (error) {
-      fail(error);
-    }
-  });
-
-mcpCommand
-  .command('config')
-  .description('Show current workspace configuration')
-  .action(async () => {
-    try {
-      await mcpCommands.config();
-    } catch (error) {
-      fail(error);
-    }
-  });
-
-mcpCommand
-  .command('quickstart')
-  .description('One-command setup: authenticate, configure, and test')
-  .action(async () => {
-    try {
-      await mcpCommands.quickstart();
-    } catch (error) {
-      fail(error);
-    }
-  });
 
 mcpCommand
   .command('execute')
@@ -4825,8 +4509,12 @@ program
           const { WorkspaceConfig } = await import('../lib/workspace-config.js');
           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`));
+          // RELAY the loader's own diagnosis; do not re-derive a remedy here. This site used to
+          // print "Run 'descix init' first" for EVERY failure, including a corrupt-but-present
+          // workspace.json — prescribing an overwrite of the file it had just failed to read,
+          // and discarding the loader's message that said exactly what was wrong.
+          console.error(chalk.red(e.message));
+          console.error(chalk.gray(`    Or use --scope entitlements, which needs no workspace.`));
           process.exit(1);
         }
         const appIds = new Set();
@@ -4912,55 +4600,6 @@ program
     }
   });
 
-// ============ Update Commands (Context-Driven) ============
-
-const updateCommand = program
-  .command('update')
-  // `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('--preview', 'Site: Deploy to preview URL')
-  .option('--build <cmd>', 'Site: Run build command first')
-  .option('--full', 'Force full sync (ignore delta)')
-  .option('--port <number>', 'Site: Register local dev server port')
-  .action(async (type, options) => {
-    try {
-      switch (type) {
-        case 'app':
-          await updateCommands.updateApp(options);
-          break;
-        case 'kb':
-          refuseRetiredKbSync('descix update kb', chalk.red);
-          break;
-        case 'site':
-          await updateCommands.updateSite({ 
-            ...options,
-            port: options.port ? parseInt(options.port) : undefined
-          });
-          break;
-        case 'all':
-          console.log(chalk.gray(`  (knowledge bases are not included: use \`${CANONICAL_KB_SYNC}\`)`));
-          await updateCommands.updateAll(options);
-          break;
-        default:
-          // 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) {
-      fail(error);
-    }
-  });
-
 // ============ Local Gateway Command ============
 
 program
@@ -5019,29 +4658,53 @@ program
       await authCommands.loginDevice(loginOptions);
     }
 
-    // Step 2: Workspace init — create workspace.json if missing
-    const wsConfigPath = path.join(workspaceRoot, '.descix', 'workspace.json');
-    let hasWorkspace = false;
-    try {
-      await fs.access(wsConfigPath);
-      hasWorkspace = true;
+    // Step 2: Workspace init — create workspace.json only when there is none ANYWHERE UP THE TREE.
+    //
+    // WHERE THE WORKSPACE ROOT IS has ONE OWNER: WorkspaceConfig.findWorkspaceRoot, which walks UP
+    // exactly as load() does. This step used to derive it a THIRD time with fs.access on the target
+    // path only (the wizard guard was the second). Run from a SUBDIRECTORY of an existing
+    // workspace, that check saw nothing, runInit created a NESTED workspace.json whose
+    // workspaceRoot pointed at the subdirectory, and it SHADOWED the parent for every later
+    // resolution — silently, with "Quickstart complete!" and exit 0.
+    //
+    // quickstart is an ONBOARDING flow: a user who asked to be set up and already IS set up has
+    // SUCCEEDED, so this SKIPS and REPORTS and continues.
+    const existingRoot = await WorkspaceConfig.findWorkspaceRoot(workspaceRoot);
+    if (existingRoot) {
       console.log(chalk.green('✓ Workspace already initialized'));
-    } catch { /* missing */ }
-
-    if (!hasWorkspace) {
+      if (path.resolve(existingRoot) !== path.resolve(workspaceRoot)) {
+        console.log(chalk.gray(`  Workspace root: ${existingRoot}`));
+        console.log(chalk.gray(`  You are in a subdirectory of it. Not creating a second workspace`));
+        console.log(chalk.gray(`  here — a nested one would shadow the root for every command run`));
+        console.log(chalk.gray(`  from this directory.`));
+      }
+    } else {
       console.log(chalk.cyan('\n📋 Initialize Workspace\n'));
-      await runInit({ path: workspaceRoot });
+      // runInit's signature is (apiClient, options). Passing a single object put it in the
+      // apiClient slot and left options defaulting to {}, so `path` was silently discarded and
+      // runInit fell back to process.cwd(). It was MASKED here only because workspaceRoot IS
+      // process.cwd() in this action — the argument was in the wrong slot regardless, and would
+      // have written the workspace to the wrong directory the moment that stopped being true.
+      // This action has no apiClient of its own; null is passed explicitly rather than implied.
+      await runInit(null, { path: workspaceRoot });
     }
 
+    // EVERY REMAINING STEP TARGETS THE RESOLVED ROOT, not the directory the command was typed in.
+    // They read the workspace to learn the app, community and origin they must state, so pointing
+    // them at a subdirectory that deliberately has no workspace.json makes them hard-fail on the
+    // absence this command just chose to preserve. Resolving the root once and ferrying it is the
+    // same one-owner rule that fixed the check above.
+    const targetRoot = existingRoot || workspaceRoot;
+
     // Step 3: Generate agent instruction files
     console.log(chalk.cyan('\n📋 Generating Agent Instructions\n'));
-    const written = await generateAgentFiles(workspaceRoot);
+    const written = await generateAgentFiles(targetRoot);
     for (const f of written) {
       console.log(chalk.green(`  ✓ ${f}`));
     }
 
     // Step 4: Generate .vscode/mcp.json (skipped if DeSciX extension handles MCP)
-    const mcpWritten = await generateMcpConfig(workspaceRoot);
+    const mcpWritten = await generateMcpConfig(targetRoot);
     if (mcpWritten) {
       console.log(chalk.green('  ✓ .vscode/mcp.json'));
     } else {
@@ -5049,11 +4712,9 @@ program
     }
 
     // Step 5: Copy SDK assets
-    try {
-      const { pullSdkAssets } = await import('../lib/wizard/setup.js');
-      const pulled = await pullSdkAssets(workspaceRoot);
-      if (pulled) console.log(chalk.green('  ✓ .descix/sdk-assets/'));
-    } catch { /* setup.js pullSdkAssets may not be exported — skip */ }
+    const { pullSdkAssets } = await import('../lib/sdk-assets.js');
+    await pullSdkAssets(targetRoot);
+    console.log(chalk.green('  ✓ .descix/sdk-assets/'));
 
     // Done
     console.log(chalk.green('\n✅ Quickstart complete!\n'));
@@ -5076,11 +4737,69 @@ program
     }
   });
 
+// ============ Public-vs-admin help listing (CEO ruling, see lib/command-visibility.js) ============
+//
+// The class comes from the server (`get_command_surface`, guest-allowed) at the moment help is
+// about to render — never a committed table. Only a help-rendering invocation pays the network
+// cost: isHelpInvocation() is a fast, offline, syntactic check (no parsing, no I/O) so every
+// ordinary command keeps running at today's speed. `--admin` / `DESCIX_ADMIN=1` skip this
+// entirely, which is what "show everything" means — nothing is ever hidden unless this block
+// explicitly hides it.
+const rawArgv = process.argv.slice(2);
+const adminMode = rawArgv.includes('--admin') || process.env.DESCIX_ADMIN === '1';
+
+/** Read `--flag <value>` or `--flag=<value>` out of raw argv, pre-parse — Commander has not run yet at this point. */
+function rawFlagValue(argv, flag) {
+  const i = argv.indexOf(flag);
+  if (i !== -1) return argv[i + 1];
+  const joined = argv.find((tok) => tok.startsWith(`${flag}=`));
+  return joined === undefined ? undefined : joined.slice(flag.length + 1);
+}
+
+if (!adminMode && isHelpInvocation(program, rawArgv, { valueFlags: ['--env', '--api-url'], booleanFlags: ['--admin'] })) {
+  // Apply --api-url / --env BEFORE constructing the client. The `preAction` hook above does the
+  // same thing but only ever fires before an ACTION runs — Commander short-circuits straight to
+  // help output without one, so for a help-rendering invocation this is the only place that
+  // ever applies these flags. Without it, `descix --api-url https://X --help` silently asked
+  // the DEFAULT origin (not X) whether each command is admin.
+  applyGlobalOriginOverride({ apiUrl: rawFlagValue(rawArgv, '--api-url'), env: rawFlagValue(rawArgv, '--env') });
+
+  // BOUNDED, regardless of what the underlying HTTP client's own timeout is: "help must stay
+  // fast" is a promise about THIS invocation, not about how patient axios feels like being
+  // against an origin that accepts the TCP connection and then never answers.
+  const SURFACE_FETCH_TIMEOUT_MS = 5000;
+  let timeoutHandle;
+  try {
+    const apiClient = new DeSciXApiClient();
+    await apiClient.ensureInitialized();
+    const { commands } = await Promise.race([
+      getCommandSurface(apiClient.baseUrl, apiClient),
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(
+          () => reject(new Error(`timed out after ${SURFACE_FETCH_TIMEOUT_MS}ms`)),
+          SURFACE_FETCH_TIMEOUT_MS
+        );
+        timeoutHandle.unref?.(); // never itself the reason the process stays alive
+      }),
+    ]);
+    applyVisibility(program, commands);
+  } catch (error) {
+    // FAIL LOUD ABOUT THE DEGRADATION, NEVER SILENTLY: help must still render (everything
+    // visible, the safe default) — offline, an old server without the command, or any other
+    // fetch failure is not a reason to hang or crash `--help`.
+    console.error(chalk.gray(
+      `(admin-only commands could not be filtered from this listing: ${error.message}. Showing everything. Use --admin to always see everything.)`
+    ));
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+
 // Parse arguments
-program.parse();
+await program.parseAsync(process.argv);
 
 // Show help if no command provided
-if (!process.argv.slice(2).length) {
+if (!rawArgv.length) {
   program.outputHelp();
 }