docs(configuration,reference): refresh for 0.66.2

[edspencer]

Docs last had a systematic pass at v0.62; main is 0.66.2. This is the
configuration/ + reference/ slice of a coordinated five-way refresh.
Docs only — no changeset, no version bump.

Every claim below was re-verified against source before editing.

The two that told readers a shipped capability does not exist

headers / type: sse are carried. herdctl 5.32.0 widened McpServerSchema
and Paddock shipped it in 0.63.0 (#705). Four blocks across two pages still
described the 0.62 behaviour — that headers is stripped (breaking the OAuth
token hash, which is keyed on {type, url, headers}) and that every url server
is downgraded to HTTP. Both are now carried verbatim on both the host-inherit
path and the declared mcpServers: path, and nothing produces a degraded
caveat any more. The "What cannot be declared" list is rewritten around the
refusals that actually remain: an unrecognised key, both command and url or
neither, headers on a non-url server, a type that disagrees with the
declaration, and a reserved name.
(claude-mcp.ts:74-99, :207-233; mcp-servers.ts:79-83, :146, :306-321,
:388-415.)

Host plugin inheritance exists. Shipped in 0.63.0 and documented as not
existing — "inert today", "none of them reach Paddock", "the engine also has no
way to pass a plugin path per session". Every clause is false. Replaced with the
three-row truth table from the source, plus why the symlink alone never worked
(a session plugin is enabled by default, no settings-source grant needed) and the
mcp__plugin_<plugin>_<server>__* allow-list widening.
(claude-plugins.ts:31-56, :375-430; herdctl-agent-config.ts:189.)

Then

The Config screen's DTO (0.66.2, #757/#722/#723) — instance-settings.md
described one always-on banner and a write with no concurrency story. Added: the
three banner states, value vs pendingValue vs pendingRestart,
configVersion → expectedVersion → 409 config_conflict, the 400 on an
env-shadowed write, and that a save stamps schemaVersion: 1 when absent —
which is the mechanism config-file.md already promises.

reference/websocket.md was three frames and several fields behind. Added
chat:queued_state, chat:queued_returned and chat:injected; attachments on
chat:send / chat:set_queue / chat:queued_flushed; qid superseding the
legacy ts; subagentType/description/hasSubagent on both tool frames; the
three hub.broadcast frames missing from the no-seq list. The closing note
asserting "no chat:queued" was actively misleading with four chat:queued_*
frames now in play — replaced with a section on what each one means.

Smaller: fourteen → fifteen paddock_manage tools (3 read + 8 write + 4
trigger) in two places; api.md's auth section named /api/health as the sole
exemption when there are three groups; the /api/root/* mount is now documented
(every workspace route registered once, mounted twice — which is why the root
workspace's key is ""); the two trigger routes hooks.md was missing, on which
it disagreed with schedules.md; /open-api/yaml; a
CLAUDE_SECURESTORAGE_CONFIG_DIR row.

Where the docs are right and the code is wrong

Three filed issues are cited in the pages rather than worked around, so nobody
later "corrects" a page back against a stale type or string:

• chat:injected is emitted but is not a member of the server ServerMessage union — the emit seam is untyped #772 and Web client's mirrored WebSocket frame types have drifted from the server union in both directions — 5 payloads, 5 inline casts hiding it (folds in #772) #773 — reference/websocket.md carries a note that the page
  documents what the server sends, and that neither the ServerMessage union
  nor the web client's mirrored types is a safe source to check it against.
• PADDOCK_SELF_MCP_PROJECTS help text understates its grant: it also gates promote_project, which clones a caller-supplied git URL #775 — configuration/instance-settings.md documents the real
  PADDOCK_SELF_MCP_PROJECTS grant (it also gates promote_project, which
  clones a caller-supplied URL) and flags that the field's own help text
  understates it. The retired "repo-backed" phrasing is dropped from the two
  capability rows in favour of the managed/unmanaged vocabulary self-mcp.md
  already uses.
• The import → adopt rename (#744) is incomplete: paddock --help and the OpenAPI descriptions still say "import" #770 needs nothing here — neither reference/api.md nor
  configuration/openapi.md says anything about the adopt routes' published
  summaries, so the stale "import" wording in the spec has no doc surface in
  this slice.

Left alone, deliberately

The audit's "verified correct" set — port 7233, the claude: block and all
five defaults (credentials is the one host), schemaVersion,
environmentPrompt omitted-vs-empty semantics, the auth exemption list in
authentication.md, bind-safety, the model catalog, chat recovery. Not swept.

cd website && npm run build exits 0. The two caddyfile highlighting warnings
it prints are pre-existing and come from guides/securing.md, outside this slice.

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	83ad8b2
Status:	✅  Deploy successful!
Preview URL:	https://cf230d29.paddock-7u2.pages.dev
Branch Preview URL:	https://docs-configuration-reference.paddock-7u2.pages.dev

View logs