@descix/cli 1.0.7 → 1.0.9

package/bin/descix.js

@@ -31,8 +31,7 @@ import * as airdropCommands from '../lib/commands/airdrop.js';
 import { runInit } from '../lib/commands/init.js';
 // "May I prompt?" has ONE OWNER. No command in this file derives it.
 import { createPromptSession } from '../lib/interactive.js';
-import * as updateCommands from '../lib/commands/update.js';
-import { registerAllRetiredKbSync, refuseRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.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';
@@ -40,36 +39,13 @@ 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 { progress } from '../lib/output.js';
+import { runMediaUpload } from '../lib/commands/media-upload.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".
  *
@@ -99,7 +75,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.
@@ -116,24 +93,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
@@ -142,7 +122,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://...`
       ));
@@ -153,6 +133,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) ============
@@ -302,32 +292,6 @@ program
     }
   });
 
-// ============ 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) ============
 
@@ -433,7 +397,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')
@@ -447,7 +411,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')
@@ -593,7 +557,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')
@@ -661,7 +625,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)')
@@ -770,7 +734,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')
@@ -1207,37 +1171,14 @@ 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).
-// 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).
+// API surface (WS-V1-PURGE Phase 1, item 2; media-via-API-surface PLATFORM half). Command body
+// lives in lib/commands/media-upload.js (runMediaUpload) — see that module for the full
+// contract (server-owned quota/path/permission checks, verbatim upload_headers ferrying).
 appCommand
   .command('media-upload')
-  .description('Upload media/asset files to an app\'s GCS assets prefix via the API surface (returns asset references)')
+  .description('Upload media/asset files to an app\'s GCS assets prefix (200 MB per app today; app owners, community admins and platform admins may upload — 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")', '')
@@ -1246,160 +1187,13 @@ appCommand
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-
-      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 {
-          stat = await fs.stat(abs);
-        } catch {
-          console.error(chalk.red(`\n❌ File not found: ${abs}\n`));
-          process.exit(1);
-        }
-        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
-        });
-      }
-
-      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})`)));
-
-      // 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
-          });
-          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}`));
-        }
-      }
-
-      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}`));
-        });
-        console.log();
-      }
+      await runMediaUpload(apiClient, options);
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       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);
-      }
-      
-      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')
@@ -1460,6 +1254,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')
@@ -1848,7 +1679,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.')
@@ -1893,10 +1724,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.{}.")
@@ -2119,32 +1948,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')
@@ -2514,7 +2317,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
@@ -2570,8 +2373,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 {
@@ -2744,92 +2546,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)
@@ -2856,6 +2642,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`));
@@ -2863,7 +2655,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('');
 
@@ -2873,75 +2665,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
@@ -3270,127 +2993,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
@@ -3734,7 +3336,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();
@@ -4004,45 +3606,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 ============
 
@@ -4693,57 +4256,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')
@@ -4948,55 +4466,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
@@ -5065,9 +4534,7 @@ program
     // 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. `descix mcp quickstart` refuses non-zero
-    // on the same fact because it was asked specifically to CREATE a workspace and cannot honour
-    // that. Different verbs, different contracts, ONE OWNER for the underlying fact.
+    // SUCCEEDED, so this SKIPS and REPORTS and continues.
     const existingRoot = await WorkspaceConfig.findWorkspaceRoot(workspaceRoot);
     if (existingRoot) {
       console.log(chalk.green('✓ Workspace already initialized'));
@@ -5111,11 +4578,9 @@ program
     }
 
     // Step 5: Copy SDK assets
-    try {
-      const { pullSdkAssets } = await import('../lib/wizard/setup.js');
-      const pulled = await pullSdkAssets(targetRoot);
-      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'));
@@ -5138,11 +4603,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();
 }