@descix/cli 1.0.1 → 1.0.4

package/lib/workspace-identity.js

@@ -0,0 +1,92 @@
+/**
+ * THE ONE OWNER OF "whose app is this workspace, and where does it point".
+ *
+ * WHY (measured 2026-08-29): `descix init -c egpt -a godsworld` wrote
+ * `env.products[0].appId = "godsworld"` and nothing else, while `agent-files.js` read
+ * `env.platform.appId`, `defaultContext.appId` and a TOP-LEVEL `config.apiUrl` — three keys the
+ * init path never writes. The reader missed on every one and fell through to the literals
+ * `'my-app'` and the production origin. The measured result: the four generated
+ * agent-instruction files named `my-app` and that origin, and named the developer's
+ * actual app and community ZERO times.
+ *
+ * That is a READER/WRITER MISMATCH, which is the mirror-drift bug class in its purest form —
+ * two modules each holding their own idea of the workspace's shape. The cure is this module:
+ * ONE reader, over the keys the writer actually writes, consumed by every surface that needs
+ * the workspace's identity. `registerApp()` is the writer; this is its reader.
+ *
+ * NO FALLBACK LITERALS. A fact this module cannot find is returned as `null` and the caller
+ * decides loudly. `'my-app'` was never a default — it was a wrong answer wearing a default's
+ * clothes, and it shipped in every file the CLI generated.
+ */
+
+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.
+ *
+ * @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
+ *                          only has the JSON).
+ * @returns {{ appId: string|null, communityId: string|null, apiUrl: string|null,
+ *             originSource: string|null }}
+ */
+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 legacy = config.defaultContext || {};
+
+    const appId =
+        platform.appId ||
+        product.appId ||
+        legacy.appId ||
+        null;
+
+    const communityId =
+        platform.communityId ||
+        product.communityId ||
+        legacy.communityId ||
+        config.primaryCommunity ||
+        null;
+
+    // The origin comes from the ONE origin owner, over the same sources every other surface
+    // resolves against — including DESCIX_API_URL, because `descix --env dev init` is the
+    // developer stating their choice at exactly the moment these files are written.
+    // Under (A') this ALWAYS yields an origin: a workspace that named none resolves to the
+    // declared default, carrying `source: default`. The generated files therefore state the
+    // origin AND where it came from, instead of either guessing or going silent. A configured
+    // origin that is unusable still THROWS here — writing agent files against a broken origin
+    // would bake the breakage into four files the developer's agent then trusts.
+    const resolved = resolveOrigin({
+        envVar: process.env.DESCIX_API_URL,
+        workspaceEnvApiUrl: env.apiUrl,
+        legacyApiUrl: config.apiUrl,
+    });
+
+    return {
+        appId,
+        communityId,
+        apiUrl: resolved.origin,
+        originSource: resolved.source,
+    };
+}
+
+/**
+ * True when the identity is complete enough to generate honest agent-instruction files.
+ * `apiUrl` is deliberately NOT required: a workspace can legitimately exist before an
+ * environment is chosen, and the generated files say so in words rather than guessing.
+ *
+ * @param {{appId: string|null, communityId: string|null}} identity
+ * @returns {boolean}
+ */
+export function isIdentityNamed(identity) {
+    return Boolean(identity && identity.appId && identity.communityId);
+}

package/lib/workspace-utils.js

@@ -1,49 +1,36 @@
 /**
  * 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
+ * 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) {
-  // Strict Mode Validation: Prioritize explicit mode
+  // Explicit mode declaration
   if (workspace.mode) {
     return workspace.mode;
   }
-  
-  // Infer from structure (fallback)
-  if (workspace.communities && Object.keys(workspace.communities).length > 0) {
-    const communityCount = Object.keys(workspace.communities).length;
-    if (communityCount > 1) {
-      return 'multi_community';
-    }
-    // Single community in communities object
-    const community = Object.values(workspace.communities)[0];
-    const appCount = Object.keys(community.apps || {}).length;
-    return appCount > 1 ? 'single_community' : 'single_app';
-  }
-  
-  // Legacy format: single community at root
-  if (workspace.community_id && workspace.app_id) {
-    return 'single_app';
-  }
-  
-  if (workspace.community_id && workspace.apps) {
-    return Object.keys(workspace.apps).length > 1 ? 'single_community' : 'single_app';
+
+  // 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 && workspace.defaultContext.communityId && workspace.defaultContext.appId) {
-     return 'single_app';
+  if (workspace.defaultContext?.communityId && workspace.defaultContext?.appId) {
+    return 'single_app';
   }
-  
-  throw new Error('Unable to determine workspace mode from configuration');
+
+  throw new Error('Unable to determine workspace mode from configuration. Expected v2.1 format (env.platform / env.products).');
 }
 
 /**
@@ -54,37 +41,31 @@ export function detectWorkspaceMode(workspace) {
  */
 export function resolveToDrivePath(workspace, localPath) {
   const mode = detectWorkspaceMode(workspace);
-  
+
   // Normalize local path (remove leading ./)
   const normalizedLocal = localPath.replace(/^\.\//, '');
-  
+
   switch (mode) {
-    case 'single_app':
-      // Workspace root = app folder
-      // Local: ./kb/General/file.md
-      // Drive: {community_id}/{app_id}/kb/General/file.md
-      const communityId = workspace.community_id || (workspace.defaultContext && workspace.defaultContext.communityId);
-      const appId = workspace.app_id || (workspace.defaultContext && workspace.defaultContext.appId);
-      
+    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');
+        throw new Error('Missing community_id or app_id for single_app mode path resolution');
       }
       return `${communityId}/${appId}/${normalizedLocal}`;
-      
-    case 'single_community':
-      // Workspace root = community folder
-      // Local: ./agent/kb/General/file.md
-      // Drive: {community_id}/agent/kb/General/file.md
-      const commId = workspace.community_id || (workspace.communities && Object.keys(workspace.communities)[0]);
+    }
+
+    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');
+        throw new Error('Missing community_id for single_community mode path resolution');
       }
       return `${commId}/${normalizedLocal}`;
-      
+    }
+
     case 'multi_community':
       // Workspace root = base folder
-      // Local: ./descix/agent/kb/General/file.md
-      // Drive: descix/agent/kb/General/file.md
       return normalizedLocal;
   }
 }
@@ -97,30 +78,29 @@ export function resolveToDrivePath(workspace, localPath) {
  */
 export function resolveToLocalPath(workspace, drivePath) {
   const mode = detectWorkspaceMode(workspace);
-  
+
   switch (mode) {
-    case 'single_app':
-      // Remove community_id/app_id prefix
-      const communityId = workspace.community_id || (workspace.defaultContext && workspace.defaultContext.communityId);
-      const appId = workspace.app_id || (workspace.defaultContext && workspace.defaultContext.appId);
-      
+    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}' implies app '${appId}', but workspace is configured for '${appId}'`);
-      
-    case 'single_community':
-      // Remove community_id prefix
-      const commId = workspace.community_id || (workspace.communities && Object.keys(workspace.communities)[0]);
+      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}' implies community '${commId}', but workspace is configured for '${commId}'`);
-      
+      throw new Error(`Drive path '${drivePath}' does not match workspace community '${commId}'`);
+    }
+
     case 'multi_community':
-      // No prefix to remove
       return './' + drivePath;
   }
 }

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DeSciX/DeSciXCore.git",
+    "directory": "descix-cli"
+  },
   "type": "module",
   "main": "./bin/descix.js",
   "bin": {
@@ -9,8 +14,9 @@
     "descix-mcp": "bin/mcp-server.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "pack": "npm pack"
+    "test": "node --test \"tests/*.test.js\"",
+    "pack": "npm pack",
+    "check:doc-paths": "node scripts/check-doc-paths.js"
   },
   "keywords": [
     "descix",
@@ -21,18 +27,19 @@
     "ai"
   ],
   "author": "DeSciX",
-  "license": "@Daita_DeSci_Community_License_v1/Daita_DeSci_Community_License_v1.pdf",
+  "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@descix/app-sdk": "^0.1.0",
+    "@descix/app-sdk": "^0.1.2",
     "@descix/sdk": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "axios": "^1.7.9",
     "chalk": "^5.6.2",
     "commander": "^14.0.1",
+    "google-auth-library": "^10.6.1",
     "googleapis": "^170.1.0",
     "inquirer": "^12.1.0",
     "ora": "^9.0.0",
-    "vite": "^6.2.0"
+    "@descix/platform-api": "^2.0.0"
   },
   "files": [
     "bin",
@@ -44,5 +51,11 @@
   ],
   "engines": {
     "node": ">=24.0.0"
+  },
+  "exports": {
+    ".": "./lib/service-api-client.js",
+    "./service-api-client": "./lib/service-api-client.js",
+    "./api-client": "./lib/api-client.js",
+    "./package.json": "./package.json"
   }
 }

package/templates/agent-claude.md

@@ -43,7 +43,8 @@ If it does:
 4. If `kb_ready` is true, skip KB setup and demonstrate value immediately:
    `descix chat -a <app_id> "What is this about?"` — show the user what the AI knows
 5. If `kb_ready` is false, skip the chat demo — the KB is not populated yet.
-   Proceed to setup (`descix init`, `app init`, `update kb`), then demo afterward.
+   Proceed to setup (`descix init`, `app init`, then a KB manifest + `kb corpus sync` —
+   see "KB sync is manifest-driven" below), then demo afterward.
    Frame it as: "Let's get this set up so you can start exploring."
 6. If `has_repo` is true and no source code is present locally, offer `descix clone -a <app_id>`.
    For non-technical users (infer from `agent_hint`): "Want to run this on your own machine?"
@@ -105,8 +106,7 @@ Until workspace context is verified working, **always use explicit flags**
 for all CLI commands:
 ```bash
 descix chat -c <community> -a <app> -q "..."
-descix update kb -c <community> -a <app>
-descix kb sync -c <community> -a <app> --kb General
+descix kb corpus sync -c <community> -a <app> -k <KB>
 ```
 
 Implicit defaults can silently target the wrong app. After setup, verify
@@ -116,9 +116,45 @@ with `descix chat -c <community> -a <app> -q "test"` before dropping flags.
 
 After setup, verify all of these pass:
 - [ ] App visible in `descix app list`
-- [ ] `descix update kb -c <community> -a <app>` succeeds (KB sync)
+- [ ] `descix kb corpus sync ... --dry-run --show-walk` walks the files you expect
+- [ ] `descix kb corpus sync -c <community> -a <app> -k <KB>` succeeds and reports a non-zero chunk count
 - [ ] `descix chat -c <community> -a <app> -q "..."` returns response with source attribution
 
+## KB sync is manifest-driven
+
+`descix kb corpus sync` is the KB sync. It is **git-aware**: it walks the sources named in a
+manifest, resolves them at a git ref, and upserts only what changed, purging stale chunks in the
+same pass.
+
+**The manifest is a precondition, not an optimisation — no manifest means nothing to sync.** It
+lives at `<localPath>/.descix/manifests/<KB-name>.json`, where `<localPath>` is the product's
+`localPath` in `workspace.json`. That directory holds manifests only; it is not where
+`workspace.json` lives. Minimal shape:
+
+```json
+{
+  "kb_name": "General",
+  "sync_mode": "local",
+  "sources": [
+    { "path": "docs", "ref": "main", "tier": 1, "doc_type": "documentation", "syncignore": ["node_modules/"] }
+  ]
+}
+```
+
+**Check before you write.** `--dry-run` enumerates would-be upserts and purges with no writes at
+all (exit 0 = no drift, exit 1 = drift); `--show-walk` prints the resolved ref and the walked
+files. Run the dry-run first, confirm the file count is what you expect, then sync:
+
+```bash
+descix kb corpus sync -c <community> -a <app> -k <KB> --dry-run --show-walk
+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
 
 To see your app in a browser:
@@ -127,10 +163,19 @@ To see your app in a browser:
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
 | Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
-| Run full gateway (multi-app) | `descix serve` (reverse proxy on :5173) |
+| Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
-For single-app development, a static server is sufficient. The gateway is only
-needed when running multiple apps or testing platform routing.
+A plain static server is enough to look at your HTML. `descix serve` is what you
+want as soon as the app needs the platform: it puts the App Shell, your app and
+`/apifront` on ONE HTTPS origin, which is what makes shell sign-in visible to
+your app and passkeys work at all.
+
+It serves exactly ONE app, standalone — detected from the directory you are
+standing in, or named with `--app <id>`. There is no store chrome under
+`descix serve`, and it starts nothing else (no backend, no dev server). The port
+resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
+never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
+gateway does not rewrite paths.
 
 ## Integrating Existing Content
 
@@ -142,6 +187,7 @@ If the repo already has content (an HTML page, a React app, an SDK with docs),
 **If the project has an `index.html` or web app already:**
 - Serve it directly — it IS the site. Don't duplicate into `site/`.
 - To add DeSciX integration (auth, API access), include `DeSciXAppSDK.js`
+  `DeSciXAppSDK.js` is GENERATED (from `descix-app-sdk/templates/DeSciXAppSDK.template.js`, with a `--check` drift gate) — copy it in, never hand-edit it; a local patch forks the bridge and stops inheriting its fixes.
   (scaffolded by `descix app init`) in your HTML:
   ```html
   <script src="DeSciXAppSDK.js"></script>
@@ -202,8 +248,9 @@ Every app has three parts:
 | Tool | Purpose |
 |------|---------|
 | `descix_doctor` | Startup diagnostic — call first |
-| `ask_question_to_app` | RAG chat with any app's knowledge base |
-| `query_knowledge_base` | Raw vector search (returns chunks) |
+| `ask_question_to_app` | RAG chat with any app's knowledge base (METERED — debits USD AI credits per actual token usage) |
+| `query_knowledge_base` | Raw vector search, returns chunks (METERED — small flat USD debit per call) |
+| `get_credit_balance` | Check your USD AI-credits balance; buy with `descix credits buy --usd <n>` |
 | `find_communities` | List communities on the platform |
 | `list_apps_for_community` | List apps in a community |
 | `tell_me_how` | Discover any platform capability by asking |
@@ -216,6 +263,107 @@ Every app has three parts:
 - `descix status` may suggest `descix setup` — that command doesn't exist. Use
   `descix init -c <community> -a <app> -p .` instead.
 
+## Cloud Brain Alignment
+
+After calling `descix_doctor`, check the `alignment` and `available_kbs` fields:
+
+### If `alignment` is present (already configured)
+You are bonded to cloud knowledge bases. **BEFORE starting any task**, query them:
+
+**Multi-app query (preferred — richer context):**
+```bash
+descix chat --apps APP1,APP2 -q "YOUR SPECIFIC QUESTION" --level 3 --thinking -1 --tokens
+```
+
+**Single-app query:**
+```bash
+descix chat --app APP_ID -q "YOUR SPECIFIC QUESTION" --level 3 --tokens
+```
+
+**MCP tool (if shell unavailable):**
+```
+ask_question_to_app({ app_id: "APP_ID", user_input: "YOUR SPECIFIC QUESTION" })
+```
+
+**Query parameters:**
+- `--level 1-5` — intelligence (1=fast lookup, 3=balanced, 5=deep reasoning)
+- `--thinking -1` — dynamic thinking budget; `0`=off, `N`=fixed tokens
+- `--tokens` — show token usage in response
+- Omit `--new` to continue the session thread (Gemini remembers context)
+
+Query **multiple times** during a task — not just at the start. Cross-reference KB answers with local files.
+
+### If `alignment` is null (not yet configured)
+Follow Checkpoint 4 from the doctor's `next_steps`:
+1. Show the user apps from `available_kbs` (from the doctor report)
+2. Ask: "Which knowledge bases should I always consult when helping you in this project?"
+3. Write their selections to `.descix/alignment.json`:
+```json
+{
+  "version": "1.0",
+  "apps": [
+    { "app_id": "selected_app", "kb": "General", "role": "user's description of this KB's domain" }
+  ],
+  "defaults": { "level": 3, "thinking": -1, "tokens": true }
+}
+```
+4. If user wants an app they don't have access to, guide them to `find_communities` to discover and join.
+
+### If `claude_code_detected` is true (Claude Code environment)
+Also create these files for always-on dynamic alignment:
+
+**`.claude/settings.json`** (merge with existing if present):
+```json
+{
+  "mcpServers": {
+    "descix": {
+      "command": "npx",
+      "args": ["descix", "mcp-serve"]
+    }
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/cloud-brain.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**`.claude/hooks/cloud-brain.sh`** (make executable):
+```bash
+#!/bin/bash
+set -euo pipefail
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ALIGNMENT="$PROJECT_DIR/.descix/alignment.json"
+[ ! -f "$ALIGNMENT" ] && exit 0
+REMINDER=$(node -e '
+const fs = require("fs");
+const cfg = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+const apps = cfg.apps || [];
+if (!apps.length) { process.exit(0); }
+const appList = apps.map(a => a.app_id).join(", ");
+const appsCsv = apps.map(a => a.app_id).join(",");
+const level = (cfg.defaults && cfg.defaults.level) || 3;
+const thinking = (cfg.defaults && cfg.defaults.thinking !== undefined) ? cfg.defaults.thinking : -1;
+const tokens = (cfg.defaults && cfg.defaults.tokens) ? "--tokens" : "";
+const roles = apps.map(a => "  • " + a.app_id + ": " + a.role).join("\n");
+const reminder = "CLOUD BRAIN ACTIVE — Aligned apps: " + appList + "\n\nYOU MUST query your cloud knowledge bases BEFORE starting any task. Do not guess when the KB knows.\n\nApps and their domains:\n" + roles + "\n\nMulti-app query:\n  descix chat --apps " + appsCsv + " -q \"YOUR QUESTION\" --level " + level + " --thinking " + thinking + " " + tokens + "\n\nSingle-app query:\n  descix chat --app APP_ID -q \"YOUR QUESTION\" --level " + level + " " + tokens + "\n\nMCP fallback:\n  ask_question_to_app({ app_id: \"APP_ID\", user_input: \"YOUR QUESTION\" })\n\nThreading: omit --new to continue session. Use --new only for unrelated topics.\nQuery MULTIPLE TIMES during a task. Cross-reference KB answers with local files.";
+process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: reminder } }));
+' "$ALIGNMENT" 2>/dev/null)
+[ -n "$REMINDER" ] && echo "$REMINDER"
+```
+
+This hook injects a reminder on EVERY prompt turn, surviving context compaction.
+
 ## After Bootstrap
 
 Once you understand the user's intent and have verified the success criteria,

package/templates/agent-cline.md

@@ -25,7 +25,8 @@ If it does:
 4. If `kb_ready` is true, skip KB setup and demonstrate value immediately:
    `descix chat -a <app_id> "What is this about?"` — show the user what the AI knows
 5. If `kb_ready` is false, skip the chat demo — the KB is not populated yet.
-   Proceed to setup (`descix init`, `app init`, `update kb`), then demo afterward.
+   Proceed to setup (`descix init`, `app init`, then a KB manifest + `kb corpus sync` —
+   see "KB sync is manifest-driven" below), then demo afterward.
    Frame it as: "Let's get this set up so you can start exploring."
 6. If `has_repo` is true and no source code is present locally, offer `descix clone -a <app_id>`.
    For non-technical users (infer from `agent_hint`): "Want to run this on your own machine?"
@@ -73,31 +74,77 @@ descix app init -a <app> -c <community>    # register app on platform
 Always use `-c <community> -a <app>` for all commands until verified:
 ```bash
 descix chat -c <community> -a <app> -q "..."
-descix update kb -c <community> -a <app>
+descix kb corpus sync -c <community> -a <app> -k <KB>
 ```
 
 ## Success Criteria
 
 - App visible in `descix app list`
-- KB sync succeeds: `descix update kb -c <community> -a <app>`
+- Dry-run walks the expected files: `descix kb corpus sync ... --dry-run --show-walk`
+- KB sync succeeds with a non-zero chunk count: `descix kb corpus sync -c <community> -a <app> -k <KB>`
 - Chat returns response: `descix chat -c <community> -a <app> -q "test"`
 
+## KB sync is manifest-driven
+
+`descix kb corpus sync` is the KB sync. It is **git-aware**: it walks the sources named in a
+manifest, resolves them at a git ref, and upserts only what changed, purging stale chunks in the
+same pass.
+
+**The manifest is a precondition, not an optimisation — no manifest means nothing to sync.** It
+lives at `<localPath>/.descix/manifests/<KB-name>.json`, where `<localPath>` is the product's
+`localPath` in `workspace.json`. That directory holds manifests only; it is not where
+`workspace.json` lives. Minimal shape:
+
+```json
+{
+  "kb_name": "General",
+  "sync_mode": "local",
+  "sources": [
+    { "path": "docs", "ref": "main", "tier": 1, "doc_type": "documentation", "syncignore": ["node_modules/"] }
+  ]
+}
+```
+
+**Check before you write.** `--dry-run` enumerates would-be upserts and purges with no writes at
+all (exit 0 = no drift, exit 1 = drift); `--show-walk` prints the resolved ref and the walked
+files. Run the dry-run first, confirm the file count is what you expect, then sync:
+
+```bash
+descix kb corpus sync -c <community> -a <app> -k <KB> --dry-run --show-walk
+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
 
 | Goal | Command |
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
 | Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
-| Run full gateway (multi-app) | `descix serve` (reverse proxy on :5173) |
+| Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
-Single-app dev: a static server is sufficient. Gateway is for multi-app or
-platform routing tests.
+A plain static server is enough to look at your HTML. `descix serve` is what you
+want as soon as the app needs the platform: it puts the App Shell, your app and
+`/apifront` on ONE HTTPS origin, which is what makes shell sign-in visible to
+your app and passkeys work at all.
+
+It serves exactly ONE app, standalone — detected from the directory you are
+standing in, or named with `--app <id>`. There is no store chrome under
+`descix serve`, and it starts nothing else (no backend, no dev server). The port
+resolves `--port` > `env.gateway.port` > 5173 and is printed with its source, so
+never hardcode `:5173`. Set your framework's base path to `/p/<appId>` — the
+gateway does not rewrite paths.
 
 ## MCP Tools
 
 - `descix_doctor` — Startup diagnostic (call first)
-- `ask_question_to_app` — RAG chat with app_id `{{appId}}`
-- `query_knowledge_base` — Vector search (raw chunks)
+- `ask_question_to_app` — RAG chat with app_id `{{appId}}` (METERED — debits USD AI credits per actual token usage)
+- `query_knowledge_base` — Vector search, raw chunks (METERED — small flat USD debit per call)
+- `get_credit_balance` — Check your USD AI-credits balance; buy with `descix credits buy --usd <n>`
 - `find_communities` — List communities
 - `list_apps_for_community` — List apps in a community
 - `tell_me_how` — Discover any platform capability (use scope "discovery" if "entitlements" is empty)
@@ -108,6 +155,7 @@ platform routing tests.
 **NEVER copy existing project files into `site/` or `kb/`.** Integrate in place:
 
 - **Existing HTML/JS app:** Serve as-is. Add `DeSciXAppSDK.js` for DeSciX integration.
+  `DeSciXAppSDK.js` is GENERATED (from `descix-app-sdk/templates/DeSciXAppSDK.template.js`, with a `--check` drift gate) — copy it in, never hand-edit it; a local patch forks the bridge and stops inheriting its fixes.
 - **React/Vite app:** Wrap root in `<AppShell appId="{{appId}}">` from `@descix/app-sdk/AppShell`.
 - **Auth only (no DeSciX UI):** Use `PowchClient` from `@descix/app-sdk/powch-client`.
 - **Existing docs:** Copy `docs/*.md` to `kb/General/` for sync. Keep originals as source of truth.
@@ -128,6 +176,18 @@ platform routing tests.
 - `descix status` may show "No workspace found" even when config exists — use explicit flags
 - `descix status` may suggest `descix setup` — use `descix init` instead
 
+## Cloud Brain Alignment
+
+After calling `descix_doctor`, check the `alignment` field:
+
+**If aligned:** Query your cloud KBs BEFORE starting any task:
+```
+ask_question_to_app({ app_id: "APP_ID", user_input: "YOUR SPECIFIC QUESTION" })
+```
+The `alignment.apps` array lists which app_ids to query. Ask specific questions, query multiple times.
+
+**If not aligned:** Follow Checkpoint 4 from the doctor's `next_steps` — ask the user which KBs to bond to, write `.descix/alignment.json`.
+
 ## After Bootstrap
 
 Rewrite this file with project-specific context once you understand the user's intent.