@descix/cli 1.0.17 → 1.0.18

package/agent-assets/reference/mcp-integration.md

@@ -10,7 +10,7 @@ This document covers how AI agents interact with the DeSciX platform via MCP (Mo
 
 ## 1. Architecture Overview
 
-DeSciX operates as a **Federated MCP Service Mesh**. The `DeSciX_Cloud` backend acts as a broker that aggregates tools from all registered microservices into a unified catalog.
+DeSciX operates as a **Federated MCP Service Mesh**. The DeSciX backend acts as a broker that aggregates tools from all registered microservices into a unified catalog.
 
 **Key Innovation:** AI agents discover and invoke capabilities across the entire mesh without knowing where individual services are hosted.
 
@@ -24,7 +24,7 @@ AI Agent (Cursor/MCP Client)
    execute_remote_command
        │
        ▼
-   DeSciX_Cloud (Federated Broker)
+   DeSciX Backend (Federated Broker)
        │
        ├──► Service 1 (Powch)
        ├──► Service 2 (SmartModel)
@@ -42,9 +42,9 @@ MCP provides the communication protocol between AI agents and the DeSciX platfor
 **Key Tools:**
 - `tell_me_how` - Semantic tool discovery
 - `execute_remote_command` - Execute any backend command
-- `descix_init` - Initialize local workspace
-- `chat_with_kb` - Query knowledge bases
-- `search_knowledge_base` - Search specific KBs
+- `descix_doctor` - CLI-local startup diagnostic (auth, workspace, tools, warnings)
+- `ask_question_to_app` - RAG chat with an app's knowledge base (synthesized answer, cited)
+- `query_knowledge_base` - Raw vector search, returns chunks
 
 ### 2.2 Cursor/AI Agent Integration
 
@@ -91,13 +91,17 @@ Once signed in, `tell_me_how` is the **primary entry point** for discovering pla
 
 **Rule:** Sign in, then ask `tell_me_how` first, then execute the recommended command.
 
-### 3.2 Three Scopes
+### 3.2 Scopes
+
+The validated `tell_me_how` scope enum has five values:
 
 | Scope | Description | Use Case |
 |-------|-------------|----------|
-| `entitlements` (default) | Only tools user has access to | Production usage |
+| `entitlements` (default) | Only tools the user has access to | Production usage |
 | `project` | Tools filtered by workspace.json | Working within a project |
 | `discovery` | All available tools | Exploring capabilities |
+| `bootstrap` | Deterministic first-call on-ramp: platform summary, caller context, credit balance, essential tool schemas (no vector search; `question` is optional for this scope only) | First contact / first call in a session |
+| `artifact` | Deterministic build/reproduce provenance for a published app (npm package + spec, artifact/notebook URLs, runnable `npx` commands), no vector search | "How do I build on / reproduce this app?" |
 
 ### 3.3 CLI Usage
 
@@ -151,7 +155,7 @@ After `descix quickstart` completes:
 
 ### 4.1 Federated MCP Broker
 
-`DeSciX_Cloud` aggregates tools from all registered microservices:
+The DeSciX backend aggregates tools from all registered microservices:
 
 ```
 Microservice A
@@ -161,7 +165,7 @@ Microservice A
     Registers with Core
         │
         ▼
-DeSciX_Cloud (Broker)
+DeSciX Backend (Broker)
   └── Aggregated tools/list
         │
         ▼
@@ -199,14 +203,11 @@ execute_remote_command({
 
 ### 4.3 Service Registration
 
-Services self-register with the broker:
+Services self-register with the broker in one step — registration also vectorizes the README you
+pass, so there is no separate developer-facing vectorize step:
 
 ```bash
-# Register service manifest
-descix microservice register -m ./manifest.json
-
-# Vectorize SERVICE_README for discovery
-descix microservice vectorize -r SERVICE_README.md
+descix microservice register -r SERVICE_README.md
 ```
 
 ### 4.4 The execute_remote_command Pattern
@@ -309,11 +310,13 @@ When `--scope project` is used:
 
 ### 6.1 KB Operations via tell_me_how
 
-The new SDK V2 KB commands are discoverable:
+`tell_me_how` can be asked about KB sync in plain language, but the actionable answer for a
+developer is always the CLI verb, not the raw backend command names (`kb_sync_chunks` etc. are
+internal to the backend, not something the CLI calls directly by name):
 
 ```bash
 descix tell-me-how "How do I sync my knowledge base?"
-# Returns: kb_sync_chunks, kb_get_chunk_ids, kb_delete_chunks
+# The developer-facing command either way: descix kb corpus sync
 ```
 
 ### 6.2 workspace.json from Hydration
@@ -324,7 +327,7 @@ descix tell-me-how "How do I sync my knowledge base?"
 {
   "env": { "apiUrl": "https://dev.descix.net", "products": [ /* one entry per app */ ] },
   "driveConfig": {
-    "base_folder_id": "..."  // For tell_me_how project scope
+    "base_folder_id": "..."  // Only used by `descix drive pull/push` — unrelated to tell_me_how scope
   }
 }
 ```
@@ -334,9 +337,9 @@ descix tell-me-how "How do I sync my knowledge base?"
 Custom services integrate with the same pattern:
 
 1. Create `SERVICE_README_{name}.md`
-2. Register with `descix microservice register`
-3. Vectorize with `descix microservice vectorize`
-4. Tools become discoverable via `tell_me_how`
+2. Register with `descix microservice register -r SERVICE_README_{name}.md` — this both publishes
+   the manifest AND vectorizes the README in one step
+3. Tools become discoverable via `tell_me_how`
 
 ---
 
@@ -355,7 +358,8 @@ Custom services integrate with the same pattern:
 1. **Document all commands in SERVICE_README** - Required for discovery
 2. **Use clear descriptions** - "Use when:" is crucial for semantic matching
 3. **Include examples** - Helps AI agents understand usage
-4. **Register after changes** - Re-vectorize when README updates
+4. **Re-register after README changes** - `descix microservice register -r <file>` re-vectorizes
+   automatically; there is no separate vectorize step
 
 ### 7.3 Common Patterns
 
@@ -407,22 +411,11 @@ cd /path/to/workspace
 
 ### 8.3 "Command not found"
 
-**Cause:** Service not registered or command deprecated.
+**Cause:** Service not registered, or the README wasn't vectorized.
 
 **Solution:**
-1. Verify service is registered: `descix microservice list`
-2. Check if command was deprecated in V2
-3. Use `tell_me_how --scope discovery` to find alternatives
-
----
-
-## 9. File References
-
-| Component | Path |
-|-----------|------|
-| MCP Tools | `DeSciX_Core/descix-cli/bin/mcp-server.js` |
-| tell_me_how Implementation | `DeSciX_Cloud/microservice/services/commandHandlers/ragCommands.js` |
-| execute_remote_command | `DeSciX_Cloud/microservice/services/apiFront.js` |
-| SERVICE_README Template | `DeSciX_Core/descix-cli/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md` |
-| Workspace Config | `DeSciX_Core/descix-cli/lib/workspace-config.js` |
-| Service Registration | `DeSciX_Core/descix-cli/bin/descix.js` |
+1. Re-run `descix microservice register -r SERVICE_README_<name>.md` — it re-publishes the
+   manifest and re-vectorizes the README (`descix microservice list` exists to enumerate
+   registered services, but it is an admin-only command, not something a developer runs)
+2. Check `descix microservice health <name>` to confirm the service itself is reachable
+3. Use `descix tell-me-how --scope discovery "..."` to find alternatives

package/agent-assets/reference/workspace-config.md

@@ -160,13 +160,12 @@ descix site status -c egpt -a egpt-mydocs      # site status/list need both when
 
 ---
 
-## 7. File References
-
-| Component | Path | Description |
-|-----------|------|-------------|
-| WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | the loader, the v2.1 writer, `registerApp`, `detectContext` |
-| Origin resolution | `DeSciX_Core/descix-cli/lib/origin.js` | flag → `DESCIX_API_URL` → `env.apiUrl` → default |
-| GlobalConfig | `DeSciX_Core/descix-cli/lib/global-config.js` | user-level settings (`~/.descixrc`) |
-| Config commands | `DeSciX_Core/descix-cli/lib/commands/config.js` | `config init/set-env/set-*` |
-| Wallet file | `DeSciX_Core/descix-cli/lib/wallet-file.js` | `.descix/wallet.json` location |
-| Corpus sync | `DeSciX_Core/descix-cli/lib/commands/corpus.js` | manifests, sync-state |
+## 7. Where each concept lives (conceptual, not a file map)
+
+| Concept | Owner |
+|---|---|
+| Workspace loading, the v2.1 writer, app registration, context detection | `WorkspaceConfig`, internal to `@descix/cli` |
+| Origin resolution precedence | flag → `DESCIX_API_URL` → `env.apiUrl` → default (`descix config` commands) |
+| User-level settings (`~/.descixrc`) | `GlobalConfig`, internal to `@descix/cli` |
+| `.descix/wallet.json` | written by `descix login` |
+| Corpus manifests, sync-state | `descix kb corpus` commands, internal to `@descix/cli` |

package/bin/descix.js

@@ -35,6 +35,7 @@ import { registerAllRetiredKbSync, CANONICAL_KB_SYNC } from '../lib/commands/ret
 import { runStatus } from '../lib/commands/status.js';
 import { refreshCommunityIdentity, printIdentityReceipt } from '../lib/commands/communityIdentity.js';
 import { runAppInit } from '../lib/commands/appInit.js';
+import { assertKnownCommandForHelp } from '../lib/help-guard.js';
 import { runDoctor } from '../lib/commands/doctor.js';
 import { runHealth } from '../lib/commands/health.js';
 import * as kbCommands from '../lib/commands/kb.js';
@@ -4650,6 +4651,10 @@ if (!adminMode && isHelpInvocation(program, rawArgv, { valueFlags: ['--env', '--
   }
 }
 
+// A command that does not exist must not appear to have help (see lib/help-guard.js). This runs
+// before the parse, because Commander resolves --help before it resolves the command.
+assertKnownCommandForHelp(program, process.argv.slice(2));
+
 // Parse arguments
 await program.parseAsync(process.argv);
 

package/lib/help-guard.js

@@ -0,0 +1,85 @@
+/**
+ * A COMMAND THAT DOES NOT EXIST MUST NOT APPEAR TO HAVE HELP.
+ *
+ * Commander resolves `--help` before it resolves the command, so `descix update --help` printed the
+ * TOP-LEVEL help and exited 0 — indistinguishable, to a reader or a script, from a real verb with
+ * help. `descix update` alone correctly says `error: unknown command 'update'`.
+ *
+ * That exit 0 is not only wrong, it TAUGHT something wrong: the daita-sdk docs tell readers that
+ * `site upload --help` "silently prints top-level help" and to use `help <sub>` instead. It does no
+ * such thing for a real command; the author had been probing a command that did not exist (devx
+ * review 2026-09-19, I2 → S5).
+ *
+ * This guard runs ONLY when a help flag is present, so every other path keeps Commander's own
+ * behaviour (it already exits non-zero for an unknown command without `--help`).
+ */
+
+const HELP_FLAGS = new Set(['-h', '--help']);
+
+/** Does this option consume the next argv token as its value? */
+function takesValue(option) {
+    return Boolean(option && option.required);
+}
+
+function findOption(command, token) {
+    const name = token.split('=')[0];
+    return command.options.find((o) => o.short === name || o.long === name);
+}
+
+function findSubcommand(command, token) {
+    return command.commands.find(
+        (c) => c.name() === token || (typeof c.aliases === 'function' && c.aliases().includes(token)),
+    );
+}
+
+/**
+ * Walk argv down the command tree and return the first token that should name a subcommand but does
+ * not. Returns null when every command token resolves — including when a command takes positional
+ * arguments (a command with no subcommands ends the walk, so `descix chat hello` is not "unknown").
+ *
+ * @param {import('commander').Command} program
+ * @param {string[]} argv arguments after the node binary and script (process.argv.slice(2))
+ * @returns {{token: string, parent: import('commander').Command}|null}
+ */
+export function findUnknownCommand(program, argv) {
+    let command = program;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--') break;
+        if (token.startsWith('-')) {
+            if (takesValue(findOption(command, token)) && !token.includes('=')) i++;
+            continue;
+        }
+        // A command with no subcommands takes positional arguments from here on.
+        if (command.commands.length === 0) break;
+        const sub = findSubcommand(command, token);
+        if (!sub) return { token, parent: command };
+        command = sub;
+    }
+    return null;
+}
+
+/** The command names `parent` actually has, for the "did you mean" line. */
+function nameList(parent) {
+    return parent.commands.map((c) => c.name()).sort();
+}
+
+/**
+ * When argv asks for help on a command that does not exist, refuse by name and exit 1.
+ *
+ * @param {import('commander').Command} program
+ * @param {string[]} argv
+ * @param {{ error: (msg: string) => void, exit: (code: number) => void }} io
+ */
+export function assertKnownCommandForHelp(program, argv, io = { error: console.error, exit: process.exit }) {
+    if (!argv.some((a) => HELP_FLAGS.has(a))) return;
+    const unknown = findUnknownCommand(program, argv);
+    if (!unknown) return;
+
+    const path = [];
+    for (let c = unknown.parent; c && c.parent; c = c.parent) path.unshift(c.name());
+    const where = path.length ? `'descix ${path.join(' ')}'` : 'descix';
+    io.error(`error: unknown command '${unknown.token}'`);
+    io.error(`${where} has: ${nameList(unknown.parent).join(', ')}`);
+    io.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",

package/templates/agent-claude.md

@@ -226,8 +226,9 @@ const user = await powch.auth();
 ### KB Integration
 
 If docs already exist (`docs/`, `README.md`, SDK reference files):
-- Copy markdown files to `kb/General/` for the sync pipeline
-- Keep originals as the source of truth — sync from there
+- Name the docs' folder as a source in a corpus manifest (`.descix/manifests/<KB>.json`), then run
+  `descix kb corpus sync`. The docs stay exactly where they are — there is no copy step and no
+  required KB folder.
 - Ask: "I see docs in `docs/`. Want me to use those as your knowledge base?"
 
 ### Decision Guide
@@ -236,7 +237,7 @@ If docs already exist (`docs/`, `README.md`, SDK reference files):
 |-----------------|---------------|-------------|
 | HTML/JS app with `index.html` | Serve as-is, add DeSciXAppSDK.js | Use any `docs/` or `*.md` files |
 | React/Vite app | Wrap root in `<AppShell>` | Use `docs/` or README |
-| SDK package with docs + demo | Serve the SDK's demo page | Copy docs to `kb/General/` |
+| SDK package with docs + demo | Serve the SDK's demo page | Name docs folder in a corpus manifest |
 | Docs only (no frontend) | Skip or create minimal site | Docs ARE the KB |
 | Empty repo | Scaffold from scratch | Create starter KB doc |
 
@@ -244,7 +245,8 @@ If docs already exist (`docs/`, `README.md`, SDK reference files):
 
 Every app has three parts:
 - `site/` — Frontend (any framework: React, VitePress, vanilla HTML)
-- `kb/General/` — Knowledge base source docs (markdown files)
+- A corpus manifest (`.descix/manifests/<KB>.json`) — names the git-tracked docs `descix kb corpus
+  sync` publishes; there is no required KB folder
 - `microservice/` — Backend service (optional)
 
 ## App Context

package/templates/agent-cline.md

@@ -165,13 +165,13 @@ unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
   `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.
+- **Existing docs:** Name the docs' folder as a source in a corpus manifest (`.descix/manifests/<KB>.json`), then `descix kb corpus sync`. Docs stay where they are — no copy step.
 - **Empty repo:** Scaffold from scratch.
 
 ## App Structure
 
 - `site/` — Frontend (any framework)
-- `kb/General/` — Knowledge base source docs (markdown)
+- A corpus manifest (`.descix/manifests/<KB>.json`) — names the git-tracked docs `descix kb corpus sync` publishes (no required folder)
 - `microservice/` — Backend service (optional)
 
 ## Context

package/templates/agent-copilot.md

@@ -165,13 +165,13 @@ unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
   `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.
+- **Existing docs:** Name the docs' folder as a source in a corpus manifest (`.descix/manifests/<KB>.json`), then `descix kb corpus sync`. Docs stay where they are — no copy step.
 - **Empty repo:** Scaffold from scratch.
 
 ## App Structure
 
 - `site/` — Frontend (any framework)
-- `kb/General/` — Knowledge base source docs (markdown)
+- A corpus manifest (`.descix/manifests/<KB>.json`) — names the git-tracked docs `descix kb corpus sync` publishes (no required folder)
 - `microservice/` — Backend service (optional)
 
 ## Context

package/templates/agent-cursor.md

@@ -165,13 +165,13 @@ unverified step — see `.descix/sdk-assets/reference/local-dev.md` §3.3.
   `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.
+- **Existing docs:** Name the docs' folder as a source in a corpus manifest (`.descix/manifests/<KB>.json`), then `descix kb corpus sync`. Docs stay where they are — no copy step.
 - **Empty repo:** Scaffold from scratch.
 
 ## App Structure
 
 - `site/` — Frontend (any framework)
-- `kb/General/` — Knowledge base source docs (markdown)
+- A corpus manifest (`.descix/manifests/<KB>.json`) — names the git-tracked docs `descix kb corpus sync` publishes (no required folder)
 - `microservice/` — Backend service (optional)
 
 ## Context