@descix/cli 1.0.1 → 1.0.3

package/agent-assets/reference/local-dev.md

@@ -16,9 +16,9 @@ This approach unifies three distinct scenarios:
 | Aspect | Git Mode (CLI) | Drive Mode (PWA) |
 |--------|---------------|-----------------|
 | **User Type** | Developers | Non-technical users |
-| **Content Source** | Local git repo (MD exports pulled from Drive via `kb pull`) | Google Drive |
+| **Content Source** | Local git repo (MD exports pulled from Drive via `descix drive pull`) | Google Drive |
 | **Version Control** | Git | Drive/GCS/Firestore |
-| **KB Processing** | `descix update kb` or `descix kb build` — local chunking → Pinecone directly | Server-side pipeline (Drive → GCS → Pinecone) — PWA users only |
+| **KB Processing** | `descix kb corpus sync` — manifest-driven git-aware sync → Pinecone | Server-side pipeline (Drive → GCS → Pinecone) — PWA users only |
 | **Configuration** | `workspace.json` | N/A (PWA handles) |
 | **Tools** | CLI, VSCode, Git | PWA only |
 
@@ -28,104 +28,185 @@ Instead of exposing implementation details (like GCS bucket URLs or specific por
 
 ### 2.1. Route Patterns
 
-| Resource Type | Canonical Path | Production Target (LB) | Local Target (Gateway Proxy) |
-| :--- | :--- | :--- | :--- |
-| **Core API** | `/apifront`, `/api`, `/mcp` | Core API | `https://localhost:4000` |
-| **Powch PWA** | `/powch` | Powch PWA | `https://localhost:5174` |
-| **Microservice** | `/s/{community}/{appId}` | k8s-service | `http://localhost:{service.port}` |
-| **CodeSite / App Site** | `/Community/{c}/Apps/{a}/site`, `/s/{appId}` | GCS / service | `http://localhost:{site.port}` |
-| **PWA** | `/*` | PWA bucket | Served from gateway root (when run from DeSciX_PWA) |
+| Canonical Path | Production Target (LB) | Local Target (Gateway) |
+| :--- | :--- | :--- |
+| `/apifront`, `/api`, `/mcp`, `/oauth`, `/.well-known/oauth-*` | Core API | the resolved **API origin** (see §3.2) |
+| `/powch` | Powch PWA | the origin the workspace names. **No route at all when unset** — there is no default wallet origin |
+| `/s/{appId}` | service | `http://localhost:{microservice.port}` — prefix **stripped** |
+| `/p/{appId}` | app site | `{proto}://localhost:{site.port}` (**no** path rewrite), or served from disk when the product has `site.static` |
+| `/Community`, `/.proxy/gcs_media` | GCS public bucket | proxied to `storage.googleapis.com` |
+| `/__descix/app-binding.json` | (not served in production) | answered by the gateway itself |
+| `/` | PWA bucket | the resolved **Shell origin** (see §3.2) — always matched **last** |
 
 ## 3. The "Local Mesh" Proxy
 
-The `descix serve` command spins up a **Local Gateway** on port `5173`. This gateway acts as the router, serving the PWA (when run from `DeSciX_PWA`) and proxying traffic based on the **Workspace Configuration**. Run `npm run dev:serve` from `DeSciX_PWA` or `npx descix serve` with PWA as cwd for Platform Dev.
+`descix serve` spins up a **Local Gateway**: one HTTPS origin that proxies the whole mesh. It is a Vite server used only as proxy + static + TLS, and it **starts nothing else** — no backend, no app dev server. An unreachable target surfaces as a 502/`ECONNREFUSED`; nothing is masked or retried against a fallback.
+
+**Port:** `--port` → `env.gateway.port` → built-in `5173`, with `strictPort` on. The resolved port and **its source** are printed at startup. Do not assume `:5173`; give a checkout its own with `descix config set-gateway-port <n>`.
+
+**It serves ONE app, standalone — the shell opens ON your app instead of the store.** (Standalone is the INITIAL VIEW, not a reduced mode: the platform views stay reachable by navigation.) The app is detected from the directory you are standing in (the product whose `localPath` contains your cwd; longest match wins), or named with `--app <id>`. Nothing is persisted to `workspace.json`. When it cannot name an app it fails loud and lists the workspace's apps rather than falling back to the store.
+
+The binding is **served, not compiled**: the gateway answers `GET /__descix/app-binding.json` on the shell's own origin with `{mode:'standalone', appId, appUrl, source}`, and the shell reads it before it mounts. One pre-built cloud shell bundle therefore boots as the store on `descix.net` and as your app locally, with no rebuild. No binding (or a timeout, or a malformed body) means the store — the safe degradation. There is no `__STANDALONE_APP_ID__` build define; an app that builds itself standalone declares it at its own mount, `<AppShell appId="..." standalone>`.
+
+### `/p/<appId>` is a LOCAL route only
+
+The gateway serves your app at `/p/<appId>`. **That path does not exist in the cloud.** Deployed
+apps are served on their own host, `{appId}.{env}.descix.net`. Measured against dev:
+
+```
+# LOCAL — the /p/ form, served by your own gateway
+https://localhost:5173/p/egpt-godsworld/       works   (gateway port varies)
+
+# CLOUD — measured against dev
+https://egpt-godsworld.dev.descix.net/         -> 200  (the deployed app, per-app host)
+https://dev.descix.net/p/egpt-godsworld/       -> 404  (the /p/ form does not exist here)
+```
+
+So a URL that works all through local development 404s the moment you point it at a deployed
+environment. If you are writing a link, a redirect, or a test that must survive deployment, use
+the per-app host; keep `/p/` for the local gateway, where it is the correct and necessary form.
+
+**Every app the shell iframes is on the GATEWAY origin** — `/p/{appId}`, never the app's own dev-server port. The shell dispatches chat action blocks by reaching straight into `iframe.contentWindow.DeSciX_Actions` (direct interframe scripting, no postMessage bridge), so a cross-origin iframe kills SplitView with a `SecurityError`. **Powch is the deliberate exception** and stays cross-origin: it holds passkeys and the HD wallet, and same-origin would expose it to that same reach.
+
+Typical app-dev session, in full:
+
+```bash
+descix config set-env dev
+descix app init -a <app-id> -p ./my-app
+descix app set-site -a <app-id> --static .
+cd my-app && descix serve
+```
 
 ### 3.1. Configuration: `.descix/workspace.json`
 The `workspace.json` file is the **single source of truth** for local routing and app configuration. This is the only configuration methodology - `.descix.app/context.json` files are no longer used.
 
 **Key Features:**
-- Workspace root detection (searches upward for `.descix/`, `.cursor/`, or `.vscode/`)
+- Workspace root detection (walks upward looking for `.descix/workspace.json`)
 - App context autodiscovery (CLI commands auto-detect community/app from cwd)
-- Port registration for local dev servers
-- Drive folder configuration for `kb pull/push`
-- `apiUrl` derived automatically from `env.platform.microservice.port` in DEV mode
+- Explicit port registration for local dev servers — there is **no auto-allocation**
+- Drive folder configuration for `descix drive pull` / `descix drive push`
+
+**Author it with CLI verbs, never by hand:**
+
+| Key | Verb |
+|---|---|
+| `env.apiUrl` | `descix config set-env <dev\|demo\|prod> [--url <url>]` (env is positional) |
+| `env.gateway.port` | `descix config set-gateway-port <n\|none>` |
+| `env.devCerts` | `descix config set-dev-certs --dir\|--cert\|--key\|--clear` |
+| `env.powchUrl` | `descix config set-powch-url <url\|none>` |
+| `env.siteUrl` | `descix config set-site-url <url\|none>` |
+| `env.products[]` | `descix app init` / `app set-site` / `app set-port` / `app set-localpath` / `app unmap` |
 
-#### Platform Dev format (V2.1)
+#### Format (v2.1 — the only format)
 
 ```json
 {
   "version": "2.1",
-  "workspaceRoot": "/path/to/workspace",
-  "serve-port": 5173,
-  "driveConfig": { "base_folder_id": "..." },
   "env": {
     "environment": "DEV",
+    "apiUrl": "https://dev.descix.net",
+    "gateway": { "port": 5599 },
+    "devCerts": { "dir": "/Users/you/.descix/dev-certs-san" },
+    "powchUrl": "https://powch.dev.descix.net/",
     "platform": {
       "appId": "daita",
       "localPath": "DeSciX_Cloud",
-      "site": { "port": 5174, "devCommand": "npm run dev:site" },
-      "microservice": { "port": 4000, "devCommand": "npm run dev:service" }
+      "site": { "port": 5174 },
+      "microservice": { "port": 4000 }
     },
     "products": [
-      {
-        "appId": "powch",
-        "localPath": "DeSciX_Powch",
-        "site": { "port": 5175, "devCommand": "npm run dev:site" },
-        "microservice": { "port": 3003, "devCommand": "npm run dev:service" }
-      }
+      { "appId": "my-app", "localPath": "my-app", "site": { "static": "." } },
+      { "appId": "other-app", "localPath": "other", "site": { "port": 5599 }, "microservice": { "port": 4001 } }
     ]
   }
 }
 ```
 
-`env.platform.microservice.port` is the Core API port. CLI derives `apiUrl = https://localhost:{port}` automatically.
+`env.platform` is optional — an app developer has no platform checkout and needs none. A top-level `apiUrl` key (the v1 shape) fails loud naming its replacement.
 
-#### App Dev format (V2.0 — generated by `descix init`)
+#### KB sync is manifest-driven
+
+`descix kb corpus sync -a <app-id> [-k <KB>]` is the KB sync. It is **git-aware**: it walks the
+sources named in a manifest at `<checkout>/.descix/manifests/<KB>.json`, resolves them at a git
+ref (`main` unless `--ref` overrides), and upserts only what changed — stale blob SHAs are purged
+in the same pass. **No manifest means nothing to sync**, so the manifest is the first thing a new
+KB needs, not an optimisation.
+
+Check before you write: `--dry-run` enumerates would-be upserts and purges with **no** Pinecone
+writes (exit 0 = no drift, 1 = drift), and `--show-walk` prints the resolved ref and the walked
+files. `descix kb corpus status` shows files, chunks, last sync and resolved ref.
+
+**Only `.md` is ingested.** The corpus walk takes Markdown; a `.mdc` file is shipped and read
+from disk but never enters a knowledge base. That matters for
+`agent-assets/rules/descix_mcp.template.mdc`, which agents read as a file and which no amount of
+KB querying will surface. If you fix something there, the fix reaches readers of the file and
+nobody asking the KB — so do not assume KB coverage for a surface that has none. This is a known
+boundary, not a defect.
+
+`descix kb chunk`, `descix kb sync` and `descix update kb` still run but are **superseded
+duplicates** — each names `kb corpus sync` as its replacement in its own `--help` and is slated
+for removal. Do not put them in new instructions.
+
+#### What you put in a KB changes what comes out of it
+
+Retrieval is **vocabulary-dominated**, and when it goes wrong it does so silently. Measured against
+a live KB of primary papers: a domain-plausible paraphrase of a paper's thesis returned a *sibling*
+paper at 0.469 and never surfaced the correct one at all; rephrasing the same question in the
+paper's own wording returned it at 0.575. Same KB, same document, correctly indexed the whole time.
+
+Neither failure looked like a failure. Both returned confident, on-topic prose scoring in the same
+0.45–0.58 band as the right answer, so nothing in the response told the caller they had the wrong
+document.
+
+For callers:
+- Phrase queries in the **source's own vocabulary**; quote a distinctive phrase where you can.
+- Never treat rank-1 as authoritative alone. Pull `limit >= 3` and **check `fileName`**.
+- A confident, well-scored answer is not evidence the right document was retrieved. Verify by
+  **document identity**, not by score.
+
+For curators, which is the part that bites: **mixing overview or summary documents into a KB with
+the primary sources they describe systematically shadows those primaries.** Overviews are written in
+general vocabulary, so they match paraphrases *better* than the specific documents they summarise —
+the survey outranks the paper for exactly the reader who does not yet know the paper's terms.
+
+### 3.2. Target resolution (one owner, explicit-first)
+
+| Target | 1. flag / env | 2. workspace | 3. global | 4. default |
+|---|---|---|---|---|
+| **API** | `--api-url` / `--env` / `DESCIX_API_URL` | `env.apiUrl`, then the legacy top-level `apiUrl` | `~/.descix/config.json` `api_url` | **the declared default: PROD** |
+| **Shell** (`/`) | `--site-url` | `env.siteUrl` | **the API origin, when the API is remote** | `env.platform.site.port`, else fail loud |
+
+**There is no port-derived step for the API.** An environment NAME never becomes an origin, and
+`env.platform.microservice.port` is not consulted: a local backend is a URL you name
+(`descix config set-env dev --url https://localhost:4000`, or `env.apiUrl` direct). The single
+owner of this order is `lib/origin.js::PRECEDENCE`; this table is a description of it, not a
+second copy of the rule.
+
+**Every resolution carries its SOURCE, and every network-bound command prints it on stderr** —
+always, not only when it lands on the default:
 
-```json
-{
-  "version": "2.0",
-  "communities": {
-    "descix": {
-      "apps": {
-        "myapp": {
-          "localPath": "myapp",
-          "kbId": "General",
-          "site": { "port": 3000, "devCommand": "npm run dev" },
-          "service": { "port": 4001, "devCommand": "npm run start" }
-        }
-      }
-    }
-  },
-  "driveConfig": { "base_folder_id": "..." }
-}
+```
+env: prod (default — no workspace config; `descix config init --env dev` targets DEV) <prod origin>
+env: dev (.descix/workspace.json env.apiUrl) https://dev.descix.net
 ```
 
-### 3.2. Proxy Logic (createViteProxyConfig)
-The gateway uses `createViteProxyConfig` from `@descix/app-sdk/dev` to generate Vite proxy rules from `workspace.json`:
+An unconfigured workspace resolving to PROD is the shipped product's declared target, not a
+fallback; what makes it legitimate is that it is announced. A configured-but-unusable origin is
+a different case and FAILS LOUD naming the remedy, rather than quietly becoming the default.
 
-- **`/apifront`, `/api`, `/mcp`** → `env.platform.microservice.port` (DEV) or `https://descix.net`
-- **`/powch`** → `env.products.find(p => p.appId === 'powch').site.port`
-- **`/s/{community}/{appId}`** → `localhost:{microservice.port}` for each product in `workspace.json`
-- **`/Community/{c}/Apps/{a}/site`** → `localhost:{site.port}` for local app dev
-- **`/Community`** → GCS fallback
-- **`/.proxy/gcs_media`** → GCS media proxy
+The derived Shell rule is the important one: point the API at a cloud environment and the shell comes from that same origin, so one origin carries shell + app + `/apifront` with nothing else configured. A stale `env.platform.site` block does not hijack the root once the API is remote. Platform developers opt IN to a local shell by naming it (`--site-url https://localhost:5174` or `env.siteUrl`).
 
 ## 4. Scenarios
 
-### Scenario 1: Platform Dev ("Dogfooding")
-*   **User**: Core Team.
-*   **Setup**: Full repo checkout. Run `npm run dev:serve` from `DeSciX_PWA` plus Core, Powch PWA, Powch service. `workspace.json` maps Powch and apps to local ports.
-*   **Result**: The gateway serves the PWA at `/` and routes `/apifront` to Core, `/powch` to Powch PWA, `/s/*` to microservices. Local app sites are proxied via `/Community/{c}/Apps/{a}/site`.
+### Scenario 1: App Dev (the common case)
+*   **User**: App developer. No platform checkout.
+*   **Setup**: `descix config set-env dev`, `descix app init`, `descix app set-site`, then `cd my-app && descix serve`.
+*   **Result**: one HTTPS origin. `/` → the cloud App Shell, `/apifront` → the cloud API, `/p/my-app` → your app, and the shell boots **standalone into your app** — its INITIAL VIEW is your app rather than the store, with the platform views still reachable from there.
 
-### Scenario 2: End-User Dev (Hybrid)
-*   **User**: App Developer.
-*   **Setup**: `descix init` creates a `workspace.json` mapping *only* their specific app.
-*   **Result**:
-    *   `/apps/my-community/my-app` -> **Localhost** (User's Dev Server).
-    *   `/apps/other-app` -> **Production** (Live GCS).
-    *   `/api/core` -> **Production** (Live API).
-    *   `/*` (PWA Shell) -> **Production** (Live PWA).
+### Scenario 2: Platform Dev ("Dogfooding")
+*   **User**: Core team, full repo checkout.
+*   **Setup**: start the backend (`:4000`), the platform site (`:5174`), Powch site/service as needed, then `descix serve --site-url https://localhost:5174`.
+*   **Result**: the gateway routes `/` to the local shell, `/apifront` to the local Core, `/powch` to the configured Powch origin, `/s/*` to microservices, `/p/{appId}` to product sites.
 
 ### Scenario 3: Production
 *   **User**: End User.
@@ -134,5 +215,87 @@ The gateway uses `createViteProxyConfig` from `@descix/app-sdk/dev` to generate
 
 ## 5. Client-Side Implications
 
-*   **"Dumb" Client**: The PWA Client (`AppData.js`) no longer needs complex logic to rewrite GCS URLs. It simply constructs the canonical path: `/apps/{community}/{app_id}/index.html`.
-*   **Embedded Mode**: For embedded scenarios (e.g., iframes), we may retain some legacy rewrite logic as a fallback, but the primary development flow relies on the Proxy.
+*   **"Dumb" client**: the shell constructs a canonical relative path and lets the gateway (locally) or the LB (in production) resolve it. No GCS-URL rewriting in client code.
+*   **The credential is a body field**, not a cookie and not a header: every call is a relative `POST /apifront/` with the token in the JSON body. There is no `SameSite` problem, no credentialed CORS preflight, and the browser origin is irrelevant to the mesh — same-origin is required for *frame scripting*, not for auth.
+*   **Set your framework's base path to `/p/{appId}`.** The gateway does not rewrite paths, so assets requested at `/` will 404.
+
+## 6. Running from a git worktree
+
+`.descix/workspace.json` is gitignored, so no worktree has one. The gateway walks **up** from cwd to find it, so an in-repo worktree silently inherits the **main checkout's** workspace — its port, its products, its `localPath`s. Copying the file into a worktree does not help: a saved workspace bakes an absolute `workspaceRoot` and prefers it over the discovered root, pointing back at the original checkout. Out-of-repo worktrees fail earlier and more confusingly: a credential-loading command reports **"Authentication required… Run: descix login"** when the real cause is a missing workspace file.
+
+Rules of thumb: run the CLI from the canonical checkout, and treat an auth error raised from a worktree as a workspace-resolution suspect *before* re-authenticating.
+
+### Deploying: probe the credential the action actually uses
+
+`deploy-env.sh` will refuse to start rather than fail halfway:
+
+```
+gcloud credentials are NOT usable (expired user session, or no active account)...
+Refusing to start a real deploy that would fail partway through.
+```
+
+That refusal is the script working correctly, and **an expired gcloud user session alongside live
+ADC is a normal steady state**, not a broken machine. The two are different credentials behind one
+word: the deploy path needs the **user session**, while most quick probes reach for **ADC**.
+
+This is the trap: `gcloud auth application-default print-access-token` returns a token, you record
+"gcloud is fine", and that observation is *true and irrelevant*. **Probe the credential the action
+actually uses, not an adjacent one that happens to answer.**
+
+The remedy is one line, needs no re-auth prompt, and the script prints it itself:
+
+```bash
+export CLOUDSDK_AUTH_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
+[ -n "$CLOUDSDK_AUTH_ACCESS_TOKEN" ] || { echo "empty token"; exit 1; }
+```
+
+Assert it non-empty before launching — an empty token reproduces the same refusal one layer later,
+where it is harder to recognise.
+
+**Why this is written down rather than left to be rediscovered:** without it, the next agent reads
+a correct fail-loud refusal as *platform unreachable* and stops under the platform-reachability
+rule — halting a lane and escalating, over a one-line export the script had already told it. A
+fail-loud message nobody knows how to act on still costs a lane.
+
+### Exit codes from wrappers are not evidence
+
+A deploy wrapper ending in `| tail` returns **tail's** status, not the deploy's. A run can report
+exit 0 while the deploy correctly returned 1. Capture the real status *before* anything pipes it:
+
+```bash
+deploy-env.sh dev; rc=$?          # capture FIRST
+deploy-env.sh dev 2>&1 | tail -40 # then look at output separately
+```
+
+To confirm a deploy succeeded, **read the log, not the exit code** — and where the artifact is
+observable (a served object's timestamp, a string in the shipped bundle), check that instead. A
+pipe silently drops information in both directions: `| tail` hides a failure, and `| head` hides
+later matches from a search that looks complete.
+
+### The SDK you edit is not always the SDK you serve
+
+A second, sharper worktree trap, and it is silent. `DeSciX_Cloud/site/node_modules/@descix/app-sdk`
+is a **symlink into the canonical Core checkout**:
+
+```
+$ readlink DeSciX_Cloud/site/node_modules/@descix/app-sdk
+../../../../DeSciX_Core/descix-app-sdk
+```
+
+and `@descix/app-sdk` has **no build step** — its `main` and its `.` export both point straight at
+`./src/index.js`, so Vite serves the package source as-is. Put those two facts together: **`descix
+serve` serves whatever the CANONICAL Core working tree contains**, no matter which worktree you are
+editing in. Change `app-sdk` on a branch, reload, and you are still running canonical `main` — your
+edit is not in the page, nothing errors, and the obvious conclusion ("my change had no effect") is
+wrong.
+
+Verify what is actually being served before you conclude anything about a change:
+
+```bash
+readlink DeSciX_Cloud/site/node_modules/@descix/app-sdk       # where the symlink points
+node -p "require.resolve('@descix/app-sdk')"                  # from the site directory
+```
+
+If it resolves to the canonical checkout and you are editing elsewhere, you are measuring the wrong
+tree. Re-point the symlink at your worktree for the measurement **and restore it afterwards** — it
+is untracked, so nothing will remind you.

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

@@ -133,7 +133,7 @@ tell_me_how({
 
 ### 3.5 Integration with SDK V2 Setup
 
-After `descix setup` completes:
+After `descix mcp quickstart` completes:
 
 1. `workspace.json` is created with community/app mappings
 2. Credentials are saved to `.descix/wallet.json`
@@ -233,7 +233,7 @@ const result = await execute_remote_command({
 ### 5.1 Initial Setup Phase
 
 ```
-descix setup [--dev]
+descix mcp quickstart
        │
        ▼
    Prerequisites Check (gcloud, ADC)
@@ -368,7 +368,7 @@ if (tools.recommended_tools.length > 0) {
 
 **Pattern: Project-Scoped Operations**
 ```javascript
-// Only works after descix setup
+// Only works after descix mcp quickstart
 const tools = await tell_me_how({ 
   question: "How do I update this app?",
   scope: "project"  // Uses workspace.json
@@ -395,7 +395,7 @@ descix microservice vectorize -r SERVICE_README.md
 **Solution:**
 ```bash
 # Run setup first
-descix setup --dev
+descix mcp quickstart
 
 # Or ensure you're in the workspace root
 cd /path/to/workspace
@@ -416,9 +416,9 @@ cd /path/to/workspace
 
 | Component | Path |
 |-----------|------|
-| MCP Tools | `DeSciX_Core/descix-cli/lib/mcp-tools.js` |
-| tell_me_how Implementation | `DeSciX_Cloud/services/commandHandlers/ragCommands.js` |
-| execute_remote_command | `DeSciX_Cloud/services/apiFront.js` |
-| SERVICE_README Template | `DeSciX_ServiceSDK/templates/SERVICE_README_TEMPLATE.md` |
+| 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/lib/commands/service.js` |
+| Service Registration | `DeSciX_Core/descix-cli/bin/descix.js` |