@descix/cli 1.0.0

package/agent-assets/guides/knowledge-only-pattern.md

@@ -0,0 +1,93 @@
+# Knowledge-Only App Pattern
+
+## Overview
+
+A Knowledge-Only app is pure documentation/content that gets indexed for semantic search. No public URL, no executable code.
+
+## When to Use
+
+Choose this pattern when the user wants to:
+- Make documentation searchable via RAG
+- Create a reference library for AI agents
+- Index research notes or papers
+- Build training data for AI assistants
+
+**Key Question:** "Do you need a public website or backend logic?"
+- If NO → Knowledge-Only is the right choice
+
+## Structure
+
+```
+my-docs/
+├── assets/
+│   ├── app_description.md      # Required
+│   ├── icon.png                # Required (512x512)
+│   └── system_instructions.md  # Required
+└── kb/
+    ├── staging/                # New files to push
+    ├── General/                # Text-converted content
+    │   ├── README.md
+    │   ├── getting-started.md
+    │   ├── api-reference.md
+    │   └── tutorials/
+    │       └── ...
+    └── chunks/                 # Processed chunks (JSON)
+```
+
+**Note:** No `site/` or `microservice/` folders needed.
+
+## Configuration (`workspace.json`)
+
+```json
+{
+  "communities": {
+    "my-community": {
+      "apps": {
+        "my-docs": {
+          "localPath": "my-community/my-docs",
+          "sync_mode": "git"
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI Workflow
+
+```bash
+# 1. Pull content from Drive (if any)
+descix kb pull -c <community> -a <app>
+
+# 2. Add local files to staging
+cp my-new-doc.pdf kb/staging/
+
+# 3. Push to Drive (converts to text)
+descix kb push -c <community> -a <app>
+
+# 4. Pull converted text back
+descix kb pull -c <community> -a <app>
+
+# 5. Chunk for RAG
+descix kb chunk -c <community> -a <app>
+
+# 6. Sync to Pinecone
+descix kb sync -c <community> -a <app>
+```
+
+## Capabilities
+
+| Capability | Enabled |
+|------------|---------|
+| RAG search | Yes |
+| chat_with_kb | Yes |
+| Public URL | No |
+| MCP tools | No |
+| tell_me_how discovery | No |
+
+## Example Use Cases
+
+1. **Research Library** - Index academic papers for semantic search
+2. **Internal Docs** - Make company documentation searchable by AI
+3. **Training Data** - Build a knowledge base for fine-tuning AI models
+4. **Reference Materials** - API docs, specifications, standards

package/agent-assets/guides/microservice-pattern.md

@@ -0,0 +1,152 @@
+# Microservice App Pattern
+
+## Overview
+
+A Microservice app is a backend service that exposes commands via MCP, plus optional frontend and documentation.
+
+## When to Use
+
+Choose this pattern when the user wants to:
+- Create API endpoints callable via MCP
+- Build tools discoverable via `tell_me_how`
+- Add backend logic to their app
+- Integrate with external services
+
+**Key Questions:**
+1. "Does it have backend logic (API endpoints, commands)?" → Yes
+2. "Should AI agents be able to discover and use its tools?" → Yes
+
+## Structure
+
+```
+my-service/
+├── assets/
+│   ├── app_description.md
+│   ├── icon.png
+│   └── system_instructions.md
+├── kb/
+│   ├── staging/
+│   ├── General/
+│   │   ├── README.md
+│   │   └── api-reference.md
+│   └── chunks/
+├── site/                       # Optional frontend
+│   └── ...
+├── microservice/
+│   ├── manifest.json           # Command registration
+│   ├── SERVICE_README_myapp.md # Tool discovery docs
+│   ├── package.json
+│   ├── Dockerfile
+│   ├── app.yaml
+│   └── src/
+│       ├── index.js
+│       ├── apiFront.js
+│       └── commandHandlers/
+│           └── myCommands.js
+└── package.json
+```
+
+## Configuration (`workspace.json`)
+
+```json
+{
+  "communities": {
+    "my-community": {
+      "apps": {
+        "my-service": {
+          "localPath": "my-community/my-service",
+          "sync_mode": "git",
+          "service": {
+            "port": 4000,
+            "devCommand": "npm run start"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI Workflow
+
+```bash
+# 1. Create microservice scaffold
+descix microservice init
+
+# 2. Implement your commands in commandHandlers/
+
+# 3. Register service with gateway
+descix microservice register
+
+# 4. Vectorize SERVICE_README for discovery
+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 (via service) |
+| MCP tools | Yes |
+| tell_me_how discovery | Yes |
+
+## Key Files
+
+### manifest.json
+
+Defines commands exposed to MCP:
+
+```json
+{
+  "service_id": "my-service",
+  "version": "1.0.0",
+  "commands": [
+    {
+      "name": "my_command",
+      "description": "What this command does",
+      "parameters": {
+        "param1": { "type": "string", "required": true }
+      }
+    }
+  ]
+}
+```
+
+### SERVICE_README_{app_id}.md
+
+Documentation for `tell_me_how` discovery:
+
+```markdown
+# My Service
+
+## Overview
+What this service does and when to use it.
+
+## Commands
+
+### my_command
+**Description:** What it does
+**Use when:** Scenarios when appropriate
+**Parameters:**
+- param1 (required): Description
+```
+
+## Microservice Scaffold
+
+To add the microservice folder to an existing app:
+
+```bash
+descix microservice init
+```
+
+This copies the full Express microservice template with:
+- `app.js` - Server entry point
+- `manifest.json` - Command registration
+- `services/` - API handlers and utilities
+- `Dockerfile` - Container build
+- `SERVICE_README_TEMPLATE.md` - Discovery docs template

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

@@ -0,0 +1,111 @@
+# Static Site App Pattern
+
+## Overview
+
+A Static Site app is a built website (HTML/CSS/JS) deployed to CDN, plus documentation indexed for RAG. No backend logic.
+
+## When to Use
+
+Choose this pattern when the user wants to:
+- Deploy a documentation site (VitePress, Docusaurus)
+- Host a landing page or portfolio
+- Create a marketing site with searchable content
+- Build a client-side-only web app
+
+**Key Questions:**
+1. "Do you need a public website?" → Yes
+2. "Does it have backend logic?" → No
+
+## Structure
+
+```
+my-site/
+├── assets/
+│   ├── app_description.md
+│   ├── icon.png
+│   └── system_instructions.md
+├── kb/
+│   ├── staging/
+│   ├── General/
+│   │   ├── README.md
+│   │   └── ... (markdown for RAG)
+│   └── chunks/
+├── site/                       # Static files to deploy
+│   ├── index.html
+│   ├── styles.css
+│   ├── app.js
+│   └── dist/                   # Build output (if using bundler)
+├── src/                        # Source files (not deployed)
+│   └── ...
+├── package.json
+└── vite.config.js
+```
+
+## Configuration (`workspace.json`)
+
+```json
+{
+  "communities": {
+    "my-community": {
+      "apps": {
+        "my-site": {
+          "localPath": "my-community/my-site",
+          "sync_mode": "git",
+          "site": {
+            "port": 3000,
+            "devCommand": "npm run docs:dev"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI Workflow
+
+```bash
+# 1. Create site scaffold (if starting fresh)
+descix site init
+
+# 2. Build your site
+npm run build
+
+# 3. Upload site to GCS
+descix site upload
+```
+
+## Capabilities
+
+| Capability | Enabled |
+|------------|---------|
+| RAG search | Yes |
+| chat_with_kb | Yes |
+| Public URL | Yes |
+| MCP tools | No |
+| tell_me_how discovery | No |
+
+## Example Use Cases
+
+1. **Documentation Site** - VitePress/Docusaurus docs with searchable content
+2. **Landing Page** - Marketing site for a project or product
+3. **Portfolio** - Personal or company portfolio
+4. **Client-Side App** - React/Vue app with no backend
+
+## Site Scaffold
+
+To add the site folder to an existing app:
+
+```bash
+descix site init
+```
+
+This copies the site template with:
+- `index.html` - Main entry point
+- `styles.css` - Basic styling
+- `app.js` - Client-side JavaScript
+- `README.md` - Usage instructions
+
+## Deployment
+
+Static files are deployed to Google Cloud Storage and served via signed URLs. The site URL is available in the app's metadata.