docs: document catalog and workflow capabilities

architecture.mdx

@@ -46,7 +46,7 @@ flowchart LR
 6. The execution engine fetches run context from the control plane, streams model requests through the LLM gateway, and calls allowed tools.
 7. The control plane records run events and streams them back to the management console.
 
-Remote MCP servers use the same run-scoped tool permission model. The gateway discovers remote tools from `tools/list`, stores discovered tools disabled by default, and forwards calls with platform scope headers plus any configured non-secret public headers.
+Remote MCP servers use the same run-scoped tool permission model. Each installation belongs to one Agent. The gateway discovers remote tools from `tools/list`, stores them pending explicit review, and invokes only an exact `{serverId, toolName}` reference allowed by the pinned Agent version.
 
 ## Auth and trust boundaries
 
@@ -68,7 +68,7 @@ Remote MCP credentials are secret-backed. Non-secret `publicHeaders` may be forw
 
 ## Workspace and role model
 
-A workspace contains members, audit events, targets, Kubernetes clusters, VMs, MCP server settings, tool settings, sessions, runs, and webhooks. Server responses include role-derived permissions so clients can show available actions without reimplementing authorization rules.
+A workspace contains members, audit events, targets, Kubernetes clusters, VMs, MCP registries, Agents with independently installed capabilities, sessions, runs, and webhooks. Server responses include role-derived permissions so clients can show available actions without reimplementing authorization rules.
 
 The deployment defines the supported workspace role templates. `owner` is always present, protected, and required. Deployments can disable non-owner built-ins (`admin`, `operator`, `viewer`, `auditor`) and define custom lowercase snake_case roles with supported workspace capabilities. Workspaces assign members and invitations from this deployment catalog; they cannot edit capability sets or role availability.
 

catalog-registries.mdx

@@ -0,0 +1,126 @@
+---
+title: "MCP registries"
+description: "Discover MCP servers from configured private, public, or air-gapped registries"
+---
+
+AcornOps provides installation UX over registries that you configure; it does not operate its own catalog. No public registry is enabled by default. Self-hosted operators can bootstrap internal registries, and workspace admins can add registries when deployment policy permits.
+
+Registries let administrators discover MCP servers without coupling a run to a live registry. AcornOps resolves and imports a pinned artifact onto one Agent or target installation. Runs use that stored snapshot even if the registry is later unavailable.
+
+AcornOps supports the official MCP Registry v0.1 wire format at `/v0.1`. A private registry can expose the same format. Other formats require a compiled, allow-listed adapter; AcornOps does not execute uploaded adapter code or arbitrary JSON mappings.
+
+## Discovery and installation
+
+MCP registries and MCP installations have separate lifecycles:
+
+1. An administrator adds or bootstraps a catalog source.
+2. AcornOps synchronizes normalized artifacts, versions, digests, and compatible remote endpoints.
+3. An administrator chooses an Agent or target destination and imports a pinned version onto that installation.
+4. AcornOps discovers tools and leaves them disabled for review.
+5. An administrator reviews each exact server/tool pair.
+
+Package-only and stdio-only registry entries remain visible as incompatible. AcornOps v1 imports only remote Streamable HTTP endpoints.
+
+| Destination | Entry point | Stored scope | Available to |
+| --- | --- | --- | --- |
+| One Agent | **Agents → Agent detail → Capabilities → MCP servers → Add MCP server → Browse registries** | Exact workspace and Agent ID, with optional authoritative target type/ID constraints | Runs pinned to that Agent version |
+| One target | **Target → MCP servers → Add MCP server → Browse registries** | Exact workspace and target ID | Runs through that target's default Agent |
+
+Installing the same artifact on another Agent creates an independent installation. Each installation has its own server ID, endpoint configuration, enabled state, reviewed tools, provenance, pinned digest, connections, version history, and lifecycle. An installation never leaks to another Agent or target.
+
+Browsing keeps the destination fixed and provides a canonical **Back to destination** link. Existing `/workspaces/:workspaceId/catalog` links remain valid, but destination-less visits require selecting an Agent or target before installation.
+
+The same **Add MCP server** menu also provides **Connect by URL**. This accepts only the actual remote MCP Streamable HTTP endpoint, such as `https://mcp.internal.example/mcp`. It does not accept a registry URL, `server.json`, a GitHub repository, a package, a container, or a stdio command.
+
+Workspace settings contain **MCP registries** administration. Authorized admins can also open it from **Manage registries** while browsing. Target installations and Agent installations remain independent even when they point to the same upstream URL.
+
+## Managing registries
+
+Admins with `manage_catalog_sources` can add, probe, edit, enable or disable, synchronize, and delete workspace-managed registries when deployment policy permits. Deployment-managed registries are configuration-read-only in the console, but authorized admins may synchronize them.
+
+Enter an HTTPS registry root or path prefix, such as `https://registry.internal.example` or `https://platform.internal.example/mcp-registry`. Do not include `/v0.1`, query parameters, fragments, or credentials; AcornOps appends `/v0.1`. Credentials belong in the authentication fields. Only direct routing is currently available.
+
+Disabling a registry immediately removes its artifacts from browsing but retains the cached snapshot for later re-enablement. Deleting a workspace registry removes its cache and registry credential. Neither operation uninstalls existing servers: installations retain pinned provenance and keep running, but cannot update until their source returns.
+
+When no registry is configured, the browser offers **Connect by URL** and, for authorized admins, **Add a registry**. Other users are told to contact a workspace administrator.
+
+## Agent and workflow permissions
+
+Every workflow step selects exactly one Agent. The workflow can retain a subset of that Agent's MCP, skill, and tool grants or remove them; it cannot add a capability the Agent does not already grant. Target-owned installations remain available only through that target's default Agent and do not become workflow-owned credentials.
+
+An empty workflow restriction grants no capability. It does not inherit all Agent permissions.
+
+Runtime tool identity includes both the stable server ID and tool name. This keeps tools with the same name on different servers independently selectable and prevents name-only authorization.
+
+## Credential ownership
+
+Authenticated MCP installations explicitly select `workspace` or `individual`
+credential ownership. Importing or enabling a server does not authorize it by
+itself.
+
+Workspace-managed credentials are installation-owned and can be used by user or
+service principals. Individual credentials are scoped to one user and one
+installation and require a user principal. Select the matching **Connect
+credential** action, enter the write-only credential, and grant storage consent.
+AcornOps stores it encrypted in the LLM gateway and immediately performs
+authenticated tool discovery. Responses never return the secret or its name.
+
+A target and an Agent always have separate connections, even for the same
+upstream server. AcornOps never deduplicates connections by URL or copies
+credentials between installations. Failed verification retains an encrypted
+error-state credential so an authorized owner can verify, replace, or disconnect
+it. An upstream `401` or `403` marks that exact connection erroneous.
+
+## Kubernetes configuration
+
+Configure registry policy under `components.llmGateway.catalog`:
+
+```yaml
+components:
+  llmGateway:
+    catalog:
+      officialRegistryEnabled: false
+      # Set this only when deployment policy explicitly permits the public registry.
+      officialRegistryUrl: https://registry.modelcontextprotocol.io
+      allowWorkspaceManagedSources: true
+      bootstrapSources:
+        - workspaceId: "*"
+          displayName: Internal MCP Registry
+          baseUrl: https://registry.internal.example
+          adapterBasePath: /v0.1
+          networkRoute: direct
+          enabled: true
+          auth:
+            type: bearer_token
+            secretKeyRef:
+              name: internal-registry-credential
+              key: token
+    mcpEgress:
+      allowedHosts: registry.internal.example,mcp.internal.example
+      allowPrivateNetworks: true
+```
+
+The chart renders a secret-free bootstrap JSON document. Each registry
+`secretKeyRef` is injected into a separate environment variable and copied into
+the configured gateway secret backend. Runtime MCP credentials are entered
+through the console and have no Helm client or callback configuration.
+
+## Air-gapped self-hosting
+
+For a fully air-gapped deployment:
+
+- set `officialRegistryEnabled: false`,
+- bootstrap an internal v0.1-compatible registry,
+- allow-list only internal registry and MCP server hostnames,
+- mount your private CA through `components.llmGateway.mcpEgress.caBundle`, and
+- keep all registry synchronization, artifact import, tool discovery, and runtime MCP traffic on the internal network.
+
+No public internet access is required when the gateway, registry, and MCP servers share the private network.
+
+Registry availability stays outside global platform readiness. Synchronization failures appear through each registry's status, bounded metrics, and structured logs.
+
+## Agent-owned skills
+
+Install manual or Git-backed skills from the same Agent **Capabilities** page. Git imports resolve to a pinned commit and content digest; upgrades require an explicit reimport. Skill installation state is independent on every Agent. The catalog layer reserves `agent_skill` as a later artifact handler, but MCP import never executes or installs skill content.
+
+See [MCP and tools](/mcp-tools) for direct endpoint rules, tool review, and runtime behavior, and [Configuration](/configuration#mcp-egress-policy) for egress controls.

configuration.mdx

@@ -211,6 +211,17 @@ Clusters can inherit the deployment default or set a per-cluster override. Requi
 
 In the management console, per-cluster write confirmation policy is managed from Cluster Settings.
 
+## Workflow runtime and report retention
+
+Workflow execution duration and PDF report retention are deployment-wide. Workflow definitions cannot override them.
+
+| Helm value | Rendered environment variable | Default | Purpose |
+| --- | --- | --- | --- |
+| `agent.runtime.maxRuntimeMs` | `AGENT_MAX_RUNTIME_MS` | `600000` | Maximum execution duration for Workflow and target-chat runs. |
+| `components.controlPlane.reportArtifacts.maxRetentionDays` | `TARGET_CHAT_REPORT_RETENTION_DAYS` | `30` | Retention period for Workflow and target-chat PDF reports. Accepts `1` through `365`. |
+
+The Workflow options API returns each effective value as a singleton policy list. Legacy mutation fields remain accepted for compatibility but cannot override deployment configuration.
+
 ## Audit logging lifecycle
 
 Workspace audit logging is deployment-wide. There is no workspace-level or user-level override.
@@ -230,7 +241,7 @@ Retention always runs for persisted rows, even when logging mode is `disabled`.
 
 ## MCP egress policy
 
-Remote MCP servers are configured per target. The management console presents MCP server settings on Kubernetes cluster and VM target pages. In production, the gateway should require HTTPS and block private, local, and reserved network targets unless you intentionally allow specific hosts.
+Remote MCP servers can be installed at workspace scope for Agent and Workflow use, or at exact target scope for one Kubernetes cluster or VM. In production, the gateway should require HTTPS and block private, local, and reserved network targets unless you intentionally allow specific hosts.
 
 Use allow-lists for trusted internal MCP endpoints instead of broad private-network access.
 
@@ -244,6 +255,8 @@ Use allow-lists for trusted internal MCP endpoints instead of broad private-netw
 
 Remote MCP server `publicHeaders` are for non-secret metadata only. Credentials belong in secret-backed auth fields, and platform scope headers are reserved.
 
+MCP registry policy uses `components.llmGateway.catalog`. The Official MCP Registry is disabled by default and must be enabled explicitly. Configure internal registries through `bootstrapSources`, use `secretKeyRef` for registry credentials, and keep bootstrap routing set to `direct`. MCP installations select workspace-managed or individual credential ownership and require no deployment-level callback configuration. See [MCP registries](/catalog-registries) for complete examples and lifecycle behavior.
+
 ## Webhooks
 
 Webhook signing secrets are generated per subscription and returned only once at creation time. The control plane stores encrypted webhook secrets and signs deliveries with HMAC-SHA256.

deployment.mdx

@@ -5,6 +5,11 @@ description: "Deploy AcornOps through Kubernetes, VM Compose, workload agents, a
 
 AcornOps deployment has two independent steps: deploy the central platform, then connect each Kubernetes cluster or Linux VM with an outbound agent.
 
+Starter automation is part of current-version control-plane workspace
+provisioning in every environment. It is independent of optional local target
+fixtures such as `SEED_DEVELOPMENT_DATA`; each new workspace receives the final
+starter bundle once, with no startup upgrade or repair pass.
+
 ## Kubernetes
 
 Use the `acornops-platform` Helm chart to deploy the central platform into a Kubernetes cluster. The chart deploys:
@@ -205,6 +210,13 @@ Before starting the stack:
 
 Database init jobs run before services start. Treat init failures as deployment blockers.
 
+### Greenfield database epoch
+
+This version is not a rolling database upgrade. Back up if needed, then drop and
+recreate the external control-plane and gateway databases before installing the
+complete pinned stack matrix. Pre-release data is not preserved, and mixed
+gateway, control-plane, or execution-engine versions are unsupported.
+
 ## Kubernetes clusters
 
 Each connected Kubernetes cluster gets the `acornops-agentk` Helm chart. Register the cluster in the management console, then run the generated install command returned by the control plane.

docs.json

@@ -64,6 +64,7 @@
               "quickstart",
               "deployment",
               "configuration",
+              "catalog-registries",
               "automation",
               "kubernetes-clusters",
               "vm-targets"
@@ -183,18 +184,21 @@
                 ]
               },
               {
-                "group": "Tools and MCP servers",
+                "group": "Agent capabilities and target tools",
                 "pages": [
-                  "GET /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/catalog",
                   "GET /api/v1/workspaces/{workspaceId}/targets/{targetId}/tools",
                   "PATCH /api/v1/workspaces/{workspaceId}/targets/{targetId}/tools/{toolId}",
-                  "GET /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers",
-                  "POST /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers",
-                  "PATCH /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers/{serverId}",
-                  "DELETE /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers/{serverId}",
-                  "POST /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers/{serverId}/test-connection",
-                  "GET /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers/{serverId}/tools",
-                  "PATCH /api/v1/workspaces/{workspaceId}/targets/{targetId}/mcp/servers/{serverId}/tools/{toolName}"
+                  "GET /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers",
+                  "POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers",
+                  "POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/import",
+                  "PATCH /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/{serverId}",
+                  "DELETE /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/{serverId}",
+                  "POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/{serverId}/test-connection",
+                  "GET /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/{serverId}/tools",
+                  "PATCH /api/v1/workspaces/{workspaceId}/agents/{agentId}/mcp/servers/{serverId}/tools/{toolName}",
+                  "GET /api/v1/workspaces/{workspaceId}/agents/{agentId}/skills",
+                  "POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/skills",
+                  "POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/skills/import"
                 ]
               },
               {

index.mdx

@@ -26,7 +26,7 @@ AcornOps is self-hosted for production use. A public demo is available at `https
 
 ## What AcornOps gives you
 
-- A workspace model for grouping targets, Kubernetes clusters, VMs, members, MCP servers, tool settings, and investigation history.
+- A workspace model for grouping targets, Kubernetes clusters, VMs, members, MCP registries, Agent-owned capabilities, and investigation history.
 - A browser management console for target inventory, findings, runbooks, members, settings, and chat-based troubleshooting.
 - A control plane that owns auth, sessions, workspaces, the target core, target registration, agent connections, run state, and API authorization.
 - An execution engine that performs troubleshooting runs and streams progress back to the control plane.