agentic-govbot/PLATFORM_SKILLS.md

# Mastodon Platform Skills

Complete listing of all platform-specific governance skills available through the Mastodon API.

## Overview

The bot now implements **35+ platform skills** organized into 7 categories:
- Account Moderation (9 skills)
- Account Management (4 skills)
- Report Management (4 skills)
- Federation Management (4 skills)
- Security Management (4 skills)
- Instance Administration (2 skills)
- Web-Only Actions (2 skills - informational only)

## Account Moderation Skills

### suspend_account
**Description**: Suspend a user account (reversible, blocks login and hides content)
**Parameters**:
- `account_id` (str): Account ID to suspend
- `reason` (str): Reason for suspension
**Reversible**: Yes (use `unsuspend_account`)
**Authorization**: Requires moderation authority per constitution

### unsuspend_account
**Description**: Lift suspension from an account
**Parameters**:
- `account_id` (str): Account ID to unsuspend
**Reversible**: Yes (can suspend again)
**Authorization**: Requires moderation authority per constitution

### silence_account
**Description**: Silence a user account (hide from public timelines, reversible)
**Parameters**:
- `account_id` (str): Account ID to silence
- `reason` (str): Reason for silencing
**Reversible**: Yes (use `unsilence_account`)
**Authorization**: Requires moderation authority per constitution

### unsilence_account
**Description**: Lift silence from an account
**Parameters**:
- `account_id` (str): Account ID to unsilence
**Reversible**: Yes (can silence again)
**Authorization**: Requires moderation authority per constitution

### disable_account
**Description**: Disable local account login (reversible)
**Parameters**:
- `account_id` (str): Account ID to disable
- `reason` (str): Reason for disabling
**Reversible**: Yes (use `enable_account`)
**Authorization**: Requires moderation authority per constitution

### enable_account
**Description**: Re-enable a disabled local account
**Parameters**:
- `account_id` (str): Account ID to enable
**Reversible**: Yes (can disable again)
**Authorization**: Requires moderation authority per constitution

### mark_account_sensitive
**Description**: Mark account's media as always sensitive
**Parameters**:
- `account_id` (str): Account ID to mark
- `reason` (str): Reason for marking sensitive
**Reversible**: Yes (use `unmark_account_sensitive`)
**Authorization**: Requires moderation authority per constitution

### unmark_account_sensitive
**Description**: Remove sensitive flag from account
**Parameters**:
- `account_id` (str): Account ID to unmark
**Reversible**: Yes (can mark sensitive again)
**Authorization**: Requires moderation authority per constitution

### delete_status
**Description**: Delete a status/post (permanent)
**Parameters**:
- `status_id` (str): Status ID to delete
- `reason` (str): Reason for deletion
**Reversible**: No
**Authorization**: Requires moderation authority per constitution

## Account Management Skills

### approve_account
**Description**: Approve a pending account registration
**Parameters**:
- `account_id` (str): Account ID to approve
**Reversible**: No
**Authorization**: Requires account approval authority per constitution

### reject_account
**Description**: Reject a pending account registration (permanent)
**Parameters**:
- `account_id` (str): Account ID to reject
**Reversible**: No
**Authorization**: Requires account approval authority per constitution

### delete_account_data
**Description**: Permanently delete all data for a suspended account (IRREVERSIBLE)
**Parameters**:
- `account_id` (str): Suspended account ID to delete
**Reversible**: No
**Note**: Account must already be suspended before data deletion
**Authorization**: Requires highest level authority per constitution

### create_account
**Description**: Create a new user account (requires email verification, may need approval)
**Parameters**:
- `username` (str): Desired username
- `email` (str): Email address
- `password` (str): Account password
- `reason` (str, optional): Registration reason (if approval required)
**Reversible**: No
**Limitations**:
- User must verify email before account is active
- May require manual moderator approval depending on instance settings
- Only creates regular user accounts (not admin accounts)
**Authorization**: Requires account creation authority per constitution

## Report Management Skills

### assign_report
**Description**: Assign a report to yourself for handling
**Parameters**:
- `report_id` (str): Report ID to assign
**Reversible**: Yes (use `unassign_report`)
**Authorization**: Requires report management authority per constitution

### unassign_report
**Description**: Unassign a report so others can claim it
**Parameters**:
- `report_id` (str): Report ID to unassign
**Reversible**: Yes (can reassign)
**Authorization**: Requires report management authority per constitution

### resolve_report
**Description**: Mark a report as resolved
**Parameters**:
- `report_id` (str): Report ID to resolve
**Reversible**: Yes (use `reopen_report`)
**Authorization**: Requires report management authority per constitution

### reopen_report
**Description**: Reopen a closed report
**Parameters**:
- `report_id` (str): Report ID to reopen
**Reversible**: Yes (can resolve again)
**Authorization**: Requires report management authority per constitution

## Federation Management Skills

### block_domain
**Description**: Block federation with a domain
**Parameters**:
- `domain` (str): Domain to block
- `severity` (str): Block severity: "silence", "suspend", or "noop"
- `public_comment` (str): Public reason for block
- `private_comment` (str, optional): Internal note
- `reject_media` (bool, optional): Reject media files from domain
- `reject_reports` (bool, optional): Reject reports from domain
- `obfuscate` (bool, optional): Hide domain name publicly
**Reversible**: Yes (use `unblock_domain`)
**Authorization**: Requires federation management authority per constitution

### unblock_domain
**Description**: Remove domain from block list
**Parameters**:
- `block_id` (str): Domain block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires federation management authority per constitution

### allow_domain
**Description**: Add domain to allowlist (for LIMITED_FEDERATION_MODE)
**Parameters**:
- `domain` (str): Domain to allow
**Reversible**: Yes (use `disallow_domain`)
**Authorization**: Requires federation management authority per constitution

### disallow_domain
**Description**: Remove domain from allowlist
**Parameters**:
- `allow_id` (str): Domain allow ID to remove
**Reversible**: Yes (can allow again)
**Authorization**: Requires federation management authority per constitution

## Security Management Skills

### block_ip
**Description**: Block IP address or range
**Parameters**:
- `ip` (str): IP address with CIDR prefix (e.g., "192.168.0.1/24")
- `severity` (str): Block severity: "sign_up_requires_approval", "sign_up_block", or "no_access"
- `comment` (str): Reason for IP block
- `expires_in` (int, optional): Expiration time in seconds
**Reversible**: Yes (use `unblock_ip`)
**Authorization**: Requires security management authority per constitution

### unblock_ip
**Description**: Remove IP block
**Parameters**:
- `block_id` (str): IP block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires security management authority per constitution

### block_email_domain
**Description**: Block email domain from registrations
**Parameters**:
- `domain` (str): Email domain to block (e.g., "spam.com")
**Reversible**: Yes (use `unblock_email_domain`)
**Authorization**: Requires security management authority per constitution

### unblock_email_domain
**Description**: Remove email domain from block list
**Parameters**:
- `block_id` (str): Email domain block ID to remove
**Reversible**: Yes (can block again)
**Authorization**: Requires security management authority per constitution

## Constitution Management Skills

### publish_constitution
**Description**: Post constitution as pinned thread (deprecates previous version)
**Parameters**:
- `constitution_text` (str): Full constitution text in markdown
- `change_summary` (str, optional): Summary of what changed
**Reversible**: No
**Authorization**: Requires constitutional amendment process
**Behavior**:
1. Finds previously pinned constitution (if any)
2. Adds deprecation notice to old version
3. Splits constitution into thread-sized chunks (~450 chars each)
4. Posts as public thread
5. Pins new thread to profile
6. Unpins old thread
7. Saves post ID for future updates

### update_profile
**Description**: Update bot profile information (bio, fields, display name)
**Parameters**:
- `display_name` (str, optional): Display name
- `note` (str, optional): Bio/description
- `fields` (list, optional): Profile fields (max 4, each with 'name' and 'value')
**Reversible**: Yes
**Authorization**: Requires governance approval
**Example fields**:
```json
[
  {"name": "Constitution", "value": "📜 See pinned post"},
  {"name": "Governance", "value": "Consensus-based"},
  {"name": "Source", "value": "github.com/..."}
]
```

## Instance Administration Skills

**⚠️ IMPORTANT**: Role management is **NOT available via the Mastodon API**. See "Platform Limitations" section below for details.

## Web-Only Actions (Not Available via API)

These skills are included in the bot's knowledge so it can explain limitations to users.

### update_instance_rules
**Description**: Update instance rules/code of conduct
**Status**: WEB-ONLY - Must be done through admin interface
**Web Interface**: `/admin/server_settings/rules`
**Note**: Mastodon API does not provide endpoints for managing server rules programmatically

### create_announcement
**Description**: Create an instance-wide announcement
**Status**: WEB-ONLY - Must be done through admin interface
**Web Interface**: `/admin/announcements`
**Note**: Mastodon API does not provide endpoints for creating announcements programmatically

## Platform Limitations

The bot is now aware of the following limitations and can explain them to users:

### Actions Requiring Web Interface
- **Instance Rules**: Creating and editing server rules must be done at `/admin/server_settings/rules`
- **Announcements**: Creating instance-wide announcements must be done at `/admin/announcements`
- **Role Management**: ALL role operations (grant/revoke moderator, admin, or custom roles) must be done at `/admin/roles`
- **Instance Settings**: Modifying instance description, contact info, etc. requires web admin access

### Actions Not Possible via API
- **Role Management**: The Mastodon API does **NOT** support granting or revoking ANY roles (moderator, admin, or custom). You must use:
  - **Web interface**: `/admin/roles`
  - **Command line**: `tootctl accounts modify username --role RoleName`
- **Admin Account Creation**: Admin accounts cannot be created via API:
  ```bash
  RAILS_ENV=production bin/tootctl accounts create username --email user@example.com --confirmed --role Owner
  ```

### General Limitations
- **Account Creation**: New accounts require email verification and may require manual approval depending on instance settings
- **Permissions Required**: All admin actions require both OAuth scopes AND appropriate role permissions (Manage Users, Manage Reports, etc.)
- **Rate Limits**: API endpoints are subject to rate limiting
- **Suspended Account Deletion**: Account data can only be deleted for already-suspended accounts

## How It Works

1. **Skill Discovery**: When a user makes a request, the bot receives the full list of platform skills
2. **Limitation Awareness**: The bot also receives information about what's not possible via API
3. **Intelligent Routing**: The LLM agent decides whether to:
   - Execute a platform skill (if available and authorized)
   - Explain a limitation (if requested action requires web interface)
   - Create a governance process (if actor lacks authority)
   - Respond with information (if just asking a question)

## Example Interactions

### Successful Platform Skill Execution
```
User: @govbot please suspend account 12345 for spam
Bot: I've suspended account 12345 for spam.
     This action is reversible using the unsuspend_account skill.
```

### Web-Only Limitation
```
User: @govbot please update the instance rules
Bot: Instance rules cannot be updated via the API.
     To update server rules, please visit:
     https://your-instance.com/admin/server_settings/rules

     You can add, edit, or remove rules through the admin interface.
```

### Account Creation with Limitations
```
User: @govbot create an account for newuser@example.com
Bot: Account @newuser created successfully.

     Important: The user must verify their email before they can log in.
     Depending on instance settings, manual approval may also be required.
```

## Technical Implementation

### Code Changes
1. **Mastodon Adapter** (`src/govbot/platforms/mastodon.py`):
   - Added 35+ platform skills across 7 categories
   - Implemented execution methods for all API-available skills
   - Added `get_platform_limitations()` method to document limitations
   - Web-only skills return helpful messages with admin interface URLs

2. **Governance Agent** (`src/govbot/agent.py`):
   - Updated `process_request()` to accept `platform_limitations` parameter
   - Enhanced decision-making prompt to include limitation information
   - Agent now explains limitations when users request unavailable actions

3. **Bot Integration** (`src/govbot/bot.py`):
   - Retrieves platform limitations alongside platform skills
   - Passes limitations to agent for informed decision-making

### API Requirements
All admin skills require:
- Appropriate OAuth scopes (`admin:read`, `admin:write`, etc.)
- Role permissions (Manage Users, Manage Reports, Manage Federation, etc.)
- Active Mastodon.py connection with admin access token

## Documentation Sources
- [Mastodon Admin Accounts API](https://docs.joinmastodon.org/methods/admin/accounts/)
- [Mastodon Admin Reports API](https://docs.joinmastodon.org/methods/admin/reports/)
- [Mastodon Admin Domain Blocks API](https://docs.joinmastodon.org/methods/admin/domain_blocks/)
- [Mastodon Admin IP Blocks API](https://docs.joinmastodon.org/methods/admin/ip_blocks/)
- [Mastodon Admin Email Domain Blocks API](https://docs.joinmastodon.org/methods/admin/email_domain_blocks/)
- [Mastodon Accounts API](https://docs.joinmastodon.org/methods/accounts/)
- [Mastodon OAuth Scopes](https://docs.joinmastodon.org/api/oauth-scopes/)