@descix/cli 1.0.16 → 1.0.18

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/lib/verb-invokes.generated.json

@@ -190,11 +190,15 @@
     "fetch_my_purchases"
   ],
   "quickstart": [
+    "create_app_for_community",
     "device_check_status",
     "device_request_login",
     "find_communities",
+    "get_product_context",
+    "init_git_mode_kb",
     "resolve_invite",
-    "sync_auto_purchases"
+    "sync_auto_purchases",
+    "update_community_metadata"
   ],
   "reconnect": [
     "reconnect_by_wallet"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "1.0.16",
+  "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

@@ -84,15 +84,18 @@ Use `find_communities` and `list_apps_for_community` to show options, then ask:
 > "Which community and app should this project target?"
 
 ### Checkpoint 3: Environment
-> "Should this run against local dev backend (localhost:4000) or hosted API?"
+> "Should this app be built against DEV (https://dev.descix.net) or production?"
+
+Pin the choice before anything else; every later command reads it from the workspace.
 
 ### Canonical Setup Commands (run in terminal after checkpoints)
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the app id the platform issued (with `-c` it is `<community>-<name>`). Use that
+id, not the name, as `-a` in every later command.
 
 ### Checkpoint 4: Content Strategy
 > "Should I create a starter KB doc now, or wait for your domain docs?"
@@ -223,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
@@ -233,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 |
 
@@ -241,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

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"
@@ -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

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"
@@ -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

@@ -56,15 +56,15 @@ Ask the user at each checkpoint — don't assume:
 
 1. **Objective:** "Explore existing apps or build something new?"
 2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
-3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+3. **Environment:** "Build against DEV (https://dev.descix.net) or production?" Pin it first.
 
 Canonical setup commands:
 ```bash
-descix whoami                              # confirm identity
-descix app list                            # see available apps
-descix init -c <community> -a <app> -p .   # create workspace.json
-descix app init -a <app> -c <community>    # register app on platform
+descix --env dev config init               # pin the environment (omit --env dev for production)
+descix login                               # sign in
+descix app init -a <name> -c <community>   # create the app; the platform issues its id
 ```
+`app init` prints the issued id (`<community>-<name>` with `-c`); use it as `-a` from then on.
 
 4. **Content strategy:** "Create starter KB now or wait for your docs?"
 5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"
@@ -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