@descix/cli 1.0.3 → 1.0.5

package/agent-assets/reference/mcp-integration.md

@@ -85,9 +85,11 @@ The broker validates this context and propagates it to downstream services.
 
 ### 3.1 Primary Discovery Mechanism
 
-`tell_me_how` is the **primary entry point** for discovering platform capabilities. Always use it before attempting platform operations.
+**Prerequisite: the developer is signed in.** `tell_me_how` returns caller-specific context (and `kb corpus sync` writes to a KB namespace) — both correctly refuse a credential-free caller, loud: `Authentication required`, exit 1. There is no guest/unauthenticated form of discovery, and that refusal must not be treated as a bug to work around. The step before discovery is `descix login --env dev`: it starts a device-code flow — opens a browser and mints a fresh sign-in code for that one invocation — and completes once the browser confirms it.
 
-**Rule:** Ask `tell_me_how` first, then execute the recommended command.
+Once signed in, `tell_me_how` is the **primary entry point** for discovering platform capabilities. Always use it before attempting platform operations.
+
+**Rule:** Sign in, then ask `tell_me_how` first, then execute the recommended command.
 
 ### 3.2 Three Scopes
 
@@ -100,6 +102,9 @@ The broker validates this context and propagates it to downstream services.
 ### 3.3 CLI Usage
 
 ```bash
+# Sign in first — device-code flow, opens a browser (skip if already authenticated)
+descix login --env dev
+
 # Default (entitlements scope)
 descix tell-me-how "How do I create a new app?"
 
@@ -341,10 +346,11 @@ Custom services integrate with the same pattern:
 
 ### 7.1 For AI Agents
 
-1. **Always use tell_me_how first** - Don't guess at command names
-2. **Use project scope when in a workspace** - More focused results
-3. **Chain operations** - tell_me_how -> execute_remote_command
-4. **Handle errors gracefully** - Show user-friendly messages
+1. **Be signed in before discovery** - `descix login --env dev` (device-code flow) is the step before `tell_me_how`; it refuses loud, not silently, for a credential-free caller
+2. **Always use tell_me_how first (once signed in)** - Don't guess at command names
+3. **Use project scope when in a workspace** - More focused results
+4. **Chain operations** - tell_me_how -> execute_remote_command
+5. **Handle errors gracefully** - Show user-friendly messages
 
 ### 7.2 For Service Developers
 

package/bin/descix.js

@@ -13,6 +13,7 @@ import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
 import { WorkspaceConfig } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
+import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
 import {
   getSessionInteractionId,
@@ -107,12 +108,24 @@ const ENV_URL_MAP = Object.fromEntries(
   Object.entries(WorkspaceConfig.ENV_MAP).map(([k, v]) => [k, v.url])
 );
 
+// The fold into DESCIX_API_URL is what makes every consumer see ONE variable — and it is also
+// what used to DESTROY the answer to "who chose this origin", so the origin owner printed a
+// static disjunction ("DESCIX_API_URL (or --api-url / --env)") for all three cases. The fold
+// 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) => {
-  const opts = thisCommand.opts();
+  // 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();
 
   // --api-url takes highest priority
   if (opts.apiUrl) {
     process.env.DESCIX_API_URL = opts.apiUrl;
+    recordInvocationOrigin(opts.apiUrl, 'flagApiUrl');
     return;
   }
 
@@ -120,12 +133,23 @@ program.hook('preAction', (thisCommand) => {
   if (opts.env) {
     const envName = opts.env.toLowerCase();
     if (!(envName in ENV_URL_MAP)) {
-      console.error(chalk.red(`Unknown environment: ${opts.env}. Use: dev, demo, prod`));
+      // 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
+      // richer text inside `config init` that names `config set-env` for exactly this case can
+      // no longer be reached through the flag. A refusal that names only the three built-in
+      // 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` +
+        'For a self-hosted or port-forwarded gateway, name it with its origin instead:\n' +
+        `  descix config set-env ${envName} --url https://...`
+      ));
       process.exit(1);
     }
     // Every named environment resolves to a URL (including dev → cloud DEV).
     // A local backend is a URL you name, not an environment.
     process.env.DESCIX_API_URL = ENV_URL_MAP[envName];
+    recordInvocationOrigin(ENV_URL_MAP[envName], 'flagEnv');
   }
 });
 
@@ -2327,7 +2351,7 @@ corpusCommand
   .option('-k, --kb <name>', 'KB name (syncs specific manifest; default: all)')
   .option('-v, --verbose', 'Show verbose output')
   .option('--ref <ref>', 'Override the git ref for ALL manifest sources (e.g., --ref ws-admin-b1). Precedence: --ref > manifest source.ref > "main".')
-  .option('--rebuild', 'Reconcile Pinecone against the current manifest walk: enumerate remote file_ids, purge any not in the current corpus, then re-sync from scratch. Use to recover from accumulated stale-chunk drift. Prompts before deleting unless --yes is supplied.')
+  .option('--rebuild', 'Reconcile Pinecone against REMOTE state: enumerate remote file_ids, purge any not in the current corpus, then re-sync from scratch. NOT needed to remove deleted files — an ordinary sync already purges them, diffing the walk against sync-state\'s last_sync_commit (measured: a plain sync purged 1962 chunks across 124 stale blob SHAs). Use --rebuild ONLY when that local sync-state cannot be trusted: it is lost, hand-edited, or vectors were orphaned outside the history it tracks. Prompts before deleting unless --yes is supplied.')
   .option('--dry-run', 'Enumerate would-be-purged file_ids and would-be-upserted chunks without ANY Pinecone writes. Exit 0 if no drift, 1 if drift. Read-only.')
   .option('--show-walk', 'Print the resolved ref + the first 50 walked files BEFORE any Pinecone operations. Useful for verifying --ref / manifest source resolution.')
   .option('--yes', 'Skip the interactive purge confirmation in --rebuild mode. Use in scripting/CI.')
@@ -4334,15 +4358,24 @@ configCommand
 
 configCommand
   .command('init')
-  .description('Initialize configuration for an environment (requires --env)')
+  .description('Pin this workspace to an environment (requires the global --env dev|demo|prod)')
   // `--dev` DELETED, not deprecated: its absence meant PRODUCTION, so the most common
   // invocation (`descix config init`) wrote a prod origin nobody named. There is no default.
-  .option('--env <name>', 'Environment to initialize: dev, demo or prod')
+  //
+  // `--env` IS NOT REDECLARED HERE, and that is the fix, not an omission. It was declared both
+  // globally (program.option, above) and on this subcommand; Commander 14 binds `--env dev` to
+  // the ROOT program, so this action received `{}` and threw "requires an environment" — the
+  // command REJECTED THE FLAG ITS OWN --help ADVERTISED. Measured on published 1.0.4, and worse
+  // than a missing command: the CLI printed `descix config init --env dev` as the remedy for an
+  // unconfigured origin (origin.js DEFAULT_ORIGIN_SOURCE) and that exact copy-pasted string
+  // exited 1. Two declarations of one flag is the mirror-drift class; one owner is the cure.
   .option('--url <url>', 'Explicit origin (for a self-hosted or port-forwarded gateway)')
   .option('-g, --global', 'Save to global config (~/.descixrc)')
+  .addHelpText('after', '\nEnvironment comes from the global flag:\n' +
+    '  descix config init --env dev|demo|prod\n')
   .action(async (options) => {
     try {
-      await configCommands.init(options.env, options);
+      await configCommands.init(program.opts().env, options);
     } catch (error) {
       fail(error);
     }

package/lib/api-client.js

@@ -66,6 +66,15 @@ export class DeSciXApiClient {
       this.baseUrl = String(this.baseUrl).trim().replace(/\/+$/, '');
       originSource = EXPLICIT_ORIGIN_SOURCE;
     }
+    // KEPT ON THE CLIENT, not just printed and dropped. `status` and `doctor` have to SHOW the
+    // resolved origin and its source in their own report bodies; when this was a local variable
+    // the only way for them to state an origin was to derive one themselves, and both did —
+    // from GlobalConfig.api_url, which is legitimately null. That produced three different
+    // answers for one state seconds apart (status "production (null)", doctor "API URL: null",
+    // app list the real origin). A consumer can only ferry the owner's answer if the owner's
+    // answer is still reachable.
+    this.originSource = originSource;
+
     // I1 (A', rev 2): ALWAYS, not default-only. Silence was the defect; PROD was not.
     reportEnvironment({ origin: this.baseUrl, source: originSource });
 

package/lib/commands/briefer/sources/entitlements.js

@@ -85,12 +85,23 @@ export async function extract({ env, cliPaths } = {}) {
     relPath: CM_FILE,
     section: `§${SECTION.number} ${SECTION.heading}`
   });
+  // The symbol is matched WITHIN an export list rather than as the list's sole member. The old
+  // pattern anchored on the closing brace immediately after the name, so it broke the moment a
+  // second symbol was re-exported beside it — the extractor reported the re-export missing when
+  // it was present and one token wider.
+  //
+  // HONEST LIMITATION, stated rather than implied: this is still textual matching, so it remains a
+  // derivation of a fact the module itself owns. The robust fix is to consume the owner's actual
+  // exports, but this extractor cannot import communityManagement.js — that would pull the whole
+  // Cloud service graph (config bootstrap, Firestore) into the CLI. Matching the identifier inside
+  // any export list is what survives a re-ordering; a move to `export * from` would still need
+  // this line changed.
   const reExportMatch = findInLines({
     lines: cm.lines,
-    regex: /export\s*\{\s*hydrateCommunityIdFromProducts\s*\}/,
+    regex: /export\s*\{[^}]*\bhydrateCommunityIdFromProducts\b/,
     section: `§${SECTION.number} ${SECTION.heading}`,
     source: `${CM_FILE} (hydrate re-export)`,
-    expected: 'export { hydrateCommunityIdFromProducts }',
+    expected: 'hydrateCommunityIdFromProducts named in an export list',
     recovery: `Verify ${CM_FILE} still re-exports hydrateCommunityIdFromProducts.`
   });
 

package/lib/commands/config.js

@@ -101,13 +101,29 @@ export async function init(env, options = {}) {
     // Write through the CANONICAL writer. This function used to assign the LEGACY top-level
     // `workspaceConfig.apiUrl`, while `config set-env` writes `env.apiUrl` — two writers of one
     // fact, writing two different keys, one of which `getApiUrl()` only consults as a fallback.
-    const workspaceConfig = await WorkspaceConfig.load();
+    //
+    // `tryLoad`, NOT `load`, AND IT CREATES ONE WHEN THERE IS NONE. This is what closes the
+    // PROD WINDOW at the start of every onboarding (measured on published 1.0.4): in a fresh
+    // directory `config init --env dev` threw "Workspace not configured", `config set-env dev`
+    // threw the same, and so there was NO WORKING WAY TO PIN THE ENVIRONMENT BEFORE the first
+    // command ran — every one of them silently targeted PROD while printing a remedy that could
+    // not be executed. Pinning the environment must not require a workspace to already exist:
+    // choosing the origin is the FIRST thing a developer does, not something they may only do
+    // after they have already talked to the wrong one.
+    const existing = await WorkspaceConfig.tryLoad();
+    const workspaceConfig = existing
+      || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, process.cwd());
+    const created = !existing;
     const result = await workspaceConfig.setEnvironment(normalized, options.url || null);
 
     console.log(chalk.green('\n✅ Configuration initialized!\n'));
     console.log(chalk.white(`   Environment: ${result.environment}`));
     console.log(chalk.white(`   API URL:     ${result.apiUrl}`));
-    console.log(chalk.gray(`   Saved to:    ${result.configPath}\n`));
+    console.log(chalk.gray(`   Saved to:    ${result.configPath}`));
+    if (created) {
+      console.log(chalk.gray('   (new workspace created here — this directory is now the workspace root)'));
+    }
+    console.log('');
 
   } catch (error) {
     console.error(chalk.red('Error initializing config:', error.message));
@@ -124,7 +140,32 @@ export async function init(env, options = {}) {
  */
 export async function setEnv(envName, options = {}) {
   try {
-    const workspaceConfig = await WorkspaceConfig.load();
+    // ONE SURFACE PER CAPABILITY. `config init` and `config set-env` both write through the same
+    // canonical writer (setEnvironment) — that shared owner is correct — but they must not both
+    // accept the SAME input, or there are two commands for one act and the CLI's own remedy
+    // string can name the loser. `config init` is canonical for the three KNOWN environments:
+    // the origin owner prints `descix config init --env dev` as the remedy, so that command must
+    // be the one that does it. `set-env` keeps the capability `init` genuinely does not have —
+    // a CUSTOM environment name with an explicit --url — and REFUSES the known names outright,
+    // naming its replacement. A refusal, not a warning: a warning would leave two working paths.
+    const knownName = WorkspaceConfig.ENV_MAP[String(envName).toLowerCase()];
+    if (knownName) {
+      throw new Error(
+        `"${envName}" is a known environment — use the canonical command:\n` +
+        `  descix config init --env ${String(envName).toLowerCase()}\n\n` +
+        'descix config set-env is for a CUSTOM environment name with an explicit origin, e.g.\n' +
+        '  descix config set-env staging --url https://staging.example.com'
+      );
+    }
+
+    // Same tryLoad-or-create as `config init`, for the same reason: `config init`'s own error
+    // text sends a developer HERE for the self-hosted / port-forwarded case, so this command has
+    // to work where that developer actually is. If it still required a pre-existing workspace,
+    // init's remedy would point at a command that refuses — the identical closed loop, moved one
+    // hop along. A remedy string is only true if the command it names runs.
+    const existing = await WorkspaceConfig.tryLoad();
+    const workspaceConfig = existing
+      || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, process.cwd());
 
     const result = await workspaceConfig.setEnvironment(envName, options.url || null);
 

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -2,11 +2,11 @@
 
 ## Overview
 
-The DeSciX SDK provides command-line tools and MCP (Model Context Protocol) integration for building applications on the DeSciX platform. The SDK enables developers to authenticate, manage workspaces, create apps, and leverage AI-assisted development through Cursor IDE integration.
+The DeSciX SDK provides command-line tools and MCP (Model Context Protocol) integration for building applications on the DeSciX platform. The SDK enables developers to authenticate, manage workspaces, create apps, and leverage AI-assisted development through editor MCP integration (Claude Code, Copilot, Cursor, Cline).
 
 **Key capabilities:**
 - CLI commands for all platform operations
-- MCP server for Cursor IDE integration
+- MCP server integration for Claude Code, Copilot, Cursor and Cline
 - Intelligent tool discovery via `tell_me_how`
 - Entitlements-driven workspace setup
 - Git-aware project initialization
@@ -28,23 +28,22 @@ npm link
 
 ## CLI Commands
 
-### descix setup
+### descix quickstart
 
-**Description:** One-time workspace configuration wizard
-**Use when:** First time setting up DeSciX in a new workspace or Cursor project
+**Description:** One-command setup: auth → workspace → agent files → MCP config
+**Use when:** First time setting up DeSciX in a new workspace
 **What it does:**
-1. Prompts for API endpoint (production/local/custom)
-2. Runs device authentication (opens browser)
-3. Creates `.cursor/mcp.json` for MCP server
-4. Creates `.cursor/rules/descix_mcp.mdc` for AI agent instructions
-5. Creates `.descix/workspace.json` with initial configuration
+1. Authenticates via device login if no valid session exists
+2. Initializes `.descix/workspace.json` if missing
+3. Generates agent instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.clinerules`) from the workspace's registered app/community
+4. Generates `.vscode/mcp.json` for MCP server config (skipped if the DeSciX VS Code extension already handles MCP)
+5. Copies SDK assets into `.descix/sdk-assets/`
 
 **Example:**
 ```bash
 cd ~/Projects/MyApp
-descix setup
+descix quickstart
 # Follow the prompts
-# Restart Cursor after completion
 ```
 
 ---
@@ -54,8 +53,11 @@ descix setup
 **Description:** Authenticate with the DeSciX platform
 **Use when:** Session expired or first-time authentication
 **Options:**
-- `--device` (default): Opens browser for Powch authentication
-- `--wallet`: Direct wallet signature authentication
+- (default, no flag needed): Device login — opens a browser for Powch authentication
+- `--wallet`: Direct wallet signature authentication (advanced, not yet implemented)
+- `-u, --url <url>`: API URL override
+- `--no-oauth`: Skip the OAuth long-lived token leg (wallet-signature login only)
+- `--scope <scope>`: OAuth scope to request (default: `mcp:read mcp:tools mcp:write mcp:admin`)
 
 **Example:**
 ```bash
@@ -107,41 +109,44 @@ descix tell-me-how --scope discovery "What AI training tools exist?"
 
 ---
 
-### descix app create
+### descix app init
 
-**Description:** Create or hydrate an app using the interactive wizard
-**Use when:** Starting a new project or hydrating an existing app
+**Description:** Create (if needed) and initialize an app: platform record + default KB + local workspace registration and scaffold. Idempotent.
+**Use when:** Starting a new project or hydrating an existing app. This is the single canonical path — the old two-step `app create` then `app init` is deleted; `descix app create` now hard-fails naming this replacement.
 **Options:**
-- `-c, --community <id>`: Community ID
-- `-a, --app <name>`: App name
-- `--wizard`: Interactive wizard mode
-- `--quick`: Skip optional prompts
-
-**Note:** New apps should primarily be provisioned via the PWA. This command can hydrate a local workspace from an existing app or create a skeleton if permitted.
+- `-a, --app <app_id>` (required): App ID. With `-c` this is the app NAME to create.
+- `-c, --community <id>`: Community ID — required to create an app that does not exist yet
+- `-s, --short <short_name>`: Short id segment (no hyphens) used when creating; defaults to `--app`
+- `--overwrite`: When creating, overwrite an existing app record intentionally
+- `--kb <name>`: Knowledge base name (default: `General`)
+- `-p, --path <dir>`: Local app directory (default: auto-detected or cwd)
 
 **Example:**
 ```bash
-# Interactive wizard
-descix app create --wizard
+descix app init -a myapp -c descix
 ```
 
 ---
 
 ### descix kb
 
-**Description:** Manage Knowledge Base content (Git Mode)
-**Use when:** Processing KB documents locally
+**Description:** Manage Knowledge Base registration, corpus sync and per-KB configuration
+**Use when:** Creating a KB, syncing its corpus to Pinecone, or managing per-KB settings
 
 **Subcommands:**
-- `pull`: Download source documents from Drive to `kb/src/`
-- `chunk`: Process source files into chunks in `kb/chunks/`
-- `sync`: Push chunks to the platform (Pinecone)
-- `build`: Run the full pipeline (Pull -> Chunk -> Sync)
+- `create` / `list` / `delete`: Register, list or remove a KB
+- `corpus sync`: The one KB sync surface — walks the corpus manifest, chunks in-memory, pushes to Pinecone
+- `set-override-model` / `clear-override-model`: Pin or clear a per-KB model override
+- `status`: Show corpus sync state (files, chunks, last sync, resolved ref)
+- `doctor`: Detect drift between local sync-state and live Pinecone vector count
+- `records put|query|get|delete`: Structured record CRUD on a KB
+
+**Drive content authoring is a separate command:** `descix drive pull` / `descix drive push` (not under `kb`) move source documents between Drive and the local working tree.
 
 **Example:**
 ```bash
-# Full build pipeline
-descix kb build -c descix -a myapp
+# Sync a KB's corpus manifest to Pinecone
+descix kb corpus sync -a myapp -k General
 ```
 
 ---
@@ -159,8 +164,7 @@ The scaffold reads them via `utils.DEVELOPER_WALLET_ADDRESS` / `utils.DEVELOPER_
 
 **Canonical microservice onboarding sequence:**
 ```bash
-descix app create   -c <community> -a <app>
-descix app init      -a <community>-<app>
+descix app init      -a <app> -c <community>
 descix app set-port  -a <community>-<app> -p <port>
 descix microservice register
 # then: cp dev-overrides.example.json dev-overrides.json  and fill in the developer credential
@@ -200,14 +204,15 @@ descix purchases
 
 ---
 
-## MCP Tools (for Cursor AI)
+## MCP Tools
 
-After running `descix setup` and restarting Cursor, these MCP tools are available to the AI agent:
+After running `descix quickstart` and reloading your editor/session, these MCP tools are available to the AI agent. `descix quickstart` authenticates via device login as its first step (opens a browser device-code flow) before it writes workspace, agent-instruction and MCP config files; there is no unauthenticated form of any of this.
 
 ### tell_me_how
 
 **Description:** Primary discovery tool - finds relevant commands for any task
-**Use first:** Always use this before attempting platform operations
+**Prerequisite:** the caller is signed in — it returns caller-specific context and is refused loud (`Authentication required`, exit 1) for a credential-free caller, never a silent partial answer
+**Use first:** Once signed in, always use this before attempting platform operations
 
 ```javascript
 tell_me_how({ 
@@ -230,7 +235,7 @@ tell_me_how({
 
 ```javascript
 execute_remote_command({
-  command: "create_app",
+  command: "create_app_for_community",
   params: {
     community_id: "descix",
     app_name: "My New App"
@@ -240,90 +245,31 @@ execute_remote_command({
 
 ---
 
-### descix_init
-
-**Description:** Initialize a local project for DeSciX deployment
-**Use when:** Setting up a new project folder
-
-```javascript
-descix_init({
-  projectPath: "/Users/dev/Projects/MyApp",
-  appName: "my-app",
-  communityId: "descix"
-})
-```
-
-**Creates:**
-- `.descix/workspace.json` or `.descix/context.json`
-- `app_description.md` from README if missing
-- Folder structure for knowledge base
-
----
-
-### descix_wizard_step
+### query_knowledge_base
 
-**Description:** Execute multi-step wizard workflows
-**Use when:** Creating apps, communities, or complex operations
+**Description:** Vector-similarity search over a knowledge base — returns raw source chunks with dereferenceable citations (retrieval, no synthesis, stateless)
+**Use when:** You want primary-source passages/citations, or to ground/check an `ask_question_to_app` answer
 
 ```javascript
-descix_wizard_step({
-  wizard_type: "create_app",
-  step: "init",
-  params: {
-    community_id: "descix",
-    app_name: "My App"
-  }
-})
-```
-
-**Wizard types:**
-- `create_app`: App creation with folder setup
-- `create_community`: Community creation with token
-- `publish_kb`: Knowledge base sync and publish
-
----
-
-### git_sync_ops
-
-**Description:** Git operations with auto-generated commit messages
-**Use when:** Committing changes, checking status
-
-```javascript
-git_sync_ops({
-  operation: "status",  // or "commit", "diff", "sync_info"
-  projectPath: "/Users/dev/Projects/MyApp"
-})
-```
-
----
-
-### search_knowledge_base
-
-**Description:** Search a specific knowledge base via RAG
-**Use when:** You know the exact KB to search
-
-```javascript
-search_knowledge_base({
-  communityId: "descix",
-  appId: "docs",
-  kbId: "sdk",
+query_knowledge_base({
+  app_id: "docs",
+  kb_id: "sdk",
   query: "How do I authenticate?"
 })
 ```
 
 ---
 
-### chat_with_kb
+### ask_question_to_app
 
-**Description:** Conversational RAG with knowledge base context
-**Use when:** Complex questions requiring AI reasoning
+**Description:** Ask a natural-language question against an app's knowledge base and get a synthesized, cited answer (stateful — pass `previous_interaction_id` to continue a thread)
+**Use when:** Complex questions requiring AI reasoning over a community's own sources
 
 ```javascript
-chat_with_kb({
-  communityId: "descix",
-  appId: "docs",
-  kbId: "sdk",
-  message: "Explain the authentication flow step by step"
+ask_question_to_app({
+  app_id: "docs",
+  knowledgebase_name: "sdk",
+  user_input: "Explain the authentication flow step by step"
 })
 ```
 
@@ -331,65 +277,44 @@ chat_with_kb({
 
 ## Workspace Configuration
 
-### workspace.json (Monorepo)
+### workspace.json (v2.1 — canonical)
 
-For multi-app workspaces, create `.descix/workspace.json`:
+`.descix/workspace.json` is written and mutated by `descix init` / `descix app init` / `descix app set-*` — never hand-edited. The v2.1 format is `env.platform` (the shell/store app, served at root) plus `env.products[]` (apps hosted inside the shell); the older `communities`-based v1 format is not supported and hard-errors on load ("v1 workspace format is not supported. Migrate to v2.1."):
 
 ```json
 {
-  "version": "2.0",
-  "primaryCommunity": "descix",
-  "directoryMappings": {
-    "frontend": { "communityId": "descix", "appId": "pwa", "kbId": "General" },
-    "backend": { "communityId": "descix", "appId": "cloud", "kbId": "General" },
-    "docs": { "communityId": "descix", "appId": "docs", "kbId": "sdk" }
-  },
-  "defaultContext": {
-    "communityId": "descix",
-    "appId": "docs",
-    "kbId": "sdk"
+  "version": "2.1",
+  "env": {
+    "platform": { "appId": "daita", "communityId": "descix", "localPath": ".", "kbId": "General" },
+    "products": [
+      { "appId": "docs", "communityId": "descix", "kbId": "sdk", "localPath": "descix-docs" }
+    ]
   }
 }
 ```
 
-### context.json (Single App)
-
-For individual app folders, create `.descix/context.json`:
-
-```json
-{
-  "version": "2.0",
-  "type": "app",
-  "community_id": "descix",
-  "app_id": "myapp",
-  "app_name": "My Application",
-  "folders": {
-    "app": { "local_path": ".", "sync_type": "assets" },
-    "kb": { "local_path": "docs", "sync_type": "rag" }
-  }
-}
-```
+A single-app (non-monorepo) workspace uses the same v2.1 shape with only `env.platform` set and an empty (or omitted) `env.products[]` — there is no separate single-app file format.
 
 ---
 
 ## Common Workflows
 
-### New Developer Onboarding (Cursor IDE)
+### New Developer Onboarding
 
 1. Install CLI: `npm install -g @descix/cli`
-2. Run setup: `descix setup`
-3. Restart Cursor (Cmd+Shift+P → "Reload Window")
+2. Run quickstart: `descix quickstart` — authenticates, initializes `.descix/workspace.json`, generates agent instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.clinerules`) for Claude Code, Copilot, Cursor and Cline, and writes `.vscode/mcp.json` (skipped if the DeSciX VS Code extension is installed — it registers MCP natively)
+3. Reload the editor/session so it picks up the generated files
 4. AI agent can now use MCP tools
 5. Ask: "How do I create an app?"
 6. AI uses `tell_me_how` → `execute_remote_command`
 
 ### Entitlements-First App Creation
 
-1. AI calls `execute_remote_command({ command: "fetch_my_purchases" })`
+1. AI calls `fetch_my_purchases()` directly (it is its own MCP tool, not an `execute_remote_command` target)
 2. AI presents user's communities and apps
 3. User selects community (or creates new)
-4. AI calls `descix_wizard_step` for app creation
-5. AI creates local `.descix/context.json`
+4. AI calls `execute_remote_command({ command: "create_app_for_community", params: {...} })` for app creation
+5. AI runs `descix app init` to register the local workspace mapping in `.descix/workspace.json`
 
 ### Monorepo Setup
 
@@ -404,9 +329,9 @@ For individual app folders, create `.descix/context.json`:
 ## Troubleshooting
 
 ### "MCP tools not available"
-1. Run `descix setup` in workspace root
-2. Restart Cursor completely
-3. Check `.cursor/mcp.json` exists with `descix` server
+1. Run `descix quickstart` in workspace root
+2. Reload your editor/session completely
+3. Check `.vscode/mcp.json` exists with a `descix` server (this file is skipped, by design, if the DeSciX VS Code extension is installed — it registers MCP natively)
 
 ### "401 Unauthorized on a loopback / mesh call"
 For the app data plane, your service authenticates AS the developer (wallet_address + signature). A 401 means the
@@ -421,7 +346,7 @@ Run `descix reconnect` or `descix login`
 Service READMEs may not be vectorized. Ask admin to run `descix microservice vectorize` for relevant services.
 
 ### "workspace.json not found" for project scope
-Run `descix init` or let AI create workspace.json via `descix_init` MCP tool.
+Run `descix init` (or `descix quickstart`, which runs it for you if missing).
 
 ---