@descix/cli 1.0.16 → 1.0.18

package/agent-assets/instructions/standard-folder-structure.md

@@ -23,13 +23,15 @@ DeSciX uses a "Mono-Repo" style structure where multiple communities and apps ca
 │       │   ├── icon.png
 │       │   └── system_instructions.md (AI Persona)
 │       │
-│       ├── kb/                 # Knowledge Base (RAG)
-│       │   ├── staging/        # Local files to push to Drive
+│       ├── .descix/
+│       │   └── manifests/
+│       │       └── General.json    # Corpus manifest — names the KB's git-tracked sources
+│       │
+│       ├── kb/                 # Knowledge Base content — OPTIONAL location, any path works
+│       │   ├── staging/        # (if using Drive) Local files to push to Drive
 │       │   │   └── new-doc.pdf
-│       │   ├── General/        # Converted markdown (from Drive pull)
-│       │   │   └── *.md
-│       │   └── chunks/         # JSON chunk files (for vectorization)
-│       │       └── *.chunks.json
+│       │   └── General/        # (if using Drive) Converted markdown from `descix drive pull`
+│       │       └── *.md
 │       │
 │       ├── site/               # Frontend UI (Optional)
 │       │   ├── index.html
@@ -66,19 +68,24 @@ Self-contained folder for a single application.
 - **`system_instructions.md`**: Instructions for the AI Agent that interacts with users of this app.
 - **`icon.png`**: App Icon.
 
-#### `kb/` - Knowledge Base
-The KB folder supports both local-first (Git mode) and Drive-based workflows:
+#### `.descix/manifests/<KB>.json` - Corpus Manifest
+**This is what makes a KB syncable — not any folder's existence.** It names the git-tracked
+path(s) `descix kb corpus sync` walks, chunks and upserts to Pinecone. No manifest means nothing
+to sync, regardless of what is under `kb/`.
+
+#### `kb/` - Knowledge Base content (optional convention)
+There is no required KB folder. `kb/` is one common place to keep content, especially if you also
+use Drive-based authoring:
 - **`staging/`**: Place raw files here (PDFs, images) to push them to Drive via `descix drive push`.
-- **`General/`**: The canonical source of text content. Files here are pulled from Drive and converted to Markdown via `descix drive pull`.
-- **`chunks/`**: Processed JSON chunk files ready for vectorization via `descix kb corpus sync`.
+- **`General/`**: Files pulled from Drive and converted to Markdown via `descix drive pull`. Still
+  needs to be named as a source in the corpus manifest to be indexed — pulling alone does not sync.
 
 **CLI-Centric Processing (Git Mode):**
 ```bash
-descix drive push   # Push staging/ -> Drive
-descix drive pull   # Pull Drive -> General/ (converted to markdown)
-descix kb corpus sync  # Generate chunks from General/ -> chunks/
-descix kb corpus sync   # Push chunks to Pinecone via service layer
-descix kb corpus sync  # Convenience: pull → chunk → sync
+descix drive push      # (optional) Push staging/ -> Drive
+descix drive pull      # (optional) Pull Drive -> local markdown, converted
+# Commit the markdown, name its folder in .descix/manifests/<KB>.json, then:
+descix kb corpus sync  # Walk the manifest's sources, chunk what changed, upsert + purge in Pinecone
 ```
 
 #### `site/` - Frontend
@@ -94,34 +101,30 @@ descix kb corpus sync  # Convenience: pull → chunk → sync
 
 ## Configuration Files
 
-### `.descix/workspace.json` (Root)
+### `.descix/workspace.json` (Root) — v2.1, the only supported format
+
 ```json
 {
-  "version": "2.0",
-  "communities": {
-    "my-dao": {
-      "apps": {
-        "governance": { 
-          "localPath": "my-dao/governance",
-          "sync_mode": "git"
-        },
-        "treasury": { 
-          "localPath": "my-dao/treasury",
-          "sync_mode": "drive"
-        }
-      }
-    }
+  "version": "2.1",
+  "env": {
+    "environment": "DEV",
+    "apiUrl": "https://dev.descix.net",
+    "products": [
+      { "appId": "my-dao-governance", "communityId": "my-dao", "localPath": "my-dao/governance", "kbId": "General" },
+      { "appId": "my-dao-treasury", "communityId": "my-dao", "localPath": "my-dao/treasury", "kbId": "General" }
+    ]
   }
 }
 ```
 
-**`sync_mode` Options:**
-| Mode | KB Source | Use Case |
-|------|-----------|----------|
-| `git` | Local files | CLI-managed apps, developers (default for CLI) |
-| `drive` | Pull from Drive | PWA-created apps, non-technical users |
+Written by CLI verbs only — `descix config init`, `descix app init`, `descix app set-site`,
+`descix app set-port`. A `communities`-keyed block with no `env` block is the removed v1 shape and
+is refused on load: `v1 workspace format is not supported. Migrate to v2.1.`
 
-**Note:** The CLI only supports `git` mode operations. If you are using the CLI, you are effectively in `git` mode.
+**Sync mode:** The CLI only performs **git-mode** operations (local files → corpus manifest →
+Pinecone, via `descix kb corpus sync`). Drive-mode (Drive → GCS → Pinecone, fully server-side) is
+PWA-only and is never triggered by the CLI. There is no per-app `sync_mode` switch in workspace.json
+— using the CLI at all means git mode.
 
 ## Agent Workflow for Migration
 

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

@@ -44,16 +44,9 @@ This separation ensures:
 
 ### Drive Templates
 
-**Location:** Google Drive, owned by `dip@descix.net`  
-**SDK Reference:** `DeSciX_Core/descix-cli/templates/drive/`  
-**Template IDs:** Configured in `DeSciX_Cloud/microservice/defaults-config.json`
-
-```json
-{
-  "DRIVE_COMMUNITY_TEMPLATE_FOLDER_ID": "1ABC...",
-  "DRIVE_AGENT_APP_TEMPLATE_FOLDER_ID": "1XYZ..."
-}
-```
+**Location:** Google Drive, owned by the platform. The CLI ships its own copy of the template
+layout under `templates/drive/`; the platform's Drive folder IDs are server-side config, not
+something the CLI or a developer needs to touch.
 
 **Community Template:**
 ```
@@ -80,9 +73,10 @@ templates/drive/app/
 
 ### Git Scaffolds
 
-**Location:** microservice — `DeSciX_Core/descix-cli/templates/scaffolds/`;
-site — `DeSciX_Core/descix-app-sdk/scaffold/` (owned there, and exported as `SITE_SCAFFOLD_DIR`
-from `@descix/app-sdk/scaffold`, so no caller re-derives the path).
+**Location:** the microservice scaffold ships inside the CLI package (`templates/scaffolds/`); the
+site scaffold ships inside `@descix/app-sdk` and is exported as `SITE_SCAFFOLD_DIR` from
+`@descix/app-sdk/scaffold`, so no caller re-derives the path. `descix microservice init` /
+`descix site init` copy these for you — you do not need to locate them yourself.
 
 **Site Scaffold:**
 ```
@@ -243,12 +237,16 @@ detection.
 | Folder | Purpose | Sync Direction |
 |--------|---------|----------------|
 | `assets/` | App metadata (icon, description) | Bidirectional |
-| `kb/staging/` | Local files to push to Drive | Local → Drive |
-| `kb/General/` | Text-converted files from Drive | Drive → Local |
-| `kb/chunks/` | JSON chunks for Pinecone | Local only |
+| `.descix/manifests/<KB>.json` | Names the KB's git-tracked sources — REQUIRED for a KB to sync | Local, git-tracked |
+| `kb/staging/` (optional) | Local files to push to Drive | Local → Drive |
+| `kb/General/` (optional) | Text-converted files from Drive | Drive → Local |
 | `site/` | Static site files | Local → GCS |
 | `microservice/` | Service code | Local → GCS |
 
+There is no required KB folder and no persisted chunk directory — chunking happens in memory
+during `descix kb corpus sync`. A knowledge base is whatever git-tracked path(s) the corpus
+manifest names; `kb/General/` is a common convention, not a requirement.
+
 ### Required Files
 
 **`assets/` folder:**
@@ -256,9 +254,10 @@ detection.
 - `app_description.md` - Markdown description for App Store
 - `system_instructions.md` - AI agent persona and instructions
 
-**`kb/General/` folder:**
-- Contains reference documents for RAG
-- All formats converted to Markdown/text
+**`.descix/manifests/<KB>.json`:**
+- Names the source path(s) that make up the KB
+- `descix kb corpus sync` walks them at a git ref and publishes to Pinecone — no manifest means
+  nothing to sync
 
 ---
 
@@ -322,17 +321,12 @@ descix site upload -a <app_id>         # deploy the static site
 
 ---
 
-## 9. File References
-
-| Component | Path | Description |
-|-----------|------|-------------|
-| Community Management | `DeSciX_Cloud/microservice/services/communityManagement.js` | Community/App creation |
-| App Commands | `DeSciX_Cloud/microservice/services/commandHandlers/appCommands.js` | Server-side app ops |
-| Google Storage Service | `DeSciX_Cloud/microservice/services/googleStorageService.js` | Drive/GCS operations |
-| 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` | `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 |
+## 9. Summary of Verbs
+
+| Concept | Owned by |
+|---------|----------|
+| Community/App creation | Platform backend (server-side; not part of the SDK you have locally) |
+| Drive/GCS content operations | Platform backend, reached via `descix app init`, `descix drive pull/push` |
+| Content templates (Drive) | Shipped inside the CLI package; copied by `descix app init` |
+| Code scaffolds (site/microservice) | Shipped inside the CLI/app-sdk packages; copied by `descix site init` / `descix microservice init` |
+| Local workspace configuration | `.descix/workspace.json`, written only by CLI verbs — see `workspace-config.md` |

package/agent-assets/reference/architecture.md

@@ -12,93 +12,55 @@ This document is the canonical reference for the DeSciX SDK architecture, coveri
 
 ### Core Philosophy
 
-1. **Drive as Backend:** Google Drive is the canonical source for raw assets (PDFs, documents, images).
-2. **Git as Truth:** The local Git repository is the canonical source for *processed* text and code.
-3. **Client-Side Mediation:** The CLI communicates directly with Drive via ADC (Application Default Credentials), removing server-side proxy overhead for file transfers.
-4. **No Local Tools:** The CLI relies on Drive's internal conversion capabilities (OCR, Doc-to-Markdown) instead of bundling heavy local dependencies.
+1. **Git as Truth:** The git repository — whatever files a corpus manifest names — is the
+   canonical source for what gets published to a knowledge base. There is no required KB folder.
+2. **Manifest-Driven Publish:** `descix kb corpus sync` walks the sources a manifest names at a
+   git ref, chunks what changed, and upserts/purges against Pinecone in one pass. This is the
+   ONE sync surface; there is no separate chunk step or push step for the developer to run.
+3. **Drive as an optional authoring front-end:** Google Drive is one way to *author* raw content
+   (PDFs, documents, images) before it lands in git — via `descix drive pull`/`descix drive push`
+   (ADC-based, client-side, no server-side proxy for the file transfer). It is not required, and
+   it is not itself a sync step — content still has to be committed and named in a manifest.
+4. **No Local Tools:** Drive-based conversion (OCR, Doc-to-Markdown) uses Drive's own capabilities
+   instead of bundling heavy local dependencies.
 
 ### Data Flow Summary
 
 ```
-Drive (raw assets) → CLI (pull + convert) → Local Git (text + chunks) → Backend API → Pinecone
+Any git-tracked source, optionally authored via Drive:
+Drive (raw assets, optional) → CLI (pull + convert) → committed to git
+                                                              │
+                                            named in .descix/manifests/<KB>.json
+                                                              │
+                                                              ▼
+                                          descix kb corpus sync → Backend API → Pinecone
 ```
 
 ---
 
-## 2. Core Components
+## 2. Core Components (SDK internals — not a developer-facing API)
 
-All core SDK logic resides in `DeSciX_Core/descix-cli/lib/core/`.
+These modules are internal to the CLI. A developer never calls them directly; they run underneath
+the CLI verbs below.
 
-### 2.1 Hydrator (`Hydrator.js`)
+### 2.1 Hydrator
 
-**Responsibilities:**
-- Pull content from Drive to local filesystem
-- Push staging files to Drive
-- Convert files using Drive's native capabilities (PDF/Image → Google Doc → Markdown)
-- Conflict detection and resolution during hydration
+Drive-side operations, invoked by `descix drive pull` / `descix drive push`:
+- Pulls content from Drive to the local filesystem, converting Drive's native formats to Markdown
+  (PDF/DOCX/Image → temp Google Doc → Markdown export; Google Docs → direct Markdown export;
+  Sheets → CSV; plain text → downloaded as-is)
+- Pushes staging files to Drive
+- Also copies the `site`/`microservice` scaffold into an app (`descix site init` /
+  `descix microservice init`)
 
-**Key Functions:**
+### 2.2 Chunker and Syncer
 
-| Function | Description |
-|----------|-------------|
-| `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 |
-| `convertAndSave(driveFile, localDir)` | Convert and save a single file |
-
-**Drive-Native Conversion Logic:**
-1. PDF/DOCX/Images: Copy with `convert=true` → Creates temp Google Doc → Export as Markdown → Delete temp doc
-2. Google Docs: Export directly as `text/markdown`
-3. Google Sheets: Export as `text/csv`
-4. Plain text files: Download as-is
-
-### 2.2 Chunker (`Chunker.js`)
-
-**Responsibilities:**
-- Chunk documents for RAG embedding
-- Support multiple chunking strategies (semantic, sliding window)
-- Generate chunk records with metadata for Pinecone
-
-**Key Functions:**
-
-| Function | Description |
-|----------|-------------|
-| `categorizeFile(fileName, mimeType)` | Detect file type (code/docs/papers/generic) |
-| `chunkFile(fileInfo, options)` | Chunk a file based on its type |
-| `chunkDocument(content, metadata, rules)` | Markdown-aware section-based chunking |
-| `processKb(config, options)` | Process entire KB directory into chunks |
-| `loadChunks(config)` | Load all chunks from JSON files |
-
-**Chunking Parameters (defaults):**
-- `maxChunkSize`: 2000 characters
-- `maxCodeFileSize`: 8000 characters
-- `overlapSize`: 500 characters
-
-**Chunking Strategies:**
-- **Documents:** Split by Markdown headers (`#`, `##`, `###`) with overlap
-- **Code:** Split by logical boundaries (functions, classes, contracts)
-- **Generic:** Sliding window with overlap
-
-### 2.3 Syncer (`Syncer.js`)
-
-**Responsibilities:**
-- Sync local chunks to Pinecone via backend API
-- Compute delta between local and remote chunks
-- Manage chunk lifecycle (upsert/delete)
-
-**Key Functions:**
-
-| Function | Description |
-|----------|-------------|
-| `syncKb(apiClient, config, options)` | Full sync workflow (delta + upsert + delete) |
-| `computeChunkDelta(localChunks, remoteIds)` | Compare local vs remote chunks |
-| `getRemoteChunkIds(apiClient, communityId, appId, kbId)` | Get existing chunk IDs from Pinecone |
-| `upsertChunks(apiClient, ...)` | Push chunks to backend |
-| `deleteStaleChunks(apiClient, ...)` | Remove deleted chunks |
-| `getSyncStatus(apiClient, config)` | Check sync state |
-
-**Security Note:** The CLI never communicates with Pinecone directly. All chunk operations go through the backend API, which validates metadata and manages Pinecone credentials.
+Invoked by `descix kb corpus sync`, never called separately: chunk documents (Markdown-aware
+section splitting, with a code-aware and a generic sliding-window strategy for non-Markdown files),
+then upsert/delete against Pinecone via the backend API — computing the delta between what the
+manifest's git walk found and what is already indexed. **The CLI never communicates with Pinecone
+directly.** All chunk operations go through the backend API, which validates metadata and manages
+Pinecone credentials.
 
 ---
 
@@ -112,15 +74,15 @@ All core SDK logic resides in `DeSciX_Core/descix-cli/lib/core/`.
 │   ├── icon.png
 │   ├── app_description.md
 │   └── system_instructions.md
-├── kb/
-│   ├── staging/                # Local files to push to Drive
+├── .descix/
+│   └── manifests/
+│       └── General.json        # Corpus manifest — names the KB's git-tracked sources
+├── kb/                          # OPTIONAL — content can live anywhere; kb/ is a common convention
+│   ├── staging/                # (if using Drive) Local files to push to Drive
 │   │   └── research.pdf
-│   ├── General/                # Text-converted mirror of Drive
-│   │   ├── research.md         # Converted from PDF
-│   │   └── notes.md            # Converted from Google Doc
-│   └── chunks/                 # Processed JSON chunks (Git-tracked)
-│       ├── research.chunks.json
-│       └── notes.chunks.json
+│   └── General/                # (if using Drive) Text-converted mirror of Drive
+│       ├── research.md         # Converted from PDF
+│       └── notes.md            # Converted from Google Doc
 ├── site/                       # Static site files (push-only)
 │   ├── index.html
 │   └── DeSciXAppSDK.js         # The DeSciX bridge (generated)
@@ -129,14 +91,17 @@ All core SDK logic resides in `DeSciX_Core/descix-cli/lib/core/`.
     └── services/               # Service code — there is no src/
 ```
 
+Chunking happens in memory during `descix kb corpus sync` — there is no persisted `kb/chunks/`
+folder of JSON chunk files to manage.
+
 ### Folder Purposes
 
 | Folder | Sync Direction | Purpose |
 |--------|----------------|---------|
 | `assets/` | Bidirectional | App metadata (icon, description, instructions) |
-| `kb/staging/` | Local → Drive | Raw files waiting to be pushed |
-| `kb/General/` | Drive → Local | Text-converted files from Drive |
-| `kb/chunks/` | Local only | JSON chunk files for Pinecone sync |
+| `.descix/manifests/<KB>.json` | Local, git-tracked | Names the sources `descix kb corpus sync` walks — REQUIRED for a KB to sync |
+| `kb/staging/` | Local → Drive (optional) | Raw files waiting to be pushed via `descix drive push` |
+| `kb/General/` | Drive → Local (optional) | Text-converted files from `descix drive pull` |
 | `site/` | Local → GCS | Static site deployment |
 | `microservice/` | Local → GCS | Backend service deployment |
 
@@ -206,8 +171,7 @@ The DeSciX CLI publishes content with one verb per plane. Each command resolves
 | `descix site upload` | Deploy site to GCS |
 | `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 |
+| `descix microservice register -r SERVICE_README.md` | Register microservice AND vectorize the README for `tell_me_how` discovery, in one step |
 
 **Note:** Site and microservice commands are Git-based code operations. Drive templates contain content (assets, KB), while site/microservice commands handle code (HTML, JS, Dockerfile, etc.).
 
@@ -284,47 +248,49 @@ CLI → kb_sync_chunks API → pineconeService.upsertChunkRecords() → Pinecone
 
 ## 6. Data Flows
 
-### Push-Pull-Convert Cycle
+### Publish Cycle
 
 ```mermaid
 flowchart LR
-    subgraph local [Local Filesystem]
-        staging[kb/staging/]
-        general[kb/General/]
-        chunks[kb/chunks/]
+    subgraph drive [Google Drive — optional authoring]
+        driveKb[Drive folder]
     end
-    
-    subgraph drive [Google Drive]
-        driveKb[kb/General/]
+
+    subgraph local [Local Git repo]
+        staging[kb/staging/ — optional]
+        docs[docs (or any git-tracked path)]
+        manifest[".descix/manifests/&lt;KB&gt;.json"]
     end
-    
+
     subgraph backend [Backend]
         api[kb_sync_chunks]
         pinecone[Pinecone]
     end
-    
-    staging -->|"kb push"| driveKb
-    driveKb -->|"kb pull (convert)"| general
-    general -->|"kb chunk"| chunks
-    chunks -->|"kb sync"| api
+
+    staging -->|"descix drive push"| driveKb
+    driveKb -->|"descix drive pull (convert)"| docs
+    docs -->|"named as a source in"| manifest
+    manifest -->|"descix kb corpus sync (walk + chunk in memory + upsert)"| api
     api --> pinecone
 ```
 
 ### Detailed Flow
 
-1. **Stage:** User adds `paper.pdf` to `kb/staging/`
-2. **Push:** `descix drive push` uploads to Drive `kb/General/`
-3. **Pull:** `descix drive pull` downloads and converts:
+1. **(Optional) Stage:** User adds `paper.pdf` to `kb/staging/`
+2. **(Optional) Push:** `descix drive push` uploads to a Drive folder
+3. **(Optional) Pull:** `descix drive pull` downloads and converts:
    - Sees `paper.pdf` in Drive
    - Copies with `convert=true` → temp Google Doc
-   - Exports as Markdown → `kb/General/paper.md`
+   - Exports as Markdown → local `paper.md`
    - Deletes temp doc
-4. **Chunk:** `descix kb corpus sync` processes `paper.md`:
-   - Generates `kb/chunks/paper.chunks.json`
-5. **Sync:** `descix kb corpus sync` pushes to backend:
-   - Backend validates metadata
-   - Forwards to Pinecone
-   - Pinecone embeds and stores
+4. **Commit + name:** commit `paper.md` and name its folder as a source in
+   `.descix/manifests/<KB>.json` (skip steps 1-3 entirely if the content already lives in git —
+   Drive is optional)
+5. **Sync:** `descix kb corpus sync` does the rest in one pass:
+   - Walks the manifest's sources at a git ref, chunking each file in memory (nothing is written
+     to disk)
+   - Pushes changed chunks to the backend, which validates metadata and forwards to Pinecone
+   - Purges any chunk that is live in Pinecone but no longer in the manifest's walk
 
 ---
 
@@ -352,49 +318,20 @@ CLI authenticates to backend via device login:
 
 ---
 
-## 8. Migration Notes
-
-### From `kb/src/` to `kb/staging/`
-
-The v2 architecture renamed `kb/src/` to `kb/staging/` for clarity. The Hydrator includes automatic migration:
-
-```javascript
-// If old kb/src/ exists, rename to kb/staging/
-const oldSrcDir = path.join(kbBaseDir, 'src');
-if (await exists(oldSrcDir)) {
-  await rename(oldSrcDir, stagingDir);
-}
-```
-
-### Git Mode vs Drive Mode
+## 8. Git Mode vs Drive Mode
 
 Apps operate in one of two modes, determined by how they are managed:
 
 | Mode | Source of Truth | Versioning | User Type | Tool |
 |------|-----------------|------------|-----------|------|
-| **git** | Local Git repo | Git | Developers | CLI (`descix kb *`) |
+| **git** | Local Git repo | Git | Developers | CLI (`descix kb corpus sync`, `descix drive pull/push`) |
 | **drive** | Google Drive | GCS/Firestore | Non-developers | PWA only |
 
 **Important:** The CLI only supports **git-mode** operations. Drive-mode apps are managed entirely through the PWA with server-side processing. There is no CLI flag to switch modes - if you're using the CLI, you're in git-mode.
 
-Both modes start with content on Google Drive (users create documents there). The difference is:
-- **Git mode**: Developer pulls content from Drive, then manages text/chunks locally with Git
-- **Drive mode**: PWA triggers server-side pipeline (Drive → GCS → Pinecone) automatically
-
----
-
-## 9. File References
-
-| Component | Path | Description |
-|-----------|------|-------------|
-| WorkspaceConfig | `DeSciX_Core/descix-cli/lib/workspace-config.js` | Sole configuration class |
-| GlobalConfig | `DeSciX_Core/descix-cli/lib/global-config.js` | User-level settings (~/.descix) |
-| Hydrator | `DeSciX_Core/descix-cli/lib/core/Hydrator.js` | Drive sync operations |
-| Chunker | `DeSciX_Core/descix-cli/lib/core/Chunker.js` | KB chunking |
-| Syncer | `DeSciX_Core/descix-cli/lib/core/Syncer.js` | Pinecone sync |
-| KB Commands | `DeSciX_Core/descix-cli/lib/commands/kb.js` | Git-mode KB processing |
-| Setup Command | `DeSciX_Core/descix-cli/lib/wizard/setup.js` | Initial workspace setup |
-| Drive ADC | `DeSciX_Core/descix-cli/lib/google-storage-adc.js` | Google Drive API wrapper |
-| Backend KB API | `DeSciX_Cloud/microservice/services/commandHandlers/appCommands.js` | Server-side processing |
-| Pinecone Service | `DeSciX_Cloud/microservice/services/pineconeService.js` | Vector database |
-| Server Chunking | `DeSciX_Cloud/microservice/services/chunkingUtils.js` | Drive-mode chunking |
+Git mode does not require Drive at all: content can be authored directly in the repo. Drive is one
+optional way to bring raw content (PDFs, images) in as converted Markdown, via `descix drive pull`.
+- **Git mode**: developer commits content (optionally pulled from Drive first), names it in a
+  corpus manifest, and `descix kb corpus sync` publishes it
+- **Drive mode**: PWA triggers a server-side pipeline (Drive → GCS → Pinecone) automatically; the
+  CLI never triggers it

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

@@ -169,9 +169,11 @@ the survey outranks the paper for exactly the reader who does not yet know the p
 
 **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.
+(`descix config set-env dev --url https://localhost:4000`, or `env.apiUrl` direct). **This is
+platform-dev mode** — running your own local backend (Scenario 2 below), not part of standard app
+development, which targets a hosted environment (`descix config set-env dev` with no `--url`, or
+`demo`/`prod`). 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:
@@ -250,83 +252,3 @@ human it is unverified.
 *   **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.