@descix/cli 1.0.17 → 1.0.18

package/agent-assets/guides/README.md

@@ -44,7 +44,8 @@ Does the user need a public website?
 ### Microservice
 - Backend service with MCP-exposed commands
 - Add `microservice/` folder with `descix microservice init`
-- Commands: `descix microservice register/vectorize`
+- Commands: `descix microservice register -r SERVICE_README.md` (registration also vectorizes the
+  README for `tell_me_how` discovery — there is no separate developer step)
 
 ### Dynamic Site
 - SSR app where microservice serves the site

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

@@ -24,12 +24,8 @@ my-dynamic-app/
 │   ├── app_description.md
 │   ├── icon.png
 │   └── system_instructions.md
-├── kb/
-│   ├── staging/
-│   ├── General/
-│   │   ├── README.md
-│   │   └── user-guide.md
-│   └── chunks/
+├── docs/                        # Your RAG content — any location works
+│   └── user-guide.md            # named in a corpus manifest (.descix/manifests/General.json)
 ├── site/
 │   └── README.md               # "Site served by microservice"
 ├── microservice/
@@ -85,9 +81,9 @@ descix microservice init
 # 2. Add SSR routes to your service, run it locally behind the gateway
 descix serve
 
-# 3. Register and vectorize (after the service is deployed — see Deployment)
-descix microservice register
-descix microservice vectorize
+# 3. Register (after the service is deployed — see Deployment). This also vectorizes the
+#    README you pass with -r, so tell_me_how can discover the service's tools.
+descix microservice register -r SERVICE_README_myapp.md
 
 # 4. Sync KB
 descix kb corpus sync -c <community> -a <app>
@@ -98,7 +94,7 @@ descix kb corpus sync -c <community> -a <app>
 | Capability | Enabled |
 |------------|---------|
 | RAG search | Yes |
-| chat_with_kb | Yes |
+| RAG chat (`ask_question_to_app`) | Yes |
 | Public URL | Yes |
 | MCP tools | Yes |
 | tell_me_how discovery | Yes |

package/agent-assets/guides/knowledge-only-pattern.md

@@ -23,18 +23,19 @@ my-docs/
 │   ├── app_description.md      # Required
 │   ├── icon.png                # Required (512x512)
 │   └── system_instructions.md  # Required
-└── kb/
-    ├── staging/                # New files to push
-    ├── General/                # Text-converted content
-    │   ├── README.md
-    │   ├── getting-started.md
-    │   ├── api-reference.md
-    │   └── tutorials/
-    │       └── ...
-    └── chunks/                 # Processed chunks (JSON)
+├── docs/                       # Your content — any location works
+│   ├── getting-started.md
+│   ├── api-reference.md
+│   └── tutorials/
+│       └── ...
+└── .descix/
+    └── manifests/
+        └── General.json        # Corpus manifest — names the docs source(s) above
 ```
 
-**Note:** No `site/` or `microservice/` folders needed.
+**Note:** No `site/` or `microservice/` folders needed. There is no required KB folder — the
+corpus manifest names whichever git-tracked directory holds your docs (`docs/` above is just an
+example; `kb/General/` also works if that's where content ends up, e.g. from `descix drive pull`).
 
 ## Configuration (`workspace.json`)
 
@@ -76,7 +77,7 @@ The git path needs no Drive at all: commit markdown, name it in the manifest, ru
 | Capability | Enabled |
 |------------|---------|
 | RAG search | Yes |
-| chat_with_kb | Yes |
+| RAG chat (`ask_question_to_app`) | Yes |
 | Public URL | No |
 | MCP tools | No |
 | tell_me_how discovery | No |

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

@@ -24,12 +24,9 @@ my-service/
 │   ├── app_description.md
 │   ├── icon.png
 │   └── system_instructions.md
-├── kb/
-│   ├── staging/
-│   ├── General/
-│   │   ├── README.md
-│   │   └── api-reference.md
-│   └── chunks/
+├── .descix/
+│   └── manifests/
+│       └── General.json        # Corpus manifest — names the docs `kb corpus sync` publishes
 ├── site/                       # Optional frontend
 │   └── ...
 ├── microservice/
@@ -72,7 +69,7 @@ infrastructure for free, and a service that hand-rolls its own config or reads
 only shows up later, in the environment where it matters.
 
 **This is also why your service is called at its own Cloud Run instance rather than
-through an extra hop at the DeSciX router** (CEO-D-2026-08-21-DIRECT-MICROSERVICE-ROUTING-IS-DESIGN).
+through an extra hop at the DeSciX router** — direct routing is by design.
 Direct routing is the intended path *because* a service built on the SDK already carries
 the infrastructure the extra hop would otherwise have to add. Read a direct call as the
 architecture working, not as a bypass — the correctness precondition is that the service
@@ -110,19 +107,19 @@ descix microservice init
 
 # 2. Implement your commands in commandHandlers/
 
-# 3. Publish the service MANIFEST so its commands are discoverable
-descix microservice register
+# 3. Publish the service MANIFEST and vectorize its SERVICE_README in one step
+descix microservice register -r SERVICE_README_myapp.md
 
-# 4. Vectorize SERVICE_README for discovery
-descix microservice vectorize
-
-# 5. Sync KB
+# 4. Sync KB
 descix kb corpus sync -c <community> -a <app>
 ```
 
 **What registration is, and is not.** It publishes your `manifest.json` — the command list —
-so `tell_me_how` can discover your tools. `scripts/register.js` writes that manifest and logs
-the commands it published. It is a DISCOVERY step.
+and vectorizes the README you pass with `-r`, so `tell_me_how` can discover your tools.
+`scripts/register.js` writes that manifest and logs the commands it published. There is no
+separate developer-facing vectorize step — `descix microservice vectorize` exists but is an
+admin-only utility (for re-vectorizing without re-registering), not part of the normal flow.
+It is a DISCOVERY step.
 
 It is not how your service becomes reachable, and nothing here asks you to declare a route or
 a URL. Do not read this step as wiring up addressing.
@@ -132,7 +129,7 @@ a URL. Do not read this step as wiring up addressing.
 | Capability | Enabled |
 |------------|---------|
 | RAG search | Yes |
-| chat_with_kb | Yes |
+| RAG chat (`ask_question_to_app`) | Yes |
 | Public URL | Yes (via service) |
 | MCP tools | Yes |
 | tell_me_how discovery | Yes |

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

@@ -24,12 +24,8 @@ my-site/
 │   ├── app_description.md
 │   ├── icon.png
 │   └── system_instructions.md
-├── kb/
-│   ├── staging/
-│   ├── General/
-│   │   ├── README.md
-│   │   └── ... (markdown for RAG)
-│   └── chunks/
+├── docs/                       # Your RAG content — any location works
+│   └── ... (markdown, named in a corpus manifest)
 ├── site/                       # Static files to deploy
 │   ├── index.html
 │   ├── styles.css
@@ -39,6 +35,9 @@ my-site/
 │   └── dist/                   # Build output (if using bundler)
 ├── src/                        # Source files (not deployed)
 │   └── ...
+├── .descix/
+│   └── manifests/
+│       └── General.json        # Corpus manifest — names docs/ as the sync source
 ├── package.json
 └── vite.config.js
 ```
@@ -79,7 +78,7 @@ descix site upload
 | Capability | Enabled |
 |------------|---------|
 | RAG search | Yes |
-| chat_with_kb | Yes |
+| RAG chat (`ask_question_to_app`) | Yes |
 | Public URL | Yes |
 | MCP tools | No |
 | tell_me_how discovery | No |

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

@@ -6,17 +6,20 @@ This document guides the AI agent through validating an app's folder structure a
 
 ### Step 1: Check Folder Structure
 
-Verify these folders exist:
+Verify these exist:
 
 ```
 {app_folder}/
-├── assets/           # Required
-├── kb/               # Required
-│   └── General/      # Required (default KB)
-├── site/             # Required (even if placeholder)
-└── microservice/     # Required (even if placeholder)
+├── assets/                          # Required
+├── .descix/manifests/<KB>.json      # Required — the corpus manifest (see Step 3)
+├── site/                            # Required (even if placeholder)
+└── microservice/                    # Required (even if placeholder)
 ```
 
+There is no required KB folder. A knowledge base is whatever git-tracked source(s) the corpus
+manifest names — `kb/General/` is one common convention (especially if the app also uses `descix
+drive pull`), but any path works.
+
 **If folders are missing**, offer to create them with appropriate placeholder content.
 
 ### Step 2: Check Required Assets
@@ -76,33 +79,48 @@ I can create a starter template based on your app description.
 
 ### Step 3: Check Knowledge Base
 
-#### `kb/General/README.md`
+#### `.descix/manifests/<KB>.json`
+
+**Check**: A corpus manifest exists at `{app_folder}/.descix/manifests/<KB-name>.json` (default KB
+name is `General`) and its `sources` array names at least one git-tracked path.
 
-**Check**: File exists with overview content
+**This is the real check** — the manifest is what `descix kb corpus sync` reads. There is no
+folder-existence check to run instead of it: a `kb/General/` folder with files in it does nothing
+for RAG until a manifest names it.
 
-**If missing**, create from app_description or guide:
+**If missing**, guide the user:
 
 ```
-Your knowledge base needs a README. This is the first document
-the AI will reference when answering questions.
+Your app doesn't have a knowledge base manifest yet. This file
+(.descix/manifests/General.json) tells `descix kb corpus sync` which
+of your git-tracked files to index for RAG.
 
-I can create one based on your app description, or you can
-provide specific content for the overview.
+Minimal shape:
+{
+  "kb_name": "General",
+  "sync_mode": "local",
+  "sources": [
+    { "path": "docs", "ref": "main", "tier": 1, "doc_type": "documentation" }
+  ]
+}
+
+Which folder(s) in your repo should I name as sources?
 ```
 
-#### KB Content
+#### Manifest Sources
 
-**Check**: At least one documentation file in `kb/General/`
+**Check**: `descix kb corpus status -a <app_id> -k <KB>` reports at least one tracked file (or run
+`descix kb corpus sync --dry-run --show-walk` to preview the walk before syncing).
 
 **If empty**, suggest:
 
 ```
-Your knowledge base is empty. The AI can only answer questions
-based on content in kb/General/.
+Your knowledge base manifest has no sources yet (or its sources walk to zero files).
+The AI can only answer questions based on content the manifest names.
 
 Suggestions:
-- Move existing documentation here
-- Create a getting-started.md
+- Point a source at existing documentation
+- Create a getting-started.md and name its folder
 - Add API reference docs
 - Include user guides
 ```
@@ -160,49 +178,31 @@ This app does not have a backend microservice.
 
 ## Pull from Drive Workflow
 
-If the app already exists on Drive, offer to pull existing assets.
-
-### Check if App Exists Remotely
-
-```
-Use: validate_app_assets({ community_id, app_id, check_drive: true })
-
-Returns:
-{
-  "local_assets": { ... },
-  "remote_assets": { ... },
-  "missing_locally": ["icon.png", "system_instructions.md"],
-  "can_pull": true
-}
-```
+If the app already exists on Drive (Drive-mode authoring), offer to pull existing content.
+**There is no dedicated "check what's on Drive" command** — the canonical tool is `descix drive
+pull` itself, which downloads and converts in one step (nothing to plan around a separate check
+command that doesn't exist).
 
 ### Offer to Pull
 
 ```
-I found your app already exists on DeSciX Drive with these assets:
-- ✓ app_description.md (234 bytes)
-- ✓ icon.png (45KB)
-- ✓ system_instructions.md (1.2KB)
+Your app may already have content on DeSciX Drive.
 
-Your local folder is missing:
-- icon.png
-- system_instructions.md
-
-Would you like me to pull these from Drive to your local folder?
-[Yes, pull missing assets] [No, I'll create new ones]
+Would you like me to pull it into your local folder?
+[Yes, pull from Drive] [No, I'll create new ones]
 ```
 
 ### Execute Pull
 
-```
-Use: pull_app_assets_from_drive({
-  community_id,
-  app_id,
-  local_path,
-  folders: ["assets", "kb"]  // Optional: specify which folders
-})
+```bash
+descix drive pull -c <community_id> -a <app_id>
 ```
 
+This downloads and converts Drive content to local markdown (default KB `General`; pass `-k
+<name>` for another) and reports what it pulled, converted, skipped or left unchanged. Follow up
+with `descix kb corpus sync -a <app_id>` once the pulled files are named in a corpus manifest —
+`descix drive pull` never syncs to Pinecone by itself.
+
 ## Validation Results Format
 
 After validation, report status clearly:
@@ -212,7 +212,7 @@ After validation, report status clearly:
 
 ### Folder Structure
 ✓ assets/ exists
-✓ kb/General/ exists
+✓ .descix/manifests/General.json exists
 ✓ site/ exists
 ✓ microservice/ exists
 
@@ -222,8 +222,8 @@ After validation, report status clearly:
 ✓ assets/system_instructions.md (1.2KB)
 
 ### Knowledge Base
-✓ kb/General/README.md exists
-✓ 5 documents found (12.4KB total)
+✓ .descix/manifests/General.json names 1 source
+✓ 5 documents tracked (`descix kb corpus status -a my-app -k General`)
 
 ### Site
 ○ site/ contains placeholder only (no UI)
@@ -303,7 +303,9 @@ Do NOT:
 {Describe the desired tone: professional, friendly, technical, etc.}
 ```
 
-### kb/README.md Template
+### KB Overview Doc Template
+
+Place this wherever your corpus manifest points (e.g. `docs/README.md`):
 
 ```markdown
 # {App Name} Knowledge Base
@@ -376,10 +378,10 @@ Always run validation:
 
 ### Before `descix kb corpus sync`
 
-1. Check `kb/General/` exists
-2. Verify at least one document exists
-3. Warn if no README.md
-4. Report total document count and size
+1. Check `.descix/manifests/<KB>.json` exists
+2. Run `--dry-run --show-walk` and confirm the manifest's sources resolve to at least one file
+3. Warn if no overview doc is named among the sources
+4. Report total document count from the dry-run output
 
 ### Before `descix site upload`
 

package/agent-assets/instructions/onboarding-flow.md

@@ -16,26 +16,28 @@ Purpose: Maps local folders to DeSciX apps and stores all configuration.
 
 ```json
 {
-  "version": "2.0",
-  "primaryCommunity": "daita",
-  "communities": {
-    "daita": {
-      "apps": {
-        "appsdk": {
-          "localPath": "daita/appsdk",
-          "absolutePath": "/path/to/workspace/daita/appsdk",
-          "kbId": "General"
-        }
+  "version": "2.1",
+  "env": {
+    "environment": "DEV",
+    "apiUrl": "https://dev.descix.net",
+    "products": [
+      {
+        "appId": "daita-appsdk",
+        "communityId": "daita",
+        "localPath": "daita/appsdk",
+        "kbId": "General"
       }
-    }
+    ]
   },
   "driveConfig": {
-    "base_folder_id": "...",
-    "base_folder_name": "..."
+    "base_folder_id": "..."
   }
 }
 ```
 
+A `communities`-keyed block with no `env` block is the removed v1 shape — the loader refuses it:
+`v1 workspace format is not supported. Migrate to v2.1.`
+
 **Used for:**
 - CLI auto-detection of community/app from current directory
 - `tell_me_how --scope project` to discover project-specific tools
@@ -139,20 +141,12 @@ Which mappings should I create?
 
 For each mapping, create appropriate config:
 
-1. **workspace.json** (root level):
-   ```json
-   {
-     "version": "2.0",
-     "primaryCommunity": "{primary_community_id}",
-     "directoryMappings": {
-       "{folder}": {
-         "communityId": "{community_id}",
-         "appId": "{app_id}",
-         "kbId": "General"
-       }
-     }
-   }
+1. **workspace.json** (root level) — written by CLI verbs, never by hand:
+   ```bash
+   descix config init --env dev                          # creates workspace.json, pins env.apiUrl
+   descix app init -a {app_id} -c {community_id} -p {folder}   # adds env.products[] entry
    ```
+   Each mapping becomes one `env.products[]` entry (`appId`, `communityId`, `localPath`, `kbId`).
 
 ## App Configuration Flow
 
@@ -180,10 +174,13 @@ Would you like to:
 
 For each folder being configured:
 
-1. Read `packaging-types.md` for the decision tree
-2. Read `folder-analysis.md` for detection heuristics
+1. Read [guides/README.md](../guides/README.md) for the decision tree (Knowledge-Only / Static
+   Site / Microservice / Dynamic Site)
+2. Read [app-asset-validation.md](./app-asset-validation.md#folder-analysis-heuristics) for
+   detection heuristics
 3. Present options to user with recommendations
-4. Use appropriate template from `templates/{type}/`
+4. Scaffold with the matching CLI verb: `descix site init` and/or `descix microservice init`
+   (there is no `templates/{type}/` to read directly — the CLI copies the right scaffold)
 
 ### Step 4: Validate Folder Structure
 
@@ -191,12 +188,15 @@ After determining packaging type, ensure the folder follows the [Standard Folder
 
 ```
 {app_folder}/
-├── assets/                    # App identity (required)
-├── kb/General/                # Knowledge base (required)
-├── site/                      # Static site (required)
-└── microservice/              # Backend service (required)
+├── assets/                          # App identity (required)
+├── .descix/manifests/<KB>.json      # Corpus manifest — required for RAG, see below
+├── site/                            # Static site (required)
+└── microservice/                    # Backend service (required)
 ```
 
+There is no required KB folder — a knowledge base is whatever git-tracked source(s) the corpus
+manifest names.
+
 **Validation Steps:**
 
 1. Check if each required folder exists
@@ -204,54 +204,37 @@ After determining packaging type, ensure the folder follows the [Standard Folder
 3. Check if kb/ has a README.md
 4. For missing folders/files, offer to create with placeholders
 
-Use `validate_app_structure` command:
-
-```javascript
-execute_remote_command({
-  command: "validate_app_structure",
-  params: { local_path: "/path/to/app" }
-})
-```
+`validate_app_structure` returns a generic checklist — a folder existing does not mean the KB is
+wired up. **The check that actually matters for RAG is `.descix/manifests/<KB>.json` existing with
+at least one source**, per [app-asset-validation.md](./app-asset-validation.md#step-3-check-knowledge-base).
 
 ### Step 5: Pull from Drive (Optional)
 
-If the app already exists remotely, offer to pull existing assets:
+If the app already exists remotely, offer to pull existing content:
 
 ```
-I notice this app ({community_id}/{app_id}) already exists on DeSciX.
-
-Remote assets found:
-- ✓ app_description.md
-- ✓ icon.png
-- ✓ system_instructions.md
+Your app may already have content on DeSciX Drive.
 
-Your local folder is missing some of these.
-
-Would you like me to pull them from Drive?
-[Yes, pull missing assets] [No, I'll create new ones]
+Would you like me to pull it into your local folder?
+[Yes, pull from Drive] [No, I'll create new ones]
 ```
 
-Use `pull_app_assets_from_drive` command:
-
-```javascript
-execute_remote_command({
-  command: "pull_app_assets_from_drive",
-  params: {
-    community_id: "...",
-    app_id: "...",
-    local_path: "/path/to/app",
-    folders: ["assets", "kb"]  // Which folders to pull
-  }
-})
+```bash
+descix drive pull -c <community_id> -a <app_id>
 ```
 
+This downloads and converts Drive content to local markdown and reports what changed. It does not
+sync to Pinecone by itself — follow with `descix kb corpus sync` once the pulled files are named
+in a corpus manifest.
+
 ### Step 6: Create Missing Structure
 
 For any missing folders or files:
 
-1. Create the folder structure
-2. Add placeholder READMEs explaining purpose
-3. Use templates from `templates/common/`
+1. Create `assets/` with starter `app_description.md` / `system_instructions.md` (or run
+   `descix app init`, which scaffolds these for you)
+2. Create a `.descix/manifests/<KB>.json` corpus manifest naming wherever the docs will live
+3. `descix site init` / `descix microservice init` for the code scaffolds
 
 ```
 Creating standard folder structure...
@@ -260,7 +243,7 @@ Created:
 ✓ assets/app_description.md (from template)
 ✓ assets/system_instructions.md (from template)
 ○ assets/icon.png (TODO: add a 512x512 PNG)
-✓ kb/General/README.md
+✓ .descix/manifests/General.json (empty — add sources once you have docs)
 ✓ site/README.md (placeholder)
 ✓ microservice/README.md (placeholder)
 
@@ -307,7 +290,8 @@ Once configured, guide user to:
 ### Sync Commands (in order)
 
 1. **Sync app assets**: `descix app sync-assets`
-   - Uploads app_description.md, icon.png, system_instructions.md to Drive
+   - Syncs app_description.md, icon.png, system_instructions.md to the platform (Firestore/GCS) —
+     not Google Drive
    
 2. **Sync knowledge base**: `descix kb corpus sync`
    - Indexes documents to Pinecone for RAG
@@ -315,14 +299,14 @@ Once configured, guide user to:
 3. **Deploy static site** (if applicable): `descix site upload`
    - Uploads site/ contents to GCS
 
-4. **Register microservice** (if applicable): `descix microservice register`
-   - Registers service with gateway
-   - Run `descix microservice vectorize` for tell_me_how discovery
+4. **Register microservice** (if applicable): `descix microservice register -r SERVICE_README_<name>.md`
+   - Registers the service manifest AND vectorizes the README you pass, in one step —
+     `tell_me_how` discovery needs no separate developer action
 
 ### Ongoing Development
 
 - Use `tell_me_how` for tool discovery and guidance
-- Use `chat_with_kb` to test your AI agent
+- Use `ask_question_to_app` (or `descix chat`) to test your AI agent
 - Use `validate_app_structure` before syncing to catch issues
 
 ---