@descix/cli 1.0.6 → 1.0.7

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

@@ -61,25 +61,21 @@ 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

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/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,33 +146,30 @@ 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.
 
 ---
@@ -191,7 +188,7 @@ These commands auto-detect app context from `workspace.json` based on the curren
 | `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`. |
+| `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`)
 
@@ -256,15 +253,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",

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

@@ -71,7 +71,7 @@ All MCP calls include a `_descix` context object for identity propagation:
     expires_at: "..."
   },
   workspace: {
-    community_id: "descix",
+    community_id: "daita",
     app_id: "agent"
   }
 }
@@ -224,7 +224,7 @@ const plan = await tell_me_how({
 const result = await execute_remote_command({
   command: plan.recommended_tools[0].name,
   params: {
-    community_id: "descix",
+    community_id: "daita",
     app_id: "agent",
     kb_id: "General"
   }
@@ -241,19 +241,13 @@ const result = await execute_remote_command({
 descix mcp quickstart
        │
        ▼
-   Prerequisites Check (gcloud, ADC)
+   Requires a prior `descix login` (refuses and names it otherwise)
        │
        ▼
-   Device Login (browser)
+   Setup wizard (lib/wizard/setup.js)
        │
        ▼
-   Workspace Builder (PWA)
-       │
-       ▼
-   Hydration (Hydrator module)
-       │
-       ▼
-   Credentials Saved (.descix/wallet.json)
+   .cursor/rules/descix_mcp.mdc deployed
        │
        ▼
    ✓ Ready for agent interaction
@@ -290,18 +284,17 @@ When `--scope project` is used:
 4. Returns focused recommendations
 
 ```javascript
-// workspace.json
+// workspace.json (v2.1)
 {
-  "communities": {
-    "descix": {
-      "apps": {
-        "agent": { "localPath": ".", "sync_mode": "git" }
-      }
-    }
+  "env": {
+    "apiUrl": "https://dev.descix.net",
+    "products": [
+      { "appId": "daita-agent", "communityId": "daita", "localPath": ".", "kbId": "General" }
+    ]
   }
 }
 
-// tell_me_how with project scope only searches within descix/agent
+// tell_me_how with project scope only searches within daita-agent
 ```
 
 ---
@@ -319,12 +312,11 @@ descix tell-me-how "How do I sync my knowledge base?"
 
 ### 6.2 workspace.json from Hydration
 
-The `Hydrator` module creates `workspace.json` during setup:
+`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`:
 
 ```javascript
-// Created by Hydrator.hydrateWorkspace()
 {
-  "communities": { ... },
+  "env": { "apiUrl": "https://dev.descix.net", "products": [ /* one entry per app */ ] },
   "driveConfig": {
     "base_folder_id": "..."  // For tell_me_how project scope
   }