@descix/cli 1.0.16 → 1.0.18

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

@@ -10,7 +10,7 @@ This document covers how AI agents interact with the DeSciX platform via MCP (Mo
 
 ## 1. Architecture Overview
 
-DeSciX operates as a **Federated MCP Service Mesh**. The `DeSciX_Cloud` backend acts as a broker that aggregates tools from all registered microservices into a unified catalog.
+DeSciX operates as a **Federated MCP Service Mesh**. The DeSciX backend acts as a broker that aggregates tools from all registered microservices into a unified catalog.
 
 **Key Innovation:** AI agents discover and invoke capabilities across the entire mesh without knowing where individual services are hosted.
 
@@ -24,7 +24,7 @@ AI Agent (Cursor/MCP Client)
    execute_remote_command
        │
        ▼
-   DeSciX_Cloud (Federated Broker)
+   DeSciX Backend (Federated Broker)
        │
        ├──► Service 1 (Powch)
        ├──► Service 2 (SmartModel)
@@ -42,9 +42,9 @@ MCP provides the communication protocol between AI agents and the DeSciX platfor
 **Key Tools:**
 - `tell_me_how` - Semantic tool discovery
 - `execute_remote_command` - Execute any backend command
-- `descix_init` - Initialize local workspace
-- `chat_with_kb` - Query knowledge bases
-- `search_knowledge_base` - Search specific KBs
+- `descix_doctor` - CLI-local startup diagnostic (auth, workspace, tools, warnings)
+- `ask_question_to_app` - RAG chat with an app's knowledge base (synthesized answer, cited)
+- `query_knowledge_base` - Raw vector search, returns chunks
 
 ### 2.2 Cursor/AI Agent Integration
 
@@ -91,13 +91,17 @@ Once signed in, `tell_me_how` is the **primary entry point** for discovering pla
 
 **Rule:** Sign in, then ask `tell_me_how` first, then execute the recommended command.
 
-### 3.2 Three Scopes
+### 3.2 Scopes
+
+The validated `tell_me_how` scope enum has five values:
 
 | Scope | Description | Use Case |
 |-------|-------------|----------|
-| `entitlements` (default) | Only tools user has access to | Production usage |
+| `entitlements` (default) | Only tools the user has access to | Production usage |
 | `project` | Tools filtered by workspace.json | Working within a project |
 | `discovery` | All available tools | Exploring capabilities |
+| `bootstrap` | Deterministic first-call on-ramp: platform summary, caller context, credit balance, essential tool schemas (no vector search; `question` is optional for this scope only) | First contact / first call in a session |
+| `artifact` | Deterministic build/reproduce provenance for a published app (npm package + spec, artifact/notebook URLs, runnable `npx` commands), no vector search | "How do I build on / reproduce this app?" |
 
 ### 3.3 CLI Usage
 
@@ -151,7 +155,7 @@ After `descix quickstart` completes:
 
 ### 4.1 Federated MCP Broker
 
-`DeSciX_Cloud` aggregates tools from all registered microservices:
+The DeSciX backend aggregates tools from all registered microservices:
 
 ```
 Microservice A
@@ -161,7 +165,7 @@ Microservice A
     Registers with Core
         │
         ▼
-DeSciX_Cloud (Broker)
+DeSciX Backend (Broker)
   └── Aggregated tools/list
         │
         ▼
@@ -199,14 +203,11 @@ execute_remote_command({
 
 ### 4.3 Service Registration
 
-Services self-register with the broker:
+Services self-register with the broker in one step — registration also vectorizes the README you
+pass, so there is no separate developer-facing vectorize step:
 
 ```bash
-# Register service manifest
-descix microservice register -m ./manifest.json
-
-# Vectorize SERVICE_README for discovery
-descix microservice vectorize -r SERVICE_README.md
+descix microservice register -r SERVICE_README.md
 ```
 
 ### 4.4 The execute_remote_command Pattern
@@ -309,11 +310,13 @@ When `--scope project` is used:
 
 ### 6.1 KB Operations via tell_me_how
 
-The new SDK V2 KB commands are discoverable:
+`tell_me_how` can be asked about KB sync in plain language, but the actionable answer for a
+developer is always the CLI verb, not the raw backend command names (`kb_sync_chunks` etc. are
+internal to the backend, not something the CLI calls directly by name):
 
 ```bash
 descix tell-me-how "How do I sync my knowledge base?"
-# Returns: kb_sync_chunks, kb_get_chunk_ids, kb_delete_chunks
+# The developer-facing command either way: descix kb corpus sync
 ```
 
 ### 6.2 workspace.json from Hydration
@@ -324,7 +327,7 @@ descix tell-me-how "How do I sync my knowledge base?"
 {
   "env": { "apiUrl": "https://dev.descix.net", "products": [ /* one entry per app */ ] },
   "driveConfig": {
-    "base_folder_id": "..."  // For tell_me_how project scope
+    "base_folder_id": "..."  // Only used by `descix drive pull/push` — unrelated to tell_me_how scope
   }
 }
 ```
@@ -334,9 +337,9 @@ descix tell-me-how "How do I sync my knowledge base?"
 Custom services integrate with the same pattern:
 
 1. Create `SERVICE_README_{name}.md`
-2. Register with `descix microservice register`
-3. Vectorize with `descix microservice vectorize`
-4. Tools become discoverable via `tell_me_how`
+2. Register with `descix microservice register -r SERVICE_README_{name}.md` — this both publishes
+   the manifest AND vectorizes the README in one step
+3. Tools become discoverable via `tell_me_how`
 
 ---
 
@@ -355,7 +358,8 @@ Custom services integrate with the same pattern:
 1. **Document all commands in SERVICE_README** - Required for discovery
 2. **Use clear descriptions** - "Use when:" is crucial for semantic matching
 3. **Include examples** - Helps AI agents understand usage
-4. **Register after changes** - Re-vectorize when README updates
+4. **Re-register after README changes** - `descix microservice register -r <file>` re-vectorizes
+   automatically; there is no separate vectorize step
 
 ### 7.3 Common Patterns
 
@@ -407,22 +411,11 @@ cd /path/to/workspace
 
 ### 8.3 "Command not found"
 
-**Cause:** Service not registered or command deprecated.
+**Cause:** Service not registered, or the README wasn't vectorized.
 
 **Solution:**
-1. Verify service is registered: `descix microservice list`
-2. Check if command was deprecated in V2
-3. Use `tell_me_how --scope discovery` to find alternatives
-
----
-
-## 9. File References
-
-| Component | Path |
-|-----------|------|
-| MCP Tools | `DeSciX_Core/descix-cli/bin/mcp-server.js` |
-| tell_me_how Implementation | `DeSciX_Cloud/microservice/services/commandHandlers/ragCommands.js` |
-| execute_remote_command | `DeSciX_Cloud/microservice/services/apiFront.js` |
-| SERVICE_README Template | `DeSciX_Core/descix-cli/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md` |
-| Workspace Config | `DeSciX_Core/descix-cli/lib/workspace-config.js` |
-| Service Registration | `DeSciX_Core/descix-cli/bin/descix.js` |
+1. Re-run `descix microservice register -r SERVICE_README_<name>.md` — it re-publishes the
+   manifest and re-vectorizes the README (`descix microservice list` exists to enumerate
+   registered services, but it is an admin-only command, not something a developer runs)
+2. Check `descix microservice health <name>` to confirm the service itself is reachable
+3. Use `descix tell-me-how --scope discovery "..."` to find alternatives

package/agent-assets/reference/workspace-config.md

@@ -160,13 +160,12 @@ descix site status -c egpt -a egpt-mydocs      # site status/list need both when
 
 ---
 
-## 7. File References
-
-| Component | Path | Description |
-|-----------|------|-------------|
-| WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | the loader, the v2.1 writer, `registerApp`, `detectContext` |
-| Origin resolution | `DeSciX_Core/descix-cli/lib/origin.js` | flag → `DESCIX_API_URL` → `env.apiUrl` → default |
-| GlobalConfig | `DeSciX_Core/descix-cli/lib/global-config.js` | user-level settings (`~/.descixrc`) |
-| Config commands | `DeSciX_Core/descix-cli/lib/commands/config.js` | `config init/set-env/set-*` |
-| Wallet file | `DeSciX_Core/descix-cli/lib/wallet-file.js` | `.descix/wallet.json` location |
-| Corpus sync | `DeSciX_Core/descix-cli/lib/commands/corpus.js` | manifests, sync-state |
+## 7. Where each concept lives (conceptual, not a file map)
+
+| Concept | Owner |
+|---|---|
+| Workspace loading, the v2.1 writer, app registration, context detection | `WorkspaceConfig`, internal to `@descix/cli` |
+| Origin resolution precedence | flag → `DESCIX_API_URL` → `env.apiUrl` → default (`descix config` commands) |
+| User-level settings (`~/.descixrc`) | `GlobalConfig`, internal to `@descix/cli` |
+| `.descix/wallet.json` | written by `descix login` |
+| Corpus manifests, sync-state | `descix kb corpus` commands, internal to `@descix/cli` |

package/bin/descix.js

@@ -34,6 +34,8 @@ 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 { assertKnownCommandForHelp } from '../lib/help-guard.js';
 import { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
@@ -1082,131 +1084,7 @@ appCommand
     try {
       const apiClient = new DeSciXApiClient();
       await requireAuth(apiClient);
-      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}`));
-        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 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}`));
-
-      // 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:'));
-      // 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`));
+      await runAppInit(apiClient, options);
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -4581,10 +4459,10 @@ 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 ID for the new workspace')
-  .option('-a, --app <name>', 'App name for the new workspace')
+  .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) => {
     // Every failure prints as a message and exits 1 — never a stack trace. A new developer's AI
@@ -4652,11 +4530,26 @@ program
       // 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 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>'));
       }
 
       // Step 4: Generate .vscode/mcp.json (skipped if DeSciX extension handles MCP)
@@ -4758,6 +4651,10 @@ if (!adminMode && isHelpInvocation(program, rawArgv, { valueFlags: ['--env', '--
   }
 }
 
+// A command that does not exist must not appear to have help (see lib/help-guard.js). This runs
+// before the parse, because Commander resolves --help before it resolves the command.
+assertKnownCommandForHelp(program, process.argv.slice(2));
+
 // Parse arguments
 await program.parseAsync(process.argv);
 

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/init.js

@@ -11,7 +11,6 @@ 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.
@@ -151,11 +150,10 @@ 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 = options.yes ? true : await rl.askYesNo(chalk.white('\nProceed?'), true);
     if (!proceed) {
@@ -170,7 +168,11 @@ export async function runInit(apiClient, options = {}) {
       config.env.products = [];
       delete config.env.platform;
     }
-    config.registerApp(communityId, appId, { localPath: '.', kbId: 'General' });
+    // 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
@@ -180,24 +182,16 @@ export async function runInit(apiClient, options = {}) {
       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: [] };
@@ -208,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 };