@descix/cli 1.0.15 → 1.0.16

package/bin/descix.js

@@ -33,6 +33,7 @@ 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 { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
@@ -199,7 +200,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 +214,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 +463,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')
@@ -1067,6 +1085,15 @@ appCommand
       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 {
@@ -1106,7 +1133,6 @@ appCommand
       }
 
       // 1. Workspace.json — register app if not already mapped
-      const workspaceConfig = await WorkspaceConfig.tryLoad();
       const alreadyMapped = workspaceConfig?.getAppByAppId(appId);
       let appPath = alreadyMapped?.absolutePath;
 
@@ -1158,11 +1184,27 @@ appCommand
 
       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`));
       console.log(chalk.cyan('Next steps:'));
-      console.log(chalk.gray(`  Create a corpus manifest at apps/${appId}/.descix/manifests/${kbId}.json`));
+      // 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`));
     } catch (error) {
@@ -2177,17 +2219,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 +2359,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 +2474,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 +4319,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')
@@ -4535,94 +4583,107 @@ program
   .command('quickstart')
   .description('One-command setup: auth → workspace → agent files → MCP config')
   .option('-u, --url <url>', 'API URL override')
+  .option('-c, --community <id>', 'Community ID for the new workspace')
+  .option('-a, --app <name>', 'App name for the new workspace')
+  .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 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)'));
-    }
+      // 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 5: Copy SDK assets
-    const { pullSdkAssets } = await import('../lib/sdk-assets.js');
-    await pullSdkAssets(targetRoot);
-    console.log(chalk.green('  ✓ .descix/sdk-assets/'));
+      if (needsLogin) {
+        const loginOptions = {};
+        if (options.url) loginOptions.url = options.url;
+        await authCommands.loginDevice(loginOptions);
+      }
 
-    // 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 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: 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 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/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

@@ -17,7 +17,7 @@ import { generateAgentFiles } from '../agent-files.js';
 // 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 +28,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 +107,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) {
@@ -157,17 +157,28 @@ export async function runInit(apiClient, options = {}) {
     console.log(chalk.white(`  Community: ${communityId}`));
     console.log(chalk.white(`  App:       ${appName} (${appId})`));
 
-    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);
+    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;
+    }
     config.registerApp(communityId, appId, { localPath: '.', kbId: 'General' });
     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('  ✓ .descix/workspace.json'));

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"
   ],

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.16",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",

package/templates/agent-claude.md

@@ -317,15 +317,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": [
       {