@descix/cli 1.0.1 → 1.0.3

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/`)
 

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -146,6 +146,30 @@ descix kb build -c descix -a myapp
 
 ---
 
+### Calling /apifront from your microservice (data plane)
+
+**The microservice IS the CLI's api-client running in the cloud** (CEO-D-2026-06-02-APP-MICROSERVICE-IS-CLI-CLIENT-WALLET-SIG). To call Core commands (`app_records_*`, `get_app_asset`, `get_asset_upload_token`, RAG, ...) the scaffold's `mcpClient` authenticates to `/apifront` **exactly like the CLI**: it holds the **developer's own durable credential** (`wallet_address` + `signature`) and calls `reconnect_by_wallet` to mint a session — then makes calls **as the developer**. There is NO `register-delegate`, NO `SERVICE_KEY`, NO service account, NO OIDC.
+
+**Provide the developer credential (gitignored / secret — never checked in):**
+1. Copy `dev-overrides.example.json` → `dev-overrides.json` (this file is `.gitignore`d).
+2. Fill in `DEVELOPER_WALLET_ADDRESS` + `DEVELOPER_SIGNATURE` — your own values from `.descix/wallet.json` (the durable `signature`, not the expiring session token).
+3. In prod these come from a **secret**, never a checked-in file. They must NOT live in `defaults-config.json` (the signature is a credential).
+
+The scaffold reads them via `utils.DEVELOPER_WALLET_ADDRESS` / `utils.DEVELOPER_SIGNATURE` and HARD-FAILS (no fallback) if absent.
+
+**Canonical microservice onboarding sequence:**
+```bash
+descix app create   -c <community> -a <app>
+descix app init      -a <community>-<app>
+descix app set-port  -a <community>-<app> -p <port>
+descix microservice register
+# then: cp dev-overrides.example.json dev-overrides.json  and fill in the developer credential
+```
+
+> `descix microservice register-delegate` still exists for genuine **service-slot** mesh calls (one service calling another's tools as a delegate). It is NOT used for the app **data plane** — that authenticates as the developer per the model above.
+
+---
+
 ### descix microservice vectorize
 
 **Description:** Vectorize a SERVICE_README for tell_me_how discovery
@@ -384,6 +408,12 @@ For individual app folders, create `.descix/context.json`:
 2. Restart Cursor completely
 3. Check `.cursor/mcp.json` exists with `descix` server
 
+### "401 Unauthorized on a loopback / mesh call"
+For the app data plane, your service authenticates AS the developer (wallet_address + signature). A 401 means the
+developer credential is missing or wrong: check `DEVELOPER_WALLET_ADDRESS` + `DEVELOPER_SIGNATURE` in the gitignored
+`dev-overrides.json` (dev) / the secret (prod). Then restart the service.
+Discover it via `descix tell-me-how "my service gets 401 on a loopback call"`.
+
 ### "Session expired"
 Run `descix reconnect` or `descix login`
 

package/templates/scaffolds/microservice/app.js

@@ -5,6 +5,7 @@
  */
 
 import express from 'express';
+import http from 'http';
 import cors from 'cors';
 import { initializeServiceConfig, utils } from './services/utils.js';
 import { killExistingProcess } from '@descix/cloud-core';
@@ -12,12 +13,55 @@ import apiRouter from './services/apiFront.js';
 
 const app = express();
 
+/**
+ * Bind the http.Server with a bounded retry on EADDRINUSE.
+ *
+ * DEV RESTART RACE (CEO-D-2026-06-01-SCAFFOLD-RESIDUALS, fix #2):
+ *   killExistingProcess() SIGKILLs the prior instance on THIS port and returns
+ *   synchronously, then we bind immediately. The kernel may not have fully released
+ *   the old listening socket yet (it can linger briefly after a kill -9), so the first
+ *   bind can throw EADDRINUSE on a fast kill-then-restart. We retry the bind a few times
+ *   with a short backoff so dev restarts don't flake. Any non-EADDRINUSE listen error
+ *   fails loud (no swallowing); after the retries are exhausted we exit 1.
+ *
+ * NOTE: we bind an explicit http.Server (not app.listen) so the 'error'/'listening'
+ * handlers attach to the SAME object we retry on. A server that failed to bind is left
+ * unbound and can be re-listened safely.
+ */
+function listenWithRetry(server, port, { retries = 10, delayMs = 150 } = {}) {
+    let attempt = 0;
+
+    const onError = (err) => {
+        if (err && err.code === 'EADDRINUSE' && attempt < retries) {
+            attempt += 1;
+            console.warn(`[Service] Port ${port} busy (EADDRINUSE), retry ${attempt}/${retries} in ${delayMs}ms...`);
+            setTimeout(() => server.listen(port), delayMs);
+            return;
+        }
+        // Not a transient bind race (or retries exhausted) — fail loud.
+        console.error(`[Service] Failed to bind port ${port}:`, err?.message || err);
+        process.exit(1);
+    };
+
+    server.on('error', onError);
+    server.on('listening', () => {
+        console.log(`[Service] Listening on port ${port}`);
+        console.log(`[Service] Environment: ${utils.DEPLOY_ENV || 'unknown'}`);
+    });
+
+    server.listen(port);
+}
+
 // Initialize Config (Async)
 // In a real app, we might want to block startup until config is loaded
 initializeServiceConfig().then(() => {
     
-    // Kill any existing instances of this service in debug mode
-    killExistingProcess(import.meta.url, utils.DEBUG_LOCAL);
+    // Resolve this service's own port up front so process cleanup is scoped to it.
+    const port = utils.PORT;
+
+    // Kill ONLY a prior instance of THIS service (scoped to its own port) in debug mode.
+    // Port-scoping guarantees we never kill an unrelated app.js (e.g. the Core :4000 backend).
+    killExistingProcess(import.meta.url, utils.DEBUG_LOCAL, port);
     
     // Middleware
     app.use(cors({ origin: true })); // Allow all origins (controlled by Core proxy)
@@ -32,17 +76,14 @@ initializeServiceConfig().then(() => {
     app.use('/api', apiRouter);
 
     // Start Server
-    const port = utils.PORT || 8080;
-    
-    if (port === 'auto') {
-        console.error('[Service] CRITICAL ERROR: Port is "auto". Gateway registration failed.');
+    if (!port || port === 'auto') {
+        console.error('[Service] CRITICAL ERROR: Port is missing or "auto". Gateway registration failed.');
         process.exit(1);
     }
 
-    app.listen(port, () => {
-        console.log(`[Service] Listening on port ${port}`);
-        console.log(`[Service] Environment: ${utils.DEPLOY_ENV || 'unknown'}`);
-    });
+    // Bind with a bounded retry so a fast dev kill-then-restart doesn't flake on EADDRINUSE.
+    const server = http.createServer(app);
+    listenWithRetry(server, port);
 
 }).catch(err => {
     console.error('[Service] Failed to initialize config:', err);

package/templates/scaffolds/microservice/app.yaml

@@ -3,6 +3,6 @@ instance_class: F1
 automatic_scaling:
   max_instances: 1
 env_variables:
-  DEPLOY_ENV: "production"
-  CONFIG_SECRET_NAME: "descix_config"
+  DEPLOY_ENV: "prod"
+  CONFIG_SECRET_NAME: "descix_config_prod"
   CONFIG_SECRET_VERSION: "latest"

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

@@ -0,0 +1,4 @@
+{
+  "_comment": "Per-env NON-SECRET config for the dev environment. Layer 2 of the cloud-core bootstrap (process.env > defaults-config-{env}.json > defaults-config.json > Secret Manager). FIRESTORE_DATABASE_ID is a UNIVERSAL required key for every cloud-core consumer and is deliberately null here: cloud-core hard-fails at boot on a null required key, which is correct. Set it to your named Firestore database. It is left null rather than given a plausible default because a wrong database id writes silently to the wrong place — a hard failure at boot is the cheaper outcome.",
+  "FIRESTORE_DATABASE_ID": null
+}

package/templates/scaffolds/microservice/dev-overrides.example.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Copy this file to dev-overrides.json (GITIGNORED) and fill in the developer credential. The microservice authenticates to /apifront AS the developer — exactly like the CLI — using these. In prod these come from a SECRET, never from a checked-in file. defaults-config.json must NOT contain the signature (it is a credential).",
+  "DEVELOPER_WALLET_ADDRESS": "0xYOUR_WALLET_ADDRESS",
+  "DEVELOPER_SIGNATURE": "PASTE_YOUR_DURABLE_SIGNATURE_FROM_.descix/wallet.json"
+}

package/templates/scaffolds/microservice/manifest.json

@@ -2,7 +2,6 @@
   "service": {
     "name": "sample-service",
     "version": "1.0.0",
-    "domain": "sample-service.descix.net",
     "description": "Sample DeSciX Add-on Service",
     "healthEndpoint": "/health",
     "debugPort": 3003,

package/templates/scaffolds/microservice/package.json

@@ -12,15 +12,15 @@
   },
   "dependencies": {
     "@descix/cloud-core": "^1.0.0",
-    "@google-cloud/firestore": "^7.1.0",
+    "@descix/platform-api": "^2.0.0",
     "@google-cloud/secret-manager": "^5.0.1",
     "@google-cloud/storage": "^7.7.0",
     "axios": "^1.6.2",
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
-    "google-auth-library": "^9.4.1",
-    "@descix/sdk": "^1.0.0"
+    "@descix/sdk": "^1.0.0",
+    "@descix/cli": "^1.0.0"
   },
   "devDependencies": {
     "nodemon": "^3.0.2"

package/templates/scaffolds/microservice/scripts/register.js

@@ -1,55 +1,70 @@
 /**
  * Service Registration Script
- * 
- * Registers the service manifest with DeSciX Cloud.
+ *
+ * Registers this service's manifest with the DeSciX platform.
  * Usage: npm run register
+ *
+ * THIS SCRIPT CONSUMES THE DOOR. It calls Cloud's `register_service` command over apifront,
+ * through `@descix/platform-api/service-bootstrap` — the ONE owner of "a microservice registers
+ * its manifest". It does NOT write the ServiceManifests collection directly.
+ *
+ * WHY THAT MATTERS (this is not a style preference — it was measured):
+ *   The previous version of this script opened a Firestore client and `set()` the manifest
+ *   verbatim into `ServiceManifests`. That bypassed every check the platform performs at
+ *   registration, and the platform DERIVES a service's domain at that door. A verbatim write
+ *   therefore stored a manifest with `service.domain === undefined`, and the router then composed
+ *   its endpoint as `https://${service.domain}/api` — the literal string `https://undefined/api`.
+ *   That is a valid URL naming a host called "undefined", so nothing threw, nothing warned, and
+ *   the service simply never answered. Every service scaffolded from this template shipped that
+ *   bypass. Going through the door also gets the manifest VECTORIZED, which is what makes the
+ *   service's commands discoverable by `tell_me_how` — a direct write never did.
+ *
+ * AUTHORIZATION is a platform-runtime service-account OIDC identity token minted from ADC
+ * (audience = CORE_API_URL). On Cloud Run that works with no setup. Under local developer ADC,
+ * ID-token minting is unsupported without impersonation and this reports a named failure — it
+ * does not fall back to anything.
  */
 
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { Firestore } from '@google-cloud/firestore';
+import { createServiceBootstrap } from '@descix/platform-api/service-bootstrap';
+import { initializeServiceConfig, utils } from '../services/utils.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Load Manifest
-const manifestPath = path.resolve(__dirname, '../manifest.json');
-const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 async function register() {
-    console.log(`[Register] Registering service: ${manifest.service.name}`);
-    
-    // Connect to Firestore (uses ADC)
-    // Assumes we are running in a context with access to the Core project
-    // OR we might need to hit an admin API endpoint on Core if we don't have direct DB access.
-    // For this template, we'll assume direct DB access (common for internal services)
-    // or provide instructions to copy output to Core.
-
-    // OPTION: We could check if we have CREDENTIALS, if not, output the JSON 
-    // for the user to paste into the Core admin console.
-
-    try {
-        const firestore = new Firestore();
-        const docRef = firestore.collection('ServiceManifests').doc(manifest.service.name);
-        
-        await docRef.set({
-            ...manifest,
-            registeredAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            status: 'active'
-        });
-
-        console.log(`[Register] SUCCESS: Registered ${manifest.service.name}`);
-        console.log(`[Register] Domain: ${manifest.service.domain}`);
-        console.log(`[Register] Commands: ${Object.keys(manifest.commands).join(', ')}`);
-
-    } catch (error) {
-        console.error('[Register] FAILED:', error.message);
-        console.log('\n[Tip] If you don\'t have direct Firestore access, create a document in the "ServiceManifests" collection with this ID and content:');
-        console.log(`ID: ${manifest.service.name}`);
-        console.log(JSON.stringify(manifest, null, 2));
+    await initializeServiceConfig();
+
+    const manifestPath = path.resolve(__dirname, '../manifest.json');
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+    const bootstrap = createServiceBootstrap({
+        manifest,
+        // Running this script IS the explicit opt-in; there is no config key to consult. The
+        // key name is still supplied so any refusal names the boot-time knob a service would use.
+        selfRegister: true,
+        selfRegisterConfigKey: 'npm run register',
+        // No hardcoded default: CORE_API_URL is the env-correct apifront endpoint from
+        // defaults-config-{env}.json, and it is also the OIDC audience.
+        coreApiUrl: utils.CORE_API_URL,
+        // Used ONLY to name the derived domain in a message. The platform, not this script,
+        // owns the derivation.
+        siteDomain: utils.SITE_DOMAIN,
+    });
+
+    const result = await bootstrap.register();
+
+    if (result.status !== 'ok') {
+        console.error(`[Register] ${manifest.service.name}: registration ${result.status} — ${result.error || result.reason}`);
+        process.exit(1);
     }
+    console.log(`[Register] SUCCESS: ${manifest.service.name} registered via register_service`);
+    console.log(`[Register] Commands: ${Object.keys(manifest.commands).join(', ')}`);
 }
 
-register();
+register().catch((error) => {
+    // Never silent: a registration this script could not even attempt is reported and exits non-zero.
+    console.error(`[Register] FAILED: ${error.message}`);
+    process.exit(1);
+});