@descix/cli 1.0.1 → 1.0.4

package/templates/agent-copilot.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.

package/templates/agent-cursor.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.

package/templates/alignment-schema.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "Schema reference for .descix/alignment.json — cloud brain alignment config",
+  "version": "1.0",
+  "apps": [
+    {
+      "app_id": "example-app",
+      "kb": "General",
+      "role": "Description of what this KB covers"
+    }
+  ],
+  "defaults": {
+    "level": 3,
+    "thinking": -1,
+    "tokens": true
+  },
+  "persona_cache": {
+    "path": ".descix/cloud-persona.md",
+    "ttl_seconds": 3600
+  }
+}

package/templates/cloud-brain-hook.sh

@@ -0,0 +1,20 @@
+#!/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"

package/templates/drive/README.md

@@ -31,7 +31,7 @@ app/
 
 These templates are:
 1. Uploaded to Google Drive (by admin)
-2. Referenced by folder ID in `DeSciX_Cloud/defaults-config.json`
+2. Referenced by folder ID in `DeSciX_Cloud/microservice/defaults-config.json`
 3. Copied by the backend when `create_community_with_app` is called
 
 **Note:** Code scaffolds (site, microservice) live in `../scaffolds/`, not here. Drive templates contain only content that syncs to/from Google Drive.

package/templates/drive_templates/README.md

@@ -74,7 +74,7 @@ These are NOT automatically replaced - they serve as guidance for the user to ed
 If you need to re-upload:
 1. Upload the `community_template/` folder to the target Drive folder
 2. Upload the `agent_app_template/` folder to the target Drive folder
-3. Update folder IDs in `DeSciX_Cloud/defaults-config.json`
+3. Update folder IDs in `DeSciX_Cloud/microservice/defaults-config.json`
 
 **Note:** Default icons are already included (from `DeSciX_PWA/assets/icon.png`).
 
@@ -87,7 +87,7 @@ If you need to re-upload:
 
 ## Configuration
 
-Template folder IDs are stored in `DeSciX_Cloud/defaults-config.json` (not secrets):
+Template folder IDs are stored in `DeSciX_Cloud/microservice/defaults-config.json` (not secrets):
 
 ```json
 "DRIVE_COMMUNITY_TEMPLATE_FOLDER_ID": "1ocVhrODQPGMICWmod3OWSGAj4-t6-o-B",

package/templates/scaffolds/README.md

@@ -16,18 +16,14 @@ Code cannot live in Drive because:
 
 ## Available Scaffolds
 
-### Site (`site/`)
+### Site — owned by `@descix/app-sdk`
 
-A hello-world static site with:
-- `index.html` - Main entry point
-- `styles.css` - Basic styling
-- `app.js` - Client-side JavaScript
-- `README.md` - Usage instructions
+The site scaffold does NOT live here. It is owned by `@descix/app-sdk` (`scaffold/site/`),
+because its `DeSciXAppSDK.js` is generated from that package's template and bridgeResolver, and
+because `@descix/sdk/app`'s `descix-app` bin scaffolds the same bytes. The CLI consumes the
+`SITE_SCAFFOLD_DIR` constant that package exports rather than keeping a copy.
 
-**Install with:**
-```bash
-descix site init
-```
+**Install with:** `descix site init`, or `descix-app init` from `@descix/sdk`.
 
 ### Microservice (`microservice/`)