@hailer/mcp 0.0.1

package/.claude/skills/add-app-member-skill/SKILL.md

@@ -0,0 +1,977 @@
+---
+name: Sharing Hailer Apps
+description: Complete guide for sharing Hailer apps with users and teams - use when granting app access
+---
+
+# Sharing Hailer Apps - Complete Guide
+
+Complete reference for sharing Hailer apps with workspace members using the `add_app_member` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [Core Concepts](#core-concepts)
+4. [Member Types](#member-types)
+5. [Basic Usage](#basic-usage)
+6. [Sharing Strategies](#sharing-strategies)
+7. [Common Scenarios](#common-scenarios)
+8. [Best Practices](#best-practices)
+9. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**Share with Entire Workspace:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+**Share with Specific Team:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'team_team-id'
+})
+```
+
+**Share with Individual User:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'user_user-id'
+})
+```
+
+**Response:**
+```
+✅ App Member Added Successfully
+
+App ID: app-id
+Member: network_workspace-id (Entire Workspace)
+
+The app is now accessible to the specified member(s)
+```
+
+**Key Requirements:**
+- Must be app owner OR workspace administrator
+- App must exist
+- Member ID must be valid
+- Member format: `network_`, `team_`, or `user_` prefix
+
+## Overview
+
+**What does add_app_member do?**
+
+Grants access to a Hailer app for workspace members, teams, or the entire workspace. This makes the app visible and usable for the specified members.
+
+**Think of it as:**
+- Publishing an app to users
+- Granting app permissions
+- Sharing app access
+- Making app visible
+
+**When to Use:**
+- After creating published app
+- Deploy app to workspace
+- Share with specific teams
+- Grant individual access
+- Expand app availability
+
+**When NOT to Use:**
+- For development apps (typically private)
+- Removing access (use remove_app_member)
+- Changing app ownership (not supported)
+- Managing workspace members (different functionality)
+
+## Core Concepts
+
+### Member vs Access
+
+**Member:**
+- Entity that has access to app
+- Can be workspace, team, or user
+- Added via add_app_member
+- Removed via remove_app_member
+
+**Access levels:**
+- All members have same access level
+- Can view and use the app
+- No distinction between viewer/editor
+- Owner has additional permissions (edit, delete, share)
+
+### Visibility Model
+
+**Before sharing:**
+```
+App created → Only owner can see it
+```
+
+**After sharing with workspace:**
+```
+App created → Shared with workspace → Everyone can see it
+```
+
+**After sharing with team:**
+```
+App created → Shared with team → Team members can see it
+```
+
+### Member Prefixes
+
+**Critical:** Member IDs must have correct prefix:
+
+| Type | Prefix | Example | Who Gets Access |
+|------|--------|---------|-----------------|
+| Workspace | `network_` | `network_68446...` | Everyone in workspace |
+| Team | `team_` | `team_68446...` | All team members |
+| User | `user_` | `user_68446...` | Single user |
+
+**Wrong prefix = Error**
+
+## Member Types
+
+### Workspace Members (network_)
+
+**Share with entire workspace:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+**Who gets access:**
+- All current workspace members
+- New members joining workspace
+- Workspace-wide availability
+
+**Use when:**
+- App is for everyone
+- General-purpose workspace tool
+- No access restrictions needed
+- Maximum visibility desired
+
+**Getting workspace ID:**
+```javascript
+const workspace = get_current_workspace()
+const memberId = `network_${workspace._id}`
+
+add_app_member({
+  appId: 'app-id',
+  member: memberId
+})
+```
+
+### Team Members (team_)
+
+**Share with specific team:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'team_team-id'
+})
+```
+
+**Who gets access:**
+- All current team members
+- New members joining team
+- Team-specific access
+
+**Use when:**
+- App is for specific team/department
+- Need access control
+- Team-specific functionality
+- Limited distribution
+
+**Getting team ID:**
+```javascript
+// From workspace cache or API
+const teamId = 'team-id-here'
+const memberId = `team_${teamId}`
+
+add_app_member({
+  appId: 'app-id',
+  member: memberId
+})
+```
+
+### Individual Users (user_)
+
+**Share with single user:**
+
+```javascript
+add_app_member({
+  appId: 'app-id',
+  member: 'user_user-id'
+})
+```
+
+**Who gets access:**
+- Single specified user only
+- Most restrictive access
+
+**Use when:**
+- Beta testing with specific users
+- Privileged access
+- Personal tools
+- Gradual rollout
+
+**Getting user ID:**
+```javascript
+// Search for user
+const users = search_workspace_users({ query: 'john@example.com' })
+const user = users[0]
+const memberId = `user_${user._id}`
+
+add_app_member({
+  appId: 'app-id',
+  member: memberId
+})
+```
+
+## Basic Usage
+
+### Example 1: Share with Workspace
+
+```javascript
+// 1. Get workspace ID
+const workspace = get_current_workspace()
+console.log('Workspace:', workspace.name)
+
+// 2. Share app with entire workspace
+add_app_member({
+  appId: 'app-id',
+  member: `network_${workspace._id}`
+})
+
+console.log('✅ App shared with entire workspace')
+```
+
+### Example 2: Share with Team
+
+```javascript
+// 1. Have team ID (from workspace data or API)
+const teamId = 'team-id'
+
+// 2. Share with team
+add_app_member({
+  appId: 'app-id',
+  member: `team_${teamId}`
+})
+
+console.log('✅ App shared with team')
+```
+
+### Example 3: Share with Individual User
+
+```javascript
+// 1. Find user
+const users = search_workspace_users({ query: 'john.doe' })
+const user = users[0]
+
+if (!user) {
+  console.error('User not found')
+  return
+}
+
+// 2. Share with user
+add_app_member({
+  appId: 'app-id',
+  member: `user_${user._id}`
+})
+
+console.log(`✅ App shared with ${user.name}`)
+```
+
+### Example 4: Share in Specific Workspace
+
+```javascript
+add_app_member({
+  workspaceId: 'workspace-id',
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+### Example 5: Complete Workflow
+
+```javascript
+// Complete workflow: Create app → Share with workspace
+
+// 1. Create app
+const app = create_app({
+  name: 'Team Dashboard',
+  description: 'Real-time team metrics'
+})
+
+console.log('App created:', app.appId)
+
+// 2. Build and publish app
+// ... build and publish steps ...
+
+// 3. Share with workspace
+const workspace = get_current_workspace()
+add_app_member({
+  appId: app.appId,
+  member: `network_${workspace._id}`
+})
+
+console.log('✅ App published and shared with workspace')
+```
+
+## Sharing Strategies
+
+### Strategy 1: Immediate Workspace Sharing
+
+**Best for:** General-purpose tools
+
+```javascript
+// Create and immediately share
+const app = create_app({
+  name: 'Task Manager',
+  description: 'Workspace task management'
+})
+
+// Share with everyone
+const workspace = get_current_workspace()
+add_app_member({
+  appId: app.appId,
+  member: `network_${workspace._id}`
+})
+
+console.log('✅ App available to entire workspace')
+```
+
+### Strategy 2: Gradual Rollout
+
+**Best for:** Testing and validation
+
+```javascript
+// Phase 1: Share with specific users (beta testers)
+const betaUsers = ['user1-id', 'user2-id', 'user3-id']
+
+betaUsers.forEach(userId => {
+  add_app_member({
+    appId: 'app-id',
+    member: `user_${userId}`
+  })
+})
+
+console.log('Phase 1: Beta testing with selected users')
+
+// Phase 2: Share with team (after feedback)
+add_app_member({
+  appId: 'app-id',
+  member: 'team_team-id'
+})
+
+console.log('Phase 2: Rolled out to team')
+
+// Phase 3: Share with workspace (after validation)
+const workspace = get_current_workspace()
+add_app_member({
+  appId: 'app-id',
+  member: `network_${workspace._id}`
+})
+
+console.log('Phase 3: Available to entire workspace')
+```
+
+### Strategy 3: Team-Based Distribution
+
+**Best for:** Department-specific tools
+
+```javascript
+// Share with multiple teams
+const teams = [
+  { id: 'sales-team-id', name: 'Sales' },
+  { id: 'support-team-id', name: 'Support' }
+]
+
+teams.forEach(team => {
+  add_app_member({
+    appId: 'app-id',
+    member: `team_${team.id}`
+  })
+  console.log(`✅ Shared with ${team.name} team`)
+})
+```
+
+### Strategy 4: Role-Based Access
+
+**Best for:** Privileged tools
+
+```javascript
+// Share only with admins and managers
+const privilegedUsers = [
+  'admin-user-id-1',
+  'admin-user-id-2',
+  'manager-user-id-1'
+]
+
+privilegedUsers.forEach(userId => {
+  add_app_member({
+    appId: 'app-id',
+    member: `user_${userId}`
+  })
+})
+
+console.log('✅ Shared with privileged users only')
+```
+
+## Common Scenarios
+
+### Scenario 1: Publish New App to Workspace
+
+**Goal:** Make newly created app available to everyone.
+
+```javascript
+// 1. Create published app
+const app = create_app({
+  name: 'Project Dashboard',
+  description: 'Real-time project tracking dashboard'
+})
+
+// 2. Update manifest.json with appId
+// ... manual step ...
+
+// 3. Build and publish
+// ... build and publish steps ...
+
+// 4. Share with entire workspace
+const workspace = get_current_workspace()
+add_app_member({
+  appId: app.appId,
+  member: `network_${workspace._id}`
+})
+
+console.log('✅ App published and available to workspace')
+console.log('Users can now access app from Apps menu')
+```
+
+### Scenario 2: Share Existing App with Team
+
+**Goal:** Give team access to existing app.
+
+```javascript
+// 1. Find app
+const apps = list_apps()
+const app = apps.find(a => a.name === 'Analytics Dashboard')
+
+if (!app) {
+  console.error('App not found')
+  return
+}
+
+// 2. Share with team
+const teamId = 'marketing-team-id'
+add_app_member({
+  appId: app._id,
+  member: `team_${teamId}`
+})
+
+console.log('✅ Analytics Dashboard shared with Marketing team')
+```
+
+### Scenario 3: Beta Testing with Selected Users
+
+**Goal:** Test app with specific users before wide release.
+
+```javascript
+// Find app
+const app = list_apps().find(a => a.name === 'New Feature App')
+
+// Beta tester emails
+const betaTesters = [
+  'alice@example.com',
+  'bob@example.com',
+  'charlie@example.com'
+]
+
+// Share with each beta tester
+betaTesters.forEach(email => {
+  const users = search_workspace_users({ query: email })
+  const user = users[0]
+
+  if (user) {
+    add_app_member({
+      appId: app._id,
+      member: `user_${user._id}`
+    })
+    console.log(`✅ Shared with ${user.name}`)
+  } else {
+    console.warn(`⚠️ User not found: ${email}`)
+  }
+})
+
+console.log('Beta testing phase initiated')
+```
+
+### Scenario 4: Share Multiple Apps with Team
+
+**Goal:** Give team access to suite of apps.
+
+```javascript
+// Team ID
+const teamId = 'sales-team-id'
+
+// App names to share
+const appNames = [
+  'CRM Dashboard',
+  'Sales Pipeline',
+  'Customer Insights',
+  'Reporting Tool'
+]
+
+// Get all apps
+const apps = list_apps()
+
+// Share each app with team
+appNames.forEach(name => {
+  const app = apps.find(a => a.name === name)
+
+  if (app) {
+    add_app_member({
+      appId: app._id,
+      member: `team_${teamId}`
+    })
+    console.log(`✅ Shared ${name}`)
+  } else {
+    console.warn(`⚠️ App not found: ${name}`)
+  }
+})
+
+console.log('Sales team now has access to all tools')
+```
+
+### Scenario 5: Migrate from Team to Workspace
+
+**Goal:** Expand app from team-only to workspace-wide.
+
+```javascript
+// App currently shared with team, expand to workspace
+
+const app = list_apps().find(a => a.name === 'Report Generator')
+
+// Check current members
+console.log('Current members:', app.members)
+
+// Add workspace access
+const workspace = get_current_workspace()
+add_app_member({
+  appId: app._id,
+  member: `network_${workspace._id}`
+})
+
+console.log('✅ App now available to entire workspace')
+console.log('Note: Team-specific access remains')
+```
+
+### Scenario 6: Share All Apps with New Team
+
+**Goal:** Give newly created team access to all existing apps.
+
+```javascript
+// New team created
+const newTeamId = 'new-team-id'
+
+// Get all apps you own
+const apps = list_apps()
+const myApps = apps.filter(a => a.isOwner && !a.url)  // Published apps only
+
+console.log(`Sharing ${myApps.length} apps with new team`)
+
+// Share each app
+myApps.forEach(app => {
+  add_app_member({
+    appId: app._id,
+    member: `team_${newTeamId}`
+  })
+  console.log(`✅ Shared ${app.name}`)
+})
+```
+
+## Best Practices
+
+### 1. Share After Publishing, Not Before
+
+```javascript
+// Good: Create → Publish → Share
+const app = create_app({ name: 'My App' })
+// ... build and publish ...
+add_app_member({
+  appId: app.appId,
+  member: 'network_workspace-id'
+})
+
+// Bad: Create → Share → Publish
+// Users might access incomplete app
+```
+
+### 2. Use Correct Member Prefix
+
+```javascript
+// Good: Correct prefixes
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'  // ✅
+})
+
+add_app_member({
+  appId: 'app-id',
+  member: 'team_team-id'  // ✅
+})
+
+// Bad: Missing prefix
+add_app_member({
+  appId: 'app-id',
+  member: 'workspace-id'  // ❌ Error!
+})
+```
+
+### 3. Verify App Exists Before Sharing
+
+```javascript
+// Always verify
+const apps = list_apps()
+const app = apps.find(a => a._id === 'app-id')
+
+if (!app) {
+  console.error('App not found')
+  return
+}
+
+if (!app.isOwner && !app.isAdmin) {
+  console.error('No permission to share')
+  return
+}
+
+// Safe to share
+add_app_member({
+  appId: app._id,
+  member: 'network_workspace-id'
+})
+```
+
+### 4. Start Restrictive, Expand Later
+
+```javascript
+// Start with limited access
+add_app_member({
+  appId: 'app-id',
+  member: 'team_team-id'
+})
+
+// Later, expand to workspace
+// (Don't remove team access, add workspace access)
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+### 5. Document Sharing Decisions
+
+```javascript
+// Log sharing for audit trail
+console.log({
+  action: 'add_app_member',
+  appId: 'app-id',
+  appName: 'Dashboard',
+  member: 'network_workspace-id',
+  memberType: 'workspace',
+  date: new Date().toISOString(),
+  sharedBy: 'admin-user-id'
+})
+```
+
+### 6. Don't Share Development Apps
+
+```javascript
+const apps = list_apps()
+
+apps.forEach(app => {
+  // Only share published apps
+  if (app.url) {
+    console.log(`Skipping dev app: ${app.name}`)
+    return
+  }
+
+  // Share published apps
+  add_app_member({
+    appId: app._id,
+    member: 'network_workspace-id'
+  })
+})
+```
+
+### 7. Batch Share Operations
+
+```javascript
+// Share multiple apps efficiently
+const appIds = ['app-id-1', 'app-id-2', 'app-id-3']
+const member = 'team_team-id'
+
+appIds.forEach(appId => {
+  add_app_member({ appId, member })
+  console.log(`✅ Shared ${appId}`)
+})
+```
+
+## Troubleshooting
+
+### Error: "Permission Denied"
+
+**Cause:** Not app owner or workspace administrator.
+
+**Solution:**
+
+```javascript
+const app = list_apps().find(a => a._id === 'app-id')
+
+console.log('Owner:', app.isOwner)
+console.log('Admin:', app.isAdmin)
+
+if (!app.isOwner && !app.isAdmin) {
+  console.error('Cannot share - not owner or admin')
+  console.log('App owner:', app.owner)
+}
+```
+
+### Error: "Invalid Member ID"
+
+**Cause:** Wrong member ID format.
+
+**Solution:**
+
+```javascript
+// Must have correct prefix
+// ❌ Wrong:
+member: 'workspace-id'
+member: 'team-id'
+member: 'user-id'
+
+// ✅ Correct:
+member: 'network_workspace-id'
+member: 'team_team-id'
+member: 'user_user-id'
+
+// Get workspace ID properly
+const workspace = get_current_workspace()
+const correctMember = `network_${workspace._id}`
+
+add_app_member({
+  appId: 'app-id',
+  member: correctMember
+})
+```
+
+### Error: "App Not Found"
+
+**Cause:** Invalid app ID.
+
+**Solution:**
+
+```javascript
+// List apps to find correct ID
+const apps = list_apps()
+apps.forEach(a => {
+  console.log(`${a.name}: ${a._id}`)
+})
+
+// Use correct ID
+add_app_member({
+  appId: 'correct-app-id',
+  member: 'network_workspace-id'
+})
+```
+
+### Member Added But App Not Visible
+
+**Causes:**
+1. Browser cache
+2. User not logged in
+3. Wrong member ID
+4. App not published yet
+
+**Solutions:**
+
+```javascript
+// 1. Verify member added
+const app = list_apps().find(a => a._id === 'app-id')
+console.log('Members:', app.members)
+
+// 2. Check if member ID is in list
+const memberExists = app.members.includes('network_workspace-id')
+console.log('Member added:', memberExists)
+
+// 3. User should refresh browser
+console.log('⚠️ Users need to refresh browser to see new apps')
+
+// 4. Verify app is published (not dev)
+console.log('App type:', app.url ? 'Dev (not visible)' : 'Published')
+```
+
+### Shared with Workspace But User Can't Access
+
+**Causes:**
+1. User not in workspace
+2. User needs to refresh
+3. App entry exists but code not published
+
+**Solutions:**
+
+```javascript
+// Verify sharing
+const app = list_apps().find(a => a._id === 'app-id')
+const workspace = get_current_workspace()
+const workspaceMember = `network_${workspace._id}`
+
+if (app.members.includes(workspaceMember)) {
+  console.log('✅ Shared with workspace')
+  console.log('ℹ️ Users should refresh browser')
+  console.log('ℹ️ Verify app code is published')
+} else {
+  console.log('❌ Not shared with workspace')
+}
+```
+
+## Integration with Other Tools
+
+### With create_app
+
+Create and share:
+
+```javascript
+// 1. Create app
+const app = create_app({
+  name: 'Dashboard'
+})
+
+// 2. Build and publish
+// ...
+
+// 3. Share
+const workspace = get_current_workspace()
+add_app_member({
+  appId: app.appId,
+  member: `network_${workspace._id}`
+})
+```
+
+### With list_apps
+
+Find and share:
+
+```javascript
+// 1. Find app
+const app = list_apps().find(a => a.name === 'Report Tool')
+
+// 2. Share
+if (app && app.isOwner) {
+  add_app_member({
+    appId: app._id,
+    member: 'team_team-id'
+  })
+}
+```
+
+### With publish_hailer_app
+
+Publish then share:
+
+```javascript
+// 1. Publish app
+publish_hailer_app({
+  email: 'your@email.com',
+  password: 'password',
+  projectDirectory: '/path/to/app'
+})
+
+// 2. Share with workspace
+const app = list_apps().find(a => a.name === 'My App')
+const workspace = get_current_workspace()
+
+add_app_member({
+  appId: app._id,
+  member: `network_${workspace._id}`
+})
+```
+
+### With search_workspace_users
+
+Find user and share:
+
+```javascript
+// 1. Find user
+const users = search_workspace_users({ query: 'john' })
+const user = users[0]
+
+// 2. Share app with user
+if (user) {
+  add_app_member({
+    appId: 'app-id',
+    member: `user_${user._id}`
+  })
+  console.log(`✅ Shared with ${user.name}`)
+}
+```
+
+### With remove_app_member
+
+Grant then revoke:
+
+```javascript
+// Grant access
+add_app_member({
+  appId: 'app-id',
+  member: 'user_user-id'
+})
+
+// Later, revoke access
+remove_app_member({
+  appId: 'app-id',
+  member: 'user_user-id'
+})
+```
+
+## Summary
+
+**Key Takeaways:**
+1. 🔓 **Grants access** - Makes app visible to members
+2. 🔒 **Owner/admin only** - Requires permissions
+3. 🌐 **Three levels** - Workspace, team, or user
+4. 🏷️ **Prefix required** - `network_`, `team_`, or `user_`
+5. 📱 **After publishing** - Share published apps, not dev apps
+6. 🔄 **Additive** - Can share with multiple members
+7. ✅ **Immediate effect** - Access granted right away
+
+**Quick Decision Tree:**
+
+```
+Need to share app?
+│
+├─ For everyone? → network_workspace-id
+├─ For specific team? → team_team-id
+├─ For one person? → user_user-id
+├─ Beta testing? → Share with selected users first
+├─ Dev app? → Don't share (keep private)
+└─ After sharing? → Users refresh browser to see
+```
+
+## Additional Resources
+
+- See `create-app-skill` for creating apps
+- See `list-apps-skill` for viewing apps
+- See `remove-app-member-skill` for revoking access
+- See `publish-hailer-app-skill` for publishing apps
+- See `app-api` skill for comprehensive App API documentation
+- Use `search_workspace_users` to find user IDs
+- Use `get_current_workspace` to get workspace ID