@descix/cli 1.0.21 → 2.0.0

package/bin/descix.js

@@ -1082,7 +1082,6 @@ appCommand
   .option('-s, --short <short_name>', 'SHORT id segment (no hyphens) used when creating; the app_id is composed server-side as {community}-{short}. Defaults to --app.')
   .option('--overwrite', 'When creating, overwrite an existing app record intentionally')
   .option('--kb <name>', 'Knowledge base name', 'General')
-  .option('-p, --path <dir>', 'Local app directory (default: auto-detected or cwd)')
   .action(async (options) => {
     try {
       const apiClient = new DeSciXApiClient();
@@ -1501,111 +1500,15 @@ appCommand
     }
   });
 
-appCommand
-  .command('set-localpath')
-  .description('Update the local directory path for a mapped app')
-  .requiredOption('-a, --app <app_id>', 'App ID')
-  .requiredOption('-p, --path <dir>', 'New local directory path')
-  .action(async (options) => {
-    try {
-      const appId = options.app;
-      const newPath = options.path;
-
-      const workspaceConfig = await WorkspaceConfig.load();
-      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
-
-      // Read the RAW registry entry, never the RESOLVED one. getAppByAppId() resolves the stored
-      // localPath, so on a workspace already carrying a rejected value it throws here — before
-      // any write is attempted. That is what made this verb refuse exactly when it was needed,
-      // while the rejection told the user to fix it with the config verb and never by hand.
-      // This command is about to REPLACE that value; it has no business resolving it.
-      //
-      // Display value only. setLocalPath() is the SINGLE authority on whether the app is mapped
-      // and refuses if it is not — deciding that here as well would be two derivations of one
-      // fact, and they would not even agree: _buildAppIdMap (behind getAppEntry) requires BOTH
-      // appId and localPath, while the live-entry walk matches on appId alone.
-      const oldPath = workspaceConfig.getAppEntry(appId)?.localPath;
-
-      // VALIDATE AT THE WRITE, through the LOADER'S OWN resolver — not a second copy of its rules.
-      // If resolveWorkspacePath would reject this value on the next read, it is rejected now, and
-      // nothing reaches disk. Writing a value the loader will refuse is what bricks a workspace.
-      const absPath = resolveWorkspacePath(wsRoot, newPath, appId);
-
-      // Hard-fail if path doesn't exist or is not a directory — checked at the path the LOADER
-      // will resolve to, not at a CWD-relative path that only exists from where you happened to
-      // be standing when you typed it.
-      let stat;
-      try {
-        stat = await fs.stat(absPath);
-      } catch {
-        throw new Error(
-          `Path does not exist: ${absPath}\n` +
-          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
-        );
-      }
-      if (!stat.isDirectory()) {
-        throw new Error(
-          `Path is not a directory: ${absPath}\n` +
-          `  (localPath '${newPath}' resolved against workspace root ${wsRoot})`
-        );
-      }
-
-      // Write through the canonical setter, which covers env.platform AND env.products[]. The
-      // loop this replaces walked env.products ONLY: on the platform app it matched nothing,
-      // wrote nothing, and still printed success — a loud failure turned into a silent lie at
-      // the one entry that matters most.
-      await workspaceConfig.setLocalPath(appId, newPath);
-
-      console.log(chalk.green(`\n✓ ${appId} local path updated`));
-      console.log(chalk.gray(`  ${oldPath} → ${newPath}\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
-appCommand
-  .command('unmap')
-  .description('Remove an app from the local workspace mapping (does not delete Firestore/Pinecone data)')
-  .requiredOption('-a, --app <app_id>', 'App ID')
-  .action(async (options) => {
-    try {
-      const appId = options.app;
-
-      const workspaceConfig = await WorkspaceConfig.load();
-      const appConfig = workspaceConfig.getAppByAppId(appId);
-      if (!appConfig) {
-        throw new Error(`App '${appId}' is not mapped.`);
-      }
-
-      // Remove from env.products
-      const products = workspaceConfig.env?.products || [];
-      const idx = products.findIndex(p => p.appId === appId || p.app_id === appId);
-      if (idx === -1) {
-        throw new Error(`App '${appId}' is not found in env.products.`);
-      }
-      products.splice(idx, 1);
-
-      const wsRoot = workspaceConfig.workspaceRoot || process.cwd();
-      await workspaceConfig.save(wsRoot);
-
-      console.log(chalk.green(`\n✓ ${appId} removed from workspace mapping`));
-      console.log(chalk.gray(`  Pinecone vectors, Firestore docs, and Drive data are not affected.\n`));
-    } catch (error) {
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  });
-
 // ============ App: set-port (WS-CLI-MESH-ROUTING-GAP) ============
 //
 // Canonical write path for an app's microservice.port in workspace.json.
-// `descix microservice init` READS env.products[<app>].microservice.port and hard-fails
+// `descix microservice init` READS env.app.microservice.port and hard-fails
 // if it is missing; this command is how that port is set, without hand-editing workspace.json.
 // Backed by WorkspaceConfig.setMicroservicePort.
 appCommand
   .command('set-port')
-  .description('Set the microservice port for a mapped app (writes env.products[<app>].microservice.port). Pass "n" to remove.')
+  .description('Set the microservice port for this workspace\'s app (writes env.app.microservice.port). Pass "n" to remove.')
   .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
   .requiredOption('-p, --port <port>', 'Microservice port number (1-65535), or "n" to remove')
   .action(async (options) => {
@@ -1632,7 +1535,7 @@ appCommand
 
       console.log(chalk.green(`\n✓ Microservice port set for ${appId}`));
       console.log(chalk.cyan(`  Port: ${portNum}`));
-      console.log(chalk.gray(`  Written to env.products[${appId}].microservice.port in workspace.json.`));
+      console.log(chalk.gray(`  Written to env.app.microservice.port in workspace.json.`));
       console.log(chalk.gray(`  The gateway routes the microservice on this port; \`descix microservice init -a ${appId}\` can now scaffold it.\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
@@ -1656,7 +1559,7 @@ appCommand
 // Backed by WorkspaceConfig.setStaticSite. It writes ONLY the local workspace.json site.{} slot.
 appCommand
   .command('set-site')
-  .description("Set a mapped app's site config (env.products[<app>].site). One active mode per write: --static <dir> (built site served at /p/<app>/) or --port <n> [--protocol http|https] (dev server proxied at /p/<app>); setting one clears the other. Pass both flags together to keep both — the gateway then serves the dev server (site.port wins). --unset clears site.{} entirely.")
+  .description("Set this workspace app's site config (env.app.site). One active mode per write: --static <dir> (built site served at /p/<app>/) or --port <n> [--protocol http|https] (dev server proxied at /p/<app>); setting one clears the other. Pass both flags together to keep both — the gateway then serves the dev server (site.port wins). --unset clears site.{} entirely.")
   .requiredOption('-a, --app <app_id>', 'App ID (must be mapped in workspace.json)')
   .option('--static <path>', 'Static mode: relative dir under the app localPath (e.g. "site"; "." = the localPath itself). Alone, it clears site.port and site.protocol (one active mode per write).')
   .option('--port <port>', 'Dev-server mode: proxy /p/<app> to your local dev server on this port (1-65535). Alone, it clears site.static. With --static in the same call, both are kept and the gateway serves the dev server.')
@@ -1715,9 +1618,7 @@ appCommand
       // Print the RESULTING slot, not just the fields passed: a dev-server write keeps a
       // previously declared site.protocol (same mode, new port), and a retained field the
       // output does not show is invisible state — the whole defect class this command fixes.
-      const entryNow = workspaceConfig.env?.platform?.appId === appId
-        ? workspaceConfig.env.platform
-        : (workspaceConfig.env?.products || []).find(p => p.appId === appId);
+      const entryNow = workspaceConfig.env?.app?.appId === appId ? workspaceConfig.env.app : null;
       console.log(chalk.cyan(`  site is now:   ${JSON.stringify(entryNow?.site)}`));
       if (fields.static !== undefined && fields.port === undefined) {
         console.log(chalk.gray(`  site.port and site.protocol cleared (one active mode per write) — /p/${appId}/ now serves the static dir.`));
@@ -1726,7 +1627,7 @@ appCommand
       } else if (fields.static !== undefined && fields.port !== undefined) {
         console.log(chalk.yellow(`  Combined write: BOTH modes kept. The gateway serves the DEV SERVER (site.port wins); site.static is used only after you clear site.port (--static alone, or --unset).`));
       }
-      console.log(chalk.gray(`  Written to env.products[${appId}].site in workspace.json; \`descix serve\` picks it up.\n`));
+      console.log(chalk.gray(`  Written to env.app.site in workspace.json; \`descix serve\` picks it up.\n`));
     } catch (error) {
       console.error(chalk.red(error.message));
       process.exit(1);
@@ -1741,9 +1642,9 @@ appCommand
 // Reuses the SDK resolver resolveAppGatewayUrl() — the same workspace.json read path
 // behind buildWorkspaceProducts() that the PWA bakes into __WORKSPACE_PRODUCTS__ — so
 // the URL matches what the app store routes to:
-//   - env.platform        → https://localhost:{gatewayPort}/
-//   - product (static)    → https://localhost:{gatewayPort}/p/{appId}
-//   - product (dev-server)→ https://localhost:{gatewayPort}/p/{appId}
+//   - the gateway shell   → https://localhost:{gatewayPort}/
+//   - an app (static)     → https://localhost:{gatewayPort}/p/{appId}
+//   - an app (dev-server) → https://localhost:{gatewayPort}/p/{appId}
 // Hard-fails clearly if the app is unmapped or has no site config.
 appCommand
   .command('open')
@@ -2857,13 +2758,7 @@ microserviceCommand
       // Hard-fail early if missing — a scaffolded microservice without a known port
       // cannot be routed by the gateway and cannot start on a deterministic port.
       const env = workspaceConfig.env || {};
-      let microservicePort = null;
-      if (env.platform?.appId === ctx.appId) {
-        microservicePort = env.platform?.microservice?.port || null;
-      } else if (Array.isArray(env.products)) {
-        const productEntry = env.products.find(p => p.appId === ctx.appId);
-        microservicePort = productEntry?.microservice?.port || null;
-      }
+      const microservicePort = env.app?.appId === ctx.appId ? (env.app.microservice?.port || null) : null;
 
       if (!microservicePort) {
         console.error(chalk.red(`\n❌ App '${ctx.appId}' has no microservice.port in workspace.json.`));
@@ -4206,7 +4101,7 @@ program
       // app_ids". `--scope project` was dead on this surface for exactly as long as v2.1 has been
       // the format.
       //
-      // v2.1 carries APP IDS ONLY (env.platform.appId, env.products[].appId) — no community ids.
+      // v3 carries ONE APP ID (env.app.appId) — no community ids.
       // We therefore send app_ids alone and let the server resolve ownership from Products.
       // Deriving a community_id by splitting an app_id would violate the platform invariant that
       // app ids are OPAQUE to routing and lookups.
@@ -4226,14 +4121,11 @@ program
           process.exit(1);
         }
         const appIds = new Set();
-        if (wsConfig?.env?.platform?.appId) appIds.add(wsConfig.env.platform.appId);
-        for (const product of wsConfig?.env?.products || []) {
-          if (product?.appId) appIds.add(product.appId);
-        }
+        if (wsConfig?.env?.app?.appId) appIds.add(wsConfig.env.app.appId);
         // Fail LOUD rather than sending an empty context the server can only reject.
         if (appIds.size === 0) {
-          console.error(chalk.red("project scope: no apps found in .descix/workspace.json (env.platform.appId / env.products[].appId)."));
-          console.error(chalk.gray("    Use --scope entitlements, or add products to the workspace."));
+          console.error(chalk.red("project scope: this workspace holds no app (workspace.json env.app)."));
+          console.error(chalk.gray("    Use --scope entitlements, or run `descix app init` in this repo."));
           process.exit(1);
         }
         project_context = { app_ids: Array.from(appIds) };

package/lib/commands/appInit.js

@@ -12,27 +12,24 @@
 import chalk from 'chalk';
 import fs from 'fs/promises';
 import path from 'path';
-import { WorkspaceConfig, resolveWorkspacePath } from '../workspace-config.js';
+import { WorkspaceConfig, assertNoParentWorkspace } 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
+ * @param {{app: string, community?: string, short?: string, overwrite?: boolean, kb?: 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);
-  }
+  // v3 single-app: THIS directory becomes (or already is) the workspace root. A workspace at an
+  // ANCESTOR is a refusal, loud, BEFORE anything is written anywhere — the walk-up used to
+  // silently register a nested checkout into the parent workspace (the measured trap).
+  await assertNoParentWorkspace(process.cwd());
+  const workspaceConfig = await WorkspaceConfig.tryLoad(process.cwd());
 
   // Resolve community_id from the Products registry to learn whether the app exists yet.
   let communityId;
@@ -74,26 +71,15 @@ export async function runAppInit(apiClient, options) {
     );
   }
 
-  // 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.`
-    );
-  }
-
+  // 1. Workspace.json — THIS repo root is the workspace root and holds exactly this app (v3).
+  // registerApp is idempotent for the same id and REFUSES a different one: a repo that already
+  // holds another app errors loudly instead of being silently re-pointed.
   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}`));
-  }
+  const cfg = workspaceConfig || new WorkspaceConfig({ version: '3.0' }, wsRoot);
+  cfg.registerApp(communityId, appId, { kbId });
+  await cfg.save(wsRoot);
+  const appPath = wsRoot;
+  console.log(chalk.gray(`  workspace.json: env.app = ${appId} (this repo root)`));
 
   // 2. Create app folder structure (site, microservice, assets)
   const assetsDir = path.join(appPath, 'assets');

package/lib/commands/auth.js

@@ -22,9 +22,18 @@ const POLL_INTERVAL_MS = 3000; // 3 seconds
 const MAX_POLL_TIME_MS = 15 * 60 * 1000; // 15 minutes
 
 /**
- * Open browser to URL
+ * Open browser to URL — INTERACTIVE SESSIONS ONLY.
+ *
+ * A non-interactive invocation (a spawned test harness, CI, any piped run) must NEVER reach
+ * into the operator's live browser: measured 2026-10-10, the CLI test suite repeatedly seized
+ * the CEO's active tab because every spawned `quickstart`/`login` walked straight into the
+ * device flow's `open`. No TTY on stdout = print the URL, open nothing. DESCIX_NO_BROWSER=1
+ * forces the same for interactive runs that want it.
  */
 async function openBrowser(url) {
+  if (!process.stdout.isTTY || process.env.DESCIX_NO_BROWSER === '1') {
+    return false; // the caller already prints the URL on a false return
+  }
   const platform = process.platform;
   let command;
   

package/lib/commands/config.js

@@ -34,12 +34,10 @@ export async function show() {
       console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
     }
 
-    // Show mapped apps (v2.1 env.products)
-    const platform = workspaceConfig.env?.platform;
-    const products = workspaceConfig.env?.products || [];
-    const allApps = [platform?.appId, ...products.map(p => p.appId)].filter(Boolean);
-    if (allApps.length > 0) {
-      console.log(chalk.white(`   Apps:          ${allApps.join(', ')}`));
+    // v3 single-app: the one app this workspace holds
+    const appId = workspaceConfig.env?.app?.appId;
+    if (appId) {
+      console.log(chalk.white(`   App:           ${appId}`));
     }
 
     console.log('');

package/lib/commands/corpus.js

@@ -373,7 +373,7 @@ export async function runCorpusSync(apiClient, options) {
     const appConfig = workspaceConfig.getAppByAppId(appId);
     if (!appConfig) {
       spinner.fail(`App not found: ${appId}`);
-      throw new Error(`App "${appId}" not found in workspace.json. Check env.products[].`);
+      throw new Error(`App "${appId}" is not this workspace's app (workspace.json env.app).`);
     }
 
     const appRoot = appConfig.absolutePath;

package/lib/commands/health.js

@@ -36,7 +36,7 @@ import { promisify } from 'util';
 import { localUpstreamOrigin, resolveGatewayPort } from '@descix/app-sdk/dev';
 import https from 'https';
 import http from 'http';
-import { WorkspaceConfig } from '../workspace-config.js';
+import { WorkspaceConfig, resolveLocalApps } from '../workspace-config.js';
 
 const execAsync = promisify(exec);
 
@@ -109,47 +109,27 @@ function defaultHttpsProbe(url, timeoutMs = 8000, { insecure = false } = {}) {
  */
 function buildServiceRegistry(wsConfig) {
     const services = [];
-    const env = wsConfig.env || {};
 
-    if (env.platform) {
-        const name = env.platform.appId || 'platform';
-        if (env.platform.microservice?.port) {
+    // The local app set has ONE owner (workspaceApps, v3 fork (b)): this workspace's own
+    // env.app plus every repo env.gateway lists, each read from its OWN workspace.json.
+    const { apps } = resolveLocalApps(wsConfig);
+    for (const app of apps) {
+        if (app.microservice?.port) {
             services.push({
-                name,
-                appId: env.platform.appId,
-                port: env.platform.microservice.port,
+                name: app.appId,
+                appId: app.appId,
+                port: app.microservice.port,
                 type: 'microservice',
-                origin: localUpstreamOrigin(env.platform.microservice, 'env.platform.microservice'),
+                origin: localUpstreamOrigin(app.microservice, `env.app.microservice (${app.appId})`),
             });
         }
-        if (env.platform.site?.port) {
+        if (app.site?.port) {
             services.push({
-                name: `${name}-site`,
-                appId: env.platform.appId,
-                port: env.platform.site.port,
+                name: `${app.appId}-site`,
+                appId: app.appId,
+                port: app.site.port,
                 type: 'site',
-                origin: localUpstreamOrigin(env.platform.site, 'env.platform.site'),
-            });
-        }
-    }
-
-    for (const product of (env.products || [])) {
-        if (product.microservice?.port) {
-            services.push({
-                name: product.appId,
-                appId: product.appId,
-                port: product.microservice.port,
-                type: 'microservice',
-                origin: localUpstreamOrigin(product.microservice, `env.products[${product.appId}].microservice`),
-            });
-        }
-        if (product.site?.port) {
-            services.push({
-                name: `${product.appId}-site`,
-                appId: product.appId,
-                port: product.site.port,
-                type: 'site',
-                origin: localUpstreamOrigin(product.site, `env.products[${product.appId}].site`),
+                origin: localUpstreamOrigin(app.site, `env.app.site (${app.appId})`),
             });
         }
     }
@@ -279,15 +259,9 @@ async function probeGcloudAuth(execFn) {
  * - prod: only descix/egpt/powch (cutover #1 in-scope); raise on out-of-scope filter
  */
 function resolveAppsForCloudProbe(env, wsConfig, filterAppId) {
-    const allApps = [];
-    if (wsConfig.env?.platform?.appId) {
-        allApps.push(wsConfig.env.platform.appId);
-    }
-    for (const product of (wsConfig.env?.products || [])) {
-        if (product.appId) allApps.push(product.appId);
-    }
-    // Dedupe
-    const unique = [...new Set(allApps)];
+    // The app set has ONE owner (workspaceApps): env.app + every repo env.gateway lists.
+    const { apps } = resolveLocalApps(wsConfig);
+    const unique = [...new Set(apps.map(a => a.appId))];
 
     if (env === 'prod') {
         // PROD scope guard: only in-scope hosts allowed.

package/lib/commands/init.js

@@ -163,10 +163,9 @@ export async function runInit(apiClient, options = {}) {
     }
 
     console.log(chalk.gray(`\n${existingConfig ? 'Updating' : 'Writing'} .descix/workspace.json...\n`));
-    const config = existingConfig || new WorkspaceConfig({ version: '2.1', type: 'workspace', env: {} }, projectPath);
+    const config = existingConfig || new WorkspaceConfig({ version: '3.0', type: 'workspace', env: {} }, projectPath);
     if (existingConfig && options.force && config.env) {
-      config.env.products = [];
-      delete config.env.platform;
+      delete config.env.app;
     }
     // 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

package/lib/commands/kb.js

@@ -11,7 +11,7 @@
  * - compare: Show file-level deltas
  * 
  * Architecture:
- * - Uses WorkspaceConfig for all path resolution (supports v2.1 env.platform/products format)
+ * - Uses WorkspaceConfig for all path resolution (v3 single-app env.app format)
  * - All operations delegate to lib/core/ modules
  * - Supports interactive and unattended (agent) modes
  * - CLI handles UX (prompts, progress, errors)

package/lib/commands/microservice-restart.js

@@ -2,11 +2,11 @@
  * Microservice Restart Command (DEV only)
  *
  * Eliminates the "hand-kill + nohup-relaunch" tribal-knowledge workflow:
- *   1. Resolve the service from workspace.json `env.platform` / `env.products`
+ *   1. Resolve the service from the workspace's app set (env.app / env.gateway)
  *      (HARD-FAIL on unknown / ambiguous / missing devCommand).
  *   2. Find the running PID via `lsof -iTCP:<port> -sTCP:LISTEN` (or `ps`).
  *   3. SIGTERM → wait up to 5s → SIGKILL.
- *   4. Re-launch the canonical devCommand from `{workspaceRoot}/{localPath}/microservice/`
+ *   4. Re-launch the canonical devCommand from the app repo's own `microservice/` dir
  *      detached via `setsid + nohup`, redirecting stdout/stderr to a canonical log.
  *   5. Poll until the port is bound again; print new PID + log path.
  *   6. Run `descix health -m <name>` and print the result.
@@ -27,7 +27,7 @@ import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import fs from 'fs/promises';
 import path from 'path';
-import { WorkspaceConfig } from '../workspace-config.js';
+import { WorkspaceConfig, resolveLocalApps } from '../workspace-config.js';
 
 const execAsync = promisify(exec);
 
@@ -44,28 +44,25 @@ const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * are restart-eligible (devCommand is the canonical launch signature).
  *
  * @param {WorkspaceConfig} wsConfig
- * @returns {Array<{name, localPath, port, devCommand, microserviceDir}>}
+ * @returns {Array<{name, dir, port, devCommand, microserviceDir}>}
  */
 export function buildRestartRegistry(wsConfig) {
-  const env = wsConfig.env || {};
-  const root = wsConfig.workspaceRoot;
   const out = [];
 
-  const collect = (entry) => {
-    if (!entry?.appId || !entry?.localPath) return;
-    const ms = entry.microservice;
-    if (!ms || !ms.port) return;
+  // The local app set has ONE owner (workspaceApps, v3 fork (b)): this workspace's own
+  // env.app plus every repo env.gateway lists, each read from its OWN workspace.json.
+  const { apps } = resolveLocalApps(wsConfig);
+  for (const app of apps) {
+    const ms = app.microservice;
+    if (!ms || !ms.port) continue;
     out.push({
-      name: entry.appId,
-      localPath: entry.localPath,
+      name: app.appId,
+      dir: app.dir,
       port: ms.port,
       devCommand: ms.devCommand || null,
-      microserviceDir: path.join(root, entry.localPath, 'microservice')
+      microserviceDir: path.join(app.dir, 'microservice')
     });
-  };
-
-  collect(env.platform);
-  for (const p of (env.products || [])) collect(p);
+  }
   return out;
 }
 
@@ -75,7 +72,7 @@ export function buildRestartRegistry(wsConfig) {
  *
  * @param {WorkspaceConfig} wsConfig
  * @param {string} name
- * @returns {{name, localPath, port, devCommand, microserviceDir}}
+ * @returns {{name, dir, port, devCommand, microserviceDir}}
  */
 export function resolveService(wsConfig, name) {
   const registry = buildRestartRegistry(wsConfig);
@@ -84,24 +81,19 @@ export function resolveService(wsConfig, name) {
   if (matches.length === 0) {
     const candidates = registry.map((s) => s.name).join(', ') || '(none)';
     throw new Error(
-      `Service '${name}' not found in workspace.json env.platform/env.products.\n` +
+      `Service '${name}' is not served by this workspace (env.app / env.gateway).\n` +
       `  Restart-eligible services (with microservice.port + microservice.devCommand): ${candidates}\n` +
       `  Add an entry to .descix/workspace.json or run 'descix microservice list'.`
     );
   }
-  if (matches.length > 1) {
-    throw new Error(
-      `Service name '${name}' is ambiguous — matches ${matches.length} entries: ` +
-      matches.map((m) => `${m.name}@${m.localPath}`).join(', ')
-    );
-  }
-
+  // No ambiguity branch: duplicate app ids are refused upstream by the app-set owner
+  // (resolveWorkspaceApps), so at most one entry can match here.
   const svc = matches[0];
   if (!svc.devCommand) {
     throw new Error(
       `Service '${name}' has no microservice.devCommand in workspace.json — ` +
       `cannot determine canonical launch signature. ` +
-      `Add 'devCommand' under env.products[].microservice to enable restart.`
+      `Add 'devCommand' under env.app.microservice in that app repo's workspace.json to enable restart.`
     );
   }
   return svc;
@@ -173,17 +165,20 @@ export async function killPid(pid, opts = {}) {
 
 /**
  * Resolve the canonical log path for a restart.
- *   apps/<community>/<app>/.descix/logs/<service>-<ts>.log
+ *   <app repo root>/.descix/logs/<service>-<ts>.log
+ * The app repo root is the entry's own `dir` (workspaceApps): under v3 each app lives in its
+ * own repo, so there is no workspace-wide apps/<community>/ tree to hang logs under.
  * Falls back to /tmp/<service>-restart-<ts>.log if the canonical dir
  * cannot be created.
+ *
+ * @param {{name: string, dir: string}} svc - a restart-registry entry
  */
-export async function resolveLogPath(wsConfig, serviceName, opts = {}) {
+export async function resolveLogPath(svc, opts = {}) {
   const deps = opts.deps || {};
   const fsImpl = deps.fs || fs;
   const ts = (opts.timestamp || new Date().toISOString()).replace(/[:.]/g, '-');
-  const root = wsConfig.workspaceRoot;
-  const community = wsConfig.env?.communityId || 'unkamon';
-  const canonicalDir = path.join(root, 'apps', community, serviceName, '.descix', 'logs');
+  const serviceName = svc.name;
+  const canonicalDir = path.join(svc.dir, '.descix', 'logs');
   try {
     await fsImpl.mkdir(canonicalDir, { recursive: true });
     return {
@@ -303,7 +298,7 @@ export async function restartMicroservice(args) {
   }
 
   // Step 2: resolve log path.
-  const logRes = await resolveLogPath(wsConfig, svc.name, { deps });
+  const logRes = await resolveLogPath(svc, { deps });
   if (logRes.fallback) {
     log(chalk.yellow(`  Canonical log dir unavailable (${logRes.fallbackReason}); using ${logRes.path}`));
   } else {

package/lib/commands/status.js

@@ -159,12 +159,10 @@ export async function runStatus(options = {}) {
     console.log(`Config File:    ${path.join(workspaceRoot, '.descix', 'workspace.json')}`);
 
     try {
-      // List all configured apps from env.platform + env.products
-      const platform = workspaceConfig.env?.platform;
-      const products = workspaceConfig.env?.products || [];
-      const allApps = [platform?.appId, ...products.map(p => p.appId)].filter(Boolean);
-      if (allApps.length > 0) {
-        console.log(`Local Apps:     ${allApps.join(', ')}`);
+      // v3 single-app: the one app this workspace holds
+      const wsAppId = workspaceConfig.env?.app?.appId;
+      if (wsAppId) {
+        console.log(`App:            ${wsAppId}`);
       }
 
       // WHAT THE WORKSPACE FILE ITSELF SAYS — deliberately NOT a resolved origin. The resolved

package/lib/verb-invokes.generated.json

@@ -34,7 +34,6 @@
   "app set-listed": [
     "update_app"
   ],
-  "app set-localpath": [],
   "app set-name": [
     "update_app"
   ],
@@ -49,7 +48,6 @@
   "app sync-assets": [
     "sync_app_assets"
   ],
-  "app unmap": [],
   "buy chains": [],
   "buy poll": [
     "get_quote_status"
@@ -218,7 +216,8 @@
   "site upload": [
     "confirm_site_deploy",
     "get_site_build_config",
-    "get_site_deploy_token"
+    "get_site_deploy_token",
+    "get_site_manifest"
   ],
   "stats": [
     "get_user_community_stats"

package/lib/workspace-config.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { ENV_ORIGINS } from '@descix/app-sdk/dev';
+import { ENV_ORIGINS, resolveWorkspaceApps } from '@descix/app-sdk/dev';
 import { resolveOrigin } from './origin.js';
 // The one canonical KB-sync surface, from its owner. The example in requireContext() is a remedy
 // a stuck developer will copy verbatim, so it must resolve to the live verb rather than a literal
@@ -22,8 +22,9 @@ import { npxCommand } from './invocation.js';
  */
 export function unmappedAppMessage(appId) {
   return (
-    `App "${appId}" is not mapped in workspace.json. ` +
-    'Use `descix app init` to register, or `descix app set-localpath -a <id> -p <path>` to repoint.'
+    `App "${appId}" is not this workspace's app (workspace.json env.app). ` +
+    'A v3 workspace is single-app: run commands for another app from ITS repo root, ' +
+    'or run `descix app init -a <id>` in a fresh repo to create its workspace.'
   );
 }
 
@@ -55,6 +56,55 @@ export function resolveWorkspacePath(workspaceRoot, localPath, label = 'app') {
     return path.resolve(workspaceRoot, localPath);
 }
 
+/**
+ * The local app set of a loaded workspace — THE one CLI-side entry to resolveWorkspaceApps.
+ * Every command that enumerates local apps (health, microservice restart) goes through here, so
+ * a config that carries no workspaceRoot FAILS LOUD in one place instead of each caller quietly
+ * substituting the cwd and enumerating a different workspace than the one it was handed.
+ *
+ * @param {WorkspaceConfig} wsConfig
+ * @returns {{ shellApp: Object|null, apps: Object[] }} see resolveWorkspaceApps
+ */
+export function resolveLocalApps(wsConfig) {
+    if (!wsConfig?.workspaceRoot) {
+        throw new Error(
+            'Cannot enumerate the workspace apps: the workspace config carries no workspaceRoot. ' +
+            'Load it with WorkspaceConfig.load() (which sets it) rather than constructing it bare.'
+        );
+    }
+    return resolveWorkspaceApps(wsConfig.workspaceRoot);
+}
+
+/**
+ * `descix app init` runs where the APP REPO is — its root becomes the workspace root. A nested
+ * checkout used to WALK UP, find a parent workspace and silently register into it (the measured
+ * trap: an app repo cloned inside another workspace mapped itself into the parent's registry).
+ * Under v3 single-app there is nothing to register into: a workspace found at an ANCESTOR of the
+ * init directory is a refusal, loud, before anything is written anywhere.
+ *
+ * A workspace AT the directory itself is fine — that is the re-init case.
+ *
+ * @param {string} dir - the directory `app init` is about to make a workspace root
+ * @throws when a workspace.json exists at a strict ancestor of dir
+ */
+export async function assertNoParentWorkspace(dir = process.cwd()) {
+    const resolved = path.resolve(dir);
+    const found = await WorkspaceConfig.findWorkspaceRoot(resolved);
+    if (found && path.resolve(found) !== resolved) {
+        throw new Error(
+            `This directory is nested inside another DeSciX workspace.\n` +
+            `  Here:              ${resolved}\n` +
+            `  Parent workspace:  ${found} (.descix/workspace.json)\n` +
+            `\n` +
+            `A v3 workspace is single-app: the app repo's own root is its workspace root, and\n` +
+            `"descix app init" refuses to run inside someone else's workspace rather than\n` +
+            `silently registering this checkout into it.\n` +
+            `Move this checkout OUT of ${found} (sibling checkouts, one gateway config, is the\n` +
+            `supported local layout), then run "descix app init" again from the repo root.`
+        );
+    }
+}
+
 /**
  * The ONE text for "there is no workspace here". It is correct advice for exactly one state —
  * the file does not exist — and it is a lie for every other state, which is why it now has a
@@ -166,7 +216,7 @@ export class WorkspaceConfig {
     this.environment = config.environment;
     this.directoryMappings = config.directoryMappings || {};
 
-    // app_id → localPath map from env.platform + env.products (Unified Registry)
+    // app_id → config map from env.app (v3 single-app)
     this._appIdToConfig = this._buildAppIdMap(config);
     
     // Environment URLs for descix-serve gateway routing
@@ -177,50 +227,39 @@ export class WorkspaceConfig {
   }
 
   /**
-   * Build app_id → config map from env.platform and env.products
-   * Unified Registry: app_id is globally unique; localPath maps to directory
+   * Build the app_id → config map from env.app (v3 single-app).
+   *
+   * v3 holds exactly ONE app and its localPath is implicitly '.': the app repo's root IS the
+   * workspace root. The map shape survives (one entry) so every reader keyed on appId keeps
+   * its contract; the retired v2.1 multi-app walk (env.platform + env.products) is refused by
+   * load() and has no reader here any more.
+   *
    * @param {Object} config - Parsed workspace.json
    * @returns {Object} Map of appId -> { localPath, communityId?, kbId }
    */
   _buildAppIdMap(config) {
     const map = {};
-    const env = config.env || {};
-    const wsRoot = config.workspaceRoot || this.workspaceRoot;
-
-    // env.platform (e.g. daita -> DeSciX_Cloud)
-    if (env.platform?.appId && env.platform?.localPath) {
-      map[env.platform.appId] = {
-        localPath: env.platform.localPath,
-        communityId: env.platform.communityId || null,
-        kbId: env.platform.kbId || 'General'
+    const app = config.env?.app;
+    if (app?.appId) {
+      map[app.appId] = {
+        localPath: '.',
+        communityId: app.communityId || null,
+        kbId: app.kbId || 'General'
       };
     }
-
-    // env.products array (e.g. powch -> DeSciX_Powch)
-    const products = Array.isArray(env.products) ? env.products : [];
-    for (const p of products) {
-      if (p?.appId && p?.localPath) {
-        map[p.appId] = {
-          localPath: p.localPath,
-          communityId: p.communityId || null,
-          kbId: p.kbId || 'General'
-        };
-      }
-    }
-
     return map;
   }
 
   /**
    * Get app config by app_id (Unified Registry - app_id is globally unique)
-   * Resolves from env.platform, env.products, communities, or products
+   * Resolves from env.app (v3 single-app)
    * @param {string} appId - App/product identifier
    * @returns {Object|null} { localPath, absolutePath?, communityId?, kbId } or null
    */
   getAppByAppId(appId) {
     if (!appId || !this.workspaceRoot) return null;
 
-    // env.platform + env.products (primary for manually crafted workspace)
+    // env.app (v3 single-app)
     const fromEnv = this._appIdToConfig[appId];
     if (fromEnv) {
       const absPath = resolveWorkspacePath(this.workspaceRoot, fromEnv.localPath, appId);
@@ -235,87 +274,29 @@ export class WorkspaceConfig {
     return null;
   }
 
-  /**
-   * The RAW registry entry for an app — `localPath` exactly as workspace.json carries it, with NO
-   * path resolution and therefore no possibility of throwing on a bad stored value.
-   *
-   * This exists for exactly one caller shape: a command that is about to REPLACE an app's
-   * localPath. Such a command must not resolve the OUTGOING value. getAppByAppId() resolves, and
-   * resolving the value you are on your way to overwrite is what made `descix app set-localpath`
-   * unusable precisely when it was needed — a workspace already carrying a rejected localPath
-   * could not be repaired by the one verb whose job is repairing it, while the rejection itself
-   * forbade hand-editing. The verb was the prescribed remedy and the verb refused.
-   *
-   * It reads the SAME map getAppByAppId reads (_buildAppIdMap is still the one owner of "what is
-   * mapped"); it simply stops short of resolution. Do NOT use it to obtain a usable path — take
-   * getAppByAppId().absolutePath for that, so the loader's rejection still runs.
-   *
-   * @param {string} appId - App/product identifier
-   * @returns {{ localPath: string, communityId: string|null, kbId: string }|null}
-   */
-  getAppEntry(appId) {
-    if (!appId) return null;
-    return this._appIdToConfig?.[appId] || null;
-  }
+
 
   /**
    * THE ONE OWNER of "find the LIVE env entry for this app, or hard-fail".
    *
    * Live means the actual object inside this.env — mutate it and save() persists the mutation.
-   * getAppByAppId() and getAppEntry() both return copies and are useless for writing.
+   * getAppByAppId() returns copies and is useless for writing.
    *
-   * The one lookup every entry setter (setMicroservicePort, setStaticSite, setLocalPath) uses. A
-   * private walk of env.products ONLY misses the platform app, finds nothing, writes nothing and
-   * still reports success.
+   * The one lookup every entry setter (setMicroservicePort, setStaticSite) uses. In v3 the only
+   * live entry is env.app; any other id hard-fails with the canonical unmapped message.
    *
    * @param {string} appId - App identifier
-   * @returns {Object} the live env.platform or env.products[] entry
-   * @throws if appId is not mapped
+   * @returns {Object} the live env.app entry
+   * @throws if appId is not THE app
    */
   _liveEnvEntry(appId) {
-    let entry = null;
-    if (this.env?.platform?.appId === appId) {
-      entry = this.env.platform;
-    } else if (Array.isArray(this.env?.products)) {
-      entry = this.env.products.find(p => p.appId === appId) || null;
-    }
+    const entry = this.env?.app?.appId === appId ? this.env.app : null;
     if (!entry) {
       throw new Error(unmappedAppMessage(appId));
     }
     return entry;
   }
 
-  /**
-   * Update an app's localPath in env.platform or env.products[].
-   *
-   * The canonical write path for localPath. Backs `descix app set-localpath`.
-   *
-   * localPath MUST be workspace-root-relative. It is validated here through
-   * resolveWorkspacePath — the LOADER'S OWN resolver, not a second copy of its rules — so a
-   * value the loader will refuse on the next read is refused now, before anything is written.
-   * Writing a value the loader rejects is what bricked workspaces: every subsequent command
-   * threw, including the repair verbs, while the rejection forbade hand-editing.
-   *
-   * Persists via save() — same auto-save pattern as its siblings.
-   * Hard-fails if appId is not mapped in env.platform or env.products.
-   *
-   * @param {string} appId - App identifier (must exist in env.platform or env.products)
-   * @param {string} localPath - New path, relative to the workspace root
-   * @returns {Promise<string>} Path to saved config (from save())
-   */
-  async setLocalPath(appId, localPath) {
-    if (!appId) throw new Error('appId is required');
-    if (!localPath) throw new Error('localPath is required');
-
-    const entry = this._liveEnvEntry(appId);
-
-    // Validate through the loader's own resolver. Throws on an absolute path.
-    resolveWorkspacePath(this.workspaceRoot, localPath, appId);
-
-    entry.localPath = localPath;
-    return this.save();
-  }
-
   /**
    * Get the absolute path to an app's site/ directory
    * @param {string} appId - App identifier
@@ -437,6 +418,28 @@ export class WorkspaceConfig {
       );
     }
 
+    // v2.1 MULTI-APP hard-error: env.platform / env.products are the retired mapping model —
+    // one workspace registering OTHER repos' apps by localPath. v3 is single-app (CEO
+    // 2026-10-09; fork (b) 2026-10-10): the app repo's root IS the workspace root, and local
+    // multi-app dev is sibling checkouts behind one gateway config. Same posture as the v1
+    // refusal above: loud, non-destructive, the remedy is one command per app repo.
+    if (parsed.env && (parsed.env.platform || parsed.env.products)) {
+      throw new Error(
+        'v2.1 multi-app workspace format is not supported. Migrate to v3 (single-app).\n' +
+        `  File:   ${configPath}\n` +
+        '\n' +
+        'This file is still on disk and has NOT been modified. v3 holds exactly ONE app\n' +
+        '(env.app) and the app repo\'s own root is the workspace root. To migrate:\n' +
+        '  • In EACH app repo this file mapped, run from that repo\'s root:\n' +
+        '      descix config init --env <dev|demo|prod>   # pins env.apiUrl\n' +
+        '      descix app init -a <app_id>                # writes the v3 env.app block\n' +
+        '  • A gateway hosting several local apps lists their repo roots in ITS OWN\n' +
+        '    workspace.json under env.gateway.appRepos (fork (b): sibling checkouts, one\n' +
+        '    gateway config).\n' +
+        moveAsideRemedy(configPath, 'descix app init')
+      );
+    }
+
     // A v2.1 file carrying a TOP-LEVEL `apiUrl` is refused by name. That key is retired: no
     // reader consumes it (the origin owner resolves `env.apiUrl` only) and save() never writes
     // it, so a developer who set it by hand would be silently ignored on every invocation —
@@ -480,8 +483,8 @@ export class WorkspaceConfig {
   }
   
   /**
-   * Save workspace configuration in v2.1 format.
-   * Always writes env.platform / env.products structure.
+   * Save workspace configuration in v3 (single-app) format: env.app, never
+   * env.platform / env.products.
    *
    * PRESERVES KEYS IT DOES NOT UNDERSTAND. This method used to serialize a fixed field list from
    * memory over the whole file, so ANY top-level key it did not itself enumerate was silently
@@ -508,7 +511,7 @@ export class WorkspaceConfig {
 
     this.workspaceRoot = root;
 
-    // Build env block for v2.1 output
+    // Build env block for v3 output
     const envBlock = (this.env && Object.keys(this.env).length > 0) ? this.env : null;
 
     // The keys this writer OWNS. Everything else on disk is carried through untouched.
@@ -537,7 +540,7 @@ export class WorkspaceConfig {
 
     const configData = {
       ...carried,
-      version: '2.1',
+      version: '3.0',
       workspaceRoot: path.resolve(root),
       type: this.type,
     };
@@ -552,54 +555,47 @@ export class WorkspaceConfig {
   // ============ App Registration Methods ============
 
   /**
-   * Register an app in the v2.1 workspace (env.platform or env.products).
-   * community_id is server-authoritative — not stored in workspace.json.
-   * @param {string} communityId - Accepted for call-site compatibility but not stored
+   * Register THE app of this v3 workspace (env.app).
+   *
+   * Single-app is the FORMAT, not a convention: a workspace that already holds a different app
+   * refuses loudly — there is no second slot to put one in, and silently replacing env.app
+   * would re-point every path-derived surface (site/, microservice/, manifests) at a different
+   * platform record. Re-registering the SAME app is idempotent (the `app init` re-run case) and
+   * may update kbId / communityId.
+   *
+   * localPath is GONE as an input: the app repo's root is the workspace root, always ('.').
+   *
+   * communityId is STORED, not just validated. It was previously accepted as a parameter and
+   * silently discarded, so `descix init -c egpt` wrote no trace of `egpt` anywhere — and
+   * `workspace-identity.js` (this entry's reader) then had no community to report, which is
+   * how the generated agent files named nobody's community. Writer and reader are a pair.
+   *
+   * @param {string} communityId - The app's community (server-authoritative value, mirrored here)
    * @param {string} appId - App identifier (globally unique)
-   * @param {Object} appConfig - App configuration
-   * @param {string} appConfig.localPath - Local folder path relative to workspaceRoot
-   * @param {string} [appConfig.kbId] - Default knowledge base ID
+   * @param {Object} [appConfig] - { kbId? }
    * @returns {boolean} Success status
    */
-  registerApp(communityId, appId, appConfig) {
-    if (!appId || !appConfig.localPath) {
-      throw new Error('appId and localPath are required');
+  registerApp(communityId, appId, appConfig = {}) {
+    if (!appId) {
+      throw new Error('appId is required');
     }
 
-    // Validate through THE LOADER'S OWN RESOLVER — the same owner setLocalPath consumes, never a
-    // second copy of its rules. Three writers persisted a localPath and only ONE validated it, so
-    // `descix app init -p /abs` wrote an absolute value, created directories at that arbitrary
-    // absolute location, printed success, and bricked the workspace on the NEXT read — the loader
-    // refused the value for every command including the repair verbs, while the refusal forbade
-    // hand-editing. A path this CLI accepts must be honoured, or refused before anything is written.
-    resolveWorkspacePath(this.workspaceRoot, appConfig.localPath, appId);
-
     if (!this.env) this.env = {};
-    if (!Array.isArray(this.env.products)) this.env.products = [];
-
-    // communityId is STORED, not just validated. It was previously accepted as a parameter and
-    // silently discarded, so `descix init -c egpt` wrote no trace of `egpt` anywhere — and
-    // `workspace-identity.js` (this entry's reader) then had no community to report, which is
-    // how the generated agent files named nobody's community. Writer and reader are a pair:
-    // the key order in `readIdentity()` mirrors the shape written here.
-    const entry = { appId, localPath: appConfig.localPath, kbId: appConfig.kbId || 'General' };
-    if (communityId) entry.communityId = communityId;
-
-    if (this.env.platform?.appId === appId) {
-      this.env.platform.localPath = appConfig.localPath;
-      if (appConfig.kbId) this.env.platform.kbId = appConfig.kbId;
-      if (communityId) this.env.platform.communityId = communityId;
-    } else {
-      const idx = this.env.products.findIndex(p => p.appId === appId);
-      if (idx >= 0) {
-        this.env.products[idx] = { ...this.env.products[idx], ...entry };
-      } else {
-        this.env.products.push(entry);
-      }
+    const existing = this.env.app;
+    if (existing?.appId && existing.appId !== appId) {
+      throw new Error(
+        `This workspace already holds app '${existing.appId}' — a v3 workspace is single-app.\n` +
+        `To work on '${appId}', clone or create its OWN repo and run "descix app init" from\n` +
+        `that repo's root (sibling checkouts, one gateway config, is the supported local layout).`
+      );
     }
 
+    const entry = { ...(existing || {}), appId, kbId: appConfig.kbId || existing?.kbId || 'General' };
+    if (communityId) entry.communityId = communityId;
+    this.env.app = entry;
+
     this._appIdToConfig = this._buildAppIdMap({ env: this.env, workspaceRoot: this.workspaceRoot });
-    this.version = '2.1';
+    this.version = '3.0';
     return true;
   }
   
@@ -648,7 +644,7 @@ export class WorkspaceConfig {
     const cwd = path.resolve(startDir);
     const wsRoot = this.workspaceRoot ? path.resolve(this.workspaceRoot) : null;
 
-    // env.platform + env.products (Unified Registry - primary)
+    // env.app (v3 single-app): at most one entry
     if (wsRoot) {
       for (const [appId, cfg] of Object.entries(this._appIdToConfig || {})) {
         const appPath = resolveWorkspacePath(wsRoot, cfg.localPath, appId);
@@ -776,7 +772,7 @@ export class WorkspaceConfig {
       throw new Error(
         `"${dottedKey}" is not a workspace-level env key.\n` +
         `  Settable here: ${ALLOWED.join(', ')}\n` +
-        '  Per-app keys have their own verbs: descix app set-site / set-port / set-localpath.'
+        '  Per-app keys have their own verbs: descix app set-site / set-port.'
       );
     }
 
@@ -806,7 +802,7 @@ export class WorkspaceConfig {
   }
 
   /**
-   * Update an app's microservice.port in env.products[] (or env.platform if it is the platform app).
+   * Update the app's microservice.port on env.app (v3 single-app).
    *
    * Operates on the entry's microservice.{} slot.
    * This is the canonical write path for the microservice port that `descix microservice init`
@@ -815,9 +811,9 @@ export class WorkspaceConfig {
    *
    * Pass `null` to remove microservice.port; if microservice.{} becomes empty, it is also deleted.
    * Persists via save() at the end — same auto-save pattern as setEnvironment().
-   * Hard-fails if appId is not mapped in env.platform or env.products.
+   * Hard-fails if appId is not THE app (env.app).
    *
-   * @param {string} appId - App identifier (must exist in env.platform or env.products)
+   * @param {string} appId - App identifier (must be env.app.appId)
    * @param {number|string|null} port - Port number to set, or null to remove microservice.port
    * @returns {Promise<string>} Path to saved config (from save())
    */
@@ -843,7 +839,7 @@ export class WorkspaceConfig {
   }
 
   /**
-   * Update an app's site config in env.products[] (or env.platform if it is the platform app).
+   * Update the app's site config on env.app (v3 single-app).
    *
    * Parallel to setMicroservicePort(), but operates on the entry's site.{} slot. This is the
    * canonical write path for site.static — the relative path the dev gateway's
@@ -867,9 +863,9 @@ export class WorkspaceConfig {
    * Pass null for a field to remove it (what `--unset` does for all three). Removals clear
    * only the named field. If site.{} becomes empty after removals it is deleted.
    * Persists via save() at the end — same auto-save pattern as setMicroservicePort().
-   * Hard-fails if appId is not mapped in env.platform or env.products.
+   * Hard-fails if appId is not THE app (env.app).
    *
-   * @param {string} appId - App identifier (must exist in env.platform or env.products)
+   * @param {string} appId - App identifier (must be env.app.appId)
    * @param {Object} fields - Fields to set on site.{}
    * @param {string|null} [fields.static] - Relative static-site path to set, or null to remove site.static
    * @param {number|string|null} [fields.port] - Site dev-server port to set, or null to remove site.port
@@ -1006,9 +1002,9 @@ export class WorkspaceConfig {
   validate() {
     const errors = [];
 
-    // v2.1 validation: must have env block
+    // v3 validation: must have env block
     if (!this.env || Object.keys(this.env).length === 0) {
-      errors.push('Missing env block — workspace.json must be v2.1 format with env.platform or env.products');
+      errors.push('Missing env block — workspace.json must be v3 format with env.app');
     }
 
     return {

package/lib/workspace-identity.js

@@ -24,10 +24,9 @@ import { resolveOrigin } from './origin.js';
 /**
  * Read the workspace's identity from a parsed `.descix/workspace.json`.
  *
- * The key order below mirrors `WorkspaceConfig.registerApp()` — `env.platform` for the
- * workspace's own platform app, then `env.products[]` for a registered product, then the
- * legacy `defaultContext`. If that order ever diverges from the writer's, the agent files go
- * wrong again, so the two are commented as a pair.
+ * v3 single-app: the one key the writer (`WorkspaceConfig.registerApp()`) writes is `env.app`,
+ * so that is the one key read here — writer and reader are a pair. The legacy `defaultContext`
+ * survives as the last resort for files written before the env block existed.
  *
  * @param {object} config - the PARSED workspace.json (not a WorkspaceConfig instance, so that
  *                          `agent-files.js` can stay usable from the VS Code extension where it
@@ -37,22 +36,16 @@ import { resolveOrigin } from './origin.js';
  */
 export function readIdentity(config = {}) {
     const env = config.env || {};
-    const platform = env.platform || {};
-    const products = Array.isArray(env.products) ? env.products : [];
-    // The first registered product is the workspace's app when there is no platform app. A
-    // workspace with several products has no single identity, and `init` only ever writes one.
-    const product = products[0] || {};
+    const app = env.app || {};
     const legacy = config.defaultContext || {};
 
     const appId =
-        platform.appId ||
-        product.appId ||
+        app.appId ||
         legacy.appId ||
         null;
 
     const communityId =
-        platform.communityId ||
-        product.communityId ||
+        app.communityId ||
         legacy.communityId ||
         config.primaryCommunity ||
         null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.21",
+  "version": "2.0.0",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
   "author": "DeSciX",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.2.0",
+    "@descix/app-sdk": "^0.3.0",
     "@descix/sdk": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",

package/lib/workspace-utils.js

@@ -1,106 +0,0 @@
-/**
- * Workspace Utilities
- *
- * Helper functions for workspace mode detection and path resolution.
- * v2.1 workspace format only (env.platform / env.products).
- */
-
-import path from 'path';
-
-/**
- * Detect workspace mode from workspace.json configuration (v2.1 format)
- * @param {Object} workspace - Parsed workspace.json
- * @returns {'single_app' | 'single_community' | 'multi_community'}
- */
-export function detectWorkspaceMode(workspace) {
-  // Explicit mode declaration
-  if (workspace.mode) {
-    return workspace.mode;
-  }
-
-  // v2.1 format: infer from env.platform + env.products
-  if (workspace.env?.platform) {
-    const productCount = Array.isArray(workspace.env.products) ? workspace.env.products.length : 0;
-    // Platform + products = multi-community workspace
-    return productCount > 0 ? 'multi_community' : 'single_app';
-  }
-
-  // Fallback for empty/initialized workspace using defaultContext
-  if (workspace.defaultContext?.communityId && workspace.defaultContext?.appId) {
-    return 'single_app';
-  }
-
-  throw new Error('Unable to determine workspace mode from configuration. Expected v2.1 format (env.platform / env.products).');
-}
-
-/**
- * Resolve local path to Drive path based on workspace mode
- * @param {Object} workspace - Workspace configuration
- * @param {string} localPath - Path relative to workspace root
- * @returns {string} Path relative to user's base_folder_id
- */
-export function resolveToDrivePath(workspace, localPath) {
-  const mode = detectWorkspaceMode(workspace);
-
-  // Normalize local path (remove leading ./)
-  const normalizedLocal = localPath.replace(/^\.\//, '');
-
-  switch (mode) {
-    case 'single_app': {
-      const communityId = workspace.defaultContext?.communityId || workspace.env?.platform?.communityId;
-      const appId = workspace.defaultContext?.appId || workspace.env?.platform?.appId;
-
-      if (!communityId || !appId) {
-        throw new Error('Missing community_id or app_id for single_app mode path resolution');
-      }
-      return `${communityId}/${appId}/${normalizedLocal}`;
-    }
-
-    case 'single_community': {
-      const commId = workspace.defaultContext?.communityId || workspace.env?.platform?.communityId;
-      if (!commId) {
-        throw new Error('Missing community_id for single_community mode path resolution');
-      }
-      return `${commId}/${normalizedLocal}`;
-    }
-
-    case 'multi_community':
-      // Workspace root = base folder
-      return normalizedLocal;
-  }
-}
-
-/**
- * Resolve Drive path to local path based on workspace mode
- * @param {Object} workspace - Workspace configuration
- * @param {string} drivePath - Path relative to user's base_folder_id
- * @returns {string} Path relative to workspace root
- */
-export function resolveToLocalPath(workspace, drivePath) {
-  const mode = detectWorkspaceMode(workspace);
-
-  switch (mode) {
-    case 'single_app': {
-      const communityId = workspace.defaultContext?.communityId || workspace.env?.platform?.communityId;
-      const appId = workspace.defaultContext?.appId || workspace.env?.platform?.appId;
-
-      const appPrefix = `${communityId}/${appId}/`;
-      if (drivePath.startsWith(appPrefix)) {
-        return './' + drivePath.slice(appPrefix.length);
-      }
-      throw new Error(`Drive path '${drivePath}' does not match workspace app '${appId}'`);
-    }
-
-    case 'single_community': {
-      const commId = workspace.defaultContext?.communityId || workspace.env?.platform?.communityId;
-      const commPrefix = `${commId}/`;
-      if (drivePath.startsWith(commPrefix)) {
-        return './' + drivePath.slice(commPrefix.length);
-      }
-      throw new Error(`Drive path '${drivePath}' does not match workspace community '${commId}'`);
-    }
-
-    case 'multi_community':
-      return './' + drivePath;
-  }
-}