@hailer/mcp 0.0.1

package/.claude/skills/app-api/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: App API Reference
+description: Complete reference for Hailer App API - use when building app management MCP tools
+---
+
+# App API Reference Skill
+
+This skill provides comprehensive documentation for Hailer App API endpoints. Apps are custom applications that integrate with Hailer workspaces, extending functionality with custom UIs and workflows.
+
+## When to Use This Skill
+
+Invoke this skill when:
+- Building app management MCP tools
+- Creating or managing Hailer apps
+- Working with app permissions and members
+- Installing marketplace apps
+- Understanding app configuration
+
+## What are Hailer Apps?
+
+**Apps = Custom web applications that run within Hailer**
+
+Think of them as:
+- **Custom UIs**: React/vanilla JS applications
+- **Workspace Extensions**: Add new capabilities to Hailer
+- **Development Apps**: Point to localhost for development
+- **Published Apps**: Deployed to apps.hailer.com or custom URLs
+
+## Quick Navigation
+
+### Core App Operations
+- **v3.app.create** - Create new app entry
+- **v3.app.list** - List all apps in workspace
+- **v3.app.update** - Update existing app
+- **v3.app.remove** - Delete app entry
+- **v3.app.config.update** - Edit app configuration
+
+### App Permission Management
+- **v3.app.member.add** - Add member permissions (users, teams, workspace)
+- **v3.app.member.remove** - Remove member permissions
+
+### Marketplace Operations
+- **v3.app.product.create** - Create marketplace product
+- **v3.app.product.get** - Get product details
+- **v3.app.product.install** - Install marketplace app
+- **v3.app.product.getManifest** - Get app manifest
+- **v3.app.product.isProductInstalled** - Check installation status
+
+## Key Concepts
+
+### App Types
+
+**1. Development Apps**
+- URL points to localhost (e.g., `http://localhost:3000`)
+- Used during development
+- Hot reload, live updates
+- Accessible only to developers
+
+**2. Published Apps**
+- URL empty or points to production (e.g., `https://apps.hailer.com/app/xyz`)
+- Deployed to production
+- Accessible based on permissions
+- Version controlled
+
+### App Structure
+
+```javascript
+{
+  name: 'My App',
+  description: 'Cool app description',
+  url: 'http://localhost:3000', // or empty for published
+  image: '<imageId>',            // Optional app icon
+  config: {                      // Optional configuration
+    fields: {}
+  }
+}
+```
+
+### App Permissions
+
+Apps support member-based permissions:
+- **Workspace**: `network_<networkId>` - All workspace members
+- **Team**: `team_<teamId>` - Specific team members
+- **User**: `user_<userId>` - Individual users
+- **Group**: `group_<groupId>` - Custom user groups
+
+Default: Only creator and admins can see/use the app
+
+## Common Use Cases
+
+1. **Create Development App**: Point to localhost for local development
+2. **Create Published App**: Empty URL for deployment
+3. **Manage Permissions**: Control who can access the app
+4. **List Apps**: See all apps in workspace
+5. **Update App**: Change name, description, URL, icon
+6. **Install Marketplace App**: Add pre-built apps from Hailer marketplace
+
+## App Development Workflow
+
+### 1. Create Development App Entry
+```javascript
+v3.app.create({
+  name: 'Local Development',
+  description: 'App pointing to local server',
+  url: 'http://localhost:3000'
+})
+```
+
+### 2. Scaffold App from Template
+```bash
+npm create @hailer/app@latest
+# Select: react-ts, react-swc-ts, or vanilla
+```
+
+### 3. Develop Locally
+```bash
+cd my-app
+npm install
+npm run dev
+# App runs on http://localhost:3000
+```
+
+### 4. Create Published App Entry
+```javascript
+v3.app.create({
+  name: 'Published App',
+  description: 'Production app',
+  url: '' // Empty for auto URL
+})
+```
+
+### 5. Configure manifest.json
+```javascript
+{
+  "appId": "<published-app-id>",
+  "name": "My App",
+  "version": "1.0.0"
+}
+```
+
+### 6. Publish App
+```bash
+EMAIL=user@example.com npm run publish-production
+```
+
+## Documentation
+
+See [App API Endpoints](references/app-endpoints.md) for complete endpoint documentation with request/response schemas and examples.
+
+## MCP Tool Building Rules
+
+When building App MCP tools:
+
+1. **Use workspace context**: Apps are workspace-specific
+2. **Handle permissions**: Only creators/admins can manage apps
+3. **Support both dev and prod**: Dev apps have URL, published apps may not
+4. **Member management**: Support user, team, workspace, group permissions
+5. **Clear feedback**: Show app ID, URL, and access info
+
+## Example Patterns
+
+### Create Development App
+```javascript
+create_app({
+  name: 'Task Manager Dev',
+  description: 'Local development version',
+  url: 'http://localhost:3000'
+})
+```
+
+### Create Published App
+```javascript
+create_app({
+  name: 'Task Manager',
+  description: 'Production task management app',
+  url: '' // Auto URL
+})
+```
+
+### Share App with Team
+```javascript
+add_app_member({
+  appId: '<app-id>',
+  member: 'team_<team-id>'
+})
+```
+
+### Share App with Entire Workspace
+```javascript
+add_app_member({
+  appId: '<app-id>',
+  member: 'network_<workspace-id>'
+})
+```
+
+## Important Notes
+
+**App Entry vs App Code**:
+- **App Entry**: Hailer metadata (name, URL, permissions) - managed via API
+- **App Code**: React/JS source code - developed separately, published via CLI
+
+**URL Behavior**:
+- **With URL**: App loads from specified URL (development)
+- **Empty URL**: Hailer sets default publication URL (production)
+
+**Permissions**:
+- Default: Creator + workspace admins
+- Use member.add to grant access to others
+- Use member.remove to revoke access
+
+**Marketplace Apps**:
+- Pre-built apps available in Hailer marketplace
+- Can be installed into workspaces
+- May have dependencies or configuration requirements
+
+## Next Steps
+
+For complete endpoint documentation with request/response schemas, see:
+- [App API Endpoints](references/app-endpoints.md) - All v3.app.* endpoints