@descix/cli 1.0.5 → 1.0.7

package/README.md

@@ -15,11 +15,12 @@ npm install -g @descix/cli
     descix login
     ```
 
-2.  **Setup your workspace**:
+2.  **Initialize your workspace**:
     ```bash
-    descix setup
+    descix init
     ```
-    This will guide you through connecting your Google Drive and setting up your local environment.
+    This writes `.descix/workspace.json` for the current project. Pass `-c <community_id> -a <app_id>`
+    to pre-fill the app context, or `--from-invite <token>` to resolve an invite token.
 
     **Choosing an environment**:
     The `--dev` flag has been REMOVED. Its absence silently meant production, so the most common
@@ -58,40 +59,129 @@ Best for platform admins or agencies managing multiple communities.
 ## Core Commands
 
 - `descix login`: Authenticate with the platform.
-- `descix setup`: Initialize or repair your workspace configuration.
 - `descix status`: View your current environment status and workspace mode.
-- `descix init`: Create `.descix/workspace.json` for the current project.
-- `descix app create`: Show instructions; use `--quick -c <community> -a <name>` for template-only app creation, or use PWA / `descix-admin app create`.
-- `descix sync`: Sync content to the platform (Site, Assets).
-- `descix kb`: Manage Knowledge Base content (Pull -> Chunk -> Sync).
+- `descix init`: Initialize workspace for DeSciX app development (Git-aware) — writes `.descix/workspace.json`.
+- `descix app init`: Create (when it does not exist yet) and initialize an app — the one path to an app. See [Creating an App](#creating-an-app).
+- `descix site init` / `descix site upload`: Scaffold an app's site, then build and deploy it. See [Deploying a Site](#deploying-a-site).
+- `descix app sync-assets`: Sync local assets (`system_instructions.md`, `app_description.md`, `icon.png`) to the platform.
+- `descix drive pull` / `descix drive push`: Drive content authoring — pull from Drive to local markdown, push staging back to Drive.
+- `descix kb`: Manage Knowledge Bases (`list`, `create`, `delete`, and `corpus sync`).
 
 ## Knowledge Base Management (Git Mode)
 
-For apps managed via CLI (Git Mode), use the following commands to process your Knowledge Base locally:
+The CLI exposes exactly ONE knowledge-base sync surface: `descix kb corpus sync`, driven by a
+git-tracked corpus manifest. The older four-step local pipeline has been REMOVED — its invocations
+now exit non-zero and name this replacement.
 
-1.  **Pull**: Fetch source documents from Drive.
+1.  **Create** the knowledge base (once per KB):
     ```bash
-    descix kb pull
+    descix kb create -c <community_id> -a <app_id> -k <kb_name>
     ```
-2.  **Chunk**: Process documents into chunks locally.
+2.  **Author** a corpus manifest at `.descix/manifests/<kb_name>.json` describing the sources to sync.
+3.  **Sync** the corpus to the platform (Pinecone):
     ```bash
-    descix kb chunk
-    ```
-3.  **Sync**: Push chunks to the platform (Pinecone).
-    ```bash
-    descix kb sync
-    ```
-4.  **Build**: Run the full pipeline (Pull -> Chunk -> Sync).
-    ```bash
-    descix kb build
+    descix kb corpus sync -a <app_id> [-k <kb_name>]
     ```
+    It walks the git blobs at the manifest's ref, so only changed files are re-vectorized. Useful
+    flags: `--dry-run` (report drift, write nothing), `--show-walk` (print the resolved ref and the
+    files it would walk), `--ref <ref>` (override the git ref for all manifest sources).
+
+To fetch source documents from Google Drive into local markdown, use `descix drive pull`.
+
+## Creating an App
+
+`descix app init` is the one path to an app. It creates the app on the platform when it does not
+exist yet, then registers and scaffolds it locally — one command, not two.
+
+```bash
+descix app init -a <name> -c <community>
+```
+
+Pass `-c` to create a new app in that community. **Omit `-c` to initialize an app that already
+exists** — the CLI resolves the app from the Products registry and only does the local half.
+
+The command is idempotent, so re-running it on a half-made app finishes the job.
+
+**Options:**
+
+- `-a, --app <app_id>` (required): the app ID. With `-c`, this is the app NAME to create.
+- `-c, --community <id>`: the community to create the app in. It must already be materialized in
+  this environment. Required only for creation.
+- `-s, --short <short_name>`: the short id segment (no hyphens). The `app_id` is composed
+  **server-side** as `{community}-{short}`; defaults to `--app`.
+- `--overwrite`: when creating, overwrite an existing app record intentionally.
+- `--kb <name>`: knowledge base name (default: `General`).
+- `-p, --path <dir>`: local app directory (default: auto-detected, else the current directory).
+
+**What it does, in order:**
+
+1.  **Creates the app** (only when `-c` is given and the app does not exist): the server composes
+    the unique `app_id` and writes `Products/{app_id}` and `Community/{community}/Apps/{app_id}`.
+    Every app is guaranteed a default knowledge base at creation.
+2.  **Registers it in `.descix/workspace.json`** if it is not already mapped.
+3.  **Scaffolds the app folder**: creates `site/`, `microservice/` and `assets/`, and writes
+    `assets/system_instructions.md` and `assets/app_description.md` when they do not exist.
+4.  **Creates the knowledge base record** for Git-mode sync.
+
+It fails loud rather than guessing: initializing an app that does not exist without `-c` names the
+`-c` invocation that would create it; a `-c` that disagrees with the app's real community is
+refused; and `-p` against an already-mapped app names `descix app set-localpath` instead.
 
-## Provisioning
+**Next step** — author a corpus manifest at `.descix/manifests/<kb_name>.json`, then
+`descix kb corpus sync -a <app_id>`.
 
-**Communities and apps are created in the PWA** (Workspace Config / Device Setup / App Manager) or via **Admin CLI** (`descix-admin community create`, `descix-admin app create`) for platform admins. The user CLI does not create communities or full app structures; use `descix init` to write `.descix/workspace.json` and PWA or Admin CLI to create entities.
+Creating a **community** is a separate, admin-only operation: `descix community create` requires
+platform-admin membership and deploys a real ERC-20 token contract to live Polygon. App developers
+work inside a community that already exists.
 
-1.  Create your App in the PWA (Workspace Builder).
-2.  Run `descix setup` to hydrate your local folder structure.
+## Deploying a Site
+
+An app's site is scaffolded, then uploaded. `descix site upload` is the deploy verb — there is no
+`descix site deploy`.
+
+```bash
+descix site init      # scaffold site/ (optional — upload works on any site directory)
+descix site upload --env dev
+```
+
+### `descix site init`
+
+Copies the site scaffold — `index.html`, `app.js`, `styles.css`, `DeSciXAppSDK.js`, `README.md` —
+into the app's `site/` directory. The app must already be mapped in `.descix/workspace.json`.
+
+- `-f, --force`: overwrite an existing `site/` folder.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+It scaffolds site content only; it writes no manifest. Skip it entirely if you already have a site.
+
+### `descix site upload`
+
+Builds (when a manifest declares a build) and uploads the site to GCS, then updates the app's
+metadata. Files are uploaded straight to GCS with short-lived **signed URLs** issued by
+`get_site_deploy_token`; `confirm_site_deploy` then records the deploy and returns the site URL.
+
+- `-p, --path <localPath>`: directory to deploy (default `./site`). **Ignored when a site manifest
+  exists.**
+- `--preview`: deploy to the preview path.
+- `--full`: force a full upload, ignoring the unchanged-file delta.
+- `--dry-run`: show what would be deployed.
+- `--no-cache`: set `Cache-Control: no-cache`.
+- `-c, --community <id>` / `-a, --app <id>`: auto-detected from context when omitted.
+
+**Site deploys target a cloud environment.** An upload that resolves to a local backend without
+this invocation naming its target is refused — pass `--env <dev|demo|prod>`.
+
+**Manifest-driven builds.** When `{app_root}/.descix/manifests/site.json` exists it takes over from
+`-p`. Author it yourself; nothing generates it for you. It declares the sources to walk and,
+optionally, a `buildCommand`, which runs in the app root with the environment-specific `VITE_*`
+build variables the server returns injected into its environment:
+
+```json
+{
+  "sources": [{ "path": "site/dist", "include": ["**/*"] }],
+  "buildCommand": "npm run build --prefix site"
+}
+```
 
 ## Airdrop Admin Operations (WS-ADMIN-B1)
 
@@ -103,25 +193,31 @@ Admin-only commands for triggering airdrop migration batch runs. Per CEO-D-MANUA
 
 Manually trigger the server-side `airdrop_execute_queue` command on the target environment. Assembles `pending_migrations` rows into per-community batches and (when `BATCH_UPDATE_BALANCES_BROADCAST_ENABLED=true`) broadcasts to the Powch HD wallet. When the broadcast flag is off (default for DEV), batches are assembled but the downstream Powch handler returns `stopped_at_broadcast_boundary` — useful for verifying queue shape without spending MATIC.
 
+**Read-only is the default.** Without `--apply`, the command runs as a dry run.
+
 **Options:**
 
+- `--dry-run`: Read-only preview — encode calldata, estimate gas, validate the net-zero invariant. No PK, no transaction, no state mutation. Mutually exclusive with `--apply`.
+- `--apply`: Live execution. Requires `--signer-pk-file` or the interactive prompt, and requires `--community`.
+- `--community <slug>`: Community slug for per-community batch scoping. **Required for `--apply`**; optional in dry-run mode, where omitting it returns an aggregate preview across communities.
+- `--signer-pk-file <path>`: Path to a file containing the admin signer PK (`0x` + 64 hex). Used for `--apply`; when omitted, the PK is requested at an interactive no-echo prompt. Inline PK flags and environment variables are rejected on security grounds (process-listing leak).
 - `--batch-size <n>`: Cap on users processed this run (server caps at `AIRDROP_MAX_RUN_USERS`; a larger `--batch-size` is clamped).
-- `--dry-run`: Assemble batches but skip the broadcast call entirely. Emits an `on_chain_log` row with `status: dry_run` for audit.
 
 **Examples:**
 
 ```bash
-# Dry run against DEV — safe to run repeatedly; no broadcast, no MATIC
+# Dry run against DEV — safe to run repeatedly; no PK, no tx, no state mutation
 descix airdrop execute-queue --env dev --dry-run
 
-# Execute a capped real run (10 users max this invocation)
-descix airdrop execute-queue --env dev --batch-size 10
+# Dry run scoped to one community
+descix airdrop execute-queue --env dev --dry-run --community smile
 
-# Execute a full queue run (still gated by BATCH_UPDATE_BALANCES_BROADCAST_ENABLED)
-descix airdrop execute-queue --env dev
-```
+# Live execution, capped at 10 users this invocation (prompts for the signer PK)
+descix airdrop execute-queue --env dev --apply --community smile --batch-size 10
 
-**Audit trail:** every invocation (dry-run or real) writes one `on_chain_log` row with `op.kind = "airdrop_execute_queue_trigger"` and `caller.operator_email = <invoking admin email>`.
+# Live execution reading the signer PK from a file
+descix airdrop execute-queue --env dev --apply --community smile --signer-pk-file ./signer.key
+```
 
 **Testing:**
 
@@ -131,4 +227,4 @@ cd DeSciX_Core/descix-cli && npm test
 
 ## Documentation
 
-For full documentation, please refer to the [DeSciX SDK Documentation](../../SERVICE_README_sdk.md).
+For full documentation, please refer to the [DeSciX SDK Documentation](./SERVICE_README_sdk.md).

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 |