@descix/cli 1.0.7 → 1.0.9

package/lib/command-visibility.js

@@ -0,0 +1,213 @@
+/**
+ * Command Visibility — the PUBLIC-vs-admin CLI help listing.
+ *
+ * CEO ruling (verbatim): "The microservice manifest consumed by DeSciX core should determine
+ * what gets exposed via MCP (and therefore CLI listing should be easily exposed there too for
+ * the core itself) - shouldn't we reuse that surface." And: "It's not a worry that admin
+ * commands can be discovered by normal users but rather we are trying to avoid the flood of
+ * noise so it is acceptable to have two lists that can be derived from the same manifest."
+ *
+ * THE CLASS COMES FROM THE SERVER AT RUNTIME (`get_command_surface`, guest-allowed) — there is
+ * NO committed class table in this repo. The only thing committed here is
+ * lib/verb-invokes.generated.json, a CLI-owned fact ("this verb invokes these commands"),
+ * regenerated by scripts/generate-verb-invokes.mjs from bin/descix.js + lib/** itself.
+ *
+ * A verb is hidden from the default listing when it invokes at least one command AND every
+ * command it invokes is classified 'admin' by the server. A verb with no recorded invokes
+ * (local-only, or a verb whose only invoke call sites are dynamic — see
+ * scripts/lib/verb-invoke-graph.mjs) stays visible: absence of information is not evidence of
+ * admin-only-ness. A GROUP (a command with children and no action of its own) is hidden when
+ * every one of its children ends up hidden — hiding is transitive up the tree, computed
+ * bottom-up from the LIVE commander tree (never a second, hand-kept tree).
+ *
+ * Hiding is LISTING ONLY. A hidden verb still EXECUTES normally when typed; the server's own
+ * permission gate (checkCommandPermission) is the actual enforcement, unchanged by this file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import VERB_INVOKES from './verb-invokes.generated.json' with { type: 'json' };
+
+const CACHE_PATH = path.join(os.homedir(), '.descix', 'command-surface-cache.json');
+/** Short TTL: this is a LISTING convenience cache, not a security boundary — a stale read only
+ * ever risks showing (or hiding) a help row for a few minutes, never changes what executes. */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * ONE explicit, CLI-owned declaration: Drive content authoring (`descix drive pull/push`) needs
+ * infrastructure admin credentials (Google ADC / a Drive service account) that `get_command_surface`
+ * has no visibility into — it is not gated by any COMMAND_PERMISSIONS entry the server classifies
+ * 'admin', so it can never be derived from the manifest. Per the CEO's ruling these stay OUT of
+ * the public CLI listing (internal Drive authoring still uses them — hidden, never deleted). The
+ * `drive` group itself is included for clarity; it would also be hidden automatically once both
+ * of its children are (see applyVisibility's group rule), but naming it here keeps this ONE set
+ * the single place that answers "why is drive hidden" rather than splitting the answer across a
+ * declaration and an inference.
+ */
+export const INFRA_ADMIN_HIDDEN_PATHS = new Set(['drive', 'drive pull', 'drive push']);
+
+/** @returns {Record<string,string[]>} the committed, generated verb -> invoked-commands map. */
+export function getVerbInvokeMap() {
+  return VERB_INVOKES;
+}
+
+/**
+ * Fetch the server's per-command visibility surface as a guest (no login needed).
+ * @param {import('./api-client.js').DeSciXApiClient} apiClient
+ * @returns {Promise<{ service: string, manifest_hash: string, commands: Record<string,'public'|'admin'> }>}
+ */
+export async function fetchCommandSurface(apiClient) {
+  const resp = await apiClient.invoke('get_command_surface', {}, { allowGuest: true });
+  const msg = resp?.message || resp;
+  if (!msg || typeof msg.commands !== 'object' || msg.commands === null) {
+    throw new Error(`get_command_surface returned an unexpected shape: ${JSON.stringify(resp)}`);
+  }
+  return msg;
+}
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(CACHE_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+async function writeCache(cache) {
+  try {
+    await fs.mkdir(path.dirname(CACHE_PATH), { recursive: true });
+    await fs.writeFile(CACHE_PATH, JSON.stringify(cache, null, 2), 'utf8');
+  } catch {
+    // Best-effort. A cache write failure must never break help output — the caller already has
+    // the freshly-fetched surface in hand and can render with it regardless.
+  }
+}
+
+/**
+ * The server surface for `origin`, from the user-level cache (keyed by origin, short TTL) when
+ * fresh, else fetched live and cached. Throws if the fetch fails (network down, old server
+ * without the command, etc.) — the caller decides what "help shows everything" means.
+ *
+ * @param {string} origin
+ * @param {import('./api-client.js').DeSciXApiClient} apiClient
+ * @returns {Promise<{ commands: Record<string,'public'|'admin'>, fromCache: boolean }>}
+ */
+export async function getCommandSurface(origin, apiClient) {
+  const cache = await readCache();
+  const entry = cache[origin];
+  if (entry && typeof entry.fetchedAt === 'number' && (Date.now() - entry.fetchedAt) < CACHE_TTL_MS) {
+    return { commands: entry.surface.commands, fromCache: true };
+  }
+  const surface = await fetchCommandSurface(apiClient);
+  cache[origin] = { surface, fetchedAt: Date.now() };
+  await writeCache(cache);
+  return { commands: surface.commands, fromCache: false };
+}
+
+/**
+ * Should a single LEAF verb (identified by its full space-joined path, e.g. "kb corpus sync") be
+ * hidden from the default listing, given the server's command->visibility surface?
+ *
+ * @param {string} verbPath
+ * @param {Record<string,'public'|'admin'>} surfaceCommands
+ * @returns {boolean}
+ */
+export function shouldHideLeaf(verbPath, surfaceCommands) {
+  if (INFRA_ADMIN_HIDDEN_PATHS.has(verbPath)) return true;
+  const invokes = VERB_INVOKES[verbPath];
+  if (!invokes || invokes.length === 0) return false; // no recorded invokes -> stays visible
+  return invokes.every((cmd) => surfaceCommands[cmd] === 'admin');
+}
+
+/**
+ * Apply hide/show to the LIVE commander tree rooted at `program`, bottom-up. Never reads or
+ * builds a second command tree — `cmd.commands` / `cmd._actionHandler` (commander's own runtime
+ * state) is the only source of "what verbs exist and how they nest", so this can never drift
+ * from the tree `--help` actually renders.
+ *
+ * @param {import('commander').Command} program
+ * @param {Record<string,'public'|'admin'>} surfaceCommands
+ */
+export function applyVisibility(program, surfaceCommands) {
+  function visit(cmd, pathTokens) {
+    const verbPath = pathTokens.join(' ');
+    const hasChildren = Array.isArray(cmd.commands) && cmd.commands.length > 0;
+    // ADDITIVE ONLY. Some commands are registered `{ hidden: true }` by the CLI itself for
+    // reasons that have nothing to do with server admin-gating — see the retired-surface
+    // registrations in lib/commands/retired-kb-sync.js, each a deliberate loud-refusal stub kept
+    // out of the default listing so it doesn't clutter it, while still working and refusing
+    // clearly when typed. This layer may HIDE a visible command; it must never REVEAL a command
+    // the CLI already chose to hide. MEASURED: an early version unconditionally overwrote
+    // `_hidden`, which un-hid a retired-surface stub the moment its verb had no generated-map
+    // entry (it invokes no /apifront command at all, so its invoke list is empty).
+    const alreadyHidden = !!cmd._hidden;
+
+    if (hasChildren) {
+      let allChildrenHidden = true;
+      for (const child of cmd.commands) {
+        const childHidden = visit(child, [...pathTokens, child.name()]);
+        if (!childHidden) allChildrenHidden = false;
+      }
+      if (pathTokens.length === 0) return false; // never hide the root program
+      if (cmd._actionHandler) {
+        // A command that is BOTH a group and its own runnable leaf (not used in this CLI today,
+        // but commander allows it) is judged as a leaf: its own invokes decide it, independent
+        // of its children.
+        const hidden = alreadyHidden || shouldHideLeaf(verbPath, surfaceCommands);
+        cmd._hidden = hidden;
+        return hidden;
+      }
+      cmd._hidden = alreadyHidden || allChildrenHidden;
+      return cmd._hidden;
+    }
+
+    if (pathTokens.length === 0) return false; // the root has no children in practice, but guard anyway
+    const hidden = alreadyHidden || shouldHideLeaf(verbPath, surfaceCommands);
+    cmd._hidden = hidden;
+    return hidden;
+  }
+  visit(program, []);
+}
+
+/**
+ * Is this invocation one that will render `--help` output? Only these fetch the network — every
+ * other invocation must stay fast and offline-safe.
+ *
+ * Recognizes: `-h` / `--help` anywhere, `help` in subcommand position, a bare invocation (no positional tokens once
+ * global flags are stripped), and a "bare group" invocation (the resolved command has children
+ * but no action handler of its own — e.g. `descix app` with no subcommand, which commander
+ * renders as help even though the CLI never called outputHelp() itself).
+ *
+ * @param {import('commander').Command} program
+ * @param {string[]} argv - process.argv.slice(2)
+ * @param {{ valueFlags?: string[], booleanFlags?: string[] }} [globalFlags]
+ * @returns {boolean}
+ */
+export function isHelpInvocation(program, argv, globalFlags = {}) {
+  if (argv.length === 0) return true;
+  if (argv.includes('-h') || argv.includes('--help')) return true;
+  if (argv.includes('-V') || argv.includes('--version')) return false; // prints a version, renders no listing
+
+  const valueFlags = new Set(globalFlags.valueFlags || []);
+  const booleanFlags = new Set(globalFlags.booleanFlags || []);
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (valueFlags.has(tok)) { i++; continue; }
+    if (booleanFlags.has(tok)) continue;
+    if (tok.startsWith('-')) continue; // an option belonging to whatever command it turns out to be
+    positional.push(tok);
+  }
+  if (positional.length === 0) return true;
+
+  let cmd = program;
+  for (const tok of positional) {
+    if (cmd._actionHandler) break; // reached a leaf; remaining tokens are ITS args, not subcommands
+    if (tok === 'help') return true; // commander's help subcommand, only in subcommand position
+    const next = (cmd.commands || []).find((c) => c.name() === tok || (c.aliases && c.aliases().includes(tok)));
+    if (!next) return false; // unresolvable path — commander's own error path, not ours to fetch for
+    cmd = next;
+  }
+  return !cmd._actionHandler;
+}

package/lib/commands/corpus.js

@@ -452,16 +452,13 @@ export async function runCorpusSync(apiClient, options) {
     const missingKbNames = requestedKbNames.filter(name => !registeredKbNames.has(name));
     if (missingKbNames.length > 0) {
       // Hard-fail: every KB we are about to sync into must already be registered in Firestore.
-      // No hardcoded fallback. `app init` is the verb that actually creates a KB on a
-      // git-mode app (init_git_mode_kb, bin/descix.js:1163). `kb create` is Drive-mode
-      // wired (create_skeleton_kb, :2087) and fails here — filed as its own defect.
+      // No hardcoded fallback. `app init --kb` is the verb that creates a KB (init_git_mode_kb).
       spinner.fail(`Unregistered KB(s) for app "${appId}"`);
       throw new Error(
         `KnowledgeBase document(s) missing in Firestore for app "${appId}": ${missingKbNames.join(', ')}.\n` +
         `Registered KBs for this app: ${[...registeredKbNames].join(', ') || '(none)'}.\n` +
         `Syncing vectors into Pinecone without a matching KB doc would orphan them (chat queries hard-fail).\n` +
-        `Fix: run \`descix app init -a ${appId}\` — it creates the KB via init_git_mode_kb and needs no Drive folder.\n` +
-        `(\`descix kb create\` currently routes through create_skeleton_kb and FAILS on a git-mode app.)`
+        `Fix: run \`descix app init -a ${appId} --kb <kb_name>\` for each missing KB — it creates the KB and needs no Drive folder.`
       );
     }
 

package/lib/commands/kb.js

@@ -179,9 +179,9 @@ export async function runKbPush(apiClient, options) {
     const onConflictPrompt = options.interactive ? async (fileName, fileInfo) => {
       spinner.stop();
       requireInteractive({
-        what: 'descix kb push --interactive',
+        what: 'descix drive push --interactive',
         question: `File "${fileName}" exists in Drive. Overwrite or skip?`,
-        nonInteractiveForm: ['descix kb push   # without --interactive, conflicts resolve without a prompt']
+        nonInteractiveForm: ['descix drive push   # without --interactive, conflicts resolve without a prompt']
       });
       const { action } = await inquirer.prompt([{
         type: 'list',

package/lib/commands/media-upload.js

@@ -0,0 +1,176 @@
+/**
+ * `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; storage-cap
+ * ferrying added WS-MEDIA-QUOTA per CEO ruling 2026-09-16: "Yes you can build with a 200MB
+ * size limit for now until we get credit based metering for more storage.").
+ *
+ * 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 server's 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). App owners, community admins and platform admins may upload — the server is the
+ * sole authority on that and on the app's storage quota (200 MB per app today; nothing here
+ * pre-validates either).
+ *
+ * SERVER IS THE SOLE AUTHORITY (super-DRY: never re-derive a server-owned fact client-side):
+ * - quota, path validity (no leading `/`, no backslash, no empty/`.`/`..` segment) and caller
+ *   permission are enforced ONLY by `get_asset_upload_token`; a refusal there throws with the
+ *   server's message verbatim (`DeSciXApiClient#invoke`) and this module does not catch it —
+ *   let it propagate so the caller prints exactly what the server said and exits non-zero.
+ * - `--prefix` is passed through UNCHANGED (no slash-stripping): stripping could silently mask
+ *   a server-side path refusal the server is best positioned to name.
+ * - Each file is PUT with the server's `upload_headers[path]` bag VERBATIM (precedent: `site
+ *   upload`'s `ferriedHeaders` — the server binds Content-Type and
+ *   `x-goog-content-length-range` into the v4 signed-URL signature, so a re-derived header
+ *   403s). Size is still read from `fs.stat`, since GCS itself rejects a body whose length
+ *   disagrees with the declared range.
+ * - `public_url` and `storage` are printed exactly as the server returned them — never
+ *   reconstructed from `bucket` + `gcs_path` (that WAS a client-side re-derivation of a server
+ *   fact; removed here rather than perpetuated).
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import chalk from 'chalk';
+import { progress } from '../output.js';
+
+/**
+ * Run `app media-upload`.
+ *
+ * @param {import('../api-client.js').DeSciXApiClient} apiClient
+ * @param {{app:string, file:string|string[], prefix?:string, json?:boolean}} options
+ * @returns {Promise<{app_id:string, assets:Array<object>, storage:object|null}>}
+ */
+export async function runMediaUpload(apiClient, options) {
+  const mime = (await import('mime-types')).default;
+
+  const appId = options.app;
+  const localFiles = Array.isArray(options.file) ? options.file : [options.file];
+  // No local normalization: a leading/trailing slash, empty segment, or `.`/`..` segment is a
+  // server-owned validity rule (get_asset_upload_token) — pass --prefix through untouched so a
+  // bad prefix surfaces as the server's own refusal, never a silently-corrected local guess.
+  const subPrefix = options.prefix || '';
+
+  // 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 {
+      throw new Error(`File not found: ${abs}`);
+    }
+    if (!stat.isFile()) {
+      throw new Error(`Not a file: ${abs}`);
+    }
+    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
+    });
+  }
+
+  progress(options, 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. The server owns quota, path
+  // validity and caller permission — a refusal here throws with the server's message verbatim
+  // and this function does not catch it.
+  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, upload_headers, objects, storage } = token;
+
+  // 2. PUT each file directly to GCS using its signed URL and the server's exact header bag.
+  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;
+    }
+    // Never re-derive Content-Type (or the length-range header) locally for the PUT — the
+    // server binds them into the v4 signature. A path the server did not ferry a header bag
+    // for is an error for that path, naming the server as the thing that is missing it.
+    const headers = upload_headers?.[f.path];
+    if (!headers) {
+      errors.push(
+        `No upload_headers for: ${f.path} (get_asset_upload_token response is missing the header ` +
+        `bag for this 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,
+        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) || {};
+        uploaded.push({
+          path: f.path,
+          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) {
+    throw new Error('No files uploaded.');
+  }
+  if (errors.length > 0) {
+    // FAIL LOUD on a partial upload: the files that went up are listed above, but a caller that
+    // reads only the exit status must not take a half-uploaded set as success.
+    throw new Error(`${errors.length} of ${fileDescriptors.length} file(s) failed to upload:\n  - ${errors.join('\n  - ')}`);
+  }
+
+  const result = { app_id: appId, assets: uploaded, storage: storage || null };
+
+  if (options.json) {
+    console.log('\n' + JSON.stringify(result, null, 2) + '\n');
+  } else {
+    console.log(chalk.green(`\n  ✅ Uploaded ${uploaded.length} asset(s).\n`));
+    console.log(chalk.cyan('  Asset references (pass the path to your app handler; the service fetches via get_app_asset):'));
+    uploaded.forEach(u => {
+      console.log(chalk.white(`    ${u.path}`));
+      console.log(chalk.gray(`      public_url: ${u.public_url}`));
+    });
+    if (result.storage) {
+      // projected_bytes is the app's total INCLUDING this upload; used_bytes is the total before it.
+      const usedMb = (result.storage.projected_bytes / (1024 * 1024)).toFixed(1);
+      const limitMb = (result.storage.limit_bytes / (1024 * 1024)).toFixed(1);
+      console.log(chalk.gray(`\n  Storage: ${usedMb} MB / ${limitMb} MB used`));
+    }
+    console.log();
+  }
+
+  return result;
+}

package/lib/commands/retired-kb-sync.js

@@ -19,20 +19,17 @@
 export const CANONICAL_KB_SYNC = 'descix kb corpus sync';
 
 /** The verb that creates a KB — `kb corpus sync`'s dependency (I4). */
-export const CANONICAL_KB_CREATE = 'descix kb create';
+export const CANONICAL_KB_CREATE = 'descix app init --kb <kb_name>';
 
 /**
  * Every KB-sync surface retired by ws-devplane-cli-kb-surface-single-canonical-sync.
  * `invocation` is what a user types; `parent` is the commander parent it hung off.
  */
 export const RETIRED_KB_SYNC_SURFACES = [
-  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync',      registered: true  },
-  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb',   registered: true  },
-  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk',  registered: true  },
-  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync',   registered: true  },
-  // registered:false -- `update` survives for app/site, so this one is a dispatcher branch
-  // inside the live `update` command rather than a commander registration of its own.
-  { id: 'update.kb', parent: 'update',  name: 'kb',    invocation: 'descix update kb', registered: false },
+  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync' },
+  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb' },
+  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk' },
+  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync' },
 ];
 
 /** Implementations deleted with those surfaces. No exported symbol survives without a caller (I3). */
@@ -61,24 +58,6 @@ export function retiredKbSyncMessage(invocation) {
   );
 }
 
-/**
- * Refuse a retired invocation LOUDLY and exit non-zero.
- *
- * MEASURED, not assumed: a `throw` from updateAuto is NOT swallowed — updateAuto's own catch
- * prints the message before rethrowing, so both forms reach the user and exit 1. This exists
- * for two smaller, real reasons: (1) ONE owner for the refusal, so the dispatcher branch and
- * updateAuto's kb branch cannot drift into different wording or different exit codes; and
- * (2) a deliberate retirement is not a crash, so it should not be framed as "✖ Update failed".
- *
- * @param {string} invocation - the retired invocation, e.g. 'descix update kb'
- * @param {(s:string)=>string} red - chalk.red or equivalent
- * @returns {never}
- */
-export function refuseRetiredKbSync(invocation, red) {
-  console.error(red(`\n❌ ${retiredKbSyncMessage(invocation)}\n`));
-  process.exit(1);
-}
-
 /**
  * Register a retired invocation so it exits NON-ZERO naming the canonical surface.
  * Accepts and ignores any args/options the old surface took, so an old script fails with
@@ -120,7 +99,6 @@ export function registerRetiredKbSync(parent, name, invocation, red) {
 export function registerAllRetiredKbSync(roots, red) {
   const byId = { ...roots };
   for (const s of RETIRED_KB_SYNC_SURFACES) {
-    if (!s.registered) continue;
     const parent = byId[s.parent];
     if (!parent) {
       throw new Error(

package/lib/commands/status.js

@@ -206,15 +206,6 @@ export async function runStatus(options = {}) {
     console.log(`Service Key:        ${chalk.gray('None')} (dev-overrides.json)`);
   }
 
-  // Check for MCP rules
-  const rulesPath = path.join(checkDir, '.cursor', 'rules', 'descix_mcp.mdc');
-  try {
-    await fs.access(rulesPath);
-    console.log(`MCP Rules:          ${chalk.green('Deployed')} (.cursor/rules/descix_mcp.mdc)`);
-  } catch {
-    console.log(`MCP Rules:          ${chalk.gray('Not Deployed')}`);
-  }
-
   // Check gcloud
   const gcloudStatus = await checkGcloud();
   if (gcloudStatus.installed) {

package/lib/output.js

@@ -0,0 +1,31 @@
+/**
+ * CLI output — ONE OWNER of the "human progress vs. --json data channel" split.
+ *
+ * Relocated from bin/descix.js (WS-MEDIA-QUOTA) so lib/commands/* modules can share it
+ * without bin/ -> lib/ layering going backwards. This is a move, not a duplication: bin/descix.js
+ * imports `progress` from here instead of defining its own copy.
+ */
+
+/**
+ * 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
+ */
+export function progress(options, ...args) {
+  if (options && options.json) console.error(...args);
+  else console.log(...args);
+}

package/lib/sdk-assets.js

@@ -0,0 +1,28 @@
+/**
+ * The SDK's agent assets (instructions, guides, reference) ship inside this package at
+ * agent-assets/. `pullSdkAssets` copies them into a workspace at .descix/sdk-assets/ so a local AI
+ * agent can read them. A missing source is a broken install and throws; it is never skipped.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+/** agent-assets/ at the package root, one level above lib/. */
+export const SDK_ASSETS_SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'agent-assets');
+
+/**
+ * Copy the package's agent-assets/ to <workspaceRoot>/.descix/sdk-assets/.
+ * @param {string} workspaceRoot
+ * @returns {Promise<string>} the target directory
+ * @throws when the package's agent-assets/ is absent or the copy fails
+ */
+export async function pullSdkAssets(workspaceRoot) {
+  const target = path.join(workspaceRoot, '.descix', 'sdk-assets');
+  try {
+    await fs.access(SDK_ASSETS_SOURCE);
+  } catch {
+    throw new Error(`SDK agent assets are missing from this install (${SDK_ASSETS_SOURCE}). Reinstall @descix/cli.`);
+  }
+  await fs.cp(SDK_ASSETS_SOURCE, target, { recursive: true });
+  return target;
+}