@hailer/mcp 0.0.1

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

@@ -0,0 +1,671 @@
+---
+name: remove-app-member-skill
+description: Complete guide to using the remove_app_member tool to revoke Hailer app access from users, teams, or workspaces
+---
+
+# Remove App Member Skill
+
+Complete guide to using the `remove_app_member` tool to revoke Hailer app access from workspace members, teams, or individual users.
+
+## Table of Contents
+- [Quick Reference](#quick-reference)
+- [Overview](#overview)
+- [Core Concepts](#core-concepts)
+- [Basic Usage](#basic-usage)
+- [Common Scenarios](#common-scenarios)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Integration with Other Tools](#integration-with-other-tools)
+- [Additional Resources](#additional-resources)
+
+## Quick Reference
+
+### Remove workspace access (revoke for all members)
+```javascript
+remove_app_member({
+  appId: '<app-id>',
+  member: 'network_68446c045b30685f67c6fc8c'
+})
+```
+
+### Remove team access
+```javascript
+remove_app_member({
+  appId: '<app-id>',
+  member: 'team_<team-id>'
+})
+```
+
+### Remove individual user access
+```javascript
+remove_app_member({
+  appId: '<app-id>',
+  member: 'user_<user-id>'
+})
+```
+
+## Overview
+
+The `remove_app_member` tool revokes permission for users, teams, or entire workspaces to access a Hailer app. This is the inverse operation of `add_app_member` and is essential for managing app distribution, restricting access during development, or implementing role-based access control.
+
+**Key capabilities:**
+- Revoke workspace-wide access
+- Remove team-based access
+- Revoke individual user access
+- Maintain creator/admin access (cannot be revoked)
+- Clean permission management
+
+**Requirements:**
+- User must be app creator or workspace admin
+- App must exist
+- Member ID must have correct prefix (network_, team_, user_, group_)
+
+**Important notes:**
+- Creator and admins always retain access (cannot be removed)
+- Removing workspace access revokes access from ALL members (except creator/admins)
+- Member format is same as `add_app_member` tool
+
+## Core Concepts
+
+### Member Types and Prefixes
+
+Member identifiers **must** include specific prefixes to indicate the type of access being revoked:
+
+| Member Type | ID Format | Example | Effect |
+|------------|-----------|---------|--------|
+| **Workspace** | `network_<workspace-id>` | `network_68446c045b30685f67c6fc8c` | Revokes access for entire workspace (all members) |
+| **Team** | `team_<team-id>` | `team_507f1f77bcf86cd799439011` | Revokes access for specific team |
+| **User** | `user_<user-id>` | `user_507f191e810c19729de860ea` | Revokes access for individual user |
+| **Group** | `group_<group-id>` | `group_507f191e810c19729de860eb` | Revokes access for group |
+
+### Permission Hierarchy
+
+Understanding who can be removed:
+1. **Cannot remove:** App creator and workspace admins (always retain access)
+2. **Can remove:** Regular members, teams, or workspace-wide grants
+3. **Cascading effect:** Removing workspace access affects all non-admin members
+
+### Access Control
+
+Who can remove members:
+- App creator
+- Workspace administrators
+- Cannot be delegated to regular users
+
+## Basic Usage
+
+### Step 1: Identify the app
+
+Use `list_apps` to find your app ID:
+
+```javascript
+list_apps()
+```
+
+Look for the app you want to modify:
+```
+App ID: abc123
+Name: Task Manager
+Members: network_68446c045b30685f67c6fc8c, team_507f1f77bcf86cd799439011
+```
+
+### Step 2: Identify member to remove
+
+From the members list, identify which access grant to revoke:
+- Workspace access: `network_68446c045b30685f67c6fc8c`
+- Team access: `team_507f1f77bcf86cd799439011`
+
+### Step 3: Remove the member
+
+```javascript
+remove_app_member({
+  appId: 'abc123',
+  member: 'team_507f1f77bcf86cd799439011'
+})
+```
+
+### Step 4: Verify removal
+
+Check the app's member list again:
+
+```javascript
+list_apps()
+```
+
+The removed member should no longer appear in the members array.
+
+## Common Scenarios
+
+### Scenario 1: Restrict Beta App to Specific Team
+
+You have a beta app shared workspace-wide, but want to restrict it to just the development team:
+
+```javascript
+// 1. Remove workspace access
+remove_app_member({
+  appId: 'beta-app-id',
+  member: 'network_68446c045b30685f67c6fc8c'
+})
+
+// 2. Add specific team access
+add_app_member({
+  appId: 'beta-app-id',
+  member: 'team_dev-team-id'
+})
+```
+
+**Result:** Only development team members (plus creator/admins) can access the app.
+
+### Scenario 2: Revoke Individual Tester Access
+
+Remove access for specific users after beta testing completes:
+
+```javascript
+// Remove multiple testers
+remove_app_member({
+  appId: 'beta-app-id',
+  member: 'user_tester1-id'
+})
+
+remove_app_member({
+  appId: 'beta-app-id',
+  member: 'user_tester2-id'
+})
+
+remove_app_member({
+  appId: 'beta-app-id',
+  member: 'user_tester3-id'
+})
+```
+
+### Scenario 3: Migrate from Workspace to Team Access
+
+Narrow access from everyone to specific teams:
+
+```javascript
+// 1. Get current app details
+const apps = list_apps()
+const myApp = apps.find(app => app.id === 'my-app-id')
+
+// 2. Remove workspace access
+remove_app_member({
+  appId: 'my-app-id',
+  member: 'network_68446c045b30685f67c6fc8c'
+})
+
+// 3. Add specific teams
+add_app_member({
+  appId: 'my-app-id',
+  member: 'team_sales-id'
+})
+
+add_app_member({
+  appId: 'my-app-id',
+  member: 'team_marketing-id'
+})
+```
+
+### Scenario 4: Remove All External Access
+
+Remove all sharing and keep app private (creator/admins only):
+
+```javascript
+// 1. List current members
+list_apps()
+
+// 2. Remove each member grant
+remove_app_member({
+  appId: 'private-app-id',
+  member: 'network_68446c045b30685f67c6fc8c'  // If workspace shared
+})
+
+// App is now private - only creator and admins have access
+```
+
+### Scenario 5: Clean Up Old Access Grants
+
+Remove deprecated team or user access:
+
+```javascript
+// Remove old team that no longer exists
+remove_app_member({
+  appId: 'app-id',
+  member: 'team_old-team-id'
+})
+
+// Remove former employees
+remove_app_member({
+  appId: 'app-id',
+  member: 'user_former-employee-id'
+})
+```
+
+## Best Practices
+
+### 1. Verify Before Removal
+
+Always check current members before removing:
+
+```javascript
+// Check current access
+list_apps()
+
+// Then remove specific member
+remove_app_member({
+  appId: 'app-id',
+  member: 'team_old-team-id'
+})
+```
+
+### 2. Use Least Privilege Principle
+
+Remove broad access and add specific access:
+
+```javascript
+// ❌ Bad: Leave workspace access + add exceptions
+// Everyone can access, hard to manage
+
+// ✅ Good: Remove workspace, add specific teams
+remove_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+
+add_app_member({
+  appId: 'app-id',
+  member: 'team_authorized-team-id'
+})
+```
+
+### 3. Document Access Changes
+
+Keep track of why access was removed:
+
+```javascript
+// Update app name or config to reflect access level
+update_app({
+  appId: 'app-id',
+  name: 'Internal Tool (Sales & Marketing Only)',
+  config: {
+    ...app.config,
+    accessLevel: 'team-specific',
+    authorizedTeams: ['sales', 'marketing']
+  }
+})
+```
+
+### 4. Communicate Changes
+
+Before removing access from teams or workspace:
+- Notify affected users
+- Explain why access is being restricted
+- Provide timeline for changes
+
+### 5. Test with Minimal Access First
+
+When deploying to production:
+
+```javascript
+// 1. Start private (no sharing)
+create_app({
+  name: 'New App',
+  url: 'https://app-url.com'
+})
+
+// 2. Add small test team
+add_app_member({
+  appId: 'new-app-id',
+  member: 'team_test-team-id'
+})
+
+// 3. After validation, expand to other teams
+// (Don't go straight to workspace-wide)
+
+// 4. If issues found, easily restrict again
+remove_app_member({
+  appId: 'new-app-id',
+  member: 'team_test-team-id'
+})
+```
+
+### 6. Handle Cascading Effects
+
+Understand impact of removing workspace access:
+
+```javascript
+// Removing workspace access affects ALL members
+// (except creator and admins)
+
+remove_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+
+// This is equivalent to removing access from:
+// - All teams
+// - All individual users
+// - Any future workspace members
+
+// Creator and admins still retain access
+```
+
+## Troubleshooting
+
+### Error: "Permission Denied"
+
+**Problem:** Can't remove app member.
+
+**Causes:**
+1. You're not the app creator or workspace admin
+2. Trying to remove creator or admin (not allowed)
+
+**Solutions:**
+```javascript
+// Check who you are
+list_apps()
+
+// Look for "You are: creator" or "You are: admin"
+
+// If you're not creator/admin, ask them to remove the member
+// Creators and admins cannot be removed - they always have access
+```
+
+### Error: "App not found"
+
+**Problem:** Invalid app ID.
+
+**Solution:**
+```javascript
+// List all apps to get correct ID
+list_apps()
+
+// Use exact app ID from the list
+remove_app_member({
+  appId: 'correct-app-id',
+  member: 'team_team-id'
+})
+```
+
+### Error: "Member format invalid"
+
+**Problem:** Member ID doesn't have required prefix.
+
+**Solution:**
+```javascript
+// ❌ Wrong: No prefix
+remove_app_member({
+  appId: 'app-id',
+  member: '68446c045b30685f67c6fc8c'
+})
+
+// ✅ Correct: With prefix
+remove_app_member({
+  appId: 'app-id',
+  member: 'network_68446c045b30685f67c6fc8c'
+})
+```
+
+### Member Still Has Access After Removal
+
+**Problem:** User can still access app after removing their team.
+
+**Possible causes:**
+1. User is app creator or admin (always has access)
+2. User has access through another grant (e.g., workspace or different team)
+3. User has individual user grant
+
+**Solution:**
+```javascript
+// 1. Check all current members
+list_apps()
+
+// Look at the members array:
+// members: [
+//   'network_workspace-id',     // Workspace access
+//   'team_team-id',             // Team access
+//   'user_specific-user-id'     // Individual access
+// ]
+
+// 2. Remove ALL relevant grants
+remove_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+
+remove_app_member({
+  appId: 'app-id',
+  member: 'user_specific-user-id'
+})
+```
+
+### Accidentally Removed Wrong Member
+
+**Problem:** Removed the wrong team or user.
+
+**Solution:**
+```javascript
+// Simply add them back
+add_app_member({
+  appId: 'app-id',
+  member: 'team_correct-team-id'
+})
+
+// Or re-add workspace access if you removed it by mistake
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+### Want to Remove Creator Access
+
+**Problem:** Creator wants to transfer ownership or remove their access.
+
+**Solution:**
+This is not possible. The app creator always retains access. Workspace admins also always retain access.
+
+**Workarounds:**
+1. Delete the app entirely using `remove_app`
+2. Create a new app with a different creator
+3. Keep the app but remove all other members
+
+## Integration with Other Tools
+
+### With `add_app_member`
+
+Manage access by adding and removing members:
+
+```javascript
+// Migration pattern: Replace team access
+remove_app_member({
+  appId: 'app-id',
+  member: 'team_old-team-id'
+})
+
+add_app_member({
+  appId: 'app-id',
+  member: 'team_new-team-id'
+})
+```
+
+### With `list_apps`
+
+Always check current members before removing:
+
+```javascript
+// 1. Check current state
+const apps = list_apps()
+const myApp = apps.find(app => app.name === 'My App')
+
+console.log('Current members:', myApp.members)
+
+// 2. Remove specific member
+remove_app_member({
+  appId: myApp.id,
+  member: 'team_unwanted-team-id'
+})
+
+// 3. Verify removal
+const updatedApps = list_apps()
+const updatedApp = updatedApps.find(app => app.id === myApp.id)
+console.log('Updated members:', updatedApp.members)
+```
+
+### With `update_app`
+
+Update app metadata to reflect access changes:
+
+```javascript
+// Remove workspace access
+remove_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+
+// Update app name to reflect restricted access
+update_app({
+  appId: 'app-id',
+  name: 'Beta Tool (Dev Team Only)',
+  config: {
+    ...app.config,
+    accessLevel: 'restricted'
+  }
+})
+```
+
+### With `create_app`
+
+Start with restricted access during development:
+
+```javascript
+// 1. Create app (private by default)
+const result = create_app({
+  name: 'New Feature (Dev)',
+  url: 'http://localhost:3000'
+})
+
+// 2. Add only dev team during development
+add_app_member({
+  appId: result.appId,
+  member: 'team_dev-team-id'
+})
+
+// 3. After testing, remove dev team and add production teams
+remove_app_member({
+  appId: result.appId,
+  member: 'team_dev-team-id'
+})
+
+add_app_member({
+  appId: result.appId,
+  member: 'network_workspace-id'
+})
+```
+
+### With `publish_hailer_app`
+
+Manage access during publishing workflow:
+
+```javascript
+// 1. Start private during development
+create_app({
+  name: 'My App (Dev)',
+  url: 'http://localhost:3000'
+})
+
+// 2. Build and publish
+publish_hailer_app({
+  manifestPath: './manifest.json',
+  buildDir: './dist',
+  appId: 'app-id'
+})
+
+// 3. Test with small team first
+add_app_member({
+  appId: 'app-id',
+  member: 'team_qa-team-id'
+})
+
+// 4. If issues found, restrict again
+remove_app_member({
+  appId: 'app-id',
+  member: 'team_qa-team-id'
+})
+
+// 5. After validation, share workspace-wide
+add_app_member({
+  appId: 'app-id',
+  member: 'network_workspace-id'
+})
+```
+
+### With `remove_app`
+
+Clean up before deleting:
+
+```javascript
+// 1. Remove all members first (optional, for cleanliness)
+remove_app_member({
+  appId: 'old-app-id',
+  member: 'network_workspace-id'
+})
+
+// 2. Then delete the app
+remove_app({
+  appId: 'old-app-id'
+})
+```
+
+## Additional Resources
+
+### Related Skills
+- **add-app-member-skill** - Share apps with users, teams, or workspace
+- **list-apps-skill** - View and manage workspace apps
+- **create-app-skill** - Create new Hailer app entries
+- **update-app-skill** - Modify app properties
+- **remove-app-skill** - Delete app entries
+- **publish-hailer-app-skill** - Deploy and publish apps
+
+### Related Tools
+- `add_app_member` - Grant app access
+- `list_apps` - View all apps and their members
+- `update_app` - Modify app configuration
+- `create_app` - Create new app entries
+
+### Key Concepts
+- Member ID prefixes (network_, team_, user_, group_)
+- Permission hierarchy (creator/admin always retain access)
+- Cascading effects (removing workspace affects all members)
+- Access control patterns (least privilege)
+
+### Access Patterns
+
+| Pattern | Use Case | Implementation |
+|---------|----------|----------------|
+| **Private** | Development only | Don't add any members |
+| **Team Specific** | Department tools | Remove workspace, add specific teams |
+| **Graduated Rollout** | Phased deployment | Start with one team, expand gradually |
+| **Workspace Wide** | Company tools | Add network_workspace-id |
+| **Restricted Beta** | Testing | Remove workspace, add test users individually |
+
+### Common Workflows
+
+1. **Lock down during development:**
+   ```javascript
+   remove_app_member({ appId, member: 'network_...' })
+   ```
+
+2. **Gradual expansion:**
+   ```javascript
+   add_app_member({ appId, member: 'team_pilot-team' })
+   // test...
+   remove_app_member({ appId, member: 'team_pilot-team' })
+   add_app_member({ appId, member: 'network_...' })
+   ```
+
+3. **Access cleanup:**
+   ```javascript
+   // Remove all, re-add only authorized
+   remove_app_member({ appId, member: 'network_...' })
+   add_app_member({ appId, member: 'team_authorized-team' })
+   ```