@descix/cli 1.0.6 → 1.0.8

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

@@ -61,41 +61,35 @@ Keeping the scaffold's shape is what lets the service keep inheriting platform b
 
 ## Configuration (`workspace.json`)
 
+One `env.products[]` entry, written by `descix app init` and `descix app set-port` (never by hand):
+
 ```json
 {
-  "communities": {
-    "my-community": {
-      "apps": {
-        "my-dynamic-app": {
-          "localPath": "my-community/my-dynamic-app",
-          "sync_mode": "git",
-          "service": {
-            "port": 4000,
-            "devCommand": "npm run dev"
-          }
-        }
-      }
-    }
-  }
+  "appId": "my-community-my-dynamic-app",
+  "communityId": "my-community",
+  "localPath": "my-dynamic-app",
+  "kbId": "General",
+  "microservice": { "port": 4001 }
 }
 ```
 
+`descix microservice init` refuses to run until `microservice.port` is set: the gateway routes
+`/s/<app_id>` to that port and the service must start on it.
+
 ## CLI Workflow
 
 ```bash
 # 1. Create microservice scaffold
 descix microservice init
 
-# 2. Add SSR routes to your service
-
-# 3. Deploy to Cloud Run  (ADMIN/LOCAL ONLY — see note below)
-descix microservice deploy
+# 2. Add SSR routes to your service, run it locally behind the gateway
+descix serve
 
-# 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>
 ```
 
@@ -128,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/guides/knowledge-only-pattern.md

@@ -38,18 +38,15 @@ my-docs/
 
 ## Configuration (`workspace.json`)
 
+One `env.products[]` entry, written by `descix app init` (never by hand); no `site` and no
+`microservice` slot:
+
 ```json
 {
-  "communities": {
-    "my-community": {
-      "apps": {
-        "my-docs": {
-          "localPath": "my-community/my-docs",
-          "sync_mode": "git"
-        }
-      }
-    }
-  }
+  "appId": "my-community-my-docs",
+  "communityId": "my-community",
+  "localPath": "my-docs",
+  "kbId": "General"
 }
 ```
 
@@ -68,13 +65,12 @@ descix drive push -c <community> -a <app>
 # 4. Pull converted text back
 descix drive pull -c <community> -a <app>
 
-# 5. Chunk for RAG
-descix kb corpus sync -c <community> -a <app>
-
-# 6. Sync to Pinecone
-descix kb corpus sync -c <community> -a <app>
+# 5. Commit the pulled markdown, name its folder in .descix/manifests/<KB>.json, then chunk + sync to Pinecone in one pass
+descix kb corpus sync -a <app>
 ```
 
+The git path needs no Drive at all: commit markdown, name it in the manifest, run step 5.
+
 ## Capabilities
 
 | Capability | Enabled |

package/agent-assets/guides/microservice-pattern.md

@@ -85,25 +85,23 @@ out until something depends on the difference.
 
 ## Configuration (`workspace.json`)
 
+One `env.products[]` entry, written by `descix app init`, `descix app set-port` and (for the optional
+frontend) `descix app set-site` — never by hand:
+
 ```json
 {
-  "communities": {
-    "my-community": {
-      "apps": {
-        "my-service": {
-          "localPath": "my-community/my-service",
-          "sync_mode": "git",
-          "service": {
-            "port": 4000,
-            "devCommand": "npm run start"
-          }
-        }
-      }
-    }
-  }
+  "appId": "my-community-my-service",
+  "communityId": "my-community",
+  "localPath": "my-service",
+  "kbId": "General",
+  "site": { "static": "site" },
+  "microservice": { "port": 4001 }
 }
 ```
 
+`descix microservice init` refuses to run until `microservice.port` is set: the gateway routes
+`/s/<app_id>` to that port and the service must start on it.
+
 ## CLI Workflow
 
 ```bash

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

@@ -45,25 +45,22 @@ my-site/
 
 ## Configuration (`workspace.json`)
 
+One `env.products[]` entry, written by `descix app init` and `descix app set-site` (never by hand):
+
 ```json
 {
-  "communities": {
-    "my-community": {
-      "apps": {
-        "my-site": {
-          "localPath": "my-community/my-site",
-          "sync_mode": "git",
-          "site": {
-            "port": 3000,
-            "devCommand": "npm run docs:dev"
-          }
-        }
-      }
-    }
-  }
+  "appId": "my-community-my-site",
+  "communityId": "my-community",
+  "localPath": "my-site",
+  "kbId": "General",
+  "site": { "static": "site" }
 }
 ```
 
+For a framework dev server instead of files on disk, `descix app set-site -a <app_id> --port 3000`
+writes `"site": { "port": 3000 }`; the gateway proxies `/p/<app_id>` to it without rewriting paths,
+so the framework's base path must be `/p/<app_id>/`.
+
 ## CLI Workflow
 
 ```bash
@@ -116,4 +113,4 @@ This copies the site template with:
 
 ## Deployment
 
-Static files are deployed to Google Cloud Storage and served via signed URLs. The site URL is available in the app's metadata.
+`descix site upload -a <app_id>` uploads the files (delta) to the app's site prefix in Google Cloud Storage and records the deploy manifest. The app is then served on its own host, `https://<app_id>.dev.descix.net/` on DEV and `https://<app_id>.descix.net/` on PROD; `descix site status -c <community> -a <app_id>` shows the deployed manifest.

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/instructions/onboarding-flow.md

@@ -17,13 +17,13 @@ Purpose: Maps local folders to DeSciX apps and stores all configuration.
 ```json
 {
   "version": "2.0",
-  "primaryCommunity": "descix",
+  "primaryCommunity": "daita",
   "communities": {
-    "descix": {
+    "daita": {
       "apps": {
         "appsdk": {
-          "localPath": "descix/appsdk",
-          "absolutePath": "/path/to/workspace/descix/appsdk",
+          "localPath": "daita/appsdk",
+          "absolutePath": "/path/to/workspace/daita/appsdk",
           "kbId": "General"
         }
       }

package/agent-assets/reference/app-creation.md

@@ -4,16 +4,17 @@
 **Version:** 2.0  
 **Last Updated:** January 2026
 
-This document describes how apps and communities are created and hydrated in the DeSciX platform.
+This document describes how apps and communities are created in the DeSciX platform and how the local workspace for an app is set up.
 
 ---
 
 ## 1. Core Philosophy
 
-**"PWA for Provisioning, CLI for Development"**
+**"One path to an app"**
 
-- **Provisioning:** All apps and communities are created through the PWA. This enforces entitlement checks (NFTs, subscriptions) and ensures consistent folder structures via Drive templates.
-- **Development:** The CLI is the primary tool for hydrating the local workspace, managing content, and syncing to the cloud. The CLI does not create apps directly.
+- **Apps:** `descix app init -a <name> -c <community> -p <dir>` creates the app on the platform (`create_app_for_community`, which composes the id `<community>-<short>` and guarantees the default KB) and registers it in the local workspace in one idempotent step. The PWA creates apps too; both reach the same server command. Entitlement checks run server-side either way.
+- **Communities:** created by platform admins only (`descix community create` is `[ADMIN]` and writes live Polygon). A developer builds inside an existing community.
+- **Development:** the CLI is the tool for the local workspace, content, and syncing to the cloud.
 
 **Important Distinction:**
 
@@ -128,7 +129,7 @@ the file to open first.
 
 ### Adding Scaffolds to Apps
 
-After an app is created via PWA, add code scaffolds via CLI:
+After `descix app init` (or PWA creation), add code scaffolds via CLI:
 
 ```bash
 # Add site scaffold
@@ -213,96 +214,29 @@ sequenceDiagram
 
 ---
 
-## 4. Workspace Builder
+## 4. Local Workspace
 
-The PWA Workspace Builder allows users to configure which apps to sync to their local workspace.
-
-### Flow
-
-1. User completes device login (`descix login --setup`)
-2. PWA opens with Workspace Builder
-3. User selects/creates apps to include
-4. PWA returns `workspace_config` to CLI
-5. CLI hydrates local folders
-
-### Workspace Config Response
-
-```json
-{
-  "workspace_config": {
-    "communities": {
-      "descix": {
-        "apps": {
-          "agent": {
-            "localPath": "descix/agent",
-            "sync_mode": "git"
-          }
-        }
-      }
-    }
-  },
-  "drive_config": {
-    "base_folder_id": "1ABC..."
-  }
-}
-```
-
----
-
-## 5. CLI Hydration
-
-### Setup Command
+There is no PWA "workspace builder" hand-off and no hydration step. The local workspace is built by
+CLI verbs, each writing one part of `.descix/workspace.json` (v2.1 — see `workspace-config.md`):
 
 ```bash
-descix mcp quickstart
+descix config init --env dev                        # creates .descix/workspace.json, pins env.apiUrl
+descix login                                        # .descix/wallet.json (add it to .gitignore yourself)
+descix app init -a <name> -c <community> -p .       # env.products[] entry + site/ microservice/ assets/ + default KB
+descix app set-site -a <app_id> --static site       # what the gateway serves at /p/<app_id>
+descix app set-port -a <app_id> -p 4001             # required before descix microservice init
 ```
 
-**Flow:**
-1. Check prerequisites (gcloud CLI, ADC)
-2. Verify Drive access
-3. Open browser for device login
-4. Receive workspace config from PWA
-5. Call `Hydrator.hydrateWorkspace()`
-6. Create local folder structure
-7. Pull content from Drive
-
-### Hydration Process
-
-The `Hydrator` module handles all folder creation and content sync:
-
-```javascript
-// Hydrator.hydrateWorkspace() creates:
-[workspace]/
-├── .descix/
-│   └── workspace.json       # Workspace configuration (sole config file)
-├── [community]/[app]/
-│   ├── assets/
-│   ├── kb/
-│   │   ├── staging/         # For local files to push to Drive
-│   │   ├── General/         # Converted text from Drive
-│   │   └── chunks/          # Generated chunk files
-│   ├── site/                # Optional: for CodeSite
-│   └── microservice/        # Optional: for backend service
-└── .gitignore               # Updated with .descix/wallet.json
-```
-
-**Note:** App configuration is stored in `workspace.json`, not in per-app `context.json` files. The CLI auto-detects app context based on the current working directory.
-
-### Hydrating Individual Apps
-
-After initial setup, users can hydrate specific apps:
-
-```bash
-# Pull entire app from Drive
-descix drive pull -c community -a app
-
-# Or use the build command for full pipeline
-descix kb corpus sync
-```
+`descix app init` creates `site/`, `microservice/` and `assets/` (with starter
+`system_instructions.md` and `app_description.md`) under the app directory. Knowledge-base content
+is whatever your corpus manifest names (`.descix/manifests/<KB>.json`); Drive content arrives via
+`descix drive pull -c <community> -a <app_id>` into `kb/<KB>/` and goes back via `descix drive push`.
+The CLI auto-detects the app from the directory you are standing in; `-c`/`-a` flags win over
+detection.
 
 ---
 
-## 6. Folder Structure Standards
+## 5. Folder Structure Standards
 
 ### App Folders
 
@@ -328,7 +262,7 @@ descix kb corpus sync
 
 ---
 
-## 7. Entitlement Checks
+## 6. Entitlement Checks
 
 App creation requires appropriate entitlements:
 
@@ -343,7 +277,7 @@ The PWA and backend enforce these checks before template copying.
 
 ---
 
-## 8. Key Backend Functions
+## 7. Key Backend Functions
 
 ### Template Copying
 
@@ -366,28 +300,29 @@ async function copyFolderRecursive(sourceFolderId, destParentId, newName) {
 
 ---
 
-## 9. CLI Commands
+## 8. CLI Commands
 
-### App Management (via PWA)
+### App Creation
 
-The CLI does not create apps directly. Users should:
+```bash
+descix config init --env dev                       # pin the environment first (no default)
+descix login                                       # device-code sign-in
+descix app init -a <name> -c <community> -p .      # create on the platform + register locally + default KB
+```
 
-1. Go to PWA dashboard
-2. Create app/community
-3. Run `descix mcp quickstart` or `descix login --setup` to hydrate
+An app created in the PWA is initialized locally with the same verb, minus `-c`:
+`descix app init -a <app_id> -p .`.
 
 ### Post-Creation Commands
 
 ```bash
-# After app is created via PWA:
-descix mcp quickstart                  # Hydrate workspace (first time)
-descix kb corpus sync               # Pull, chunk, sync KB
-descix site upload -a app   # Deploy static site
+descix kb corpus sync -a <app_id>      # chunk + sync the manifest's sources to Pinecone
+descix site upload -a <app_id>         # deploy the static site
 ```
 
 ---
 
-## 10. File References
+## 9. File References
 
 | Component | Path | Description |
 |-----------|------|-------------|
@@ -397,7 +332,7 @@ descix site upload -a app   # Deploy static site
 | Template Config | `DeSciX_Cloud/microservice/defaults-config.json` | Template folder IDs |
 | Drive Templates | `DeSciX_Core/descix-cli/templates/drive/` | Content templates |
 | Git Scaffolds | `DeSciX_Core/descix-cli/templates/scaffolds/` | Code scaffolds |
-| Hydrator | `DeSciX_Core/descix-cli/lib/core/Hydrator.js` | Workspace hydration |
+| Hydrator | `DeSciX_Core/descix-cli/lib/core/Hydrator.js` | `copyScaffold` — copies the site / microservice scaffold into an app |
 | WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | CLI configuration |
 | Setup Command | `DeSciX_Core/descix-cli/lib/wizard/setup.js` | Initial setup |
 | Scaffold Command | `DeSciX_Core/descix-cli/bin/descix.js` | CLI scaffolds |

package/agent-assets/reference/architecture.md

@@ -41,7 +41,7 @@ All core SDK logic resides in `DeSciX_Core/descix-cli/lib/core/`.
 
 | Function | Description |
 |----------|-------------|
-| `hydrateWorkspace(root, config, driveConfig, options)` | Full workspace setup with folder creation and Drive sync |
+| `copyScaffold(type, appPath, options)` | Copy the `site` or `microservice` scaffold into an app (`descix site init` / `descix microservice init`) |
 | `hydrateApp(config, options)` | Pull entire app from Drive |
 | `hydrateKb(config, options)` | Pull and convert KB files from Drive |
 | `pushStaging(config, options)` | Upload files from `kb/staging/` to Drive |
@@ -146,65 +146,57 @@ All core SDK logic resides in `DeSciX_Core/descix-cli/lib/core/`.
 
 ```json
 {
-  "version": "2.0",
-  "communities": {
-    "descix": {
-      "apps": {
-        "agent": {
-          "localPath": "descix/agent",
-          "kbId": "General",
-          "absolutePath": "/path/to/workspace/descix/agent",
-          "site": {
-            "port": 3000,
-            "devCommand": "npm run docs:dev"
-          },
-          "service": {
-            "port": 4001,
-            "devCommand": "npm run start"
-          }
-        }
+  "version": "2.1",
+  "type": "workspace",
+  "workspaceRoot": "/path/to/workspace",
+  "env": {
+    "environment": "DEV",
+    "apiUrl": "https://dev.descix.net",
+    "gateway": { "port": 5599 },
+    "products": [
+      {
+        "appId": "daita-agent",
+        "communityId": "daita",
+        "localPath": "daita/agent",
+        "kbId": "General",
+        "site": { "port": 3000 },
+        "microservice": { "port": 4001 }
       }
-    }
+    ]
   },
-  "driveConfig": {
-    "base_folder_id": "1ABC...",
-    "base_folder_name": "DeSciX"
-  }
+  "driveConfig": { "base_folder_id": "1ABC..." }
 }
 ```
 
+Every key is written by a CLI verb (`descix config init --env …`, `descix app init`, `descix app set-site`, `descix app set-port`, …) — see `workspace-config.md` for the key → verb table. A `communities` block without `env` (the v1 shape) is refused on load.
+
 **Note:** `.descix.app/context.json` files are no longer used. All app configuration is stored in `workspace.json`. The CLI auto-detects app context from the current working directory by matching against registered app paths.
 
 ---
 
 ## 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`~~ | **Deleted.** There is no single all-resources verb. Run the three canonical commands: `descix app sync-assets`, `descix kb corpus sync`, `descix site upload`. |
-
-### 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
 
@@ -212,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 |
@@ -231,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)
 
 ---
 
@@ -256,15 +249,15 @@ Flow:
 
 ```json
 {
-  "community_id": "descix",
+  "community_id": "daita",
   "app_id": "agent",
   "kb_id": "General",
   "chunks": [
     {
-      "id": "descix_agent_General_research_0",
+      "id": "daita_agent_General_research_0",
       "text": "...",
       "entity_type": "CHUNK",
-      "community_id": "descix",
+      "community_id": "daita",
       "app_id": "agent",
       "knowledgebase_name": "General",
       "file_id": "research.md",
@@ -347,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