@descix/cli 1.0.16 → 1.0.17

package/bin/descix.js

@@ -34,6 +34,7 @@ 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';
@@ -1082,131 +1083,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 +4458,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 +4529,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)

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 };

package/lib/verb-invokes.generated.json

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

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.16",
+  "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?"

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)?"