diff --git a/.mise.toml b/.mise.toml
index 738fa1d27..f6ebf6461 100644
--- a/.mise.toml
+++ b/.mise.toml
@@ -3,3 +3,4 @@ go = "1.25"
 just = "latest"
 node = "22"
 bun = "latest"
+uv = "latest"
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..ff18639ac
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Test: `just test` | Before committing: `just ready`
+
+Read @CONTRIBUTING.md first. It covers prerequisites, setup, project structure,
+code standards, testing, input validation, and how to add an API domain — all of
+which apply to agents exactly as they apply to people. This file carries only
+what is specific to agents.
+
+## Running tools
+
+Invoke tools through `mise`, not from your path:
+
+```bash
+mise exec -- just test
+```
+
+`mise` is active in a person's shell and supplies the versions `.mise.toml`
+declares. An agent's shell has no activation, so a bare `just` resolves to
+whatever is installed globally — usually an older version.
+
+The symptom is a check that fails here and passes in continuous integration, on
+a file nobody edited. When that happens, establish which version ran before
+treating the failure as real.
+
+## Never build with the Go toolchain directly
+
+`go build ./...` and `go test ./...` fail in this repository. The UI is embedded
+via `//go:embed dist/*`, which requires `ui/dist/` to hold files at compile
+time. Use `just build`, `just test`, or `just ready` — each builds the UI first.
+See @CONTRIBUTING.md under "Building and running".
+
+## Where the rules come from
+
+Repository layout, shared tooling, and the Go conventions this repository
+follows are specified in [osapi-io/specs](https://github.com/osapi-io/specs).
+When a convention here and the specification disagree, the specification wins —
+say so rather than following the code.
+
+## Commit trailer
+
+When committing via Claude Code, end the message with:
+
+```
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Task tracking
+
+Implementation planning and execution uses the superpowers plugin workflows
+(`writing-plans` and `executing-plans`). Plans are working notes and are not
+committed — the design record for a change lives in
+[osapi-io/specs](https://github.com/osapi-io/specs).
diff --git a/CLAUDE.md b/CLAUDE.md
index d463eda75..4365898c8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,928 +1,8 @@
-# CLAUDE.md
+# Claude Code
 
-This file provides guidance to Claude Code (claude.ai/code) when working with
-code in this repository.
+All agent guidance lives in @AGENTS.md — how to invoke tools, why the Go
+toolchain is never called directly, where the rules come from, the commit
+trailer, and task tracking. This file exists so Claude Code finds it; the
+content is upstream.
 
-## Project Overview
-
-OSAPI is a Linux system management REST API and CLI written in Go 1.25. It uses
-NATS JetStream for distributed async job processing with a KV-first,
-stream-notification architecture.
-
-## Development Reference
-
-For setup, building, testing, and contributing, see the Docusaurus docs:
-
-- @docs/docs/sidebar/development/development.md - Prerequisites, setup, code
-  style, testing, commit conventions
-- @docs/docs/sidebar/development/contributing.md - PR workflow and contribution
-  guidelines
-- @docs/docs/sidebar/development/testing.md - How to run tests and list just
-  recipes
-- @docs/docs/sidebar/development/ui-development.md - UI prerequisites, setup,
-  code style, components
-- @docs/docs/sidebar/architecture/principles.md - Guiding principles
-  (simplicity, minimalism, design philosophy)
-- @docs/docs/sidebar/architecture/api-guidelines.md - API design guidelines
-  (REST conventions, endpoint structure)
-- @docs/docs/sidebar/architecture/ui.md - UI architecture, embedding, component
-  layers
-- @docs/docs/sidebar/usage/configuration.md - Configuration reference
-  (osapi.yaml, env overrides)
-- @docs/docs/sidebar/architecture/architecture.md - Architecture overview (links
-  to system and job architecture)
-
-Quick reference for common commands:
-
-```bash
-just deps          # Install all dependencies
-just build         # Build production binary (React UI + Go)
-just test          # Run all tests (lint + unit + coverage)
-just go-unit      # Run unit tests only
-just go-unit-int  # Run integration tests (requires running osapi)
-just go-vet       # Run golangci-lint
-just go-fmt       # Auto-format (gofumpt + golines)
-go test -run TestName -v ./internal/job/...  # Run a single test
-
-just react-dev    # Start UI dev server (http://localhost:5173)
-just react-build  # Production UI build
-just react-lint   # Run ESLint on UI
-just react-fmt    # Format UI with Prettier
-```
-
-## Architecture (Quick Reference)
-
-- **`cmd/`** - Cobra CLI commands (`client`, `node agent`, `controller.api`,
-  `nats server`)
-- **`internal/controller/api/`** - Echo REST API. Node-targeted handlers nest
-  under `node/{domain}/`. Controller-only handlers are top-level (`job/`,
-  `health/`, etc.). Each domain has its own `gen/` with OpenAPI spec. Combined
-  spec: `api/gen/api.yaml`
-- **`internal/job/`** - Job domain types, subject routing. `client/` for
-  high-level ops
-- **`internal/agent/`** - Node agent: consumer/handler/processor pipeline for
-  job execution
-- **`internal/telemetry/tracing/`** - OpenTelemetry tracer initialization, slog
-  trace handler, context propagation\\
-- **`internal/telemetry/metrics/`** - Per-component Prometheus metrics server
-  with isolated registries\\
-- **`internal/provider/`** - Operation implementations organized by category
-  then domain. Browse the directory to see current providers
-- **`internal/telemetry/process/`** - Agent self-metrics (CPU%, RSS, goroutines)
-  and process condition evaluation for heartbeat
-- **`internal/controller/notify/`** - Pluggable condition notification system:
-  watches registry KV for condition transitions, dispatches via `Notifier`
-  interface (`log` backend)
-- **`internal/config/`** - Viper-based config from `osapi.yaml`. Struct fields
-  use `validate` tags (same validator as API handlers). Defaults are set via
-  `viper.SetDefault()` in `cmd/root.go`
-- **`pkg/sdk/`** - Go SDK for programmatic REST API access (`client/` client
-  library). See @docs/docs/sidebar/sdk/guidelines.md for SDK development rules
-- Shared `nats-client` and `nats-server` are sibling repos, consumed as pinned
-  module versions in `go.mod` (no `replace` directive)
-
-## UI Architecture (Quick Reference)
-
-- **`ui/`** - React 19 + TypeScript + Vite + Tailwind CSS v4. Embedded into the
-  Go binary at build time.
-- **`ui/src/sdk/gen/`** - Generated TypeScript SDK (orval) from the combined
-  OpenAPI spec. DO NOT EDIT.
-- **`ui/src/sdk/fetch.ts`** - Hand-written fetch mutator: auth token + base URL
-  wiring for orval.
-- **`ui/src/components/ui/`** - Reusable UI primitives. Every visual pattern is
-  a component.
-- **`ui/src/components/layout/`** - Page structure (Navbar, PageLayout,
-  ContentArea, NetworkMapBackground).
-- **`ui/src/components/domain/`** - Domain-specific components (blocks, cards,
-  pickers).
-- **`ui/src/hooks/`** - Data fetching, state, keyboard navigation hooks.
-- **`ui/src/lib/`** - `cn.ts`, `auth.tsx`, `permissions.ts`, `features.ts`.
-- **`ui/embed.go`** - `//go:embed dist/*` directive exposing `ui.Assets`.
-- **`internal/controller/api/ui/`** - SPA serving handler (static files +
-  `index.html` fallback for client-side routing).
-- Config: `controller.ui.enabled` in `osapi.yaml` (default `true`).
-- `//go:embed dist/*` requires `ui/dist/` to have files at compile time. Always
-  use `just build` / `just test` / `just ready` — these run `just react-build`
-  first. Running `go build` / `go test` directly without a prior UI build will
-  fail.
-
-## UI Conventions (MANDATORY)
-
-- One component per file. Use `cva` for variants, `cn()` for conditional
-  classes.
-- Icons from lucide-react only. No inline styles — Tailwind only.
-- Always use the `Text` component for styled text. Always use `Dropdown` — never
-  `<select>`.
-- Tailwind scale only (`text-xs`, `text-sm`). Never arbitrary pixel values.
-- File naming: components `kebab-case.tsx`, hooks `use-kebab-case.ts`, utilities
-  `kebab-case.ts`.
-- Colors defined in `ui/src/index.css` via Tailwind v4 `@theme`. Never use raw
-  hex values.
-- **Block** = single operation (command, file deploy, cron create, etc.);
-  **Stack** = saved composition of one or more blocks with targets. Do NOT use
-  "runlist" — that term has been replaced.
-- Regenerate the TypeScript SDK via `just generate` at the repository root (runs
-  `redocly join`, `go generate`, copies the combined spec to
-  `ui/src/sdk/gen/api.yaml`, and runs `orval`).
-
-## Adding a New API Domain
-
-When adding a new domain, follow existing domains as reference. Node-targeted
-operations live under `internal/controller/api/node/{domain}/`. Controller-only
-operations live under `internal/controller/api/{domain}/`. Read existing domains
-before creating new ones — the codebase IS the reference.
-
-### Cross-Layer Consistency (MANDATORY)
-
-Every domain MUST be consistent across all layers: provider, agent processor,
-API handler, SDK service, CLI commands, docs, and tests. When adding a new
-domain, look at a recently completed domain (like `ntp` or `sysctl`) and
-replicate the same set of artifacts across every layer. If something exists for
-`sysctl` but not for your new domain, it's missing.
-
-The principle: **pick any existing domain and `find`/`grep` for it across the
-codebase. Your new domain should appear in all the same places.** This includes
-code, tests, examples, SDK docs, CLI docs, feature docs, docusaurus config, and
-permissions tables.
-
-### Step 0: Provider Implementation
-
-Providers are the operations layer — they execute the actual work on agent
-hosts. Every operation under `/node/{hostname}/...` is backed by a provider. The
-request flows:
-
-```
-CLI → SDK → REST API → Job Client → NATS → Agent → Provider
-```
-
-The provider runs on the agent, not the controller. It receives parameters from
-the job payload and returns a result.
-
-#### Provider Types
-
-Three provider patterns exist. Check existing providers for examples of each:
-
-**Direct providers** interact with the system directly via commands or system
-calls. No file management.
-
-**Meta providers** delegate file writes to `file.Deployer` for SHA tracking,
-idempotency, and template rendering.
-
-**Direct-write providers** manage their own config files via `avfs.VFS` without
-`file.Deployer`. They use the `osapi-` filename prefix to identify managed
-files.
-
-Meta providers depend on `file.Deployer` (the narrow interface):
-
-```go
-type Deployer interface {
-    Deploy(ctx context.Context, req DeployRequest) (*DeployResult, error)
-    Undeploy(ctx context.Context, req UndeployRequest) (*UndeployResult, error)
-}
-```
-
-Meta providers store domain-specific metadata in the `FileState.Metadata` map
-(e.g., schedule, interval, user for cron). The file provider persists this in
-the file-state KV alongside SHA, path, and mode — one KV bucket for all
-providers.
-
-Reference: look at existing meta providers in the codebase.
-
-#### File Structure
-
-Platform-specific providers:
-
-```
-internal/provider/{category}/{domain}/
-  types.go              — Provider interface + domain types
-  debian.go             — Debian-family implementation
-  debian_{operation}.go — Per-operation file (large methods)
-  debian_docker.go      — Container-aware variant (if needed)
-  darwin.go             — macOS stub (returns ErrUnsupported)
-  linux.go              — Generic Linux stub (returns ErrUnsupported)
-  mocks/                — Generated gomock mocks
-    generate.go         — //go:generate mockgen directive
-```
-
-SDK-based providers (no platform variants):
-
-```
-internal/provider/{category}/{domain}/
-  types.go        — Provider interface + domain types
-  {domain}.go     — Single implementation (e.g., docker.go)
-  client.go       — API client interface for testing
-  mocks/          — Generated gomock mocks
-    generate.go   — //go:generate mockgen directive
-```
-
-For top-level providers: `internal/provider/{domain}/`. For categorized
-providers: `internal/provider/{category}/{domain}/`. Look at existing providers
-to see both patterns.
-
-#### Provider Interface
-
-```go
-// types.go — package {domain}
-type Provider interface {
-    List(ctx context.Context) ([]Entry, error)
-    Get(ctx context.Context, name string) (*Entry, error)
-    Create(ctx context.Context, entry Entry) (*CreateResult, error)
-    Update(ctx context.Context, entry Entry) (*UpdateResult, error)
-    Delete(ctx context.Context, name string) (*DeleteResult, error)
-}
-```
-
-Every method takes `context.Context` as the first parameter. Result types
-include `Changed bool` for mutations and `Error string` for per-operation error
-reporting.
-
-#### Idempotency (MANDATORY)
-
-All provider mutations follow Ansible-style desired-state semantics. Operations
-MUST be idempotent:
-
-| Operation  | Resource exists       | Resource absent       |
-| ---------- | --------------------- | --------------------- |
-| **Create** | `Changed: false`, nil | Creates it            |
-| **Update** | Updates it            | Error (not found)     |
-| **Delete** | Removes it            | `Changed: false`, nil |
-
-- **Create** when the resource already exists returns success with
-  `Changed: false` — the desired state (present) is already met.
-- **Delete** when the resource doesn't exist returns success with
-  `Changed: false` — the desired state (absent) is already met.
-- **Update** when the resource doesn't exist returns an error — there is nothing
-  to update.
-- `ErrUnsupported` (wrong OS family) maps to `StatusSkipped` at the agent layer,
-  which is distinct from `Changed: false`.
-
-Every concrete provider struct MUST embed `provider.FactsAware` and include a
-compile-time check:
-
-```go
-// Compile-time check: Debian must satisfy FactsSetter.
-var _ provider.FactsSetter = (*Debian)(nil)
-
-type Debian struct {
-    provider.FactsAware
-    logger *slog.Logger
-    // ...
-}
-```
-
-The provider must also be passed to `provider.WireProviderFacts()` in
-`internal/agent/agent.go` so facts are injected at startup.
-
-#### Platform-Specific Implementations
-
-OSAPI follows Ansible's OS family naming. Implementations are selected at
-runtime via `platform.Detect()`:
-
-- `debian.go` — Debian family (Ubuntu, Debian, Raspbian)
-- `darwin.go` — macOS (for development)
-- `linux.go` — generic Linux fallback
-
-Unsupported platforms return `provider.ErrUnsupported`. The agent marks the job
-as `skipped` (not `failed`) so the caller knows the operation isn't available on
-that host rather than broken.
-
-```go
-// darwin.go
-func (d *Darwin) List(
-    _ context.Context,
-) ([]Entry, error) {
-    return nil, fmt.Errorf("cron: %w", provider.ErrUnsupported)
-}
-```
-
-#### Provider Naming Conventions
-
-There are three provider implementation patterns. The naming convention
-determines the struct name, constructor, and file layout.
-
-**1. Platform-specific providers** (most common)
-
-One struct per OS family, each in its own file. Constructor names follow
-`New{Platform}Provider()`. Methods that are large or testable go in separate
-files named `{platform}_{operation}.go`.
-
-| Struct   | Constructor              | File(s)                        |
-| -------- | ------------------------ | ------------------------------ |
-| `Debian` | `NewDebianProvider(...)` | `debian.go`, `debian_get_*.go` |
-| `Darwin` | `NewDarwinProvider(...)` | `darwin.go`, `darwin_get_*.go` |
-| `Linux`  | `NewLinuxProvider()`     | `linux.go`, `linux_get_*.go`   |
-
-Most providers under `node/` and `network/` follow this pattern.
-
-**2. Container-aware platform providers**
-
-When a provider's behavior differs inside a Docker container (e.g., hostname is
-read-only, DNS uses `/etc/resolv.conf` instead of `resolvectl`), add a
-`DebianDocker` variant alongside the regular `Debian` struct. The agent selects
-it via `platform.IsContainer()`.
-
-| Struct         | Constructor                    | File(s)                                  |
-| -------------- | ------------------------------ | ---------------------------------------- |
-| `DebianDocker` | `NewDebianDockerProvider(...)` | `debian_docker.go`, `debian_docker_*.go` |
-
-`DebianDocker` either embeds `Debian` (delegating reads, overriding writes) or
-stands alone. It satisfies the same `Provider` interface.
-
-```go
-// agent_setup.go wiring
-case "debian":
-    if platform.IsContainer() {
-        hostProvider = nodeHost.NewDebianDockerProvider()
-    } else {
-        hostProvider = nodeHost.NewDebianProvider(execManager)
-    }
-```
-
-Examples: `node/host` (embeds `Debian`, blocks `UpdateHostname`), `network/dns`
-(standalone, reads `/etc/resolv.conf` directly).
-
-**3. SDK-based providers** (no platform variants)
-
-Providers that talk to an external API (not the OS) use a single `Client` struct
-with `New()` / `NewWithClient()` constructors. No `debian.go` / `darwin.go` /
-`linux.go` files — the provider works the same on all platforms. Availability is
-checked at startup (e.g., Docker daemon ping).
-
-| Struct   | Constructor        | File(s)              |
-| -------- | ------------------ | -------------------- |
-| `Client` | `New()`            | `docker.go`          |
-|          | `NewWithClient(c)` | (same file, testing) |
-
-```go
-// agent_setup.go wiring — no platform switch
-dockerClient, err := dockerNewFn()
-if err == nil {
-    if pingErr := dockerClient.Ping(ctx); pingErr == nil {
-        dockerProvider = dockerClient
-    }
-}
-```
-
-Examples: `container/docker`.
-
-#### FactsAware
-
-Embed `provider.FactsAware` in the provider struct to access agent facts (OS
-family, architecture, hostname, network interfaces) at runtime. The agent wires
-facts via `provider.WireProviderFacts()`.
-
-```go
-type Debian struct {
-    provider.FactsAware
-    logger *slog.Logger
-    fs     avfs.VFS
-}
-```
-
-Facts are available in template rendering via `{{ .Facts.os_family }}` when
-using the file provider's template support.
-
-#### Agent Wiring
-
-Two files connect a provider to the agent:
-
-1. **`internal/agent/processor_{domain}.go`** — create helper functions that
-   dispatch sub-operations to the provider. If the domain gets its own category
-   (like `schedule`, `docker`), create a `NewXxxProcessor` factory. If the
-   domain belongs under an existing category (like `node`), add a `case` to that
-   category's processor and delegate to helpers in a new file:
-
-   ```go
-   // processor_{domain}.go
-   func process{Domain}Operation(
-       provider {domain}.Provider,
-       logger *slog.Logger,
-       req job.Request,
-   ) (json.RawMessage, error) {
-       // switch on sub-operation, call provider, marshal result
-   }
-   ```
-
-2. **`cmd/agent_setup.go`** — create the provider and register it with the
-   `ProviderRegistry`. For new categories, use a separate `Register` call. For
-   existing categories (e.g., `node`), pass the provider to the existing
-   processor factory:
-
-   ```go
-   // New category example (like schedule, docker):
-   registry.Register("mydomain",
-       agent.NewMyDomainProcessor(myProv, log),
-       myProv)
-
-   // Existing category example (node):
-   // Add your provider as a parameter to NewNodeProcessor
-   // and include it in the providers list for FactsAware wiring.
-   // Read cmd/agent_setup.go to see the current parameter list.
-   ```
-
-That's it. No changes to `agent/types.go`, `agent/agent.go`, or the `JobClient`
-interface. The registry handles dispatch and FactsAware wiring automatically.
-
-#### Provider Testing
-
-- **Filesystem:** Use `avfs` — `memfs.New()` for in-memory, `failfs.New()` for
-  targeted error injection. Never use `afero`.
-- **Mocks:** Use gomock for all interfaces (`FileDeployer`, `KeyValue`,
-  `ObjectStore`). Generated mocks live in `{package}/mocks/`.
-- **Platform stubs:** Test that Darwin and Linux stubs return `ErrUnsupported`
-  for every method.
-- **export_test.go:** Use for testing unexported variable swaps (e.g.,
-  `marshalJSON`). Public tests import via the bridge.
-- **Table-driven:** One suite method per provider method, all scenarios as rows.
-
-### Step 1: OpenAPI Spec + Code Generation
-
-For node-targeted domains, create `internal/controller/api/node/{domain}/gen/`
-with three hand-written files. For controller-only domains, create
-`internal/controller/api/{domain}/gen/` instead:
-
-- `api.yaml` — OpenAPI spec with paths, schemas, and `BearerAuth` security
-- `cfg.yaml` — oapi-codegen config (`strict-server: true`, import-mapping for
-  `common/gen`)
-- `generate.go` — `//go:generate` directive
-
-#### HTTP Verb Conventions
-
-Mutable domains MUST use separate verbs for create and update:
-
-- `POST` — create a new resource (key/name in request body)
-- `PUT` — update an existing resource (key/name from path parameter)
-- `GET` — read/list resources
-- `DELETE` — remove a resource
-
-Do NOT combine create and update into a single "set" or "upsert" endpoint. The
-cron domain is the reference: `POST` creates, `PUT /{name}` updates. This
-separation gives clear 404 semantics (update fails if not found, create fails if
-already exists) and matches REST conventions.
-
-#### Validation in OpenAPI Specs
-
-The OpenAPI spec is the **source of truth** for input validation. All user input
-must be validated, and the spec must declare how:
-
-- **Request body properties**: Add `x-oapi-codegen-extra-tags` with `validate:`
-  tags. These generate Go struct tags that `validation.Struct()` enforces at
-  runtime.
-  ```yaml
-  properties:
-    address:
-      type: string
-      x-oapi-codegen-extra-tags:
-        validate: required,ip
-  ```
-- **Path parameters (UUID)**: Use `format: uuid` on the schema. This causes
-  oapi-codegen to generate `openapi_types.UUID` type, and the router validates
-  the format before the handler runs. No manual validation needed in the
-  handler.
-  ```yaml
-  parameters:
-    - name: id
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-  ```
-- **Query parameters**: Place `x-oapi-codegen-extra-tags` at the **parameter
-  level** (sibling of `name`/`in`/`schema`), NOT inside `schema:`. At parameter
-  level, oapi-codegen generates `validate:` tags on the `*Params` struct fields.
-  Use `enum` for constrained string values (generates `oneof` validation).
-  ```yaml
-  parameters:
-    - name: limit
-      in: query
-      required: false
-      x-oapi-codegen-extra-tags:
-        validate: omitempty,min=1,max=100
-      schema:
-        type: integer
-        default: 20
-        minimum: 1
-        maximum: 100
-  ```
-  Then in the handler, validate with a single call:
-  ```go
-  if errMsg, ok := validation.Struct(request.Params); !ok {
-      return gen.GetFoo400JSONResponse{Error: &errMsg}, nil
-  }
-  ```
-  **NOTE:** `x-oapi-codegen-extra-tags` on **path parameters** does NOT generate
-  tags on `RequestObject` structs in **strict-server mode** (upstream limitation
-  — see oapi-codegen issue). Keep the `x-oapi-codegen-extra-tags` in the spec
-  for documentation and add a YAML comment noting validation is handled
-  manually. Path params that need validation beyond `format: uuid` (e.g.,
-  `valid_target`) use a shared helper like `node.validateHostname()` which calls
-  `validation.Var()`.
-
-**IMPORTANT — every endpoint with user input MUST have:**
-
-1. `x-oapi-codegen-extra-tags` with `validate:` tags on all request body
-   properties and query params in the OpenAPI spec
-2. `validation.Struct(request.Params)` in the handler for query params,
-   `validation.Struct(request.Body)` for request bodies
-3. A `400` response defined in the OpenAPI spec for endpoints that accept user
-   input
-4. HTTP wiring tests (`TestXxxHTTP` / `TestXxxRBACHTTP` methods in the
-   `*_public_test.go` suite) that send raw HTTP through the full Echo middleware
-   stack and verify:
-   - Validation errors return correct status codes and error messages
-   - RBAC: 401 (no token), 403 (wrong permissions), 200 (valid token)
-
-**Defense-in-depth validation**: When validation calls cannot currently fail
-(e.g., all fields use `omitempty`), keep the call but add a comment explaining
-why. This guards against future field additions breaking validation silently:
-
-```go
-// Defense in depth: current fields use omitempty so validation
-// always passes, but guards against future field additions.
-if errMsg, ok := validation.Struct(request.Body); !ok {
-    return gen.PostFoo400JSONResponse{Error: &errMsg}, nil
-}
-```
-
-### Step 2: Handler Implementation
-
-For node-targeted domains, create `internal/controller/api/node/{domain}/`. For
-controller-only domains, create `internal/controller/api/{domain}/`:
-
-- `types.go` — domain struct, dependency interfaces (e.g., `Checker`)
-- `{domain}.go` — `New()` factory, compile-time interface check:
-  `var _ gen.StrictServerInterface = (*Domain)(nil)`
-- One file per endpoint (e.g., `{operation}_get.go`). Every handler that accepts
-  user input MUST call `validation.Struct()` and return a 400 on failure.
-- Tests: `{operation}_get_public_test.go` (testify/suite, table-driven). Must
-  cover validation failures (400), success, and error paths. Each public test
-  suite also includes HTTP wiring methods:
-  - `TestXxxHTTP` — sends raw HTTP through the full Echo middleware stack to
-    verify validation (valid input, invalid input → 400).
-  - `TestXxxRBACHTTP` — verifies auth middleware: no token (401), wrong
-    permissions (403), valid token (200). Uses `api.New()` +
-    `{domain}.Handler()` + `server.RegisterHandlers()` to wire through
-    `ScopeMiddleware`. Follow existing handler test files in the codebase.
-
-#### Broadcast Support (MANDATORY for node-targeted operations)
-
-Every operation under `/node/{hostname}/...` MUST support broadcast targeting
-(`_all`, `_any`, hostname, label selectors). The handler checks
-`job.IsBroadcastTarget(hostname)` and routes to a broadcast function. Both
-single-target and broadcast paths return the same collection response shape.
-
-**Response pattern** — all node-targeted operations return:
-
-```json
-{
-  "job_id": "...",
-  "results": [
-    {"hostname": "web-01", "error": "", ...domain fields...},
-    {"hostname": "web-02", "error": "unsupported", ...}
-  ]
-}
-```
-
-Every result item MUST have `hostname` and `error` fields. Single-target returns
-1 result; broadcast returns N results. Failed/skipped agents appear as entries
-with `error` set.
-
-**Handler pattern:**
-
-```go
-func (s *Handler) PostOperation(ctx, request) {
-    validate(request)
-    hostname := request.Hostname
-    if job.IsBroadcastTarget(hostname) {
-        return s.postOperationBroadcast(ctx, hostname, ...)
-    }
-    // Single-target: wrap in collection with 1 result.
-}
-```
-
-**Job client** — the `JobClient` interface has 4 generic methods: `Query`,
-`QueryBroadcast`, `Modify`, `ModifyBroadcast`. Handlers call these with a
-category string and operation constant. No new methods are needed when adding
-operations. Example:
-
-```go
-jobID, resp, err := s.JobClient.Modify(
-    ctx, hostname, "node", job.OperationSysctlCreate, data)
-```
-
-Read existing handlers in the codebase for reference.
-
-### Step 3: Handler Registration
-
-Each domain package exports a `Handler()` function that creates the handler,
-wraps it with auth middleware, and returns route registration closures. No
-changes to the `Server` struct are needed.
-
-Create `handler.go` in your domain package:
-
-```go
-// internal/controller/api/node/{domain}/handler.go
-package {domain}
-
-func Handler(
-    logger *slog.Logger,
-    jobClient client.JobClient,
-    signingKey string,
-    customRoles map[string][]string,
-) []func(e *echo.Echo) {
-    var tokenManager api.TokenValidator = authtoken.New(logger)
-    h := New(logger, jobClient)
-    strictHandler := gen.NewStrictHandler(h,
-        []gen.StrictMiddlewareFunc{
-            func(handler strictecho.StrictEchoHandlerFunc,
-                _ string,
-            ) strictecho.StrictEchoHandlerFunc {
-                return api.ScopeMiddleware(
-                    handler, tokenManager, signingKey,
-                    gen.BearerAuthScopes, customRoles,
-                )
-            },
-        },
-    )
-    return []func(e *echo.Echo){
-        func(e *echo.Echo) {
-            gen.RegisterHandlers(e, strictHandler)
-        },
-    }
-}
-```
-
-Add a `handler_public_test.go` that tests route registration and middleware
-execution. Follow existing domain handler tests.
-
-### Step 4: Startup Wiring
-
-- `cmd/controller_setup.go` — add one line to `registerControllerHandlers`:
-  ```go
-  handlers = append(handlers,
-      {domain}API.Handler(log, jc, signingKey, customRoles)...)
-  ```
-  Add the import for your domain package.
-
-### Step 5: Update SDK
-
-The SDK client library lives in `pkg/sdk/client/`. Its generated HTTP client
-uses the same combined OpenAPI spec as the server
-(`internal/controller/api/gen/api.yaml`). Follow the rules in
-@docs/docs/sidebar/sdk/guidelines.md — especially: never expose `gen` types in
-public method signatures, add JSON tags to all result types, and wrap errors
-with context.
-
-**When modifying existing API specs:**
-
-1. Make changes to the domain's `gen/api.yaml` (under `api/node/{domain}/` for
-   node-targeted domains or `api/{domain}/` for controller-only domains)
-2. Run `just generate` to regenerate server code (this also regenerates the
-   combined spec via `redocly join`)
-3. Run `go generate ./pkg/sdk/client/gen/...` to regenerate the SDK client
-4. Update the SDK service wrappers in `pkg/sdk/client/{domain}.go` if new
-   response codes were added
-5. Update CLI switch blocks in `cmd/` if new response codes were added
-
-**When adding a new API domain:**
-
-1. Add a service with four files in `pkg/sdk/client/`:
-   - `{service}.go` — `{Service}Service` struct + methods
-   - `{service}_types.go` — SDK result types + gen→SDK conversions
-   - `{service}_public_test.go` — service method tests
-   - `{service}_types_public_test.go` — conversion function tests Each service
-     gets its own files — do NOT add methods or types to an existing service's
-     files.
-2. Add a field to the `Client` struct in `osapi.go` and wire it in `New()`
-3. Run `go generate ./pkg/sdk/client/gen/...` to pick up the new domain's spec
-   from the combined `api.yaml`
-4. Add an SDK example in `examples/sdk/client/{service}.go` — one file per SDK
-   service (e.g., `hostname.go`, `disk.go`, `ntp.go`). The example file name
-   matches the Client field name in lowercase.
-5. Add an SDK doc page under the appropriate category subdirectory in
-   `docs/docs/sidebar/sdk/client/`. SDK docs are grouped by concern (e.g.,
-   `node-info/`, `system-config/`, `operations/`). Place the new page in the
-   matching group — look at the existing directory structure to find the right
-   one. Use the Client field name as the page title (e.g., `# Power`), NOT the
-   Go struct name. Update `client.md` to add the service to its category table.
-6. Add the new service to the SDK navbar dropdown in `docs/docusaurus.config.ts`
-   under the matching category header. The dropdown is grouped the same way as
-   the sidebar.
-
-#### SDK method naming
-
-Method naming, type exposure, result-field tags, and error handling are
-specified in the `sdk-standards` capability in
-[osapi-io/specs](https://github.com/osapi-io/specs). When a convention here and
-the specification disagree, the specification wins.
-
-#### SDK example conventions
-
-SDK examples live in `examples/sdk/client/`, one file per SDK service. Follow
-the same principles as the orchestrator examples:
-
-- **One service per file**: demonstrate the service's SDK operations. Don't mix
-  in other services.
-- **Self-contained**: for read-only operations, just call and print. For
-  mutating operations, cleanup at the start so the example is repeatable.
-- **Print results**: decode and print at least one result so the example isn't
-  silent.
-- **Keep it short**: under ~100 lines of code (excluding license).
-- **Handle errors inline**: use `log.Fatalf` for unexpected errors. For
-  operations that may fail on some platforms, check the error and print a
-  message instead of crashing.
-
-### Step 6: CLI Commands
-
-- `cmd/client_node_{domain}.go` — parent command registered under
-  `clientNodeCmd` (for node-targeted domains)
-- `cmd/client_node_{domain}_{operation}.go` — one subcommand per endpoint (e.g.,
-  `client_node_sysctl_get.go`)
-- All commands support `--json` for raw output
-- Use `cli.PrintKV` for inline key-value output and `cli.PrintCompactTable` for
-  multi-row tabular data (both in `internal/cli/ui.go`)
-- Use flags (e.g., `--job-id`, `--audit-id`) instead of positional args for
-  resource IDs
-- Handle **all** API response codes in the `switch resp.StatusCode()` block:
-  200, 400 (`handleUnknownError`), 401/403 (`handleAuthError`), 404
-  (`handleUnknownError`), 500 (`handleUnknownError`). Match the responses
-  declared in the OpenAPI spec.
-
-### Step 7: Documentation
-
-- `docs/docs/sidebar/features/{domain}-management.md` — feature page. Follow
-  existing feature pages for the template.
-- `docs/docs/sidebar/usage/cli/client/node/{domain}/{domain}.md` — CLI landing
-  page with `<DocCardList />`
-- `docs/docs/sidebar/usage/cli/client/node/{domain}/{verb}.md` — one page per
-  CLI subcommand (e.g., `get.md`, `create.md`, `update.md`)
-- Update `docs/docusaurus.config.ts`:
-  - Add the new feature to the "Features" navbar dropdown
-  - Add the new SDK service to the "SDK" → "Client Library" dropdown
-- Update `docs/docs/sidebar/features/features.md` — add the new domain to the
-  features landing page table
-- Update `docs/docs/sidebar/usage/configuration.md` — add any new permissions to
-  the roles table and permissions comments in the YAML reference
-- Update `docs/docs/sidebar/features/authentication.md` — add new permissions to
-  the roles/permissions tables
-- Update `docs/docs/sidebar/architecture/architecture.md` — add link to the new
-  feature page in the features list
-- Update `docs/docs/sidebar/architecture/api-guidelines.md` — add new endpoints
-  to the path pattern table
-- Update `docs/docs/sidebar/architecture/system-architecture.md` — add endpoints
-  to the health/endpoint tables if applicable
-
-### Step 8: Verify
-
-```bash
-just generate        # regenerate specs + code
-go build ./...       # compiles
-just go-unit        # tests pass
-just go-vet         # lint passes
-```
-
-## Code Standards (MANDATORY)
-
-### Function Signatures
-
-ALL function signatures MUST use multi-line format:
-
-```go
-func FunctionName(
-    param1 type1,
-    param2 type2,
-) (returnType, error) {
-}
-```
-
-### Testing
-
-Three test layers:
-
-- **Unit tests** (`*_test.go`, `*_public_test.go`) — fast, mocked dependencies,
-  run with `just go-unit`. Includes `TestXxxHTTP` / `TestXxxRBACHTTP` methods
-  that send raw HTTP through real Echo middleware with mocked backends.
-- **Integration tests** (`test/integration/`) — build and start a real `osapi`
-  binary, exercise CLI commands end-to-end. Guarded by `//go:build integration`
-  tag, run with `just go-unit-int`. New API domains should include a
-  `{domain}_test.go` smoke suite. Write tests (mutations) must be guarded by
-  `skipWrite(s.T())` so CI can run read-only tests by default
-  (`OSAPI_INTEGRATION_WRITES=1` enables writes).
-
-Conventions:
-
-- ALL tests MUST use `testify/suite` with table-driven patterns
-- Public tests: `*_public_test.go` in test package (e.g., `package job_test`)
-  for exported functions. This is the default — all new tests should be public
-  tests.
-- Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`
-- Table-driven structure with `validateFunc` callbacks
-- One suite method per function under test — all scenarios (success, errors,
-  edge cases) as rows in one table
-- Avoid generic file names like `helpers.go` or `utils.go` — name files after
-  what they contain
-- **`types.go` is for types only**: `types.go` files MUST contain only type
-  definitions (structs, interfaces, constants, type aliases). Never put
-  functions or methods in `types.go` — put them in a file named after what they
-  do (e.g., `nats.go` for NATS config methods, `options.go` for option
-  functions).
-- **Test file naming**: every test file MUST have a corresponding production
-  file with a matching name. `foo_public_test.go` tests `foo.go`. Never create
-  test files with names that don't match a production file (e.g., don't create
-  `check_error_public_test.go` if the code lives in `response.go` — name it
-  `response_public_test.go`). If a production file is too large and you want to
-  split tests by concern, split the production file first (e.g., `agent.go` →
-  `agent.go` + `agent_drain.go` + `agent_timeline.go`), then create matching
-  test files.
-
-#### Mocking
-
-- **Always use gomock** (`go:generate mockgen`) for interface mocks. Generated
-  mocks live in `{package}/mocks/` directories alongside their source
-  interfaces. Never hand-roll mock structs.
-- **export_test.go pattern** for testing unexported internals: create an
-  `export_test.go` file in the production package that exposes unexported
-  variables or functions to the `_test` package:
-  ```go
-  // export_test.go — package file
-  package file
-
-  func SetMarshalJSON(fn func(interface{}) ([]byte, error)) {
-      marshalJSON = fn
-  }
-  func ResetMarshalJSON() { marshalJSON = json.Marshal }
-  ```
-  Public tests then call `file.SetMarshalJSON(...)` and
-  `defer file.ResetMarshalJSON()`. This avoids internal tests, import cycles,
-  and hand-rolled stubs.
-- **TearDownSubTest** — use `suite.TearDownSubTest()` to reset swapped variables
-  between table-driven sub-tests, not `defer` inside the loop.
-- **Filesystem testing** — use `avfs` (`memfs.New()` for in-memory,
-  `failfs.New()` for targeted error injection). Never use `afero`. The only
-  exception for hand-rolled types is stdlib interfaces like `fs.FS` or
-  `net.Conn` where gomock is impractical.
-
-### Go Patterns
-
-- Non-blocking lifecycle: `Start()` returns immediately, `Stop(ctx)` shuts down
-  with deadline
-- Error wrapping: `fmt.Errorf("context: %w", err)`
-- Early returns over nested if-else
-- Unused parameters: rename to `_`
-- Import order: stdlib, third-party, local (blank-line separated)
-
-### Logging
-
-All logging uses Go's `log/slog` structured logger. Follow these rules:
-
-- **Subsystem labels**: Every component that holds a logger MUST wrap it with
-  `logger.With(slog.String("subsystem", "..."))` at construction time. This
-  auto-tags every log line from that component. Examples: `"agent"`,
-  `"agent.seed"`, `"api.schedule"`, `"provider.file"`, `"job.client"`,
-  `"metrics"`, `"controller.heartbeat"`.
-- **Always use typed attributes**: Use `slog.String("key", val)`,
-  `slog.Int("key", val)`, `slog.Bool("key", val)`, `slog.Any("key", val)`. Never
-  use positional pairs like `"key", val` — they compile but bypass type safety
-  and are inconsistent with the codebase.
-- **Standard field names**: `error` for errors, `hostname` for hosts, `path` for
-  file paths, `job_id` for job IDs, `name` for entry names, `addr` for
-  addresses.
-- **Error fields**: Use `slog.String("error", err.Error())` for string context
-  or `slog.Any("error", err)` to preserve the error type.
-- **Log levels**: `Debug` for operation dispatch and idempotency skips, `Info`
-  for lifecycle events and state changes, `Warn` for degraded but functional
-  states, `Error` for failures that need attention.
-
-### Linting
-
-golangci-lint with: errcheck, errname, goimports, govet, prealloc, predeclared,
-revive, staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded from
-formatting.
-
-### Branching
-
-See @docs/docs/sidebar/development/development.md#branching for full
-conventions.
-
-When committing changes via `/commit`, create a feature branch first if
-currently on `main`. Branch names use the pattern `type/short-description`
-(e.g., `feat/add-dns-retry`, `fix/memory-leak`, `docs/update-readme`).
-
-### Commit Messages
-
-See @docs/docs/sidebar/development/development.md#commit-messages for full
-conventions.
-
-Follow [Conventional Commits](https://www.conventionalcommits.org/) with the
-50/72 rule. Format: `type(scope): description`.
-
-When committing via Claude Code, end with:
-
-- `🤖 Generated with [Claude Code](https://claude.ai/code)`
-- `Co-Authored-By: Claude <noreply@anthropic.com>`
-
-## Task Tracking
-
-Implementation planning and execution uses the superpowers plugin workflows
-(`writing-plans` and `executing-plans`). Plans live in `docs/plans/`.
+@AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..5d19ca10d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,413 @@
+# Contributing
+
+Contributions to OSAPI are very welcome, but we ask that you read this document
+before submitting a PR. It covers everything you need: prerequisites, setup, the
+conventions code follows, how to add an API domain, and the pull request
+workflow.
+
+## Before you start
+
+- Read the [Code of Conduct](CODE_OF_CONDUCT.md). It applies to every
+  interaction in this repo.
+
+- **Design records** — Reasoning behind a change lives in
+  [osapi-io/specs](https://github.com/osapi-io/specs) as a change, not in this
+  repository. A design document kept here goes stale the moment the code moves
+  past it, with nothing to catch the drift.
+
+- **Get familiar with the project** — Read the docs in this order:
+
+  1. [Guiding Principles][principles] — design philosophy and project values
+  2. [System Architecture][system-architecture] — REST API, NATS, CLI
+  3. [API Design Guidelines][api-guidelines] — REST conventions and endpoint
+     structure
+  4. [Job System Architecture][job-architecture] — KV-first job processing,
+     subject routing, and the agent pipeline
+
+- **Check existing work** — Is there an existing PR? Are there issues discussing
+  the feature/change you want to make? Please make sure you consider/address
+  these discussions in your work.
+
+- **Backwards compatibility** — Will your change break existing OSAPI files? It
+  is much more likely that your change will be merged if it is backwards
+  compatible. Is there an approach you can take that maintains this
+  compatibility? If not, consider opening an issue first so that API changes can
+  be discussed before you invest your time into a PR.
+
+## Prerequisites
+
+Install tools using [mise]:
+
+```bash
+mise install
+```
+
+- **[Go]** — OSAPI is written in Go. We always support the latest two major Go
+  versions, so make sure your version is recent enough.
+- **[Node.js]** — Runtime for tools like `@redocly/cli`, for building the
+  Docusaurus docs site, and for building the embedded React UI in `ui/`.
+- **[Bun]** — JavaScript package manager and script runner used for the
+  Docusaurus docs and the React UI.
+- **[just]** — Task runner used for building, testing, formatting, and other
+  development workflows.
+- **[uv]** — Python package runner. `just md-fmt` formats repository markdown
+  with [mdformat] via `uvx`; nothing is installed into the repo.
+- **[NATS CLI]** — Command-line tools for interacting with NATS. Useful for
+  debugging and monitoring during development. Install with
+  `brew install nats-io/nats-tools/nats`.
+
+### Claude Code
+
+If you use [Claude Code] for development, install these plugins from the default
+marketplace:
+
+```
+/plugin install commit-commands@claude-plugins-official
+/plugin install superpowers@claude-plugins-official
+```
+
+- **commit-commands** — provides `/commit` and `/commit-push-pr` slash commands
+  that follow the project's commit conventions automatically.
+- **superpowers** — provides structured workflows for planning, TDD, debugging,
+  code review, and git worktree isolation.
+
+## Setup
+
+Fetch shared justfiles and install all dependencies:
+
+```bash
+just fetch
+just deps
+```
+
+## Building and running
+
+```bash
+just build     # Builds the React UI, then the Go binary
+./osapi controller start -f configs/osapi.yaml
+```
+
+**Always build through `just`.** The `//go:embed dist/*` directive in
+`ui/embed.go` requires `ui/dist/` to hold files at compile time, and
+`just build` runs `just react-build` first to satisfy it. Running
+`go build ./...` or `go test ./...` directly fails for this reason.
+`just build`, `just test`, and `just ready` all build the UI first.
+
+## Project structure
+
+- **`cmd/`** — Cobra CLI commands (`client`, `node agent`, `controller.api`,
+  `nats server`).
+- **`internal/controller/api/`** — Echo REST API. Node-targeted handlers nest
+  under `node/{domain}/`; controller-only handlers are top-level (`job/`,
+  `health/`). Each domain has its own `gen/` with an OpenAPI spec; the combined
+  spec is `internal/controller/api/gen/api.yaml`.
+- **`internal/job/`** — Job domain types and subject routing. `client/` holds
+  the high-level operations.
+- **`internal/agent/`** — Node agent: the consumer/handler/processor pipeline
+  for job execution.
+- **`internal/provider/`** — Operation implementations, organized by category
+  then domain.
+- **`internal/config/`** — Viper-based config from `osapi.yaml`.
+- **`internal/telemetry/`** — Tracing, metrics, and agent self-metrics.
+- **`internal/controller/notify/`** — Condition notification system.
+- **`pkg/sdk/`** — Go SDK for programmatic REST API access.
+- **`ui/`** — React 19 + TypeScript + Vite + Tailwind CSS v4, embedded into the
+  Go binary at build time.
+
+[System Architecture][system-architecture] describes the package layout, handler
+structure, and provider pattern in full.
+
+`nats-client` and `nats-server` are sibling repositories, consumed as pinned
+module versions in `go.mod` — there is no `replace` directive.
+
+## Code style
+
+Go code should be formatted by [gofumpt] and linted using [golangci-lint]. This
+style is enforced by CI.
+
+```bash
+just go-fmt-check   # Check formatting
+just go-fmt         # Auto-fix formatting
+just go-vet         # Run linter
+```
+
+golangci-lint runs errcheck, errname, goimports, govet, prealloc, predeclared,
+revive, and staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded
+from formatting.
+
+TypeScript and CSS in `ui/` are formatted by [Prettier] and linted by [ESLint].
+Markdown outside the Docusaurus site is formatted by [mdformat]; the site itself
+is formatted by Prettier through the `docusaurus` module.
+
+```bash
+just react-fmt      # Auto-fix UI formatting
+just react-lint     # Run ESLint
+just md-fmt         # Format markdown outside the site
+just docusaurus-fmt # Format the site
+```
+
+## Code standards
+
+The Go conventions this repository follows — multi-line function signatures,
+naming a file for what it holds, `types.go` for types only, table-driven
+`testify/suite` tests, generated mocks, and the error-wrapping and import-order
+baseline — are specified in the `go-code-standards` capability in
+[osapi-io/specs](https://github.com/osapi-io/specs). Read it before writing
+code; it is the source, and this repository does not restate it.
+
+The conventions below are specific to OSAPI and are stated only here.
+
+### Logging
+
+All logging uses Go's `log/slog` structured logger.
+
+- **Subsystem labels** — Every component that holds a logger MUST wrap it with
+  `logger.With(slog.String("subsystem", "..."))` at construction time, which
+  auto-tags every line from that component. Examples: `"agent"`, `"agent.seed"`,
+  `"api.schedule"`, `"provider.file"`, `"job.client"`, `"metrics"`,
+  `"controller.heartbeat"`.
+- **Typed attributes** — Use `slog.String("key", val)`, `slog.Int`, `slog.Bool`,
+  `slog.Any`. Never use positional pairs like `"key", val`; they compile but
+  bypass type safety.
+- **Standard field names** — `error` for errors, `hostname` for hosts, `path`
+  for file paths, `job_id` for job IDs, `name` for entry names, `addr` for
+  addresses.
+- **Error fields** — `slog.String("error", err.Error())` for string context, or
+  `slog.Any("error", err)` to preserve the error type.
+- **Log levels** — `Debug` for operation dispatch and idempotency skips, `Info`
+  for lifecycle events and state changes, `Warn` for degraded but functional
+  states, `Error` for failures that need attention.
+
+### Lifecycle
+
+Components use a non-blocking lifecycle: `Start()` returns immediately, and
+`Stop(ctx)` shuts down with a deadline.
+
+### Filesystem access
+
+Use [avfs] — `memfs.New()` for in-memory work and `failfs.New()` for targeted
+error injection. Never use `afero`.
+
+## Testing
+
+```bash
+just test           # Run all tests (lint + unit + coverage)
+just go-unit        # Run unit tests only
+just go-unit-int    # Run integration tests
+go test -run TestName -v ./internal/job/...  # Run a single test
+```
+
+Coverage is gated at 99.9%. `just test` fails if total coverage drops below it,
+so a change that adds untested code fails locally and in CI:
+
+```bash
+just go-unit-cov-check   # Report coverage and fail below the target
+```
+
+The target is declared in `.github/codecov.yml` and in the shared `go` justfile
+module — change both together.
+
+### Test layers
+
+- **Unit tests** (`*_test.go`, `*_public_test.go`) — fast, mocked dependencies.
+  Public suites also carry HTTP wiring methods (`TestXxxHTTP`,
+  `TestXxxRBACHTTP`) that send raw HTTP through the full Echo middleware stack
+  with mocked backends.
+- **Integration tests** (`test/integration/`) — build and start a real `osapi`
+  binary and exercise CLI commands end-to-end. Guarded by a
+  `//go:build integration` tag. The harness allocates random ports, generates a
+  JWT, and starts the server, so no external setup is required.
+
+A new API domain should include a `{domain}_test.go` smoke suite under
+`test/integration/`. Mutating tests MUST be guarded by `skipWrite(s.T())` so CI
+runs read-only tests by default; `OSAPI_INTEGRATION_WRITES=1` enables writes.
+
+### Test doubles
+
+- Use `export_test.go` to expose an unexported variable or function to the
+  `_test` package, rather than writing an internal test or a hand-rolled stub.
+- Use `suite.TearDownSubTest()` to reset swapped variables between table-driven
+  sub-tests, not `defer` inside the loop.
+- Platform stubs: test that the Darwin and Linux stubs return `ErrUnsupported`
+  for every method.
+- The only exception to generated mocks is a stdlib interface such as `fs.FS` or
+  `net.Conn`, where `mockgen` is impractical.
+
+## Input validation
+
+All user input is validated through the `internal/validation` package, which
+wraps [go-playground/validator]. Rules are declared in OpenAPI specs via
+`x-oapi-codegen-extra-tags` and enforced at runtime by handler calls to
+`validation.Struct()` or `validation.Var()`.
+
+Config struct fields in `internal/config/types.go` use the same `validate` tags.
+Validation runs at startup after `viper.Unmarshal()`, so an invalid value exits
+immediately with a clear error. Defaults are set via `viper.SetDefault()` in
+`cmd/root.go`, so most fields can be omitted. Use `go_duration` for Go duration
+strings, and add `required` to fields with no sensible default.
+
+- **Required fields** use `validate:"required,..."`.
+- **Optional fields** use `validate:"omitempty,..."`.
+- **Enum constraints** use `validate:"oneof=a b c"`.
+- **Cross-field validation** uses `required_without` / `excluded_with` for
+  mutually exclusive fields, such as cron `schedule` versus `interval`.
+
+### Update endpoints with all-optional fields
+
+When a PUT endpoint has all-optional fields (user update, group update, cron
+update), call `validation.AtLeastOneField(request.Body)` after
+`validation.Struct()` to reject empty bodies with a 400. This prevents
+meaningless no-op updates and, worse, triggering destructive defaults.
+
+```go
+if errMsg, ok := validation.Struct(request.Body); !ok {
+    return gen.PutXxx400JSONResponse{Error: &errMsg}, nil
+}
+
+if errMsg, ok := validation.AtLeastOneField(request.Body); !ok {
+    return gen.PutXxx400JSONResponse{Error: &errMsg}, nil
+}
+```
+
+### Defense in depth
+
+When `validation.Struct()` cannot currently fail because every field uses
+`omitempty`, keep the call and comment why. This guards against a later field
+addition silently breaking validation:
+
+```go
+// Defense in depth: current fields use omitempty so validation
+// always passes, but guards against future field additions.
+if errMsg, ok := validation.Struct(request.Body); !ok {
+    return gen.PostXxx400JSONResponse{Error: &errMsg}, nil
+}
+```
+
+This applies to action endpoints (power, docker stop) where an empty body is
+valid — unlike update endpoints, which must use `AtLeastOneField`.
+
+## Adding a new API domain
+
+Every domain must be consistent across all layers: provider, agent processor,
+API handler, SDK service, CLI commands, docs, and tests. The
+[Adding an API Domain][adding-an-api-domain] guide walks the nine steps in
+order, from the provider implementation through to verification.
+
+The principle: **pick an existing domain and `find`/`grep` for it across the
+codebase. Your new domain should appear in all the same places.** If something
+exists for `sysctl` but not for yours, it is missing.
+
+## UI contributions
+
+The React management dashboard lives in `ui/` and is embedded into the Go binary
+at build time. See [UI Development][ui-development] for prerequisites, the
+development server, code style, and component conventions, and
+[UI Architecture][ui-architecture] for the embedding mechanism, component
+layers, and SDK generation flow.
+
+## Documentation
+
+OSAPI uses [Docusaurus] to host a documentation server. Content is written in
+Markdown under `docs/docs/`, wrapped at 80 characters.
+
+```bash
+just docusaurus-start     # Start local docs server
+just docusaurus-build     # Build docs for production
+just docusaurus-fmt-check # Check site formatting
+just md-fmt-check         # Check markdown outside the site
+```
+
+## Before committing
+
+Run `just ready` before committing. It regenerates code, formats, lints, and
+builds both the Go binary and the UI, so your commit matches what CI verifies:
+
+```bash
+just ready
+```
+
+## Branching
+
+All changes should be developed on feature branches. Create a branch from `main`
+using the naming convention `type/short-description`, where `type` matches the
+[Conventional Commits] type:
+
+- `feat/add-retry-logic`
+- `fix/null-pointer-crash`
+- `docs/update-api-reference`
+- `refactor/simplify-handler`
+- `chore/update-dependencies`
+
+When using Claude Code's `/commit` command, a branch will be created
+automatically if you are on `main`.
+
+## Commit messages
+
+Follow [Conventional Commits] with the 50/72 rule:
+
+- **Subject line**: max 50 characters, imperative mood, capitalized, no period
+- **Body**: wrap at 72 characters, separated from subject by a blank line
+- **Format**: `type(scope): description`
+- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
+- Summarize the "what" and "why", not the "how"
+
+Try to write meaningful commit messages and avoid having too many commits on a
+PR. Most PRs should likely have a single commit (although for bigger PRs it may
+be reasonable to split it in a few). Git squash and rebase is your friend!
+
+## Submitting a PR
+
+- **Describe your changes** — Ensure that you provide a comprehensive
+  description of your changes.
+- **Issue/PR links** — Link any previous work such as related issues or PRs.
+  Please describe how your changes differ to/extend this work.
+- **Examples** — Add any examples or screenshots that you think are useful to
+  demonstrate the effect of your changes.
+- **Draft PRs** — If your changes are incomplete, but you would like to discuss
+  them, open the PR as a draft and add a comment to start a discussion. Using
+  comments rather than the PR description allows the description to be updated
+  later while preserving any discussions.
+
+## AI usage
+
+This repo is written with AI assistance. All contributions are subject to the
+[AI Usage Policy](AI_POLICY.md) — disclose the tool you used, and make sure you
+can explain what your change does without the aid of AI tools.
+
+## FAQ
+
+> I want to contribute, where do I start?
+
+All kinds of contributions are welcome, whether it's a typo fix or a shiny new
+feature. You can also contribute by upvoting/commenting on issues or helping to
+answer questions.
+
+> I'm stuck, where can I get help?
+
+If you have questions, feel free to open a [Discussion] on GitHub.
+
+[adding-an-api-domain]: docs/docs/sidebar/development/adding-an-api-domain.md
+[api-guidelines]: docs/docs/sidebar/architecture/api-guidelines.md
+[avfs]: https://github.com/avfs/avfs
+[bun]: https://bun.sh
+[claude code]: https://claude.ai/code
+[conventional commits]: https://www.conventionalcommits.org
+[discussion]: https://github.com/osapi-io/osapi/discussions
+[docusaurus]: https://docusaurus.io
+[eslint]: https://eslint.org
+[go]: https://go.dev
+[go-playground/validator]: https://github.com/go-playground/validator
+[gofumpt]: https://github.com/mvdan/gofumpt
+[golangci-lint]: https://golangci-lint.run
+[job-architecture]: docs/docs/sidebar/architecture/job-architecture.md
+[just]: https://just.systems
+[mdformat]: https://pypi.org/project/mdformat/
+[mise]: https://mise.jdx.dev
+[nats cli]: https://github.com/nats-io/natscli
+[node.js]: https://nodejs.org
+[prettier]: https://prettier.io
+[principles]: docs/docs/sidebar/architecture/principles.md
+[system-architecture]: docs/docs/sidebar/architecture/system-architecture.md
+[ui-architecture]: docs/docs/sidebar/architecture/ui.md
+[ui-development]: docs/docs/sidebar/development/ui-development.md
+[uv]: https://docs.astral.sh/uv/
diff --git a/README.md b/README.md
index c53bd9fd5..14563ebda 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,11 @@ them to be used as appliances.
 | [nats-server]        | A Go package for running an embedded NATS server                    |
 | [osapi-orchestrator] | Declarative infrastructure orchestration DSL built on the OSAPI SDK |
 
+## 🤝 Contributing
+
+See the [Contributing](CONTRIBUTING.md) guide for prerequisites, setup,
+conventions, and the PR workflow.
+
 ## 📄 License
 
 The [MIT] License.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
deleted file mode 100644
index 8171634e9..000000000
--- a/docs/CONTRIBUTING.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# How to contribute
-
-:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
-
-It's people like you that make security open source such a force in preventing
-successful cyber-attacks. Following these guidelines helps keep the project
-maintainable, easy to contribute to, and more secure. Thank you for taking the
-time to follow this guide.
-
-## Where to start
-
-There are many ways to contribute. You can fix a bug, improve the documentation,
-submit bug reports and feature requests, or take a first shot at a feature you
-need for yourself.
-
-Pull requests are necessary for all contributions of code or documentation.
-
-## New to open source?
-
-If you're **new to open source** and not sure what a pull request is, welcome!!
-We're glad to have you! All of us once had a contribution to make and didn't
-know where to start.
-
-Even if you don't write code for your job, don't worry, the skills you learn
-during your first contribution to open source can be applied in so many ways,
-you'll wonder what you ever did before you had this knowledge. It's worth
-learning.
-
-[Learn how to make a pull request](https://github.com/PaloAltoNetworks/.github/blob/master/Learn-GitHub.md#learn-how-to-make-a-pull-request)
-
-## Fixing a typo, or a one or two line fix
-
-Many fixes require little effort or review, such as:
-
-> - Spelling / grammar, typos, white space and formatting changes
-> - Comment clean up
-> - Change logging messages or debugging output
-
-These small changes can be made directly in GitHub if you like.
-
-Click the pencil icon in GitHub above the file to edit the file directly in
-GitHub. This will automatically create a fork and pull request with the change.
-See:
-[Make a small change with a Pull Request](https://www.freecodecamp.org/news/how-to-make-your-first-pull-request-on-github/)
-
-## Bug fixes and features
-
-For something that is bigger than a one or two line fix, go through the process
-of making a fork and pull request yourself:
-
-> 1. Create your own fork of the code
-> 2. Clone the fork locally
-> 3. Make the changes in your local clone
-> 4. Push the changes from local to your fork
-> 5. Create a pull request to pull the changes from your fork back into the
->    upstream repository
-
-Please use clear commit messages so we can understand what each commit does.
-We'll review every PR and might offer feedback or request changes before
-merging.
diff --git a/docs/docs/sidebar/architecture/architecture.md b/docs/docs/sidebar/architecture/architecture.md
index d43e9a073..08a5426bc 100644
--- a/docs/docs/sidebar/architecture/architecture.md
+++ b/docs/docs/sidebar/architecture/architecture.md
@@ -200,5 +200,5 @@ configure them — see the Features section:
 - [API Design Guidelines](api-guidelines.md) — REST conventions and endpoint
   patterns
 - [Guiding Principles](principles.md) — design philosophy and project values
-- [Development](../development/development.md) — setup, building, testing, and
-  contributing
+- [Contributing](https://github.com/osapi-io/osapi/blob/main/CONTRIBUTING.md) —
+  setup, building, testing, and the conventions code follows
diff --git a/docs/docs/sidebar/architecture/system-architecture.md b/docs/docs/sidebar/architecture/system-architecture.md
index 4a7824420..5c0aed800 100644
--- a/docs/docs/sidebar/architecture/system-architecture.md
+++ b/docs/docs/sidebar/architecture/system-architecture.md
@@ -314,8 +314,8 @@ disables CORS headers entirely.
 - [API Design Guidelines](api-guidelines.md) — REST conventions, collection
   envelopes, and endpoint patterns
 - [Guiding Principles](principles.md) — design philosophy and project values
-- [Development](../development/development.md) — setup, building, testing, and
-  contributing
+- [Contributing](https://github.com/osapi-io/osapi/blob/main/CONTRIBUTING.md) —
+  setup, building, testing, and the conventions code follows
 
 <!-- prettier-ignore-start -->
 [Cobra]: https://github.com/spf13/cobra
diff --git a/docs/docs/sidebar/development/adding-an-api-domain.md b/docs/docs/sidebar/development/adding-an-api-domain.md
new file mode 100644
index 000000000..e9a41e9d7
--- /dev/null
+++ b/docs/docs/sidebar/development/adding-an-api-domain.md
@@ -0,0 +1,654 @@
+---
+sidebar_position: 5
+---
+
+# Adding an API Domain
+
+When adding a new domain, follow existing domains as reference. Node-targeted
+operations live under `internal/controller/api/node/{domain}/`. Controller-only
+operations live under `internal/controller/api/{domain}/`. Read existing domains
+before creating new ones — the codebase IS the reference.
+
+## Cross-Layer Consistency (MANDATORY)
+
+Every domain MUST be consistent across all layers: provider, agent processor,
+API handler, SDK service, CLI commands, docs, and tests. When adding a new
+domain, look at a recently completed domain (like `ntp` or `sysctl`) and
+replicate the same set of artifacts across every layer. If something exists for
+`sysctl` but not for your new domain, it's missing.
+
+The principle: **pick any existing domain and `find`/`grep` for it across the
+codebase. Your new domain should appear in all the same places.** This includes
+code, tests, examples, SDK docs, CLI docs, feature docs, docusaurus config, and
+permissions tables.
+
+## Step 0: Provider Implementation
+
+Providers are the operations layer — they execute the actual work on agent
+hosts. Every operation under `/node/{hostname}/...` is backed by a provider. The
+request flows:
+
+```
+CLI → SDK → REST API → Job Client → NATS → Agent → Provider
+```
+
+The provider runs on the agent, not the controller. It receives parameters from
+the job payload and returns a result.
+
+### Provider Types
+
+Three provider patterns exist. Check existing providers for examples of each:
+
+**Direct providers** interact with the system directly via commands or system
+calls. No file management.
+
+**Meta providers** delegate file writes to `file.Deployer` for SHA tracking,
+idempotency, and template rendering.
+
+**Direct-write providers** manage their own config files via `avfs.VFS` without
+`file.Deployer`. They use the `osapi-` filename prefix to identify managed
+files.
+
+Meta providers depend on `file.Deployer` (the narrow interface):
+
+```go
+type Deployer interface {
+    Deploy(ctx context.Context, req DeployRequest) (*DeployResult, error)
+    Undeploy(ctx context.Context, req UndeployRequest) (*UndeployResult, error)
+}
+```
+
+Meta providers store domain-specific metadata in the `FileState.Metadata` map
+(e.g., schedule, interval, user for cron). The file provider persists this in
+the file-state KV alongside SHA, path, and mode — one KV bucket for all
+providers.
+
+Reference: look at existing meta providers in the codebase.
+
+### File Structure
+
+Platform-specific providers:
+
+```
+internal/provider/{category}/{domain}/
+  types.go              — Provider interface + domain types
+  debian.go             — Debian-family implementation
+  debian_{operation}.go — Per-operation file (large methods)
+  debian_docker.go      — Container-aware variant (if needed)
+  darwin.go             — macOS stub (returns ErrUnsupported)
+  linux.go              — Generic Linux stub (returns ErrUnsupported)
+  mocks/                — Generated gomock mocks
+    generate.go         — //go:generate mockgen directive
+```
+
+SDK-based providers (no platform variants):
+
+```
+internal/provider/{category}/{domain}/
+  types.go        — Provider interface + domain types
+  {domain}.go     — Single implementation (e.g., docker.go)
+  client.go       — API client interface for testing
+  mocks/          — Generated gomock mocks
+    generate.go   — //go:generate mockgen directive
+```
+
+For top-level providers: `internal/provider/{domain}/`. For categorized
+providers: `internal/provider/{category}/{domain}/`. Look at existing providers
+to see both patterns.
+
+### Provider Interface
+
+```go
+// types.go — package {domain}
+type Provider interface {
+    List(ctx context.Context) ([]Entry, error)
+    Get(ctx context.Context, name string) (*Entry, error)
+    Create(ctx context.Context, entry Entry) (*CreateResult, error)
+    Update(ctx context.Context, entry Entry) (*UpdateResult, error)
+    Delete(ctx context.Context, name string) (*DeleteResult, error)
+}
+```
+
+Every method takes `context.Context` as the first parameter. Result types
+include `Changed bool` for mutations and `Error string` for per-operation error
+reporting.
+
+### Idempotency (MANDATORY)
+
+All provider mutations follow Ansible-style desired-state semantics. Operations
+MUST be idempotent:
+
+| Operation  | Resource exists       | Resource absent       |
+| ---------- | --------------------- | --------------------- |
+| **Create** | `Changed: false`, nil | Creates it            |
+| **Update** | Updates it            | Error (not found)     |
+| **Delete** | Removes it            | `Changed: false`, nil |
+
+- **Create** when the resource already exists returns success with
+  `Changed: false` — the desired state (present) is already met.
+- **Delete** when the resource doesn't exist returns success with
+  `Changed: false` — the desired state (absent) is already met.
+- **Update** when the resource doesn't exist returns an error — there is nothing
+  to update.
+- `ErrUnsupported` (wrong OS family) maps to `StatusSkipped` at the agent layer,
+  which is distinct from `Changed: false`.
+
+Every concrete provider struct MUST embed `provider.FactsAware` and include a
+compile-time check:
+
+```go
+// Compile-time check: Debian must satisfy FactsSetter.
+var _ provider.FactsSetter = (*Debian)(nil)
+
+type Debian struct {
+    provider.FactsAware
+    logger *slog.Logger
+    // ...
+}
+```
+
+The provider must also be passed to `provider.WireProviderFacts()` in
+`internal/agent/agent.go` so facts are injected at startup.
+
+### Platform-Specific Implementations
+
+OSAPI follows Ansible's OS family naming. Implementations are selected at
+runtime via `platform.Detect()`:
+
+- `debian.go` — Debian family (Ubuntu, Debian, Raspbian)
+- `darwin.go` — macOS (for development)
+- `linux.go` — generic Linux fallback
+
+Unsupported platforms return `provider.ErrUnsupported`. The agent marks the job
+as `skipped` (not `failed`) so the caller knows the operation isn't available on
+that host rather than broken.
+
+```go
+// darwin.go
+func (d *Darwin) List(
+    _ context.Context,
+) ([]Entry, error) {
+    return nil, fmt.Errorf("cron: %w", provider.ErrUnsupported)
+}
+```
+
+### Provider Naming Conventions
+
+There are three provider implementation patterns. The naming convention
+determines the struct name, constructor, and file layout.
+
+**1. Platform-specific providers** (most common)
+
+One struct per OS family, each in its own file. Constructor names follow
+`New{Platform}Provider()`. Methods that are large or testable go in separate
+files named `{platform}_{operation}.go`.
+
+| Struct   | Constructor              | File(s)                        |
+| -------- | ------------------------ | ------------------------------ |
+| `Debian` | `NewDebianProvider(...)` | `debian.go`, `debian_get_*.go` |
+| `Darwin` | `NewDarwinProvider(...)` | `darwin.go`, `darwin_get_*.go` |
+| `Linux`  | `NewLinuxProvider()`     | `linux.go`, `linux_get_*.go`   |
+
+Most providers under `node/` and `network/` follow this pattern.
+
+**2. Container-aware platform providers**
+
+When a provider's behavior differs inside a Docker container (e.g., hostname is
+read-only, DNS uses `/etc/resolv.conf` instead of `resolvectl`), add a
+`DebianDocker` variant alongside the regular `Debian` struct. The agent selects
+it via `platform.IsContainer()`.
+
+| Struct         | Constructor                    | File(s)                                  |
+| -------------- | ------------------------------ | ---------------------------------------- |
+| `DebianDocker` | `NewDebianDockerProvider(...)` | `debian_docker.go`, `debian_docker_*.go` |
+
+`DebianDocker` either embeds `Debian` (delegating reads, overriding writes) or
+stands alone. It satisfies the same `Provider` interface.
+
+```go
+// agent_setup.go wiring
+case "debian":
+    if platform.IsContainer() {
+        hostProvider = nodeHost.NewDebianDockerProvider()
+    } else {
+        hostProvider = nodeHost.NewDebianProvider(execManager)
+    }
+```
+
+Examples: `node/host` (embeds `Debian`, blocks `UpdateHostname`), `network/dns`
+(standalone, reads `/etc/resolv.conf` directly).
+
+**3. SDK-based providers** (no platform variants)
+
+Providers that talk to an external API (not the OS) use a single `Client` struct
+with `New()` / `NewWithClient()` constructors. No `debian.go` / `darwin.go` /
+`linux.go` files — the provider works the same on all platforms. Availability is
+checked at startup (e.g., Docker daemon ping).
+
+| Struct   | Constructor        | File(s)              |
+| -------- | ------------------ | -------------------- |
+| `Client` | `New()`            | `docker.go`          |
+|          | `NewWithClient(c)` | (same file, testing) |
+
+```go
+// agent_setup.go wiring — no platform switch
+dockerClient, err := dockerNewFn()
+if err == nil {
+    if pingErr := dockerClient.Ping(ctx); pingErr == nil {
+        dockerProvider = dockerClient
+    }
+}
+```
+
+Examples: `container/docker`.
+
+### FactsAware
+
+Embed `provider.FactsAware` in the provider struct to access agent facts (OS
+family, architecture, hostname, network interfaces) at runtime. The agent wires
+facts via `provider.WireProviderFacts()`.
+
+```go
+type Debian struct {
+    provider.FactsAware
+    logger *slog.Logger
+    fs     avfs.VFS
+}
+```
+
+Facts are available in template rendering via `{{ .Facts.os_family }}` when
+using the file provider's template support.
+
+### Agent Wiring
+
+Two files connect a provider to the agent:
+
+1. **`internal/agent/processor_{domain}.go`** — create helper functions that
+   dispatch sub-operations to the provider. If the domain gets its own category
+   (like `schedule`, `docker`), create a `NewXxxProcessor` factory. If the
+   domain belongs under an existing category (like `node`), add a `case` to that
+   category's processor and delegate to helpers in a new file:
+
+   ```go
+   // processor_{domain}.go
+   func process{Domain}Operation(
+       provider {domain}.Provider,
+       logger *slog.Logger,
+       req job.Request,
+   ) (json.RawMessage, error) {
+       // switch on sub-operation, call provider, marshal result
+   }
+   ```
+
+2. **`cmd/agent_setup.go`** — create the provider and register it with the
+   `ProviderRegistry`. For new categories, use a separate `Register` call. For
+   existing categories (e.g., `node`), pass the provider to the existing
+   processor factory:
+
+   ```go
+   // New category example (like schedule, docker):
+   registry.Register("mydomain",
+       agent.NewMyDomainProcessor(myProv, log),
+       myProv)
+
+   // Existing category example (node):
+   // Add your provider as a parameter to NewNodeProcessor
+   // and include it in the providers list for FactsAware wiring.
+   // Read cmd/agent_setup.go to see the current parameter list.
+   ```
+
+That's it. No changes to `agent/types.go`, `agent/agent.go`, or the `JobClient`
+interface. The registry handles dispatch and FactsAware wiring automatically.
+
+### Provider Testing
+
+Testing conventions are in the root `CONTRIBUTING.md` under "Testing". The
+interfaces a provider typically mocks are `FileDeployer`, `KeyValue`, and
+`ObjectStore`; their generated mocks live in `{package}/mocks/`.
+
+## Step 1: OpenAPI Spec + Code Generation
+
+For node-targeted domains, create `internal/controller/api/node/{domain}/gen/`
+with three hand-written files. For controller-only domains, create
+`internal/controller/api/{domain}/gen/` instead:
+
+- `api.yaml` — OpenAPI spec with paths, schemas, and `BearerAuth` security
+- `cfg.yaml` — oapi-codegen config (`strict-server: true`, import-mapping for
+  `common/gen`)
+- `generate.go` — `//go:generate` directive
+
+### HTTP Verb Conventions
+
+Mutable domains MUST use separate verbs for create and update:
+
+- `POST` — create a new resource (key/name in request body)
+- `PUT` — update an existing resource (key/name from path parameter)
+- `GET` — read/list resources
+- `DELETE` — remove a resource
+
+Do NOT combine create and update into a single "set" or "upsert" endpoint. The
+cron domain is the reference: `POST` creates, `PUT /{name}` updates. This
+separation gives clear 404 semantics (update fails if not found, create fails if
+already exists) and matches REST conventions.
+
+### Validation in OpenAPI Specs
+
+The OpenAPI spec is the **source of truth** for input validation. All user input
+must be validated, and the spec must declare how:
+
+- **Request body properties**: Add `x-oapi-codegen-extra-tags` with `validate:`
+  tags. These generate Go struct tags that `validation.Struct()` enforces at
+  runtime.
+  ```yaml
+  properties:
+    address:
+      type: string
+      x-oapi-codegen-extra-tags:
+        validate: required,ip
+  ```
+- **Path parameters (UUID)**: Use `format: uuid` on the schema. This causes
+  oapi-codegen to generate `openapi_types.UUID` type, and the router validates
+  the format before the handler runs. No manual validation needed in the
+  handler.
+  ```yaml
+  parameters:
+    - name: id
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+  ```
+- **Query parameters**: Place `x-oapi-codegen-extra-tags` at the **parameter
+  level** (sibling of `name`/`in`/`schema`), NOT inside `schema:`. At parameter
+  level, oapi-codegen generates `validate:` tags on the `*Params` struct fields.
+  Use `enum` for constrained string values (generates `oneof` validation).
+  ```yaml
+  parameters:
+    - name: limit
+      in: query
+      required: false
+      x-oapi-codegen-extra-tags:
+        validate: omitempty,min=1,max=100
+      schema:
+        type: integer
+        default: 20
+        minimum: 1
+        maximum: 100
+  ```
+  Then in the handler, validate with a single call:
+  ```go
+  if errMsg, ok := validation.Struct(request.Params); !ok {
+      return gen.GetFoo400JSONResponse{Error: &errMsg}, nil
+  }
+  ```
+  **NOTE:** `x-oapi-codegen-extra-tags` on **path parameters** does NOT generate
+  tags on `RequestObject` structs in **strict-server mode** (upstream limitation
+  — see oapi-codegen issue). Keep the `x-oapi-codegen-extra-tags` in the spec
+  for documentation and add a YAML comment noting validation is handled
+  manually. Path params that need validation beyond `format: uuid` (e.g.,
+  `valid_target`) use a shared helper like `node.validateHostname()` which calls
+  `validation.Var()`.
+
+**IMPORTANT — every endpoint with user input MUST have:**
+
+1. `x-oapi-codegen-extra-tags` with `validate:` tags on all request body
+   properties and query params in the OpenAPI spec
+2. `validation.Struct(request.Params)` in the handler for query params,
+   `validation.Struct(request.Body)` for request bodies
+3. A `400` response defined in the OpenAPI spec for endpoints that accept user
+   input
+4. HTTP wiring tests (`TestXxxHTTP` / `TestXxxRBACHTTP` methods in the
+   `*_public_test.go` suite) that send raw HTTP through the full Echo middleware
+   stack and verify:
+   - Validation errors return correct status codes and error messages
+   - RBAC: 401 (no token), 403 (wrong permissions), 200 (valid token)
+
+**Defense-in-depth validation**: When validation calls cannot currently fail
+(e.g., all fields use `omitempty`), keep the call but add a comment explaining
+why. This guards against future field additions breaking validation silently:
+
+```go
+// Defense in depth: current fields use omitempty so validation
+// always passes, but guards against future field additions.
+if errMsg, ok := validation.Struct(request.Body); !ok {
+    return gen.PostFoo400JSONResponse{Error: &errMsg}, nil
+}
+```
+
+## Step 2: Handler Implementation
+
+For node-targeted domains, create `internal/controller/api/node/{domain}/`. For
+controller-only domains, create `internal/controller/api/{domain}/`:
+
+- `types.go` — domain struct, dependency interfaces (e.g., `Checker`)
+- `{domain}.go` — `New()` factory, compile-time interface check:
+  `var _ gen.StrictServerInterface = (*Domain)(nil)`
+- One file per endpoint (e.g., `{operation}_get.go`). Every handler that accepts
+  user input MUST call `validation.Struct()` and return a 400 on failure.
+- Tests: `{operation}_get_public_test.go` (testify/suite, table-driven). Must
+  cover validation failures (400), success, and error paths. Each public test
+  suite also includes HTTP wiring methods:
+  - `TestXxxHTTP` — sends raw HTTP through the full Echo middleware stack to
+    verify validation (valid input, invalid input → 400).
+  - `TestXxxRBACHTTP` — verifies auth middleware: no token (401), wrong
+    permissions (403), valid token (200). Uses `api.New()` +
+    `{domain}.Handler()` + `server.RegisterHandlers()` to wire through
+    `ScopeMiddleware`. Follow existing handler test files in the codebase.
+
+### Broadcast Support (MANDATORY for node-targeted operations)
+
+Every operation under `/node/{hostname}/...` MUST support broadcast targeting
+(`_all`, `_any`, hostname, label selectors). The handler checks
+`job.IsBroadcastTarget(hostname)` and routes to a broadcast function. Both
+single-target and broadcast paths return the same collection response shape.
+
+**Response pattern** — all node-targeted operations return:
+
+```json
+{
+  "job_id": "...",
+  "results": [
+    {"hostname": "web-01", "error": "", ...domain fields...},
+    {"hostname": "web-02", "error": "unsupported", ...}
+  ]
+}
+```
+
+Every result item MUST have `hostname` and `error` fields. Single-target returns
+1 result; broadcast returns N results. Failed/skipped agents appear as entries
+with `error` set.
+
+**Handler pattern:**
+
+```go
+func (s *Handler) PostOperation(ctx, request) {
+    validate(request)
+    hostname := request.Hostname
+    if job.IsBroadcastTarget(hostname) {
+        return s.postOperationBroadcast(ctx, hostname, ...)
+    }
+    // Single-target: wrap in collection with 1 result.
+}
+```
+
+**Job client** — the `JobClient` interface has 4 generic methods: `Query`,
+`QueryBroadcast`, `Modify`, `ModifyBroadcast`. Handlers call these with a
+category string and operation constant. No new methods are needed when adding
+operations. Example:
+
+```go
+jobID, resp, err := s.JobClient.Modify(
+    ctx, hostname, "node", job.OperationSysctlCreate, data)
+```
+
+Read existing handlers in the codebase for reference.
+
+## Step 3: Handler Registration
+
+Each domain package exports a `Handler()` function that creates the handler,
+wraps it with auth middleware, and returns route registration closures. No
+changes to the `Server` struct are needed.
+
+Create `handler.go` in your domain package:
+
+```go
+// internal/controller/api/node/{domain}/handler.go
+package {domain}
+
+func Handler(
+    logger *slog.Logger,
+    jobClient client.JobClient,
+    signingKey string,
+    customRoles map[string][]string,
+) []func(e *echo.Echo) {
+    var tokenManager api.TokenValidator = authtoken.New(logger)
+    h := New(logger, jobClient)
+    strictHandler := gen.NewStrictHandler(h,
+        []gen.StrictMiddlewareFunc{
+            func(handler strictecho.StrictEchoHandlerFunc,
+                _ string,
+            ) strictecho.StrictEchoHandlerFunc {
+                return api.ScopeMiddleware(
+                    handler, tokenManager, signingKey,
+                    gen.BearerAuthScopes, customRoles,
+                )
+            },
+        },
+    )
+    return []func(e *echo.Echo){
+        func(e *echo.Echo) {
+            gen.RegisterHandlers(e, strictHandler)
+        },
+    }
+}
+```
+
+Add a `handler_public_test.go` that tests route registration and middleware
+execution. Follow existing domain handler tests.
+
+## Step 4: Startup Wiring
+
+- `cmd/controller_setup.go` — add one line to `registerControllerHandlers`:
+  ```go
+  handlers = append(handlers,
+      {domain}API.Handler(log, jc, signingKey, customRoles)...)
+  ```
+  Add the import for your domain package.
+
+## Step 5: Update SDK
+
+The SDK client library lives in `pkg/sdk/client/`. Its generated HTTP client
+uses the same combined OpenAPI spec as the server
+(`internal/controller/api/gen/api.yaml`). Follow the rules in the
+[SDK Development Guidelines](../sdk/guidelines.md) — especially: never expose
+`gen` types in public method signatures, add JSON tags to all result types, and
+wrap errors with context.
+
+**When modifying existing API specs:**
+
+1. Make changes to the domain's `gen/api.yaml` (under `api/node/{domain}/` for
+   node-targeted domains or `api/{domain}/` for controller-only domains)
+2. Run `just generate` to regenerate server code (this also regenerates the
+   combined spec via `redocly join`)
+3. Run `go generate ./pkg/sdk/client/gen/...` to regenerate the SDK client
+4. Update the SDK service wrappers in `pkg/sdk/client/{domain}.go` if new
+   response codes were added
+5. Update CLI switch blocks in `cmd/` if new response codes were added
+
+**When adding a new API domain:**
+
+1. Add a service with four files in `pkg/sdk/client/`:
+   - `{service}.go` — `{Service}Service` struct + methods
+   - `{service}_types.go` — SDK result types + gen→SDK conversions
+   - `{service}_public_test.go` — service method tests
+   - `{service}_types_public_test.go` — conversion function tests Each service
+     gets its own files — do NOT add methods or types to an existing service's
+     files.
+2. Add a field to the `Client` struct in `osapi.go` and wire it in `New()`
+3. Run `go generate ./pkg/sdk/client/gen/...` to pick up the new domain's spec
+   from the combined `api.yaml`
+4. Add an SDK example in `examples/sdk/client/{service}.go` — one file per SDK
+   service (e.g., `hostname.go`, `disk.go`, `ntp.go`). The example file name
+   matches the Client field name in lowercase.
+5. Add an SDK doc page under the appropriate category subdirectory in
+   `docs/docs/sidebar/sdk/client/`. SDK docs are grouped by concern (e.g.,
+   `node-info/`, `system-config/`, `operations/`). Place the new page in the
+   matching group — look at the existing directory structure to find the right
+   one. Use the Client field name as the page title (e.g., `# Power`), NOT the
+   Go struct name. Update `client.md` to add the service to its category table.
+6. Add the new service to the SDK navbar dropdown in `docs/docusaurus.config.ts`
+   under the matching category header. The dropdown is grouped the same way as
+   the sidebar.
+
+### SDK method naming
+
+Method naming, type exposure, result-field tags, and error handling are
+specified in the `sdk-standards` capability in
+[osapi-io/specs](https://github.com/osapi-io/specs). When a convention here and
+the specification disagree, the specification wins.
+
+### SDK example conventions
+
+SDK examples live in `examples/sdk/client/`, one file per SDK service. Follow
+the same principles as the orchestrator examples:
+
+- **One service per file**: demonstrate the service's SDK operations. Don't mix
+  in other services.
+- **Self-contained**: for read-only operations, just call and print. For
+  mutating operations, cleanup at the start so the example is repeatable.
+- **Print results**: decode and print at least one result so the example isn't
+  silent.
+- **Keep it short**: under ~100 lines of code (excluding license).
+- **Handle errors inline**: use `log.Fatalf` for unexpected errors. For
+  operations that may fail on some platforms, check the error and print a
+  message instead of crashing.
+
+## Step 6: CLI Commands
+
+- `cmd/client_node_{domain}.go` — parent command registered under
+  `clientNodeCmd` (for node-targeted domains)
+- `cmd/client_node_{domain}_{operation}.go` — one subcommand per endpoint (e.g.,
+  `client_node_sysctl_get.go`)
+- All commands support `--json` for raw output
+- Use `cli.PrintKV` for inline key-value output and `cli.PrintCompactTable` for
+  multi-row tabular data (both in `internal/cli/ui.go`)
+- Use flags (e.g., `--job-id`, `--audit-id`) instead of positional args for
+  resource IDs
+- Handle **all** API response codes in the `switch resp.StatusCode()` block:
+  200, 400 (`handleUnknownError`), 401/403 (`handleAuthError`), 404
+  (`handleUnknownError`), 500 (`handleUnknownError`). Match the responses
+  declared in the OpenAPI spec.
+
+## Step 7: Documentation
+
+- `docs/docs/sidebar/features/{domain}-management.md` — feature page. Follow
+  existing feature pages for the template.
+- `docs/docs/sidebar/usage/cli/client/node/{domain}/{domain}.md` — CLI landing
+  page with `<DocCardList />`
+- `docs/docs/sidebar/usage/cli/client/node/{domain}/{verb}.md` — one page per
+  CLI subcommand (e.g., `get.md`, `create.md`, `update.md`)
+- Update `docs/docusaurus.config.ts`:
+  - Add the new feature to the "Features" navbar dropdown
+  - Add the new SDK service to the "SDK" → "Client Library" dropdown
+- Update `docs/docs/sidebar/features/features.md` — add the new domain to the
+  features landing page table
+- Update `docs/docs/sidebar/usage/configuration.md` — add any new permissions to
+  the roles table and permissions comments in the YAML reference
+- Update `docs/docs/sidebar/features/authentication.md` — add new permissions to
+  the roles/permissions tables
+- Update `docs/docs/sidebar/architecture/architecture.md` — add link to the new
+  feature page in the features list
+- Update `docs/docs/sidebar/architecture/api-guidelines.md` — add new endpoints
+  to the path pattern table
+- Update `docs/docs/sidebar/architecture/system-architecture.md` — add endpoints
+  to the health/endpoint tables if applicable
+
+## Step 8: Verify
+
+```bash
+just generate        # regenerate specs + code
+go build ./...       # compiles
+just go-unit        # tests pass
+just go-vet         # lint passes
+```
diff --git a/docs/docs/sidebar/development/contributing.md b/docs/docs/sidebar/development/contributing.md
index 70304f030..73175e15c 100644
--- a/docs/docs/sidebar/development/contributing.md
+++ b/docs/docs/sidebar/development/contributing.md
@@ -4,106 +4,14 @@ sidebar_position: 2
 
 # Contributing
 
-Contributions to OSAPI are very welcome, but we ask that you read this document
-before submitting a PR.
+The contributing guide is [`CONTRIBUTING.md`][contributing] at the root of the
+[OSAPI][] repository. It covers prerequisites, setup, code style, code
+standards, testing, input validation, and the pull request workflow.
 
-:::note
-
-This document applies to the [OSAPI][] repository.
-
-:::
-
-## Before you start
-
-- **Get familiar with the project** - Read through the docs in this order:
-  1. [Development](development.md) - Prerequisites, setup, code style, testing,
-     and commit conventions
-  2. [Guiding Principles](../architecture/principles.md) - Design philosophy and
-     project values
-  3. [System Architecture](../architecture/system-architecture.md) - High-level
-     component overview (REST API, NATS, CLI)
-  4. [API Design Guidelines](../architecture/api-guidelines.md) - REST
-     conventions and endpoint structure
-  5. [Job System Architecture](../architecture/job-architecture.md) - KV-first
-     job processing, subject routing, and agent pipeline
-- **Check existing work** - Is there an existing PR? Are there issues discussing
-  the feature/change you want to make? Please make sure you consider/address
-  these discussions in your work.
-- **Backwards compatibility** - Will your change break existing OSAPI files? It
-  is much more likely that your change will merged if it backwards compatible.
-  Is there an approach you can take that maintains this compatibility? If not,
-  consider opening an issue first so that API changes can be discussed before
-  you invest your time into a PR.
-
-## Making changes
-
-- **Code style** - Follow the conventions described in the
-  [Development](development.md#code-style) guide.
-
-- **Documentation** - Ensure that you add/update any relevant documentation.
-- **Tests** - Ensure that you add/update any relevant tests and that all tests
-  are passing before submitting the PR. See
-  [Development](development.md#testing) for how to run tests.
-
-## UI Contributions
-
-The React management dashboard lives in the `ui/` directory and is embedded into
-the Go binary at build time. See [UI Development](ui-development.md) for
-prerequisites, setup, and code style, and
-[UI Architecture](../architecture/ui.md) for the embedding mechanism, component
-layers, and SDK generation flow.
-
-### Adding new block types
-
-When adding a new operation to the Configure page:
-
-1. Add the `BlockType` entry to `ui/src/hooks/use-stack.ts` in `ALL_BLOCK_TYPES`
-   and the appropriate category.
-2. Add the required permission to `BLOCK_PERMISSIONS` in
-   `ui/src/lib/permissions.ts`.
-3. Create a block form component in `ui/src/components/domain/` if the block
-   needs input fields. Use `SingleInputBlock` for simple single-field blocks.
-4. Add the apply handler case in `ui/src/pages/configure.tsx`.
-5. Add result rendering in `ui/src/components/domain/result-card.tsx` if the
-   response shape isn't handled by existing patterns.
-6. Add the icon mapping in `blockIcons` in `configure.tsx`.
-
-### Adding new UI components
-
-When extracting a new shared component:
-
-1. Create it in `ui/src/components/ui/` with cva variants if applicable.
-2. Accept a `className` prop for escape-hatch styling.
-3. Replace all inline occurrences across the codebase.
-4. Update [UI Architecture](../architecture/ui.md) if the new component is part
-   of the core visual language.
-
-## Submitting a PR
-
-- **Describe your changes** - Ensure that you provide a comprehensive
-  description of your changes.
-- **Issue/PR links** - Link any previous work such as related issues or PRs.
-  Please describe how your changes differ to/extend this work.
-- **Examples** - Add any examples or screenshots that you think are useful to
-  demonstrate the effect of your changes.
-- **Draft PRs** - If your changes are incomplete, but you would like to discuss
-  them, open the PR as a draft and add a comment to start a discussion. Using
-  comments rather than the PR description allows the description to be updated
-  later while preserving any discussions.
-
-## FAQ
-
-> I want to contribute, where do I start?
-
-All kinds of contributions are welcome, whether its a typo fix or a shiny new
-feature. You can also contribute by upvoting/commenting on issues or helping to
-answer questions.
-
-> I'm stuck, where can I get help?
-
-If you have questions, feel free open a [Discussion][] on GitHub.
+That file is the single source, so this page is a pointer rather than a second
+copy of it. GitHub surfaces it when you open an issue or a pull request.
 
 <!-- prettier-ignore-start -->
 [OSAPI]: https://github.com/osapi-io/osapi
-[Discussion]: https://github.com/osapi-io/osapi/discussions
+[contributing]: https://github.com/osapi-io/osapi/blob/main/CONTRIBUTING.md
 <!-- prettier-ignore-end -->
diff --git a/docs/docs/sidebar/development/development.md b/docs/docs/sidebar/development/development.md
index a306d5e10..b0f8edcd3 100644
--- a/docs/docs/sidebar/development/development.md
+++ b/docs/docs/sidebar/development/development.md
@@ -5,250 +5,20 @@ sidebar_label: Overview
 
 # Development
 
-This guide covers the tools, setup, and conventions needed to work on OSAPI.
+Prerequisites, setup, building, code style, code standards, testing, and input
+validation all live in [`CONTRIBUTING.md`][contributing] at the repository root.
 
-## Prerequisites
+That file is the single source, so this page is a pointer rather than a second
+copy of it.
 
-Install tools using [mise][]:
+Two guides remain in this section, because each covers a subject rather than the
+act of contributing:
 
-```bash
-mise install
-```
-
-- **[Go][]** - OSAPI is written in Go. We always support the latest two major Go
-  versions, so make sure your version is recent enough.
-- **[Node.js][]** - Required as a runtime for tools like `@redocly/cli`, for
-  building the Docusaurus docs site, and for building the embedded React UI in
-  `ui/`.
-- **[Bun][]** - JavaScript package manager and script runner used for the
-  Docusaurus docs and the React UI.
-- **[just][]** - Task runner used for building, testing, formatting, and other
-  development workflows. Install with `brew install just`.
-- **[NATS CLI][]** - Command-line tools for interacting with NATS. Useful for debugging
-  and monitoring during development. Install with `brew install nats-io/nats-tools/nats`.
-
-### Claude Code
-
-If you use [Claude Code][] for development, install these plugins from the default
-marketplace:
-
-```
-/plugin install commit-commands@claude-plugins-official
-/plugin install superpowers@claude-plugins-official
-```
-
-- **commit-commands** — provides `/commit` and `/commit-push-pr` slash commands
-  that follow the project's commit conventions automatically.
-- **superpowers** — provides structured workflows for planning, TDD, debugging,
-  code review, and git worktree isolation.
-
-## Setup
-
-Fetch shared justfiles and install all dependencies:
-
-```bash
-just fetch
-just deps
-```
-
-## Code style
-
-Go code should be formatted by [`gofumpt`][gofumpt] and linted using
-[`golangci-lint`][golangci-lint]. Markdown and TypeScript files should be
-formatted and linted by [Prettier][]. This style is enforced by CI.
-
-```bash
-just go-fmt-check   # Check formatting
-just go-fmt         # Auto-fix formatting
-just go-vet         # Run linter
-```
-
-## Running your changes
-
-To run OSAPI with working changes:
-
-```bash
-just build     # Builds React UI + Go binary
-./osapi controller start -f configs/osapi.yaml
-```
-
-:::important
-
-Use `just build` (not `go build` directly). The `//go:embed` directive for the
-UI assets requires `ui/dist/` to be populated at compile time — `just build`
-runs `just react-build` first to satisfy this. The same applies to tests: use
-`just test`, not `go test ./...`.
-
-:::
-
-## UI Development
-
-The embedded React management dashboard has its own development workflow. See
-the [UI Development](ui-development.md) guide for prerequisites, the development
-server (`just react-dev`), code style, and component conventions.
-
-## Documentation
-
-OSAPI uses [Docusaurus][] to host a documentation server. Content is written in
-Markdown and located in the `docs/docs` directory. All Markdown documents should
-have an 80 character line wrap limit. The site is formatted by Prettier through
-the `docusaurus` module; markdown outside it is formatted by mdformat through
-the `md` module.
-
-```bash
-just docusaurus-start     # Start local docs server (requires bun)
-just docusaurus-build     # Build docs for production
-just docusaurus-fmt-check # Check site formatting
-just md-fmt-check         # Check markdown outside the site
-```
-
-## Testing
-
-See the [Testing](testing.md) page for details on running tests and listing just
-recipes.
-
-```bash
-just test           # Run all tests (lint + unit + coverage)
-just go-unit       # Run unit tests only
-just go-unit-int   # Run integration tests (requires running osapi)
-```
-
-Coverage is gated at 99.9%. `just test` fails if total coverage drops below it,
-so a change that adds untested code fails locally and in CI:
-
-```bash
-just go-unit-cov-check   # Report coverage and fail below the target
-```
-
-The target is declared in `.github/codecov.yml` and in the shared `go` justfile
-module — change both together.
-
-Unit tests should follow the Go convention of being located in a file named
-`*_test.go` in the same package as the code being tested. Integration tests are
-located in `test/integration/` and use a `//go:build integration` tag. They
-build and start a real `osapi` binary, so they require no external setup.
-
-Use `testify/suite` with table-driven patterns and `validateFunc` callbacks.
-**One suite method per function under test.** All scenarios for a function
-(success, error codes, transport failures, nil responses) belong as rows in a
-single table — never split into separate `TestFoo`, `TestFooError`,
-`TestFooNilResponse` methods.
-
-### File naming
-
-Avoid generic file names like `helpers.go` or `utils.go`. Name files after what
-they contain.
-
-## Input Validation
-
-All user input is validated through the `internal/validation` package, which
-wraps `go-playground/validator`. Validation rules are declared in OpenAPI specs
-via `x-oapi-codegen-extra-tags` and enforced at runtime by handler calls to
-`validation.Struct()` or `validation.Var()`.
-
-### Config validation
-
-Config struct fields in `internal/config/types.go` use the same `validate` tags.
-Validation runs at startup after `viper.Unmarshal()` — invalid values cause an
-immediate exit with a clear error. Defaults are set via `viper.SetDefault()` in
-`cmd/root.go` so most fields can be omitted. Use `go_duration` for Go duration
-strings. Add `required` to fields with no sensible default.
-
-### Validation rules
-
-- **Required fields** use `validate: "required,..."` — the field must be present
-  and non-zero.
-- **Optional fields** use `validate: "omitempty,..."` — validation is skipped
-  when the field is absent or zero-valued.
-- **Enum constraints** use `validate: "oneof=a b c"` to restrict values.
-- **Cross-field validation** uses `required_without` / `excluded_with` for
-  mutually exclusive fields (e.g., cron `schedule` vs `interval`).
-
-### Update endpoints with all-optional fields
-
-When a PUT endpoint has all optional fields (e.g., user update, group update,
-cron update), use `validation.AtLeastOneField(request.Body)` to reject empty
-bodies with a 400. This prevents clients from sending meaningless no-op updates
-or, worse, triggering destructive defaults. Place this call after
-`validation.Struct()`:
-
-```go
-if errMsg, ok := validation.Struct(request.Body); !ok {
-    return gen.PutXxx400JSONResponse{Error: &errMsg}, nil
-}
-
-if errMsg, ok := validation.AtLeastOneField(request.Body); !ok {
-    return gen.PutXxx400JSONResponse{Error: &errMsg}, nil
-}
-```
-
-### Defense-in-depth pattern
-
-When `validation.Struct()` cannot currently fail (all fields use `omitempty`),
-keep the call with a comment explaining why. This guards against future field
-additions breaking validation silently:
-
-```go
-// Defense in depth: current fields use omitempty so validation
-// always passes, but guards against future field additions.
-if errMsg, ok := validation.Struct(request.Body); !ok {
-    return gen.PostXxx400JSONResponse{Error: &errMsg}, nil
-}
-```
-
-This pattern applies to action endpoints (power, docker stop) where an empty
-body is valid — unlike update endpoints which must use `AtLeastOneField`.
-
-## Before committing
-
-Run `just ready` before committing to ensure generated code, package docs,
-formatting, and lint are all up to date:
-
-```bash
-just ready
-```
-
-## Branching
-
-All changes should be developed on feature branches. Create a branch from `main`
-using the naming convention `type/short-description`, where `type` matches the
-[Conventional Commits][] type:
-
-- `feat/add-retry-logic`
-- `fix/null-pointer-crash`
-- `docs/update-api-reference`
-- `refactor/simplify-handler`
-- `chore/update-dependencies`
-
-When using Claude Code's `/commit` command, a branch will be created
-automatically if you are on `main`.
-
-## Commit messages
-
-Follow [Conventional Commits][] with the 50/72 rule:
-
-- **Subject line**: max 50 characters, imperative mood, capitalized, no period
-- **Body**: wrap at 72 characters, separated from subject by a blank line
-- **Format**: `type(scope): description`
-- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
-- Summarize the "what" and "why", not the "how"
-
-Try to write meaningful commit messages and avoid having too many commits on a
-PR. Most PRs should likely have a single commit (although for bigger PRs it may
-be reasonable to split it in a few). Git squash and rebase is your friend!
+- [UI Development](ui-development.md) — the React dashboard's development
+  server, code style, and component conventions.
+- [Adding an API Domain](adding-an-api-domain.md) — the nine-step walkthrough
+  taking a new domain from provider through to CLI.
 
 <!-- prettier-ignore-start -->
-[mise]: https://mise.jdx.dev
-[Go]: https://go.dev
-[Node.js]: https://nodejs.org/en/
-[Bun]: https://bun.sh
-[just]: https://just.systems
-[Claude Code]: https://claude.ai/code
-[Anthropic Marketplace]: https://marketplace.anthropic.com
-[gofumpt]: https://github.com/mvdan/gofumpt
-[golangci-lint]: https://golangci-lint.run
-[Prettier]: https://prettier.io/
-[Docusaurus]: https://docusaurus.io
-[Conventional Commits]: https://www.conventionalcommits.org
-[NATS CLI]: https://github.com/nats-io/natscli
+[contributing]: https://github.com/osapi-io/osapi/blob/main/CONTRIBUTING.md
 <!-- prettier-ignore-end -->
diff --git a/docs/docs/sidebar/development/testing.md b/docs/docs/sidebar/development/testing.md
index a1e97b7b8..f1a964651 100644
--- a/docs/docs/sidebar/development/testing.md
+++ b/docs/docs/sidebar/development/testing.md
@@ -4,54 +4,20 @@ sidebar_position: 3
 
 # Testing
 
-Install dependencies:
+How to run the unit and integration suites, the coverage gate, and the test
+conventions this repository follows are in [`CONTRIBUTING.md`][contributing]
+under "Testing".
 
-```bash
-$ just deps
-```
-
-## Unit Tests
-
-Unit tests run with mocked dependencies and require no external services:
-
-```bash
-$ just go-unit       # Run unit tests
-$ just go-unit-cov   # Run with coverage report
-$ just test           # Run all checks (lint + unit + coverage)
-```
-
-Unit tests follow the Go convention of being located in `*_test.go` files in the
-same package as the code being tested. Public API tests use the `_test` package
-suffix in `*_public_test.go` files. Public test suites also include HTTP wiring
-methods (`TestXxxHTTP`, `TestXxxRBACHTTP`) that send raw HTTP through the full
-Echo middleware stack with mocked backends.
+That file is the single source, so this page is a pointer rather than a second
+copy of it.
 
-## Integration Tests
-
-Integration tests build a real `osapi` binary, start all three components (NATS,
-API server, agent), and exercise CLI commands end-to-end. They are guarded by a
-`//go:build integration` tag and located in `test/integration/`:
+To list every available recipe, including those from the shared justfile
+modules:
 
 ```bash
-$ just go-unit-int   # Run integration tests
+just --list --list-submodules
 ```
 
-The test harness allocates random ports, generates a JWT, and starts the server
-automatically — no manual setup required. Tests validate JSON responses from CLI
-commands with `--json` output.
-
-## Formatting
-
-Auto format code:
-
-```bash
-$ just go-fmt
-```
-
-## Listing Recipes
-
-List helpful targets:
-
-```bash
-$ just --list --list-submodules
-```
+<!-- prettier-ignore-start -->
+[contributing]: https://github.com/osapi-io/osapi/blob/main/CONTRIBUTING.md
+<!-- prettier-ignore-end -->
diff --git a/docs/docs/sidebar/development/ui-development.md b/docs/docs/sidebar/development/ui-development.md
index ce7f6c481..2dd3f9866 100644
--- a/docs/docs/sidebar/development/ui-development.md
+++ b/docs/docs/sidebar/development/ui-development.md
@@ -122,6 +122,8 @@ just react-lint    # Run ESLint
   pixel values like `text-[10px]`.
 - **Every visual pattern must be a component.** Never duplicate styling with raw
   Tailwind when a component exists.
+- Colors are defined in `ui/src/index.css` via the Tailwind v4 `@theme` block.
+  Never use raw hex values.
 
 ### File naming
 
@@ -129,6 +131,37 @@ just react-lint    # Run ESLint
 - Hooks: `use-kebab-case.ts` (e.g., `use-health.ts`)
 - Utilities: `kebab-case.ts` (e.g., `cn.ts`)
 
+### Vocabulary
+
+A **block** is a single operation — a command, a file deploy, a cron create. A
+**stack** is a saved composition of one or more blocks together with their
+targets. Do not use "runlist"; that term has been replaced.
+
+## Adding a new block type
+
+When adding a new operation to the Configure page:
+
+1. Add the `BlockType` entry to `ui/src/hooks/use-stack.ts` in `ALL_BLOCK_TYPES`
+   and the appropriate category.
+2. Add the required permission to `BLOCK_PERMISSIONS` in
+   `ui/src/lib/permissions.ts`.
+3. Create a block form component in `ui/src/components/domain/` if the block
+   needs input fields. Use `SingleInputBlock` for simple single-field blocks.
+4. Add the apply handler case in `ui/src/pages/configure.tsx`.
+5. Add result rendering in `ui/src/components/domain/result-card.tsx` if the
+   response shape isn't handled by existing patterns.
+6. Add the icon mapping in `blockIcons` in `configure.tsx`.
+
+## Adding a new UI component
+
+When extracting a new shared component:
+
+1. Create it in `ui/src/components/ui/` with cva variants if applicable.
+2. Accept a `className` prop for escape-hatch styling.
+3. Replace all inline occurrences across the codebase.
+4. Update [UI Architecture](../architecture/ui.md) if the new component is part
+   of the core visual language.
+
 ## SDK regeneration
 
 The UI uses a generated TypeScript SDK under `ui/src/sdk/gen/`. When the Go API
diff --git a/ui/docs/contributing.md b/ui/docs/contributing.md
deleted file mode 100644
index f470d760a..000000000
--- a/ui/docs/contributing.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Contributing
-
-Contributions to osapi-ui are very welcome, but we ask that you read this
-document before submitting a PR.
-
-## Before you start
-
-- Read the [Development](development.md) guide for prerequisites, setup, code
-  style, testing, and commit message conventions.
-- **Check existing work** — Is there an existing PR? Are there issues discussing
-  the feature/change you want to make? Please make sure you consider/address
-  these discussions in your work.
-- **Backwards compatibility** — Will your change break existing consumers of
-  osapi-ui? It is much more likely that your change will be merged if it is
-  backwards compatible. Is there an approach you can take that maintains this
-  compatibility? If not, consider opening an issue first so that API changes can
-  be discussed before you invest your time into a PR.
-
-## Making changes
-
-- **Code style** — Follow the conventions described in the
-  [Development](development.md#code-style) guide.
-- **Documentation** — Ensure that you add/update any relevant documentation.
-- **Tests** — Ensure that you add/update any relevant tests and that all tests
-  are passing before submitting the PR. See
-  [Development](development.md#before-committing) for how to verify.
-
-### Adding new block types
-
-When adding a new operation to the Configure page:
-
-1. Add the `BlockType` entry to `src/hooks/use-stack.ts` in `ALL_BLOCK_TYPES`
-   and the appropriate category.
-2. Add the required permission to `BLOCK_PERMISSIONS` in
-   `src/lib/permissions.ts`.
-3. Create a block form component in `src/components/domain/` if the block needs
-   input fields. Use `SingleInputBlock` for simple single-field blocks.
-4. Add the apply handler case in `src/pages/configure.tsx`.
-5. Add result rendering in `src/components/domain/result-card.tsx` if the
-   response shape isn't handled by existing patterns.
-6. Add the icon mapping in `blockIcons` in `configure.tsx`.
-
-### Adding new UI components
-
-When extracting a new shared component:
-
-1. Create it in `src/components/ui/` with cva variants if applicable.
-2. Accept `className` prop for escape-hatch styling.
-3. Update CLAUDE.md and `docs/architecture.md` with the new component.
-4. Replace all inline occurrences across the codebase.
-
-## Submitting a PR
-
-- **Describe your changes** — Ensure that you provide a comprehensive
-  description of your changes.
-- **Issue/PR links** — Link any previous work such as related issues or PRs.
-  Please describe how your changes differ to/extend this work.
-- **Examples** — Add any examples or screenshots that you think are useful to
-  demonstrate the effect of your changes.
-- **Draft PRs** — If your changes are incomplete, but you would like to discuss
-  them, open the PR as a draft and add a comment to start a discussion. Using
-  comments rather than the PR description allows the description to be updated
-  later while preserving any discussions.
-
-## FAQ
-
-> I want to contribute, where do I start?
-
-All kinds of contributions are welcome, whether it's a typo fix or a shiny new
-feature. You can also contribute by upvoting/commenting on issues or helping to
-answer questions.
-
-> I'm stuck, where can I get help?
-
-If you have questions, feel free to open a [Discussion] on GitHub.
-
-[discussion]: https://github.com/osapi-io/osapi-ui/discussions
diff --git a/ui/docs/development.md b/ui/docs/development.md
deleted file mode 100644
index 8ce0e4678..000000000
--- a/ui/docs/development.md
+++ /dev/null
@@ -1,168 +0,0 @@
-# Development
-
-This guide covers the tools, setup, and conventions needed to work on osapi-ui.
-
-## Prerequisites
-
-Install tools using [mise]:
-
-```bash
-mise install
-```
-
-- **[Node.js]** — Required runtime.
-- **[Bun]** — Package manager and script runner.
-- **[just]** — Task runner used for building, testing, formatting, and other
-  development workflows. Install with `brew install just`.
-
-### Claude Code
-
-If you use [Claude Code] for development, install these plugins from the default
-marketplace:
-
-```
-/plugin install commit-commands@claude-plugins-official
-/plugin install superpowers@claude-plugins-official
-```
-
-- **commit-commands** — provides `/commit` and `/commit-push-pr` slash commands
-  that follow the project's commit conventions automatically.
-- **superpowers** — provides structured workflows for planning, TDD, debugging,
-  code review, and git worktree isolation.
-
-## Setup
-
-Fetch shared justfiles and install all dependencies:
-
-```bash
-just fetch
-just deps
-```
-
-## Development server
-
-```bash
-just dev
-```
-
-Opens at `http://localhost:5173`. Hot-reloads on file changes.
-
-## Environment variables
-
-Create a `.env.local` file (gitignored):
-
-```bash
-OSAPI_API_URL=http://localhost:8080
-OSAPI_BEARER_TOKEN=<your-jwt-here>
-```
-
-All env vars use the `OSAPI_` prefix (configured in `vite.config.ts`).
-
-| Variable               | Default                 | Description              |
-| ---------------------- | ----------------------- | ------------------------ |
-| `OSAPI_API_URL`        | `http://localhost:8080` | OSAPI API base URL       |
-| `OSAPI_BEARER_TOKEN`   | (empty)                 | JWT token for auto-login |
-| `OSAPI_FEATURE_STACKS` | `false`                 | Enable saved stacks UI   |
-
-Generate a bearer token with the OSAPI CLI:
-
-```bash
-osapi token generate
-```
-
-If `OSAPI_BEARER_TOKEN` is set, the app auto-authenticates and skips the sign-in
-page. If not set, users paste their token on the sign-in page.
-
-## Code style
-
-TypeScript and CSS should be formatted by [Prettier] and linted using [ESLint].
-This style is enforced by CI.
-
-```bash
-just react-fmt           # Auto-fix formatting
-just react-lint          # Run ESLint
-```
-
-### Component conventions
-
-- One component per file.
-- Use `cva` from class-variance-authority for component variants.
-- Use the `cn()` helper for conditional Tailwind classes.
-- Icons from lucide-react only.
-- No inline styles — Tailwind classes only.
-- Use shared UI primitives (see [Architecture](architecture.md) docs) instead of
-  repeating Tailwind patterns inline.
-- **Always use `Text` for styled text** — never write `text-xs text-text-muted`
-  inline. Use `<Text variant="muted">` instead.
-- Always use the custom `Dropdown` component. Never use native `<select>`.
-- Use Tailwind scale only (`text-xs`, `text-sm`, etc.). Never use arbitrary
-  pixel values like `text-[10px]`.
-
-### File naming
-
-- Components: `kebab-case.tsx` (e.g., `agent-card.tsx`)
-- Hooks: `use-kebab-case.ts` (e.g., `use-health.ts`)
-- Utilities: `kebab-case.ts` (e.g., `cn.ts`)
-
-## SDK regeneration
-
-When the OSAPI Go API changes, copy the combined OpenAPI spec from the osapi
-repo and regenerate the TypeScript SDK:
-
-```bash
-# In the osapi repo, run `just generate` first to produce the combined spec.
-# Then copy it into this repo:
-cp <osapi-repo>/internal/controller/api/gen/api.yaml src/sdk/gen/api.yaml
-
-# Regenerate typed fetch functions from the spec:
-just react-generate
-```
-
-See the [Architecture](architecture.md) docs for the full generation flow.
-
-## Before committing
-
-Run `just ready` before committing to ensure SDK generation, formatting, lint,
-and build are all up to date:
-
-```bash
-just ready   # generate + fmt + lint + build
-```
-
-## Branching
-
-All changes should be developed on feature branches. Create a branch from `main`
-using the naming convention `type/short-description`, where `type` matches the
-[Conventional Commits] type:
-
-- `feat/add-dns-block`
-- `fix/agent-card-overflow`
-- `docs/update-architecture`
-- `refactor/extract-component`
-- `chore/update-dependencies`
-
-When using Claude Code's `/commit` command, a branch will be created
-automatically if you are on `main`.
-
-## Commit messages
-
-Follow [Conventional Commits] with the 50/72 rule:
-
-- **Subject line**: max 50 characters, imperative mood, capitalized, no period
-- **Body**: wrap at 72 characters, separated from subject by a blank line
-- **Format**: `type(scope): description`
-- **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
-- Summarize the "what" and "why", not the "how"
-
-Try to write meaningful commit messages and avoid having too many commits on a
-PR. Most PRs should likely have a single commit (although for bigger PRs it may
-be reasonable to split it in a few). Git squash and rebase is your friend!
-
-[bun]: https://bun.sh
-[claude code]: https://claude.ai/code
-[conventional commits]: https://www.conventionalcommits.org
-[eslint]: https://eslint.org
-[just]: https://just.systems
-[mise]: https://mise.jdx.dev
-[node.js]: https://nodejs.org
-[prettier]: https://prettier.io