@descix/cli 1.0.5 → 1.0.6

package/README.md

@@ -15,11 +15,12 @@ npm install -g @descix/cli
     descix login
     ```
 
-2.  **Setup your workspace**:
+2.  **Initialize your workspace**:
     ```bash
-    descix setup
+    descix init
     ```
-    This will guide you through connecting your Google Drive and setting up your local environment.
+    This writes `.descix/workspace.json` for the current project. Pass `-c <community_id> -a <app_id>`
+    to pre-fill the app context, or `--from-invite <token>` to resolve an invite token.
 
     **Choosing an environment**:
     The `--dev` flag has been REMOVED. Its absence silently meant production, so the most common
@@ -58,40 +59,129 @@ Best for platform admins or agencies managing multiple communities.
 ## Core Commands
 
 - `descix login`: Authenticate with the platform.
-- `descix setup`: Initialize or repair your workspace configuration.
 - `descix status`: View your current environment status and workspace mode.
-- `descix init`: Create `.descix/workspace.json` for the current project.
-- `descix app create`: Show instructions; use `--quick -c <community> -a <name>` for template-only app creation, or use PWA / `descix-admin app create`.
-- `descix sync`: Sync content to the platform (Site, Assets).
-- `descix kb`: Manage Knowledge Base content (Pull -> Chunk -> Sync).
+- `descix init`: Initialize workspace for DeSciX app development (Git-aware) — writes `.descix/workspace.json`.
+- `descix app init`: Create (when it does not exist yet) and initialize an app — the one path to an app. See [Creating an App](#creating-an-app).
+- `descix site init` / `descix site upload`: Scaffold an app's site, then build and deploy it. See [Deploying a Site](#deploying-a-site).
+- `descix app sync-assets`: Sync local assets (`system_instructions.md`, `app_description.md`, `icon.png`) to the platform.
+- `descix drive pull` / `descix drive push`: Drive content authoring — pull from Drive to local markdown, push staging back to Drive.
+- `descix kb`: Manage Knowledge Bases (`list`, `create`, `delete`, and `corpus sync`).
 
 ## Knowledge Base Management (Git Mode)
 
-For apps managed via CLI (Git Mode), use the following commands to process your Knowledge Base locally:
+The CLI exposes exactly ONE knowledge-base sync surface: `descix kb corpus sync`, driven by a
+git-tracked corpus manifest. The older four-step local pipeline has been REMOVED — its invocations
+now exit non-zero and name this replacement.
 
-1.  **Pull**: Fetch source documents from Drive.
+1.  **Create** the knowledge base (once per KB):
     ```bash
-    descix kb pull
+    descix kb create -c <community_id> -a <app_id> -k <kb_name>
     ```
-2.  **Chunk**: Process documents into chunks locally.
+2.  **Author** a corpus manifest at `.descix/manifests/<kb_name>.json` describing the sources to sync.
+3.  **Sync** the corpus to the platform (Pinecone):
     ```bash
-    descix kb chunk
-    ```
-3.  **Sync**: Push chunks to the platform (Pinecone).
-    ```bash
-    descix kb sync
-    ```
-4.  **Build**: Run the full pipeline (Pull -> Chunk -> Sync).
-    ```bash
-    descix kb build
+    descix kb corpus sync -a <app_id> [-k <kb_name>]
     ```
+    It walks the git blobs at the manifest's ref, so only changed files are re-vectorized. Useful
+    flags: `--dry-run` (report drift, write nothing), `--show-walk` (print the resolved ref and the
+    files it would walk), `--ref <ref>` (override the git ref for all manifest sources).
+
+To fetch source documents from Google Drive into local markdown, use `descix drive pull`.
+
+## Creating an App
+
+`descix app init` is the one path to an app. It creates the app on the platform when it does not
+exist yet, then registers and scaffolds it locally — one command, not two.
+
+```bash
+descix app init -a <name> -c <community>
+```
+
+Pass `-c` to create a new app in that community. **Omit `-c` to initialize an app that already
+exists** — the CLI resolves the app from the Products registry and only does the local half.
+
+The command is idempotent, so re-running it on a half-made app finishes the job.
+
+**Options:**
+
+- `-a, --app <app_id>` (required): the app ID. With `-c`, this is the app NAME to create.
+- `-c, --community <id>`: the community to create the app in. It must already be materialized in
+  this environment. Required only for creation.
+- `-s, --short <short_name>`: the short id segment (no hyphens). The `app_id` is composed
+  **server-side** as `{community}-{short}`; defaults to `--app`.
+- `--overwrite`: when creating, overwrite an existing app record intentionally.
+- `--kb <name>`: knowledge base name (default: `General`).
+- `-p, --path <dir>`: local app directory (default: auto-detected, else the current directory).
+
+**What it does, in order:**
+
+1.  **Creates the app** (only when `-c` is given and the app does not exist): the server composes
+    the unique `app_id` and writes `Products/{app_id}` and `Community/{community}/Apps/{app_id}`.
+    Every app is guaranteed a default knowledge base at creation.
+2.  **Registers it in `.descix/workspace.json`** if it is not already mapped.
+3.  **Scaffolds the app folder**: creates `site/`, `microservice/` and `assets/`, and writes
+    `assets/system_instructions.md` and `assets/app_description.md` when they do not exist.
+4.  **Creates the knowledge base record** for Git-mode sync.
+
+It fails loud rather than guessing: initializing an app that does not exist without `-c` names the
+`-c` invocation that would create it; a `-c` that disagrees with the app's real community is
+refused; and `-p` against an already-mapped app names `descix app set-localpath` instead.
 
-## Provisioning
+**Next step** — author a corpus manifest at `.descix/manifests/<kb_name>.json`, then
+`descix kb corpus sync -a <app_id>`.
 
-**Communities and apps are created in the PWA** (Workspace Config / Device Setup / App Manager) or via **Admin CLI** (`descix-admin community create`, `descix-admin app create`) for platform admins. The user CLI does not create communities or full app structures; use `descix init` to write `.descix/workspace.json` and PWA or Admin CLI to create entities.
+Creating a **community** is a separate, admin-only operation: `descix community create` requires
+platform-admin membership and deploys a real ERC-20 token contract to live Polygon. App developers
+work inside a community that already exists.
 
-1.  Create your App in the PWA (Workspace Builder).
-2.  Run `descix setup` to hydrate your local folder structure.
+## Deploying a Site
+
+An app's site is scaffolded, then uploaded. `descix site upload` is the deploy verb — there is no
+`descix site deploy`.
+
+```bash
+descix site init      # scaffold site/ (optional — upload works on any site directory)
+descix site upload --env dev
+```
+
+### `descix site init`
+
+Copies the site scaffold — `index.html`, `app.js`, `styles.css`, `DeSciXAppSDK.js`, `README.md` —
+into the app's `site/` directory. The app must already be mapped in `.descix/workspace.json`.
+
+- `-f, --force`: overwrite an existing `site/` folder.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+It scaffolds site content only; it writes no manifest. Skip it entirely if you already have a site.
+
+### `descix site upload`
+
+Builds (when a manifest declares a build) and uploads the site to GCS, then updates the app's
+metadata. Files are uploaded straight to GCS with short-lived **signed URLs** issued by
+`get_site_deploy_token`; `confirm_site_deploy` then records the deploy and returns the site URL.
+
+- `-p, --path <localPath>`: directory to deploy (default `./site`). **Ignored when a site manifest
+  exists.**
+- `--preview`: deploy to the preview path.
+- `--full`: force a full upload, ignoring the unchanged-file delta.
+- `--dry-run`: show what would be deployed.
+- `--no-cache`: set `Cache-Control: no-cache`.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+**Site deploys target a cloud environment.** An upload that resolves to a local backend without
+this invocation naming its target is refused — pass `--env <dev|demo|prod>`.
+
+**Manifest-driven builds.** When `{app_root}/.descix/manifests/site.json` exists it takes over from
+`-p`. Author it yourself; nothing generates it for you. It declares the sources to walk and,
+optionally, a `buildCommand`, which runs in the app root with the environment-specific `VITE_*`
+build variables the server returns injected into its environment:
+
+```json
+{
+  "sources": [{ "path": "site/dist", "include": ["**/*"] }],
+  "buildCommand": "npm run build --prefix site"
+}
+```
 
 ## Airdrop Admin Operations (WS-ADMIN-B1)
 
@@ -103,25 +193,31 @@ Admin-only commands for triggering airdrop migration batch runs. Per CEO-D-MANUA
 
 Manually trigger the server-side `airdrop_execute_queue` command on the target environment. Assembles `pending_migrations` rows into per-community batches and (when `BATCH_UPDATE_BALANCES_BROADCAST_ENABLED=true`) broadcasts to the Powch HD wallet. When the broadcast flag is off (default for DEV), batches are assembled but the downstream Powch handler returns `stopped_at_broadcast_boundary` — useful for verifying queue shape without spending MATIC.
 
+**Read-only is the default.** Without `--apply`, the command runs as a dry run.
+
 **Options:**
 
+- `--dry-run`: Read-only preview — encode calldata, estimate gas, validate the net-zero invariant. No PK, no transaction, no state mutation. Mutually exclusive with `--apply`.
+- `--apply`: Live execution. Requires `--signer-pk-file` or the interactive prompt, and requires `--community`.
+- `--community <slug>`: Community slug for per-community batch scoping. **Required for `--apply`**; optional in dry-run mode, where omitting it returns an aggregate preview across communities.
+- `--signer-pk-file <path>`: Path to a file containing the admin signer PK (`0x` + 64 hex). Used for `--apply`; when omitted, the PK is requested at an interactive no-echo prompt. Inline PK flags and environment variables are rejected on security grounds (process-listing leak).
 - `--batch-size <n>`: Cap on users processed this run (server caps at `AIRDROP_MAX_RUN_USERS`; a larger `--batch-size` is clamped).
-- `--dry-run`: Assemble batches but skip the broadcast call entirely. Emits an `on_chain_log` row with `status: dry_run` for audit.
 
 **Examples:**
 
 ```bash
-# Dry run against DEV — safe to run repeatedly; no broadcast, no MATIC
+# Dry run against DEV — safe to run repeatedly; no PK, no tx, no state mutation
 descix airdrop execute-queue --env dev --dry-run
 
-# Execute a capped real run (10 users max this invocation)
-descix airdrop execute-queue --env dev --batch-size 10
+# Dry run scoped to one community
+descix airdrop execute-queue --env dev --dry-run --community smile
 
-# Execute a full queue run (still gated by BATCH_UPDATE_BALANCES_BROADCAST_ENABLED)
-descix airdrop execute-queue --env dev
-```
+# Live execution, capped at 10 users this invocation (prompts for the signer PK)
+descix airdrop execute-queue --env dev --apply --community smile --batch-size 10
 
-**Audit trail:** every invocation (dry-run or real) writes one `on_chain_log` row with `op.kind = "airdrop_execute_queue_trigger"` and `caller.operator_email = <invoking admin email>`.
+# Live execution reading the signer PK from a file
+descix airdrop execute-queue --env dev --apply --community smile --signer-pk-file ./signer.key
+```
 
 **Testing:**
 
@@ -131,4 +227,4 @@ cd DeSciX_Core/descix-cli && npm test
 
 ## Documentation
 
-For full documentation, please refer to the [DeSciX SDK Documentation](../../SERVICE_README_sdk.md).
+For full documentation, please refer to the [DeSciX SDK Documentation](./SERVICE_README_sdk.md).

package/agent-assets/reference/local-dev.md

@@ -143,10 +143,6 @@ KB querying will surface. If you fix something there, the fix reaches readers of
 nobody asking the KB — so do not assume KB coverage for a surface that has none. This is a known
 boundary, not a defect.
 
-`descix kb chunk`, `descix kb sync` and `descix update kb` still run but are **superseded
-duplicates** — each names `kb corpus sync` as its replacement in its own `--help` and is slated
-for removal. Do not put them in new instructions.
-
 #### What you put in a KB changes what comes out of it
 
 Retrieval is **vocabulary-dominated**, and when it goes wrong it does so silently. Measured against

package/bin/descix.js

@@ -11,7 +11,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { requireAuth } from '../lib/auth-guard.js';
-import { WorkspaceConfig } from '../lib/workspace-config.js';
+import { WorkspaceConfig, unmappedAppMessage } from '../lib/workspace-config.js';
 import { CLI_VERSION } from '../lib/cli-version.js';
 import { recordInvocationOrigin } from '../lib/origin.js';
 // Chat session pointer + the ONE rule for when a dead pointer may be self-healed.
@@ -2507,8 +2507,7 @@ siteCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -2518,9 +2517,10 @@ siteCommand
       console.log(chalk.cyan('\n📁 Adding site scaffold...\n'));
       
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
-      const stats = await copyScaffold('site', appPath, { 
-        verbose: true, 
-        force: options.force 
+      const stats = await copyScaffold('site', appPath, {
+        verbose: true,
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
       
       console.log(chalk.green(`\n✅ Site scaffold added (${stats.copied} files)\n`));
@@ -2874,8 +2874,7 @@ siteCommand
       if (!port) {
         const appConfig = workspaceConfig.getAppByAppId(appId);
         if (!appConfig) {
-          console.error(chalk.red('\n❌ App not found in workspace.json.'));
-          console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+          console.error(chalk.red(`\n❌ ${unmappedAppMessage(appId)}\n`));
           process.exit(1);
         }
         // Read site.port from the live env entry (not from the constructed copy)
@@ -3116,8 +3115,7 @@ microserviceCommand
       
       const appConfig = workspaceConfig.getAppByAppId(ctx.appId);
       if (!appConfig) {
-        console.error(chalk.red('\n❌ App not found in workspace.json.'));
-        console.log(chalk.gray('  Run "npx descix init" to set up your workspace.\n'));
+        console.error(chalk.red(`\n❌ ${unmappedAppMessage(ctx.appId)}\n`));
         process.exit(1);
       }
 
@@ -3149,7 +3147,8 @@ microserviceCommand
       const { copyScaffold } = await import('../lib/core/Hydrator.js');
       const stats = await copyScaffold('microservice', appPath, {
         verbose: true,
-        force: options.force
+        force: options.force,
+        substitute: { appId: ctx.appId, communityId: ctx.communityId }
       });
 
       // Configuration Injection
@@ -3158,15 +3157,16 @@ microserviceCommand
       const manifestPath = path.join(microserviceDir, 'manifest.json');
       const overridesPath = path.join(microserviceDir, 'dev-overrides.json');
 
-      // 1. Inject Context + Port into defaults-config.json
+      // 1. Inject Port into defaults-config.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolves {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so re-deriving them here would be a second derivation of one fact. The port is a
+      // workspace-derived RUNTIME value with no scaffold token, so it stays.
       try {
         const defaultsContent = await fs.readFile(defaultsPath, 'utf-8');
         const defaults = JSON.parse(defaultsContent);
-        defaults.community_id = ctx.communityId;
-        defaults.app_id = ctx.appId;
         defaults.LOCAL_PORT = microservicePort;
         await fs.writeFile(defaultsPath, JSON.stringify(defaults, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into defaults-config.json`));
+        console.log(chalk.gray(`  ✓ Injected port into defaults-config.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update defaults-config.json: ${err.message}`));
       }
@@ -3188,20 +3188,19 @@ microserviceCommand
         console.warn(chalk.yellow(`  ⚠ Could not claim package.json: ${err.message}`));
       }
 
-      // 2. Inject Context + Port into manifest.json
+      // 2. Inject Port into manifest.json.
+      // IDENTITY IS NOT SET HERE. copyScaffold resolved {{APP_ID}}/{{COMMUNITY_ID}} during the
+      // copy, so setting app_id/community_id/name again would be a second derivation of one fact —
+      // the exact mirror-drift shape that let a scaffold ship `community_id: 'descix'` while this
+      // block quietly wrote the right value into a different file.
+      // No domain is injected. A service does not declare its own domain — the platform derives
+      // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
       try {
         const manifestContent = await fs.readFile(manifestPath, 'utf-8');
         const manifest = JSON.parse(manifestContent);
-        manifest.service.app_id = ctx.appId;
-        manifest.service.community_id = ctx.communityId;
-        manifest.service.name = ctx.appId;
-        // No domain is injected. A service does not declare its own domain — the platform derives
-        // it ({app_id}.{SITE_DOMAIN}) at registration, and refuses a manifest that declares one.
-        // The literal this replaced was `${ctx.appId}.descix.net`: the PROD host, scaffolded into
-        // every service regardless of the env it would be registered against.
         manifest.service.debugPort = microservicePort;
         await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
-        console.log(chalk.gray(`  ✓ Injected context + port into manifest.json`));
+        console.log(chalk.gray(`  ✓ Injected port into manifest.json`));
       } catch (err) {
         console.warn(chalk.yellow(`  ⚠ Could not update manifest.json: ${err.message}`));
       }

package/lib/commands/auth.js

@@ -275,6 +275,7 @@ export async function loginDevice(options = {}) {
     diag(chalk.gray(`   ${walletPath}\n`));
     
     // Sync auto-purchase apps
+    let entitlementsSynced = true;
     spinner.start('Syncing app entitlements...');
     try {
       apiClient.setCredentials({
@@ -293,10 +294,25 @@ export async function loginDevice(options = {}) {
         spinner.succeed(chalk.gray('App entitlements up to date'));
       }
     } catch (error) {
+      entitlementsSynced = false;
       spinner.warn(chalk.yellow('Could not sync app entitlements'));
       diag(chalk.gray(`   ${error.message}\n`));
     }
-    
+
+    // DO NOT CLAIM SUCCESS ON A PARTIAL LOGIN, AND DO NOT EXIT 0.
+    // Credentials are saved either way, so this is genuinely partial rather than a failed login —
+    // but entitlements are what grant app access, so "you can now use all DeSciX CLI commands" is
+    // false when the sync failed. A script branching on the exit code is the caller least able to
+    // read the yellow warning above, which is why the code is the sharper half of this fix.
+    if (!entitlementsSynced) {
+      diag(chalk.yellow(
+        'Logged in, but app entitlements did NOT sync. Credentials are saved; commands needing an ' +
+        'entitlement may fail until you re-run `descix login`.\n'
+      ));
+      process.exitCode = 1;
+      return;
+    }
+
     diag(chalk.white('You can now use all DeSciX CLI commands!\n'));
 
   } catch (error) {

package/lib/commands/init.js

@@ -13,6 +13,10 @@ import { dirname, join } from 'path';
 // clone.js is imported dynamically inside the invite flow to avoid circular deps
 import { WorkspaceConfig } from '../workspace-config.js';
 import { generateAgentFiles } from '../agent-files.js';
+// The canonical KB-sync surface is owned by retired-kb-sync.js. Consume the constant: a literal
+// spelled here is a second derivation of the same fact, and the removed verb this replaced
+// reached a developer who had done everything right.
+import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -208,8 +212,9 @@ export async function runInit(apiClient, options = {}) {
 
     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.white(`  2. descix update kb -c ${communityId} -a ${appId}   # sync KB to Pinecone`));
-    console.log(chalk.white(`  3. descix chat -c ${communityId} -a ${appId} -q "test"  # verify RAG\n`));
+    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.green('✅ Workspace initialized.\n'));
     rl.close();
     return { created: ['.descix/workspace.json'], skipped: [], warnings: [] };
@@ -250,7 +255,7 @@ export async function initWorkspace(options) {
     created,
     skipped: [],
     warnings: [],
-    nextSteps: [`descix app init -a ${appId} -c ${communityId}`, `descix update kb -c ${communityId} -a ${appId}`]
+    nextSteps: [`descix app init -a ${appId} -c ${communityId}`, `${CANONICAL_KB_SYNC} -a ${appId}`]
   };
 }
 

package/lib/commands/kb.js

@@ -27,6 +27,10 @@ import { hydrateKb, pushStaging, checkStagingFiles } from '../core/Hydrator.js';
 import { processKb } from '../core/Chunker.js';
 import { syncKb, getSyncStatus } from '../core/Syncer.js';
 import * as driveADC from '../google-storage-adc.js';
+// The one canonical KB-sync surface, from its owner. Never spell it as a literal here: these
+// commands' next steps are read by a developer as instructions, so they must name the live verb
+// and nothing else.
+import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
 
 // ============ Pull Command ============
 
@@ -110,8 +114,7 @@ export async function runKbPull(apiClient, options) {
     if (!options.quiet) {
       console.log(chalk.cyan('\n📋 Next steps:'));
       console.log(chalk.gray('   1. Review files in kb/' + kbId + '/'));
-      console.log(chalk.gray('   2. Run "descix kb chunk" to generate chunks'));
-      console.log(chalk.gray('   3. Run "descix kb sync" to push to Pinecone\n'));
+      console.log(chalk.gray(`   2. Run "${CANONICAL_KB_SYNC} -a <app_id>" to push to Pinecone\n`));
     }
     
     return result;
@@ -220,8 +223,8 @@ export async function runKbPush(apiClient, options) {
     // Show next steps
     if (!options.quiet) {
       console.log(chalk.cyan('\n📋 Next steps:'));
-      console.log(chalk.gray('   1. Run "descix kb pull" to sync all Drive content'));
-      console.log(chalk.gray('   2. Run "descix kb chunk" to generate chunks\n'));
+      console.log(chalk.gray('   1. Run "descix drive pull" to sync all Drive content'));
+      console.log(chalk.gray(`   2. Run "${CANONICAL_KB_SYNC} -a <app_id>" to push to Pinecone\n`));
     }
     
     return result;

package/lib/commands/update.js

@@ -4,7 +4,6 @@
  * Commands for updating resources based on workspace.json context detection:
  *   descix update          # Auto-detect what to update
  *   descix update app      # Sync app assets to Drive
- *   descix update kb       # Sync KB + vectorize
  *   descix update site     # Deploy site to GCS
  *   descix update all      # Update everything
  * 

package/lib/core/Hydrator.js

@@ -726,11 +726,15 @@ export async function checkStagingFiles(stagingDir) {
  * 
  * @param {string} scaffoldType - 'site' or 'microservice'
  * @param {string} appPath - Path to the app directory
- * @param {Object} options - { verbose, force }
+ * @param {Object} options - { verbose, force, substitute }
+ * @param {{appId: string, communityId: string, appName?: string}} [options.substitute] - the
+ *   caller's real identity. Supply it for any scaffold a developer will actually use: without it
+ *   the copy is verbatim and every {{TOKEN}} ships unresolved. Omitting it is only appropriate
+ *   when materializing the raw template itself.
  * @returns {Promise<{copied: number}>}
  */
 export async function copyScaffold(scaffoldType, appPath, options = {}) {
-  const { verbose = false, force = false } = options;
+  const { verbose = false, force = false, substitute = null } = options;
   
   const scaffoldDir = SCAFFOLD_DIRS[scaffoldType];
   if (!scaffoldDir) {
@@ -767,8 +771,36 @@ export async function copyScaffold(scaffoldType, appPath, options = {}) {
   
   // Copy scaffold recursively
   const stats = { copied: 0 };
-  await copyDir(scaffoldDir, targetDir, stats, verbose);
-  
+  let values = null;
+  if (substitute) {
+    if (!substitute.appId || !substitute.communityId) {
+      throw new Error(
+        'copyScaffold: substitute requires both appId and communityId. Refusing to resolve a ' +
+        'scaffold against a partial identity — a half-substituted scaffold is harder to spot ' +
+        'than an unsubstituted one.'
+      );
+    }
+    values = {
+      APP_ID: substitute.appId,
+      COMMUNITY_ID: substitute.communityId,
+      APP_NAME: substitute.appName || substitute.appId,
+    };
+  }
+
+  const unresolved = [];
+  await copyDir(scaffoldDir, targetDir, stats, verbose, values, unresolved);
+
+  // FAIL LOUD. A placeholder that survives the copy reaches the developer as literal braces, and
+  // that is exactly the class of defect this substitution exists to end — so it must never be a
+  // warning. Name every offender so a new token added to a template cannot ship unnoticed.
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Scaffold "${scaffoldType}" has ${unresolved.length} unresolved placeholder(s): ` +
+      `${unresolved.join(', ')}. Every {{TOKEN}} in a scaffold needs a value in copyScaffold's ` +
+      `substitute map (see templates/scaffolds/README.md for the documented set).`
+    );
+  }
+
   return stats;
 }
 
@@ -785,21 +817,66 @@ async function hasContentInDir(dirPath) {
 }
 
 /**
- * Recursively copy a directory
+ * THE ONE OWNER of scaffold placeholder substitution.
+ *
+ * templates/scaffolds/README.md has documented this contract all along — "Scaffolds use these
+ * placeholders (replaced during copy): {{APP_NAME}}, {{APP_ID}}, {{COMMUNITY_ID}}" — but nothing
+ * ever performed the replacement. Both scaffolds shipped their placeholders and their sample
+ * literals verbatim, so a developer's site was titled `{{APP_NAME}}` and the sample handler
+ * queried a community that is not theirs.
+ *
+ * SUBSTITUTION, NOT A SECOND LITERAL. The fix resolves each token to the caller's real values;
+ * it does not swap one hardcoded community for another. That is what lets the same scaffold serve
+ * every community without the CLI knowing any of their names.
+ *
+ * @param {string} text - file contents
+ * @param {Record<string,string>} values - token name (without braces) -> replacement
+ * @returns {string}
  */
-async function copyDir(src, dest, stats, verbose) {
+function applyScaffoldTokens(text, values) {
+  return text.replace(/\{\{([A-Z_]+)\}\}/g, (whole, token) =>
+    Object.prototype.hasOwnProperty.call(values, token) ? values[token] : whole
+  );
+}
+
+/** A NUL byte is the cheap, dependency-free binary tell. Never rewrite bytes we cannot read. */
+function looksBinary(buf) {
+  return buf.includes(0);
+}
+
+/**
+ * Recursively copy a directory, optionally substituting scaffold tokens on the way.
+ *
+ * @param {Record<string,string>|null} values - when null, the copy is byte-for-byte verbatim
+ * @param {string[]} unresolved - collects `file:{{TOKEN}}` for tokens no value was supplied for
+ */
+async function copyDir(src, dest, stats, verbose, values = null, unresolved = [], relBase = '') {
   await fs.mkdir(dest, { recursive: true });
-  
+
   const entries = await fs.readdir(src, { withFileTypes: true });
-  
+
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+
     if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath, stats, verbose);
+      await copyDir(srcPath, destPath, stats, verbose, values, unresolved, rel);
     } else {
-      await fs.copyFile(srcPath, destPath);
+      if (values) {
+        const buf = await fs.readFile(srcPath);
+        if (looksBinary(buf)) {
+          await fs.copyFile(srcPath, destPath);
+        } else {
+          const out = applyScaffoldTokens(buf.toString('utf8'), values);
+          // Anything still wearing braces had no value supplied. Collect it rather than shipping
+          // it: an unresolved placeholder reaching a developer is the defect this exists to end.
+          for (const m of out.matchAll(/\{\{([A-Z_]+)\}\}/g)) unresolved.push(`${rel}:{{${m[1]}}}`);
+          await fs.writeFile(destPath, out);
+        }
+      } else {
+        await fs.copyFile(srcPath, destPath);
+      }
       stats.copied++;
       if (verbose) console.log(`  Copied: ${entry.name}`);
     }

package/lib/workspace-config.js

@@ -2,6 +2,29 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { ENV_ORIGINS } 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
+// that can go stale where nobody is watching.
+import { CANONICAL_KB_SYNC } from './commands/retired-kb-sync.js';
+
+/**
+ * THE ONE OWNER of "this app is not mapped in workspace.json, here is how to fix it".
+ *
+ * This text existed as three byte-identical copies in this file, and TWO OTHER call sites in
+ * bin/descix.js answered the same condition with a DIFFERENT and wrong remedy — `npx descix init`,
+ * which initialises a WORKSPACE and cannot map an app, so a developer who followed it stayed
+ * exactly as stuck. That is the mirror-drift tell: the same condition explained two ways, and the
+ * wrong one was the one a developer actually hit on the onboarding path.
+ *
+ * @param {string} appId - the app that is not mapped
+ * @returns {string}
+ */
+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.'
+  );
+}
 
 /**
  * ONE OWNER for turning a workspace-relative localPath into an absolute path.
@@ -248,6 +271,17 @@ export class WorkspaceConfig {
   /**
    * Save workspace configuration in v2.1 format.
    * Always writes env.platform / env.products structure.
+   *
+   * 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
+   * destroyed by the next `descix app set-port` — a writer re-serializing a known schema and
+   * discarding the rest. That is the same defect class as a record writer dropping a field it was
+   * never taught about, and it is invisible: the write succeeds, the file looks well-formed, and
+   * the loss is only discovered by whoever needed the missing key.
+   *
+   * The on-disk file is re-read at save time rather than trusted from construction, because the
+   * instance may have been held across another writer's save.
+   *
    * @param {string} [workspaceRoot] - Workspace root directory (uses stored root if not provided)
    * @returns {Promise<string>} Path to saved config
    */
@@ -266,7 +300,32 @@ export class WorkspaceConfig {
     // Build env block for v2.1 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.
+    const OWNED = ['version', 'workspaceRoot', 'type', 'env', 'driveConfig'];
+
+    let onDisk = {};
+    try {
+      const existing = await fs.readFile(configPath, 'utf-8');
+      const parsed = JSON.parse(existing);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) onDisk = parsed;
+    } catch (err) {
+      // ENOENT is the ordinary first save. A PRESENT-BUT-UNPARSEABLE file is different: carrying
+      // on would overwrite content we could not read, so refuse and name the file.
+      if (err.code !== 'ENOENT') {
+        throw new Error(
+          `Refusing to overwrite ${configPath}: it exists but could not be read as JSON ` +
+          `(${err.message}). Fix or remove it — saving now would destroy whatever it holds.`
+        );
+      }
+    }
+
+    const carried = {};
+    for (const [k, v] of Object.entries(onDisk)) {
+      if (!OWNED.includes(k)) carried[k] = v;
+    }
+
     const configData = {
+      ...carried,
       version: '2.1',
       workspaceRoot: path.resolve(root),
       type: this.type,
@@ -508,7 +567,7 @@ export class WorkspaceConfig {
         'Options:\n' +
         '  1. cd into an app directory\n' +
         '  2. Use flag: -a <app_id>\n\n' +
-        'Example: npx descix update kb -a daita'
+        `Example: npx ${CANONICAL_KB_SYNC} -a daita`
       );
     }
     
@@ -637,8 +696,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `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.'
+        unmappedAppMessage(appId)
       );
     }
 
@@ -687,8 +745,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `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.'
+        unmappedAppMessage(appId)
       );
     }
 
@@ -743,8 +800,7 @@ export class WorkspaceConfig {
 
     if (!entry) {
       throw new Error(
-        `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.'
+        unmappedAppMessage(appId)
       );
     }
 

package/package.json

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

package/templates/agent-claude.md

@@ -151,9 +151,6 @@ descix kb corpus sync -c <community> -a <app> -k <KB>
 descix kb corpus status -c <community> -a <app>
 ```
 
-`descix update kb`, `descix kb chunk` and `descix kb sync` still run, but each names
-`kb corpus sync` as its replacement in its own `--help` and is slated for removal. Do not put
-them in new instructions.
 
 ## Local Development
 

package/templates/agent-cline.md

@@ -115,9 +115,6 @@ descix kb corpus sync -c <community> -a <app> -k <KB>
 descix kb corpus status -c <community> -a <app>
 ```
 
-`descix update kb`, `descix kb chunk` and `descix kb sync` still run, but each names
-`kb corpus sync` as its replacement in its own `--help` and is slated for removal. Do not put
-them in new instructions.
 
 ## Local Development
 

package/templates/agent-copilot.md

@@ -115,9 +115,6 @@ descix kb corpus sync -c <community> -a <app> -k <KB>
 descix kb corpus status -c <community> -a <app>
 ```
 
-`descix update kb`, `descix kb chunk` and `descix kb sync` still run, but each names
-`kb corpus sync` as its replacement in its own `--help` and is slated for removal. Do not put
-them in new instructions.
 
 ## Local Development
 

package/templates/agent-cursor.md

@@ -115,9 +115,6 @@ descix kb corpus sync -c <community> -a <app> -k <KB>
 descix kb corpus status -c <community> -a <app>
 ```
 
-`descix update kb`, `descix kb chunk` and `descix kb sync` still run, but each names
-`kb corpus sync` as its replacement in its own `--help` and is slated for removal. Do not put
-them in new instructions.
 
 ## Local Development
 

package/templates/drive/app/kb/General/README.md

@@ -9,7 +9,7 @@ This folder contains the documents that power the AI assistant. Add your content
 ## How It Works
 
 1. **Add Documents**: Upload markdown, text, or PDF files to this folder
-2. **Sync**: Use `descix kb sync` to process and vectorize your documents
+2. **Sync**: Use `descix kb corpus sync -a <app_id>` to process and vectorize your documents
 3. **Query**: Users can now ask questions and get answers based on your content
 
 ## Folder Structure

package/templates/drive_templates/agent_app_template/kb/General/README.md

@@ -9,7 +9,7 @@ This folder contains the documents that power the AI assistant. Add your content
 ## How It Works
 
 1. **Add Documents**: Upload markdown, text, or PDF files to this folder
-2. **Sync**: Use `descix kb sync` to process and vectorize your documents
+2. **Sync**: Use `descix kb corpus sync -a <app_id>` to process and vectorize your documents
 3. **Query**: Users can now ask questions and get answers based on your content
 
 ## Folder Structure

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -237,7 +237,7 @@ tell_me_how({
 execute_remote_command({
   command: "create_app_for_community",
   params: {
-    community_id: "descix",
+    community_id: "{{COMMUNITY_ID}}",
     app_name: "My New App"
   }
 })
@@ -285,9 +285,9 @@ ask_question_to_app({
 {
   "version": "2.1",
   "env": {
-    "platform": { "appId": "daita", "communityId": "descix", "localPath": ".", "kbId": "General" },
+    "platform": { "appId": "daita", "communityId": "daita", "localPath": ".", "kbId": "General" },
     "products": [
-      { "appId": "docs", "communityId": "descix", "kbId": "sdk", "localPath": "descix-docs" }
+      { "appId": "docs", "communityId": "daita", "kbId": "sdk", "localPath": "descix-docs" }
     ]
   }
 }

package/templates/scaffolds/microservice/defaults-config.json

@@ -1,5 +1,7 @@
 {
   "DEBUG_LOCAL": true,
   "LOCAL_PORT": "auto",
-  "CORE_API_URL": "https://localhost:4000/apifront"
+  "CORE_API_URL": "https://localhost:4000/apifront",
+  "community_id": "{{COMMUNITY_ID}}",
+  "app_id": "{{APP_ID}}"
 }

package/templates/scaffolds/microservice/manifest.json

@@ -1,12 +1,12 @@
 {
   "service": {
-    "name": "sample-service",
+    "name": "{{APP_ID}}",
     "version": "1.0.0",
     "description": "Sample DeSciX Add-on Service",
     "healthEndpoint": "/health",
     "debugPort": 3003,
-    "app_id": "sample-app",
-    "community_id": "descix"
+    "app_id": "{{APP_ID}}",
+    "community_id": "{{COMMUNITY_ID}}"
   },
   "commands": {
     "sample_hello": {
@@ -21,7 +21,9 @@
             "description": "Message to echo"
           }
         },
-        "required": ["message"]
+        "required": [
+          "message"
+        ]
       }
     },
     "sample_analyze": {
@@ -36,7 +38,9 @@
             "description": "Topic to analyze"
           }
         },
-        "required": ["query"]
+        "required": [
+          "query"
+        ]
       }
     }
   },

package/templates/scaffolds/microservice/package.json

@@ -19,7 +19,7 @@
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
-    "@descix/sdk": "^1.0.0",
+    "@descix/sdk": "^2.0.0",
     "@descix/cli": "^1.0.0"
   },
   "devDependencies": {

package/templates/scaffolds/microservice/services/commandHandlers/sampleCommands.js

@@ -33,8 +33,8 @@ export const commands = {
             // CALL CORE TOOL: query_knowledge_base
             // This goes Service -> Cloud -> Vector DB -> Cloud -> Service
             const ragResult = await mcpClient.callTool('query_knowledge_base', {
-                community_id: 'descix',
-                app_id: 'docs',
+                community_id: '{{COMMUNITY_ID}}',
+                app_id: '{{APP_ID}}',
                 kb_id: 'sdk',
                 query: query
             }, _descix);