no idea how this works

plugin-agent-permissions/README.md

@@ -0,0 +1,208 @@
+# @paperclipai/plugin-agent-permissions
+
+Per-agent permission toggling for fine-grained access control in Paperclip.
+
+## Overview
+
+This plugin provides a UI for managing per-agent permissions, allowing administrators to enable or disable specific capabilities for each agent in their organization.
+
+### Permission Keys
+
+- `agents:create` - Create new agents
+- `users:invite` - Invite new users to the company
+- `users:manage_permissions` - Manage user permissions
+- `tasks:assign` - Assign tasks to agents
+- `tasks:assign_scope` - Control task assignment scope
+- `joins:approve` - Approve join requests
+
+## Installation
+
+### Local Development
+
+```bash
+# Clone or navigate to the plugin directory
+cd plugin-agent-permissions
+
+# Install dependencies
+pnpm install
+
+# Build the plugin
+pnpm build
+```
+
+### Development Mode
+
+```bash
+# Watch mode - rebuilds on changes
+pnpm dev
+
+# UI dev server with hot-reload (optional)
+pnpm dev:ui
+```
+
+### Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Type checking
+pnpm typecheck
+```
+
+## Plugin Structure
+
+```
+plugin-agent-permissions/
+├── src/
+│   ├── manifest.ts          # Plugin metadata and capabilities
+│   ├── worker.ts            # Worker entry point with handlers
+│   └── ui/
+│       ├── index.tsx        # UI entry point
+│       ├── AgentPermissionsTab.tsx  # Detail tab component
+│       └── PermissionsNav.tsx       # Sidebar navigation
+├── tests/
+│   └── worker.test.ts       # Unit tests
+├── esbuild.config.mjs       # Build configuration
+├── tsconfig.json            # TypeScript config
+├── vitest.config.ts         # Test configuration
+└── package.json             # Dependencies and scripts
+```
+
+## Worker Handlers
+
+### Data Handlers
+
+#### `agent-permissions`
+Returns permissions for a single agent.
+
+```typescript
+// Input: { agentId: string }
+// Output: { agentId: string, permissions: Record<PermissionKey, boolean> }
+```
+
+#### `all-agents-permissions`
+Returns all agents with their permissions.
+
+```typescript
+// Input: { companyId?: string }
+// Output: Array<{ agentId: string, agentName: string, permissions: Record<PermissionKey, boolean> }>
+```
+
+### Actions
+
+#### `toggle-agent-permission`
+Enables or disables a permission for an agent.
+
+```typescript
+// Input: { agentId: string, permissionKey: PermissionKey, enabled: boolean }
+// Output: { success: true }
+```
+
+## UI Entrypoints
+
+### Detail Tab (`permissions`)
+
+Shown on agent detail pages. Displays all permissions with toggle controls.
+
+### Sidebar Navigation (`permissions-nav`)
+
+Global navigation entry for accessing the permissions management interface.
+
+## Publishing to npm
+
+### Prerequisites
+
+1. An npm account with publish permissions
+2. The `@paperclipai/plugin-sdk` must be published to npm (currently in development)
+
+### Steps
+
+1. **Update package.json**
+   ```json
+   {
+     "private": false,
+     "version": "1.0.0",
+     "publishConfig": {
+       "access": "public"
+     }
+   }
+   ```
+
+2. **Replace local SDK references**
+   
+   Change from:
+   ```json
+   "@paperclipai/plugin-sdk": "file:.paperclip-sdk/paperclipai-plugin-sdk-1.0.0.tgz"
+   ```
+   
+   To:
+   ```json
+   "@paperclipai/plugin-sdk": "^1.0.0"
+   ```
+
+3. **Build and publish**
+   ```bash
+   pnpm build
+   npm publish
+   ```
+
+### For Local Development Only
+
+The current setup uses `.paperclip-sdk/` tarballs for local development against an unpublished SDK:
+
+```bash
+# The scaffolded package.json already points to local SDK files
+"@paperclipai/plugin-sdk": "file:.paperclip-sdk/paperclipai-plugin-sdk-1.0.0.tgz"
+```
+
+This allows development before the SDK is officially published to npm.
+
+## Install Into Paperclip (Local Development)
+
+### Step 1: Build the plugin
+
+```bash
+cd plugin-agent-permissions
+pnpm install
+pnpm build
+```
+
+### Step 2: Install into Paperclip
+
+After building, install the plugin into your local Paperclip instance using the API:
+
+```bash
+curl -X POST http://localhost:3100/api/plugins/install \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-api-key>" \
+  -d '{"packageName":"/home/mike/code/paperclip_plugins/plugin-agent-permissions","isLocalPath":true}'
+```
+
+**Note:** Replace `<your-api-key>` with your Paperclip API key. For local development, you can get this from browser dev tools or the CLI config.
+
+The server watches local-path plugins and will automatically restart the worker after rebuilds.
+
+### Step 3: Verify installation
+
+```bash
+curl http://localhost:3100/api/plugins \
+  -H "Authorization: Bearer <your-api-key>"
+```
+
+You should see `plugin-agent-permissions` in the list.
+
+## Uninstall
+
+```bash
+curl -X DELETE http://localhost:3100/api/plugins/paperclipai.plugin-agent-permissions \
+  -H "Authorization: Bearer <your-api-key>"
+```
+
+## License
+
+MIT
+
+## Author
+
+FrenoCorp