@descix/cli 1.0.4 → 1.0.6

package/lib/commands/doctor.js

@@ -13,7 +13,6 @@ import fs from 'fs/promises';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { DeSciXApiClient } from '../api-client.js';
-import { GlobalConfig } from '../global-config.js';
 import { isAuthenticated } from '../auth-guard.js';
 
 const execAsync = promisify(exec);
@@ -62,6 +61,28 @@ async function checkNode() {
  * Check API Connectivity
  */
 async function checkConnectivity(apiClient) {
+  // NO NETWORK VERDICT ON AN ORIGIN WE DO NOT HAVE. Measured on published 1.0.4: doctor was
+  // handed `baseUrl: globalConfig.api_url`, which is legitimately null on a machine that has
+  // never written ~/.descix/config.json, and then called `fetch(null)`. That throws, so doctor
+  // reported `[✗] API Connectivity — Unreachable / Fix: Check your internet connection.
+  // API URL: null` — UNCONFIGURED STATE MISREPORTED AS A NETWORK FAILURE, sending the developer
+  // to debug their wifi over a config fact. A red verdict on a null origin is not a measurement
+  // of anything; neither would a green one be.
+  //
+  // This is now unreachable through runDoctor, which resolves via the origin owner (never null,
+  // or a loud OriginInvalidError). It stays as a hard guard because "the caller always passes a
+  // good origin" is exactly the assumption that produced the defect.
+  if (!apiClient.baseUrl) {
+    return {
+      ok: false,
+      message: 'NOT CHECKED — no origin resolved',
+      remediation:
+        'This is a configuration fact, not a network problem, and no connectivity result is\n' +
+        '    reported for it. Choose an origin:\n' +
+        '      descix config init --env dev|demo|prod',
+    };
+  }
+
   try {
     // Just check if we can reach the health endpoint or root
     // The API client doesn't expose a raw ping, but we can try a lightweight call
@@ -148,10 +169,11 @@ export async function checkGcloud() {
     const version = stdout.split('\n')[0].trim(); // e.g. "Google Cloud SDK 456.0.0"
     return { ok: true, message: version };
   } catch (error) {
-    return { 
-      ok: false, 
-      message: 'Not installed or not in PATH', 
-      remediation: `Install the Google Cloud SDK: https://cloud.google.com/sdk/docs/install` 
+    return {
+      ok: false,
+      advisory: true,
+      message: 'Not installed or not in PATH',
+      remediation: `Only needed to administer DeSciX infrastructure. If you are building on DeSciX, ignore this.\n    Install (admins): https://cloud.google.com/sdk/docs/install`
     };
   }
 }
@@ -166,10 +188,11 @@ export async function checkAdc() {
       await fs.access(process.env.GOOGLE_APPLICATION_CREDENTIALS);
       return { ok: true, message: 'Configured via Env Var' };
     } catch {
-      return { 
-        ok: false, 
-        message: 'Env Var set but file missing', 
-        remediation: `Check GOOGLE_APPLICATION_CREDENTIALS path: ${process.env.GOOGLE_APPLICATION_CREDENTIALS}` 
+      return {
+        ok: false,
+        advisory: true,
+        message: 'Env Var set but file missing',
+        remediation: `Check GOOGLE_APPLICATION_CREDENTIALS path: ${process.env.GOOGLE_APPLICATION_CREDENTIALS}`
       };
     }
   }
@@ -191,10 +214,11 @@ export async function checkAdc() {
     // For now, existence is a good enough proxy for "attempted setup"
     return { ok: true, message: 'Configured (Default Location)' };
   } catch {
-    return { 
-      ok: false, 
-      message: 'Missing Credentials', 
-      remediation: `Run: gcloud auth application-default login --scopes=https://www.googleapis.com/auth/drive.file,https://www.googleapis.com/auth/drive` 
+    return {
+      ok: false,
+      advisory: true,
+      message: 'Missing Credentials',
+      remediation: `Only needed for Google Drive-backed KB authoring and infrastructure admin.\n    If you are building on DeSciX, ignore this.\n    Admins run: gcloud auth application-default login --scopes=https://www.googleapis.com/auth/drive.file,https://www.googleapis.com/auth/drive`
     };
   }
 }
@@ -209,9 +233,26 @@ export async function runDoctor(options = {}) {
   const results = [];
   
   try {
-    const globalConfig = await GlobalConfig.load();
-    const apiClient = new DeSciXApiClient({ baseUrl: globalConfig.api_url });
-    
+    // THE ORIGIN COMES FROM THE ONE OWNER. This was `new DeSciXApiClient({ baseUrl:
+    // globalConfig.api_url })` — a THIRD independent derivation of the origin, beside status's
+    // and beside the real one. ~/.descix/config.json names no origin on a fresh machine, so
+    // doctor ran its whole diagnosis against `null`. Passing NO baseUrl routes through
+    // initialize() → resolveOrigin(), which never returns null, fails loud on an origin that was
+    // named but unusable, and prints the `env:` line doctor was missing.
+    const apiClient = new DeSciXApiClient();
+    try {
+      await apiClient.ensureInitialized();
+    } catch (error) {
+      // A CONFIGURED-BUT-INVALID origin is not a diagnosis to render in a results table — it is
+      // the answer, and it already carries its own remedy from the origin owner. Fail loud
+      // rather than continuing into checks whose results would all be meaningless.
+      spinner.stop();
+      console.error(chalk.red(`\n${error.message}\n`));
+      process.exitCode = 1;
+      return;
+    }
+
+
     // 1. Node Version
     spinner.text = 'Checking Node.js...';
     const nodeRes = await checkNode();
@@ -247,9 +288,19 @@ export async function runDoctor(options = {}) {
     // Print Results
     let hasFailures = false;
     
+    // AN ADVISORY IS NOT A FAILURE. gcloud and ADC are administrator dependencies: an external
+    // developer building ON DeSciX has no business holding Google ADC credentials, yet doctor
+    // showed them a red [✗] and exited non-zero for not having them — telling every non-admin
+    // caller their environment is broken when it is correct and complete. A check that cries
+    // wolf on correct behaviour trains people to ignore the checks that matter.
     results.forEach(res => {
       if (res.ok) {
         console.log(`${chalk.green('[✓]')} ${chalk.white(res.label)} ${chalk.gray(res.message ? `(${res.message})` : '')}`);
+      } else if (res.advisory) {
+        console.log(`${chalk.gray('[-]')} ${chalk.white(res.label)} ${chalk.gray(`(${res.message} — not required)`)}`);
+        if (res.remediation) {
+          console.log(`    ${chalk.gray('Note:')}  ${chalk.gray(res.remediation)}`);
+        }
       } else {
         hasFailures = true;
         console.log(`${chalk.red('[✗]')} ${chalk.white(res.label)}`);
@@ -259,19 +310,35 @@ export async function runDoctor(options = {}) {
         }
       }
     });
-    
+
     console.log();
-    
+
+    // COVERAGE BOUNDARY, printed on green as well as red: the reader of a pass must see where
+    // the pass stops.
+    console.log(chalk.gray(
+      'Checked: Node version, API origin resolution + reachability, session, local write\n' +
+      'permissions. [-] rows are admin-only dependencies and never fail this command. NOT\n' +
+      'checked: your app\'s own build, chain state, or any credential\'s permissions at the API.'
+    ));
+    console.log();
+
     if (hasFailures) {
       console.log(chalk.yellow('⚠️  Some checks failed. Please review the issues above.'));
-      process.exit(1);
+      // `process.exitCode` rather than `process.exit(1)`: it lets Node drain stdout before
+      // exiting, where an immediate process.exit can truncate buffered output on a pipe.
+      // NO DEFECT WAS MEASURED HERE — this is a hardening, and the distinction matters. A
+      // suspected "exit code says 0 while the text says failed" was investigated on published
+      // 1.0.4 and DID NOT REPRODUCE: the 0 came from reading `$?` after a shell PIPELINE, which
+      // reports the exit of the last stage (`head`), not of `descix`. Recorded so the next
+      // reader does not re-open it: 1.0.4 exits 1 correctly.
+      process.exitCode = 1;
     } else {
       console.log(chalk.green('✨ All checks passed! Your environment is ready.'));
     }
-    
+
   } catch (error) {
     spinner.fail('Doctor crashed');
     console.error(chalk.red(`\nUnexpected error: ${error.message}`));
-    process.exit(1);
+    process.exitCode = 1;
   }
 }

package/lib/commands/init.js

@@ -13,6 +13,10 @@ import { dirname, join } from 'path';
 // clone.js is imported dynamically inside the invite flow to avoid circular deps
 import { WorkspaceConfig } from '../workspace-config.js';
 import { generateAgentFiles } from '../agent-files.js';
+// The canonical KB-sync surface is owned by retired-kb-sync.js. Consume the constant: a literal
+// spelled here is a second derivation of the same fact, and the removed verb this replaced
+// reached a developer who had done everything right.
+import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -208,8 +212,9 @@ export async function runInit(apiClient, options = {}) {
 
     console.log(chalk.cyan('\n─── Next Steps ───\n'));
     console.log(chalk.white(`  1. descix app init -a ${appId} -c ${communityId}    # register app on platform`));
-    console.log(chalk.white(`  2. descix update kb -c ${communityId} -a ${appId}   # sync KB to Pinecone`));
-    console.log(chalk.white(`  3. descix chat -c ${communityId} -a ${appId} -q "test"  # verify RAG\n`));
+    console.log(chalk.gray(`  2. Create a corpus manifest at .descix/manifests/General.json`));
+    console.log(chalk.white(`  3. ${CANONICAL_KB_SYNC} -a ${appId}   # sync KB to Pinecone`));
+    console.log(chalk.white(`  4. descix chat -c ${communityId} -a ${appId} -q "test"  # verify RAG\n`));
     console.log(chalk.green('✅ Workspace initialized.\n'));
     rl.close();
     return { created: ['.descix/workspace.json'], skipped: [], warnings: [] };
@@ -250,7 +255,7 @@ export async function initWorkspace(options) {
     created,
     skipped: [],
     warnings: [],
-    nextSteps: [`descix app init -a ${appId} -c ${communityId}`, `descix update kb -c ${communityId} -a ${appId}`]
+    nextSteps: [`descix app init -a ${appId} -c ${communityId}`, `${CANONICAL_KB_SYNC} -a ${appId}`]
   };
 }
 

package/lib/commands/kb.js

@@ -27,6 +27,10 @@ import { hydrateKb, pushStaging, checkStagingFiles } from '../core/Hydrator.js';
 import { processKb } from '../core/Chunker.js';
 import { syncKb, getSyncStatus } from '../core/Syncer.js';
 import * as driveADC from '../google-storage-adc.js';
+// The one canonical KB-sync surface, from its owner. Never spell it as a literal here: these
+// commands' next steps are read by a developer as instructions, so they must name the live verb
+// and nothing else.
+import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
 
 // ============ Pull Command ============
 
@@ -110,8 +114,7 @@ export async function runKbPull(apiClient, options) {
     if (!options.quiet) {
       console.log(chalk.cyan('\n📋 Next steps:'));
       console.log(chalk.gray('   1. Review files in kb/' + kbId + '/'));
-      console.log(chalk.gray('   2. Run "descix kb chunk" to generate chunks'));
-      console.log(chalk.gray('   3. Run "descix kb sync" to push to Pinecone\n'));
+      console.log(chalk.gray(`   2. Run "${CANONICAL_KB_SYNC} -a <app_id>" to push to Pinecone\n`));
     }
     
     return result;
@@ -220,8 +223,8 @@ export async function runKbPush(apiClient, options) {
     // Show next steps
     if (!options.quiet) {
       console.log(chalk.cyan('\n📋 Next steps:'));
-      console.log(chalk.gray('   1. Run "descix kb pull" to sync all Drive content'));
-      console.log(chalk.gray('   2. Run "descix kb chunk" to generate chunks\n'));
+      console.log(chalk.gray('   1. Run "descix drive pull" to sync all Drive content'));
+      console.log(chalk.gray(`   2. Run "${CANONICAL_KB_SYNC} -a <app_id>" to push to Pinecone\n`));
     }
     
     return result;

package/lib/commands/status.js

@@ -19,6 +19,7 @@ import { promisify } from 'util';
 import { DeSciXApiClient } from '../api-client.js';
 import { GlobalConfig } from '../global-config.js';
 import { isAuthenticated } from '../auth-guard.js';
+import { environmentNameFor } from '../environment-report.js';
 
 const execAsync = promisify(exec);
 
@@ -89,7 +90,24 @@ export async function runStatus(options = {}) {
   console.log(`OS:             ${os.type()} ${os.release()}`);
   
   const globalConfig = await GlobalConfig.load();
-  console.log(`Environment:    ${globalConfig.environment} (${globalConfig.api_url})`);
+
+  // THE ORIGIN COMES FROM THE ONE OWNER, VIA ITS CONSUMER. This line used to read
+  // `${globalConfig.environment} (${globalConfig.api_url})` — a SECOND, independent derivation
+  // of the origin that consulted only ~/.descix/config.json. That file legitimately names no
+  // origin, so on an unconfigured workspace status printed "production (null)": an environment
+  // NAME it had not resolved, beside a null origin, while `descix app list` seconds later
+  // correctly reported prod at https://descix.net from the actual owner. `environment` here is
+  // GlobalConfig's own unrelated default string, not a resolution — it was never an answer to
+  // "which origin will this CLI talk to".
+  //
+  // Constructing the client with NO baseUrl is what routes through the owner: initialize()
+  // resolves via resolveOrigin() and prints the `env:` line (I1 — every network-bound command,
+  // always). status and doctor were the two network-bound commands missing that line, which is
+  // exactly why the three-way disagreement stayed invisible.
+  const apiClient = new DeSciXApiClient();
+  await apiClient.ensureInitialized();
+  console.log(`Environment:    ${environmentNameFor(apiClient.baseUrl)} (${apiClient.originSource})`);
+  console.log(`API Origin:     ${chalk.green(apiClient.baseUrl)}`);
   console.log();
 
   // Load workspace context via WorkspaceConfig
@@ -110,7 +128,6 @@ export async function runStatus(options = {}) {
   console.log(chalk.white('Authentication'));
   console.log(chalk.white('--------------'));
 
-  const apiClient = new DeSciXApiClient({ baseUrl: globalConfig.api_url });
   const isAuth = await isAuthenticated(apiClient);
 
   if (isAuth) {
@@ -150,8 +167,15 @@ export async function runStatus(options = {}) {
         console.log(`Local Apps:     ${allApps.join(', ')}`);
       }
 
-      console.log(`API:            ${workspaceConfig.getApiUrl() ||
-        '(not configured — run `descix config set-env dev|demo|prod`)'}`);
+      // WHAT THE WORKSPACE FILE ITSELF SAYS — deliberately NOT a resolved origin. The resolved
+      // origin and its source are reported once, above, by the owner's consumer. This line used
+      // to call getApiUrl() with a `|| '(not configured …)'` fallback; getApiUrl() now consumes
+      // the origin owner and so NEVER returns null, making that branch unreachable — a dead
+      // fallback that could only ever misreport. Printing the raw key answers the different and
+      // genuinely useful question "is this origin coming from my workspace, or from elsewhere?"
+      const workspaceApiUrl = workspaceConfig.env?.apiUrl;
+      console.log(`API (this file): ${workspaceApiUrl
+        || '(unset — origin resolves from the sources printed above)'}`);
       console.log(`Local Root:     ${workspaceRoot}`);
     } catch (error) {
       console.log(`Mode:           ${chalk.red('Unknown/Invalid')} (${error.message})`);

package/lib/commands/update.js

@@ -4,7 +4,6 @@
  * Commands for updating resources based on workspace.json context detection:
  *   descix update          # Auto-detect what to update
  *   descix update app      # Sync app assets to Drive
- *   descix update kb       # Sync KB + vectorize
  *   descix update site     # Deploy site to GCS
  *   descix update all      # Update everything
  * 

package/lib/core/Hydrator.js

@@ -726,11 +726,15 @@ export async function checkStagingFiles(stagingDir) {
  * 
  * @param {string} scaffoldType - 'site' or 'microservice'
  * @param {string} appPath - Path to the app directory
- * @param {Object} options - { verbose, force }
+ * @param {Object} options - { verbose, force, substitute }
+ * @param {{appId: string, communityId: string, appName?: string}} [options.substitute] - the
+ *   caller's real identity. Supply it for any scaffold a developer will actually use: without it
+ *   the copy is verbatim and every {{TOKEN}} ships unresolved. Omitting it is only appropriate
+ *   when materializing the raw template itself.
  * @returns {Promise<{copied: number}>}
  */
 export async function copyScaffold(scaffoldType, appPath, options = {}) {
-  const { verbose = false, force = false } = options;
+  const { verbose = false, force = false, substitute = null } = options;
   
   const scaffoldDir = SCAFFOLD_DIRS[scaffoldType];
   if (!scaffoldDir) {
@@ -767,8 +771,36 @@ export async function copyScaffold(scaffoldType, appPath, options = {}) {
   
   // Copy scaffold recursively
   const stats = { copied: 0 };
-  await copyDir(scaffoldDir, targetDir, stats, verbose);
-  
+  let values = null;
+  if (substitute) {
+    if (!substitute.appId || !substitute.communityId) {
+      throw new Error(
+        'copyScaffold: substitute requires both appId and communityId. Refusing to resolve a ' +
+        'scaffold against a partial identity — a half-substituted scaffold is harder to spot ' +
+        'than an unsubstituted one.'
+      );
+    }
+    values = {
+      APP_ID: substitute.appId,
+      COMMUNITY_ID: substitute.communityId,
+      APP_NAME: substitute.appName || substitute.appId,
+    };
+  }
+
+  const unresolved = [];
+  await copyDir(scaffoldDir, targetDir, stats, verbose, values, unresolved);
+
+  // FAIL LOUD. A placeholder that survives the copy reaches the developer as literal braces, and
+  // that is exactly the class of defect this substitution exists to end — so it must never be a
+  // warning. Name every offender so a new token added to a template cannot ship unnoticed.
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Scaffold "${scaffoldType}" has ${unresolved.length} unresolved placeholder(s): ` +
+      `${unresolved.join(', ')}. Every {{TOKEN}} in a scaffold needs a value in copyScaffold's ` +
+      `substitute map (see templates/scaffolds/README.md for the documented set).`
+    );
+  }
+
   return stats;
 }
 
@@ -785,21 +817,66 @@ async function hasContentInDir(dirPath) {
 }
 
 /**
- * Recursively copy a directory
+ * THE ONE OWNER of scaffold placeholder substitution.
+ *
+ * templates/scaffolds/README.md has documented this contract all along — "Scaffolds use these
+ * placeholders (replaced during copy): {{APP_NAME}}, {{APP_ID}}, {{COMMUNITY_ID}}" — but nothing
+ * ever performed the replacement. Both scaffolds shipped their placeholders and their sample
+ * literals verbatim, so a developer's site was titled `{{APP_NAME}}` and the sample handler
+ * queried a community that is not theirs.
+ *
+ * SUBSTITUTION, NOT A SECOND LITERAL. The fix resolves each token to the caller's real values;
+ * it does not swap one hardcoded community for another. That is what lets the same scaffold serve
+ * every community without the CLI knowing any of their names.
+ *
+ * @param {string} text - file contents
+ * @param {Record<string,string>} values - token name (without braces) -> replacement
+ * @returns {string}
  */
-async function copyDir(src, dest, stats, verbose) {
+function applyScaffoldTokens(text, values) {
+  return text.replace(/\{\{([A-Z_]+)\}\}/g, (whole, token) =>
+    Object.prototype.hasOwnProperty.call(values, token) ? values[token] : whole
+  );
+}
+
+/** A NUL byte is the cheap, dependency-free binary tell. Never rewrite bytes we cannot read. */
+function looksBinary(buf) {
+  return buf.includes(0);
+}
+
+/**
+ * Recursively copy a directory, optionally substituting scaffold tokens on the way.
+ *
+ * @param {Record<string,string>|null} values - when null, the copy is byte-for-byte verbatim
+ * @param {string[]} unresolved - collects `file:{{TOKEN}}` for tokens no value was supplied for
+ */
+async function copyDir(src, dest, stats, verbose, values = null, unresolved = [], relBase = '') {
   await fs.mkdir(dest, { recursive: true });
-  
+
   const entries = await fs.readdir(src, { withFileTypes: true });
-  
+
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+
     if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath, stats, verbose);
+      await copyDir(srcPath, destPath, stats, verbose, values, unresolved, rel);
     } else {
-      await fs.copyFile(srcPath, destPath);
+      if (values) {
+        const buf = await fs.readFile(srcPath);
+        if (looksBinary(buf)) {
+          await fs.copyFile(srcPath, destPath);
+        } else {
+          const out = applyScaffoldTokens(buf.toString('utf8'), values);
+          // Anything still wearing braces had no value supplied. Collect it rather than shipping
+          // it: an unresolved placeholder reaching a developer is the defect this exists to end.
+          for (const m of out.matchAll(/\{\{([A-Z_]+)\}\}/g)) unresolved.push(`${rel}:{{${m[1]}}}`);
+          await fs.writeFile(destPath, out);
+        }
+      } else {
+        await fs.copyFile(srcPath, destPath);
+      }
       stats.copied++;
       if (verbose) console.log(`  Copied: ${entry.name}`);
     }

package/lib/origin.js

@@ -60,15 +60,87 @@ export class OriginInvalidError extends Error {
 }
 
 /**
- * The resolution order, most explicit first. Each entry is [human-readable source, key].
- * The ORDER is the contract; the array is the only place it is written down.
+ * The SOURCE label for each thing that can name an origin. One key, one spelling.
+ *
+ * WHY EACH LABEL NAMES EXACTLY ONE THING (measured 2026-09-09 on published 1.0.4): the envVar
+ * label used to read `DESCIX_API_URL (or --api-url / --env)` — a STATIC DISJUNCTION printed
+ * whichever of the three had actually chosen the origin, and printed verbatim even with
+ * DESCIX_API_URL provably unset. `--env dev`, `--api-url https://dev.descix.net` and a real
+ * `DESCIX_API_URL=...` produced three byte-identical source strings. A source that lists the
+ * possibilities is not a source: it is the same "who chose this origin" silence this module
+ * exists to end, one level in from the null it already fixed.
+ *
+ * The flag labels are reachable because `bin/descix.js` RECORDS which flag set the variable
+ * (see `recordInvocationOrigin`) instead of only folding it into `process.env` and discarding
+ * the provenance.
+ */
+export const ORIGIN_SOURCE_LABELS = {
+    flagApiUrl: '--api-url flag',
+    flagEnv: '--env flag',
+    envVar: 'DESCIX_API_URL environment variable',
+    workspaceEnvApiUrl: '.descix/workspace.json env.apiUrl',
+    legacyApiUrl: '.descix/workspace.json apiUrl (legacy)',
+    globalApiUrl: '~/.descix/config.json api_url',
+};
+
+/**
+ * The resolution order, most explicit first. The ORDER is the contract; this array is the only
+ * place it is written down. Labels come from ORIGIN_SOURCE_LABELS, never from a second literal.
+ */
+const PRECEDENCE = ['envVar', 'workspaceEnvApiUrl', 'legacyApiUrl', 'globalApiUrl'];
+
+/**
+ * What this invocation's FLAGS named, if anything: `{ origin, sourceKey }`.
+ *
+ * `--api-url` and `--env` are folded into `process.env.DESCIX_API_URL` by the CLI's preAction
+ * hook so that every consumer sees one variable. That fold is what destroys the provenance, so
+ * the hook records it here in the same breath. Module-level because there is exactly ONE
+ * invocation per process, and because this module is imported by every consumer of the origin —
+ * one owner of the fact, not a copy ferried through four call signatures.
+ */
+let invocationOrigin = null;
+
+/**
+ * Record that a COMMAND-LINE FLAG chose this invocation's origin.
+ *
+ * @param {string} origin - the origin the flag resolved to
+ * @param {'flagApiUrl'|'flagEnv'} sourceKey - which flag it was
+ * @throws when handed a key that has no published label — a source with no name is the defect.
  */
-const PRECEDENCE = [
-    ['DESCIX_API_URL (or --api-url / --env)', 'envVar'],
-    ['.descix/workspace.json env.apiUrl', 'workspaceEnvApiUrl'],
-    ['.descix/workspace.json apiUrl (legacy)', 'legacyApiUrl'],
-    ['~/.descix/config.json api_url', 'globalApiUrl'],
-];
+export function recordInvocationOrigin(origin, sourceKey) {
+    if (!Object.prototype.hasOwnProperty.call(ORIGIN_SOURCE_LABELS, sourceKey)) {
+        throw new Error(
+            `recordInvocationOrigin: "${sourceKey}" is not a known origin source. ` +
+            `Known: ${Object.keys(ORIGIN_SOURCE_LABELS).join(', ')}.`,
+        );
+    }
+    invocationOrigin = { origin: normalizeOrigin(origin), sourceKey };
+}
+
+/** TEST SEAM ONLY: forget this invocation's recorded flag provenance. */
+export function _resetInvocationOriginForTests() {
+    invocationOrigin = null;
+}
+
+/**
+ * The label for the value that won, naming WHICH source supplied it.
+ *
+ * The envVar slot is the only one with more than one possible author, because the flags are
+ * folded into it. It reports a flag ONLY when the recorded flag actually accounts for the value
+ * in hand — if a flag was recorded and DESCIX_API_URL nevertheless holds something else, the
+ * honest answer is the environment variable.
+ *
+ * @param {string} key
+ * @param {string} value
+ * @returns {string}
+ */
+function sourceLabelFor(key, value) {
+    if (key === 'envVar' && invocationOrigin
+        && invocationOrigin.origin === normalizeOrigin(value)) {
+        return ORIGIN_SOURCE_LABELS[invocationOrigin.sourceKey];
+    }
+    return ORIGIN_SOURCE_LABELS[key];
+}
 
 /** The remedy text every failure prints. One spelling, so every surface says the same thing. */
 export const ORIGIN_REMEDY =
@@ -120,9 +192,10 @@ function isUsableOrigin(value) {
  *         same class of defect from the other direction.
  */
 export function resolveOrigin(sources = {}) {
-    for (const [label, key] of PRECEDENCE) {
+    for (const key of PRECEDENCE) {
         const value = sources[key];
         if (typeof value === 'string' && value.trim() !== '') {
+            const label = sourceLabelFor(key, value);
             if (!isUsableOrigin(value)) {
                 throw new OriginInvalidError(
                     `The DeSciX API origin configured in ${label} is not a usable origin: "${String(value).trim()}".\n` +

package/lib/workspace-config.js

@@ -2,6 +2,29 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { ENV_ORIGINS } from '@descix/app-sdk/dev';
 import { resolveOrigin } from './origin.js';
+// The one canonical KB-sync surface, from its owner. The example in requireContext() is a remedy
+// a stuck developer will copy verbatim, so it must resolve to the live verb rather than a literal
+// that can go stale where nobody is watching.
+import { CANONICAL_KB_SYNC } from './commands/retired-kb-sync.js';
+
+/**
+ * THE ONE OWNER of "this app is not mapped in workspace.json, here is how to fix it".
+ *
+ * This text existed as three byte-identical copies in this file, and TWO OTHER call sites in
+ * bin/descix.js answered the same condition with a DIFFERENT and wrong remedy — `npx descix init`,
+ * which initialises a WORKSPACE and cannot map an app, so a developer who followed it stayed
+ * exactly as stuck. That is the mirror-drift tell: the same condition explained two ways, and the
+ * wrong one was the one a developer actually hit on the onboarding path.
+ *
+ * @param {string} appId - the app that is not mapped
+ * @returns {string}
+ */
+export function unmappedAppMessage(appId) {
+  return (
+    `App "${appId}" is not mapped in workspace.json. ` +
+    'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+  );
+}
 
 /**
  * ONE OWNER for turning a workspace-relative localPath into an absolute path.
@@ -248,6 +271,17 @@ export class WorkspaceConfig {
   /**
    * Save workspace configuration in v2.1 format.
    * Always writes env.platform / env.products structure.
+   *
+   * PRESERVES KEYS IT DOES NOT UNDERSTAND. This method used to serialize a fixed field list from
+   * memory over the whole file, so ANY top-level key it did not itself enumerate was silently
+   * destroyed by the next `descix app set-port` — a writer re-serializing a known schema and
+   * discarding the rest. That is the same defect class as a record writer dropping a field it was
+   * never taught about, and it is invisible: the write succeeds, the file looks well-formed, and
+   * the loss is only discovered by whoever needed the missing key.
+   *
+   * The on-disk file is re-read at save time rather than trusted from construction, because the
+   * instance may have been held across another writer's save.
+   *
    * @param {string} [workspaceRoot] - Workspace root directory (uses stored root if not provided)
    * @returns {Promise<string>} Path to saved config
    */
@@ -266,7 +300,32 @@ export class WorkspaceConfig {
     // Build env block for v2.1 output
     const envBlock = (this.env && Object.keys(this.env).length > 0) ? this.env : null;
 
+    // The keys this writer OWNS. Everything else on disk is carried through untouched.
+    const OWNED = ['version', 'workspaceRoot', 'type', 'env', 'driveConfig'];
+
+    let onDisk = {};
+    try {
+      const existing = await fs.readFile(configPath, 'utf-8');
+      const parsed = JSON.parse(existing);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) onDisk = parsed;
+    } catch (err) {
+      // ENOENT is the ordinary first save. A PRESENT-BUT-UNPARSEABLE file is different: carrying
+      // on would overwrite content we could not read, so refuse and name the file.
+      if (err.code !== 'ENOENT') {
+        throw new Error(
+          `Refusing to overwrite ${configPath}: it exists but could not be read as JSON ` +
+          `(${err.message}). Fix or remove it — saving now would destroy whatever it holds.`
+        );
+      }
+    }
+
+    const carried = {};
+    for (const [k, v] of Object.entries(onDisk)) {
+      if (!OWNED.includes(k)) carried[k] = v;
+    }
+
     const configData = {
+      ...carried,
       version: '2.1',
       workspaceRoot: path.resolve(root),
       type: this.type,
@@ -508,7 +567,7 @@ export class WorkspaceConfig {
         'Options:\n' +
         '  1. cd into an app directory\n' +
         '  2. Use flag: -a <app_id>\n\n' +
-        'Example: npx descix update kb -a daita'
+        `Example: npx ${CANONICAL_KB_SYNC} -a daita`
       );
     }
     
@@ -637,8 +696,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `App "${appId}" is not mapped in workspace.json. ` +
-        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+        unmappedAppMessage(appId)
       );
     }
 
@@ -687,8 +745,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `App "${appId}" is not mapped in workspace.json. ` +
-        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+        unmappedAppMessage(appId)
       );
     }
 
@@ -743,8 +800,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `App "${appId}" is not mapped in workspace.json. ` +
-        'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+        unmappedAppMessage(appId)
       );
     }