stacklok
diff --git a/‎docs/arch/00-overview.md‎
Lines changed: 2 additions & 2 deletions b/‎docs/arch/00-overview.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎docs/arch/01-deployment-modes.md‎
Lines changed: 19 additions & 19 deletions b/‎docs/arch/01-deployment-modes.md‎
Lines changed: 19 additions & 19 deletions
diff --git a/‎docs/arch/02-core-concepts.md‎
Lines changed: 28 additions & 14 deletions b/‎docs/arch/02-core-concepts.md‎
Lines changed: 28 additions & 14 deletions
diff --git a/‎docs/arch/03-transport-architecture.md‎
Lines changed: 8 additions & 10 deletions b/‎docs/arch/03-transport-architecture.md‎
Lines changed: 8 additions & 10 deletions
diff --git a/‎docs/arch/04-secrets-management.md‎
Lines changed: 6 additions & 4 deletions b/‎docs/arch/04-secrets-management.md‎
Lines changed: 6 additions & 4 deletions
@@ -87,7 +87,7 @@ thv run go://package-name
 
 Manages MCP servers in Kubernetes clusters using custom resources.
 
-The operator watches for `MCPServer`, `MCPRegistry`, `MCPToolConfig`, `MCPExternalAuthConfig`, `MCPGroup`, and `VirtualMCPServer` CRDs, reconciling them into Kubernetes resources (Deployments, StatefulSets, Services).
+The operator watches a layered set of CRDs (Core: `MCPServer`, `MCPRemoteProxy`, `MCPServerEntry`; Organization: `MCPGroup`; Aggregation: `VirtualMCPServer`, `VirtualMCPCompositeToolDefinition`; Discovery: `MCPRegistry`; Configuration: `MCPToolConfig`, `MCPExternalAuthConfig`, `MCPOIDCConfig`, `MCPTelemetryConfig`, `MCPWebhookConfig`; Auxiliary: `EmbeddingServer`) and reconciles them into Kubernetes resources (proxy-runner Deployments and Services; ConfigMaps; the MCP server itself is created as a StatefulSet by the proxy-runner, while `EmbeddingServer`'s StatefulSet is created by the operator directly). See [Operator Architecture](09-operator-architecture.md) for the full taxonomy.
 
 **For details**, see:
 - [`cmd/thv-operator/README.md`](../../cmd/thv-operator/README.md) - Operator overview and usage
@@ -173,7 +173,7 @@ Via [ToolHive Studio](https://github.com/stacklok/toolhive-studio):
 
 Everything is driven by `thv-operator`:
 - Listens for Kubernetes custom resources
-- Creates Kubernetes-native resources (Deployments, StatefulSets, Services)
+- Creates Kubernetes-native resources (Deployments, Services, ConfigMaps for the proxy-runner; StatefulSets are created by the proxy-runner for MCP server pods)
 - Uses `thv-proxyrunner` binary (not `thv`)
 - Provides cluster-scale management
 
 
@@ -15,7 +15,7 @@ graph LR
         Operator[Operator Mode<br/>thv-operator]
     end
 
-    CLI --> Docker[Docker/Podman<br/>Colima<br/>Rancher Desktop]
+    CLI --> Docker[Docker/Podman<br/>Colima<br/>Rancher Desktop<br/>OrbStack]
     UI --> Docker
     Operator --> K8s[Kubernetes]
 
@@ -31,7 +31,7 @@ graph LR
 | Feature | Local CLI | Local UI | Kubernetes |
 |---------|-----------|----------|------------|
 | **Binary** | `thv` | `thv` (API server) | `thv-operator` + `thv-proxyrunner` |
-| **Container Runtime** | Docker/Podman/Colima/Rancher | Docker/Podman/Colima/Rancher | Kubernetes |
+| **Container Runtime** | Docker/Podman/Colima/Rancher/OrbStack | Docker/Podman/Colima/Rancher/OrbStack | Kubernetes |
 | **Process Management** | Detached processes | API-managed | Operator-managed |
 | **State Storage** | Local filesystem | Local filesystem | etcd (K8s API) |
 | **Scaling** | Single machine | Single machine | Cluster-wide |
@@ -45,7 +45,7 @@ graph LR
 graph TB
     User[User] -->|CLI Commands| THV[thv binary]
     THV -->|spawn detached| Proxy[Proxy Process]
-    Proxy -->|Docker API| Runtime[Container Runtime<br/>Docker/Podman/Colima]
+    Proxy -->|Docker API| Runtime[Container Runtime<br/>Docker/Podman/Colima<br/>Rancher Desktop/OrbStack]
     Runtime -->|creates| Container[MCP Server Container]
     Proxy -->|stdin/stdout or HTTP| Container
     Client[MCP Client] -->|HTTP/SSE/Streamable| Proxy
@@ -65,7 +65,7 @@ graph TB
    - Instantiates workloads API (`pkg/workloads/manager.go`)
 
 3. **Workload Manager**:
-   - Detects available container runtime (Podman → Colima → Docker)
+   - Detects available container runtime (Podman → Docker → Colima)
    - Creates container via Runtime API
    - Spawns detached proxy process
 
@@ -76,13 +76,14 @@ graph TB
    - Exposes local HTTP endpoint for MCP clients
 
 5. **State Management**:
-   - RunConfig saved to `~/.toolhive/state/` (or XDG equivalent)
-   - PID file for process management
-   - Status file for workload state tracking
+   - RunConfig saved under `$XDG_STATE_HOME/toolhive/runconfigs/`
+   - PID file in `$XDG_DATA_HOME/toolhive/pids/` for process management
+   - Status file in `$XDG_DATA_HOME/toolhive/statuses/` for workload state tracking
+   - See the platform path table below for full XDG layout
 
 ### Container Runtime Selection
 
-**Implementation**: `pkg/container/factory.go`
+**Implementation**: `pkg/container/docker/sdk/factory.go` (with per-runtime socket discovery in `pkg/container/docker/sdk/client_unix.go`)
 
 The CLI automatically detects container runtimes in this order:
 
@@ -93,18 +94,18 @@ The CLI automatically detects container runtimes in this order:
    - `~/.local/share/containers/podman/machine/podman.sock` (Podman Machine on macOS)
    - `$TMPDIR/podman/*-api.sock` (Podman Machine API on macOS)
 
-2. **Colima** - Checks for Colima socket at:
-   - `$TOOLHIVE_COLIMA_SOCKET` (if set)
-   - `~/.colima/default/docker.sock`
-
-3. **Docker** (including Docker Desktop, Rancher Desktop, and OrbStack) - Checks for Docker socket at:
+2. **Docker** (including Docker Desktop, Rancher Desktop, and OrbStack) - Checks for Docker socket at:
    - `$TOOLHIVE_DOCKER_SOCKET` (if set)
    - `/var/run/docker.sock`
    - `~/.docker/run/docker.sock` (Docker Desktop on macOS)
    - `~/.docker/desktop/docker.sock` (Docker Desktop on Linux)
    - `~/.rd/docker.sock` (Rancher Desktop on macOS)
    - `~/.orbstack/run/docker.sock` (OrbStack on macOS)
 
+3. **Colima** - Checks for Colima socket at:
+   - `$TOOLHIVE_COLIMA_SOCKET` (if set)
+   - `~/.colima/default/docker.sock`
+
 ### Detached Process Model
 
 When running in detached mode (`thv run` without `--foreground`):
@@ -129,9 +130,8 @@ sequenceDiagram
 
 **Key Implementation**:
 - `pkg/workloads/manager.go` - `RunWorkloadDetached` method
-- Uses `exec.Command` with `SysProcAttr` to detach
-- Sets `TOOLHIVE_DETACHED=true` environment variable
-- Redirects stdout/stderr to log file: `~/.toolhive/logs/<workload>.log`
+- Uses `exec.Command` with `SysProcAttr` (`Setsid` on Unix, equivalent flag on Windows) to detach from the parent session
+- Redirects stdout/stderr to log file under `$XDG_DATA_HOME/toolhive/logs/<workload>.log`
 
 ### File Locations
 
@@ -186,7 +186,7 @@ graph TB
 
 5. **Runtime Selection**:
    - Picks runtime driver based on environment
-   - Docker, Podman, or Rancher Desktop
+   - Docker, Podman, Colima, OrbStack, or Rancher Desktop (same set as CLI mode)
    - Uses driver API to spawn containers
 
 ### API Endpoints
@@ -231,7 +231,7 @@ Available flags:
 |------|-------------|-------------|
 | `--sentry-dsn` | `SENTRY_DSN` | Sentry Data Source Name (required to enable) |
 | `--sentry-environment` | `SENTRY_ENVIRONMENT` | Environment name (e.g. `production`, `development`) |
-| `--sentry-traces-sample-rate` | `SENTRY_TRACES_SAMPLE_RATE` | Trace sampling rate, 0.0–1.0 (default: `1.0`) |
+| `--sentry-traces-sample-rate` | — | Trace sampling rate, 0.0–1.0 (default: `1.0`) |
 
 When no DSN is configured, all Sentry operations are no-ops with zero overhead.
 
@@ -281,7 +281,7 @@ graph TB
 
 3. **Operator creates Deployment**:
    - Runs `thv-proxyrunner` container
-   - Mounts RunConfig as ConfigMap or secret
+   - Mounts RunConfig as ConfigMap
    - Applies middleware configuration
 
 4. **Proxy runner creates StatefulSet**:
 
@@ -38,6 +38,8 @@ A **workload** is the fundamental deployment unit in ToolHive. It represents eve
 - `error` - Workload encountered an error
 - `unhealthy` - Workload is running but unhealthy
 - `unauthenticated` - Remote workload cannot authenticate (expired tokens)
+- `unknown` - Workload status cannot be determined
+- `policy_stopped` - Workload was stopped by policy enforcement
 
 **Implementation:**
 - Interface: `pkg/workloads/manager.go`
@@ -50,7 +52,7 @@ A **workload** is the fundamental deployment unit in ToolHive. It represents eve
 
 A **transport** defines how MCP clients communicate with MCP servers. It encapsulates the protocol and proxy implementation.
 
-**Three types:**
+**Transport types:**
 
 1. **stdio**: Standard input/output communication
    - Container speaks stdin/stdout
@@ -67,6 +69,10 @@ A **transport** defines how MCP clients communicate with MCP servers. It encapsu
    - Transparent HTTP proxy (same as SSE)
    - Session management via headers
 
+4. **inspector**: Debug-only transport
+   - Special transport used for the MCP Inspector tooling
+   - Not intended for production workloads
+
 **Implementation:**
 - Interface: `pkg/transport/types/transport.go`
 - Types: `pkg/transport/types/transport.go`
@@ -112,18 +118,24 @@ A **proxy** is the component that sits between MCP clients and MCP servers, forw
 
 - **Authentication** (`auth`) - JWT token validation
 - **Token Exchange** (`tokenexchange`) - OAuth token exchange
+- **Upstream Swap** (`upstreamswap`) - Swap ToolHive JWTs for upstream IdP tokens (embedded auth server)
+- **AWS STS** (`awssts`) - Exchange tokens for AWS STS credentials
+- **OBO** (`obo`) - On-Behalf-Of token flow
 - **MCP Parser** (`mcp-parser`) - JSON-RPC parsing
 - **Tool Filter** (`tool-filter`) - Filter and override tools in `tools/list` responses
 - **Tool Call Filter** (`tool-call-filter`) - Validate and map `tools/call` requests
+- **Rate Limit** (`ratelimit`) - Per-client request rate limiting
 - **Usage Metrics** (`usagemetrics`) - Anonymous usage metrics for ToolHive development (opt-out: `thv config usage-metrics disable`)
 - **Telemetry** (`telemetry`) - OpenTelemetry instrumentation
 - **Authorization** (`authorization`) - Cedar policy evaluation
 - **Audit** (`audit`) - Request logging
+- **Recovery** (`recovery`) - Panic recovery for the proxy chain
+- **Header Forward** (`header-forward`) - Forward selected request headers to upstream
+- **Validating Webhook** (`validating-webhook`) - Call external validating webhooks
+- **Mutating Webhook** (`mutating-webhook`) - Call external mutating webhooks
 
 **Execution order (request flow):**
-Middleware applied in reverse configuration order. Requests flow through: Audit* → Authorization* → Telemetry* → Usage Metrics* → Parser → Token Exchange* → Auth → Tool Call Filter* → Tool Filter* → MCP Server
-
-(*optional middleware, only present if configured)
+Middleware is applied in reverse configuration order, and the chain composed for a given workload depends on which features are enabled. See [`docs/middleware.md`](../middleware.md) for the complete chain, ordering rules, and per-middleware semantics.
 
 **Implementation:**
 - Interface: `pkg/transport/types/transport.go`
@@ -187,9 +199,7 @@ A **permission profile** defines security boundaries for MCP servers:
 - `network` - Full network access
 
 **Implementation:**
-- Definition: `pkg/permissions/profile.go`
-- Network: `pkg/permissions/profile.go`
-- Mount declarations: `pkg/permissions/profile.go`
+- Definition, network permissions, and mount declarations: `github.com/stacklok/toolhive-core/permissions` (imported as `permissions` in `pkg/runner/`)
 
 **Related concepts:** RunConfig, Workload, Security
 
@@ -323,7 +333,7 @@ A **registry** is a catalog of MCP server definitions with metadata, configurati
 - `groups` - Predefined groups of servers
 
 **Implementation:**
-- Registry types: `pkg/registry/types.go`
+- Registry types: `github.com/stacklok/toolhive-core/registry/types`
 - Provider abstraction: `pkg/registry/provider.go`, `pkg/registry/factory.go`
 - Local provider: `pkg/registry/provider_local.go`
 - Remote provider: `pkg/registry/provider_remote.go`
@@ -389,11 +399,15 @@ A **runtime** is an abstraction over container orchestration systems. It provide
 - `IsWorkloadRunning` - Check if running
 
 **Runtime detection:**
-Order: Podman → Colima → Docker → Kubernetes (via env)
+Runtimes are registered with a numeric `Priority` (lower wins) in the runtime registry (`pkg/container/runtime/registry.go`). Today the registered runtimes are:
+
+- **Docker runtime** (`Priority: 100`, registered in `pkg/container/docker/register.go`) — covers Docker, Podman, Colima, Rancher Desktop, and OrbStack via per-runtime socket discovery (Podman → Docker → Colima).
+- **Kubernetes runtime** (`Priority: 200`, registered in `pkg/container/kubernetes/register.go`) — activated when running in-cluster (via `KUBERNETES_SERVICE_HOST`) or when `TOOLHIVE_RUNTIME=kubernetes` is set.
 
 **Implementation:**
 - Interface: `pkg/container/runtime/types.go`
-- Factory: `pkg/container/factory.go`
+- Registry: `pkg/container/runtime/registry.go`
+- Docker SDK factory and socket discovery: `pkg/container/docker/sdk/factory.go`, `pkg/container/docker/sdk/client_unix.go`
 - Detection: `pkg/container/runtime/types.go`
 
 **Related concepts:** Deployer, Workload, Container
@@ -449,7 +463,7 @@ A **skill** is an Agent Skill -- a markdown-based instruction set (SKILL.md) tha
 5. **Uninstall** - Remove files and metadata
 
 **Implementation:**
-- Service: `pkg/skills/skillsvc/skillsvc.go`
+- Service interface: `pkg/skills/service.go`; implementation in `pkg/skills/skillsvc/` (entry point `pkg/skills/skillsvc/service.go`)
 - Types: `pkg/skills/types.go`
 - Storage: `pkg/storage/sqlite/skill_store.go`
 - CLI: `cmd/thv/app/skill*.go`
@@ -480,7 +494,7 @@ A **skill** is an Agent Skill -- a markdown-based instruction set (SKILL.md) tha
 2. Start proxy
 3. Configure authentication (if needed)
 4. Apply middleware
-4. Update state
+5. Update state
 
 **Commands:**
 - `thv run <image|url>` - Deploy and start
@@ -717,7 +731,7 @@ See `pkg/audit/mcp_events.go` for complete list of event types.
 - Shutdown if unhealthy
 
 **Implementation:**
-- Monitor: `pkg/container/docker/monitor.go`
+- Monitor: `pkg/container/runtime/monitor.go`
 - Health checker: `pkg/healthcheck/healthcheck.go`
 
 **Related concepts:** Workload, Transport, Proxy
@@ -759,7 +773,7 @@ graph LR
     style Chain fill:#fff9c4
 ```
 
-Requests pass through up to 9 middleware components (Auth, Token Exchange, Tool Filter, Tool Call Filter, Parser, Usage Metrics, Telemetry, Authorization, Audit). See `docs/middleware.md` for complete middleware architecture and execution order.
+Requests pass through a configurable chain of middleware components. See [`docs/middleware.md`](../middleware.md) for the complete chain and execution order.
 
 ### Data Hierarchy
 
 
@@ -226,9 +226,9 @@ graph LR
 ```
 
 **Implementation:**
-- `pkg/transport/types/transport.go` - MiddlewareFunction type
+- `pkg/transport/types/transport.go` - `MiddlewareFunction` and `NamedMiddleware` types
 - Middleware applied in reverse order (last registered = outermost)
-- Each transport type accepts `[]MiddlewareFunction` in constructor
+- Each transport type accepts `[]NamedMiddleware` in constructor (each wraps a `MiddlewareFunction` with its name for logging)
 
 ## Remote MCP Server Proxying
 
@@ -446,25 +446,23 @@ ToolHive uses two port concepts:
 
 ### MCP Environment Variables
 
-**Implementation**: `pkg/transport/http.go`
+**Implementation**: `pkg/environment/environment.go` sets `MCP_TRANSPORT`, `MCP_PORT`, and `FASTMCP_PORT` for the CLI/local path. `pkg/runtime/setup.go` sets all four variables (`MCP_TRANSPORT`, `MCP_PORT`, `FASTMCP_PORT`, and `MCP_HOST`) when deploying workloads through the runtime (used by both local and Kubernetes/proxy-runner paths). The `TargetHost` default of `127.0.0.1` (`transport.LocalhostIPv4`) is established by `WithTargetHost` in `pkg/runner/config_builder.go` (around line 204), not by the env-emitting code — both code paths simply read `RunConfig.TargetHost`.
 
 Environment variables set automatically for container configuration:
 
 - `MCP_TRANSPORT`: Transport type (stdio, sse, streamable-http)
 - `MCP_PORT`: Target port (for SSE/Streamable HTTP)
-- `MCP_HOST`: Target host - always `127.0.0.1` (both local and Kubernetes)
+- `MCP_HOST`: Target host - defaults to `127.0.0.1` (`transport.LocalhostIPv4`), with the default applied by `WithTargetHost` in `pkg/runner/config_builder.go` when `RunConfig.TargetHost` is empty
 - `FASTMCP_PORT`: Alias for `MCP_PORT` (legacy support)
 
 **Architecture distinction:**
-- **Target host** (`MCP_HOST` env var): Where container listens - always `127.0.0.1`
-- **Proxy host**: Where proxy binds - `127.0.0.1` in local mode, `0.0.0.0` in Kubernetes for cluster access
+- **Target host** (`MCP_HOST` env var): Where the container's MCP server listens - defaults to `127.0.0.1`
+- **Proxy host**: Where the proxy binds - `127.0.0.1` in local mode, `0.0.0.0` in Kubernetes for cluster access
 
 **Merge strategy**:
 - User-provided values take precedence
 - ToolHive sets deployment-appropriate defaults
 
-**Reference**: PR #1890 - Runtime Authoring Guide
-
 ## Container Attach (Stdio Transport)
 
 For stdio transport, ToolHive attaches to container stdin/stdout:
@@ -484,7 +482,7 @@ stdin, stdout, err := t.deployer.AttachToWorkload(ctx, t.containerName)
 5. **Framing** - Newline-delimited JSON-RPC messages
 
 **Monitoring:**
-- Container monitor detects exit: `pkg/container/docker/monitor.go`
+- Container monitor detects exit: `pkg/container/runtime/monitor.go`
 - Proxy automatically stopped on container exit
 - Workload status updated
 
@@ -625,7 +623,7 @@ spec:
   trustProxyHeaders: true
 ```
 
-**Implementation**: `pkg/transport/proxy/transparent/transparent_proxy.go` - `rewriteEndpointURL()`, `getSSERewriteConfig()`
+**Implementation**: `pkg/transport/proxy/transparent/sse_response_processor.go` - `rewriteEndpointURL()`, `getSSERewriteConfig()`
 
 ## Transport Factory
 
 
@@ -26,7 +26,9 @@ graph LR
 
 ## Provider Types
 
-**Implementation**: `pkg/secrets/types.go`
+**Implementation**:
+- `pkg/secrets/factory.go` (`ProviderType` enum: `EncryptedType`, `OnePasswordType`, `EnvironmentType`)
+- `pkg/secrets/types.go` defines the `Provider` interface (the contract every provider implements) and the `EnvVarPrefix` constant (`"TOOLHIVE_SECRET_"`) used by the environment provider
 
 ### 1. Encrypted
 
@@ -68,7 +70,7 @@ MCPServer resources reference Kubernetes Secrets via `SecretRef`. Secrets are in
 
 **Implementation**:
 - CRD types: `cmd/thv-operator/api/v1beta1/mcpserver_types.go`
-- Pod builder: `cmd/thv-operator/controllers/mcpserver_podtemplatespec_builder.go`
+- Pod builder: `cmd/thv-operator/pkg/controllerutil/podtemplatespec_builder.go`
 
 ### External Authentication Secrets
 
@@ -79,7 +81,7 @@ OAuth/OIDC client secrets are stored in Kubernetes Secrets and referenced using
    - **Secret injection**: `cmd/thv-operator/pkg/controllerutil/tokenexchange.go`
 
 2. **OIDC Authentication (MCPOIDCConfig)**: OIDC client secrets for token introspection
-   - **CRD field**: `InlineOIDCSharedConfig.ClientSecretRef` in `cmd/thv-operator/api/v1beta1/mcpoidcconfig_types.go`
+   - **CRD field**: `spec.inline.clientSecretRef` on the `MCPOIDCConfig` resource (Go: `MCPOIDCConfig.Spec.Inline.ClientSecretRef`, where `Inline` is of type `*InlineOIDCSharedConfig`), defined in `cmd/thv-operator/api/v1beta1/mcpoidcconfig_types.go`
    - **Secret injection**: `cmd/thv-operator/pkg/controllerutil/oidc.go`
    - **Runtime loading**: `pkg/auth/token.go` (via `TOOLHIVE_OIDC_CLIENT_SECRET` environment variable)
 
@@ -134,7 +136,7 @@ thv run my-server --secret "api-key,target=API_KEY"
 - Log exposure: ✅
 - Malicious container: ❌ (has env access)
 
-**Implementation**: `pkg/secrets/aes/aes.go`, `pkg/secrets/keyring/`
+**Implementation**: `pkg/secrets/aes/aes.go` (AES-256-GCM), `pkg/secrets/keyring/` (OS keyring storage), `pkg/secrets/factory.go` (SHA-256 key derivation via `sha256.Sum256(secretsPassword)`)
 
 ## Integration Points