@descix/cli 1.0.7 → 1.0.9

package/README.md

@@ -75,7 +75,7 @@ now exit non-zero and name this replacement.
 
 1.  **Create** the knowledge base (once per KB):
     ```bash
-    descix kb create -c <community_id> -a <app_id> -k <kb_name>
+    descix app init -a <app_id> --kb <kb_name>
     ```
 2.  **Author** a corpus manifest at `.descix/manifests/<kb_name>.json` describing the sources to sync.
 3.  **Sync** the corpus to the platform (Pinecone):

package/agent-assets/guides/README.md

@@ -49,7 +49,7 @@ Does the user need a public website?
 ### Dynamic Site
 - SSR app where microservice serves the site
 - Everything in `microservice/` (no separate `site/`)
-- Commands: `descix microservice deploy` (ADMIN/LOCAL only — public deploy is not open yet)
+- Commands: `descix microservice init`, `descix serve` locally; public microservice deploy is not open
 
 ## Two-Tier Template System
 

package/agent-assets/guides/dynamic-site-pattern.md

@@ -82,16 +82,14 @@ One `env.products[]` entry, written by `descix app init` and `descix app set-por
 # 1. Create microservice scaffold
 descix microservice init
 
-# 2. Add SSR routes to your service
+# 2. Add SSR routes to your service, run it locally behind the gateway
+descix serve
 
-# 3. Deploy to Cloud Run  (ADMIN/LOCAL ONLY — see note below)
-descix microservice deploy
-
-# 4. Register and vectorize
+# 3. Register and vectorize (after the service is deployed — see Deployment)
 descix microservice register
 descix microservice vectorize
 
-# 5. Sync KB
+# 4. Sync KB
 descix kb corpus sync -c <community> -a <app>
 ```
 
@@ -124,13 +122,6 @@ descix kb corpus sync -c <community> -a <app>
 
 Dynamic sites deploy to Google Cloud Run as a single container. The service handles both API requests and page rendering.
 
-```bash
-# Deploy the microservice (includes site)  — ADMIN/LOCAL ONLY
-descix microservice deploy
-```
-
-> **`descix microservice deploy` is not open to every developer yet.** Its own help
-> marks it `[ADMIN/LOCAL]` — it shells out to the platform deploy script — and the
-> CLI states that public MCP deploy is "coming soon". If you are not a platform
-> admin, expect this step to fail on permissions rather than on your code. Build and
-> run locally with `descix serve` until the public path lands.
+> **Public microservice deploy is not open.** The CLI has no deploy verb for developers; a
+> microservice reaches Cloud Run only through the platform team. Build and run it locally
+> with `descix serve`.

package/agent-assets/instructions/app-asset-validation.md

@@ -334,7 +334,7 @@ This folder doesn't appear to be configured as a DeSciX app.
 
 Options:
 1. Run `descix init` to configure this folder as a new app
-2. Run `descix mcp quickstart` to configure the entire workspace
+2. Run `descix quickstart` to configure the entire workspace
 3. Check if this is the correct folder
 
 Which would you like to do?

package/agent-assets/reference/architecture.md

@@ -176,32 +176,27 @@ Every key is written by a CLI verb (`descix config init --env …`, `descix app
 
 ## 4. CLI Commands
 
-The DeSciX CLI provides two primary ways to manage content: **Context-Aware Updates** (for high-level sync) and **KB Processing Commands** (for low-level control).
+The DeSciX CLI publishes content with one verb per plane. Each command resolves app context from `workspace.json` based on the current working directory, or takes `-a <app_id>` explicitly.
 
-### 4.1 Context-Aware Updates (`descix update`)
-
-These commands auto-detect app context from `workspace.json` based on the current working directory.
+### 4.1 Publish Commands
 
 | Command | Description |
 |---------|-------------|
-| `descix update` | Auto-detect what to update based on current folder |
-| `descix app sync-assets` | Sync app assets (icon, description, instructions) to Drive |
-| `descix kb corpus sync` | Full three-stage sync (Local → Drive → GCS → Pinecone) |
-| `descix site upload` | Deploy CodeSite to GCS |
-| `descix update all` | App assets + site in sequence. It does **not** touch the knowledge base (`update kb` is removed): run `descix kb corpus sync` for that. |
-
-### 4.2 KB Processing Commands (`descix kb`)
+| `descix app sync-assets` | Sync app assets (`system_instructions.md`, `app_description.md`, `icon.png`) to the platform |
+| `descix kb corpus sync` | Sync a knowledge base from the git files its manifest names to Pinecone |
+| `descix site upload` | Deploy the site to GCS and record its path on the app |
 
-These commands provide granular control over the V2 local-first pipeline.
+### 4.2 KB Commands (`descix kb`, `descix drive`)
 
 | Command | Description |
 |---------|-------------|
-| `descix drive pull` | Download from Drive, convert to text in `kb/General/` |
-| `descix drive push` | Upload files from `kb/staging/` to Drive |
-| `descix kb corpus sync` | Generate JSON chunks from `kb/General/` to `kb/chunks/` |
-| `descix kb corpus sync` | Push chunks to Pinecone via backend API |
-| `descix kb corpus sync` | Convenience: pull → chunk → sync |
-| `descix kb corpus status` | Show sync status (local vs Pinecone) |
+| `descix app init -a <app_id> --kb <kb_name>` | Create a knowledge base on the app |
+| `descix kb corpus sync` | Sync the manifest's git files to Pinecone |
+| `descix kb corpus status` | Show corpus sync state (files, chunks, last sync, resolved ref) |
+| `descix kb list` | List knowledge bases for an app |
+| `descix kb delete` | Delete a knowledge base (refuses a non-empty KB unless `--force`) |
+| `descix drive pull` | Pull content from Drive and convert to local markdown |
+| `descix drive push` | Push staging files to Drive |
 
 ### Scaffold Commands
 
@@ -209,7 +204,7 @@ These commands provide granular control over the V2 local-first pipeline.
 |---------|-------------|
 | `descix site init` | Copy site template to current app's `site/` folder |
 | `descix site upload` | Deploy site to GCS |
-| `descix site servelocal [port]` | Register local dev server port |
+| `descix app set-site -a <app_id> --port <port>` | Register the local dev-server port for the app's site (`env.products[].site.port`) |
 | `descix microservice init` | Copy microservice template to current app's `microservice/` folder |
 | `descix microservice register` | Register microservice with gateway |
 | `descix microservice vectorize` | Vectorize README for discovery |
@@ -228,14 +223,15 @@ These commands provide granular control over the V2 local-first pipeline.
 ### Setup Command
 
 ```bash
-descix mcp quickstart
+descix quickstart
 ```
 
 Flow:
-1. Check prerequisites (gcloud CLI, ADC credentials)
-2. Open browser for device login + workspace configuration
-3. Hydrate local workspace from PWA selection
-4. Create folder structure with new KB layout
+1. Device login in the browser (skipped when `.descix/wallet.json` holds a valid session)
+2. Create `.descix/workspace.json` (skipped when a workspace already exists up the tree)
+3. Write agent instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.clinerules`)
+4. Write `.vscode/mcp.json` (skipped when the DeSciX extension handles MCP)
+5. Copy the SDK agent assets to `.descix/sdk-assets/` (fails loud if the package's assets are missing)
 
 ---
 
@@ -344,7 +340,6 @@ gcloud auth application-default login \
 ```
 
 **Verification:**
-- `descix mcp quickstart` checks ADC before proceeding
 - `Hydrator` calls `verifyDriveAuth()` before operations
 
 ### Backend Authentication

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

@@ -136,12 +136,7 @@ Check before you write: `--dry-run` enumerates would-be upserts and purges with
 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.
+**Only text extensions are ingested.** The corpus walk takes `.md .txt .js .mjs .cjs .ts .tsx .jsx .py .rs .go .sol .lean .json .jsonl .yaml .yml .toml .csv .tex .sh .bash` (`PROCESSABLE_EXTENSIONS` in `lib/core/CorpusWalker.js`); any other file in a manifest source, `.mdc` included, never enters a knowledge base.
 
 #### What you put in a KB changes what comes out of it
 

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

@@ -138,9 +138,9 @@ tell_me_how({
 
 ### 3.5 Integration with SDK V2 Setup
 
-After `descix mcp quickstart` completes:
+After `descix quickstart` completes:
 
-1. `workspace.json` is created with community/app mappings
+1. `.descix/workspace.json` exists (created when none was found up the tree)
 2. Credentials are saved to `.descix/wallet.json`
 3. `tell_me_how --scope project` now filters by configured apps
 4. Agent can discover project-specific tools
@@ -238,16 +238,22 @@ const result = await execute_remote_command({
 ### 5.1 Initial Setup Phase
 
 ```
-descix mcp quickstart
+descix quickstart
        │
        ▼
-   Requires a prior `descix login` (refuses and names it otherwise)
+   Device login (skipped when .descix/wallet.json holds a valid session)
        │
        ▼
-   Setup wizard (lib/wizard/setup.js)
+   .descix/workspace.json created (skipped when one exists up the tree)
        │
        ▼
-   .cursor/rules/descix_mcp.mdc deployed
+   CLAUDE.md, .github/copilot-instructions.md, .cursorrules, .clinerules written
+       │
+       ▼
+   .vscode/mcp.json written (skipped when the DeSciX extension handles MCP)
+       │
+       ▼
+   .descix/sdk-assets/ copied (fails loud if the package's assets are missing)
        │
        ▼
    ✓ Ready for agent interaction
@@ -312,7 +318,7 @@ descix tell-me-how "How do I sync my knowledge base?"
 
 ### 6.2 workspace.json from Hydration
 
-`descix config init --env …` creates `workspace.json`; `descix app init` adds the app's `env.products[]` entry; `descix mcp quickstart` fills `driveConfig.base_folder_id`:
+`descix config init --env …` creates `workspace.json`; `descix app init` adds the app's `env.products[]` entry; no verb writes `driveConfig.base_folder_id` — set it in `.descix/workspace.json` when you use `descix drive pull/push`:
 
 ```javascript
 {
@@ -366,7 +372,7 @@ if (tools.recommended_tools.length > 0) {
 
 **Pattern: Project-Scoped Operations**
 ```javascript
-// Only works after descix mcp quickstart
+// Only works inside a workspace (descix quickstart or descix config init)
 const tools = await tell_me_how({ 
   question: "How do I update this app?",
   scope: "project"  // Uses workspace.json
@@ -393,7 +399,7 @@ descix microservice vectorize -r SERVICE_README.md
 **Solution:**
 ```bash
 # Run setup first
-descix mcp quickstart
+descix quickstart
 
 # Or ensure you're in the workspace root
 cd /path/to/workspace

package/agent-assets/reference/platform-api-consumer.md

@@ -91,11 +91,17 @@ ASSET NOT FOUND at gs://... Upload it first with `descix app media-upload`.
 Both come back as `MEDIA_ASSET_UNREADABLE`. The first means you referenced the wrong app's asset;
 the second means you have not uploaded yet. Upload into the app that will do the asking.
 
-**The upload verb hands you both forms, and both work.** `descix app media-upload` returns a
-`path` (relative to the app's assets prefix) and a `ref` (the `gs://` URI) for every file, plus a
-`public_url`; `--json` prints them for scripting. Either `path` or `ref` is a valid `asset_ref` —
-so if a rule in your head says the tool's own `ref` field is unusable, the rule is wrong, not the
-tool.
+**The upload verb hands you the relative `path`, and it is a valid `asset_ref` as-is.** `descix
+app media-upload` returns, per file, a `path` (relative to the app's assets prefix), a
+`public_url` (the app-host form, e.g. `https://{app}.descix.net/assets/<path>`), `gcs_path` and
+`content_type`; `--json` prints them for scripting. Pass `path` (or a `gs://` URI you construct
+yourself) as `asset_ref` — either form works, see below.
+
+**Who can upload, and how much.** Any app owner, community admin or platform admin may call
+`media-upload` for that app. Storage is capped **200 MB per app today** (pending credit-based
+metering for more) — the cap is enforced server-side by `get_asset_upload_token`, which refuses
+with its own message when a would-be upload exceeds it; the CLI never pre-checks quota locally,
+so trust that refusal over any local math.
 
 **The `gs://` form is accepted.** A `gs://` URI works as an `asset_ref` — it is parsed and
 scope-checked, and the handler then looks the object up by path. What is PROVEN is the form and

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

@@ -38,7 +38,7 @@ is the schema and the verb that owns each key.
 | `env.siteUrl` | the App Shell origin the gateway proxies `/` to (optional; default is the API origin) | `descix config set-site-url <url>` |
 | `env.products[]` | one entry per app in this workspace, see below | `descix app init`, `app set-site`, `app set-port`, `app set-localpath`, `app unmap` |
 | `env.platform` | the platform shell's own entry — platform contributors only; an app developer has none | platform runbook |
-| `driveConfig.base_folder_id` | the Drive base folder for `descix drive pull/push` | `descix mcp quickstart` |
+| `driveConfig.base_folder_id` | the Drive base folder for `descix drive pull/push` | no verb; set it in `.descix/workspace.json` |
 
 A product entry:
 
@@ -135,7 +135,7 @@ gcloud auth application-default login \
 |-------|-------|--------|
 | "Could not load default credentials" | ADC not configured | `gcloud auth application-default login` |
 | "Drive authentication failed" | scopes missing | re-run with the Drive scopes above |
-| "base_folder_id missing" | Drive not registered | `descix mcp quickstart` |
+| "Drive is not linked" | `driveConfig.base_folder_id` unset | set `driveConfig.base_folder_id` in `.descix/workspace.json`, or pass `--folder <id>` to `descix drive pull` |
 
 The git path (`descix kb corpus sync`) needs none of this.