@descix/cli 1.0.1 → 1.0.4

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -2,11 +2,11 @@
 
 ## Overview
 
-The DeSciX SDK provides command-line tools and MCP (Model Context Protocol) integration for building applications on the DeSciX platform. The SDK enables developers to authenticate, manage workspaces, create apps, and leverage AI-assisted development through Cursor IDE integration.
+The DeSciX SDK provides command-line tools and MCP (Model Context Protocol) integration for building applications on the DeSciX platform. The SDK enables developers to authenticate, manage workspaces, create apps, and leverage AI-assisted development through editor MCP integration (Claude Code, Copilot, Cursor, Cline).
 
 **Key capabilities:**
 - CLI commands for all platform operations
-- MCP server for Cursor IDE integration
+- MCP server integration for Claude Code, Copilot, Cursor and Cline
 - Intelligent tool discovery via `tell_me_how`
 - Entitlements-driven workspace setup
 - Git-aware project initialization
@@ -28,23 +28,22 @@ npm link
 
 ## CLI Commands
 
-### descix setup
+### descix quickstart
 
-**Description:** One-time workspace configuration wizard
-**Use when:** First time setting up DeSciX in a new workspace or Cursor project
+**Description:** One-command setup: auth → workspace → agent files → MCP config
+**Use when:** First time setting up DeSciX in a new workspace
 **What it does:**
-1. Prompts for API endpoint (production/local/custom)
-2. Runs device authentication (opens browser)
-3. Creates `.cursor/mcp.json` for MCP server
-4. Creates `.cursor/rules/descix_mcp.mdc` for AI agent instructions
-5. Creates `.descix/workspace.json` with initial configuration
+1. Authenticates via device login if no valid session exists
+2. Initializes `.descix/workspace.json` if missing
+3. Generates agent instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.clinerules`) from the workspace's registered app/community
+4. Generates `.vscode/mcp.json` for MCP server config (skipped if the DeSciX VS Code extension already handles MCP)
+5. Copies SDK assets into `.descix/sdk-assets/`
 
 **Example:**
 ```bash
 cd ~/Projects/MyApp
-descix setup
+descix quickstart
 # Follow the prompts
-# Restart Cursor after completion
 ```
 
 ---
@@ -54,8 +53,11 @@ descix setup
 **Description:** Authenticate with the DeSciX platform
 **Use when:** Session expired or first-time authentication
 **Options:**
-- `--device` (default): Opens browser for Powch authentication
-- `--wallet`: Direct wallet signature authentication
+- (default, no flag needed): Device login — opens a browser for Powch authentication
+- `--wallet`: Direct wallet signature authentication (advanced, not yet implemented)
+- `-u, --url <url>`: API URL override
+- `--no-oauth`: Skip the OAuth long-lived token leg (wallet-signature login only)
+- `--scope <scope>`: OAuth scope to request (default: `mcp:read mcp:tools mcp:write mcp:admin`)
 
 **Example:**
 ```bash
@@ -107,45 +109,71 @@ descix tell-me-how --scope discovery "What AI training tools exist?"
 
 ---
 
-### descix app create
+### descix app init
 
-**Description:** Create or hydrate an app using the interactive wizard
-**Use when:** Starting a new project or hydrating an existing app
+**Description:** Create (if needed) and initialize an app: platform record + default KB + local workspace registration and scaffold. Idempotent.
+**Use when:** Starting a new project or hydrating an existing app. This is the single canonical path — the old two-step `app create` then `app init` is deleted; `descix app create` now hard-fails naming this replacement.
 **Options:**
-- `-c, --community <id>`: Community ID
-- `-a, --app <name>`: App name
-- `--wizard`: Interactive wizard mode
-- `--quick`: Skip optional prompts
-
-**Note:** New apps should primarily be provisioned via the PWA. This command can hydrate a local workspace from an existing app or create a skeleton if permitted.
+- `-a, --app <app_id>` (required): App ID. With `-c` this is the app NAME to create.
+- `-c, --community <id>`: Community ID — required to create an app that does not exist yet
+- `-s, --short <short_name>`: Short id segment (no hyphens) used when creating; 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 or cwd)
 
 **Example:**
 ```bash
-# Interactive wizard
-descix app create --wizard
+descix app init -a myapp -c descix
 ```
 
 ---
 
 ### descix kb
 
-**Description:** Manage Knowledge Base content (Git Mode)
-**Use when:** Processing KB documents locally
+**Description:** Manage Knowledge Base registration, corpus sync and per-KB configuration
+**Use when:** Creating a KB, syncing its corpus to Pinecone, or managing per-KB settings
 
 **Subcommands:**
-- `pull`: Download source documents from Drive to `kb/src/`
-- `chunk`: Process source files into chunks in `kb/chunks/`
-- `sync`: Push chunks to the platform (Pinecone)
-- `build`: Run the full pipeline (Pull -> Chunk -> Sync)
+- `create` / `list` / `delete`: Register, list or remove a KB
+- `corpus sync`: The one KB sync surface — walks the corpus manifest, chunks in-memory, pushes to Pinecone
+- `set-override-model` / `clear-override-model`: Pin or clear a per-KB model override
+- `status`: Show corpus sync state (files, chunks, last sync, resolved ref)
+- `doctor`: Detect drift between local sync-state and live Pinecone vector count
+- `records put|query|get|delete`: Structured record CRUD on a KB
+
+**Drive content authoring is a separate command:** `descix drive pull` / `descix drive push` (not under `kb`) move source documents between Drive and the local working tree.
 
 **Example:**
 ```bash
-# Full build pipeline
-descix kb build -c descix -a myapp
+# Sync a KB's corpus manifest to Pinecone
+descix kb corpus sync -a myapp -k General
 ```
 
 ---
 
+### 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 init      -a <app> -c <community>
+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
@@ -176,14 +204,15 @@ descix purchases
 
 ---
 
-## MCP Tools (for Cursor AI)
+## MCP Tools
 
-After running `descix setup` and restarting Cursor, these MCP tools are available to the AI agent:
+After running `descix quickstart` and reloading your editor/session, these MCP tools are available to the AI agent. `descix quickstart` authenticates via device login as its first step (opens a browser device-code flow) before it writes workspace, agent-instruction and MCP config files; there is no unauthenticated form of any of this.
 
 ### tell_me_how
 
 **Description:** Primary discovery tool - finds relevant commands for any task
-**Use first:** Always use this before attempting platform operations
+**Prerequisite:** the caller is signed in — it returns caller-specific context and is refused loud (`Authentication required`, exit 1) for a credential-free caller, never a silent partial answer
+**Use first:** Once signed in, always use this before attempting platform operations
 
 ```javascript
 tell_me_how({ 
@@ -206,7 +235,7 @@ tell_me_how({
 
 ```javascript
 execute_remote_command({
-  command: "create_app",
+  command: "create_app_for_community",
   params: {
     community_id: "descix",
     app_name: "My New App"
@@ -216,90 +245,31 @@ execute_remote_command({
 
 ---
 
-### descix_init
-
-**Description:** Initialize a local project for DeSciX deployment
-**Use when:** Setting up a new project folder
-
-```javascript
-descix_init({
-  projectPath: "/Users/dev/Projects/MyApp",
-  appName: "my-app",
-  communityId: "descix"
-})
-```
-
-**Creates:**
-- `.descix/workspace.json` or `.descix/context.json`
-- `app_description.md` from README if missing
-- Folder structure for knowledge base
-
----
-
-### descix_wizard_step
-
-**Description:** Execute multi-step wizard workflows
-**Use when:** Creating apps, communities, or complex operations
-
-```javascript
-descix_wizard_step({
-  wizard_type: "create_app",
-  step: "init",
-  params: {
-    community_id: "descix",
-    app_name: "My App"
-  }
-})
-```
-
-**Wizard types:**
-- `create_app`: App creation with folder setup
-- `create_community`: Community creation with token
-- `publish_kb`: Knowledge base sync and publish
-
----
-
-### git_sync_ops
+### query_knowledge_base
 
-**Description:** Git operations with auto-generated commit messages
-**Use when:** Committing changes, checking status
+**Description:** Vector-similarity search over a knowledge base — returns raw source chunks with dereferenceable citations (retrieval, no synthesis, stateless)
+**Use when:** You want primary-source passages/citations, or to ground/check an `ask_question_to_app` answer
 
 ```javascript
-git_sync_ops({
-  operation: "status",  // or "commit", "diff", "sync_info"
-  projectPath: "/Users/dev/Projects/MyApp"
-})
-```
-
----
-
-### search_knowledge_base
-
-**Description:** Search a specific knowledge base via RAG
-**Use when:** You know the exact KB to search
-
-```javascript
-search_knowledge_base({
-  communityId: "descix",
-  appId: "docs",
-  kbId: "sdk",
+query_knowledge_base({
+  app_id: "docs",
+  kb_id: "sdk",
   query: "How do I authenticate?"
 })
 ```
 
 ---
 
-### chat_with_kb
+### ask_question_to_app
 
-**Description:** Conversational RAG with knowledge base context
-**Use when:** Complex questions requiring AI reasoning
+**Description:** Ask a natural-language question against an app's knowledge base and get a synthesized, cited answer (stateful — pass `previous_interaction_id` to continue a thread)
+**Use when:** Complex questions requiring AI reasoning over a community's own sources
 
 ```javascript
-chat_with_kb({
-  communityId: "descix",
-  appId: "docs",
-  kbId: "sdk",
-  message: "Explain the authentication flow step by step"
+ask_question_to_app({
+  app_id: "docs",
+  knowledgebase_name: "sdk",
+  user_input: "Explain the authentication flow step by step"
 })
 ```
 
@@ -307,65 +277,44 @@ chat_with_kb({
 
 ## Workspace Configuration
 
-### workspace.json (Monorepo)
+### workspace.json (v2.1 — canonical)
 
-For multi-app workspaces, create `.descix/workspace.json`:
+`.descix/workspace.json` is written and mutated by `descix init` / `descix app init` / `descix app set-*` — never hand-edited. The v2.1 format is `env.platform` (the shell/store app, served at root) plus `env.products[]` (apps hosted inside the shell); the older `communities`-based v1 format is not supported and hard-errors on load ("v1 workspace format is not supported. Migrate to v2.1."):
 
 ```json
 {
-  "version": "2.0",
-  "primaryCommunity": "descix",
-  "directoryMappings": {
-    "frontend": { "communityId": "descix", "appId": "pwa", "kbId": "General" },
-    "backend": { "communityId": "descix", "appId": "cloud", "kbId": "General" },
-    "docs": { "communityId": "descix", "appId": "docs", "kbId": "sdk" }
-  },
-  "defaultContext": {
-    "communityId": "descix",
-    "appId": "docs",
-    "kbId": "sdk"
+  "version": "2.1",
+  "env": {
+    "platform": { "appId": "daita", "communityId": "descix", "localPath": ".", "kbId": "General" },
+    "products": [
+      { "appId": "docs", "communityId": "descix", "kbId": "sdk", "localPath": "descix-docs" }
+    ]
   }
 }
 ```
 
-### context.json (Single App)
-
-For individual app folders, create `.descix/context.json`:
-
-```json
-{
-  "version": "2.0",
-  "type": "app",
-  "community_id": "descix",
-  "app_id": "myapp",
-  "app_name": "My Application",
-  "folders": {
-    "app": { "local_path": ".", "sync_type": "assets" },
-    "kb": { "local_path": "docs", "sync_type": "rag" }
-  }
-}
-```
+A single-app (non-monorepo) workspace uses the same v2.1 shape with only `env.platform` set and an empty (or omitted) `env.products[]` — there is no separate single-app file format.
 
 ---
 
 ## Common Workflows
 
-### New Developer Onboarding (Cursor IDE)
+### New Developer Onboarding
 
 1. Install CLI: `npm install -g @descix/cli`
-2. Run setup: `descix setup`
-3. Restart Cursor (Cmd+Shift+P → "Reload Window")
+2. Run quickstart: `descix quickstart` — authenticates, initializes `.descix/workspace.json`, generates agent instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.clinerules`) for Claude Code, Copilot, Cursor and Cline, and writes `.vscode/mcp.json` (skipped if the DeSciX VS Code extension is installed — it registers MCP natively)
+3. Reload the editor/session so it picks up the generated files
 4. AI agent can now use MCP tools
 5. Ask: "How do I create an app?"
 6. AI uses `tell_me_how` → `execute_remote_command`
 
 ### Entitlements-First App Creation
 
-1. AI calls `execute_remote_command({ command: "fetch_my_purchases" })`
+1. AI calls `fetch_my_purchases()` directly (it is its own MCP tool, not an `execute_remote_command` target)
 2. AI presents user's communities and apps
 3. User selects community (or creates new)
-4. AI calls `descix_wizard_step` for app creation
-5. AI creates local `.descix/context.json`
+4. AI calls `execute_remote_command({ command: "create_app_for_community", params: {...} })` for app creation
+5. AI runs `descix app init` to register the local workspace mapping in `.descix/workspace.json`
 
 ### Monorepo Setup
 
@@ -380,9 +329,15 @@ For individual app folders, create `.descix/context.json`:
 ## Troubleshooting
 
 ### "MCP tools not available"
-1. Run `descix setup` in workspace root
-2. Restart Cursor completely
-3. Check `.cursor/mcp.json` exists with `descix` server
+1. Run `descix quickstart` in workspace root
+2. Reload your editor/session completely
+3. Check `.vscode/mcp.json` exists with a `descix` server (this file is skipped, by design, if the DeSciX VS Code extension is installed — it registers MCP natively)
+
+### "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`
@@ -391,7 +346,7 @@ Run `descix reconnect` or `descix login`
 Service READMEs may not be vectorized. Ask admin to run `descix microservice vectorize` for relevant services.
 
 ### "workspace.json not found" for project scope
-Run `descix init` or let AI create workspace.json via `descix_init` MCP tool.
+Run `descix init` (or `descix quickstart`, which runs it for you if missing).
 
 ---
 

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);
+});