@descix/cli 1.0.0

package/templates/agent-cursor.md

@@ -0,0 +1,133 @@
+# DeSciX App Development
+
+<!-- BOOTSTRAP: Auto-generated. Update this file as you learn the project. -->
+
+## First Action
+
+Call `descix_doctor` MCP tool to check auth, workspace, and available tools.
+
+## Platform
+
+DeSciX is a virtual university for knowledge-powered apps. Communities are
+departments, apps are courses/textbooks/services. You are the primary
+interface — guide the user to explore, build, or discover.
+
+## Pre-Step 0: Check for Invite Config
+
+Before scanning the repo, check if `.descix/app.json` exists.
+
+If it does:
+1. Read it — extract `app_id`, `community_id`, `agent_hint`, `kb_ready`, `has_repo`
+2. If it contains `invite_token`, call `resolve_invite` with that token to get live context
+3. **Read `agent_hint` carefully** — it was written by the app creator specifically for you.
+   It describes this user's skill level and goals. Let it override default checkpoints.
+   For example, if the hint says "no coding background", do not ask technical questions.
+4. If `kb_ready` is true, skip KB setup and demonstrate value immediately:
+   `descix chat -a <app_id> "What is this about?"` — show the user what the AI knows
+5. If `kb_ready` is false, skip the chat demo — the KB is not populated yet.
+   Proceed to setup (`descix init`, `app init`, `update kb`), then demo afterward.
+   Frame it as: "Let's get this set up so you can start exploring."
+6. If `has_repo` is true and no source code is present locally, offer `descix clone -a <app_id>`.
+   For non-technical users (infer from `agent_hint`): "Want to run this on your own machine?"
+   For developers: "I'll clone the source code so you can build on it."
+7. If `app.json` contains `api_url`, use it as the backend target — skip Checkpoint 3 (environment).
+8. After the demo and clone, check if `workspace.json` exists. If not, run standard setup
+   (`descix init`, `app init`). If it does, setup is already done — proceed to development.
+9. If `descix_doctor` shows an existing workspace with a **different** `app_id` than the invite,
+   ask the user: "You have an existing workspace for [X]. Add the invited app, or switch context?"
+
+**Important:** If `app.json` is present, Step 0's empty-repo detection does NOT mean "scaffold from scratch."
+The project context comes from the invite, not the file structure.
+
+## Step 0: Scan the Repo
+
+Before asking questions, list the working directory and check for:
+- Existing content: `docs/`, `src/`, `README.md`, `package.json`
+- Existing DeSciX structure: `kb/`, `site/`, `microservice/`, `.descix/`
+- Existing frameworks: `vite.config.*`, `next.config.*`, `tsconfig.json`
+
+Tailor your questions based on what you find (e.g., offer to use existing docs
+as KB, configure an existing site, skip starter content if KB is already populated).
+
+## Setup Workflow (if doctor reports setup_needed)
+
+Ask the user at each checkpoint — don't assume:
+
+1. **Objective:** "Explore existing apps or build something new?"
+2. **Community/App:** Use `find_communities` + `list_apps_for_community`, then ask which to target
+3. **Environment:** "Local dev (localhost:4000) or hosted API?" (Skip if `app.json` has `api_url`)
+
+Canonical setup commands:
+```bash
+descix whoami                              # confirm identity
+descix app list                            # see available apps
+descix init -c <community> -a <app> -p .   # create workspace.json
+descix app init -a <app> -c <community>    # register app on platform
+```
+
+4. **Content strategy:** "Create starter KB now or wait for your docs?"
+5. **Frontend scope:** "Plain HTML or a framework (React, VitePress)?"
+
+## Important: Use Explicit Flags
+
+Always use `-c <community> -a <app>` for all commands until verified:
+```bash
+descix chat -c <community> -a <app> -q "..."
+descix update kb -c <community> -a <app>
+```
+
+## Success Criteria
+
+- App visible in `descix app list`
+- KB sync succeeds: `descix update kb -c <community> -a <app>`
+- Chat returns response: `descix chat -c <community> -a <app> -q "test"`
+
+## Local Development
+
+| Goal | Command |
+|------|---------|
+| Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
+| Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
+| Run full gateway (multi-app) | `descix serve` (reverse proxy on :5173) |
+
+Single-app dev: a static server is sufficient. Gateway is for multi-app or
+platform routing tests.
+
+## MCP Tools
+
+- `descix_doctor` — Startup diagnostic (call first)
+- `ask_question_to_app` — RAG chat with app_id `{{appId}}`
+- `query_knowledge_base` — Vector search (raw chunks)
+- `find_communities` — List communities
+- `list_apps_for_community` — List apps in a community
+- `tell_me_how` — Discover any platform capability (use scope "discovery" if "entitlements" is empty)
+- `resolve_invite` — Exchange an invite token for app context + agent hint
+
+## Integrating Existing Content
+
+**NEVER copy existing project files into `site/` or `kb/`.** Integrate in place:
+
+- **Existing HTML/JS app:** Serve as-is. Add `DeSciXAppSDK.js` for DeSciX integration.
+- **React/Vite app:** Wrap root in `<AppShell appId="{{appId}}">` from `@descix/app-sdk/AppShell`.
+- **Auth only (no DeSciX UI):** Use `PowchClient` from `@descix/app-sdk/powch-client`.
+- **Existing docs:** Copy `docs/*.md` to `kb/General/` for sync. Keep originals as source of truth.
+- **Empty repo:** Scaffold from scratch.
+
+## App Structure
+
+- `site/` — Frontend (any framework)
+- `kb/General/` — Knowledge base source docs (markdown)
+- `microservice/` — Backend service (optional)
+
+## Context
+
+- App ID: `{{appId}}` | Community: `{{communityId}}` | API: `{{apiUrl}}`
+
+## Known CLI Quirks
+
+- `descix status` may show "No workspace found" even when config exists — use explicit flags
+- `descix status` may suggest `descix setup` — use `descix init` instead
+
+## After Bootstrap
+
+Rewrite this file with project-specific context once you understand the user's intent.

package/templates/descix_mcp.mdc

@@ -0,0 +1,122 @@
+---
+alwaysApply: true
+---
+
+### DeSciX Intelligent Tool Discovery
+
+**IMPORTANT: Use `tell_me_how` before attempting any DeSciX platform operation.**
+
+The DeSciX platform uses semantic tool discovery. Instead of memorizing commands:
+1. Ask `tell_me_how` what you want to accomplish
+2. The platform finds relevant tools based on your access level
+3. Execute the recommended tools via `execute_remote_command`
+
+### Tool Discovery with Scope Control
+
+Use `tell_me_how` with appropriate scope:
+
+- **Project scope** (`--scope project`): When working within a specific project context
+  ```
+  tell_me_how({ question: "How do I sync my KB?", scope: "project" })
+  ```
+  Uses communities/apps from `.descix/workspace.json`
+
+- **Entitlements scope** (DEFAULT): When you need actionable tools you can use now
+  ```
+  tell_me_how({ question: "How do I deploy a token?" })
+  ```
+  Only returns tools from communities you're a member of and apps you own/purchased
+
+- **Discovery scope** (`--scope discovery`): When exploring platform capabilities
+  ```
+  tell_me_how({ question: "What AI training tools exist?", scope: "discovery" })
+  ```
+  Returns all tools; indicates which require purchase
+
+### Execution Pattern
+
+After `tell_me_how` returns recommended tools:
+
+```javascript
+// 1. Ask how to do something
+const plan = await tell_me_how({ 
+    question: "Create a bonding curve for my community",
+    scope: "entitlements"
+});
+
+// 2. Execute the recommended command
+await execute_remote_command({
+    command: plan.recommended_tools[0].name,
+    params: { /* parameters from plan */ }
+});
+```
+
+### Local Operations
+
+These tools run locally (no `tell_me_how` needed):
+
+- `descix_init` - Initialize project with `.descix/workspace.json`
+- `descix_wizard_step` - Multi-step wizards (app creation, etc.)
+- `git_sync_ops` - Git operations with auto-generated commit messages
+
+### Knowledge Base Queries
+
+For documentation and RAG queries, use `tell_me_how` to discover the right KB:
+
+```
+tell_me_how({ question: "Where is the SDK authentication documented?" })
+```
+
+Or query directly if you know the KB:
+
+- `search_knowledge_base` with `communityId`, `appId`, `kbId`
+- `chat_with_kb` for conversational queries
+
+### Knowledge Base References
+
+The DeSciX platform documentation is organized in the `descix/docs` app:
+
+- **sdk** - SDK documentation, CLI commands, MCP integration
+- **architecture** - Platform architecture, design patterns
+- **cloud** - Backend services, API, deployment
+- **pwa** - Frontend React components, state management
+- **contracts** - Smart contracts, token economics
+
+### Service Registration
+
+When registering a new microservice:
+
+1. **Create SERVICE_README_{app_id}.md** in the app's Drive folder
+2. Follow the template provided by `descix service register --help`
+3. The README is vectorized for `tell_me_how` discovery
+
+If the README is missing, the CLI provides AI-friendly instructions you can use directly.
+
+### Error Recovery
+
+If a command fails:
+
+1. Use `tell_me_how` to find alternative approaches
+2. Check `search_knowledge_base` for error-specific documentation
+3. Verify scope - you may need `discovery` scope to find the right tool
+
+### CLI Quick Reference
+
+```bash
+# Discover tools (primary command)
+descix tell-me-how "What you want to accomplish"
+descix tell-me-how --scope project "sync my knowledge base"
+descix tell-me-how --scope discovery "what tokenomics tools exist"
+
+# Local operations
+descix init                      # Initialize project
+descix setup                     # One-time setup
+
+# Authentication
+descix login                     # Authenticate
+descix mcp quickstart            # Full MCP setup
+```
+
+---
+
+*This rules file is deployed by `descix mcp init`. Regenerate with `descix mcp quickstart`.*

package/templates/drive/README.md

@@ -0,0 +1,42 @@
+# Drive Templates
+
+These templates are the canonical source for content that lives in Google Drive. They are uploaded to Drive and used by the backend when creating new communities and apps.
+
+## Template Structure
+
+### Community Template (`community/`)
+
+```
+community/
+├── community_assets/
+│   ├── icon.png              # 512x512 community icon
+│   └── community_description.md
+└── Apps/                     # Empty folder for apps
+```
+
+### App Template (`app/`)
+
+```
+app/
+├── assets/
+│   ├── app_description.md    # App store listing
+│   ├── system_instructions.md # AI persona definition
+│   └── icon.png              # 512x512 app icon
+└── kb/
+    └── General/
+        └── README.md         # KB starter document
+```
+
+## Usage
+
+These templates are:
+1. Uploaded to Google Drive (by admin)
+2. Referenced by folder ID in `DeSciX_Cloud/defaults-config.json`
+3. Copied by the backend when `create_community_with_app` is called
+
+**Note:** Code scaffolds (site, microservice) live in `../scaffolds/`, not here. Drive templates contain only content that syncs to/from Google Drive.
+
+## Placeholder Variables
+
+- `{{APP_NAME}}` - Replaced with the app name during creation
+- `{{COMMUNITY_NAME}}` - Replaced with the community name during creation

package/templates/drive/app/assets/app_description.md

@@ -0,0 +1,13 @@
+# {{APP_NAME}}
+
+{{APP_NAME}} is an AI-powered application on the DeSciX platform.
+
+## Overview
+
+Edit this description to explain what your app does and how users can benefit from it.
+
+## Features
+
+- AI-powered interactions via the Knowledge Base
+- Customizable system instructions
+- Extensible with microservices

package/templates/drive/app/assets/system_instructions.md

@@ -0,0 +1,17 @@
+You are the AI assistant for {{APP_NAME}}.
+
+Your role is to help users interact with this application by:
+1. Answering questions based on the Knowledge Base
+2. Providing guidance on using the app's features
+3. Assisting with tasks related to the app's domain
+
+## Guidelines
+
+- Be helpful and concise
+- Reference the Knowledge Base when answering questions
+- If you don't know something, say so clearly
+- Maintain a professional and friendly tone
+
+## Knowledge Base
+
+You have access to documents in the `kb/` folder. Use this information to provide accurate answers to user questions.

package/templates/drive/app/kb/General/README.md

@@ -0,0 +1,25 @@
+# Knowledge Base
+
+Welcome to the {{APP_NAME}} Knowledge Base.
+
+## Overview
+
+This folder contains the documents that power the AI assistant. Add your content here to make it available to users interacting with your app.
+
+## How It Works
+
+1. **Add Documents**: Upload markdown, text, or PDF files to this folder
+2. **Sync**: Use `descix kb sync` to process and vectorize your documents
+3. **Query**: Users can now ask questions and get answers based on your content
+
+## Folder Structure
+
+- `General/` - General knowledge and documentation
+- Create additional subfolders for different topics
+
+## Best Practices
+
+- Use clear, descriptive file names
+- Structure content with headers for better retrieval
+- Keep documents focused on single topics
+- Update regularly to keep information current

package/templates/drive/community/Apps/.gitkeep

@@ -0,0 +1,4 @@
+# Apps Folder
+
+This folder contains apps belonging to the community.
+Each app has its own subfolder following the agent_app_template structure.

package/templates/drive/community/community_assets/community_description.md

@@ -0,0 +1,15 @@
+# {{COMMUNITY_NAME}}
+
+Welcome to {{COMMUNITY_NAME}}!
+
+This is your community on the DeSciX platform. Edit this description to tell members about your community's purpose, goals, and what makes it unique.
+
+## About
+
+Describe your community here.
+
+## Getting Started
+
+- Join the community discussions
+- Explore available apps
+- Contribute to the knowledge base

package/templates/drive_templates/README.md

@@ -0,0 +1,104 @@
+# DeSciX Drive Templates
+
+**IMPORTANT:** These templates should be uploaded to Google Drive and are the SINGLE SOURCE OF TRUTH for creating communities and apps.
+
+## Google Drive Location
+
+**Target Folder:** https://drive.google.com/drive/folders/1AcX-YDR5mFQo1QolBgMG7KpX2cTWF0dn  
+**Owner:** dip@descix.net
+
+## Template Structure
+
+### `community_template/`
+
+The canonical folder structure for creating new communities:
+
+```
+community_template/
+├── community_assets/
+│   ├── icon.png                    # Required: 512x512 community icon
+│   └── community_description.md   # Required: Community description (placeholder)
+└── Apps/                           # Empty folder - apps are added here
+```
+
+### `agent_app_template/`
+
+The canonical folder structure for creating new agent apps:
+
+```
+agent_app_template/
+├── assets/
+│   ├── app_description.md         # Required: App description (placeholder)
+│   ├── system_instructions.md     # Required: AI persona instructions (placeholder)
+│   └── icon.png                    # Required: 512x512 app icon
+├── kb/
+│   └── General/
+│       └── README.md               # Starter KB document
+├── site/                           # Empty - for static site content
+└── microservice/                   # Empty - for backend service code
+```
+
+## How Templates Are Used
+
+### Creating a Community
+
+1. Backend calls `copyFolderRecursive(COMMUNITY_TEMPLATE_ID, userBaseFolderId, communityId)`
+2. The entire `community_template/` structure is copied to the user's folder
+3. Folder is renamed to the `community_id`
+4. Firestore `Community` document is created
+5. User can then add apps to the community
+
+### Creating an App
+
+1. Backend calls `copyFolderRecursive(AGENT_APP_TEMPLATE_ID, communityFolderId, appId)`
+2. The entire `agent_app_template/` structure is copied into the community folder
+3. Folder is renamed to the `app_id`
+4. Firestore `App` and `KnowledgeBase` documents are created
+5. User can then customize assets and add KB content
+
+## Placeholder Variables
+
+Templates contain placeholder variables that can be replaced post-copy:
+
+| Variable | Description |
+|----------|-------------|
+| `{{COMMUNITY_NAME}}` | The community's display name |
+| `{{APP_NAME}}` | The app's display name |
+
+These are NOT automatically replaced - they serve as guidance for the user to edit.
+
+## Uploading to Google Drive
+
+**Status:** ✅ Templates have been uploaded.
+
+If you need to re-upload:
+1. Upload the `community_template/` folder to the target Drive folder
+2. Upload the `agent_app_template/` folder to the target Drive folder
+3. Update folder IDs in `DeSciX_Cloud/defaults-config.json`
+
+**Note:** Default icons are already included (from `DeSciX_PWA/assets/icon.png`).
+
+## Important Notes
+
+- **Do NOT modify templates without updating all consumers**
+- **Templates are the SINGLE source for folder structure**
+- **All structure validation has been removed from the backend**
+- **If template structure is wrong, all new communities/apps will be wrong**
+
+## Configuration
+
+Template folder IDs are stored in `DeSciX_Cloud/defaults-config.json` (not secrets):
+
+```json
+"DRIVE_COMMUNITY_TEMPLATE_FOLDER_ID": "1ocVhrODQPGMICWmod3OWSGAj4-t6-o-B",
+"DRIVE_AGENT_APP_TEMPLATE_FOLDER_ID": "1ewnvtVG5hhEcRg_rcYmnGiWjTjznu8nu"
+```
+
+**Google Drive Links:**
+- Community Template: https://drive.google.com/drive/folders/1ocVhrODQPGMICWmod3OWSGAj4-t6-o-B
+- Agent App Template: https://drive.google.com/drive/folders/1ewnvtVG5hhEcRg_rcYmnGiWjTjznu8nu
+
+## Related Documentation
+
+- [Template-Based Creation Consolidation](../../../design/proposed/template-based-creation-consolidation.md)
+- [Standard Folder Structure](../../agent-assets/instructions/standard-folder-structure.md)

package/templates/drive_templates/agent_app_template/assets/app_description.txt

@@ -0,0 +1,13 @@
+# {{APP_NAME}}
+
+{{APP_NAME}} is an AI-powered application on the DeSciX platform.
+
+## Overview
+
+Edit this description to explain what your app does and how users can benefit from it.
+
+## Features
+
+- AI-powered interactions via the Knowledge Base
+- Customizable system instructions
+- Extensible with microservices

package/templates/drive_templates/agent_app_template/assets/system_instructions.txt

@@ -0,0 +1,17 @@
+You are the AI assistant for {{APP_NAME}}.
+
+Your role is to help users interact with this application by:
+1. Answering questions based on the Knowledge Base
+2. Providing guidance on using the app's features
+3. Assisting with tasks related to the app's domain
+
+## Guidelines
+
+- Be helpful and concise
+- Reference the Knowledge Base when answering questions
+- If you don't know something, say so clearly
+- Maintain a professional and friendly tone
+
+## Knowledge Base
+
+You have access to documents in the `kb/` folder. Use this information to provide accurate answers to user questions.

package/templates/drive_templates/agent_app_template/kb/General/README.md

@@ -0,0 +1,25 @@
+# Knowledge Base
+
+Welcome to the {{APP_NAME}} Knowledge Base.
+
+## Overview
+
+This folder contains the documents that power the AI assistant. Add your content here to make it available to users interacting with your app.
+
+## How It Works
+
+1. **Add Documents**: Upload markdown, text, or PDF files to this folder
+2. **Sync**: Use `descix kb sync` to process and vectorize your documents
+3. **Query**: Users can now ask questions and get answers based on your content
+
+## Folder Structure
+
+- `General/` - General knowledge and documentation
+- Create additional subfolders for different topics
+
+## Best Practices
+
+- Use clear, descriptive file names
+- Structure content with headers for better retrieval
+- Keep documents focused on single topics
+- Update regularly to keep information current

package/templates/drive_templates/agent_app_template/microservice/.gitkeep

@@ -0,0 +1,10 @@
+# Microservice Folder
+
+This folder contains the backend service code for the app.
+Typically includes:
+- Dockerfile
+- package.json
+- src/index.js
+- Service manifest
+
+Use the service template from packages/descix-cli/templates/scaffolds/microservice/ as a starting point.

package/templates/drive_templates/agent_app_template/site/.gitkeep

@@ -0,0 +1,4 @@
+# Site Folder
+
+This folder contains the static website or Single Page Application (SPA) for the app.
+Add your index.html and other web assets here.

package/templates/drive_templates/community_template/Apps/.gitkeep

@@ -0,0 +1,4 @@
+# Apps Folder
+
+This folder contains apps belonging to the community.
+Each app has its own subfolder following the agent_app_template structure.

package/templates/drive_templates/community_template/community_assets/community_description.txt

@@ -0,0 +1,15 @@
+# {{COMMUNITY_NAME}}
+
+Welcome to {{COMMUNITY_NAME}}!
+
+This is your community on the DeSciX platform. Edit this description to tell members about your community's purpose, goals, and what makes it unique.
+
+## About
+
+Describe your community here.
+
+## Getting Started
+
+- Join the community discussions
+- Explore available apps
+- Contribute to the knowledge base

package/templates/scaffolds/README.md

@@ -0,0 +1,62 @@
+# Code Scaffolds
+
+These templates contain **code** that must live in Git (not Google Drive). They are copied by the CLI when a user needs to add a site or microservice to their app.
+
+## Why Scaffolds?
+
+DeSciX uses a two-tier template system:
+
+1. **Drive Templates** (`../drive/`) - Content (assets, KB docs) synced to/from Google Drive
+2. **Git Scaffolds** (this folder) - Code that lives in Git, deployed separately
+
+Code cannot live in Drive because:
+- Code needs version control (Git)
+- Code is deployed to Cloud Run / GCS (not synced to Drive)
+- Code has dependencies (package.json, Dockerfile)
+
+## Available Scaffolds
+
+### Site (`site/`)
+
+A hello-world static site with:
+- `index.html` - Main entry point
+- `styles.css` - Basic styling
+- `app.js` - Client-side JavaScript
+- `README.md` - Usage instructions
+
+**Install with:**
+```bash
+descix site init
+```
+
+### Microservice (`microservice/`)
+
+A complete Express microservice with:
+- `app.js` - Server entry point
+- `manifest.json` - Command registration
+- `services/` - API handlers
+- `Dockerfile` - Container build
+- `SERVICE_README_TEMPLATE.md` - Tool discovery docs
+
+**Install with:**
+```bash
+descix microservice init
+```
+
+## Usage
+
+Run scaffold commands from your app directory (auto-detects context):
+
+```bash
+cd my-app/
+descix site init          # Copies site/ scaffold
+descix microservice init  # Copies microservice/ scaffold
+```
+
+## Placeholder Variables
+
+Scaffolds use these placeholders (replaced during copy):
+
+- `{{APP_NAME}}` - App display name
+- `{{APP_ID}}` - App identifier (lowercase)
+- `{{COMMUNITY_ID}}` - Community identifier

package/templates/scaffolds/microservice/Dockerfile

@@ -0,0 +1,19 @@
+# Use official Node.js image
+FROM node:24-slim
+
+# Create app directory
+WORKDIR /usr/src/app
+
+# Install dependencies
+# Copy package.json and package-lock.json
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy app source
+COPY . .
+
+# Expose port (Cloud Run sets PORT env var)
+EXPOSE 8080
+
+# Start
+CMD [ "npm", "start" ]