@descix/cli 1.0.15 → 1.0.17

package/bin/descix.js

@@ -33,6 +33,8 @@ import { runInit } from '../lib/commands/init.js';
 import { createPromptSession } from '../lib/interactive.js';
 import { registerAllRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/retired-kb-sync.js';
 import { runStatus } from '../lib/commands/status.js';
+import { refreshCommunityIdentity, printIdentityReceipt } from '../lib/commands/communityIdentity.js';
+import { runAppInit } from '../lib/commands/appInit.js';
 import { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
@@ -199,7 +201,8 @@ program
   .option('-c, --community <id>', 'Community ID')
   .option('-a, --app <name>', 'App name')
   .option('-p, --path <path>', 'Project path (defaults to current directory)')
-  .option('-f, --force', 'Overwrite existing workspace.json')
+  .option('-f, --force', 'Restart the app registrations in an existing workspace (its environment settings are kept)')
+  .option('-y, --yes', 'Skip the confirmation — with -c and -a, init runs without a terminal')
   .option('--from-invite <token>', 'Resolve an invite token to pre-fill app context')
   .action(async (options) => {
     try {
@@ -212,7 +215,7 @@ program
         // Continue without API client
       }
       
-      await runInit(apiClient, options);
+      await runInit(apiClient, { ...options, env: program.opts().env });
     } catch (error) {
       console.error(chalk.red(`\n❌ ${error.message}\n`));
       process.exit(1);
@@ -461,6 +464,22 @@ const communityCommand = program
   .command('community')
   .description('Community operations');
 
+communityCommand
+  .command('refresh-identity')
+  .description('Mirror a community\'s token symbol and icon from the descix-chain registry into this environment (the icon only if it serves)')
+  .requiredOption('-c, --community <id>', 'Community ID')
+  .action(async (options) => {
+    try {
+      const apiClient = new DeSciXApiClient();
+      await requireAuth(apiClient);
+      printIdentityReceipt(options.community, await refreshCommunityIdentity(apiClient, options.community));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      process.exit(1);
+    }
+  });
+
 communityCommand
   .command('list')
   .description('List all communities')
@@ -1064,107 +1083,7 @@ appCommand
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      let appId = options.app;
-      const kbId = options.kb || 'General';
-
-      // Resolve community_id from the Products registry to learn whether the app exists yet.
-      let communityId;
-      try {
-        const productCtx = await apiClient.invoke('get_product_context', { app_id: appId });
-        communityId = (productCtx.message || productCtx).community_id;
-      } catch (e) {
-        // Not in Products — either we create it below (-c given) or we fail loud.
-      }
-
-      if (!communityId) {
-        if (!options.community) {
-          throw new Error(
-            `App '${appId}' does not exist yet. Pass -c <community> to create it: ` +
-            `descix app init -a ${appId} -c <community> [-s <short>]`
-          );
-        }
-        // CREATE leg — the canonical server path. It composes the unique app_id
-        // ({community}-{short}) and is authoritative; we never compose it client-side.
-        const response = await apiClient.invoke('create_app_for_community', {
-          community_id: options.community,
-          app_name: appId,
-          short_name: options.short || undefined,
-          create_skeleton: false,
-          overwrite: options.overwrite,
-        });
-        const created = response.message || response;
-        appId = created.app_id || appId;
-        communityId = created.community_id || options.community;
-        console.log(chalk.green(`\n✅ App created: ${appId}`));
-        console.log(chalk.gray(`  Products:   Products/${appId}`));
-        console.log(chalk.gray(`  Firestore:  Community/${communityId}/Apps/${appId}`));
-      } else if (options.community && options.community !== communityId) {
-        throw new Error(
-          `App '${appId}' already exists in community '${communityId}', not '${options.community}'. ` +
-          `Omit -c to initialize the existing app.`
-        );
-      }
-
-      // 1. Workspace.json — register app if not already mapped
-      const workspaceConfig = await WorkspaceConfig.tryLoad();
-      const alreadyMapped = workspaceConfig?.getAppByAppId(appId);
-      let appPath = alreadyMapped?.absolutePath;
-
-      if (alreadyMapped && options.path) {
-        throw new Error(
-          `App '${appId}' is already mapped to '${alreadyMapped.localPath}'. ` +
-          `Use 'descix app set-localpath -a ${appId} -p <new-path>' to update.`
-        );
-      }
-
-      if (!alreadyMapped) {
-        const localPath = options.path || '.';
-        const wsRoot = workspaceConfig?.workspaceRoot || process.cwd();
-        const cfg = workspaceConfig || new WorkspaceConfig({}, wsRoot);
-        cfg.registerApp(communityId, appId, { localPath, kbId });
-        await cfg.save(wsRoot);
-        appPath = path.resolve(wsRoot, localPath);
-        console.log(chalk.gray(`  workspace.json updated: ${appId} → ${localPath}`));
-      }
-
-      // 2. Create app folder structure (site, microservice, assets)
-      if (appPath) {
-        const siteDir = path.join(appPath, 'site');
-        const msDir = path.join(appPath, 'microservice');
-        const assetsDir = path.join(appPath, 'assets');
-        await fs.mkdir(siteDir, { recursive: true });
-        await fs.mkdir(msDir, { recursive: true });
-        await fs.mkdir(assetsDir, { recursive: true });
-
-        // Create template asset files if they don't exist
-        const siPath = path.join(assetsDir, 'system_instructions.md');
-        const descPath = path.join(assetsDir, 'app_description.md');
-        try {
-          await fs.access(siPath);
-        } catch {
-          await fs.writeFile(siPath, `# System Instructions for ${appId}\n\nYou are an AI assistant for the ${appId} application.\n`);
-        }
-        try {
-          await fs.access(descPath);
-        } catch {
-          await fs.writeFile(descPath, `# ${appId}\n\nApplication description goes here.\n`);
-        }
-        console.log(chalk.gray(`  Created: site/, microservice/, assets/`));
-      }
-
-      // 3. Create KnowledgeBase Firestore doc (Git Mode — no Drive required)
-      const kbResponse = await apiClient.invoke('init_git_mode_kb', { app_id: appId, kb_name: kbId });
-      const kbResult = kbResponse.message || kbResponse;
-
-      console.log(chalk.green(`\n✓ ${appId} initialized`));
-      console.log(chalk.gray(`  Community: ${communityId}`));
-      console.log(chalk.gray(`  KB: ${kbId} — ${kbResult.created ? 'created' : 'already exists'}\n`));
-      console.log(chalk.gray(`  (every app is guaranteed a default KB at creation; an empty one`));
-      console.log(chalk.gray(`   says so rather than answering from general knowledge)\n`));
-      console.log(chalk.cyan('Next steps:'));
-      console.log(chalk.gray(`  Create a corpus manifest at apps/${appId}/.descix/manifests/${kbId}.json`));
-      console.log(chalk.gray(`  then run:`));
-      console.log(chalk.white(`  descix kb corpus sync -a ${appId}\n`));
+      await runAppInit(apiClient, options);
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -2177,17 +2096,17 @@ const corpusCommand = kbCommand
 
 corpusCommand
   .command('sync')
-  .description('Sync corpus files to Pinecone using manifest definitions')
+  .description('Sync the files a corpus manifest names into the app\'s knowledge base')
   .requiredOption('-a, --app <id>', 'App ID')
   .option('-c, --community <community_id>', 'Community ID (optional; resolved from Products when omitted)')
   .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 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('--ref <ref>', 'Override the git ref for ALL manifest sources (e.g., --ref my-feature-branch). Precedence: --ref > manifest source.ref > "main".')
+  .option('--rebuild', 'Delete EVERYTHING in the knowledge base, then re-sync the whole corpus. Not needed to remove deleted or changed files — an ordinary sync already removes any corpus file that is live in the knowledge base but no longer in the corpus (see --dry-run, which names them). Use --rebuild only to clear content an ordinary sync cannot see. Prompts before deleting unless --yes is supplied.')
+  .option('--dry-run', 'Show what a sync would add and remove — naming each file it would remove — without changing anything. Exit 0 if nothing would change, 1 if something would.')
+  .option('--show-walk', 'Print the resolved ref and the first 50 files the manifest selects, before syncing anything. Useful for checking --ref and the manifest sources.')
   .option('--yes', 'Skip the interactive purge confirmation in --rebuild mode. Use in scripting/CI.')
-  .option('--skip-retrieval-canary', 'Skip the post-sync retrieval canary that confirms a synced chunk actually retrieves before reporting success (measured 2026-09-17: presence in Pinecone is not the same as searchable — the index can lag ~20 minutes after a large upsert/purge). Skipping costs nothing but SAVES one credit-metered query_knowledge_base call and up to ~25s; the sync then reports success on presence only, same as before this check existed. Prefer leaving this ON for anything user-facing; use it for CI/cost-sensitive automation that will verify separately.')
+  .option('--skip-retrieval-canary', 'Skip the post-sync check that a synced passage is actually searchable (a large sync can take several minutes to become searchable). Skipping saves one credit-metered query and up to ~25 s; the sync then reports success on upload alone. Leave the check on for anything user-facing.')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
@@ -2317,7 +2236,7 @@ driveCommand
 
 const siteCommand = program
   .command('site')
-  .description('Site lifecycle management: init, upload, status, list, delete');
+  .description('Build and publish your app\'s website');
 
 // site init - Copy scaffold to app
 siteCommand
@@ -2432,7 +2351,13 @@ siteCommand
       // Import mime for content types
       const mime = (await import('mime-types')).default;
       const { GitUtils } = await import('@descix/sdk/integrations/git');
-      const gitUtils = new GitUtils(process.cwd());
+      // Provenance is read from the directory the FILES come from — the app root when a site
+      // manifest names the sources, else the -p directory — never the caller's cwd. Reading cwd
+      // recorded the WRONG repository's commit on every deploy made from outside the app repo
+      // (measured 2026-09-18: daita-docs, whose files live in DeSciX/daita, was stamped with the
+      // Unkamon commit it happened to be run from).
+      const provenanceDir = siteManifest ? appRoot : path.resolve(options.path);
+      const gitUtils = new GitUtils(provenanceDir);
       const gitStatus = await gitUtils.getStatus();
 
       let fileList;      // Array<{ path, hash, size, content_type }>
@@ -4271,7 +4196,7 @@ const mcpCommand = program
 mcpCommand
   .command('execute')
   .description('Execute a registered MCP tool by name with JSON parameters')
-  .requiredOption('--tool <name>', 'Tool/command name (e.g., beast_get_initiatives, beast_update_stream)')
+  .requiredOption('--tool <name>', 'Tool/command name (e.g., find_communities, ask_question_to_app)')
   .option('--params <json>', 'JSON parameters for the tool', '{}')
   .option('-a, --app <app_id>', 'App context (sets app_id in params if not already present)')
   .option('--json', 'Output raw JSON response')
@@ -4533,96 +4458,124 @@ devCertsCommand
 
 program
   .command('quickstart')
-  .description('One-command setup: auth → workspace → agent files → MCP config')
+  .description('One-command setup: sign in → workspace → app (with -c and -a) → agent files → MCP config')
   .option('-u, --url <url>', 'API URL override')
+  .option('-c, --community <id>', 'Community to create the app in')
+  .option('-a, --app <name>', 'Name of the app to create (the platform issues its id; see app init)')
+  .option('-y, --yes', 'Skip the confirmation — with -c and -a, quickstart runs without a terminal')
   .action(async (options) => {
-    const { generateAgentFiles, generateMcpConfig } = await import('../lib/agent-files.js');
-    const { WalletFileManager } = await import('../lib/wallet-file.js');
-
-    console.log(chalk.cyan('\n🚀 DeSciX Quickstart\n'));
-
-    const workspaceRoot = process.cwd();
-
-    // Step 1: Auth — login if no wallet.json
-    const walletPath = WalletFileManager.getWalletPath(workspaceRoot);
-    let needsLogin = true;
+    // Every failure prints as a message and exits 1 — never a stack trace. A new developer's AI
+    // assistant runs this non-interactively, and an uncaught refusal read as a crash (2026-09-19).
     try {
-      const wallet = await WalletFileManager.loadWalletFile(walletPath);
-      if (wallet && WalletFileManager.hasValidSession(wallet)) {
-        console.log(chalk.green(`✓ Already authenticated as ${wallet.userId}`));
-        needsLogin = false;
-      }
-    } catch { /* no wallet */ }
+      const { generateAgentFiles, generateMcpConfig, generateClaudeCodeMcpConfig } = await import('../lib/agent-files.js');
+      const { WalletFileManager } = await import('../lib/wallet-file.js');
 
-    if (needsLogin) {
-      const loginOptions = {};
-      if (options.url) loginOptions.url = options.url;
-      await authCommands.loginDevice(loginOptions);
-    }
+      console.log(chalk.cyan('\n🚀 DeSciX Quickstart\n'));
 
-    // Step 2: Workspace init — create workspace.json only when there is none ANYWHERE UP THE TREE.
-    //
-    // WHERE THE WORKSPACE ROOT IS has ONE OWNER: WorkspaceConfig.findWorkspaceRoot, which walks UP
-    // exactly as load() does. This step used to derive it a THIRD time with fs.access on the target
-    // path only (the wizard guard was the second). Run from a SUBDIRECTORY of an existing
-    // workspace, that check saw nothing, runInit created a NESTED workspace.json whose
-    // workspaceRoot pointed at the subdirectory, and it SHADOWED the parent for every later
-    // resolution — silently, with "Quickstart complete!" and exit 0.
-    //
-    // quickstart is an ONBOARDING flow: a user who asked to be set up and already IS set up has
-    // SUCCEEDED, so this SKIPS and REPORTS and continues.
-    const existingRoot = await WorkspaceConfig.findWorkspaceRoot(workspaceRoot);
-    if (existingRoot) {
-      console.log(chalk.green('✓ Workspace already initialized'));
-      if (path.resolve(existingRoot) !== path.resolve(workspaceRoot)) {
-        console.log(chalk.gray(`  Workspace root: ${existingRoot}`));
-        console.log(chalk.gray(`  You are in a subdirectory of it. Not creating a second workspace`));
-        console.log(chalk.gray(`  here — a nested one would shadow the root for every command run`));
-        console.log(chalk.gray(`  from this directory.`));
-      }
-    } else {
-      console.log(chalk.cyan('\n📋 Initialize Workspace\n'));
-      // runInit's signature is (apiClient, options). Passing a single object put it in the
-      // apiClient slot and left options defaulting to {}, so `path` was silently discarded and
-      // runInit fell back to process.cwd(). It was MASKED here only because workspaceRoot IS
-      // process.cwd() in this action — the argument was in the wrong slot regardless, and would
-      // have written the workspace to the wrong directory the moment that stopped being true.
-      // This action has no apiClient of its own; null is passed explicitly rather than implied.
-      await runInit(null, { path: workspaceRoot });
-    }
+      const workspaceRoot = process.cwd();
 
-    // EVERY REMAINING STEP TARGETS THE RESOLVED ROOT, not the directory the command was typed in.
-    // They read the workspace to learn the app, community and origin they must state, so pointing
-    // them at a subdirectory that deliberately has no workspace.json makes them hard-fail on the
-    // absence this command just chose to preserve. Resolving the root once and ferrying it is the
-    // same one-owner rule that fixed the check above.
-    const targetRoot = existingRoot || workspaceRoot;
-
-    // Step 3: Generate agent instruction files
-    console.log(chalk.cyan('\n📋 Generating Agent Instructions\n'));
-    const written = await generateAgentFiles(targetRoot);
-    for (const f of written) {
-      console.log(chalk.green(`  ✓ ${f}`));
-    }
+      // Step 1: Auth — login if no wallet.json
+      const walletPath = WalletFileManager.getWalletPath(workspaceRoot);
+      let needsLogin = true;
+      try {
+        const wallet = await WalletFileManager.loadWalletFile(walletPath);
+        if (wallet && WalletFileManager.hasValidSession(wallet)) {
+          console.log(chalk.green(`✓ Already authenticated as ${wallet.userId}`));
+          needsLogin = false;
+        }
+      } catch { /* no wallet */ }
 
-    // Step 4: Generate .vscode/mcp.json (skipped if DeSciX extension handles MCP)
-    const mcpWritten = await generateMcpConfig(targetRoot);
-    if (mcpWritten) {
-      console.log(chalk.green('  ✓ .vscode/mcp.json'));
-    } else {
-      console.log(chalk.green('  ✓ MCP handled by DeSciX extension (mcp.json skipped)'));
-    }
+      if (needsLogin) {
+        const loginOptions = {};
+        if (options.url) loginOptions.url = options.url;
+        await authCommands.loginDevice(loginOptions);
+      }
 
-    // Step 5: Copy SDK assets
-    const { pullSdkAssets } = await import('../lib/sdk-assets.js');
-    await pullSdkAssets(targetRoot);
-    console.log(chalk.green('  ✓ .descix/sdk-assets/'));
+      // Step 2: Workspace init — create workspace.json only when there is none ANYWHERE UP THE TREE.
+      //
+      // WHERE THE WORKSPACE ROOT IS has ONE OWNER: WorkspaceConfig.findWorkspaceRoot, which walks UP
+      // exactly as load() does. This step used to derive it a THIRD time with fs.access on the target
+      // path only (the wizard guard was the second). Run from a SUBDIRECTORY of an existing
+      // workspace, that check saw nothing, runInit created a NESTED workspace.json whose
+      // workspaceRoot pointed at the subdirectory, and it SHADOWED the parent for every later
+      // resolution — silently, with "Quickstart complete!" and exit 0.
+      //
+      // quickstart is an ONBOARDING flow: a user who asked to be set up and already IS set up has
+      // SUCCEEDED, so this SKIPS and REPORTS and continues.
+      const existingRoot = await WorkspaceConfig.findWorkspaceRoot(workspaceRoot);
+      if (existingRoot) {
+        console.log(chalk.green('✓ Workspace already initialized'));
+        if (path.resolve(existingRoot) !== path.resolve(workspaceRoot)) {
+          console.log(chalk.gray(`  Workspace root: ${existingRoot}`));
+          console.log(chalk.gray(`  You are in a subdirectory of it. Not creating a second workspace`));
+          console.log(chalk.gray(`  here — a nested one would shadow the root for every command run`));
+          console.log(chalk.gray(`  from this directory.`));
+        }
+      } else {
+        console.log(chalk.cyan('\n📋 Initialize Workspace\n'));
+        // runInit's signature is (apiClient, options). Passing a single object put it in the
+        // apiClient slot and left options defaulting to {}, so `path` was silently discarded and
+        // runInit fell back to process.cwd(). It was MASKED here only because workspaceRoot IS
+        // process.cwd() in this action — the argument was in the wrong slot regardless, and would
+        // have written the workspace to the wrong directory the moment that stopped being true.
+        // This action has no apiClient of its own; null is passed explicitly rather than implied.
+        await runInit(null, { path: workspaceRoot, community: options.community, app: options.app, yes: options.yes, env: program.opts().env });
+      }
+
+      // EVERY REMAINING STEP TARGETS THE RESOLVED ROOT, not the directory the command was typed in.
+      // They read the workspace to learn the app, community and origin they must state, so pointing
+      // them at a subdirectory that deliberately has no workspace.json makes them hard-fail on the
+      // absence this command just chose to preserve. Resolving the root once and ferrying it is the
+      // same one-owner rule that fixed the check above.
+      const targetRoot = existingRoot || workspaceRoot;
+
+      // Step 3: The app, and the agent instruction files that state its id. The id is the
+      // platform's, so the files are written only once the workspace names one it issued: from the
+      // workspace when an app is already registered, or by `app init` (the one owner, which writes
+      // them itself) when -c and -a name the app to create.
+      const { readIdentity, isIdentityNamed } = await import('../lib/workspace-identity.js');
+      const wsRaw = JSON.parse(await fs.readFile(path.join(targetRoot, '.descix', 'workspace.json'), 'utf-8'));
+      if (isIdentityNamed(readIdentity(wsRaw))) {
+        console.log(chalk.cyan('\n📋 Generating Agent Instructions\n'));
+        const written = await generateAgentFiles(targetRoot);
+        for (const f of written) {
+          console.log(chalk.green(`  ✓ ${f}`));
+        }
+      } else if (options.community && options.app) {
+        console.log(chalk.cyan('\n📋 Create and initialize the app\n'));
+        const apiClient = new DeSciXApiClient();
+        await requireAuth(apiClient);
+        await runAppInit(apiClient, { app: options.app, community: options.community });
+      } else {
+        console.log(chalk.yellow('\n  No app yet, so no agent instruction files (they state its id). Next:'));
+        console.log(chalk.white('    descix app init -a <name> -c <community>'));
+      }
 
-    // Done
-    console.log(chalk.green('\n✅ Quickstart complete!\n'));
-    console.log(chalk.white('Open your editor — the AI knows about DeSciX.\n'));
-    console.log(chalk.gray('  Copilot / Cline / Claude Code will have DeSciX MCP tools'));
-    console.log(chalk.gray('  Ask: "What DeSciX tools do I have?"\n'));
+      // Step 4: Generate .vscode/mcp.json (skipped if DeSciX extension handles MCP)
+      const mcpWritten = await generateMcpConfig(targetRoot);
+      if (mcpWritten) {
+        console.log(chalk.green('  ✓ .vscode/mcp.json'));
+      } else {
+        console.log(chalk.green('  ✓ MCP handled by DeSciX extension (mcp.json skipped)'));
+      }
+      // Claude Code reads project MCP servers from .mcp.json — written regardless of the VS Code case.
+      await generateClaudeCodeMcpConfig(targetRoot);
+      console.log(chalk.green('  ✓ .mcp.json (Claude Code)'));
+
+      // Step 5: Copy SDK assets
+      const { pullSdkAssets } = await import('../lib/sdk-assets.js');
+      await pullSdkAssets(targetRoot);
+      console.log(chalk.green('  ✓ .descix/sdk-assets/'));
+
+      // Done
+      console.log(chalk.green('\n✅ Quickstart complete!\n'));
+      console.log(chalk.white('Open your editor — the AI knows about DeSciX.\n'));
+      console.log(chalk.gray('  Copilot / Cline / Claude Code will have DeSciX MCP tools'));
+      console.log(chalk.gray('  Ask: "What DeSciX tools do I have?"\n'));
+    } catch (error) {
+      console.error(chalk.red(`\n❌ ${error.message}\n`));
+      process.exit(1);
+    }
   });
 
 // ============ MCP Server Command (for npx usage) ============

package/bin/mcp-server.js

@@ -31,7 +31,7 @@ import * as path from 'path';
 // This stdio server imports them and CONCATENATES its CLI-LOCAL diagnostics (descix_doctor,
 // platform_health) which are NOT /apifront commands and are intentionally stdio-only.
 // The previously hand-duplicated curated literal in this file is GONE.
-import { toMcpToolList, NATIVE_MCP_TOOLS as SHARED_NATIVE_TOOLS, MCP_HANDSHAKE_INSTRUCTIONS, validateToolParams, toolAcceptsParam, VALIDATION_PHASE } from '@descix/platform-api/mcp-tools';
+import { toMcpToolList, NATIVE_MCP_TOOLS as SHARED_NATIVE_TOOLS, MCP_HANDSHAKE_INSTRUCTIONS, validateToolParams, toolAcceptsParam, VALIDATION_PHASE, isDiscoveryCoreTool } from '@descix/platform-api/mcp-tools';
 
 // ---------------------------------------------------------------------------
 // Tool definitions for the stdio MCP transport.
@@ -77,9 +77,20 @@ const CLI_LOCAL_TOOLS = [
   },
 ];
 
-// Final stdio tool list: CLI-local diagnostics + the shared curated core tools (protocol shape).
+// Every tool this server can DESCRIBE: CLI-local diagnostics + the shared curated core. It seeds
+// the schema-aware tools/call path below, and is NEVER advertised as a whole.
 const TOOLS = [...CLI_LOCAL_TOOLS, ...toMcpToolList(SHARED_NATIVE_TOOLS)];
 
+// What tools/list ADVERTISES when the backend cannot supply the caller's permission-filtered
+// list — which is every UNAUTHENTICATED session, i.e. an outside developer's first contact.
+// It is the ratified DISCOVERY-CORE floor (platform-api isDiscoveryCoreTool, the same floor the
+// server serves a caller with no grant), never the whole static catalogue: advertising all of
+// TOOLS showed 37 tools, 18 of them the internal coordination fabric's (measured 2026-09-19).
+const FALLBACK_ADVERTISED_TOOLS = [
+  ...CLI_LOCAL_TOOLS,
+  ...toMcpToolList(SHARED_NATIVE_TOOLS.filter((t) => isDiscoveryCoreTool(t.name))),
+];
+
 // Live tool surface as last returned by tools/list (permission-filtered by the backend).
 // Seeded with the static curated SSOT so the very first tools/call is schema-aware even if
 // no tools/list preceded it. Consumed by tools/call for schema-aware context injection and
@@ -410,8 +421,8 @@ try {
       console.error(`[MCP] tools/list — ${backendTools.length} permission-filtered backend tools + ${CLI_LOCAL_TOOLS.length} CLI-local = ${tools.length}`);
       return { tools };
     } catch (err) {
-      console.error(`[MCP] tools/list — backend unreachable (${err.message}); falling back to static curated core (${TOOLS.length} tools)`);
-      return { tools: TOOLS };
+      console.error(`[MCP] tools/list — backend unreachable (${err.message}); advertising the discovery-core floor (${FALLBACK_ADVERTISED_TOOLS.length} tools)`);
+      return { tools: FALLBACK_ADVERTISED_TOOLS };
     }
   });
 

package/lib/agent-files.js

@@ -11,6 +11,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { readIdentity, isIdentityNamed } from './workspace-identity.js';
+import { mcpServerEntry } from './invocation.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -163,12 +164,31 @@ export async function generateMcpConfig(workspaceRoot) {
   }
 
   // Add/update DeSciX MCP server
-  existing.servers['descix'] = {
-    command: 'descix',
-    args: ['mcp-serve'],
-  };
+  existing.servers['descix'] = mcpServerEntry();
 
   await fs.mkdir(path.dirname(outputPath), { recursive: true });
   await fs.writeFile(outputPath, JSON.stringify(existing, null, 2), 'utf-8');
   return true;
 }
+
+/**
+ * Claude Code's PROJECT MCP config: `.mcp.json` at the project root, `{ mcpServers: { … } }`.
+ * Written independently of the VS Code file above (whose DeSciX-extension skip does not apply to
+ * Claude Code). Existing servers are preserved; only the `descix` entry is set.
+ *
+ * @param {string} workspaceRoot
+ * @returns {Promise<boolean>} true when written
+ */
+export async function generateClaudeCodeMcpConfig(workspaceRoot) {
+  const outputPath = path.join(workspaceRoot, '.mcp.json');
+  let existing = { mcpServers: {} };
+  try {
+    existing = JSON.parse(await fs.readFile(outputPath, 'utf-8'));
+    if (!existing.mcpServers) existing.mcpServers = {};
+  } catch {
+    // No existing file — start fresh
+  }
+  existing.mcpServers.descix = mcpServerEntry();
+  await fs.writeFile(outputPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+  return true;
+}

package/lib/auth-guard.js

@@ -29,7 +29,7 @@ export async function requireAuth(apiClient) {
   
   if (!apiClient.hasCredentials()) {
     console.error(chalk.red('\n  Authentication required.\n'));
-    console.error(chalk.white('  Please sign up with DeSciX to use this feature.\n'));
+    console.error(chalk.white('  Sign in to use this. On first use, signing in also creates your DeSciX account.\n'));
     console.error(chalk.cyan('  Run: descix login\n'));
     process.exit(1);
   }

package/lib/commands/appInit.js

@@ -0,0 +1,154 @@
+/**
+ * `descix app init` — THE path to an app (CEO-D-2026-08-14): creates the app when it does not exist
+ * yet, then registers and scaffolds it locally. `descix quickstart` runs the same function, so the
+ * two cannot disagree about what an initialized app is.
+ *
+ * THE APP ID IS THE SERVER'S. With -c, the -a value is a NAME and create_app_for_community composes
+ * the id ({community}-{short}); this module registers whatever id the server returns and never
+ * composes one. `descix init` used to record the NAME as the app id, so the workspace and CLAUDE.md
+ * named `myapp` while the platform held `daita-myapp` (devx review 2026-09-19, D2). The agent
+ * instruction files are therefore written HERE, after the id exists, and nowhere earlier.
+ */
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import path from 'path';
+import { WorkspaceConfig, resolveWorkspacePath } from '../workspace-config.js';
+import { refreshCommunityIdentity, printIdentityReceipt } from './communityIdentity.js';
+import { generateAgentFiles } from '../agent-files.js';
+
+/**
+ * @param {Object} apiClient an authenticated DeSciXApiClient
+ * @param {{app: string, community?: string, short?: string, overwrite?: boolean, kb?: string, path?: string}} options
+ * @returns {Promise<{appId: string, communityId: string, appPath: string, kbId: string}>}
+ */
+export async function runAppInit(apiClient, options) {
+  let appId = options.app;
+  const kbId = options.kb || 'General';
+
+  // Refuse an unusable -p BEFORE anything is written — server-side included. The same resolver
+  // the workspace loader applies on every read decides it, so a value accepted here is one the
+  // next read accepts too. Refusing only at registration came AFTER a `-c` create, leaving a
+  // platform app with no local registration (measured 2026-09-18, daita-docs).
+  const workspaceConfig = await WorkspaceConfig.tryLoad();
+  if (options.path) {
+    resolveWorkspacePath(workspaceConfig?.workspaceRoot || process.cwd(), options.path, appId);
+  }
+
+  // Resolve community_id from the Products registry to learn whether the app exists yet.
+  let communityId;
+  try {
+    const productCtx = await apiClient.invoke('get_product_context', { app_id: appId });
+    communityId = (productCtx.message || productCtx).community_id;
+  } catch (e) {
+    // Not in Products — either we create it below (-c given) or we fail loud.
+  }
+
+  if (!communityId) {
+    if (!options.community) {
+      throw new Error(
+        `App '${appId}' does not exist yet. Pass -c <community> to create it: ` +
+        `descix app init -a ${appId} -c <community> [-s <short>]`
+      );
+    }
+    // CREATE leg — the canonical server path. It composes the unique app_id
+    // ({community}-{short}) and is authoritative; we never compose it client-side.
+    const response = await apiClient.invoke('create_app_for_community', {
+      community_id: options.community,
+      app_name: appId,
+      short_name: options.short || undefined,
+      create_skeleton: false,
+      overwrite: options.overwrite,
+    });
+    const created = response.message || response;
+    appId = created.app_id || appId;
+    communityId = created.community_id || options.community;
+    console.log(chalk.green(`\n✅ App created: ${appId}`));
+    if (appId !== options.app) {
+      console.log(chalk.gray(`  The platform composed the id from the community and the name you gave.`));
+      console.log(chalk.gray(`  Use -a ${appId} in every later command.`));
+    }
+  } else if (options.community && options.community !== communityId) {
+    throw new Error(
+      `App '${appId}' already exists in community '${communityId}', not '${options.community}'. ` +
+      `Omit -c to initialize the existing app.`
+    );
+  }
+
+  // 1. Workspace.json — register app if not already mapped
+  const alreadyMapped = workspaceConfig?.getAppByAppId(appId);
+  let appPath = alreadyMapped?.absolutePath;
+
+  if (alreadyMapped && options.path) {
+    throw new Error(
+      `App '${appId}' is already mapped to '${alreadyMapped.localPath}'. ` +
+      `Use 'descix app set-localpath -a ${appId} -p <new-path>' to update.`
+    );
+  }
+
+  const wsRoot = workspaceConfig?.workspaceRoot || process.cwd();
+  if (!alreadyMapped) {
+    const localPath = options.path || '.';
+    const cfg = workspaceConfig || new WorkspaceConfig({}, wsRoot);
+    cfg.registerApp(communityId, appId, { localPath, kbId });
+    await cfg.save(wsRoot);
+    appPath = path.resolve(wsRoot, localPath);
+    console.log(chalk.gray(`  workspace.json updated: ${appId} → ${localPath}`));
+  }
+
+  // 2. Create app folder structure (site, microservice, assets)
+  const assetsDir = path.join(appPath, 'assets');
+  await fs.mkdir(path.join(appPath, 'site'), { recursive: true });
+  await fs.mkdir(path.join(appPath, 'microservice'), { recursive: true });
+  await fs.mkdir(assetsDir, { recursive: true });
+  const siPath = path.join(assetsDir, 'system_instructions.md');
+  const descPath = path.join(assetsDir, 'app_description.md');
+  try {
+    await fs.access(siPath);
+  } catch {
+    await fs.writeFile(siPath, `# System Instructions for ${appId}\n\nYou are an AI assistant for the ${appId} application.\n`);
+  }
+  try {
+    await fs.access(descPath);
+  } catch {
+    await fs.writeFile(descPath, `# ${appId}\n\nApplication description goes here.\n`);
+  }
+  console.log(chalk.gray(`  Created: site/, microservice/, assets/`));
+
+  // 3. Create KnowledgeBase Firestore doc (Git Mode — no Drive required)
+  const kbResponse = await apiClient.invoke('init_git_mode_kb', { app_id: appId, kb_name: kbId });
+  const kbResult = kbResponse.message || kbResponse;
+
+  console.log(chalk.green(`\n✓ ${appId} initialized`));
+  console.log(chalk.gray(`  Community: ${communityId}`));
+
+  // A community's OWN app (app_id == community_id) mirrors its token symbol and icon from the
+  // env-invariant descix-chain registry into this environment (CEO 2026-09-19). The app is
+  // already initialized; a refusal here (not an admin of the community, or the community not in
+  // the registry) is reported with the command that retries it, not treated as an init failure.
+  if (appId === communityId) {
+    try {
+      printIdentityReceipt(communityId, await refreshCommunityIdentity(apiClient, communityId));
+    } catch (err) {
+      console.log(chalk.yellow(`\n  ⚠ Community identity not mirrored: ${err.message}`));
+      console.log(chalk.gray(`    Retry with: descix community refresh-identity -c ${communityId}`));
+    }
+  }
+  console.log(chalk.gray(`  KB: ${kbId} — ${kbResult.created ? 'created' : 'already exists'}\n`));
+  console.log(chalk.gray(`  (every app is guaranteed a default KB at creation; an empty one`));
+  console.log(chalk.gray(`   says so rather than answering from general knowledge)\n`));
+
+  // 4. Agent instruction files, now that the workspace names an id the platform issued. Files the
+  // developer has customised (no BOOTSTRAP marker) are left alone by generateAgentFiles.
+  const written = await generateAgentFiles(wsRoot);
+  for (const f of written) console.log(chalk.green(`  ✓ ${f}`));
+
+  console.log(chalk.cyan('\nNext steps:'));
+  // The manifest lives in THIS app's registered directory — never a guessed `apps/<id>/`,
+  // which named a path that does not exist for any app registered elsewhere.
+  const manifestPath = path.join(appPath, '.descix', 'manifests', `${kbId}.json`);
+  console.log(chalk.gray(`  Create a corpus manifest at ${path.relative(process.cwd(), manifestPath) || manifestPath}`));
+  console.log(chalk.gray(`  then run:`));
+  console.log(chalk.white(`  descix kb corpus sync -a ${appId}\n`));
+
+  return { appId, communityId, appPath, kbId };
+}

package/lib/commands/communityIdentity.js

@@ -0,0 +1,45 @@
+/**
+ * Mirror a community's IDENTITY — token symbol and icon — from the env-invariant descix-chain
+ * registry into the current environment's records (CEO 2026-09-19).
+ *
+ * ONE owner for both callers: `descix app init` (run for a community's own app) and
+ * `descix community refresh-identity`. The server reads the registry and verifies the icon
+ * actually serves (update_community_metadata with from_registry); this module only asks and
+ * reports, so the receipt shows what the SERVER read and wrote, never what we hoped.
+ */
+import chalk from 'chalk';
+
+/**
+ * @param {Object} apiClient
+ * @param {string} communityId
+ * @returns {Promise<Object>} the server's `registry` block
+ * @throws {Error} when the server returns no registry block — an unreported mirror is not a mirror
+ */
+export async function refreshCommunityIdentity(apiClient, communityId) {
+  const response = await apiClient.invoke('update_community_metadata', {
+    community_id: communityId,
+    from_registry: true,
+  });
+  const result = response.message || response;
+  if (!result || !result.registry) {
+    throw new Error(
+      `update_community_metadata returned no registry block for '${communityId}' — the server did ` +
+      `not report what it mirrored, so nothing can be claimed about it.`);
+  }
+  return result.registry;
+}
+
+/** Print what was read from the registry and what changed in this environment. */
+export function printIdentityReceipt(communityId, registry) {
+  const { token_symbol, icon_url, icon_status, before, community_app_updated } = registry;
+  console.log(chalk.cyan(`\n  Identity for ${communityId} (from the descix-chain registry):`));
+  const sym = before?.token_symbol === token_symbol ? 'unchanged' : `was ${before?.token_symbol ?? 'unset'}`;
+  console.log(chalk.gray(`    Token symbol: ${token_symbol}  (${sym})`));
+  if (icon_url) {
+    const ic = before?.icon_url === icon_url ? 'unchanged' : 'updated';
+    console.log(chalk.gray(`    Icon:         ${icon_url}  (${ic}, ${icon_status})`));
+  } else {
+    console.log(chalk.yellow(`    Icon:         not written — the registry icon is ${icon_status}. The store shows a monogram.`));
+  }
+  console.log(chalk.gray(`    Community app record: ${community_app_updated ? 'updated' : 'not found in this environment'}`));
+}

package/lib/commands/init.js

@@ -11,13 +11,12 @@ import { fileURLToPath } from 'url';
 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';
 // "May I prompt?" has ONE OWNER. init does not derive it, and holds no TTY check of its own.
-import { createPromptSession } from '../interactive.js';
+import { createLazyPromptSession } from '../interactive.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,13 +27,15 @@ const __dirname = dirname(__filename);
  * @param {Object} options - Command options
  */
 export async function runInit(apiClient, options = {}) {
-  // The session is GATED AT CONSTRUCTION: under a non-TTY this throws NonInteractiveError,
-  // which bin/descix.js's init action prints and exits 1 on. It can no longer hang on an open
-  // pipe/FIFO, nor exit 0 writing nothing on /dev/null.
-  const rl = createPromptSession({
+  // The session is built only when a question is actually asked, and is still gated then: under
+  // a non-TTY an unanswered question throws NonInteractiveError (bin/descix.js prints it and
+  // exits 1) — it can never hang on an open pipe, nor exit 0 having written nothing. With every
+  // answer given as a flag, nothing is asked, so an AI assistant or a script can run init.
+  const rl = createLazyPromptSession({
     what: 'descix init',
     nonInteractiveForm: [
-      'descix init has no non-interactive form today. Run it in a terminal.',
+      'descix init -c <community> -a <app> --yes',
+      '  (add --force to replace an existing .descix/workspace.json)',
       '',
       'Nothing has been changed. An existing .descix/workspace.json is left as it is.'
     ]
@@ -105,14 +106,12 @@ export async function runInit(apiClient, options = {}) {
       // No existing config
     }
 
-    if (hasExisting && !options.force) {
-      const overwrite = await rl.askYesNo(chalk.yellow('Workspace already initialized. Overwrite?'), false);
-      if (!overwrite) {
-        console.log(chalk.gray('\nInitialization cancelled.\n'));
-        rl.close();
-        return {};
-      }
-    }
+    // An existing workspace is EXTENDED, never replaced. It may carry the environment the developer
+    // chose with `descix config init --env dev` — env.apiUrl / env.environment, owned by the config
+    // verbs — and init used to write a brand-new file over it, silently moving a DEV workspace to
+    // PROD (measured 2026-09-19: DEV before, `config show` said prod after). --force now restarts
+    // only the APP registrations; the environment is kept either way.
+    const existingConfig = hasExisting ? await WorkspaceConfig.load(projectPath) : null;
 
     let communityId = options.community;
     if (!communityId) {
@@ -151,42 +150,48 @@ export async function runInit(apiClient, options = {}) {
       }
     }
 
-    const appId = appName.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
     console.log(chalk.cyan('\n─── Summary ───\n'));
     console.log(chalk.white(`  Project:   ${projectPath}`));
     console.log(chalk.white(`  Community: ${communityId}`));
-    console.log(chalk.white(`  App:       ${appName} (${appId})`));
+    console.log(chalk.white(`  App name:  ${appName}`));
 
-    const proceed = await rl.askYesNo(chalk.white('\nProceed?'), true);
+    const proceed = options.yes ? true : await rl.askYesNo(chalk.white('\nProceed?'), true);
     if (!proceed) {
       console.log(chalk.gray('\nCancelled.\n'));
       rl.close();
       return {};
     }
 
-    console.log(chalk.gray('\nWriting .descix/workspace.json...\n'));
-    const config = new WorkspaceConfig({ version: '2.0', type: 'workspace', communities: {} }, projectPath);
-    config.registerApp(communityId, appId, { localPath: '.', kbId: 'General' });
+    console.log(chalk.gray(`\n${existingConfig ? 'Updating' : 'Writing'} .descix/workspace.json...\n`));
+    const config = existingConfig || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, projectPath);
+    if (existingConfig && options.force && config.env) {
+      config.env.products = [];
+      delete config.env.platform;
+    }
+    // NO APP IS REGISTERED HERE. The app id is the platform's: `app init` creates the app and
+    // registers the id the server returns (with -c it is composed from the community and the
+    // name). Recording the NAME here as the id left the workspace and CLAUDE.md naming an app the
+    // platform does not have (devx review 2026-09-19, D2). The agent instruction files state that
+    // id, so `app init` writes them too, once it exists.
     await config.save(projectPath);
+    // A NEW workspace records the environment this run used (`descix --env dev init …`), through
+    // the same owner `config init` uses — otherwise the workspace carried no environment and the
+    // very next command fell back to PROD, although the developer had just chosen DEV. An EXISTING
+    // workspace keeps its own environment: that choice belongs to the config verbs.
+    if (!existingConfig && options.env) {
+      await config.setEnvironment(options.env);
+    }
 
-    console.log(chalk.green('Created:'));
+    console.log(chalk.green(`${existingConfig ? 'Updated' : 'Created'}:`));
     console.log(chalk.green('  ✓ .descix/workspace.json'));
 
-    // Generate agent instruction files with correct context
-    try {
-      const agentFilesWritten = await generateAgentFiles(projectPath);
-      for (const f of agentFilesWritten) {
-        console.log(chalk.green(`  ✓ ${f}`));
-      }
-    } catch {
-      // Agent file generation is best-effort
-    }
-
     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.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.white(`  1. descix login                                  # if you are not signed in`));
+    console.log(chalk.white(`  2. descix app init -a ${appName} -c ${communityId}`));
+    console.log(chalk.gray(`     Creates the app and registers the id the platform issues for it (with -c the`));
+    console.log(chalk.gray(`     id is ${communityId}-<name>), then writes CLAUDE.md and the other agent files.`));
+    console.log(chalk.gray(`  3. Create the corpus manifest app init names, then:`));
+    console.log(chalk.white(`     ${CANONICAL_KB_SYNC} -a <the id app init printed>\n`));
     console.log(chalk.green('✅ Workspace initialized.\n'));
     rl.close();
     return { created: ['.descix/workspace.json'], skipped: [], warnings: [] };
@@ -197,38 +202,4 @@ export async function runInit(apiClient, options = {}) {
   }
 }
 
-/**
- * Non-interactive init: writes .descix/workspace.json only.
- * @param {Object} options - { path?, communityId, appName? }
- * @returns {Promise<Object>} { created, skipped, warnings }
- */
-export async function initWorkspace(options) {
-  const projectPath = options.path ? path.resolve(options.path) : process.cwd();
-  const communityId = options.communityId;
-  const appName = options.appName || path.basename(projectPath).toLowerCase().replace(/[^a-z0-9]/g, '_');
-  const appId = appName.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
-  if (!communityId) {
-    throw new Error('communityId is required');
-  }
-  const config = new WorkspaceConfig({ version: '2.0', type: 'workspace', communities: {} }, projectPath);
-  config.registerApp(communityId, appId, { localPath: '.', kbId: 'General' });
-  await config.save(projectPath);
-
-  // Generate agent instruction files with workspace context
-  const created = ['.descix/workspace.json'];
-  try {
-    const agentFilesWritten = await generateAgentFiles(projectPath);
-    created.push(...agentFilesWritten);
-  } catch {
-    // Best-effort
-  }
-
-  return {
-    created,
-    skipped: [],
-    warnings: [],
-    nextSteps: [`descix app init -a ${appId} -c ${communityId}`, `${CANONICAL_KB_SYNC} -a ${appId}`]
-  };
-}
-
-export default { runInit, initWorkspace };
+export default { runInit };

package/lib/interactive.js

@@ -155,4 +155,26 @@ export function createPromptSession({ what, nonInteractiveForm, terminal, destru
   return { ask, askYesNo, askRaw, close: () => rl.close() };
 }
 
+/**
+ * A prompt session that is built only when a question is actually ASKED.
+ *
+ * `createPromptSession` gates at construction, which is right for a command that always
+ * prompts. A command whose every answer can arrive as a FLAG must not refuse a non-terminal
+ * before it knows it needs one: that made `descix init -c <c> -a <a>` impossible to run from an
+ * AI assistant or a script, although nothing was left to ask (measured 2026-09-19). The gate is
+ * unchanged, and still the one owner — this only defers WHEN it is consulted.
+ *
+ * @param {Object} o - exactly createPromptSession's options
+ * @returns {{ask: Function, askYesNo: Function, close: Function}}
+ */
+export function createLazyPromptSession(o = {}) {
+  let session = null;
+  const open = () => (session ||= createPromptSession(o));
+  return {
+    ask: (...args) => open().ask(...args),
+    askYesNo: (...args) => open().askYesNo(...args),
+    close: () => { if (session) session.close(); },
+  };
+}
+
 export default { stdinIsInteractive, requireInteractive, createPromptSession, NonInteractiveError };

package/lib/invocation.js

@@ -0,0 +1,26 @@
+/**
+ * HOW A DEVELOPER (OR THEIR AI ASSISTANT) RUNS THIS CLI — the one owner.
+ *
+ * The npm package is `@descix/cli`; the binary it installs is `descix`. There is no npm package
+ * named `descix`, so `npx descix …` is a 404 — and it was typed, independently, into the
+ * "workspace not configured" remedy, the CLAUDE.md template and the docs (devx review 2026-09-19).
+ * The editor MCP config meanwhile used a bare `descix`, which exists only after a GLOBAL install,
+ * so an npx user's editor could not start the server.
+ *
+ * `npx -y -p @descix/cli descix …` works for both: with a global install npx finds the binary, and
+ * without one it fetches the package. `-y` stops npx from prompting, which an editor launching an
+ * MCP server (or an agent running a command) cannot answer.
+ */
+export const CLI_PACKAGE = '@descix/cli';
+export const CLI_BIN = 'descix';
+const NPX_PREFIX = ['-y', '-p', CLI_PACKAGE, CLI_BIN];
+
+/** `npx -y -p @descix/cli descix <args…>` as one string, for a message a person copies. */
+export function npxCommand(...args) {
+  return ['npx', ...NPX_PREFIX, ...args].join(' ');
+}
+
+/** The MCP server entry every editor config uses: VS Code `.vscode/mcp.json`, Claude Code `.mcp.json`. */
+export function mcpServerEntry() {
+  return { command: 'npx', args: [...NPX_PREFIX, 'mcp-serve'] };
+}

package/lib/verb-invokes.generated.json

@@ -11,7 +11,8 @@
   "app init": [
     "create_app_for_community",
     "get_product_context",
-    "init_git_mode_kb"
+    "init_git_mode_kb",
+    "update_community_metadata"
   ],
   "app invite": [
     "create_app_invite"
@@ -90,6 +91,9 @@
   "community list": [
     "find_communities"
   ],
+  "community refresh-identity": [
+    "update_community_metadata"
+  ],
   "community rename": [
     "rename_community"
   ],
@@ -186,11 +190,15 @@
     "fetch_my_purchases"
   ],
   "quickstart": [
+    "create_app_for_community",
     "device_check_status",
     "device_request_login",
     "find_communities",
+    "get_product_context",
+    "init_git_mode_kb",
     "resolve_invite",
-    "sync_auto_purchases"
+    "sync_auto_purchases",
+    "update_community_metadata"
   ],
   "reconnect": [
     "reconnect_by_wallet"

package/lib/workspace-config.js

@@ -6,6 +6,7 @@ import { resolveOrigin } from './origin.js';
 // 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';
+import { npxCommand } from './invocation.js';
 
 /**
  * THE ONE OWNER of "this app is not mapped in workspace.json, here is how to fix it".
@@ -61,7 +62,7 @@ export function resolveWorkspacePath(workspaceRoot, localPath, label = 'app') {
  */
 const NOT_CONFIGURED_MESSAGE =
   'Workspace not configured.\n' +
-  'Run "npx descix init" first to initialize your workspace.';
+  `Run "${npxCommand('init')}" first to initialize your workspace.`;
 
 /**
  * THE ONE OWNER of "how do I set the API origin". Named by every refusal that turns a developer

package/package.json

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

package/templates/agent-claude.md

@@ -84,15 +84,18 @@ Use `find_communities` and `list_apps_for_community` to show options, then ask:
 > "Which community and app should this project target?"
 
 ### Checkpoint 3: Environment
-> "Should this run against local dev backend (localhost:4000) or hosted API?"
+> "Should this app be built against DEV (https://dev.descix.net) or production?"
+
+Pin the choice before anything else; every later command reads it from the workspace.
 
 ### Canonical Setup Commands (run in terminal after checkpoints)
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the app id the platform issued (with `-c` it is `<community>-<name>`). Use that
+id, not the name, as `-a` in every later command.
 
 ### Checkpoint 4: Content Strategy
 > "Should I create a starter KB doc now, or wait for your domain docs?"
@@ -317,15 +320,22 @@ Follow Checkpoint 4 from the doctor's `next_steps`:
 ### If `claude_code_detected` is true (Claude Code environment)
 Also create these files for always-on dynamic alignment:
 
-**`.claude/settings.json`** (merge with existing if present):
+**`.mcp.json`** at the project root — Claude Code reads PROJECT MCP servers from this file, not from
+`.claude/settings.json` (`descix quickstart` writes it for you; merge with existing if present):
 ```json
 {
   "mcpServers": {
     "descix": {
       "command": "npx",
-      "args": ["descix", "mcp-serve"]
+      "args": ["-y", "-p", "@descix/cli", "descix", "mcp-serve"]
     }
-  },
+  }
+}
+```
+
+**`.claude/settings.json`** (merge with existing if present):
+```json
+{
   "hooks": {
     "UserPromptSubmit": [
       {

package/templates/agent-cline.md

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"

package/templates/agent-copilot.md

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"

package/templates/agent-cursor.md

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"