@descix/cli 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# DeSciX CLI
+
+The official command-line interface for the DeSciX platform.
+
+## Installation
+
+```bash
+npm install -g @descix/cli
+```
+
+## Quick Start
+
+1.  **Login to DeSciX**:
+    ```bash
+    descix login
+    ```
+
+2.  **Setup your workspace**:
+    ```bash
+    descix setup
+    ```
+    This will guide you through connecting your Google Drive and setting up your local environment.
+
+    **Development Mode**:
+    If you are developing locally or against a test environment, you can use the `--dev` flag:
+    ```bash
+    npx descix setup --dev
+    ```
+    This defaults to `https://localhost:4000` unless configured otherwise.
+
+3.  **Check your status**:
+    ```bash
+    descix status
+    ```
+
+## Workspace Modes
+
+The CLI supports three workspace modes to accommodate different development needs:
+
+### 1. Single App Mode (`single_app`)
+Best for individual developers working on one app.
+- **Structure**: The root folder is your app folder.
+- **Drive Path**: `{community_id}/{app_id}/`
+
+### 2. Single Community Mode (`single_community`)
+Best for teams managing multiple apps within one community.
+- **Structure**: The root folder is the community folder, containing subfolders for each app.
+- **Drive Path**: `{community_id}/`
+
+### 3. Multi-Community Mode (`multi_community`)
+Best for platform admins or agencies managing multiple communities.
+- **Structure**: The root folder contains subfolders for each community.
+- **Drive Path**: `/` (Root of your base folder)
+
+## 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).
+
+## Knowledge Base Management (Git Mode)
+
+For apps managed via CLI (Git Mode), use the following commands to process your Knowledge Base locally:
+
+1.  **Pull**: Fetch source documents from Drive.
+    ```bash
+    descix kb pull
+    ```
+2.  **Chunk**: Process documents into chunks locally.
+    ```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
+    ```
+
+## Provisioning
+
+**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.
+
+1.  Create your App in the PWA (Workspace Builder).
+2.  Run `descix setup` to hydrate your local folder structure.
+
+## Documentation
+
+For full documentation, please refer to the [DeSciX SDK Documentation](../../SERVICE_README_sdk.md).

package/SERVICE_README_sdk.md

@@ -0,0 +1,399 @@
+# DeSciX SDK - CLI and MCP Tools
+
+## Overview
+
+The DeSciX SDK provides command-line tools and MCP (Model Context Protocol) integration for building applications on the DeSciX platform. The SDK enables developers to authenticate, manage workspaces, create apps, and leverage AI-assisted development through Cursor IDE integration.
+
+**Key capabilities:**
+- CLI commands for all platform operations
+- MCP server for Cursor IDE integration
+- Intelligent tool discovery via `tell_me_how`
+- Entitlements-driven workspace setup
+- Git-aware project initialization
+
+---
+
+## Installation
+
+```bash
+# Global install (recommended)
+npm install -g @descix/cli
+
+# Or via npm link during development
+cd DeSciX_Core/descix-cli
+npm link
+```
+
+---
+
+## CLI Commands
+
+### descix setup
+
+**Description:** One-time workspace configuration wizard
+**Use when:** First time setting up DeSciX in a new workspace or Cursor project
+**What it does:**
+1. Prompts for API endpoint (production/local/custom)
+2. Runs device authentication (opens browser)
+3. Creates `.cursor/mcp.json` for MCP server
+4. Creates `.cursor/rules/descix_mcp.mdc` for AI agent instructions
+5. Creates `.descix/workspace.json` with initial configuration
+
+**Example:**
+```bash
+cd ~/Projects/MyApp
+descix setup
+# Follow the prompts
+# Restart Cursor after completion
+```
+
+---
+
+### descix login
+
+**Description:** Authenticate with the DeSciX platform
+**Use when:** Session expired or first-time authentication
+**Options:**
+- `--device` (default): Opens browser for Powch authentication
+- `--wallet`: Direct wallet signature authentication
+
+**Example:**
+```bash
+descix login
+# Opens browser, complete authentication
+# Credentials saved to .descix/wallet.json
+```
+
+---
+
+### descix whoami
+
+**Description:** Display current authentication status
+**Use when:** Checking if you're logged in and what account you're using
+
+**Example:**
+```bash
+descix whoami
+# Output:
+# User: sam@descix.net
+# Wallet: 0xe71b412d...
+# Session: Valid
+```
+
+---
+
+### descix tell-me-how
+
+**Description:** Discover platform tools using natural language
+**Use when:** You don't know which command to use for a task
+
+**Options:**
+- `--scope project`: Search within current workspace apps
+- `--scope entitlements`: Search apps you have access to (default)
+- `--scope discovery`: Search all platform tools
+- `--json`: Output raw JSON response
+
+**Examples:**
+```bash
+# Find how to create an app
+descix tell-me-how "How do I create a new app?"
+
+# Search within current project
+descix tell-me-how --scope project "How do I sync my knowledge base?"
+
+# Discover all available tools
+descix tell-me-how --scope discovery "What AI training tools exist?"
+```
+
+---
+
+### descix app create
+
+**Description:** Create or hydrate an app using the interactive wizard
+**Use when:** Starting a new project or hydrating an existing app
+**Options:**
+- `-c, --community <id>`: Community ID
+- `-a, --app <name>`: App name
+- `--wizard`: Interactive wizard mode
+- `--quick`: Skip optional prompts
+
+**Note:** New apps should primarily be provisioned via the PWA. This command can hydrate a local workspace from an existing app or create a skeleton if permitted.
+
+**Example:**
+```bash
+# Interactive wizard
+descix app create --wizard
+```
+
+---
+
+### descix kb
+
+**Description:** Manage Knowledge Base content (Git Mode)
+**Use when:** Processing KB documents locally
+
+**Subcommands:**
+- `pull`: Download source documents from Drive to `kb/src/`
+- `chunk`: Process source files into chunks in `kb/chunks/`
+- `sync`: Push chunks to the platform (Pinecone)
+- `build`: Run the full pipeline (Pull -> Chunk -> Sync)
+
+**Example:**
+```bash
+# Full build pipeline
+descix kb build -c descix -a myapp
+```
+
+---
+
+### descix microservice vectorize
+
+**Description:** Vectorize a SERVICE_README for tell_me_how discovery
+**Use when:** Adding or updating service documentation
+**Options:**
+- `-n, --name <name>`: Service name
+- `-c, --community <id>`: Community ID
+- `-a, --app <id>`: App ID
+- `-r, --readme <path>`: Path to README file
+
+**Example:**
+```bash
+descix microservice vectorize -r ./SERVICE_README_myservice.md
+```
+
+---
+
+### descix purchases
+
+**Description:** List your entitlements (communities, apps, service slots)
+**Use when:** Checking what resources you have access to
+
+**Example:**
+```bash
+descix purchases
+# Output shows communities, apps, and service slots
+```
+
+---
+
+## MCP Tools (for Cursor AI)
+
+After running `descix setup` and restarting Cursor, these MCP tools are available to the AI agent:
+
+### tell_me_how
+
+**Description:** Primary discovery tool - finds relevant commands for any task
+**Use first:** Always use this before attempting platform operations
+
+```javascript
+tell_me_how({ 
+  question: "How do I deploy my app?",
+  scope: "entitlements"
+})
+```
+
+**Scope options:**
+- `project`: Uses `.descix/workspace.json` mappings
+- `entitlements`: Only tools you have access to (default)
+- `discovery`: All platform tools (may require purchase)
+
+---
+
+### execute_remote_command
+
+**Description:** Execute any backend command discovered via tell_me_how
+**Use after:** tell_me_how returns recommended commands
+
+```javascript
+execute_remote_command({
+  command: "create_app",
+  params: {
+    community_id: "descix",
+    app_name: "My New App"
+  }
+})
+```
+
+---
+
+### descix_init
+
+**Description:** Initialize a local project for DeSciX deployment
+**Use when:** Setting up a new project folder
+
+```javascript
+descix_init({
+  projectPath: "/Users/dev/Projects/MyApp",
+  appName: "my-app",
+  communityId: "descix"
+})
+```
+
+**Creates:**
+- `.descix/workspace.json` or `.descix/context.json`
+- `app_description.md` from README if missing
+- Folder structure for knowledge base
+
+---
+
+### descix_wizard_step
+
+**Description:** Execute multi-step wizard workflows
+**Use when:** Creating apps, communities, or complex operations
+
+```javascript
+descix_wizard_step({
+  wizard_type: "create_app",
+  step: "init",
+  params: {
+    community_id: "descix",
+    app_name: "My App"
+  }
+})
+```
+
+**Wizard types:**
+- `create_app`: App creation with folder setup
+- `create_community`: Community creation with token
+- `publish_kb`: Knowledge base sync and publish
+
+---
+
+### git_sync_ops
+
+**Description:** Git operations with auto-generated commit messages
+**Use when:** Committing changes, checking status
+
+```javascript
+git_sync_ops({
+  operation: "status",  // or "commit", "diff", "sync_info"
+  projectPath: "/Users/dev/Projects/MyApp"
+})
+```
+
+---
+
+### search_knowledge_base
+
+**Description:** Search a specific knowledge base via RAG
+**Use when:** You know the exact KB to search
+
+```javascript
+search_knowledge_base({
+  communityId: "descix",
+  appId: "docs",
+  kbId: "sdk",
+  query: "How do I authenticate?"
+})
+```
+
+---
+
+### chat_with_kb
+
+**Description:** Conversational RAG with knowledge base context
+**Use when:** Complex questions requiring AI reasoning
+
+```javascript
+chat_with_kb({
+  communityId: "descix",
+  appId: "docs",
+  kbId: "sdk",
+  message: "Explain the authentication flow step by step"
+})
+```
+
+---
+
+## Workspace Configuration
+
+### workspace.json (Monorepo)
+
+For multi-app workspaces, create `.descix/workspace.json`:
+
+```json
+{
+  "version": "2.0",
+  "primaryCommunity": "descix",
+  "directoryMappings": {
+    "frontend": { "communityId": "descix", "appId": "pwa", "kbId": "General" },
+    "backend": { "communityId": "descix", "appId": "cloud", "kbId": "General" },
+    "docs": { "communityId": "descix", "appId": "docs", "kbId": "sdk" }
+  },
+  "defaultContext": {
+    "communityId": "descix",
+    "appId": "docs",
+    "kbId": "sdk"
+  }
+}
+```
+
+### context.json (Single App)
+
+For individual app folders, create `.descix/context.json`:
+
+```json
+{
+  "version": "2.0",
+  "type": "app",
+  "community_id": "descix",
+  "app_id": "myapp",
+  "app_name": "My Application",
+  "folders": {
+    "app": { "local_path": ".", "sync_type": "assets" },
+    "kb": { "local_path": "docs", "sync_type": "rag" }
+  }
+}
+```
+
+---
+
+## Common Workflows
+
+### New Developer Onboarding (Cursor IDE)
+
+1. Install CLI: `npm install -g @descix/cli`
+2. Run setup: `descix setup`
+3. Restart Cursor (Cmd+Shift+P → "Reload Window")
+4. AI agent can now use MCP tools
+5. Ask: "How do I create an app?"
+6. AI uses `tell_me_how` → `execute_remote_command`
+
+### Entitlements-First App Creation
+
+1. AI calls `execute_remote_command({ command: "fetch_my_purchases" })`
+2. AI presents user's communities and apps
+3. User selects community (or creates new)
+4. AI calls `descix_wizard_step` for app creation
+5. AI creates local `.descix/context.json`
+
+### Monorepo Setup
+
+1. AI calls `fetch_my_purchases` to get entitlements
+2. AI scans workspace folders
+3. AI asks user: "Map `frontend/` to which app?"
+4. AI creates `.descix/workspace.json` with mappings
+5. `tell_me_how --scope project` now uses these mappings
+
+---
+
+## Troubleshooting
+
+### "MCP tools not available"
+1. Run `descix setup` in workspace root
+2. Restart Cursor completely
+3. Check `.cursor/mcp.json` exists with `descix` server
+
+### "Session expired"
+Run `descix reconnect` or `descix login`
+
+### "No results from tell_me_how"
+Service READMEs may not be vectorized. Ask admin to run `descix microservice vectorize` for relevant services.
+
+### "workspace.json not found" for project scope
+Run `descix init` or let AI create workspace.json via `descix_init` MCP tool.
+
+---
+
+*SDK Version: 2.0.0*
+*Package: @descix/cli*

package/agent-assets/guides/README.md

@@ -0,0 +1,61 @@
+# App Pattern Guides
+
+These guides describe the four app packaging patterns in DeSciX. Use them to help users choose the right architecture for their needs.
+
+## Patterns Overview
+
+| Pattern | Description | Public URL | MCP Tools |
+|---------|-------------|------------|-----------|
+| [Knowledge-Only](./knowledge-only-pattern.md) | RAG-indexed docs, no UI | No | No |
+| [Static Site](./static-site-pattern.md) | HTML/CSS/JS + RAG docs | Yes | No |
+| [Microservice](./microservice-pattern.md) | Backend service + MCP tools | Yes | Yes |
+| [Dynamic Site](./dynamic-site-pattern.md) | SSR app + MCP tools | Yes | Yes |
+
+## Decision Tree
+
+```
+Does the user need a public website?
+│
+├── NO → Knowledge-Only
+│
+└── YES → Does it have backend logic?
+    │
+    ├── NO → Static Site
+    │
+    └── YES → Does it need SSR?
+        │
+        ├── NO → Microservice
+        │
+        └── YES → Dynamic Site
+```
+
+## Quick Reference
+
+### Knowledge-Only
+- Just docs/content for RAG search
+- No `site/` or `microservice/` folders needed
+- Commands: `descix kb pull/push/chunk/sync`
+
+### Static Site
+- Built HTML/CSS/JS deployed to CDN
+- Add `site/` folder with `descix site init`
+- Commands: `descix site upload`
+
+### Microservice
+- Backend service with MCP-exposed commands
+- Add `microservice/` folder with `descix microservice init`
+- Commands: `descix microservice register/vectorize`
+
+### Dynamic Site
+- SSR app where microservice serves the site
+- Everything in `microservice/` (no separate `site/`)
+- Commands: `descix deploy service`
+
+## Two-Tier Template System
+
+All patterns use the same two-tier template approach:
+
+1. **Drive Templates** - Content (assets, KB) synced to/from Google Drive
+2. **Git Scaffolds** - Code (site, microservice) copied from SDK templates
+
+See [templates/drive/](../../templates/drive/) and [templates/scaffolds/](../../templates/scaffolds/) for the actual templates.

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

@@ -0,0 +1,125 @@
+# Dynamic Site App Pattern
+
+## Overview
+
+A Dynamic Site app is a server-rendered application where the microservice handles both API and HTML rendering (SSR).
+
+## When to Use
+
+Choose this pattern when the user wants to:
+- Build a full web application with server-side rendering
+- Create apps requiring real-time server logic
+- Implement multi-tenant platforms
+- Build complex apps where client-side isn't sufficient
+
+**Key Questions:**
+1. "Does it need server-side rendering?" → Yes
+2. "Is the site content dynamically generated?" → Yes
+
+## Structure
+
+```
+my-dynamic-app/
+├── assets/
+│   ├── app_description.md
+│   ├── icon.png
+│   └── system_instructions.md
+├── kb/
+│   ├── staging/
+│   ├── General/
+│   │   ├── README.md
+│   │   └── user-guide.md
+│   └── chunks/
+├── site/
+│   └── README.md               # "Site served by microservice"
+├── microservice/
+│   ├── manifest.json
+│   ├── SERVICE_README_myapp.md
+│   ├── package.json
+│   ├── Dockerfile
+│   ├── app.yaml
+│   └── src/
+│       ├── index.js
+│       ├── pages/              # SSR routes
+│       │   ├── index.js
+│       │   └── dashboard.js
+│       ├── api/                # API routes
+│       │   └── ...
+│       └── views/              # Templates
+│           └── ...
+└── package.json
+```
+
+## Configuration (`workspace.json`)
+
+```json
+{
+  "communities": {
+    "my-community": {
+      "apps": {
+        "my-dynamic-app": {
+          "localPath": "my-community/my-dynamic-app",
+          "sync_mode": "git",
+          "service": {
+            "port": 4000,
+            "devCommand": "npm run dev"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI Workflow
+
+```bash
+# 1. Create microservice scaffold
+descix microservice init
+
+# 2. Add SSR routes to your service
+
+# 3. Deploy to Cloud Run
+descix deploy service
+
+# 4. Register and vectorize
+descix microservice register
+descix microservice vectorize
+
+# 5. Sync KB
+descix kb sync -c <community> -a <app>
+```
+
+## Capabilities
+
+| Capability | Enabled |
+|------------|---------|
+| RAG search | Yes |
+| chat_with_kb | Yes |
+| Public URL | Yes |
+| MCP tools | Yes |
+| tell_me_how discovery | Yes |
+| SSR/Dynamic content | Yes |
+
+## Key Differences from Static + Microservice
+
+1. **No separate site deployment** - The microservice serves the site
+2. **SSR routes** - HTML generated on the server per request
+3. **Single deployment** - Everything deploys together to Cloud Run
+4. **Real-time capabilities** - WebSockets, streaming, etc.
+
+## Example Use Cases
+
+1. **Dashboard App** - Admin panel with real-time data
+2. **Multi-tenant Platform** - Each user sees personalized content
+3. **Streaming App** - Real-time data visualization
+4. **Complex Web App** - E-commerce, social platforms
+
+## Deployment
+
+Dynamic sites deploy to Google Cloud Run as a single container. The service handles both API requests and page rendering.
+
+```bash
+# Deploy the microservice (includes site)
+descix deploy service
+```