@descix/cli 1.0.0

package/lib/workspace-utils.js

@@ -0,0 +1,126 @@
+/**
+ * Workspace Utilities
+ * 
+ * Helper functions for workspace mode detection and path resolution.
+ */
+
+import path from 'path';
+
+/**
+ * Detect workspace mode from workspace.json configuration
+ * @param {Object} workspace - Parsed workspace.json
+ * @returns {'single_app' | 'single_community' | 'multi_community'}
+ */
+export function detectWorkspaceMode(workspace) {
+  // Strict Mode Validation: Prioritize explicit mode
+  if (workspace.mode) {
+    return workspace.mode;
+  }
+  
+  // Infer from structure (fallback)
+  if (workspace.communities && Object.keys(workspace.communities).length > 0) {
+    const communityCount = Object.keys(workspace.communities).length;
+    if (communityCount > 1) {
+      return 'multi_community';
+    }
+    // Single community in communities object
+    const community = Object.values(workspace.communities)[0];
+    const appCount = Object.keys(community.apps || {}).length;
+    return appCount > 1 ? 'single_community' : 'single_app';
+  }
+  
+  // Legacy format: single community at root
+  if (workspace.community_id && workspace.app_id) {
+    return 'single_app';
+  }
+  
+  if (workspace.community_id && workspace.apps) {
+    return Object.keys(workspace.apps).length > 1 ? 'single_community' : 'single_app';
+  }
+
+  // Fallback for empty/initialized workspace using defaultContext
+  if (workspace.defaultContext && workspace.defaultContext.communityId && workspace.defaultContext.appId) {
+     return 'single_app';
+  }
+  
+  throw new Error('Unable to determine workspace mode from configuration');
+}
+
+/**
+ * Resolve local path to Drive path based on workspace mode
+ * @param {Object} workspace - Workspace configuration
+ * @param {string} localPath - Path relative to workspace root
+ * @returns {string} Path relative to user's base_folder_id
+ */
+export function resolveToDrivePath(workspace, localPath) {
+  const mode = detectWorkspaceMode(workspace);
+  
+  // Normalize local path (remove leading ./)
+  const normalizedLocal = localPath.replace(/^\.\//, '');
+  
+  switch (mode) {
+    case 'single_app':
+      // Workspace root = app folder
+      // Local: ./kb/General/file.md
+      // Drive: {community_id}/{app_id}/kb/General/file.md
+      const communityId = workspace.community_id || (workspace.defaultContext && workspace.defaultContext.communityId);
+      const appId = workspace.app_id || (workspace.defaultContext && workspace.defaultContext.appId);
+      
+      if (!communityId || !appId) {
+          throw new Error('Missing community_id or app_id for single_app mode path resolution');
+      }
+      return `${communityId}/${appId}/${normalizedLocal}`;
+      
+    case 'single_community':
+      // Workspace root = community folder
+      // Local: ./agent/kb/General/file.md
+      // Drive: {community_id}/agent/kb/General/file.md
+      const commId = workspace.community_id || (workspace.communities && Object.keys(workspace.communities)[0]);
+      if (!commId) {
+          throw new Error('Missing community_id for single_community mode path resolution');
+      }
+      return `${commId}/${normalizedLocal}`;
+      
+    case 'multi_community':
+      // Workspace root = base folder
+      // Local: ./descix/agent/kb/General/file.md
+      // Drive: descix/agent/kb/General/file.md
+      return normalizedLocal;
+  }
+}
+
+/**
+ * Resolve Drive path to local path based on workspace mode
+ * @param {Object} workspace - Workspace configuration
+ * @param {string} drivePath - Path relative to user's base_folder_id
+ * @returns {string} Path relative to workspace root
+ */
+export function resolveToLocalPath(workspace, drivePath) {
+  const mode = detectWorkspaceMode(workspace);
+  
+  switch (mode) {
+    case 'single_app':
+      // Remove community_id/app_id prefix
+      const communityId = workspace.community_id || (workspace.defaultContext && workspace.defaultContext.communityId);
+      const appId = workspace.app_id || (workspace.defaultContext && workspace.defaultContext.appId);
+      
+      const appPrefix = `${communityId}/${appId}/`;
+      if (drivePath.startsWith(appPrefix)) {
+        return './' + drivePath.slice(appPrefix.length);
+      }
+      throw new Error(`Drive path '${drivePath}' implies app '${appId}', but workspace is configured for '${appId}'`);
+      
+    case 'single_community':
+      // Remove community_id prefix
+      const commId = workspace.community_id || (workspace.communities && Object.keys(workspace.communities)[0]);
+      const commPrefix = `${commId}/`;
+      if (drivePath.startsWith(commPrefix)) {
+        return './' + drivePath.slice(commPrefix.length);
+      }
+      throw new Error(`Drive path '${drivePath}' implies community '${commId}', but workspace is configured for '${commId}'`);
+      
+    case 'multi_community':
+      // No prefix to remove
+      return './' + drivePath;
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@descix/cli",
+  "version": "1.0.0",
+  "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
+  "type": "module",
+  "main": "./bin/descix.js",
+  "bin": {
+    "descix": "./bin/descix.js",
+    "descix-mcp": "./bin/mcp-server.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "pack": "npm pack"
+  },
+  "keywords": [
+    "descix",
+    "cli",
+    "mcp",
+    "rag",
+    "cursor",
+    "ai"
+  ],
+  "author": "DeSciX",
+  "license": "@Daita_DeSci_Community_License_v1/Daita_DeSci_Community_License_v1.pdf",
+  "dependencies": {
+    "@descix/app-sdk": "^0.1.0",
+    "@descix/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "axios": "^1.7.9",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.1",
+    "googleapis": "^170.1.0",
+    "inquirer": "^12.1.0",
+    "ora": "^9.0.0",
+    "vite": "^6.2.0"
+  },
+  "bundledDependencies": ["@descix/app-sdk", "@descix/sdk"],
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/templates/agent-claude.md

@@ -0,0 +1,226 @@
+# DeSciX App Development
+
+<!-- BOOTSTRAP MODE: This file was auto-generated by DeSciX.
+     You (the AI agent) should update it as you learn more about the user's
+     project. Remove this comment block once you've customized the file. -->
+
+## Your First Action
+
+Call the `descix_doctor` MCP tool immediately. It returns your auth state,
+workspace context, available tools, and any configuration issues. Use its
+output to orient yourself before doing anything else.
+
+## What is DeSciX?
+
+DeSciX is a platform for building knowledge-powered applications. Think of
+it as a virtual university where:
+
+- **Communities** are departments — each has an on-chain identity and members
+- **Apps** are anything: courses, textbooks, problem sets, simulations, services
+- **Knowledge bases** are the source material — markdown docs vectorized for AI retrieval
+- **You (the AI agent)** are the primary interface for building and navigating
+
+Any community member can build apps, contribute knowledge, and use AI tools
+to interact with the community's collective knowledge.
+
+## 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
+2b. **Verify auth before demo:** Call `descix_doctor` first. If `auth.connected` is false,
+    tell the user: "Run `descix login` in the terminal — or click DeSciX: Connect in the VS Code
+    status bar." Wait for auth before proceeding to chat or resolve_invite.
+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.
+   The hint can change your entire approach:
+   - "No coding background" → never ask about frameworks or deployment. Only narrate what you're doing.
+   - "Experienced DeSciX developer" → skip all setup explanations, go straight to the task.
+   - "Airdrop recipient, first time" → demonstrate value with 2-3 demo questions before explaining anything.
+   If the hint contradicts a checkpoint in this document, the hint wins.
+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 the user any questions, scan the working directory:
+- Check for existing content: `docs/`, `src/`, `README.md`, `package.json`
+- Check for existing DeSciX structure: `kb/`, `site/`, `microservice/`, `.descix/`
+- Check for existing frameworks: `vite.config.*`, `next.config.*`, `tsconfig.json`
+
+Use what you find to tailor your questions:
+- If docs exist: "I see markdown files in `docs/`. Want to use those as your knowledge base?"
+- If a site exists: "You have a site in `src/`. Want me to configure it as a DeSciX app?"
+- If KB already has content: skip the "create starter KB" question
+- If the repo is empty: proceed with standard checkpoints
+
+## Setup Workflow
+
+If `descix_doctor` reports `setup_needed: true`, guide the user through these
+checkpoints. **Ask the user at each step** — don't assume.
+
+### Checkpoint 1: Objective
+> "Do you want to explore existing apps, or build something new?"
+
+### Checkpoint 2: Community & App Selection
+Use `find_communities` and `list_apps_for_community` to show options, then ask:
+> "Which community and app should this project target?"
+
+### Checkpoint 3: Environment
+> "Should this run against local dev backend (localhost:4000) or hosted API?"
+
+### Canonical Setup Commands (run in terminal after checkpoints)
+```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
+```
+
+### Checkpoint 4: Content Strategy
+> "Should I create a starter KB doc now, or wait for your domain docs?"
+
+### Checkpoint 5: Frontend Scope
+> "Do you want plain HTML, or should I set up a framework (React, VitePress, etc.)?"
+
+## Important: Use Explicit Flags
+
+Until workspace context is verified working, **always use explicit flags**
+for all CLI commands:
+```bash
+descix chat -c <community> -a <app> -q "..."
+descix update kb -c <community> -a <app>
+descix kb sync -c <community> -a <app> --kb General
+```
+
+Implicit defaults can silently target the wrong app. After setup, verify
+with `descix chat -c <community> -a <app> -q "test"` before dropping flags.
+
+## Success Criteria
+
+After setup, verify all of these pass:
+- [ ] App visible in `descix app list`
+- [ ] `descix update kb -c <community> -a <app>` succeeds (KB sync)
+- [ ] `descix chat -c <community> -a <app> -q "..."` returns response with source attribution
+
+## Local Development
+
+To see your app in a browser:
+
+| 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) |
+
+For single-app development, a static server is sufficient. The gateway is only
+needed when running multiple apps or testing platform routing.
+
+## Integrating Existing Content
+
+If the repo already has content (an HTML page, a React app, an SDK with docs),
+**do NOT copy files into `site/` or `kb/`**. Instead, integrate them in place.
+
+### Site Integration
+
+**If the project has an `index.html` or web app already:**
+- Serve it directly — it IS the site. Don't duplicate into `site/`.
+- To add DeSciX integration (auth, API access), include `DeSciXAppSDK.js`
+  (scaffolded by `descix app init`) in your HTML:
+  ```html
+  <script src="DeSciXAppSDK.js"></script>
+  <script>
+    // window.DeSciX.call('ask_question_to_app', { user_input: '...' })
+    // window.DeSciX.AppData — user profile, community data
+  </script>
+  ```
+
+**For React/Vite apps**, wrap your root component in AppShell:
+```jsx
+import AppShell from '@descix/app-sdk/AppShell';
+<AppShell appId="{{appId}}">
+  <YourApp />
+</AppShell>
+```
+AppShell provides: Powch auth sidebar, session management, Web3 wallet, DeSciX API.
+
+**For auth-only (no DeSciX UI chrome):**
+```js
+import { PowchClient } from '@descix/app-sdk/powch-client';
+const powch = new PowchClient();
+const user = await powch.auth();
+```
+
+### KB Integration
+
+If docs already exist (`docs/`, `README.md`, SDK reference files):
+- Copy markdown files to `kb/General/` for the sync pipeline
+- Keep originals as the source of truth — sync from there
+- Ask: "I see docs in `docs/`. Want me to use those as your knowledge base?"
+
+### Decision Guide
+
+| Existing Content | Site Strategy | KB Strategy |
+|-----------------|---------------|-------------|
+| HTML/JS app with `index.html` | Serve as-is, add DeSciXAppSDK.js | Use any `docs/` or `*.md` files |
+| React/Vite app | Wrap root in `<AppShell>` | Use `docs/` or README |
+| SDK package with docs + demo | Serve the SDK's demo page | Copy docs to `kb/General/` |
+| Docs only (no frontend) | Skip or create minimal site | Docs ARE the KB |
+| Empty repo | Scaffold from scratch | Create starter KB doc |
+
+## App Structure
+
+Every app has three parts:
+- `site/` — Frontend (any framework: React, VitePress, vanilla HTML)
+- `kb/General/` — Knowledge base source docs (markdown files)
+- `microservice/` — Backend service (optional)
+
+## App Context
+
+- App ID: `{{appId}}`
+- Community: `{{communityId}}`
+- API: `{{apiUrl}}`
+
+## Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `descix_doctor` | Startup diagnostic — call first |
+| `ask_question_to_app` | RAG chat with any app's knowledge base |
+| `query_knowledge_base` | Raw vector search (returns chunks) |
+| `find_communities` | List communities on the platform |
+| `list_apps_for_community` | List apps in a community |
+| `tell_me_how` | Discover any platform capability by asking |
+| `resolve_invite` | Exchange an invite token for app context + agent hint |
+
+## Known CLI Quirks
+
+- `descix status` may report "No workspace found" even when `.descix/workspace.json`
+  exists. This is a known bug — continue with explicit flags.
+- `descix status` may suggest `descix setup` — that command doesn't exist. Use
+  `descix init -c <community> -a <app> -p .` instead.
+
+## After Bootstrap
+
+Once you understand the user's intent and have verified the success criteria,
+rewrite this file to reflect the actual project. Replace this generic content with:
+- Project-specific structure and conventions
+- The user's chosen framework and patterns
+- Relevant community/app context from `descix_doctor`
+- Workflow shortcuts specific to their use case

package/templates/agent-cline.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/agent-copilot.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.