mcp-tools.md

<!-- AUTO-GENERATED — DO NOT EDIT — see reference/auto/manifest.yml -->

# MCP Tool Catalog

> Auto-generated by `rails mcp:generate_tool_catalog` on 2026-07-31 10:12 UTC
> Source: `Ai::Tools::PlatformApiToolRegistry::TOOLS`

**581 actions** across **64 tool classes**

---

## Project & CI/CD

### `create_gitea_repository`

Create a new Gitea repository with project scaffold

- **Tool class**: `Ai::Tools::ProjectInitTool`
- **Permission**: ai.workflows.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repo_name` | string | Yes | Repository name |
| `description` | string | No | Repository description |
| `organization` | string | No | Organization name to create the repository under (omit for personal namespace) |
| `private` | boolean | No | Whether the repository should be private (default: true) |

### `update_gitea_repository`

Update settings on an existing Gitea repository (visibility, description, archival, etc.)

- **Tool class**: `Ai::Tools::RepoManagementTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner (username or organization) |
| `repo` | string | Yes | Repository name |
| `private` | boolean | No | Set repository visibility (true = private, false = public) |
| `description` | string | No | Updated repository description |
| `archived` | boolean | No | Archive or unarchive the repository |
| `default_branch` | string | No | Change the default branch |

### `dispatch_to_runner`

Dispatch a worktree execution to a self-hosted runner (GitHub Actions, Gitea Actions, or GitLab CI)

- **Tool class**: `Ai::Tools::RunnerDispatchTool`
- **Permission**: ai.workflows.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Worktree session ID |
| `worktree_id` | string | Yes | Worktree ID |
| `task_input` | object | No | Task input data |
| `runner_labels` | array | No | Required runner labels |

---

## Agent Management

### `create_agent`

Create a new AI agent with the specified configuration

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Agent name |
| `description` | string | No | Agent description |
| `model` | string | No | Model name (defaults to provider default) |
| `agent_type` | string | No | Agent type (default: assistant) |
| `system_prompt` | string | No | System prompt |
| `conversation_profile` | object | No | Conversation profile configuration |

### `list_agents`

List all active AI agents in the current account

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute
- **Parameters**: none

### `execute_agent`

Queue execution of a server-side AI agent (assistant type only). Cannot execute MCP client agents — use @mention in workspace messages to reach them.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent ID, slug, or exact name |
| `input` | object | No | Execution input |

### `get_agent`

Get detailed information about a specific AI agent

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |

### `update_agent`

Update an existing AI agent's configuration

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |
| `name` | string | No | New agent name |
| `description` | string | No | New agent description |
| `status` | string | No | Agent status |
| `system_prompt` | string | No | System prompt |
| `conversation_profile` | object | No | Conversation profile configuration |
| `mcp_metadata` | object | No | MCP metadata to merge |

### `set_agent_autonomy_level`

Manually set an agent's trust level (supervised/monitored/trusted/autonomous). Bypasses the computed trust_score tier. Use to bootstrap a new agent or override after manual review.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `trust_level` | string | Yes | supervised | monitored | trusted | autonomous |

### `update_agent_trust_score`

Update an agent's computed AgentTrustScore record. Pass any subset of dimension scores (reliability/cost_efficiency/safety/quality/speed) or `overall_score` + `tier` to manually adjust. Auto-creates the trust_score row if missing.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `tier` | string | No | supervised | monitored | trusted | autonomous |
| `overall_score` | number | No | 0.0–1.0 |
| `reliability` | number | No | 0.0–1.0 |
| `cost_efficiency` | number | No | 0.0–1.0 |
| `safety` | number | No | 0.0–1.0 |
| `quality` | number | No | 0.0–1.0 |
| `speed` | number | No | 0.0–1.0 |

### `delete_agent`

Hard-destroy an AI agent. Cascades children (executions/conversations/messages/skills/etc) via dependent:destroy. For FKs without dependent: (mcp_sessions, ralph_loops.default_agent_id, team memberships, telemetry, learnings, messages, a2a tasks, etc), if reassign_to_agent_id is given those rows are repointed to it; otherwise they are deleted. Irreversible.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name to destroy |
| `reassign_to_agent_id` | string | No | Agent UUID, slug, or name to repoint un-cascaded FKs to. If omitted, those rows are deleted. |

### `spawn_task`

Spawn a task for another agent to execute. Validates capability matrix and delegation authority before dispatching.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Target agent ID, slug, or name |
| `task` | string | Yes | Task description for the target agent |
| `budget_cents` | integer | No | Budget allocation in cents |

### `check_task_status`

Check the status and output of a previously spawned task.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | A2A task ID |

### `wait_for_task`

Poll until a spawned task completes or times out.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | A2A task ID |
| `timeout_seconds` | integer | No | Maximum wait time in seconds (default: 300) |

---

## Agent Containers

### `deploy_container_agent`

Deploy a containerized agent with MCP authentication. Launches an isolated container from a template with automatic OAuth credential provisioning and MCP session bootstrap.

- **Tool class**: `Ai::Tools::ContainerDeploymentTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | ID of the agent to deploy |
| `template_id` | string | No | Container template ID (auto-selected if omitted) |
| `template_slug` | string | No | Container template slug (alternative to template_id) |
| `conversation_id` | string | No | Conversation ID for chat-mode deployment |

### `agent_container_status`

Get the current status and details of a container instance by execution ID. Returns status, resource usage, duration, and any error information.

- **Tool class**: `Ai::Tools::ContainerStatusTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container instance |

### `agent_container_logs`

Fetch logs from a container instance. Returns the execution logs, status, and any error messages. Logs are truncated to the requested tail size.

- **Tool class**: `Ai::Tools::ContainerLogsTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container instance |
| `tail` | integer | No | Number of characters from the end to return (default: 50000, max: 100000) |

### `agent_container_terminate`

Gracefully terminate a running container instance. Respects execution gate governance checks. The container will be cancelled with the provided reason.

- **Tool class**: `Ai::Tools::ContainerTerminateTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container to terminate |
| `reason` | string | No | Reason for termination (default: 'Terminated via MCP tool') |

---

## Team Management

### `create_team`

Create a new AI agent team with the specified configuration

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Team name |
| `description` | string | No | Team description |
| `team_type` | string | No | Team type (default: sequential) |
| `coordination_strategy` | string | No | Coordination strategy (default: manager_led) |

### `add_team_member`

Add an AI agent as a member of a team

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |
| `role` | string | No | Member role (default: worker) |

### `remove_team_member`

Remove an AI agent from a team. Destroys the AgentTeamMember row and the backing TeamRole if present.

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |

### `execute_team`

Queue execution of a team workflow

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `input` | object | No | Execution input |

### `get_team`

Get detailed information about a specific team including its members

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |

### `list_teams`

List all active AI agent teams in the current account

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute
- **Parameters**: none

### `update_team`

Update an existing team's configuration

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `name` | string | No | New team name |
| `description` | string | No | New team description |
| `status` | string | No | Team status: active, paused, archived |
| `coordination_strategy` | string | No | Coordination strategy |
| `team_config` | object | No | Team configuration to merge |
| `review_config` | object | No | Review configuration to merge |

### `delete_team`

Hard-destroy a team. Cascades: members + channels + executions :destroy; conversations + learnings :nullify. Irreversible.

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |

---

## Pipeline Management

### `trigger_pipeline`

Trigger a DevOps pipeline run

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pipeline_id` | string | Yes | Devops::Pipeline ID to run |

### `list_pipelines`

List DevOps pipelines, optionally filtered by repository

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Filter by repository ID |

### `get_pipeline_status`

Get the current status of a specific pipeline

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pipeline_id` | string | Yes | Pipeline ID |

---

## Memory Management

### `write_shared_memory`

Write a value to shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key (dot-separated for nesting) |
| `value` | object | Yes | Value to write |

### `read_shared_memory`

Read a value from shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key to read |

### `delete_shared_memory`

Delete a key from shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key to delete (dot-separated for nested keys) |

### `search_memory`

Search across memory tiers by keyword query

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `agent_id` | string | No | Target agent ID |
| `limit` | integer | No | Max results (default 10) |

### `consolidate_memory`

Run memory consolidation pipeline for an agent (promotes across tiers)

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID |

### `memory_stats`

Get memory usage statistics across all tiers

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent ID (omit for account-wide stats) |

### `list_pools`

List all memory pools in the current account

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `create_memory_pool`

Create a new memory pool. pool_id should be a unique slug (e.g. 'research_ops'). Pools are account-scoped.

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | Yes | Unique slug for the pool (lowercase, underscores) |
| `name` | string | Yes | Human-readable display name |
| `pool_type` | string | No | Pool type: shared (default), persistent, short_term, long_term |
| `scope` | string | No | Scope: account (default), public, agent, team, execution |
| `owner_agent_id` | string | No | Owner agent (scope=agent) |
| `team_id` | string | No | Owner team (scope=team) |
| `retention_policy` | object | No | JSON retention config (ttl, max_size, etc.) |

### `delete_memory_pool`

Permanently delete a memory pool and all its data. Cannot delete the 'default' pool.

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | Yes | Pool slug or UUID |

### `agent_remember`

Store a key-value pair in the agent's private memory pool with optional TTL, importance, and tags

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Memory key (dot-notation supported) |
| `value` | string | Yes | Value to store (string, number, object, or array) |
| `ttl_seconds` | integer | No | Time-to-live in seconds (optional) |
| `importance` | number | No | Importance score 0-1 (default 0.5) |
| `tags` | array | No | Tags for categorization |

### `agent_forget`

Remove or soft-decay a memory key from the agent's private pool

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Memory key to forget |
| `soft` | boolean | No | If true, decay importance instead of deleting (default false) |

### `agent_reflect`

Trigger on-demand STM consolidation and summary generation (rate-limited: 1 per 15 minutes)

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none
- **Parameters**: none

### `agent_recall`

Semantic search across agent's private memory pool and optionally team_shared pools

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query |
| `include_team` | boolean | No | Also search team_shared pools (default false) |
| `limit` | integer | No | Maximum results to return (default 10) |

---

## Knowledge & RAG

### `query_knowledge_base`

Search RAG knowledge bases for relevant documents using hybrid semantic + keyword search

- **Tool class**: `Ai::Tools::KnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `knowledge_base_id` | string | No | Specific knowledge base ID (searches first available if omitted) |
| `mode` | string | No | Search mode: hybrid (default), vector, keyword, graph |
| `top_k` | integer | No | Max results (default 5, max 20) |

### `list_knowledge_bases`

List all RAG knowledge bases in the current account

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage
- **Parameters**: none

### `create_knowledge_base`

Create a new RAG knowledge base for document storage and retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Knowledge base name |
| `description` | string | No | Knowledge base description |

### `add_document`

Add a document to a RAG knowledge base

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `name` | string | Yes | Document name |
| `content` | string | Yes | Document content |
| `content_type` | string | No | Content type (default: text/plain) |
| `source_url` | string | No | Source URL for the document |

### `process_document`

Process a document: chunk and embed it for RAG retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `document_id` | string | Yes | Document ID to process |

### `search_documents`

Search across RAG knowledge base documents using hybrid retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `knowledge_base_id` | string | No | Knowledge base ID (defaults to most recent) |
| `mode` | string | No | Search mode: hybrid, vector, keyword, graph (default: hybrid) |
| `top_k` | integer | No | Max results (default 5) |

### `delete_document`

Delete a document from a RAG knowledge base

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `document_id` | string | Yes | Document ID to delete |

### `get_api_reference`

Get the platform API reference documentation

- **Tool class**: `Ai::Tools::ApiReferenceTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `section` | string | No | Section filter: workflows, agents, teams, providers, git, monitoring, memory, rag |

---

## KB Article Management

### `list_kb_articles`

List Knowledge Base articles with optional category and status filters

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category_slug` | string | No | Filter by category slug |
| `status` | string | No | Filter by status (draft/review/published/archived) |

### `get_kb_article`

Get a Knowledge Base article by ID or slug

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `article_id` | string | No | Article ID |
| `slug` | string | No | Article slug (alternative to ID) |

### `create_kb_article`

Create a new Knowledge Base article in a category

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Article title |
| `content` | string | Yes | Article content in markdown |
| `category_slug` | string | Yes | Category slug |
| `status` | string | No | Status (default: draft) |
| `excerpt` | string | No | Article excerpt |
| `is_featured` | boolean | No | Featured flag |
| `tags` | array | No | Tag names |

### `update_kb_article`

Update an existing Knowledge Base article

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `article_id` | string | Yes | Article ID |
| `title` | string | No | New article title |
| `content` | string | No | New article content |
| `excerpt` | string | No | New article excerpt |
| `status` | string | No | New status |
| `is_featured` | boolean | No | Featured flag |
| `tags` | array | No | Tag names |

---

## Page Management

### `list_pages`

List content pages with optional status filter

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status (draft/published) |

### `get_page`

Get a content page by ID or slug

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | No | Page ID |
| `slug` | string | No | Page slug (alternative to ID) |

### `create_page`

Create a new content page

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Page title |
| `content` | string | Yes | Page content in markdown |
| `slug` | string | No | Page slug (auto-generated if omitted) |
| `status` | string | No | Status (default: draft) |
| `meta_description` | string | No | SEO meta description |
| `meta_keywords` | string | No | SEO meta keywords comma-separated |

### `update_page`

Update an existing content page

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | Yes | Page ID |
| `title` | string | No | New page title |
| `content` | string | No | New page content |
| `slug` | string | No | New slug |
| `status` | string | No | New status |
| `meta_description` | string | No | SEO meta description |
| `meta_keywords` | string | No | SEO meta keywords |

---

## Compound Learning

### `query_learnings`

Query compound learnings with optional filters and keyword search

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Search query for learnings |
| `category` | string | No | Filter by category (pattern/anti_pattern/best_practice/discovery/fact/failure_mode/review_finding/performance_insight) |
| `scope` | string | No | Filter by scope (team/global) |
| `status` | string | No | Filter by status (active/superseded/archived) |
| `limit` | integer | No | Max results (default 20) |

### `reinforce_learning`

Reinforce a compound learning by recording a positive outcome and boosting importance

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | Learning ID to reinforce |

### `learning_metrics`

Get compound learning metrics and effectiveness statistics

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `create_learning`

Create a new compound learning entry

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Learning content |
| `title` | string | No | Learning title |
| `category` | string | No | Category (default: discovery) |
| `importance_score` | number | No | Importance score 0.0-1.0 (default: 0.5) |
| `confidence_score` | number | No | Confidence score 0.0-1.0 (default: 0.5) |
| `tags` | array | No | Tags array for categorization and dedup |

---

## Shared Knowledge

### `search_knowledge`

Search shared knowledge entries using semantic and keyword search

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `content_type` | string | No | Filter by content type |
| `access_level` | string | No | Filter by access level |
| `limit` | integer | No | Max results (default 10) |

### `create_knowledge`

Create a new shared knowledge entry

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Entry title |
| `content` | string | Yes | Entry content |
| `content_type` | string | No | Content type: text/markdown/code/snippet/procedure/reference/fact/definition/guide (default: text) |
| `access_level` | string | No | Access level (default: team) |
| `tags` | array | No | Tags array |

### `update_knowledge`

Update an existing shared knowledge entry

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID |
| `content` | string | No | Updated content |
| `access_level` | string | No | Updated access level |
| `tags` | array | No | Updated tags |

### `promote_knowledge`

Promote a shared knowledge entry to a higher access level

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID to promote |
| `access_level` | string | No | Target access level (auto-determined if omitted) |

### `delete_knowledge`

Delete (archive) a shared knowledge entry. Soft-deletes by default; use hard_delete: true to permanently remove.

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID to delete |
| `hard_delete` | boolean | No | Permanently destroy instead of archiving (default: false) |

---

## Skills

### `list_skills`

List AI skills with optional filters and pagination

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Filter by category |
| `status` | string | No | Filter by status: active/inactive/draft |
| `enabled` | boolean | No | Filter by enabled: true/false |
| `search` | string | No | Search query for name/description |
| `page` | integer | No | Page number (default 1) |
| `per_page` | integer | No | Results per page (default 20) |

### `get_skill`

Get detailed information about a specific AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |

### `discover_skills`

Discover relevant AI skills for a given task using graph traversal

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_context` | string | Yes | Task description to discover relevant skills |
| `mode` | string | No | Traversal mode: auto/manifest (default: auto) |
| `token_budget` | integer | No | Max token budget (default 2000) |

### `get_skill_context`

Get enriched context for an input text using skill graph

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input_text` | string | Yes | Input text for context enrichment |
| `agent_id` | string | No | Agent ID for manifest mode |
| `mode` | string | No | Traversal mode: auto/manifest (default: auto) |
| `token_budget` | integer | No | Max token budget (default 2000) |

### `skill_health`

Get a comprehensive health report for the skill graph

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read
- **Parameters**: none

### `skill_metrics`

Get skill graph health score and metrics

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read
- **Parameters**: none

### `create_skill`

Create a new AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Skill name |
| `description` | string | No | Skill description |
| `category` | string | No | Skill category |
| `system_prompt` | string | No | System prompt template |
| `commands` | array | No | Slash commands array |
| `tags` | array | No | Tags array |

### `update_skill`

Update an existing AI skill's configuration. A global/system skill is never edited in place — the edit lands on a per-account clone instead (response includes cloned: true and cloned_from_id).

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |
| `name` | string | No | New skill name |
| `description` | string | No | New skill description |
| `category` | string | No | Skill category |
| `system_prompt` | string | No | System prompt template |
| `commands` | array | No | Slash commands array |
| `tags` | array | No | Tags array |

### `clone_skill`

Fork a visible (global or account) skill into the current account as an editable copy, optionally applying overrides in the same call. Idempotent per origin — a repeat clone of the same origin edits the account's existing fork rather than duplicating it.

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill UUID or slug to clone |
| `name` | string | No | Override name on the clone |
| `description` | string | No | Override description on the clone |
| `category` | string | No | Override category on the clone |
| `system_prompt` | string | No | Override system prompt on the clone |
| `commands` | array | No | Override commands array on the clone |
| `tags` | array | No | Override tags array on the clone |

### `delete_skill`

Delete an AI skill permanently

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID to delete |

### `toggle_skill`

Enable or disable an AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |
| `enabled` | boolean | Yes | Set to true or false |

### `attach_skill_to_agent`

Bind a skill to an agent — adds an Ai::AgentSkill row that lets the agent invoke the skill. Idempotent: re-attach updates priority/is_active.

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill UUID or slug |
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `priority` | integer | No | Priority order (default 0) |
| `is_active` | boolean | No | Active flag (default true) |

### `detach_skill_from_agent`

Unbind a skill from an agent — destroys the Ai::AgentSkill row.

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill UUID or slug |
| `agent_id` | string | Yes | Agent UUID, slug, or name |

---

## Knowledge Quality

### `verify_learning`

Verify a compound learning as accurate, boosting its confidence score

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to verify |

### `dispute_learning`

Dispute a compound learning as inaccurate with a reason

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to dispute |
| `reason` | string | Yes | Reason for the dispute |

### `resolve_contradiction`

Resolve a contradiction between two learnings by picking a winner

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `winner_id` | string | Yes | Winning learning ID |
| `loser_id` | string | Yes | Losing learning ID (will be superseded) |
| `reason` | string | Yes | Reason for the resolution |

### `rate_knowledge`

Rate a shared knowledge entry on a 1-5 quality scale

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | SharedKnowledge entry ID |
| `rating` | integer | Yes | Quality rating (1-5) |

### `knowledge_health`

Get a cross-system health report for learnings, shared knowledge, and knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage
- **Parameters**: none

### `unsupersede_learning`

Revive a deprecated/superseded learning back to active state. Clears superseded_by_id and resets status to active. Use to reverse an erroneous resolve_contradiction call.

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to revive |

### `verify_learning_batch`

Bulk-verify multiple learnings at once. Skips already-non-active entries. Returns per-id success/skip.

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_ids` | array | Yes | Array of CompoundLearning IDs |

---

## Knowledge Graph

### `search_knowledge_graph`

Search the knowledge graph using hybrid retrieval (vector + keyword + graph)

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `mode` | string | No | Search mode: hybrid/vector/keyword/graph (default: hybrid) |
| `top_k` | integer | No | Max results (default 10) |
| `knowledge_base_id` | string | No | Filter by knowledge base |

### `reason_knowledge_graph`

Perform multi-hop reasoning over the knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Reasoning query |
| `max_hops` | integer | No | Max reasoning hops (default 3) |
| `top_k` | integer | No | Max results (default 5) |

### `get_graph_node`

Get detailed information about a specific knowledge graph node

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | Node ID |

### `list_graph_nodes`

List knowledge graph nodes with optional filters and pagination

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_type` | string | No | Filter by node type |
| `entity_type` | string | No | Filter by entity type |
| `query` | string | No | Search query |
| `knowledge_base_id` | string | No | Filter by knowledge base |
| `page` | integer | No | Page number |
| `per_page` | integer | No | Results per page (default 20) |

### `get_graph_neighbors`

Get neighboring nodes and edges for a specific graph node

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | Node ID |
| `depth` | integer | No | Traversal depth (default 1, max 5) |
| `relation_types` | array | No | Filter by relation types |

### `graph_statistics`

Get knowledge graph statistics (node counts, edge counts, etc.)

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `get_subgraph`

Extract a subgraph containing the specified nodes and their connections

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_ids` | array | Yes | Array of node IDs |

### `extract_to_knowledge_graph`

Extract entities and relationships from text and add them to the knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to extract entities and relations from |
| `source_label` | string | No | Label for the extraction source |

---

## AI Safety & Autonomy

### `emergency_halt`

Emergency halt ALL AI activity for the account. Cancels running executions, pauses schedules, blocks LLM calls, and demotes all agents to supervised tier.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reason` | string | No | Reason for the emergency halt |

### `emergency_resume`

Resume AI activity after an emergency halt. 'full' mode restores agent trust tiers and schedules from pre-halt snapshot. 'minimal' mode only lifts the suspension.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string | No | Resume mode: 'full' (restore snapshot, default) or 'minimal' (lift suspension only) |

### `kill_switch_status`

Check if AI activity is currently suspended. Returns halted status, timestamp, and snapshot preview.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage
- **Parameters**: none

### `create_agent_goal`

Create a goal for an agent (self or managed)

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |
| `title` | string | Yes | Goal title |
| `description` | string | No | Goal description |
| `goal_type` | string | Yes | maintenance, improvement, creation, monitoring, feature_suggestion, reaction |
| `priority` | integer | No | 1 (highest) to 5 (lowest), default 3 |
| `parent_goal_id` | string | No | Parent goal ID for sub-goals |
| `success_criteria` | object | No | Machine-evaluable success criteria |

### `list_agent_goals`

List an agent's goals (introspection)

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |
| `status` | string | No | Filter: active, terminal |

### `update_agent_goal`

Update goal progress or status

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID to update |
| `progress` | number | No | Progress 0.0 to 1.0 |
| `status` | string | No | New status |

### `agent_introspect`

View own execution history, trust score, performance, and budget

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |

### `propose_feature`

Create a feature suggestion for human review

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Proposal title |
| `description` | string | Yes | Detailed description |
| `rationale` | string | No | Why this should be done |
| `priority` | string | No | low, medium, high, critical |
| `impact_assessment` | object | No | Scope, risk, effort |

### `send_proactive_notification`

Notify users about detected issues or suggestions

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Target user ID (omit for account owner) |
| `title` | string | Yes | Notification title |
| `message` | string | Yes | Notification body |
| `severity` | string | No | info, warning, error |

### `discover_claude_sessions`

Find active Claude Code MCP client sessions

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none
- **Parameters**: none

### `request_code_change`

Request code changes via workspace message to a Claude session

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | Yes | What code change is needed |
| `files_affected` | array | No | List of file paths |
| `priority` | string | No | low, medium, high |
| `evidence` | object | No | Supporting evidence |

### `create_proposal`

Formally propose a change for human review

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_type` | string | Yes | feature, knowledge_update, code_change, architecture, process_improvement, configuration |
| `title` | string | Yes | Proposal title |
| `description` | string | Yes | Detailed description |
| `rationale` | string | No | Why this should be done |
| `priority` | string | No | low, medium, high, critical |
| `proposed_changes` | object | No | Structured changes |

### `escalate`

Structured escalation when stuck or encountering issues

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Escalation title |
| `escalation_type` | string | Yes | stuck, error, budget_exceeded, approval_timeout, quality_concern, security_issue |
| `severity` | string | No | low, medium, high, critical |
| `context` | object | No | What was tried, error details, what is needed |

### `request_feedback`

Request user feedback on completed work

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Target user ID (omit for recent interactor) |
| `context_type` | string | No | Ai::AgentExecution, Ai::AgentProposal, etc. |
| `context_id` | string | No | ID of the context item |
| `message` | string | Yes | What feedback is being requested for |

### `report_issue`

Report a detected platform issue

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Issue title |
| `description` | string | Yes | Issue details |
| `severity` | string | No | info, warning, critical |
| `evidence` | object | No | Supporting data |

### `decompose_goal`

Decompose a goal into sub-goals using autonomous planning

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID to decompose |
| `max_sub_goals` | integer | No | Maximum sub-goals to create (default 5) |

### `validate_plan`

Validate a proposed plan for feasibility and safety

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID with the plan to validate |

### `approve_plan`

Approve a validated plan for execution

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID with the plan to approve |
| `notes` | string | No | Approval notes |

### `list_intervention_policies`

List intervention policies for the current account. Filterable by agent, action_category, is_active.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Filter by agent |
| `action_category` | string | No | Filter by action category |
| `is_active` | boolean | No | Filter by active flag |

### `create_intervention_policy`

Create a new intervention policy that gates autonomous actions for an agent (or all agents in scope).

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | string | Yes | global | agent | team |
| `ai_agent_id` | string | No | Agent (when scope=agent) |
| `action_category` | string | Yes | Action category to gate (e.g. system.module_assign) |
| `policy` | string | Yes | auto_approve | notify_and_proceed | require_approval | silent | block |
| `conditions` | object | No | JSON match conditions |
| `priority` | integer | No | Higher priority wins on conflict (default 0) |
| `approval_chain_id` | string | No | Approval chain UUID (when policy=require_approval) |

### `update_intervention_policy`

Update an existing intervention policy. Pass only the fields to change.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `policy_id` | string | Yes | Intervention policy UUID |
| `policy` | string | No | auto_approve | notify_and_proceed | require_approval | silent | block |
| `conditions` | object | No | Merged into existing conditions |
| `priority` | integer | No | Higher priority wins on conflict |
| `is_active` | boolean | No | Enable or disable this policy |

### `delete_intervention_policy`

Permanently delete an intervention policy.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `policy_id` | string | Yes | Intervention policy UUID |

### `list_deferred_operations`

List deferred operations (queued autonomous actions awaiting approval or completion).

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | pending | approved | rejected | completed | failed |
| `agent_id` | string | No | Filter by agent |
| `limit` | integer | No | Max results (default 25, max 100) |

### `approve_deferred_operation`

Approve a pending deferred operation via the approval workflow. Triggers the underlying ApprovalRequest's approve path which will execute the action when the final step approves.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deferred_operation_id` | string | Yes | DeferredOperation UUID OR ApprovalRequest UUID |
| `comments` | string | No | Optional approval comment |

### `reject_deferred_operation`

Reject a pending deferred operation. Sets the request to rejected and the deferred op never executes.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deferred_operation_id` | string | Yes | DeferredOperation UUID OR ApprovalRequest UUID |
| `comments` | string | No | Reason for rejection (recommended) |

### `generate_self_challenge`

Generate a self-challenge for an agent to practice and improve

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | No | Skill to challenge (optional) |
| `difficulty` | string | No | Difficulty level: easy, medium, hard, expert |

### `list_challenges`

List self-challenges for the current agent

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status |
| `limit` | integer | No | Max results (default 20) |

### `get_challenge_result`

Get detailed result for a specific self-challenge

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `challenge_id` | string | Yes | Challenge ID |

### `mutate_skill`

Mutate a skill using a specified strategy to improve it

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID to mutate |
| `strategy` | string | Yes | Mutation strategy: learning_driven, failure_analysis, challenge_derived, peer_comparison |

### `compose_skills`

Create a composite skill from multiple component skills

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `component_skill_ids` | array | Yes | Array of skill IDs to compose |
| `name` | string | Yes | Name for the composite skill |
| `strategy` | string | No | Composition strategy: sequential, parallel, conditional |

### `auto_evolve_skill`

Automatically find and mutate underperforming skills

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `threshold` | number | No | Effectiveness threshold (default 0.4) |

### `governance_scan`

Run a governance scan on a specific agent or team

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent to scan |
| `team_id` | string | No | Team to scan |

### `list_governance_reports`

List governance reports with optional filters

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status |
| `severity` | string | No | Filter by severity |
| `agent_id` | string | No | Filter by agent |
| `limit` | integer | No | Max results |

### `get_governance_report`

Get detailed governance report

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `report_id` | string | Yes | Report ID |

### `resolve_governance_report`

Resolve a governance report with a status and notes

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `report_id` | string | Yes | Report ID |
| `resolution_status` | string | Yes | Resolution: confirmed, dismissed, remediated |
| `notes` | string | No | Resolution notes |

### `detect_collusion`

Run collusion detection across active agents

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none
- **Parameters**: none

### `governance_dashboard`

Get governance dashboard with summary metrics

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none
- **Parameters**: none

### `emit_signal`

Emit a stigmergic signal (pheromone, pressure, beacon, warning, discovery) for decentralized coordination

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_type` | string | Yes | Signal type: pheromone, pressure, beacon, warning, discovery |
| `signal_key` | string | Yes | Namespaced signal key |
| `strength` | number | No | Signal strength 0-1 (default 1.0) |
| `decay_rate` | number | No | Decay rate per cycle (default 0.05) |
| `payload` | object | No | Signal payload data |
| `ttl_seconds` | integer | No | Time-to-live in seconds |

### `perceive_signals`

Perceive active stigmergic signals, optionally filtered by type

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_types` | array | No | Filter by signal types |
| `limit` | integer | No | Max signals to return (default 20) |

### `reinforce_signal`

Reinforce an existing stigmergic signal (ant-trail reinforcement pattern)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_id` | string | Yes | Signal ID to reinforce |
| `strength_delta` | number | No | Reinforcement amount (default 0.1) |

### `measure_pressure`

Measure a pressure field on an artifact (code_quality, test_coverage, etc.)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `artifact_ref` | string | Yes | Artifact reference (e.g., file path, module name) |
| `artifact_type` | string | No | Artifact type (e.g., file, module, service) |
| `field_type` | string | Yes | Field type: code_quality, test_coverage, doc_readability, security_posture, performance, dependency_health |

### `perceive_pressure`

Perceive actionable pressure fields sorted by highest pressure

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | No | Filter by team context |
| `limit` | integer | No | Max fields to return (default 10) |

### `optimize_team`

Run full team composition optimization (gap detection, leader emergence, member rebalancing)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team ID to optimize |

### `recruit_agent`

Recruit an agent into a team to fill a capability gap

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team ID to recruit into |
| `capability` | string | Yes | Required capability |

---

## Activity Monitoring

### `get_activity_feed`

Get a unified activity feed of recent missions, conversations, execution events, and errors across the platform

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hours` | integer | No | Lookback window in hours (default 24, max 168) |
| `limit` | integer | No | Max items per category (default 10, max 50) |

### `get_mission_status`

Get mission status. Without mission_id: all in-progress missions with approval gates. With mission_id: full mission details.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | No | Specific mission ID for full details (omit for overview) |

### `get_notifications`

Get notifications for the current user. Defaults to active+unread (default 10, max 50). Filterable by category, type, source_type, before timestamp, or unread_only=false to include read.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max notifications to return (default 10, max 50) |
| `category` | string | No | Filter by category (e.g. ai, system, security) |
| `type` | string | No | Filter by notification type (e.g. autonomy_approval_required, ai_concierge_message) |
| `source_type` | string | No | Filter by metadata.source_type (e.g. system_fleet, system_cve_responder) |
| `before` | string | No | Only return notifications created before this ISO8601 timestamp |
| `unread_only` | boolean | No | Restrict to unread (default true) |

### `dismiss_notification`

Mark a notification as read

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `notification_id` | string | Yes | ID of the notification to dismiss |

### `dismiss_all_notifications`

Dismiss all active notifications permanently (sets dismissed_at). Returns count of dismissed.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `mark_all_notifications_read`

Mark all unread notifications as read (lighter than dismiss — still visible but marked as read). Returns count.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `get_system_health`

Get a lightweight system health snapshot: active counts, approval queues, error rates, and provider status

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

---

## System Health

### `integration_health`

Check the health status of integrations for the current account. Returns status, last check time, and failure count for each integration instance.

- **Tool class**: `Ai::Tools::IntegrationHealthTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `integration_type` | string | No | Filter by integration type (e.g., 'gitea', 'github', 'slack') |
| `health_status` | string | No | Filter by health status: 'healthy', 'degraded', 'unhealthy', 'unknown' |

---

## Image Generation

### `generate_image`

Generate an image using DALL-E 3 AI model. Returns the generated image file with metadata including the revised prompt.

- **Tool class**: `Ai::Tools::ImageGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Detailed description of the image to generate |
| `size` | string | No | Image size: 1024x1024, 1024x1792, 1792x1024 (default: 1024x1024) |
| `quality` | string | No | Image quality: standard, hd (default: hd) |
| `style` | string | No | Image style: vivid, natural (default: vivid) |
| `model` | string | No | Model: dall-e-3 (default: dall-e-3) |
| `filename` | string | No | Output filename (auto-generated if omitted) |

### `list_generated_images`

List AI-generated images in the current account

- **Tool class**: `Ai::Tools::ImageGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results (default: 20) |

---

## Docker Management

### `docker_list_containers`

List all containers on a Docker host with their status, image, and ports

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_get_container`

Get detailed information about a specific container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_create_container`

Create a new Docker container on a host. `runtime` sets the OCI runtime (e.g. 'runsc' for gVisor isolation, substrate L0) via HostConfig.Runtime — the runtime must be registered on the host's Docker daemon.

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `name` | string | Yes | Container name |
| `image` | string | Yes | Docker image to use |
| `env` | array | No | Environment variables as KEY=VALUE strings |
| `runtime` | string | No | OCI runtime for isolation (e.g. 'runsc' for gVisor) — sets HostConfig.Runtime |
| `params` | object | No | Additional Docker container parameters |

### `docker_start_container`

Start a stopped container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_stop_container`

Stop a running container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `timeout` | integer | No | Seconds to wait before killing (default: 10) |

### `docker_restart_container`

Restart a container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `timeout` | integer | No | Seconds to wait before killing (default: 10) |

### `docker_delete_container`

Remove a container (must be stopped unless force is true)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `force` | boolean | No | Force removal of running container |

### `docker_container_logs`

Retrieve logs from a container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `tail` | string | No | Number of lines from the end (default: 100) |
| `since` | string | No | Show logs since timestamp or duration (e.g. '10m') |

### `docker_container_stats`

Get real-time resource usage statistics for a container (CPU, memory, network I/O)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_container_exec`

Execute a command inside a running container (non-interactive, 100KB output limit)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `command` | array | Yes | Command and arguments, e.g. ['ls', '-la', '/app'] |
| `working_dir` | string | No | Working directory inside the container |
| `env` | array | No | Additional environment variables as KEY=VALUE |

### `docker_list_services`

List all Swarm services on a cluster with replica counts and health

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_get_service`

Get detailed information about a specific Swarm service

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_create_service`

Create a new Swarm service with specified image, replicas, ports, and environment

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_name` | string | Yes | Service name |
| `image` | string | Yes | Docker image |
| `replicas` | integer | No | Number of replicas (default: 1) |
| `mode` | string | No | replicated or global (default: replicated) |
| `environment` | array | No | Environment variables as KEY=VALUE |
| `ports` | array | No | Port mappings [{target: 80, published: 8080}] |
| `constraints` | array | No | Placement constraints |
| `labels` | object | No | Service labels |
| `resource_limits` | object | No | Resource limits |
| `resource_reservations` | object | No | Resource reservations |

### `docker_update_service`

Update a Swarm service's configuration (image, env, constraints, etc.)

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `image` | string | No | New Docker image |
| `environment` | array | No | New environment variables |
| `constraints` | array | No | New placement constraints |
| `labels` | object | No | New labels |
| `resource_limits` | object | No | New resource limits |

### `docker_scale_service`

Scale a Swarm service to a specific number of replicas

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `replicas` | integer | Yes | Desired number of replicas |

### `docker_rollback_service`

Rollback a Swarm service to its previous version

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_delete_service`

Remove a Swarm service and its tasks

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_service_logs`

Retrieve logs from a Swarm service (aggregated from all tasks)

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `tail` | string | No | Number of lines from the end (default: 100) |

### `docker_service_tasks`

List tasks (containers) for a Swarm service with their status and node placement

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_list_stacks`

List all Swarm stacks on a cluster with status, service count, and deployment history

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_get_stack`

Get detailed information about a stack including compose file and variables

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | Yes | Stack UUID, slug, or name |

### `docker_deploy_stack`

Deploy or redeploy a stack from a Docker Compose YAML file. Provide compose_file for new stacks, or stack_id to redeploy an existing stack.

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | No | Existing stack to redeploy (UUID, slug, or name) |
| `stack_name` | string | No | Stack name (required for new stacks) |
| `compose_file` | string | No | Docker Compose YAML content |
| `compose_variables` | object | No | Variable substitutions (e.g. {"IMAGE_TAG": "latest"}) |

### `docker_delete_stack`

Remove a stack and all its services from the cluster

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | Yes | Stack UUID, slug, or name |

### `docker_adopt_stack`

Adopt an existing Docker stack that was deployed outside Powernode. Tags its services as managed and creates a stack record.

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_name` | string | Yes | Name of the Docker stack to adopt (the com.docker.stack.namespace label) |

### `docker_list_clusters`

List all Swarm clusters registered in the account with connection status

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read
- **Parameters**: none

### `docker_get_cluster`

Get detailed information about a Swarm cluster including node/service counts

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Swarm cluster ID, slug, or name |

### `docker_cluster_health`

Run a comprehensive health check on a Swarm cluster: node status, service health, alerts

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_list_nodes`

List all nodes in a Swarm cluster with role, availability, and resource info

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_node_promote`

Promote a worker node to manager role

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_demote`

Demote a manager node to worker role

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_drain`

Drain a node (stop scheduling tasks, migrate existing tasks to other nodes)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_activate`

Activate a drained node (resume task scheduling)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_list_secrets`

List all secrets in a Swarm cluster (metadata only, not secret data)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_create_secret`

Create a new secret in the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Secret name |
| `data` | string | Yes | Secret data (will be base64 encoded) |
| `labels` | object | No | Secret labels |

### `docker_delete_secret`

Remove a secret from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `secret_id` | string | Yes | Docker secret ID |

### `docker_list_configs`

List all configs in a Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_create_config`

Create a new config in the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Config name |
| `data` | string | Yes | Config data (will be base64 encoded) |
| `labels` | object | No | Config labels |

### `docker_delete_config`

Remove a config from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `config_id` | string | Yes | Docker config ID |

### `docker_list_hosts`

List all Docker hosts registered in the account with connection status and resource counts

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read
- **Parameters**: none

### `docker_get_host`

Get detailed information about a Docker host including OS, resources, and Docker version

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Docker host ID, slug, or name |

### `docker_sync_host`

Synchronize a Docker host: fetch containers and images from the Docker daemon and update local records

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_test_host`

Test the connection to a Docker host and return system information

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_list_images`

List all Docker images on a host with tags, size, and creation time

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_pull_image`

Pull a Docker image from a registry to a host

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image` | string | Yes | Image name (e.g. 'nginx', 'registry.example.com/myorg/myimage') |
| `tag` | string | No | Image tag (default: latest) |
| `credential_id` | string | No | Registry credential ID for authenticated pulls |

### `docker_delete_image`

Remove a Docker image from a host

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image_id` | string | Yes | Image UUID or docker_image_id |
| `force` | boolean | No | Force removal even if in use |

### `docker_tag_image`

Tag a Docker image with a new repository and tag

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image_id` | string | Yes | Image UUID or docker_image_id |
| `repo` | string | Yes | New repository name |
| `tag` | string | Yes | New tag |

### `docker_list_networks`

List all networks on a Swarm cluster with driver, scope, and attachment info

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_create_network`

Create a new overlay network on the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Network name |
| `driver` | string | No | Network driver (default: overlay) |
| `attachable` | boolean | No | Allow containers to attach (default: true) |
| `internal` | boolean | No | Internal network only (default: false) |
| `labels` | object | No | Network labels |

### `docker_delete_network`

Remove a network from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `network_id` | string | Yes | Docker network ID or name |

### `docker_list_volumes`

List all volumes on a Swarm cluster with driver and mount point info

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_create_volume`

Create a new volume on the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Volume name |
| `driver` | string | No | Volume driver (default: local) |
| `labels` | object | No | Volume labels |

### `docker_delete_volume`

Remove a volume from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `volume_name` | string | Yes | Docker volume name |

---

## Uncategorized

### `system_assign_storage_owner`

Set the owner of a StorageAssignment. For owner_kind=service_user, supply service_user_username — the platform looks up (or auto-allocates via Identity::UserAllocator) the matching ServiceUser. For operator/nobody/root, only owner_kind is required. Optional shared_group_groupname overrides the default anongid (the owner's primary group) for multi-service write-shared mounts. Triggers an automatic chown task on the storage provider node; the NFS export keeps using the OLD anonuid until the chown completes to avoid EACCES storms on consuming services.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | UUID of the StorageAssignment whose owner is being set |
| `owner_kind` | string | Yes | service_user | operator | nobody | root |
| `service_user_username` | string | No | Required when owner_kind=service_user |
| `shared_group_groupname` | string | No | Optional override of anongid for shared-write mounts |

### `system_list_storage_assignments_by_owner`

List StorageAssignments filtered by owner_kind, service_user_username, chown_state, or node_instance_id. Use for ops audits like "which assignments still use owner_kind=root?" or "show me every chown that's stuck in failed across the fleet".

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner_kind` | string | No | Filter by owner kind: service_user | operator | nobody | root |
| `service_user_username` | string | No | Filter by the owning ServiceUser's username |
| `node_instance_id` | string | No | Filter by the storage provider NodeInstance UUID |
| `chown_state` | string | No | complete | pending | running | failed | manual_required |

### `system_storage_chown_status`

Inspect chown state of a StorageAssignment — current state, previous_uid/gid (if in flight), task id, start/complete timestamps, recorded error.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | UUID of the StorageAssignment whose chown status to inspect |

### `system_storage_chown_retry`

Re-dispatch a failed or manual_required chown. Resets chown_last_error and transitions back to pending — the after_commit dispatch hook then queues a fresh task. Pass force_complete: true as an escape hatch for cases where the operator has manually chowned the files (e.g. on an external NFS provider the platform can't reach) and wants to flip the assignment to complete without re-running.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | UUID of the StorageAssignment whose failed/manual_required chown to re-dispatch |
| `force_complete` | boolean | No | Escape hatch: flip the assignment to complete without re-running (use after a manual chown) |

### `system_blast_radius`

Infrastructure blast-radius: given a fleet node (System::Node name, System::NodeInstance name, or a bare provider cluster-node token like "dna"/"rna"), derive what currently depends on it — SDWAN peers/VIPs/services/port-mappings, instance-pool membership, direct + cross-node storage assignments, and other node_instance_id FK dependents.

- **Tool class**: `Ai::Tools::SystemBlastRadiusTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node` | string | Yes | Fleet node identifier: a System::Node#name, a System::NodeInstance#name, or a provider cluster-node token (e.g. "dna") embedded in cloud_instance_id |

### `system_reverse_proxy_compose`

Regenerate the reverse-proxy (Traefik) dynamic config so the platform serves an issued ACME certificate. The certificate must already be valid.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | System::AcmeCertificate id (status must be valid) |

### `system_expose_service_publicly`

Expose a service to the public internet end-to-end: create/reuse an SDWAN VIP, port-map it on the hub, provision a TLS certificate for the hostname, and regenerate the reverse proxy.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_hostname` | string | Yes | Public FQDN to serve the service on (certificate CN) |
| `service_protocol` | string | Yes | http | https |
| `sdwan_network_id` | string | Yes | Sdwan::Network to host the VIP |
| `sdwan_hub_peer_id` | string | Yes | Sdwan::Peer acting as the DNAT hub |
| `vip_cidr` | string | Yes | Operator-supplied host CIDR for the VIP (typically /128 v6 or /32 v4) within the network's /64 |
| `backend_port` | integer | Yes | Backend service port to route public traffic to |
| `target_peer_id` | string | No | Sdwan::Peer hosting the backend (mutually exclusive with target_instance_id) |
| `target_instance_id` | string | No | System::NodeInstance hosting the backend (mutually exclusive with target_peer_id) |
| `tls_issuer` | string | No | ACME issuer (default letsencrypt-prod) |
| `challenge_type` | string | No | ACME challenge (default dns-01) |
| `dns_credential_id` | string | No | System::AcmeDnsCredential id (for dns-01) |

### `system_expose_service_local`

Expose a backend service locally at /svc/<slug> on the platform's own host(s), authenticated by the reverse proxy (ForwardAuth). Creates or updates the Sdwan::Service and enables its local-exposure facet. Approval-gated. For the public internet use system_expose_service_publicly instead.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | No | Existing Sdwan::Service id to expose (omit to create from the fields below) |
| `slug` | string | No | URL slug for /svc/<slug> (required when creating) |
| `name` | string | No | Service display name (required when creating) |
| `protocol` | string | No | Backend protocol: https | http (default https) |
| `backend_vip_id` | string | No | Sdwan::VirtualIp id of the overlay backend (this or backend_host when creating) |
| `backend_host` | string | No | Static backend host/IP (this or backend_vip_id when creating) |
| `backend_port` | integer | No | Backend port (required when creating) |
| `auth_mode` | string | No | public | authenticated | scoped (default authenticated) |
| `required_permission` | string | No | Permission required for scoped mode |
| `required_group` | string | No | Group/role required for scoped mode |
| `strip_prefix` | boolean | No | Strip /svc/<slug> before proxying (default true) |
| `certificate_id` | string | No | System::AcmeCertificate id whose CN to mount under (default: account primary) |

### `system_acme_provision_certificate`

Provision (issue) an ACME TLS certificate for a hostname; the issued cert is stored as a System::AcmeCertificate.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `common_name` | string | Yes | Primary CN / FQDN for the certificate |
| `issuer` | string | Yes | letsencrypt-prod | letsencrypt-staging | internal-ca |
| `challenge_type` | string | Yes | dns-01 | http-01 | tls-alpn-01 |
| `sans` | array | No | Additional Subject Alternative Names (FQDNs) |
| `dns_credential_id` | string | No | System::AcmeDnsCredential id (required for dns-01) |
| `acme_email` | string | No | ACME registration contact email |

### `system_create_service`

Create an Sdwan::Service (identity + overlay backend). Does NOT expose it — use system_expose_service_local to publish it at /svc/<slug>, or system_expose_service_public_tcp for Path B public TLS-carrying TCP. edge_mode/client_auth may be pre-provisioned here; public_enabled itself is owned by system_expose_service_public_tcp / system_unexpose_service_public_tcp, not this action.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | URL slug (lowercase alnum + hyphen, <=64, not a reserved platform path) |
| `name` | string | Yes | Service display name |
| `backend_port` | integer | Yes | Backend service port (1-65535) |
| `protocol` | string | No | https | http | tcp | tls (default https) |
| `backend_vip_id` | string | No | Sdwan::VirtualIp id of the overlay backend (this or backend_host) |
| `backend_host` | string | No | Static backend host/IP (this or backend_vip_id) |
| `status` | string | No | active | disabled (default active) |
| `edge_mode` | string | No | Path B TLS-carrying TCP: passthrough | terminate (default passthrough; inert until public_enabled) |
| `client_auth` | string | No | Path B mTLS enforcement: none | required (default none; required needs edge_mode terminate) |

### `system_list_services`

List this account's Sdwan::Service records, newest first.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status (active | disabled) |
| `local_enabled` | boolean | No | Filter by local-exposure state |
| `public_enabled` | boolean | No | Filter by public (Path B) exposure state |

### `system_get_service`

Fetch a single Sdwan::Service by id (scoped to this account).

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id |

### `system_update_service`

Update an Sdwan::Service's identity + backend plumbing (name, protocol, status, backend, Path B edge_mode/client_auth). Exposure semantics (local_enabled, auth mode, and public_enabled) are NOT settable here. local_enabled is owned by system_expose_service_local; public_enabled (Path B) is owned by system_expose_service_public_tcp / system_unexpose_service_public_tcp — deliberately not settable through this CRUD action in either direction. Regenerates the reverse proxy when the service is locally and/or publicly exposed.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id |
| `name` | string | No | New display name |
| `protocol` | string | No | https | http | tcp | tls |
| `status` | string | No | active | disabled |
| `backend_vip_id` | string | No | New overlay backend VIP id |
| `backend_host` | string | No | New static backend host/IP |
| `backend_port` | integer | No | New backend port |
| `edge_mode` | string | No | Path B TLS-carrying TCP: passthrough | terminate |
| `client_auth` | string | No | Path B mTLS enforcement: none | required (required needs edge_mode terminate) |

### `system_delete_service`

Delete an Sdwan::Service. Regenerates the reverse proxy if the service was locally exposed (removing its /svc/<slug> route).

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id |

### `system_unexpose_service_local`

Disable a service's local /svc/<slug> exposure (fail-safe off — no approval needed) and regenerate the reverse proxy. The Sdwan::Service record is kept; re-expose with system_expose_service_local.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id |

### `system_expose_service_public_tcp`

Enable a service's public (Path B) TLS-carrying TCP exposure via Traefik HostSNI routing — validates protocol tls, a resolvable host, and (under edge_mode terminate) a matching valid ACME certificate, then flips public_enabled on and regenerates the reverse proxy. Approval-gated; the sole owner of turning Path B ON (in either direction — see system_unexpose_service_public_tcp).

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id (protocol must be tls) |

### `system_unexpose_service_public_tcp`

Disable a service's public (Path B) TLS-carrying TCP exposure and regenerate the reverse proxy. Approval-gated (unlike the fail-safe, no-approval system_unexpose_service_local) — the sole owner of turning Path B OFF; system_update_service refuses public_enabled in either direction.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_id` | string | Yes | Sdwan::Service id |

### `system_acme_get_certificate`

Fetch a single ACME certificate's non-secret detail (status, issuer, expiry, vault_paths_present). NEVER returns PEMs, private keys, or Vault secret values.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | UUID of the ACME certificate to fetch |

### `system_acme_renew_certificate`

Renew an ACME certificate currently in status=valid. Drives valid → renewing → valid via Acme::CertificateManager.renew!. Returns the reloaded non-secret cert detail on success.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | UUID of the ACME certificate to renew (must be in status=valid) |

### `system_acme_revoke_certificate`

Revoke a non-terminal ACME certificate via Acme::CertificateManager.revoke!. Drives any non-terminal status → revoked. Optionally records a revocation reason.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | UUID of the non-terminal ACME certificate to revoke |
| `reason` | string | No | Optional ACME revocation reason |

### `system_acme_create_dns_credential`

Register a new ACME DNS-01 provider credential (Cloudflare, Route53, etc.). The provider API token in `credentials` is handed straight to Vault — NEVER stored on the model, logged, or returned. The result serializes only the public index (name, provider, status).

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable name for the DNS-01 credential record |
| `provider` | string | Yes | DNS provider slug (cloudflare|route53|gcloud|digitalocean|hetzner|porkbun|ovh) |
| `credentials` | object | Yes | Provider-specific secret token fields (SENSITIVE — stored in Vault only) |
| `metadata` | object | No | Optional non-secret metadata stored on the credential record |

### `system_list_nodes`

List all nodes for the current account

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | No | Optional NodeTemplate UUID to filter nodes by their bound template |

### `system_get_node`

Fetch a node by id

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | UUID of the node to fetch (account-scoped) |

### `system_create_node`

Create a new node bound to a template

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new node |
| `template_id` | string | Yes | UUID of the NodeTemplate to bind the node to |

### `system_update_node`

Update a node's mutable attributes (rename, enable/disable, retarget template/worker, public-address config). Does NOT accept SSH key material — manage keys via the REST/Vault path.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | UUID of the node to update (account-scoped) |
| `name` | string | No | New display name for the node |
| `description` | string | No | New free-text description for the node |
| `enabled` | boolean | No | Enable (true) or disable (false) the node |
| `node_template_id` | string | No | UUID of a NodeTemplate to retarget the node to |
| `worker_id` | string | No | UUID of the Worker that services this node's tasks |
| `public_address` | string | No | Public hostname or IP to reach the node at |
| `allocate_public_ip` | boolean | No | When true, request a public IP allocation for the node |
| `config` | object | No | Arbitrary node config hash (merged into the node record) |

### `system_delete_node`

Hard-destroy a Node. Cascades node_instances, node_module_assignments, and tasks via dependent:destroy. FK-blocked if instances have unhandled SDWAN/bootstrap_token references — use system_destroy_instance first per instance, then this.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | UUID of the node to hard-destroy (account-scoped) |

### `system_delete_template`

Delete a NodeTemplate. Restricted: errors if any Node uses this template (System::NodeTemplate has dependent::restrict_with_error on nodes).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to delete (account-scoped) |

### `system_update_template`

Update mutable NodeTemplate fields: name, description.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to update (account-scoped) |
| `name` | string | No | New display name for the template |
| `description` | string | No | New free-text description for the template |

### `system_delete_module`

Delete a NodeModule. Cascades child_modules, versions, node_module_assignments, template_modules, module_puppet_assignments, module_dependencies.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | UUID of the NodeModule to delete (account-scoped) |

### `system_refresh_instance_modules`

Force re-apply all assigned modules to an instance — queues a reconcile task. Useful when instance has drifted from desired template state.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance whose modules to re-apply |

### `system_list_instances`

List instances (filterable by node_id or template_id)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | No | Optional node UUID to list only that node's instances |
| `template_id` | string | No | Optional NodeTemplate UUID to list instances of nodes on that template |

### `system_get_instance`

Fetch a node instance with its current status + metrics

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to fetch (account-scoped) |

### `system_find_node_with_gpu`

Find live node instances that expose a GPU/accelerator, optionally filtered by gpu_type, a minimum per-GPU VRAM (min_gpu_memory_mb), and a minimum GPU count. GPU is resolved from the instance's provider_instance_type SKU or its agent-reported config["gpu"] hint.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gpu_type` | string | No | Filter to a specific GPU/accelerator type (case-insensitive, e.g. 'A100') |
| `min_gpu_memory_mb` | integer | No | Minimum per-GPU VRAM in megabytes the instance must have |
| `min_gpu_count` | integer | No | Minimum number of GPUs the instance must expose (defaults to 1) |

### `system_list_instance_types_by_gpu`

List provider instance-type catalog SKUs that carry a GPU, optionally filtered by gpu_type and a minimum GPU count. Use to pick a GPU SKU for provisioning.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gpu_type` | string | No | Filter SKUs to a specific GPU/accelerator type |
| `min_gpu_count` | integer | No | Minimum number of GPUs the SKU must carry (defaults to 1) |

### `system_deploy_inference_server`

Deploy an inference runtime (ollama) onto a GPU node and make it consumable: assigns the gpu-<accelerator>-runtime + inference-ollama modules, registers an ollama Ai::Provider at the endpoint (active only once the endpoint answers a health probe — modules apply asynchronously, so re-deploy after the runtime is up to activate), and optionally publishes an SDWAN service offering. Targets a node by instance_id (must be live + GPU-capable unless force), or auto-selects via gpu_type/min_gpu_memory_mb. Pass endpoint_override to point at an existing ollama (e.g. for smoke).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | No | UUID of the target GPU NodeInstance; omit to auto-select via gpu_type/min_gpu_memory_mb |
| `gpu_type` | string | No | GPU/accelerator type to match when auto-selecting a target instance |
| `min_gpu_memory_mb` | integer | No | Minimum per-GPU VRAM (MB) when auto-selecting a target instance |
| `model` | string | No | Inference model tag to pull/serve on the ollama runtime |
| `endpoint_override` | string | No | Point the registered ollama provider at an existing endpoint URL instead of deploying (e.g. for smoke tests) |
| `sdwan_network_id` | string | No | UUID of an SDWAN network to publish the inference service offering on |
| `vip_cidr` | string | No | CIDR for the SDWAN virtual IP to front the published inference service |
| `accelerator` | string | No | Runtime accelerator family — selects the gpu-<accelerator>-runtime module (default nvidia) |
| `force` | boolean | No | Bypass the terminated/GPU gating on an explicit instance_id |

### `system_grant_instance_mcp_tools`

Grant an instance-agent the MCP tool-name glob patterns it may invoke on the platform MCP (default-deny: an instance can call nothing until granted). Patterns match the 'platform.<tool>' name, e.g. 'platform.system_*_read' or 'platform.health'. mode: 'replace' (default) or 'add'. The instance must have announced as a peer.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the instance (announced peer) to grant MCP tool access to |
| `tool_patterns` | array | Yes | Glob patterns matching 'platform.<tool>' names the instance may invoke (e.g. ['platform.system_*_read']) |
| `mode` | string | No | 'replace' (default) to overwrite the grant list, or 'add' to append |

### `system_grant_instance_peer_skills`

A2A: grant an instance-agent the peer skill-name glob patterns it may invoke on OTHER instances via agent-to-agent MCP (default-deny). Patterns match a peer's offered skill name, e.g. 'embed-*' or 'summarize'. mode: 'replace' (default) or 'add'. The instance must have announced as a peer.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the instance (announced peer) to grant peer-skill call access to |
| `skill_patterns` | array | Yes | Glob patterns matching peer-offered skill names the instance may invoke via A2A (e.g. ['embed-*', 'summarize']) |
| `mode` | string | No | 'replace' (default) to overwrite the grant list, or 'add' to append |

### `system_discover_peers`

A2A: list the online, operator-enabled agent peers in the account and the skills they offer (capability discovery). Pass instance_id to discover from a specific caller's perspective (excludes itself). Discovery does not imply call permission — the call is still gated by system_authorize_peer_call.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | No | Optional caller instance UUID to discover from its perspective (excludes itself) |

### `system_authorize_peer_call`

A2A: decide whether a caller instance may invoke a skill on a target instance via agent-to-agent MCP (three-gate, default-deny: caller granted + target online/enabled + target offers skill + same account). Returns { authorized, reason }. Consulted by the on-node A2A transport before relaying a call.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `caller_instance_id` | string | Yes | UUID of the instance attempting the A2A call |
| `target_instance_id` | string | Yes | UUID of the instance the skill would be invoked on |
| `skill` | string | Yes | Name of the peer skill the caller wants to invoke on the target |

### `system_launch_agent_fleet`

L3: launch an agent-fleet orchestration mission — dynamically provision a fleet of agent-instances, grant them L2 (platform-MCP) + L2.5 (A2A) capabilities, delegate subtasks (hybrid coordinator + peer sub-delegation), aggregate, and reap. Creates an approval-gated Ai::Mission (mission_type: agent_fleet) bound to the system_agent_fleet template and starts it; the operator approves the review_fleet gate before any instances are provisioned. fleet_spec: { size, source('provision'|'pool'), node_id, provider_region_id, provider_instance_type_id, pool_name, grant_mcp_tools[], grant_peer_skills[], member_skills[], subtasks[{id,skill}], delegation('central'|'a2a'|'hybrid'), reap }.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fleet_spec` | object | Yes | Fleet orchestration spec: { size, source, node_id, provider_region_id, provider_instance_type_id, pool_name, grant_mcp_tools[], grant_peer_skills[], member_skills[], subtasks[], delegation, reap } |
| `name` | string | No | Display name for the agent-fleet mission |
| `objective` | string | No | Free-text objective/goal for the fleet mission |

### `system_agent_fleet_status`

L3: inspect an agent-fleet mission — returns status, current_phase, error_message, and a summary of the fleet (plan, member/assignment counts, aggregated report, per-member reap actions, reap_incomplete flag).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | UUID of the agent-fleet Ai::Mission to inspect |

### `system_reap_agent_fleet`

L3: re-run reap for a failed/stuck agent-fleet mission — returns pool members, terminates provisioned members, disables their peers. Safe to retry; reports per-member actions and a reap_incomplete flag when any member fails to terminate. Pass force:true to reap a fleet whose plan disabled reaping.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | UUID of the agent-fleet Ai::Mission to re-reap |
| `force` | boolean | No | Reap even when the fleet plan set reap:false |

### `system_mint_peer_capability_token`

A2A: mint an Ed25519-signed capability token proving caller_instance may invoke `skill` on target_instance via agent-to-agent MCP. GATED on the 4-gate A2A policy (PeerCapabilityService.authorize) — only issued if the call is authorized. The on-node A2A MCP server verifies the token's signature OFFLINE against the advertised public key (no per-call platform round-trip). Short-lived (default 5 min). Returns { envelope, signature, handle, public_key, expires_at, sub, aud, skill, jti }.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `caller_instance_id` | string | Yes | UUID of the instance the token authorizes to make the call (token subject) |
| `target_instance_id` | string | Yes | UUID of the instance the token authorizes the call against (token audience) |
| `skill` | string | Yes | Name of the peer skill the minted token authorizes |
| `ttl_seconds` | integer | No | Default 300; clamped to 1..3600 (MAX_TTL_SECONDS) — revocation propagates via the agents' capability_keys pull, so token lifetime is hard-capped |

### `system_list_isolation_tiers`

L0: list the isolation tiers an agent deployment can request (native | gvisor | kata | firecracker | vm) with their Docker runtime / K8s RuntimeClass mapping, isolation strength, overhead, and host requirements. Pass isolation_tier inside a fleet_spec (system_launch_agent_fleet) to select one (default native).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_provision_instance`

Provision a new cloud instance for a node (asynchronous; returns task_id). Agents SHOULD send a stable operation_id per logical request — retries carrying the same operation_id reuse the in-flight instance instead of provisioning a duplicate.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | UUID of the node to provision a cloud instance for |
| `provider_region_id` | string | Yes | UUID of the ProviderRegion to place the instance in |
| `provider_instance_type_id` | string | Yes | UUID of the ProviderInstanceType (SKU) to provision |
| `operation_id` | string | No | Stable idempotency key per logical provision request |
| `options` | object | No | Per-provider provisioning options passed through to the adapter |

### `system_terminate_instance`

Terminate an instance (cleanly destroys cloud resource + transitions to :terminated). Use system_destroy_instance to fully remove a registry row that has no live cloud resource.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to terminate (destroys the cloud resource) |

### `system_destroy_instance`

Hard-destroy a NodeInstance registry row, walking known FK dependents (sdwan_peers + sub-tables, system_bootstrap_tokens, system_node_certificates, system_node_modules, system_storage_assignments, billing_provisioning_usage_records, etc.). Use ONLY for ghost rows: cloud_instance_id is null OR the provider resource is already gone. Irreversible. Does NOT call the provider to destroy a live VM — pair with system_terminate_instance for that.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance registry row to hard-destroy (ghost rows only) |

### `system_start_instance`

Start a stopped instance (cloud adapter or physical SSH/IPMI path). The restart counterpart to system_stop_instance.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to start |
| `operation_id` | string | No | System operation id to attribute this control action to |
| `force` | boolean | No | Force the start even if the instance is not in a cleanly stopped state |

### `system_stop_instance`

Stop a running instance WITHOUT terminating it — disk and registry row are retained, compute billing stops on most cloud providers. The cost-control lever for idle GPU instances; restart with system_start_instance.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to stop |
| `operation_id` | string | No | System operation id to attribute this control action to |
| `force` | boolean | No | Force-stop the instance (hard power-off) instead of a graceful shutdown |

### `system_reboot_instance`

Reboot a hung or misbehaving instance in place (no reprovision, addresses retained).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to reboot |
| `operation_id` | string | No | System operation id to attribute this control action to |
| `force` | boolean | No | Force a hard reset instead of a graceful reboot |

### `system_upgrade_boot_image`

Trigger an in-place boot-image (UKI) upgrade on a NodeInstance to its platform's currently promoted disk image (campaign 019f505f). Queues an agent task that pulls + cosign-verifies the target UKI, writes the ESP, and reboots — reusing the /persist cert (no re-enroll). Refuses if the platform has no promoted image or cosign trust is not configured. No-op if already current.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to upgrade |
| `force` | boolean | No | Queue the upgrade even if the node already reports the promoted git_sha |

### `system_list_providers`

List providers for the current account with id, name, type, enabled, config.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_provider`

Fetch a single provider with full config hash (used to inspect routed-mode host_node_instance_id wiring etc.).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | System::Provider id |

### `system_update_provider`

Update a provider — supports name + enabled + config. Config is merge-updated (existing keys preserved unless explicitly nilled). Use this to set host_node_instance_id on a routed-mode QEMU provider, swap the bridge_name, etc.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | System::Provider id |
| `name` | string | No | New display name for the provider |
| `enabled` | boolean | No | Enable (true) or disable (false) the provider |
| `config` | object | No | Hash of config keys to merge. nil values delete the corresponding key. |

### `system_create_provider`

Create a substrate provider record (e.g. onboard a new local_qemu/libvirt host). Credentials are NOT accepted here — attach them afterwards via the Vault-backed provider credential flow (provider connections + BYOC credential test); secret material must never transit tool calls.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Unique provider name within the account |
| `provider_type` | string | Yes | Provider type slug (e.g. local_qemu, proxmox, aws, pro_cloud) |
| `description` | string | No | Free-text description for the provider |
| `enabled` | boolean | No | Defaults to true |
| `config` | object | No | Non-secret wiring config (e.g. host_node_instance_id, bridge_name) |

### `system_delete_provider`

Delete a provider record. CASCADES: the provider's regions, connections, instance types, volume types and networks are destroyed with it — decommission instances first.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | System::Provider id |

### `system_create_provider_connection`

Create a ProviderConnection for a provider (status starts 'pending'). NO credential parameters are accepted — the adapter layer resolves keys from the Vault-encrypted BYOC ProviderCredential store (saved via the provider Credentials UI/REST) at use time. Set test_connection=true to immediately run the live credential test: on success the connection flips to 'connected' (required before Registry will use it for provisioning).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider_id` | string | Yes | System::Provider id (account-scoped) |
| `name` | string | Yes | Display name for the provider connection |
| `description` | string | No | Free-text description for the connection |
| `endpoint_url` | string | No | Provider API endpoint URL for this connection |
| `enabled` | boolean | No | Defaults to true |
| `config` | object | No | Non-secret wiring config only — never key material |
| `test_connection` | boolean | No | Run the live credential test after create (uses BYOC credentials) |

### `system_create_provider_region`

Create a ProviderRegion under a provider — the placement target referenced by nodes/instances (provider_region_id).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider_id` | string | Yes | System::Provider id (account-scoped) |
| `name` | string | Yes | Display name for the provider region |
| `region_code` | string | No | Provider-native region identifier (e.g. us-east-1, lab-1) |
| `description` | string | No | Free-text description for the region |
| `endpoint_url` | string | No | Region-specific provider API endpoint URL |
| `enabled` | boolean | No | Defaults to true |
| `kernel_image` | string | No | Default kernel image reference for instances in this region |
| `machine_image` | string | No | Default machine (root disk) image reference for this region |
| `ramdisk_image` | string | No | Default ramdisk/initrd image reference for this region |
| `capabilities` | object | No | Region capability flags hash |

### `system_create_provider_instance_type`

Create a ProviderInstanceType (SKU) under a provider — the sizing record referenced at provisioning (provider_instance_type_id).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider_id` | string | Yes | System::Provider id (account-scoped) |
| `name` | string | Yes | Display name for the instance type (SKU) |
| `instance_type_code` | string | No | Provider-native SKU code (e.g. t3.small) |
| `description` | string | No | Free-text description for the instance type |
| `vcpus` | integer | No | Number of virtual CPUs the SKU provides |
| `memory_mb` | integer | No | RAM in megabytes the SKU provides |
| `storage_gb` | integer | No | Root storage in gigabytes the SKU provides |
| `hourly_price` | number | No | Hourly price for the SKU in account currency |
| `enabled` | boolean | No | Defaults to true |
| `specs` | object | No | Extended sizing specs (gpu, accelerators, ...) |

### `system_recycle_pool`

Recycle stale members of a pool: warming members past warming_timeout_seconds become errored, ready members past ready_ttl_seconds become draining. Returns counts of transitions made. Normally the reaper does this every 60s before replenish; this is for impatient operators or for unwedging a pool that's stuck with zombie warming members blocking the deficit calculation.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the InstancePool to recycle stale members for (account-scoped) |

### `system_list_package_repositories`

List accessible apt/rpm package repositories (account-scoped + shared). Filter by platform via node_platform_ids — repos linked to any of the supplied platforms are returned.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `kind` | string | No | Filter by repository kind: apt, rpm, or dnf |
| `node_platform_ids` | array | No | Array of NodePlatform UUIDs; repos linked to ANY are returned |

### `system_get_package_repository`

Fetch one package repository with sync status

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to fetch |

### `system_create_package_repository`

Register a new apt/rpm package repository. Set visibility='shared' for system-wide (requires manage_shared permission). Optionally pre-link NodePlatforms via node_platform_ids.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable repository name |
| `kind` | string | Yes | Repository kind: apt, rpm, or dnf |
| `base_url` | string | Yes | Upstream repository base URL to sync from |
| `visibility` | string | No | 'account' (default, account-scoped) or 'shared' (system-wide; requires manage_shared) |
| `architectures` | array | No | Canonical arch names this repo serves (defaults to ['amd64']) |
| `apt_config` | object | No | APT-specific config: { suite, components: [] } |
| `rpm_config` | object | No | RPM/DNF-specific config: { releasever, gpgcheck, metalink } |
| `signing_key_armor` | string | No | ASCII-armored GPG public key used to verify the repository signature |
| `node_platform_ids` | array | No | NodePlatform UUIDs to link on create |
| `description` | string | No | Optional free-text description of the repository |

### `system_update_package_repository`

Update an apt/rpm package repository's configuration

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to update |
| `attributes` | object | Yes | Fields to update: name, description, base_url, architectures, apt_config, rpm_config, signing_key_armor, priority, enabled, node_platform_ids |

### `system_delete_package_repository`

Delete a package repository (soft-delete linked Package metadata)

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to delete |

### `system_sync_package_repository`

Enqueue a background sync of the upstream apt/rpm index for this repository (returns immediately; poll get_package_repository for sync_status)

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to sync |
| `force` | boolean | No | Re-write every package row + bypass the unchanged-fingerprint fast-path and the mass-obsoletion guard (metadata refresh / override a partial-upstream guard trip) |

### `system_link_repository_platform`

Link a NodePlatform to a PackageRepository. Cross-account validated — account-scoped repos can only link platforms in the same account; shared repos can link any platform.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to link |
| `node_platform_id` | string | Yes | UUID of the NodePlatform to link to the repository |

### `system_unlink_repository_platform`

Remove a NodePlatform ↔ PackageRepository link. Idempotent — returns linked:false whether or not the link existed.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to unlink |
| `node_platform_id` | string | Yes | UUID of the NodePlatform to unlink from the repository |

### `system_search_packages`

Search the synced apt/rpm package catalog. Supports name+description trigram + semantic embedding ranking (mode: lexical|semantic|hybrid, default hybrid). Filters: kind (apt/rpm/dnf), repository_ids[], architectures[] (canonical, cross-kind expanded), sections[], license, provides (capability lookup).

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Search query matched against package name + description |
| `mode` | string | No | lexical | semantic | hybrid (default hybrid; blank q forces lexical) |
| `sort` | string | No | relevance | name | updated (default relevance) |
| `repository_id` | string | No | Back-compat: singular form of repository_ids |
| `repository_ids` | array | No | Restrict search to these PackageRepository UUIDs |
| `kind` | string | No | apt | rpm | dnf |
| `architecture` | string | No | Back-compat: singular form of architectures |
| `architectures` | array | No | Canonical arch names (amd64, arm64) — cross-kind expanded |
| `section` | string | No | Back-compat: singular form of sections |
| `sections` | array | No | Filter by package section/group names |
| `license` | string | No | Filter by package license identifier |
| `provides` | string | No | Capability name — finds packages whose name=capability OR provides @> [{name: capability}] |
| `page` | integer | No | 1-based page number for paginated results |
| `per_page` | integer | No | Number of results per page |

### `system_discover_packages`

Intent-based package discovery — describe a capability ('reverse proxy', 'distributed cache') and get ranked packages from accessible repositories. Pure semantic ranking via pgvector cosine distance. Use system_search_packages instead when you already know the package name.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `intent` | string | Yes | Free-text capability description — what the package should do |
| `repository_ids` | array | No | Restrict discovery to these PackageRepository UUIDs |
| `kind` | string | No | apt | rpm | dnf |
| `architectures` | array | No | Canonical arch names — cross-kind expanded |
| `license` | string | No | Filter by package license identifier |
| `top_k` | integer | No | Max results (1-50, default 10) |

### `system_get_package`

Fetch package metadata including depends/recommends/provides

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `package_id` | string | Yes | UUID of the package to fetch |

### `system_resolve_package_dependencies`

Preview the dependency closure of a package WITHOUT writes. Returns required closure + recommends candidates the operator can opt into.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository to resolve against |
| `package_name` | string | Yes | Name of the root package whose dependency closure to preview |
| `architecture` | string | Yes | Canonical architecture to resolve dependencies for (e.g. amd64) |

### `system_create_module_from_package`

Materialize a package + transitive deps as NodeModule rows, link them via ModuleDependency edges, and dispatch a CI build. Operator picks recommends_selected from the resolve_dependencies preview.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the source package repository |
| `package_name` | string | Yes | Name of the package to materialize into a NodeModule |
| `architectures` | array | Yes | Canonical arch names to build the module for |
| `recommends_selected` | array | No | Recommended package names (from resolve_dependencies preview) to opt into |
| `category_id` | string | No | UUID of the NodeModuleCategory to assign the new module to |
| `dispatch_build` | boolean | No | Whether to dispatch a CI build after materialization (default true) |

### `system_list_package_module_links`

List which NodeModules were materialized from which packages (auditable provenance)

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Filter links by source PackageRepository UUID |
| `auto_generated` | boolean | No | Filter by whether the link was auto-generated (true) or operator-created (false) |

### `system_refresh_package_module`

Re-materialize a NodeModule from its source package when upstream drifts. Replays persisted recommends_chosen for deterministic refreshes.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `package_module_link_id` | string | Yes | UUID of the PackageModuleLink to refresh |
| `force` | boolean | No | Force re-materialization even when no upstream drift is detected |

### `system_suggest_architectures_for_fleet`

Suggest which canonical architectures to materialize a package for, based on the fleet's NodePlatform coverage and the repository's served archs. Returns suggested arches + per-arch rationale + confidence label. Frontend uses this to pre-populate the CreateModuleFromPackageModal multi-select.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | UUID of the package repository whose served archs constrain suggestions |
| `max_suggestions` | integer | No | 1-7 (default 4) |

### `system_list_architectures`

List the platform-wide architecture catalog. Returns canonical + custom rows with usage counts.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `family` | string | No | Filter by family (x86, arm, power, z, risc-v, mips, other) |
| `is_canonical` | boolean | No | Filter by canonical vs operator-created custom rows |
| `enabled` | boolean | No | Filter by enabled (true) vs disabled (false) architectures |

### `system_get_architecture`

Fetch a single architecture by id with full catalog metadata + usage counts

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | UUID of the architecture to fetch |

### `system_create_architecture`

Create a custom (non-canonical) architecture. Requires system.architectures.manage. Use system_propose_architecture if you only have system.architectures.propose.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Canonical architecture name (e.g. amd64, arm64) |
| `family` | string | Yes | One of: x86, arm, power, z, risc-v, mips, other |
| `apt_name` | string | No | Debian/APT arch label for this architecture (e.g. amd64) |
| `rpm_name` | string | No | RPM/DNF arch label for this architecture (e.g. x86_64) |
| `display_name` | string | No | Human-friendly display label for the catalog UI |
| `description` | string | No | Optional free-text description of the architecture |
| `kernel_options` | string | No | Default kernel boot options associated with this architecture |
| `enabled` | boolean | No | Whether the architecture is enabled for use (default true) |
| `public` | boolean | No | Whether the architecture is publicly visible (default true) |

### `system_update_architecture`

Update a non-canonical custom architecture. Rejects canonical rows with 403-equivalent error.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | UUID of the custom architecture to update |
| `attributes` | object | Yes | Allowed: name, family, apt_name, rpm_name, display_name, description, kernel_options, enabled, public |

### `system_delete_architecture`

Delete a non-canonical custom architecture. Rejects canonical rows. Will fail if any NodePlatform references it.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | UUID of the custom architecture to delete |

### `system_propose_architecture`

Propose a new architecture for human review. Creates an Ai::AgentProposal row — no architecture is materialized until the human approver clicks 'Approve & Apply' in the proposals UI. Use this when the calling agent only has system.architectures.propose.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Canonical architecture name to propose (e.g. loongarch64) |
| `family` | string | Yes | Architecture family: x86, arm, power, z, risc-v, mips, other |
| `apt_name` | string | No | Debian/APT arch label for the proposed architecture |
| `rpm_name` | string | No | RPM/DNF arch label for the proposed architecture |
| `display_name` | string | No | Human-friendly display label for the catalog UI |
| `description` | string | No | Optional free-text description of the proposed architecture |
| `justification` | string | No | Why this architecture should be added — surfaces in the approval UI |

### `system_list_templates`

List node templates for the current account

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_template`

Fetch a template with its assigned modules

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to fetch (account-scoped) |

### `system_create_template`

Create a new NodeTemplate for the current account. Binds to a NodePlatform via node_platform_id (required by the model). Lets the model validate (name presence + per-account uniqueness).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new template (must be unique within the account) |
| `description` | string | No | Free-text description for the template |
| `enabled` | boolean | No | Whether the template is enabled (selectable for new nodes) |
| `public` | boolean | No | Whether the template is shared/public rather than account-private |
| `node_platform_id` | string | No | UUID of the NodePlatform the template binds to |
| `admin_user` | string | No | Default admin username provisioned on instances built from this template |
| `config` | object | No | Arbitrary template config hash |

### `system_update_instance`

Update mutable NodeInstance metadata: name, description, config, and the IP address fields. Deliberately does NOT expose status/variety/key — status is governed by the AASM lifecycle (use the lifecycle actions), and key is encrypted signing material.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to update (account-scoped) |
| `name` | string | No | New display name for the instance |
| `description` | string | No | New free-text description for the instance |
| `config` | object | No | Instance config hash (replaces the stored config) |
| `private_ip_address` | string | No | Private/internal IP address of the instance |
| `public_ip_address` | string | No | Public IP address of the instance |
| `vpn_ip_address` | string | No | SDWAN/VPN overlay IP address of the instance |

### `system_assign_module_to_template`

Bind a NodeModule to a NodeTemplate (creates a TemplateModule join)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to bind the module to |
| `module_id` | string | Yes | UUID of the NodeModule to assign to the template |

### `system_list_modules`

List node modules (filterable by variety)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | Filter options hash — supports { variety: '<variety>' } to filter modules by variety |

### `system_get_module`

Fetch a module with its current_version + assignments

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | UUID of the NodeModule to fetch (account-scoped) |

### `system_list_module_versions`

List versions of a module (newest first)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | UUID of the NodeModule whose versions to list |

### `system_promote_module_version`

Promote a NodeModuleVersion through its lifecycle (staging|blessed|live|retired)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_version_id` | string | Yes | UUID of the NodeModuleVersion to promote |
| `target_state` | string | Yes | Target promotion state: staging | blessed | live | retired |

### `system_drift_report`

Compare a node instance's running modules vs assigned

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to compute module drift for |

### `system_module_diff`

Compare two NodeModuleVersions and return added/removed files + package changes — preview before applying assignment changes

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `version_a_id` | string | Yes | UUID of the first NodeModuleVersion (baseline) to compare |
| `version_b_id` | string | Yes | UUID of the second NodeModuleVersion (candidate) to compare |

### `system_compliance_snapshot`

Generate a complete compliance evidence document for the current account (nodes, instances, modules, certs, CVE exposures, drift, decisions)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_runbook_generate`

Generate an operational markdown runbook for a NodeTemplate — boot order, modules, common failure modes, recovery procedures

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to generate an operational runbook for |
| `persist_as_page` | boolean | No | When true, persist the generated runbook as a content Page |

### `system_cve_runbook_generate`

Generate a markdown remediation runbook for a CVE — exposed modules, recommended steps, verification commands. Reads System::CveExposure for the current account.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id (e.g. CVE-2026-12345) to generate a remediation runbook for |
| `persist_as_page` | boolean | No | When true, persist the generated runbook as a content Page |

### `system_cve_triage`

Triage a CVE entry against the fleet — risk-scored exposure list and remediation plan. Reads from System::CveExposure when persisted.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id (e.g. CVE-2026-12345) to triage against the fleet |
| `severity` | string | Yes | CVE severity: critical | high | medium | low | unknown |
| `affected_packages` | array | Yes | Affected package list, e.g. [{name: 'openssl', version: '<3.1.4'}, ...] |
| `persist` | boolean | No | Persist a System::Cve row + exposures |

### `system_recent_signals`

Recent fleet observability events for this account (signals, decisions, ticks). Live feed available via SystemFleetChannel.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max number of events to return (clamped to 1..200, default 50) |
| `kind` | string | No | Filter by event kind (e.g. 'system.module_drift') |
| `correlation_id` | string | No | Filter to events sharing this correlation id (takes precedence over kind) |

### `system_attribute_failure`

Given a NodeInstance, rank recent module changes + promotions by likelihood of being the cause of a failure

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance whose failure to attribute |
| `lookback_hours` | integer | No | How many hours back to consider module changes/promotions (default 24) |

### `system_inspect_correlation`

Walk every FleetEvent sharing a correlation_id — forensic deterministic replay of one tick or one decision flow

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `correlation_id` | string | Yes | Correlation id whose FleetEvent chain to walk in emission order |

### `system_list_tasks`

List recent tasks (filterable by node_id or instance_id)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | No | Optional node UUID to list only tasks operating on that node |
| `instance_id` | string | No | Optional instance UUID to list only tasks operating on that instance |

### `system_get_task`

Fetch a single System::Task by id (account-scoped). Returns the task's command, status, progress, operable handle, and timestamps. Not-found errors when the id is unknown or belongs to another account.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the System::Task to fetch (account-scoped) |

### `system_cancel_task`

Cancel a pending task

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the pending System::Task to cancel |

### `system_abort_task`

Abort a running task (operator recourse on a wedged provision/build/ssh task — errors once the task has already left :running)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the running System::Task to abort |
| `reason` | string | No | Optional reason recorded on the task's error_message/audit events |

### `system_list_instance_pools`

List instance pools for the current account with size + occupancy stats

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_instance_pool`

Fetch a single instance pool with full member roster + counts

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the InstancePool to fetch (account-scoped) |

### `system_create_instance_pool`

Create a new pre-warmed instance pool. Reaper will provision target_size warming members on next tick.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new instance pool |
| `template_id` | string | Yes | UUID of the NodeTemplate pool members are provisioned from (fixed at create time) |
| `target_size` | integer | Yes | Target number of warm+ready members |
| `min_size` | integer | No | Lower bound (default 0) |
| `max_size` | integer | No | Upper bound (default target+10) |
| `lifecycle_class` | string | No | ephemeral|spot (default ephemeral) |
| `provider_region_id` | string | No | UUID of the ProviderRegion pool members are provisioned in (single-AZ default) |
| `provider_instance_type_id` | string | No | UUID of the ProviderInstanceType (SKU) pool members are provisioned as |
| `preferred_regions` | array | No | Ordered list of ProviderRegion UUIDs for cross-AZ HA spread — replenishment round-robins members across them by slot and skips regions the sensor marks unhealthy. Overrides provider_region_id when set. |

### `system_update_instance_pool`

Tune an existing instance pool: min_size/max_size/target_size, status, provider region/type, metadata. The reaper reconciles to the new sizes on its next tick. (Template is fixed at create time.)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the InstancePool to update (account-scoped) |
| `description` | string | No | New free-text description for the pool |
| `target_size` | integer | No | New target number of warm+ready members |
| `min_size` | integer | No | New lower bound on pool size |
| `max_size` | integer | No | New upper bound on pool size |
| `status` | string | No | active | paused | archived |
| `provider_region_id` | string | No | UUID of the ProviderRegion to provision future members in |
| `provider_instance_type_id` | string | No | UUID of the ProviderInstanceType (SKU) for future members |
| `preferred_regions` | array | No | Ordered list of ProviderRegion UUIDs for cross-AZ HA spread (replaces the pool's list; empty array clears it back to single-AZ) |
| `metadata` | object | No | Pool metadata hash (e.g. reuse_without_reset) |

### `system_drain_instance_pool`

Mark a pool draining: terminate ready members, halt replenishment. Claimed members keep running.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the InstancePool to drain (account-scoped) |

### `system_acquire_pooled_instance`

Atomically claim the oldest ready member from a pool. Returns the NodeInstance immediately (no provision wait).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_name` | string | No | Specific pool to acquire from |
| `pool_id` | string | No | Specific pool by ID |
| `lifecycle_class` | string | No | Acquire from any matching pool when name/id absent (e.g. 'ephemeral') |

### `system_replenish_instance_pool`

Manually trigger replenishment of a pool — provisions warming members up to target_size. Normally the reaper does this every 60s; this is for impatient operators.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the InstancePool to replenish (account-scoped) |

### `system_drain_instance`

Initiate graceful drain on a NodeInstance: records drain intent + emits FleetEvent so observability tooling (and future autonomy reconcilers) can act. Workloads remain running; operator should call system_terminate_instance after relocation completes. Idempotent — calling twice updates drain_initiated_at.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the NodeInstance to mark for graceful drain |
| `timeout_seconds` | integer | No | Suggested workload-relocation window (default 600 = 10 min). Stored in metadata for observability; does not auto-terminate. |

### `system_get_silent_instances`

List NodeInstances whose last_heartbeat_at is older than the SILENT_THRESHOLD (3 minutes), or null. Aligned with InstanceStatusSensor. Useful for fleet-health dashboards and pre-upgrade gates.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `threshold_seconds` | integer | No | Override the 3-minute default; useful for dashboards with custom alert thresholds |

### `system_validate_module_manifest`

Validate a module manifest YAML against the schema (schema_version, name match, spec field types, init shape, reboot_required boolean) without committing to DB. Returns valid + validation_errors array. Use before pushing manifest changes to CI.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | Existing NodeModule id to validate against (manifest.name must match) |
| `manifest_yaml` | string | Yes | Raw manifest.yaml contents |

### `system_get_cve`

Fetch a Cve by its canonical id (e.g. CVE-2026-12345). Cves are global across accounts.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id, format CVE-YYYY-NNNN (4+ digits) |

### `system_get_cve_exposure`

Fetch the exposure breakdown for a CVE — exposed modules + per-module assignment counts, account-scoped via CveExposure → NodeModuleVersion → NodeModule.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id (e.g. CVE-2026-12345) to compute account exposure for |

### `system_create_cve`

Manually inject a Cve row (typically for embargoed CVEs not yet in NVD, or for drill-mode runbooks). Idempotent via cve_id uniqueness — re-running updates fields. NOTE: Cve table is GLOBAL (not account-scoped) — created CVEs are visible to all accounts. Requires elevated system.fleet.autonomy permission.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id, format CVE-YYYY-NNNN (4+ digits). Drills should use high-numeric ids like CVE-2026-99001. |
| `severity` | string | Yes | critical|high|medium|low|unknown |
| `summary` | string | No | Short human-readable summary of the CVE |
| `affected_packages` | array | No | [{name: 'openssl', version: '<3.1.4'}, ...] |
| `published_at` | string | No | ISO8601; defaults to now |
| `reference_url` | string | No | URL to the CVE advisory / reference |
| `feed_source` | string | No | nvd|ghsa|manual (default manual) |

### `system_delete_cve`

Destroy a Cve row + cascade-delete its CveExposures. Used for drill cleanup. Cves are global; deletion affects all accounts. Requires elevated system.fleet.autonomy permission.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id (e.g. CVE-2026-12345) of the global Cve row to delete |

### `system_unassign_module_from_template`

Remove a NodeModule from a NodeTemplate (destroys the TemplateModule join). Inverse of system_assign_module_to_template. Idempotent — returns success even when the join doesn't exist.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | UUID of the NodeTemplate to remove the module from |
| `module_id` | string | Yes | UUID of the NodeModule to unassign from the template |

### `system_update_module_assignment`

Enable or disable a NodeModuleAssignment (per-(node, module) toggle). enabled=true enables the assignment; enabled=false disables it. The assignment row is preserved either way — disabling drops the module from neighbor union mounts / rsync_spec generation without losing priority/config. Mirrors the NodeModuleAssignmentsController enable/disable member actions. Idempotent.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assignment_id` | string | Yes | UUID of the NodeModuleAssignment to enable/disable (account-scoped via its Node) |
| `enabled` | boolean | Yes | true → enable, false → disable |

### `system_return_pooled_instance`

Return a claimed instance back to its pool. Default disposition is 'recycled': the member drains + terminates and the replenisher provisions a fresh one (no cross-mission data residue). Pools with metadata reuse_without_reset=true (same-trust-domain workloads only) instead re-mark the member 'ready' for reuse ('reused' disposition).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | UUID of the claimed pool NodeInstance to return to its pool |

### `system_delete_instance_pool`

Destroy an empty InstancePool row. Errors when pool still has members — drain first via system_drain_instance_pool, then delete.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the empty InstancePool to delete (account-scoped) |

### `system_module_mark_canary`

Mark a NodeModule as a honeypot canary (config['honeypot']['canary'] = true). Canary modules are decoys — any access triggers a high-severity FleetEvent via honeypot_access_sensor. Idempotent — re-marking is a no-op.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | UUID of the NodeModule to mark as a honeypot canary |
| `lure_kind` | string | No | Display label for the canary (default 'credential_store') |

### `system_deploy_platform`

Deploy a new Powernode platform. Two execution shapes: (1) call with no `mode` to receive a wizard-card payload describing the form fields the operator should fill in — the chat UI renders this inline; (2) call with full args (mode, name, template_slug, [parent_url, spawn_mode for federated]) to actually provision. Standalone = sovereign platform; federated = peers back with this platform via P6 spawn flow. Federated mode returns a single-use acceptance_token that must be captured immediately.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string | No | standalone | federated. Omit to receive the wizard payload. |
| `name` | string | No | Display name for the new deployment (required when mode is set). |
| `template_slug` | string | No | NodeTemplate to provision from (defaults to powernode-hub). |
| `parent_url` | string | No | Required for federated mode — reachable URL of THIS platform. |
| `spawn_mode` | string | No | Required for federated mode — one of managed_child, autonomous_peer, cluster_member. |
| `region` | string | No | Provider region to deploy the new platform into |
| `instance_size` | string | No | Instance size/SKU hint for the deployment's compute |
| `service_role` | string | No | Service role for the deployment (selects the workload profile) |
| `public_dns_hostname` | string | No | Public DNS hostname to assign to the new platform |
| `token_ttl_seconds` | integer | No | TTL (seconds) for the single-use federated acceptance_token |

### `system_list_volumes`

List storage volumes for the current account. Filter by status (available/in-use/etc), transport (nfs/iscsi/block), or attached node_instance_id.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter volumes by status (e.g. available, in-use) |
| `transport` | string | No | Filter volumes by transport (nfs | iscsi | smb | block) |
| `node_instance_id` | string | No | Filter to volumes attached to this NodeInstance UUID |
| `unattached_only` | boolean | No | When true, return only volumes not attached to any instance |

### `system_get_volume`

Get full detail on a single storage volume — backing config (NFS server + export path / block device id), attachment state, ACL, capacity.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the ProviderVolume to fetch (account-scoped) |

### `system_create_volume`

Register a new ProviderVolume. For NFS, pass transport=nfs + nfs_server + nfs_export_path. For block, pass volume_type_id. The platform records the row; on-node mounting happens at attach time.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new ProviderVolume |
| `size_gb` | integer | Yes | Volume capacity in gigabytes |
| `volume_type_id` | string | No | ProviderVolumeType id (skip if transport given — we'll find/create the matching type) |
| `transport` | string | No | nfs | iscsi | smb | block (default: block) |
| `nfs_server` | string | No | Required for transport=nfs — hostname or IP |
| `nfs_export_path` | string | No | Required for transport=nfs — path on the server |
| `nfs_version` | string | No | Optional — 3 | 4.0 | 4.1 | 4.2 (default 4.1) |
| `provider_id` | string | No | Which provider to bind the volume to. REQUIRED when the account has more than one provider — the platform refuses to guess and returns the candidate list |
| `provider_region_id` | string | No | Bind to a specific region (implies the provider; takes precedence over provider_id) |
| `description` | string | No | Free-text description for the volume |

### `system_update_volume`

Update a ProviderVolume's mutable fields: name, description, size_gb, status.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the ProviderVolume to update (account-scoped) |
| `name` | string | No | New display name for the volume |
| `description` | string | No | New free-text description for the volume |
| `size_gb` | integer | No | New volume capacity in gigabytes |
| `status` | string | No | New volume status |

### `system_delete_volume`

Delete a ProviderVolume row. Refuses to delete if currently attached.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the ProviderVolume to delete (must be detached) |

### `system_attach_volume`

Attach a ProviderVolume to a NodeInstance. For block: assigns next free /dev/vdX. For NFS pools: records the per-deployment binding without flipping pool status.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `volume_id` | string | Yes | UUID of the ProviderVolume to attach |
| `node_instance_id` | string | Yes | UUID of the NodeInstance to attach the volume to |
| `deployment_name` | string | No | Used for the NFS subpath isolation when applicable |
| `role` | string | No | Service role (postgres / redis / etc.) — used for mount point + subpath |

### `system_detach_volume`

Detach a ProviderVolume. For block volumes: clears node_instance_id + sets status=available. For NFS: clears the per-deployment binding only (pool remains available to other consumers).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `volume_id` | string | Yes | UUID of the ProviderVolume to detach |
| `node_instance_id` | string | No | Required for NFS volumes to identify which consumer binding to clear |

### `system_test_nfs_export`

Probe an NFS server + export to verify reachability before recording a ProviderVolume. Runs DNS lookup + TCP probe on 111/2049 + showmount -e. Does NOT actually mount — that's safer when called from chat.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | NFS server hostname or IP to probe |
| `export_path` | string | No | Optional — when omitted, returns the list of all advertised exports |

### `system_get_storage_recommendations`

Read the platform-memory-stored storage recommendations — stateful role mount points + recommended size_gb per role. Falls back to defaults if no override exists.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_update_storage_recommendations`

Update the platform-memory storage recommendations. Partial merge — only supplied keys override defaults. Example: { recommended_size_gb_by_role: { postgres: 200 } } leaves redis/etc untouched.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendations` | object | Yes | Partial recommendations hash to merge — only supplied keys override defaults (e.g. { recommended_size_gb_by_role: { postgres: 200 } }) |

### `system_migrate_storage_component`

Records intent to migrate a stateful component's data from one ProviderVolume to another. Returns a migration plan (source subpath, target subpath, estimated bytes, recommended rsync command). v1 returns the plan only — actual rsync execution is a follow-up runbook.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | UUID of the NodeInstance whose stateful component is being migrated |
| `source_volume_id` | string | Yes | UUID of the ProviderVolume currently holding the data |
| `target_volume_id` | string | Yes | UUID of the ProviderVolume to migrate the data to (must differ from source) |
| `role` | string | Yes | Stateful component role being migrated (e.g. postgres, redis) — determines source/target subpaths |

### `system_list_storage_migrations`

List storage migrations for the account (newest first, capped at 100). Filterable by status, node_instance_id, or active_only.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by migration status |
| `node_instance_id` | string | No | Filter to migrations for this NodeInstance UUID |
| `active_only` | boolean | No | Only non-terminal migrations |

### `system_get_storage_migration`

Fetch one storage migration with full details (plan, progress bytes, status history).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to fetch (account-scoped) |

### `system_approve_storage_migration`

Approve a planned storage migration so the on-node agent may begin the sync. Errors unless the migration can transition to 'approved'.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to approve |

### `system_cancel_storage_migration`

Cancel a storage migration before sync starts (allowed in planned/approved/preparing; errors once the sync is in progress or the migration is terminal).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to cancel |
| `reason` | string | No | Optional reason recorded in the migration's audit log |

### `system_report_storage_migration_progress`

Report sync progress for a storage migration (called by the on-node agent). Optionally advances status; records bytes copied/total/verified and a note.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to report progress for |
| `status` | string | No | Optional phase transition (must be legal from the current status) |
| `bytes_copied` | integer | No | Bytes copied so far |
| `bytes_total` | integer | No | Total bytes to copy |
| `bytes_verified` | integer | No | Bytes verified after copy |
| `note` | string | No | Free-text progress note recorded in the audit log |

### `system_revert_storage_migration_binding`

Request the on-node agent re-point the consumer's canonical mount back to the SOURCE volume (inverse of cutover). Reachable from status=failed (any cutover-phase failure), or status=completed when promote_target_binding! silently failed (the half-cutover). Target data is left intact. Records intent only — the node does the actual mount work.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to revert |
| `reason` | string | No | Optional reason recorded in the migration's audit log |

### `system_cleanup_storage_migration`

DESTRUCTIVE — deletes the migration's target-side scratch artifacts only: the target_subpath partial copy + snapshot_subpath scratch + node transient mounts. NEVER touches source data, the source/target volume, or sibling subpaths. Reachable only from status=failed or status=cancelled (once preparing was reached). Explicit operator action — never auto-run on failure. Subject to a grace window (system.storage.migration.cleanup_grace_hours, SiteSetting/Account#settings-resolved, default 24h); pass immediate: true to override.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | UUID of the StorageMigration to clean up |
| `reason` | string | No | Optional reason recorded in the migration's audit log |
| `immediate` | boolean | No | Skip the cleanup grace window and clean up now |

### `system_platform_maintenance`

Wraps the platform_maintenance skill executor — op-discriminated: cert_status, cert_rotate, drift_check, health_check. Use `op:` for the sub-action; the MCP dispatcher already owns `action:`.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `op` | string | Yes | cert_status | cert_rotate | drift_check | health_check |
| `certificate_id` | string | No | UUID of the certificate to act on (for cert_status/cert_rotate) |
| `deployment_id` | string | No | UUID of the deployment to scope the maintenance op to |
| `renewal_window_days` | integer | No | Days-before-expiry window that flags a cert for rotation |

### `system_platform_resilience`

Wraps the platform_resilience skill executor — op-discriminated: drain_instance, scale, failover_check.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `op` | string | Yes | drain_instance | scale | failover_check |
| `instance_id` | string | No | UUID of the instance to drain (for op=drain_instance) |
| `deployment_id` | string | No | UUID of the deployment to scale or check failover for |
| `direction` | string | No | set | increment | decrement (for op=scale) |
| `target_replicas` | integer | No | Replica count for op=scale (used when direction=set) |
| `timeout_seconds` | integer | No | Timeout in seconds for the resilience operation |

### `system_list_disk_image_publications`

List DiskImagePublications for the account, optionally filtered by node_platform_id and/or status. Returns oldest-first by default.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_platform_id` | string | No | Filter publications to this NodePlatform UUID |
| `status` | string | No | queued|verifying|published|failed|retired |
| `limit` | integer | No | Default 50 |

### `system_set_default_disk_image_publication`

Promote a published DiskImagePublication as the platform's active disk image — copies its OCI ref + git SHA onto the parent NodePlatform so new instances boot from it. Errors if the publication is not in 'published' state.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `publication_id` | string | Yes | UUID of the published DiskImagePublication to set as the platform default |

### `system_revert_disk_image`

Roll a NodePlatform's disk image back to a prior publication — restores the target publication's file_object onto the platform (and un-soft-deletes it if the target was retired), then retires the previously-active publication. With publication_id, rolls back to that specific publication; without it, auto-selects the most recent prior publication (the newest retired one, else the newest published one that isn't currently active). Refuses purged publications (FileObject hard-deleted) and publications with no file_object. Wraps System::Executors::DiskImage::RollbackPublication — the same transaction the DiskImagePublicationsController#rollback :proceed path uses.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platform_id` | string | Yes | System::NodePlatform id to roll back |
| `publication_id` | string | No | Target DiskImagePublication to restore. Omit to auto-select the previous publication. |

### `system_set_disk_image_retention`

Update the per-NodePlatform retention count (number of historical publications kept before the reaper purges).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_platform_id` | string | Yes | UUID of the NodePlatform whose disk-image retention count to set |
| `retention_count` | integer | Yes | Number of historical publications to retain (must be ≥1) |

### `system_provision_ci_worker`

Provision a CI worker (a Worker with the 'ci_worker' role). Returns the worker plus a one-time-shown plaintext token. Token is NOT recoverable — operator must store immediately.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new CI worker |

### `system_terminate_ci_worker`

Revoke a CI worker — destroys credentials + marks the worker as revoked. Operator can then unregister the corresponding Gitea Actions runner.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `worker_id` | string | Yes | UUID of the CI Worker to revoke (account-scoped) |

### `system_list_ci_workers`

List CI workers (Workers with role='ci_worker') for the current account.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_lease_ci_runner`

Lease an ephemeral Gitea Act runner from a builder pool: acquire a warm builder instance, correlate it to the Gitea runner it self-registered, and return the lease. The instance is recycled (terminate + backfill) on release so no state bleeds between jobs.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_name` | string | No | Builder InstancePool name to acquire from (e.g. 'ci-builders-amd64'). One of pool_name/pool_id is required. |
| `pool_id` | string | No | Builder InstancePool id (alternative to pool_name) |
| `purpose` | string | No | generic | module_build | disk_image_build (default generic) — selects the publish-arrival signal the reconciler waits on before release |
| `workflow_run_id` | integer | No | Gitea workflow run id this lease serves (set by the build orchestrator; drives auto-release when the run completes) |
| `workflow_run_repo` | string | No | owner/repo of the workflow run (needed to poll run state when workflow_run_id is set) |
| `correlate_timeout` | integer | No | Seconds to wait for the runner to correlate before returning (default from SiteSetting; 0 = single attempt, the reconciler finishes async) |

### `system_release_ci_runner`

Release a CI runner lease: deregister the runner from Gitea and recycle its pooled instance (terminate + backfill). Refuses a busy runner unless force is set (never tears down a running build).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lease_id` | string | Yes | UUID of the CiRunnerLease to release (account-scoped) |
| `force` | boolean | No | Release even if the runner is currently busy (default false) |

### `system_list_ci_runner_leases`

List CI runner leases for the current account, optionally filtered by status or active-only.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter to a single lease status (leased/registered/busy/releasing/released/errored) |
| `active` | boolean | No | When true, return only active (non-terminal) leases |
| `limit` | integer | No | Max rows (default 50) |

### `system_list_disk_image_webhooks`

List DiskImageWebhook rows for the current account (the inbound webhook receivers that ingest publications from Gitea Actions).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_dispatch_module_build_batch`

Plan + dispatch a native module-build batch for a base_sha..head_sha range: computes which modules need rebuilding (System::ModuleBuildPlannerService — or every module with force_all), creates the System::ModuleBuildBatch, and leases ephemeral module-forge builders to run each module's ci.module_build task (System::NativeModuleBuildOrchestrator#dispatch!). Returns the batch immediately — planning and the first dispatch pass are synchronous; build/sign/publish completion is tracked asynchronously via the batch's status (see system_list_tasks / system_get_task for the underlying ci.module_build tasks).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `base_sha` | string | Yes | Pre-push commit SHA (diff base) the planner compares from |
| `head_sha` | string | Yes | Post-push commit SHA (diff head); also the source of each build's short tag |
| `force_all` | boolean | No | Skip the diff and plan every module with a manifest (manual full rebuild / CVE-driven sweep). Default false. |
| `trigger` | string | No | push | manual | cve (default manual) — recorded on the batch for audit |
| `source_repo` | string | No | "<owner>/<repo>" the base_sha..head_sha diff is taken against (default: the ci_build_source_repo manifest repo). Pass the CORE repo (e.g. powernode/powernode-platform) for a core-change build so the planner diffs the tree the change actually lives in — diffing the wrong repo plans 0 modules. |

### `system_gitops_register_repository`

Register a new GitopsRepository pointing at a git remote whose contents describe desired fleet state. The reconciler clones + pulls every 5 min by default; operator can trigger immediately via system_gitops_sync_repository.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name (must be unique within the account; max 64 chars) |
| `repo_url` | string | Yes | HTTPS or SSH URL. Inline credentials (user:pass@) rejected — use vault_credential_path. |
| `branch` | string | No | Default 'main' |
| `vault_credential_path` | string | No | Vault KV path with deploy-key + username/password |
| `path_prefix` | string | No | Relative path within the repo where fleet.yaml lives (default: repo root) |
| `auto_apply` | boolean | No | When true, approved proposals auto-apply on next reconcile (Phase 6b). Default false. |

### `system_gitops_sync_repository`

Trigger an immediate reconcile run for a registered repository. Creates a GitopsSyncRun row + opens proposals for any diffs found. Returns the sync_run_id for polling.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | GitopsRepository id |

### `system_gitops_get_sync_run`

Fetch the result of a sync run — diff_count, proposal_ids, status, error_message, diff_summary.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sync_run_id` | string | Yes | UUID of the GitopsSyncRun to fetch the result of (account-scoped) |

### `system_gitops_get_drift_report`

Compute current drift between a repository's desired state and live platform state — without opening proposals. Read-only diagnostic. Use before sync to preview what would change.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | GitopsRepository id |

### `system_rotate_vault_transit_pepper`

Rotate the Vault transit pepper that wraps per-account encryption keys. Bumps the key version + walks all accounts with stale transit_key_version, re-wrapping each. Online operation. WARNING: cryptographic — review before invocation. Audit-logged.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reencrypt_existing` | boolean | No | When false, only bumps the key version without walking accounts (operators may phase rotation manually). Default true. |

### `system_gitops_apply_proposal`

Apply an approved GitOps proposal — executes the diff against the DB (creates/updates templates, modules, assignments). Errors with stale_conflict if reality drifted post-proposal. v1 supports template/module/assignment kinds; destroy + provider_config remain follow-ups.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_id` | string | Yes | Ai::AgentProposal id (must be in 'approved' status with proposed_changes.source = 'gitops') |

### `system_sdwan_list_networks`

List SDWAN networks for the current account

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | Reserved options hash (currently unused; pass {} or omit) |

### `system_sdwan_get_network`

Fetch an SDWAN network by id

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to fetch |

### `system_sdwan_create_network`

Create a new SDWAN overlay network. CIDR (/64) is allocated automatically.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the new network |
| `description` | string | No | Free-form description of the network's purpose |
| `options` | object | No | settings hash (mtu, topology_strategy, ...) |

### `system_sdwan_update_network`

Update an SDWAN network's name/description/status/settings

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to update |
| `options` | object | No | Hash of fields to update: name, description, status, settings (settings must itself be a hash) |

### `system_sdwan_delete_network`

Delete an SDWAN network and all its peers + keys (destructive)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to delete |

### `system_sdwan_list_peers`

List peers in an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose peers to list |

### `system_sdwan_get_peer`

Fetch a single peer with its current key + endpoint

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer to fetch |

### `system_sdwan_set_peer_tags`

Set the firewall tag labels on a peer. A FirewallRule whose src/dst selector is { "tag": "<label>" } matches every peer carrying that label (Sdwan::SelectorResolver compiles it to an nft set of their addresses). Replaces the peer's whole tag set; empty array clears it.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer to label |
| `tags` | array | Yes | Array of tag label strings (whitespace-trimmed, de-duped). Empty array clears all tags. |

### `system_sdwan_attach_peer`

Attach a NodeInstance to an SDWAN network (allocates address, generates keypair). Slice 7a: prefer endpoint_host_v6/v4 over the legacy endpoint_host for new hubs.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to attach the node to |
| `node_instance_id` | string | Yes | UUID of the System::NodeInstance to enroll as a peer |
| `publicly_reachable` | boolean | No | Mark this peer as a hub other peers can dial (default false) |
| `endpoint_host` | string | No | Legacy single-endpoint field; prefer endpoint_host_v6/v4 for new hubs |
| `endpoint_host_v6` | string | No | IPv6 literal or hostname (slice 7a). v6-preferred when both this and endpoint_host_v4 are set. |
| `endpoint_host_v4` | string | No | IPv4 literal or hostname (slice 7a). Used as fallback if v6 dial fails. |
| `endpoint_port` | integer | No | UDP port other peers dial this hub on |
| `listen_port` | integer | No | WireGuard listen port for this peer (default 51820) |

### `system_sdwan_detach_peer`

Detach a peer (revokes key, removes membership)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer to detach |

### `system_sdwan_get_topology`

Return the compiled per-peer view for an SDWAN network — what each peer would receive on its next config pull

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to compile topology for |

### `system_sdwan_list_firewall_rules`

List firewall rules in an SDWAN network (priority-ordered)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose firewall rules to list |

### `system_sdwan_get_firewall_rule`

Fetch a single firewall rule, including its compiled nft preview

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | UUID of the SDWAN firewall rule to fetch |

### `system_sdwan_create_firewall_rule`

Create a firewall rule. Selectors accept {peer_id|tag|cidr|all} primitives. Port range is optional and only applies to tcp/udp.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network this rule belongs to |
| `name` | string | Yes | Display name for the firewall rule |
| `firewall_action` | string | No | accept (default) | drop | reject |
| `direction` | string | No | ingress | egress | both (default) |
| `protocol` | string | No | any (default) | tcp | udp | icmp6 |
| `priority` | integer | No | Evaluation priority (lower runs first); defaults to the model's default |
| `src_selector` | object | No | Source match: one of {peer_id|tag|cidr|all} |
| `dst_selector` | object | No | Destination match: one of {peer_id|tag|cidr|all} |
| `port_from` | integer | No | Start of the port range (tcp/udp only; pair with port_to) |
| `port_to` | integer | No | End of the port range (tcp/udp only; pair with port_from) |

### `system_sdwan_update_firewall_rule`

Update a firewall rule (any field). Pass port_from/port_to as null to clear the port range.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | UUID of the SDWAN firewall rule to update |
| `name` | string | No | New display name for the rule |
| `firewall_action` | string | No | accept | drop | reject |
| `direction` | string | No | ingress | egress | both |
| `protocol` | string | No | any | tcp | udp | icmp6 |
| `priority` | integer | No | Evaluation priority (lower runs first) |
| `src_selector` | object | No | Source match: one of {peer_id|tag|cidr|all} |
| `dst_selector` | object | No | Destination match: one of {peer_id|tag|cidr|all} |
| `port_from` | integer | No | Start of the port range (tcp/udp only) |
| `port_to` | integer | No | End of the port range (tcp/udp only) |
| `enabled` | boolean | No | Whether the rule is active |

### `system_sdwan_delete_firewall_rule`

Delete a firewall rule (immediate; takes effect on next agent reconcile)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | UUID of the SDWAN firewall rule to delete |

### `system_sdwan_list_access_grants`

List user access grants on an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose access grants to list |

### `system_sdwan_create_access_grant`

Grant a user access to an SDWAN network (precondition for issuing them VPN devices)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to grant access to |
| `user_id` | string | Yes | UUID of the User (in this account) being granted access |
| `tags` | array | No | Optional list of tag strings applied to the grant (used for firewall tag selectors) |

### `system_sdwan_revoke_access_grant`

Revoke an access grant — cascades to revoke all the user's devices on this network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | UUID of the SDWAN access grant to revoke |
| `reason` | string | No | Optional human-readable revocation reason (recorded on the grant) |

### `system_sdwan_list_user_devices`

List a user's VPN devices on an SDWAN network (per access grant)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | UUID of the SDWAN access grant whose devices to list |

### `system_sdwan_issue_user_device`

Issue a fresh WireGuard config for a user. Returns a one-shot bootstrap_url (15-min expiry, single-use) — copy it to the user out-of-band.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | UUID of the SDWAN access grant the device is issued under |
| `label` | string | Yes | Operator-supplied device label, e.g. 'phone' or 'work-laptop' |

### `system_sdwan_revoke_user_device`

Revoke a user device (immediate; agent drops it from the hub view on next reconcile)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_device_id` | string | Yes | UUID of the SDWAN user device to revoke |
| `reason` | string | No | Optional human-readable revocation reason (recorded on the device) |

### `system_sdwan_list_federation_peers`

List federation peer records (proposed cross-Powernode-instance overlay peerings)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | Reserved options hash (currently unused; pass {} or omit) |

### `system_sdwan_get_federation_peer`

Fetch a federation peer with its v1-allowed transitions

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer to fetch |

### `system_sdwan_propose_federation_peer`

Propose a new federation peer. Status starts at 'proposed'. With generate_token: true (Phase 11b), generates a single-use acceptance token (plaintext returned ONCE) — Account A operator copies it out-of-band to Account B operator who pastes it into system_sdwan_accept_federation_peer.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `remote_instance_url` | string | Yes | Base URL of the remote Powernode instance to peer with |
| `remote_instance_id` | string | No | Optional identifier of the remote Powernode instance |
| `remote_account_id` | string | No | Optional identifier of the remote account on the peer instance |
| `remote_prefix_advertisement` | string | No | /48|/56|/64 ULA prefix the remote instance claims |
| `generate_token` | boolean | No | When true, generate a single-use acceptance token (Phase 11b token round-trip handshake). Plaintext returned ONCE — not recoverable. |
| `token_ttl_seconds` | integer | No | Token expiry window in seconds (default 7 days) |

### `system_sdwan_accept_federation_peer`

Transition a proposed federation peer to accepted. When the proposing operator generated a single-use acceptance token, pass it as acceptance_token — it is verified (digest match + not expired + single-use) before the transition is allowed. Sets signed_at + audit metadata and (for platform peers) chains into enroll. Returns the updated peer.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer to accept (must be in 'proposed' status) |
| `acceptance_token` | string | No | Single-use token from the proposing-account operator (from propose with generate_token: true). Verified against the stored digest; consumed on success. |

### `system_sdwan_update_federation_peer`

Update a federation peer's mutable fields. When `status` is supplied it is gated by the v1 transition matrix (FederationPeer#can_transition_to?) — disallowed transitions return an error. Mirrors the FederationPeersController#update permitted keys.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer to update |
| `status` | string | No | Target status — must be an allowed v1 transition from the current status |
| `remote_instance_url` | string | No | Base URL of the remote Powernode instance |
| `remote_instance_id` | string | No | Identifier of the remote Powernode instance |
| `remote_account_id` | string | No | Identifier of the remote account on the peer instance |
| `remote_prefix_advertisement` | string | No | /48|/56|/64 ULA prefix the remote instance claims |
| `signed_at` | string | No | ISO8601 timestamp marking when the peering was signed |
| `expires_at` | string | No | ISO8601 timestamp marking when the peering expires |
| `metadata` | object | No | Free-form metadata hash stored on the peer |

### `system_sdwan_revoke_federation_peer`

Revoke a federation peer (terminal in v1)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer to revoke |
| `reason` | string | No | Optional human-readable revocation reason (recorded on the peer) |

### `system_sdwan_federation_scan`

Run the federation governance scanner — flags prefix overlaps and stale-accepted rows

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read
- **Parameters**: none

### `system_sdwan_set_data_residency`

Set a federation peer's data residency region tag (the system_federation_peers.data_residency column, a scalar string ≤64 chars). Used by the residency enforcer to gate which peers may home a given record.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer to tag |
| `data_residency` | string | Yes | Region/residency tag, e.g. 'us-east' or 'eu' |

### `system_sdwan_get_audit_log`

Read-only audit trail for a federation peer: WORM audit shipments (P9.2 sealed FleetEvent batches) plus recent federation.* FleetEvents pertaining to this peer. Secret fields (sealed_path, error_message) are not surfaced.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | UUID of the federation peer whose audit trail to read |
| `limit` | integer | No | Max rows per collection (default 50) |

### `system_sdwan_federation_compose`

Stand up a federation overlay topology (hub-and-spoke OR full-mesh) across instances. Creates one Sdwan::Network, enrolls each member as a peer (hubs publicly_reachable), and compiles the per-peer WireGuard + FRR route-policy envelope (Sdwan::PeerEnroller + TopologyCompiler + RoutePolicyCompiler). Failures are collected, not short-circuited.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_name` | string | Yes | Display name for the new federation Sdwan::Network |
| `topology` | string | Yes | hub_and_spoke | full_mesh |
| `peers` | array | Yes | Member descriptors (1-200). Each: {node_instance_id (required), role: 'hub'|'spoke' (hub_and_spoke only; default spoke), endpoint_host_v6, endpoint_host_v4, endpoint_port, listen_port, lan_subnets: [cidr], bgp_route_reflector_client: bool} |
| `routing_protocol` | string | No | static (default) | ibgp — 'ibgp' enables FRR route-policy distribution |
| `dry_run` | boolean | No | Plan only — no rows persisted |

### `system_multi_tenant_isolation`

Provision a fully-isolated SDWAN network slice for a single tenant: a dedicated overlay network with its own VRF + isolated iBGP RIB, a non-overlapping /64, default-deny nftables rules scoped to the tenant CIDR, an OVN logical switch, and tenant-CIDR OVN ACLs. SDWAN-native — no k8s NetworkPolicy, no VLAN. Approval-gated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tenant_key` | string | Yes | Stable slug-safe tenant identifier within the account (names the network/rules/switch/ACLs) |
| `network_name` | string | No | Display name for the tenant's Sdwan::Network (defaults to 'tenant-<tenant_key>') |
| `tenant_cidr` | string | No | Explicit tenant CIDR; when omitted the auto-allocated /64 is used (recommended) |
| `nb_db_endpoint` | string | No | OVN NB DB endpoint (e.g. tcp:127.0.0.1:6641) — required only when the account has no Sdwan::OvnDeployment yet |
| `sb_db_endpoint` | string | No | OVN SB DB endpoint (e.g. tcp:127.0.0.1:6642) — required only when the account has no Sdwan::OvnDeployment yet |
| `ovn_switch_name` | string | No | Override the OVN logical switch name (defaults to 'ls-tenant-<tenant_key>') |
| `dry_run` | boolean | No | Plan only — no rows persisted |

### `system_service_discovery_compose`

Make a backend service discoverable across the fleet over the SDWAN overlay — provisions a Virtual IP (auto-advertised via iBGP for in-overlay discovery), publishes a VIP-backed federation service-catalog offering, regenerates local Traefik routes, and OPTIONALLY publishes a public DNS record (A/AAAA/CNAME) for internet-facing names. Approval-gated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_name` | string | Yes | Human-readable catalog display name |
| `service_slug` | string | Yes | Lowercase-alphanumeric-hyphen slug — the catalog's natural key (also names the VIP) |
| `sdwan_network_id` | string | Yes | SDWAN network the VIP lives in |
| `backend_peer_id` | string | Yes | Sdwan::Peer hosting the service; seated as the VIP's primary holder (iBGP advertiser) |
| `backend_port` | integer | Yes | Port the backend service listens on (advertised in the catalog offering) |
| `vip_cidr` | string | Yes | Operator-supplied host CIDR for the VIP (a /128 v6 or /32 v4) within the network's /64 |
| `protocol` | string | No | Service protocol advertised in the catalog: https (default) | http | tcp | tls |
| `grant_scopes` | array | No | Default FederationGrant scopes subscribers receive (subset of read, write, admin, migrate). Defaults to ['read'] |
| `grant_ttl_days` | integer | No | Default grant TTL in days (>= 7) |
| `traefik_dynamic_dir` | string | No | Override for the Traefik dynamic-config directory |
| `public_dns` | object | No | INTERNET-FACING name only: { dns_credential_id, record_name, record_type? (A|AAAA|CNAME), record_content?, ttl? }. Omit for overlay-only discovery. |

### `system_sdwan_update_peer_lan_subnets`

Declare the external LAN prefixes a peer can route to. In static mode, the topology compiler folds these into AllowedIPs so other peers route across the SDWAN to reach them. CIDR strings (v4 or v6).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer whose LAN subnets to declare |
| `lan_subnets` | array | Yes | Array of CIDR strings. Empty array clears. |

### `system_sdwan_update_network_routing_mode`

Set a network's routing protocol: 'static' (declarative AllowedIPs, no daemon) or 'ibgp' (slice 9c FRR + dynamic distribution). Until slice 9c lands, only 'static' is fully functional.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose routing mode to set |
| `routing_protocol` | string | Yes | static | ibgp |

### `system_sdwan_list_subnet_advertisements`

List route advertisements for a network — declared lan_subnets, VIP announcements (slice 9b), and BGP-learned routes (slice 9c) unified. Filterable by source.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose advertisements to list |
| `source` | string | No | Filter: declared_lan_subnet | virtual_ip | learned_via_bgp |
| `include_withdrawn` | boolean | No | Include withdrawn (inactive) advertisements (default false = active only) |

### `system_sdwan_get_routing_summary`

Routing-layer summary for a network: protocol, peer count, advertised prefixes, hub redundancy, BGP session count. Cheap; safe to poll.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network to summarize |

### `system_sdwan_create_virtual_ip`

Create a Virtual IP. Static mode (anycast=false) = single primary holder + ordered failover. Anycast mode (slice 9c iBGP) = all holders advertise simultaneously. CIDR is typically /32 (v4) or /128 (v6).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network the Virtual IP lives in |
| `name` | string | Yes | Display name for the Virtual IP |
| `cidr` | string | Yes | Host CIDR for the VIP (typically /32 for v4, /128 for v6) within the network's /64 |
| `holder_peer_ids` | array | Yes | Ordered: first entry is primary holder when anycast=false. |
| `failover_holder_peer_ids` | array | No | Ordered failover candidates (non-anycast); head is promoted on failover |
| `anycast` | boolean | No | When true, all holders advertise simultaneously (slice 9c iBGP); default false |
| `description` | string | No | Free-form description of the VIP's purpose |
| `tags` | array | No | Optional list of tag strings applied to the VIP |
| `advertised_med` | integer | No | BGP MULTI_EXIT_DISC advertised for this VIP (default 0) |
| `advertised_local_pref` | integer | No | BGP LOCAL_PREF advertised for this VIP (default 100) |

### `system_sdwan_list_virtual_ips`

List Virtual IPs in an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose Virtual IPs to list |
| `state` | string | No | Filter: pending|active|failing_over|unassigned|error |

### `system_sdwan_get_virtual_ip`

Fetch a Virtual IP with its assignment history (last 20 transitions)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | UUID of the SDWAN virtual IP to fetch |

### `system_sdwan_update_virtual_ip`

Update a Virtual IP's holders, failover candidates, anycast mode, advertised_med/local_pref, etc. Holder changes are recorded as 'holder_changed' assignment rows.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | UUID of the SDWAN virtual IP to update |
| `holder_peer_ids` | array | No | Ordered holder peer UUIDs; first is primary when anycast=false |
| `failover_holder_peer_ids` | array | No | Ordered failover candidate peer UUIDs (non-anycast) |
| `anycast` | boolean | No | When true, all holders advertise simultaneously (slice 9c iBGP) |
| `description` | string | No | Free-form description of the VIP's purpose |
| `tags` | array | No | Optional list of tag strings applied to the VIP |
| `advertised_med` | integer | No | BGP MULTI_EXIT_DISC advertised for this VIP |
| `advertised_local_pref` | integer | No | BGP LOCAL_PREF advertised for this VIP |

### `system_sdwan_delete_virtual_ip`

Delete a Virtual IP. Closes all active assignments + destroys the row.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | UUID of the SDWAN virtual IP to delete |

### `system_sdwan_failover_virtual_ip`

Manual failover for a non-anycast VIP — promotes the head of failover_holder_peer_ids to holder. Anycast VIPs don't fail over (all holders are active simultaneously).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | UUID of the SDWAN virtual IP to fail over |

### `system_sdwan_list_vip_assignments`

Audit-grade history of VIP holder transitions for a Virtual IP

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | UUID of the SDWAN virtual IP whose assignment history to list |

### `system_sdwan_get_account_bgp`

Read the account's iBGP config (AS number, router-id strategy, default local-pref). Returns null if AS not yet allocated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read
- **Parameters**: none

### `system_sdwan_update_account_as_number`

Allocate the account's private AS number (RFC 6996 4-byte private range). Idempotent — returns existing AccountBgp if already allocated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read
- **Parameters**: none

### `system_sdwan_get_bgp_sessions`

Live BGP session matrix across all networks (or filtered to one network). Returns observed sessions reported by agents — not desired state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | No | Filter to one network |
| `state` | string | No | idle | connect | active | opensent | openconfirm | established |

### `system_sdwan_get_bgp_config_for_peer`

Compile the full BGP config for one peer including frr.conf text. Useful for debugging routing issues.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer to compile BGP config for |

### `system_sdwan_list_route_policies`

List SDWAN route policies for the current account, optionally filtered by scope/direction.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | string | No | account | network | peer |
| `direction` | string | No | import | export |

### `system_sdwan_get_route_policy`

Fetch a route policy by id, including its full statement list.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | UUID of the SDWAN route policy to fetch |

### `system_sdwan_create_route_policy`

Create a route policy. statements is an ordered list of {match: {...}, action: {...}} objects. Compile output appears in TopologyCompiler#bgp.policies.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for the route policy |
| `scope` | string | Yes | account | network | peer |
| `direction` | string | Yes | import | export |
| `statements` | array | Yes | Ordered list of {match,action} hashes |
| `scope_resource_id` | string | No | UUID of the scoped resource (network or peer) when scope is 'network' or 'peer' |
| `description` | string | No | Free-form description of the policy's intent |
| `enabled` | boolean | No | Whether the policy is active and compiled into frr.conf |

### `system_sdwan_update_route_policy`

Update a route policy's name, scope, statements, or enabled state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | UUID of the SDWAN route policy to update |
| `options` | object | Yes | Hash of fields to update: name, description, scope, scope_resource_id, direction, enabled, statements, metadata |

### `system_sdwan_delete_route_policy`

Delete a route policy. The next agent reconcile removes the corresponding route-map from frr.conf.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | UUID of the SDWAN route policy to delete |

### `system_sdwan_compile_route_policy`

Compile policies in the context of one peer; returns the FRR fragment (prefix-lists, route-maps, neighbor assignments) that would land in that peer's frr.conf. Useful for 'show me what this policy will do' previews.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | UUID of the SDWAN peer to compile route policies for |

### `system_sdwan_list_port_mappings`

List hub DNAT port mappings for a network. Optionally filter by hub_peer_id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network whose port mappings to list |
| `hub_peer_id` | string | No | Optional UUID of the hub peer to filter mappings by |

### `system_sdwan_get_port_mapping`

Fetch a port mapping by id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | UUID of the SDWAN port mapping to fetch |

### `system_sdwan_create_port_mapping`

Create a hub DNAT mapping. Exactly one of target_peer_id or target_virtual_ip_id must be set. The hub peer must be in the same network as the target.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | UUID of the SDWAN network the mapping belongs to |
| `hub_peer_id` | string | Yes | UUID of the hub peer that listens for and DNATs the traffic |
| `name` | string | Yes | Display name for the port mapping |
| `listen_port` | integer | Yes | Port the hub listens on for inbound traffic |
| `protocol` | string | Yes | tcp | udp |
| `target_peer_id` | string | No | UUID of the target peer to DNAT to (mutually exclusive with target_virtual_ip_id) |
| `target_virtual_ip_id` | string | No | UUID of the target virtual IP to DNAT to (mutually exclusive with target_peer_id) |
| `target_port` | integer | No | Defaults to listen_port if omitted |
| `description` | string | No | Free-form description of the mapping |
| `enabled` | boolean | No | Whether the mapping is active (default true) |
| `rate_limit` | integer | No | Hardened DNAT tier (increment 6): max NEW CONNECTIONS per second (conntrack flows — the nat chain only sees each connection's first packet, so this throttles connection-establishment rate, not request/packet throughput). Omit for unrestricted (default). |
| `max_connections` | integer | No | Hardened DNAT tier (increment 6): max concurrent connections before excess are dropped. Omit for unrestricted (default). |
| `source_cidrs` | array | No | Hardened DNAT tier (increment 6): allow-list of source CIDR strings (v4 and/or v6). Traffic from any other source is dropped. Omit/empty for unrestricted (default). |

### `system_sdwan_update_port_mapping`

Update a port mapping's name, target, ports, protocol, enabled state, or hardening (rate_limit/max_connections/source_cidrs).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | UUID of the SDWAN port mapping to update |
| `options` | object | Yes | Hash of fields to update: name, description, target_peer_id, target_virtual_ip_id, listen_port, target_port, protocol, enabled, metadata, rate_limit, max_connections, source_cidrs. Pass rate_limit/max_connections as null or source_cidrs as [] to clear back to unrestricted. |

### `system_sdwan_delete_port_mapping`

Delete a port mapping. Agent removes the corresponding nft DNAT rule on next reconcile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | UUID of the SDWAN port mapping to delete |

### `system_sdwan_create_host_bridge`

Allocate a HostBridge for a NodeInstance via Sdwan::HostBridgeAllocator. Idempotent — returns the existing bridge of the requested kind on this host if one already exists. When `kind` is omitted the allocator picks 'ovs' for heavyweight hosts and 'linux' for lightweight hosts based on the host's network_profile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | UUID of the System::NodeInstance (host) to allocate a bridge on |
| `kind` | string | No | linux | ovs (defaults to host's network_profile mapping) |

### `system_sdwan_list_host_bridges`

List HostBridges for the current account. Optionally filter by node_instance_id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | No | Optional UUID of the System::NodeInstance (host) to filter bridges by |

### `system_sdwan_activate_host_bridge`

Mark a HostBridge as `active` so the topology compiler picks it up. Newly allocated bridges land in `pending`; the resolver only sees active bridges. Use this after create_host_bridge when the agent isn't yet reporting back its applied state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Sdwan::HostBridge id |

### `system_sdwan_release_host_bridge`

Release a HostBridge via Sdwan::HostBridgeAllocator.release!. Default `force: false` transitions the bridge to `draining` (preserves the short_id during in-flight tap teardown). Pass `force: true` to mark the bridge `removed` immediately, releasing the short_id back to the pool.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Sdwan::HostBridge id |
| `force` | boolean | No | When true, skip the draining grace window and mark removed immediately (default false) |

### `system_sdwan_create_ovn_deployment`

Create the per-account OVN control-plane deployment. One OvnDeployment per account (DB-enforced). Endpoints use OVN's standard `tcp:HOST:PORT` / `ssl:HOST:PORT` / `unix:PATH` form (defaults: NB 6641, SB 6642).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `nb_db_endpoint` | string | Yes | OVN Northbound DB endpoint, e.g. tcp:nb.example:6641 |
| `sb_db_endpoint` | string | Yes | OVN Southbound DB endpoint, e.g. tcp:sb.example:6642 |
| `northd_host` | string | No | Hostname (advisory) of the host running ovn-northd |
| `settings` | object | No | Free-form settings hash |

### `system_sdwan_create_ovn_logical_switch`

Create an OVN logical L2 switch under a deployment. Name is unique per deployment, max 63 chars, [letters/digits/_/-/.] only.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | UUID of the Sdwan::OvnDeployment this switch belongs to |
| `name` | string | Yes | Switch name (unique per deployment, max 63 chars, [letters/digits/_/-/.] only) |
| `cidr` | string | No | Optional subnet CIDR (sets up DHCP on the switch when present) |
| `description` | string | No | Free-form description of the logical switch |
| `settings` | object | No | Free-form settings hash for the logical switch |

### `system_sdwan_create_ovn_logical_switch_port`

Create an OVN logical switch port. `kind` drives compiler choices: vm | container = host-backed (host_node_instance_id required for proper placement); external = uplink/transit (no host required, gets lsp-set-type localnet by default). MAC is auto-generated (locally-administered `02:` prefix) when blank.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | UUID of the Sdwan::OvnLogicalSwitch this port attaches to |
| `name` | string | Yes | Port name (unique per switch) |
| `kind` | string | Yes | vm | container | external |
| `host_node_instance_id` | string | No | Required for vm/container ports; ignored for external |
| `addresses` | array | No | Array of IPv4/IPv6 strings; appended to the OVN `addresses=` line |
| `mac` | string | No | MAC in `xx:xx:xx:xx:xx:xx` form; auto-generated when blank |

### `system_sdwan_activate_ovn_logical_switch`

Mark an OvnLogicalSwitch as `active` so the compiler's `compilable` scope picks it up. Newly created switches land in `pending`; without activation `system_sdwan_compile_ovn_plan` silently omits them (and their ports/ACLs) with zero errors. Use this after create_ovn_logical_switch when the agent isn't yet reporting back its applied state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | Sdwan::OvnLogicalSwitch id |

### `system_sdwan_activate_ovn_logical_switch_port`

Mark an OvnLogicalSwitchPort as `active` so the compiler's `compilable` scope picks it up. Newly created ports land in `pending`; without activation they're excluded from the compiled plan even when their parent switch is active. Use this after create_ovn_logical_switch_port when the agent isn't yet reporting back its applied state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_id` | string | Yes | Sdwan::OvnLogicalSwitchPort id |

### `system_sdwan_compile_ovn_plan`

Compile the structured ovn-nbctl command plan for an OvnDeployment via Sdwan::OvnCompiler. Returns the full plan (deployment_id, plan: array of {cmd, args}, compiled_at). The compiler does NOT execute — it returns the plan as data for an executor or operator to replay against the NB DB.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | UUID of the Sdwan::OvnDeployment to compile a plan for |

### `system_sdwan_create_ipfix_collector`

Create an IPFIX collector for the current account. When an active collector exists, the topology compiler stamps an `ipfix:` block on every ovs-kind HostBridge in the per-host payload. Linux-bridge hosts ignore IPFIX (no native OVS support).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Operator-chosen label (unique per account) |
| `host` | string | Yes | Hostname or IP literal of the IPFIX collector |
| `port` | integer | No | UDP port (default 4739, the IANA-assigned IPFIX port) |
| `sampling_rate` | integer | No | 1-in-N packet sampling (default 1 = sample every packet) |

### `system_sdwan_list_ipfix_collectors`

List IPFIX collectors for the current account.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read
- **Parameters**: none

### `system_sdwan_create_ovn_acl`

Create an OVN ACL (firewall rule) on a logical switch. ACLs operate at the intra-host / logical-network scope (compiled to OVS OpenFlow via OVN's logical-flow translation) — distinct from SDWAN nftables firewall rules which operate at inter-peer scope. Heavyweight-profile only in effect.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | Sdwan::OvnLogicalSwitch id this ACL applies to |
| `name` | string | Yes | Operator-chosen name (unique per switch, max 63 chars, [letters/digits/_/-/.] only) |
| `direction` | string | Yes | from-lport (egress from source pod/VM) | to-lport (ingress to destination) |
| `priority` | integer | No | 0-32767, higher first; default 1000. Ties broken by lexicographic match-string order. |
| `match` | string | Yes | OVN match expression, e.g. `ip4.src == 10.0.0.0/8 && tcp.dst == 5432`. Raw OVN syntax — OVN's parser rejects bad values at apply time. |
| `acl_action` | string | Yes | allow | drop | reject | allow-related |

### `system_sdwan_list_ovn_acls`

List OVN ACLs for the current account. Optionally filter by logical_switch_id (per-switch scope) or sdwan_ovn_deployment_id (per-deployment scope). With no filter, returns every active ACL across every switch in every deployment.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | No | Restrict to ACLs on this switch |
| `sdwan_ovn_deployment_id` | string | No | Restrict to ACLs on switches under this deployment |

### `system_sdwan_delete_ovn_acl`

Delete an OVN ACL. Effect: ACL row destroyed and excluded from next OVN compile; northbound database reapplies on next reconcile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl_id` | string | Yes | Sdwan::OvnAcl id |

### `system_sdwan_delete_ovn_logical_switch`

Delete an OVN logical switch. Cascades attached logical switch ports and ACLs scoped to the switch.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | Sdwan::OvnLogicalSwitch id |

### `system_sdwan_delete_ovn_deployment`

Decommission an OVN deployment. Cascades logical switches, ports, and ACLs under it. Irreversible.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | Sdwan::OvnDeployment id |

### `system_sdwan_list_ovn_deployments`

List the account's OVN deployments (id, endpoints, status). Use to rediscover a deployment id when the create response was lost or a session restarted.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Optional status filter (pending | active | degraded | ...) |

### `system_sdwan_get_ovn_deployment`

Fetch one OVN deployment with its logical switches (each switch includes its ports), so an agent can rediscover the full topology and the ids it needs for compile/delete.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | Sdwan::OvnDeployment id |

### `system_sdwan_list_ovn_logical_switches`

List OVN logical switches (optionally scoped to a deployment), each with its ports so port ids are discoverable for system_sdwan_delete_ovn_logical_switch_port.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | No | Restrict to switches under this Sdwan::OvnDeployment |

### `system_sdwan_delete_ovn_logical_switch_port`

Delete a single OVN logical switch port (prune). Removes the port row + excludes it from the next OVN compile, leaving the switch and its other ports intact.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_id` | string | Yes | Sdwan::OvnLogicalSwitchPort id |

### `system_sdwan_delete_ipfix_collector`

Delete an IPFIX collector. Next topology compile drops the ipfix: block from per-host payloads.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: system.sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collector_id` | string | Yes | Sdwan::IpfixCollector id |

### `system_provision_docker_runtime`

Auto-register a Docker daemon for a NodeInstance with the docker-engine module assigned. Returns the managed Devops::DockerHost row in 'pending' status; promote to 'connected' via system_mark_docker_ready once the agent confirms the daemon is listening.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | System::NodeInstance ID; must already have an Sdwan::Peer with an assigned overlay address |

### `system_decommission_docker_runtime`

Tear down a managed Docker daemon: destroy the Devops::DockerHost row and purge its TLS material from Vault. The NodeInstance and its docker-engine module assignment are untouched — operator must unassign the module separately if they want the agent to stop dockerd.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Managed Docker host ID, slug, or name |

### `system_mark_docker_ready`

Promote a pending managed Docker host to 'connected' status. Called by the heartbeat receiver once the agent reports the daemon is up and serving its CA-signed cert.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Managed Docker host ID, slug, or name |
| `docker_version` | string | No | Daemon version string from the agent (e.g. '25.0.3') |

### `system_list_managed_docker_hosts`

List Docker hosts auto-provisioned by NodeInstance (provisioning_state='managed'). Excludes operator-registered external hosts — use docker_list_hosts for those.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage
- **Parameters**: none

### `kubernetes_list_clusters`

List all Kubernetes clusters in the account with status, flavor (k3s|kubeadm), node + pod counts

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read
- **Parameters**: none

### `kubernetes_get_cluster`

Detailed info on a specific Kubernetes cluster including k8s_version, sync state, and metadata

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_list_nodes`

List all member nodes of a Kubernetes cluster with their roles (server/agent/control_plane/worker) and status

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_decommission_cluster`

Destroy a managed Kubernetes cluster: removes the cluster row and cascade-deletes all member Devops::KubernetesNode rows. The underlying NodeInstances are NOT terminated — they remain available for reuse. Operator must separately unassign the k3s-server / k3s-agent modules to fully clean up. Irreversible.

- **Tool class**: `Ai::Tools::KubernetesProvisioningTool`
- **Permission**: kubernetes.clusters.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_get_kubeconfig`

Retrieve the kubeconfig YAML for a managed cluster. SENSITIVE: this is the cluster admin credential. Equivalent to root on every workload running in the cluster. Audit logged.

- **Tool class**: `Ai::Tools::KubernetesProvisioningTool`
- **Permission**: kubernetes.clusters.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `platform_provisioning_capture_brief`

Translate a natural-language utterance into a structured Project Brief. When mission_id is omitted, creates a new infrastructure mission bound to the system_provisioning template. When mission_id is provided, treats the utterance as a clarification and merges fields onto the existing brief. Returns the brief plus the list of fields still missing for plan composition.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | No | Existing infrastructure mission ID — omit to create a new one |
| `natural_language` | string | Yes | Operator's natural-language description of what they want to provision |
| `prior_brief` | object | No | Optional existing brief to merge new fields onto (auto-loaded from mission.configuration['brief'] when mission_id is given) |

### `platform_provisioning_compose_plan`

Run the LLM goal-decomposition kernel against the mission's brief and produce a persisted Ai::GoalPlan whose steps are rewritten into provisioning_skill shape. Returns the DAG plus M1 enrichments: cost_estimate (CostEstimatorService), topology_preview (TopologyRendererService), and risk (RiskScorerService).

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |

### `platform_provisioning_approve_plan`

Operator decision on a composed plan. decision='approved' advances the mission past the review_plan gate; 'rejected' sends it back to compose_plan via rejection_mappings; 'modified' applies inline edits to the plan steps before approving. The optional approval_request_id field in the response is reserved for M1 when this routes through the formal approval pipeline.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `plan_id` | string | Yes | Ai::GoalPlan ID returned by compose_plan |
| `decision` | string | Yes | One of: approved, rejected, modified |
| `modifications` | object | No | Optional plan-step edits to apply when decision='modified' (shape: { steps: [{ step_number: Int, skill: String }] }) |

### `platform_provisioning_status`

Snapshot of provisioning progress: mission phase, currently-executing step number, and step-number lists by status (completed, pending, failed). For live streaming subscribe to MissionChannel rather than polling this.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |

### `platform_provisioning_adapt`

M0 stub — adaptation engine ships with the ProjectSloSensor reconciler in M2. Returns { todo: 'M2', adaptation_plan: nil } today; will accept a proposed_change (scale_horizontal, cost_control, schema_change, etc.) and return a remediation plan in M2.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |
| `proposed_change` | object | No | Optional shape of the adaptation; ignored in M0 |

### `set_gitea_action_secret`

Create or update a per-repo Actions secret. Plaintext value never echoed back; subsequent list_gitea_action_secrets returns names only.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `secret_name` | string | Yes | Secret key (e.g. POWERNODE_DISK_IMAGE_WEBHOOK_SECRET) |
| `secret_value` | string | Yes | Secret plaintext to store |

### `set_gitea_action_secrets_bulk`

Set multiple per-repo Actions secrets in one call (efficiency wrapper). Replaces existing values; missing keys are unchanged.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `secrets` | object | Yes | Hash of {SECRET_NAME: 'plaintext value', ...}. Names beginning with GITEA_ or GITHUB_ are reserved by Gitea — use a different prefix (e.g. PLATFORM_READ_TOKEN). |

### `list_gitea_action_secrets`

List secret names for a repo (values not returned by Gitea API)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |

### `delete_gitea_action_secret`

Delete a per-repo Actions secret

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `secret_name` | string | Yes | Name of the secret to delete (from list_gitea_action_secrets) |

### `dispatch_gitea_workflow`

Trigger a workflow_dispatch event for a Gitea Actions workflow

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `workflow_file` | string | Yes | Workflow filename (e.g. 'build-disk-image.yaml') |
| `ref` | string | Yes | Branch/tag ref (e.g. 'master') |
| `inputs` | object | No | Workflow input values as a hash |

### `list_gitea_workflows`

List all workflows defined in a repo (returns name + state for each .gitea/workflows/*.yaml file)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |

### `list_gitea_workflow_runs`

List recent workflow runs for a repo (optionally filtered by workflow_file)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `workflow_file` | string | No | Filter to a specific workflow filename |
| `limit` | integer | No | Max results (default 20) |

### `get_gitea_workflow_run`

Get a specific workflow run including its jobs

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID (from list_gitea_workflow_runs) |

### `get_gitea_job_logs`

Fetch the raw log text for a workflow job. Useful for diagnosing failed runs without leaving the chat.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `job_id` | string | Yes | Job ID from get_gitea_workflow_run.jobs[].id |
| `tail` | integer | No | Return only the last N lines (default: full log) |
| `grep` | string | No | Filter to lines matching this regex (case-insensitive) |

### `cancel_gitea_workflow_run`

Attempt to cancel a queued or in-progress run. USUALLY FAILS: Gitea exposes no cancel endpoint through 1.27.0, so this returns unsupported=true with an explanation on those versions — it is attempted rather than hardcoded so a future Gitea that adds cancel starts working with no code change. Do NOT route a 'stop this run' request here expecting it to succeed; the run must finish, be discarded via delete_gitea_workflow_run (destructive, and does not stop a running job), or be stopped by tearing down its CI runner.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID (from list_gitea_workflow_runs) |

### `delete_gitea_workflow_run`

DESTRUCTIVE: discard a workflow run and its logs. This is NOT a cancel — it does not stop a running job, and the run's logs are unrecoverable afterwards. Gitea exposes no cancel API, so this is the only run-level mutation available; use it only when you actually want the record gone.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID to delete |

### `rerun_gitea_workflow`

Re-run a completed workflow run (useful for retrying transient failures)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID (from list_gitea_workflow_runs) |

### `rerun_gitea_workflow_failed_jobs`

Re-run ONLY the failed jobs of a run, leaving successful jobs alone. Prefer this over rerun_gitea_workflow when one leg of a matrix failed — it avoids repeating work that already passed.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID (from list_gitea_workflow_runs) |

### `rerun_gitea_job`

Re-run a single job within a run. The scalpel for a fan-out where one matrix leg failed and the rest are fine.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID |
| `job_id` | string | Yes | Job ID from get_gitea_workflow_run.jobs[].id |

### `list_gitea_run_artifacts`

List artifacts produced by a workflow run

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner — the user or organization login that owns the repo |
| `repo` | string | Yes | Repository name (without the owner/ prefix) |
| `run_id` | string | Yes | Gitea Actions workflow run ID |

### `create_gitea_user_token`

Create a personal access token for the authenticated Gitea user. Returns plaintext EXACTLY ONCE — caller must capture. Use to mint scoped read tokens for CI workflows without leaving the chat.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token_name` | string | Yes | Human-readable name for the token (e.g. 'platform-ci-readonly') |
| `scopes` | array | No | Gitea scope strings (default: ['read:repository']). Common: read:repository, write:repository, read:user, write:user, write:package |
| `set_as_secret` | object | No | Optional: immediately set the new token as a Gitea Actions secret. Hash: {owner, repo, secret_name}. Combines mint + paste in one call. |

### `list_gitea_user_tokens`

List the authenticated user's personal access tokens (names + scopes only — plaintext is never returned by Gitea after creation)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update
- **Parameters**: none

### `delete_gitea_user_token`

Delete a personal access token by name or numeric ID. Used for rotation or cleanup.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name_or_id` | string | Yes | Token name or numeric ID (from list_gitea_user_tokens) |

### `provision_disk_image_webhook`

Create a per-pipeline disk-image webhook for the current account. Returns plaintext secret + absolute URL EXACTLY ONCE — caller must capture both, no recovery.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | Yes | Operator-chosen identifier (unique per account, e.g. 'main-ci', 'release-pipeline') |

### `provision_ci_worker`

Create a per-pipeline CI worker (narrowly scoped: system.platforms.publish_disk_image only). Returns plaintext token EXACTLY ONCE.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Operator-chosen name (e.g. 'release-pipeline-runner') |
| `description` | string | No | Optional description shown in the operator UI |

### `bootstrap_disk_image_ci`

End-to-end setup: provision webhook + CI worker, set all 4 needed Gitea Actions secrets in one call (POWERNODE_DISK_IMAGE_WEBHOOK_URL, POWERNODE_DISK_IMAGE_WEBHOOK_SECRET, POWERNODE_CI_WORKER_TOKEN, POWERNODE_API_BASE). Optionally also mints a Gitea PAT and sets it as PLATFORM_READ_TOKEN for the parent platform checkout step. Idempotent: re-running with the same label rotates secrets + token.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Gitea repo owner |
| `repo` | string | Yes | Gitea repo name |
| `label` | string | Yes | Operator-chosen identifier (used for both webhook label and CI worker name) |
| `platform_api_base` | string | No | Public-routable platform API base URL CI runners will call back to (default: ENV['POWERNODE_PUBLIC_URL'] or 'http://localhost:3000') |
| `create_platform_read_token` | boolean | No | When true (default false), mint a Gitea PAT with read:repository scope and set it as PLATFORM_READ_TOKEN secret in the same repo. Closes the manual 'go to Gitea web UI to generate a PAT' step. |
| `platform_read_token_name` | string | No | Override the auto-generated PAT name (default: '<label>-platform-ci-readonly') |

### `list_ralph_loops`

List all Ralph Loops with status, agent assignment, schedule config, and pause state

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `get_ralph_loop`

Get detailed Ralph Loop info including iterations, schedule config, and agent assignment

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `pause_ralph_loop`

Pause a Ralph Loop's autonomous scheduling. Running iterations complete but no new ones start.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `reason` | string | No | Reason for pausing |

### `resume_ralph_loop`

Resume a paused Ralph Loop's autonomous scheduling

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `update_ralph_loop`

Update mutable Ralph Loop config: name, default_agent_id, cycle_interval_minutes, max_iterations_per_day, max_iterations, schedule_paused. Useful for repointing default_agent_id when consolidating duplicate agents, adjusting cadence without delete+recreate, or raising a loop's lifetime iteration cap before it halts on max_iterations_reached.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `name` | string | No | New loop name |
| `default_agent_id` | string | No | Repoint to a different agent (UUID, slug, or name) |
| `cycle_interval_minutes` | integer | No | Time between iterations in minutes |
| `max_iterations_per_day` | integer | No | Daily iteration cap |
| `max_iterations` | integer | No | Lifetime iteration cap (distinct from the daily max_iterations_per_day throttle) |
| `schedule_paused` | boolean | No | Pause/resume scheduling without a state machine event |

### `delete_ralph_loop`

Delete a Ralph Loop permanently. Cannot be undone.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `get_ralph_loop_statistics`

Get aggregate statistics across all Ralph Loops — iteration counts, success rates, timing, improvement scoreboard, and the convergence metric (recurrence rate of already-learned bug classes per discovery window)

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `dev_next_task`

Claim the next pending task from a Ralph Loop queue (priority/dependency ordered). Returns the task with acceptance criteria, guardrails, and loop context. Idempotent: re-claiming returns your own in-progress task. Refuses when the loop is halted (kill switch, paused, terminal, max iterations).

- **Tool class**: `Ai::Tools::DevLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `holder` | string | No | Driver identity (lease holder). For a campaign loop the single-driver lease gates pulls — pass the same holder you claimed the campaign with; the pull renews the lease so another driver can't race in. |

### `dev_complete_task`

Report the outcome of a claimed (in_progress) task, OR resolve a blocked task (operator disposition — no re-claim needed). Records a RalphIteration with verification evidence, transitions the task (passed/failed/blocked/skipped), and captures learnings on the loop.

- **Tool class**: `Ai::Tools::DevLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `task_key` | string | Yes | Task key being reported |
| `outcome` | string | Yes | passed | failed | blocked | skipped |
| `summary` | string | Yes | What was done / why it failed, blocked, or was skipped |
| `check_results` | object | No | Verification evidence (specs run, results) |
| `learning` | string | No | Reusable learning extracted from this task |
| `git_branch` | string | No | Branch the work was committed to |
| `commit_sha` | string | No | Commit SHA for the passed task |
| `files_changed` | array | No | Paths touched by this task |

### `dev_list_tasks`

List tasks in a Ralph Loop queue, optionally filtered by status (pending | in_progress | passed | failed | blocked | skipped). Use to inspect blocked tasks awaiting disposition or audit the queue. Ordered by position then priority.

- **Tool class**: `Ai::Tools::DevLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `status` | string | No | Filter by status: pending | in_progress | passed | failed | blocked | skipped (omit for all) |
| `limit` | integer | No | Max tasks to return (default 50, max 200) |

### `delegate_ralph_task`

Hand a pending/in-progress Ralph task to a platform agent (A2A) instead of executing it yourself. Reuses spawn_task's capability-matrix + delegation-authority checks. With await, blocks until the agent finishes and records the outcome on the loop. No-op when halted.

- **Tool class**: `Ai::Tools::DevLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `task_key` | string | Yes | Task to delegate |
| `agent_id` | string | Yes | Platform agent to delegate to |
| `await` | boolean | No | Block until the agent finishes (default false) |
| `timeout` | integer | No | Await timeout seconds (max 300) |
| `budget_cents` | integer | No | Budget for the delegated task |

### `deliver`

Deliver a ref to a target via a strategy. direct delegates to Ai::Deploy (migration-safety + health + auto-rollback); canary/blue_green record the staged rollout plan. DRY-RUN by default — pass dry_run:false for a real delivery.

- **Tool class**: `Ai::Tools::DeliveryTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target_kind` | string | No | platform_self | project (default project) |
| `repository_id` | string | No | Devops::GitRepository UUID (project) |
| `environment` | string | No | Target environment (default production) |
| `strategy` | string | No | direct | canary | blue_green (default direct) |
| `ref` | string | No | Git ref/SHA to deliver |
| `base_ref` | string | No | Previously-delivered ref |
| `config` | object | No | Method/strategy overrides |
| `dry_run` | boolean | No | Describe without mutating (default true) |

### `delivery_status`

Get a delivery run's status (strategy, phase/steps, underlying deploy run).

- **Tool class**: `Ai::Tools::DeliveryTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `delivery_id` | string | Yes | DeliveryRun UUID |

### `delivery_list`

List this account's recent delivery runs (newest first).

- **Tool class**: `Ai::Tools::DeliveryTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max rows (default 50) |

### `discover_improvements`

Guidance for running discovery: run code_static_analysis + pattern-validation.sh (and code_dead_code / code_find_duplicates), verify each finding reproduces on HEAD, then call create_improvement for each vetted finding. Pass class_tag (a recurring bug-class learning tag) to switch to a targeted class-sweep that returns the known instances and exhausts every pattern match of the class in ONE pass.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `class_tag` | string | No | Recurring-bug-class learning tag, e.g. class:server-worker-jobseam |

### `create_improvement`

Persist one vetted code-quality finding as a pending offer. Idempotent on fingerprint (re-creating updates the open offer). Findings under extensions/private/* are tagged to the extension (gate #9), never globalized.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendation_type` | string | Yes | code_lint | dead_code | code_duplication | convention_adherence | test_gap |
| `title` | string | Yes | Short finding title |
| `fingerprint` | string | Yes | Stable dedupe key, e.g. kind|file|rule |
| `repository` | string | No | Repository id/full_name; resolved to a GitRepository target when known |
| `description` | string | No | What to fix and why |
| `files` | array | No | Files the finding touches |
| `fix` | string | No | Suggested fix / acceptance detail |
| `verifier_evidence` | string | No | Proof the finding reproduces on HEAD |
| `confidence_score` | number | No | 0..1 confidence (default 0.6) |

### `list_improvements`

List improvement offers, newest first.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | pending | approved | applied | dismissed (default pending) |
| `repository` | string | No | Filter by repository (id/full_name); matches the GitRepository target or legacy tag |

### `approve_improvement`

Approve an offer and promote it to a dev-improve Ralph Loop task that /dev-loop drains. No-op (halted) when the account kill switch is active.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendation_id` | string | Yes | Recommendation to approve |

### `dismiss_improvement`

Dismiss an offer so it is never promoted.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendation_id` | string | Yes | Recommendation to dismiss |

### `revert_improvement`

Mark the dev-improve task promoted from a recommendation as reverted (ground-truth signal for the ungameable metric). Works even while the kill switch is active.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendation_id` | string | Yes | Recommendation whose promoted task was reverted |
| `reason` | string | No | Why it was reverted |

### `enable_autonomy`

Gated opt-in: flip the dev-improve loop to unattended autonomous push drained by a capability-matched platform agent. OFF by default; refused while the kill switch is active.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent (UUID/slug/name) to drain the loop |
| `max_iterations_per_day` | integer | No | Daily iteration cap |

### `disable_autonomy`

Return the dev-improve loop to operator-driven (pull) execution.

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `scoreboard`

Improvement scoreboard: discovered/approved/applied/dismissed offer counts plus the ungameable metric (revert-adjusted net_improvement_velocity + per-kind revert_rate).

- **Tool class**: `Ai::Tools::ImprovementTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `start_content_production`

Create and start a content_production mission plus its asset bundle. Returns the mission + bundle.

- **Tool class**: `Ai::Tools::ContentProductionMissionTool`
- **Permission**: ai.missions.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Production name |
| `bundle_type` | string | No | video_project, document, image_album, audio_album, mixed (default: video_project) |
| `brief` | object | No | Content brief: goal, format, audience, constraints |

### `content_production_status`

Get the status and current phase of a content_production mission.

- **Tool class**: `Ai::Tools::ContentProductionMissionTool`
- **Permission**: ai.missions.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | The content_production mission id |

### `generate_video`

Generate a video clip from a prompt via Runway and store it as an ai_generated file.

- **Tool class**: `Ai::Tools::VideoGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video to generate |
| `model` | string | No | Runway model (defaults to provider config) |
| `duration` | integer | No | Clip duration in seconds |
| `ratio` | string | No | Aspect ratio, e.g. 1280:768 |
| `filename` | string | No | Output filename (auto-generated if omitted) |

### `generate_audio`

Synthesize speech/voiceover from text via ElevenLabs and store it as an ai_generated file.

- **Tool class**: `Ai::Tools::AudioGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to synthesize into speech |
| `voice_id` | string | No | ElevenLabs voice id (defaults to provider/credential config) |
| `model` | string | No | ElevenLabs model (defaults to provider config) |
| `filename` | string | No | Output filename (auto-generated if omitted) |

### `data_source_list`

List AI data sources for the current account with health + credential counts

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_type` | string | No | Filter by source type |
| `is_active` | boolean | No | Filter by active state |

### `data_source_get`

Get a single data source with configuration, rate limits, credentials, and quota summary

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_describe`

Describe a data source's endpoints, including HTTP method, path, response format, and response schemas

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | No | Limit to a single endpoint UUID or slug |

### `data_source_query`

Run a governed external fetch through Ai::DataSources::QueryService (kill flag, quota, cache, circuit breaker, SSRF guard, decode, normalize, schema-validate, redact, audit). Returns a FetchEnvelope. A write/side-effecting endpoint (e.g. POST /2/tweets) additionally requires ai.data_sources.manage; without it, files a proposal instead of dispatching the live call.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to fetch |
| `params` | object | No | Query/path/body parameters for the endpoint |

### `data_source_health`

Report a data source's quota summary, response-cache metrics, and circuit-breaker state

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_validate_config`

Validate a data source's configuration: SSRF-safe base URL, known auth scheme, supported protocol/formats

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_discover`

Semantically discover data sources for a natural-language need via Ai::DataSources::SemanticDiscoveryService (embedding + pgvector nearest-neighbor, blended with effectiveness/health/recency trust signals). Falls back to keyword name matching when no embedding backend is available.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language description of the data need |
| `limit` | integer | No | Max ranked results (default 10) |
| `rerank` | boolean | No | Refine top candidates with the RAG reranker (default false) |

### `data_source_provenance`

Return the provenance of a recorded fetch from the ai_data_source_queries audit log: source, endpoint, fetched_at, response_sha256, redacted_url, schema_valid, cached/served_stage, cost, and audit-chain anchor. Looks up by query_id, then correlation_id, else the latest query for a data_source (optionally scoped to an endpoint).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query_id` | string | No | ai_data_source_queries row UUID |
| `correlation_id` | string | No | Fetch correlation id |
| `data_source_id` | string | No | Data source UUID or slug (latest-query fallback) |
| `endpoint_id` | string | No | Endpoint UUID or slug to scope the latest-query fallback |

### `data_source_impact`

Usage + trust summary for a data source: distinct requesting agents, total/successful/failed/cached query counts, last_used_at, effectiveness_score, usage success rate, and health status.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_schema_history`

Return an endpoint's recorded schema-version history (version list with classification initial|none|additive|breaking) plus the latest version's structural diff. Populated when the endpoint opts into track_schema and a fetch runs through QueryService.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |

### `data_source_quality`

Return an endpoint's latest data-quality outcome (quality_score / quality_passed / quarantined from the most recent query) and its configured Ai::DataSourceExpectation rules.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |

### `data_source_introspect`

Import an OpenAPI 3 spec into endpoints via Ai::DataSources::OpenApiImportService (paths -> endpoints, 200 response schema resolved against components/schemas). Requires ai.data_sources.manage. Supports dry_run to preview without persisting.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `spec` | object | Yes | Parsed OpenAPI 3 document (Hash) |
| `dry_run` | boolean | No | Preview without creating endpoints (default false) |

### `data_source_contract`

Run Ai::DataSources::ContractService for a source+endpoint: performs a governed fetch then aggregates schema_valid + quality_passed + within_sla into a single contract verdict (met + violations). A write/side-effecting endpoint additionally requires ai.data_sources.manage; without it, files a proposal instead of dispatching the live call.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |
| `params` | object | No | Query/path/body parameters for the fetch |

### `data_source_subscribe`

Create or update a pull-based subscription to an endpoint (Ai::DataSourceSubscription). The server-side monitor polls due subscriptions on the given cadence, change-detects (etag/checksum), warms the cache and emits a data_source_changed signal on change. Requires ai.data_sources.stream.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to subscribe to |
| `params` | object | No | Query/path/body parameters passed to each poll |
| `poll_frequency` | string | No | Cadence: manual|5min|hourly|daily|weekly|monthly|realtime (default hourly) |

### `data_source_unsubscribe`

Remove a pull-based subscription. Provide subscription_id, or data_source_id + endpoint_id to remove the matching subscription(s). Requires ai.data_sources.stream.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | No | Subscription UUID |
| `data_source_id` | string | No | Data source UUID or slug (with endpoint_id) |
| `endpoint_id` | string | No | Endpoint UUID or slug (with data_source_id) |

### `data_source_create`

Create a new data source (requires ai.data_sources.create or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Data source name |
| `source_type` | string | Yes | Source type (e.g. open_meteo, fred, custom) |
| `api_base_url` | string | No | Base URL |
| `slug` | string | No | Optional slug (auto-generated when omitted) |
| `description` | string | No | Description |
| `is_active` | boolean | No | Active flag (default true) |
| `requires_auth` | boolean | No | Requires auth flag |
| `priority_order` | integer | No | Priority order |
| `configuration` | object | No | Configuration hash |
| `rate_limits` | object | No | Rate limits hash |

### `data_source_update`

Update an existing data source (requires ai.data_sources.update or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `name` | string | No | New name |
| `source_type` | string | No | New source type |
| `api_base_url` | string | No | New base URL |
| `description` | string | No | New description |
| `is_active` | boolean | No | Active flag |
| `requires_auth` | boolean | No | Requires auth flag |
| `priority_order` | integer | No | Priority order |
| `configuration` | object | No | Configuration hash |
| `rate_limits` | object | No | Rate limits hash |

### `data_source_delete`

Delete a data source (requires ai.data_sources.delete or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_invalidate_cache`

Invalidate cached responses via Ai::DataSources::ResponseCacheService. With a tag, clears every entry under that surrogate key (ResponseCacheService.invalidate_by_tag). Otherwise clears by scope: data_source + endpoint_id clears that endpoint's variants, data_source alone clears all of the source's entries. Requires ai.data_sources.update (or .manage).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | No | Data source UUID or slug (required unless tag is given) |
| `endpoint_id` | string | No | Endpoint UUID or slug to scope the invalidation |
| `tag` | string | No | Surrogate cache tag (e.g. ds:<id>, endpoint:<id>, slug:<slug>); takes precedence over scope |

### `data_source_export`

Export a data source's CREDENTIAL-FREE config manifest via Ai::DataSources::ConfigPortabilityService#export (source + endpoints MINUS all secrets). The manifest carries the auth_scheme NAME and non-secret broker knobs only — never api keys, credentials, or secret auth_config values. Re-importable to recreate the source elsewhere.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_import`

Import a CREDENTIAL-FREE config manifest into the account via Ai::DataSources::ConfigPortabilityService#import (create-or-update the source by slug, upsert endpoints by slug, all in one transaction). NEVER sets credentials — attach those separately after import. Requires ai.data_sources.create or .manage; agents lacking it file a proposal. Supports dry_run to preview the create/update plan without persisting.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manifest` | object | Yes | Credential-free manifest (as produced by data_source_export) |
| `slug` | string | No | Override target source slug (clones under a new slug; name auto-deduped) |
| `dry_run` | boolean | No | Preview the create/update plan without persisting (default false) |

### `data_source_list_templates`

List the built-in library of reusable, credential-free data-source templates (Ai::DataSources::TemplateLibrary). Each entry is a starter manifest for a well-known or generic source: slug, name, description, category.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read
- **Parameters**: none

### `data_source_install_template`

Install a library template by slug into the account via Ai::DataSources::TemplateLibrary.install (materializes the template's credential-free manifest through ConfigPortabilityService#import). NEVER sets credentials — attach those afterward if the source requires auth. Requires ai.data_sources.create or .manage; agents lacking it file a proposal.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_slug` | string | Yes | Catalog slug of the template to install (see data_source_list_templates) |

### `data_source_config_versions`

List a data source's append-only config-version history (Ai::DataSourceConfigVersion), latest first: version number, created_by_type (auto|manual|rollback), note, and created_at. Each row is a credential-free manifest snapshot captured by snapshot!/rollback.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_rollback_config`

Roll a data source's config back to a prior version via Ai::DataSources::ConfigPortabilityService#rollback! (captures the current state as a new 'rollback' snapshot first, then replays the historical manifest — credentials are never touched). Requires ai.data_sources.manage; agents lacking it file a proposal.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `version` | integer | Yes | Config version NUMBER to restore |

### `data_source_reconcile`

DETERMINISTIC multi-source merge: governed-fetch every target (Ai::DataSources::QueryService) INDEPENDENTLY, collect each successful FetchEnvelope's records, then collapse them into one list by EXACT canonical-key match via Ai::DataSources::ReconciliationService (strategy first_wins|last_wins|merge). No cross-source SQL/join, no fuzzy entity resolution — exact key merge only. Requires ai.data_sources.query (it fetches). A write/side-effecting target endpoint additionally requires ai.data_sources.manage; without it, that target files a proposal instead of dispatching the live call. Returns the merged records plus per-source status.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `targets` | array | Yes | Targets to fetch + merge; each { data_source_id, endpoint_id } |
| `key` | string | Yes | Canonical key field name shared across the sources |
| `strategy` | string | No | Merge strategy: first_wins|last_wins|merge (default last_wins) |
| `params` | object | No | Query params forwarded to EVERY target fetch |

### `data_source_failover_query`

Ordered FAILOVER across equivalent targets via Ai::DataSources::FailoverService#query: try each { data_source_id, endpoint_id } IN ORDER (primary first) through the full governed QueryService pipeline and return the FIRST success; if all fail, return the last failure envelope. Requires ai.data_sources.query. If ANY target is a write/side-effecting endpoint the agent lacks ai.data_sources.manage for, the whole call files a proposal instead of dispatching. Returns the winning FetchEnvelope with failover provenance (failover_used/failover_attempts/failover_source).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `targets` | array | Yes | Ordered targets (primary first); each { data_source_id, endpoint_id } |
| `params` | object | No | Query params forwarded to every attempt |

### `data_source_replay`

Forensic, side-effect-free REPLAY of a recorded fetch via Ai::DataSources::ReplayService#replay: reconstruct a FetchEnvelope-shaped view from the redacted ai_data_source_queries audit row WITHOUT any network call, signing, or credential resolution. The cached body (when still present and the original params are supplied) is RE-MASKED for the current requester. Requires ai.data_sources.read.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query_id` | string | No | ai_data_source_queries row UUID to replay |
| `correlation_id` | string | No | Fetch correlation id to replay |
| `params` | object | No | Original request params — supplied ONLY to recover the cached (re-masked) body |

### `data_source_ingest_to_kb`

RAG ingestion bridge: governed-fetch a source+endpoint (Ai::DataSources::QueryService) then pipe the canonical records into a knowledge base as embedded Ai::Document rows via Ai::DataSources::RagIngestionService#ingest (source_type "api", incremental re-embed dedup by record key). Requires ai.data_sources.manage (it writes documents/embeddings); agents lacking it file a proposal. Returns the ingest counts (ingested/updated/skipped/capped/errors).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug to fetch from |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to fetch |
| `knowledge_base_id` | string | Yes | Target knowledge base UUID |
| `key` | string | No | Canonical record-key field for incremental re-embed dedup (optional) |
| `params` | object | No | Query/path/body parameters for the fetch |

### `code_context_tree`

Get an AST-based structural tree of the codebase with file headers and symbol ranges. Dynamic pruning by depth.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to scan (default: root) |
| `max_depth` | integer | No | Maximum tree depth (default 3) |
| `include_symbols` | boolean | No | Include parsed symbols (default true) |

### `code_file_skeleton`

Get function signatures, class methods, and type definitions for a file — no function bodies, just the structure with line ranges.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `file_path` | string | Yes | File path relative to codebase root |

### `code_semantic_search`

Semantic search over code symbols using embeddings. Finds code by meaning, not just name.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Search query |
| `entity_types` | array | No | Filter by entity types (class, method, function, etc.) |
| `top_k` | integer | No | Max results (default 10) |

### `code_identifier_search`

Search for identifiers (functions, classes, variables) by name or semantic meaning with usage counts.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Identifier name or description |
| `entity_types` | array | No | Filter by entity types |
| `top_k` | integer | No | Max results (default 10) |

### `code_semantic_navigate`

Browse the codebase by meaning using semantic clustering. Groups related files and symbols into labeled clusters.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | No | Optional focus query to filter clusters |
| `cluster_id` | integer | No | Specific cluster ID to inspect |

### `code_feature_hub`

Obsidian-style feature navigation from markdown files with [[wikilinks]]. Discovers documentation structure and orphan files.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to scan (default: docs/) |

### `code_blast_radius`

Trace every file and line where a symbol is imported or used. Shows the impact radius of changing a function, class, or module.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `symbol_name` | string | No | Symbol name (qualified or simple) |
| `node_id` | string | No | Knowledge graph node ID |
| `max_depth` | integer | No | Maximum traversal depth (default 3, max 5) |

### `code_static_analysis`

Run native linters and compilers (RuboCop, TypeScript, ESLint). Returns structured diagnostics with file, line, severity, and message.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to analyze |
| `linters` | array | No | Linters to run: ruby, typescript, javascript_lint |

### `code_index_status`

Show codebase indexing statistics: files indexed, symbols extracted, last indexed timestamp, stale files count.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |

### `code_dead_code`

Detect dead code via language-native analyzers (ts-prune for TS, debride for Ruby) + grep verification + AI triage. Async — dispatched to the worker; the categorized result (real_dead / public_api / dynamic_dispatch / test_only / uncertain) is written to shared memory, retrieve via read_shared_memory.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `languages` | array | No | Subset of [typescript, ruby] (default: both) |
| `triage` | boolean | No | Run LLM triage of verified candidates (default: true) |
| `model` | string | No | Override the triage LLM model |

### `code_find_duplicates`

Detect copy-paste code clones via jscpd (token-based) + AI triage. Async — dispatched to the worker; the categorized result (extract_candidate / acceptable / generated / coincidental, with suggested actions) is written to shared memory, retrieve via read_shared_memory.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `scope_paths` | array | No | Subdirs to scan (default: frontend/src, server/app, worker/app) |
| `min_tokens` | integer | No | Clone size floor in tokens (default: 50) |
| `triage` | boolean | No | Run LLM triage of clone groups (default: true) |
| `model` | string | No | Override the triage LLM model |

### `code_analyze_section`

Run focused dead code + duplicate analysis on a codebase section. Omit section to auto-discover sections. Use scope_path to limit discovery to a subtree.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `section` | string | No | Section path to analyze (e.g. 'server/app/models', 'frontend/src/features'). Omit to list available sections. |
| `scope_path` | string | No | Limit section discovery to a subtree (e.g. 'server/app/services', 'frontend/src') |
| `dead_code` | boolean | No | Run dead code detection (default: true) |
| `duplicates` | boolean | No | Run duplicate detection (default: true) |
| `duplicate_threshold` | number | No | Similarity threshold for duplicates (default: 0.92) |
| `min_dead_score` | number | No | Minimum deadness score (default: 0.5) |

### `code_upsert_node`

Create or update a code-aware knowledge graph node. Auto-generates embeddings for semantic search.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `name` | string | Yes | Qualified node name (e.g. 'User#full_name') |
| `entity_type` | string | Yes | Entity type: file, directory, class, module, method, function, variable, type_definition, interface, constant |
| `file_path` | string | No | File path relative to codebase root |
| `line_range` | string | No | Line range (e.g. '10-25') |
| `description` | string | No | Human-readable description |
| `properties` | object | No | Additional metadata |

### `code_create_relation`

Create a typed edge between two code nodes (e.g. imports, calls, inherits).

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_node_id` | string | Yes | Source node ID |
| `target_node_id` | string | Yes | Target node ID |
| `relation_type` | string | Yes | Relation type: imports, calls, defines, inherits, implements, contains, related_to, depends_on, uses |
| `weight` | number | No | Edge weight 0-1 (default 1.0) |
| `properties` | object | No | Edge metadata |

### `code_search_graph`

Search the code graph with optional multi-hop traversal. Combines name matching with graph expansion.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Search query |
| `entity_types` | array | No | Filter by entity types |
| `max_depth` | integer | No | Graph traversal depth (default 2) |
| `top_k` | integer | No | Max results (default 10) |

### `code_prune_stale`

Find and remove/archive code nodes for files that no longer exist on disk (async — dispatched to the worker; result written to shared memory, retrieve via read_shared_memory). Use dry_run to preview.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `dry_run` | boolean | No | Preview without executing (default true) |

### `code_bulk_index`

Trigger codebase indexing (async — dispatched to the worker; returns immediately). Parses source files, creates knowledge graph nodes/edges, and generates embeddings. Track progress with code_index_status.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to index (default: entire codebase) |
| `incremental` | boolean | No | Only re-index changed files (default true) |

---

## Improvement Campaigns

### `campaign_propose`

Propose a new improvement/feature CAMPAIGN into the discovery/delegation queue (deduped per target). Use THIS for any request to create, propose, or queue a CAMPAIGN — NOT the generic create_proposal (which is for agent change-proposals). Returns the proposal; approve it with campaign_approve_proposal to spawn the campaign.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Short proposal title |
| `objective` | string | Yes | What the campaign should accomplish |
| `source` | string | No | discovery|trajectory|improvement|manual (default manual) |
| `scope` | string | No | Target/repo scope label (used for per-target dedupe) |
| `suggested_workload` | string | No | improvement-campaign|feature-development|new-project |
| `suggested_driver` | string | No | claude_code|platform_agent|platform_team|platform_mission |
| `decision_authority` | string | No | supervised|monitored|trusted|autonomous (default trusted) |
| `configuration` | object | No | Spawn configuration (scope/posture/plan_increments/...) |

### `campaign_list_proposals`

List the CAMPAIGN PROPOSAL QUEUE (the discovery/delegation control plane) for this account — the proposed/queued/approved/rejected/spawned campaign proposals awaiting review. Use THIS to answer 'what campaigns are proposed / in the discovery queue'.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter: proposed|queued|approved|rejected|spawned |
| `limit` | integer | No | Max rows (default 50) |

### `campaign_update_proposal`

Revise a proposed/queued CampaignProposal's fields before it's approved — the operator-directed review-round counterpart to campaign_propose (which is for creating/rediscovery-refreshing). Errors if the proposal is already approved, rejected, or spawned. Recomputes the dedupe fingerprint when scope/objective/suggested_workload change. Only the fields you pass are updated.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_id` | string | Yes | CampaignProposal UUID |
| `title` | string | No | New proposal title |
| `objective` | string | No | New objective |
| `source` | string | No | discovery|trajectory|improvement|manual |
| `scope` | string | No | New target/repo scope label |
| `suggested_workload` | string | No | improvement-campaign|feature-development|new-project |
| `suggested_driver` | string | No | claude_code|platform_agent|platform_team|platform_mission |
| `decision_authority` | string | No | supervised|monitored|trusted|autonomous |
| `configuration` | object | No | Replaces the proposal's spawn configuration |

### `campaign_approve_proposal`

Approve a queued/proposed proposal AND spawn its Ai::Campaign (and dev-loop) in one step — the concierge's 'create this campaign' action. Idempotent. Returns the proposal + the spawned campaign + its loop.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_id` | string | Yes | CampaignProposal UUID |

### `campaign_reject_proposal`

Reject a proposed/queued CampaignProposal — the operator decided not to pursue it. Terminal: a rejected proposal is never resurrected by a later campaign_propose rediscovery at the same fingerprint. Errors if already approved/rejected/spawned (use campaign_stop to stop an already-spawned campaign instead).

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_id` | string | Yes | CampaignProposal UUID |
| `reason` | string | No | Why this proposal was rejected |

### `campaign_delegate`

Route a campaign's dev-loop to a driver — claude_code (a Claude Code session drains the pull queue) or platform_agent|platform_team|platform_mission (the platform executor drains it). Reassignment releases the current single-driver lease so the new driver can claim it; for claude_code, pass holder to take the lease immediately.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `driver_kind` | string | Yes | claude_code|external_cli|platform_agent|platform_team|platform_mission |
| `target` | object | No | Platform target ref: { agent_id|group_id|mission_id } |
| `holder` | string | No | Driver identity (claude_code: take the lease now) |

### `campaign_start`

Start an Autonomous Improvement Campaign: creates the campaign + a dedicated campaign-scoped Ralph loop that /dev-loop drains. Returns the campaign + loop.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Campaign name |
| `description` | string | No | Optional campaign description |
| `configuration` | object | No | scope/posture/ordering/keep-going |
| `decision_authority` | string | No | supervised|monitored|trusted|autonomous |
| `stop_conditions` | object | No | e.g. { max_failed:, completion_pct: } |

### `campaign_list`

List this account's Autonomous Improvement CAMPAIGNS (spawned/active/completed), newest first. Use to answer 'what campaigns are running / exist'.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter: created|active|paused|completed|archived |
| `limit` | integer | No | Max rows (default 50) |

### `campaign_status`

Live status: refreshes the ledger and returns the campaign summary, open parked questions, recent decisions, and its loops.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |

### `campaign_claim`

Become the single active driver for a campaign before driving it. Returns ok:true with the lease when acquired/renewed, or ok:false with held_by when another driver holds it (back off instead of double-driving the campaign/<id> branch).

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `holder` | string | No | Driver identity (defaults to your user id) |

### `campaign_release`

Release a campaign's single-driver lease when done driving it.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `holder` | string | No | Driver identity (defaults to your user id) |

### `campaign_answer_question`

Answer a parked question (can unblock its associated task).

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `question_id` | string | Yes | Parked question UUID |
| `answer` | string | Yes | The operator's answer to the parked question |

### `campaign_record_increment`

Record one completed campaign increment: marks a passed RalphTask on the campaign loop, logs a decision, and snapshots progress (so completion% reflects real work). Idempotent on task_key.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `title` | string | Yes | Short increment title |
| `summary` | string | No | What was done |
| `task_key` | string | No | Stable key for idempotency |
| `decision_type` | string | No | build|unblock|skip|remove|defer|policy|escalate (default build) |
| `rationale` | string | No | Why this increment was done / decided |
| `status` | string | No | passed (default) | failed | skipped |

### `campaign_check_rebase`

Advise the drivers of any open campaign whose branch is behind the target branch (default develop) that a rebase is needed — notifies them + flags likely conflicts. Run after a manual land or on a schedule (auto-lands trigger it automatically). Deduped per target tip.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target_branch` | string | No | Target branch (default develop) |
| `exclude_campaign_id` | string | No | Campaign UUID to skip (e.g. the one just landed) |

### `campaign_stop`

Stop a campaign: pauses its loops (executors stop pulling) and marks it completed.

- **Tool class**: `Ai::Tools::CampaignTool`
- **Permission**: ai.campaigns.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | string | Yes | Campaign UUID or name |
| `summary` | string | No | Completion summary |

---

## Conversations & Workspaces

### `send_message`

Send a message to any conversation (workspace or agent). The conversation's agent will auto-respond (async for regular agents, sync for concierge). Include @mentions to notify specific agents in workspaces.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID (workspace or agent) |
| `message` | string | Yes | Message content (include @AgentName to mention) |
| `mentions` | array | No | Structured agent mentions [{"id": "...", "name": "..."}] |

### `send_concierge_message`

Send a message to the Powernode concierge and get an AI response. Creates or reuses an active concierge conversation.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | string | Yes | Message to send to the concierge |

### `confirm_concierge_action`

Confirm a pending concierge action (create_mission, delegate_to_team, code_review, deploy).

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID containing the pending action |
| `action_type` | string | Yes | Action type: create_mission, delegate_to_team, code_review, deploy |
| `action_params` | object | No | Optional parameters (overrides original params) |

### `list_messages`

Retrieve messages from any conversation (workspace or agent)

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID |
| `limit` | integer | No | Max messages (default 20, max 100) |

### `get_conversation_messages`

Retrieve message history for a conversation including role, content, metadata, and timestamps

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID to retrieve messages from |
| `limit` | integer | No | Max messages to return (default 20, max 100) |

### `list_conversations`

List all conversations — workspaces, agent conversations, and concierge chats

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: active, paused, completed, archived (default: all) |
| `limit` | integer | No | Max results (default 10, max 50) |

### `list_workspaces`

List workspace conversations (alias for list_conversations filtered to workspaces)

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: active, paused, completed, archived (default: all) |
| `limit` | integer | No | Max results (default 10, max 50) |

### `create_workspace`

Create a workspace conversation with selected agents for multi-agent collaboration.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Workspace name |
| `agent_ids` | array | No | Agent IDs to include |
| `include_concierge` | boolean | No | Auto-add concierge (default: false) |

### `invite_agent`

Invite an agent to a workspace conversation

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Workspace conversation ID |
| `agent_id` | string | Yes | Agent ID (or 'concierge') |

### `active_sessions`

List active MCP client sessions that can be invited to workspaces

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create
- **Parameters**: none

### `pin_conversation`

Pin a conversation to the top of the sidebar list. Sets pinned_at to now.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |

### `unpin_conversation`

Unpin a conversation (clears pinned_at).

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |

### `tag_conversation`

Set, add, or remove tags on a conversation. Pass `tags:` to replace, `add_tag:` to append, or `remove_tag:` to remove.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |
| `tags` | array | No | Replace the conversation's tag list with this array |
| `add_tag` | string | No | Append a single tag (idempotent — won't dup) |
| `remove_tag` | string | No | Remove a single tag |

---