@agentsfleet/orly 0.9.3 → 0.10.0

package/AGENTS.md

@@ -144,7 +144,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | write auth-flow / token-minting files | `write_auth` | `dispatch/write_auth.md` — auth invariants; reads the product repo's `docs/AUTH.md` before · 🟣 delegated (product repo). |
 | write published docs / OpenAPI prose | `write_documentation` | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` before narrower guides; page, fragment, API, changelog scopes differ · 🟣 delegated to repository pre-commit checks. |
 | write a changelog entry | `write_changelog` | `dispatch/write_changelog.md` — changelog voice (one headline, no marketing words, `**Bold lead-noun**` bullets, history append-only); reads `docs/CHANGELOG_VOICE.md` · 🤔 judgment-only. |
-| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; review dispositions; commands with real output. |
+| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; visual evidence from the lane's own artifacts; review dispositions; commands with real output. |
 | claim "tests pass / ready / shipping" | `verify` | `dispatch/verify.md` — verification tiers (`make` canonical; package-scoped runners are **not** verification), done-message glyph format · 🤔 judgment-only, `VERIFY GATE: <target> skipped per environment constraint (reason: ...)` only when genuinely unrunnable. |
 | name a stream/channel/Redis namespace/queue/RPC/Postgres schema, or describe a flow | `name_architecture` | `dispatch/name_architecture.md` — architecture-consult discipline; grep relevant `docs/architecture/` (chat brainstorming counts) · **no override** — doc wins until reconciled. |
 | run a lifecycle stage (open→close a stream, worktree setup, milestone bootstrap) | `lifecycle` | `dispatch/lifecycle.md` — stage runbooks: CHORE(open/close) checklists, PLAN expansions, spec discipline, deferral format, pre-PR gates, LAND · 🤔 judgment-only. |

package/audits/error-codes.sh

@@ -1,60 +1,51 @@
 #!/usr/bin/env bash
-# error-codes.sh — orphan + dead code detection against the canonical
-# error registry at src/agentsfleetd/errors/error_registry.zig, plus a raw-literal check
-# enforcing that UZ-<CAT>-<NNN> strings only appear in registry/allowlist
-# files (every other call site must reference the registry symbol).
+# error-codes.sh — orphan + dead code detection against a repository's canonical
+# error registry, plus a raw-literal check enforcing that <PREFIX>-<CAT>-<NNN>
+# strings only appear in registry/allowlist files (every other call site must
+# reference the registry symbol).
 #
 # Dispatch façade: dispatch/write_any.md (Error Registry Gate)
-# Fires in: CONFORM (via `make harness-verify` in `agentsfleet`).
+# Fires in: CONFORM (via the repository's declared `conform` command).
 #
-# TECHNICAL DEBT (acknowledged on migration to dotfiles, 2026-05-11):
-# The script hard-codes:
-#   - `UZ-` as the error-code prefix (agentsfleet schema)
-#   - `src/agentsfleetd/errors/error_registry.zig` as the canonical registry path
-#   - The raw-literal allowlist below (src/agentsfleetd/errors/**, src/runner/engine/client_errors.zig)
-# A parameterised version that reads prefix + registry path + allowlist
-# from a per-project config (e.g. `.audit-error-codes.toml`) is the right
-# long-term shape; not done yet. Today, this script lives in dotfiles so
-# the gate body and the audit binary stay co-located.
+# WHAT IS CONFIGURED, AND WHY IT IS NOT A PATH IN THIS FILE.
+# This script used to hard-code one repository's registry path, source globs and
+# allowlist. That repository retired the runtime those paths named, and the gate
+# then pointed at nothing — the same silent-green failure the UFS parity check
+# was fixed for. Every one of them is now resolved at run time, and the file
+# names no repository's layout:
+#
+#   ORLY_ERROR_PREFIX     code prefix                (default: UZ)
+#   ORLY_ERROR_REGISTRY   registry file(s), a glob   (default: autodetected)
+#   ORLY_ERROR_SOURCES    where codes may be USED    (default: by runtime)
+#   ORLY_ERROR_ALLOWLIST  extra raw-literal paths    (regex, appended)
+#
+# AUTODETECTION picks the runtime that actually declares codes:
+#   Rust — a file declaring `ErrorCode::declare("<PREFIX>-…")`; sources are the
+#          crate tree's `*.rs`.
+#   Zig  — a file named `error_registry.zig`; sources are `src/**/*.zig`.
+# A repository with neither SKIPS with a reason and exits 0. It does not fail,
+# and it does not pass by scanning nothing and calling that clean.
 #
 # Definitions:
-#   - DECLARED  — every UZ-<CAT>-<NNN> string literal in error_registry.zig
-#   - USED      — every UZ-<CAT>-<NNN> reference in src/**/*.zig (excluding
-#                  the registry itself). agentsfleet/src/** is intentionally
-#                  out of scope — the CLI consumes server-emitted UZ-* codes
-#                  as opaque strings from API responses; the dispatcher's
-#                  typed CliError variants are the CLI's named surface.
+#   - DECLARED  — every <PREFIX>-<CAT>-<NNN> literal in the registry
+#   - USED      — every such reference in the source set, minus the registry
 #   - ORPHAN    — USED but not DECLARED  (BLOCKING)
 #   - DEAD      — DECLARED but not USED  (INFORMATIONAL)
-#   - RAW LEAK  — UZ-<CAT>-<NNN> string literal in a source file outside
-#                  the registry/allowlist (BLOCKING — RULE UFS at the error
-#                  surface; non-allowlisted call sites must use a registry
-#                  symbol, never duplicate the literal).
-#
-# Raw-literal allowlist (files where UZ-* literals are legitimate):
-#   - src/agentsfleetd/errors/**            (canonical registry + entry tables)
-#   - src/runner/engine/client_errors.zig   (the runner engine's own mirror file
-#                                            — see file header for build-module
-#                                            isolation rationale; deliberate
-#                                            duplication, all other executor
-#                                            sources import from there)
-#   - **/*_test.zig                         (tests)
-#   - src/zbench_fixtures.zig               (benchmark fixture seeds)
-#   - src/agentsfleetd/http/test_harness.zig (HTTP test harness)
-#   - lines starting with `//`              (comments)
-#   - lines annotated `// audit-error-codes: intentional-fake`
+#   - RAW LEAK  — a code literal in a source file outside the registry and the
+#                 allowlist (BLOCKING — RULE UFS at the error surface)
 #
-# Tests INCLUDED for orphan detection — same code-registry rules apply to
-# test code. A test referencing a fake code (e.g. UZ-FAKE-999) for
-# negative-path testing must annotate the line:
-# `// audit-error-codes: intentional-fake` and the audit will skip it.
+# Raw-literal allowlist: the registry files themselves, anything test-shaped
+# (`*_test.zig`, `*_test.rs`, a `tests/` directory, a test harness), plus
+# whatever `ORLY_ERROR_ALLOWLIST` adds. Lines starting `//` are comments, and a
+# line annotated `// audit-error-codes: intentional-fake` skips itself and the
+# line below it — which is how a negative test names a code that must not exist.
 #
 # Modes:
 #   --staged   diff-scope: only files in `git diff --cached` are checked
 #              for new orphan refs (registry checked unconditionally)
 #   --all      (default) full repo scan
 #
-# Exits 0 clean, 1 on orphans or raw leaks (DEAD findings never block).
+# Exits 0 clean or skipped, 1 on orphans or raw leaks (DEAD never blocks).
 
 set -euo pipefail
 
@@ -62,8 +53,54 @@ MODE="${1:-${SCOPE:-all}}"
 ROOT="$(git rev-parse --show-toplevel)"
 cd "$ROOT"
 
-REGISTRY="src/agentsfleetd/errors/error_registry.zig"
-[[ -f "$REGISTRY" ]] || { printf "FAIL: registry missing: %s\n" "$REGISTRY" >&2; exit 1; }
+PREFIX="${ORLY_ERROR_PREFIX:-UZ}"
+CODE_RE="${PREFIX}-[A-Z][A-Z0-9]*-[0-9]{3,}"
+
+# Registry files, then the runtime whose sources may reference them. Resolved
+# together: the source set follows from what declares the codes, so a repository
+# cannot end up scanning one runtime's files for another runtime's registry.
+REGISTRY_PATHS=()
+RUNTIME=""
+if [[ -n "${ORLY_ERROR_REGISTRY:-}" ]]; then
+  while IFS= read -r f; do [[ -n "$f" ]] && REGISTRY_PATHS+=("$f"); done < <(
+    git ls-files -- $ORLY_ERROR_REGISTRY 2>/dev/null || true)
+  [[ ${#REGISTRY_PATHS[@]} -gt 0 ]] || {
+    printf "FAIL: ORLY_ERROR_REGISTRY matched no tracked file: %s\n" "$ORLY_ERROR_REGISTRY" >&2
+    exit 1
+  }
+  case "${REGISTRY_PATHS[0]}" in *.rs) RUNTIME=rust ;; *.zig) RUNTIME=zig ;; *) RUNTIME=other ;; esac
+else
+  while IFS= read -r f; do [[ -n "$f" ]] && REGISTRY_PATHS+=("$f"); done < <(
+    git grep -l -E "ErrorCode::declare\(\"${PREFIX}-" -- '*.rs' 2>/dev/null \
+      | grep -vE "_tests?\.rs$|(^|/)tests?/|(^|/)tests?\.rs$" | sort || true)
+  if [[ ${#REGISTRY_PATHS[@]} -gt 0 ]]; then
+    RUNTIME=rust
+  else
+    while IFS= read -r f; do [[ -n "$f" ]] && REGISTRY_PATHS+=("$f"); done < <(
+      git ls-files -- '*error_registry.zig' 2>/dev/null | sort || true)
+    [[ ${#REGISTRY_PATHS[@]} -gt 0 ]] && RUNTIME=zig
+  fi
+fi
+
+if [[ ${#REGISTRY_PATHS[@]} -eq 0 ]]; then
+  printf "OK:   audit-error-codes: skipped — no %s-* registry found, so this repository has no source of truth to compare against\n" "$PREFIX"
+  exit 0
+fi
+
+# Where a code may legitimately be REFERENCED.
+if [[ -n "${ORLY_ERROR_SOURCES:-}" ]]; then
+  SOURCE_GLOB="$ORLY_ERROR_SOURCES"
+elif [[ "$RUNTIME" = "rust" ]]; then
+  SOURCE_GLOB='*.rs'
+else
+  SOURCE_GLOB='*.zig'
+fi
+
+# The registry files are their own allowlist, joined with the test-shaped paths
+# every runtime spells differently, plus whatever the caller adds.
+REGISTRY_RE="$(printf '%s\n' "${REGISTRY_PATHS[@]}" | sed 's|[.[\*^$/]|\\&|g' | paste -sd'|' -)"
+ALLOWLIST_RE="^(${REGISTRY_RE})$|_tests?\\.(zig|rs)$|(^|/)tests?/|(^|/)tests?\\.rs$|/_?test_harness\\.[a-z]+$|_test_fixtures\\.[a-z]+$"
+[[ -n "${ORLY_ERROR_ALLOWLIST:-}" ]] && ALLOWLIST_RE="${ALLOWLIST_RE}|${ORLY_ERROR_ALLOWLIST}"
 
 FAIL=0
 fail() { printf "FAIL: %s\n" "$*" >&2; FAIL=1; }
@@ -78,9 +115,9 @@ note() { printf "NOTE: %s\n" "$*"; }
 #    the entire UZ-UUIDV7-* family (its category ends in a digit), leaving those
 #    codes invisible to the orphan/dead/used passes below.
 # ---------------------------------------------------------------------------
-declared_codes=$(grep -oE 'UZ-[A-Z][A-Z0-9]*-[0-9]{3,}\b' "$REGISTRY" | sort -u)
+declared_codes=$(grep -hoE "${CODE_RE}\b" "${REGISTRY_PATHS[@]}" | sort -u)
 if [[ -z "$declared_codes" ]]; then
-  fail "no codes declared in $REGISTRY (registry empty?)"
+  fail "no codes declared in ${REGISTRY_PATHS[*]} (registry empty?)"
   exit 1
 fi
 declared_count=$(printf '%s\n' "$declared_codes" | wc -l | tr -d ' ')
@@ -93,13 +130,12 @@ declared_count=$(printf '%s\n' "$declared_codes" | wc -l | tr -d ' ')
 gather_used_paths() {
   case "$MODE" in
     --staged|staged)
-      git diff --cached --name-only --diff-filter=ACMRT \
-        | grep -E '^src/' \
-        | grep -vE '^src/agentsfleetd/errors/error_registry\.zig$' || true
+      git diff --cached --name-only --diff-filter=ACMRT -- $SOURCE_GLOB 2>/dev/null \
+        | grep -vE "^(${REGISTRY_RE})$" || true
       ;;
     --all|all)
-      find src -type f -name '*.zig' 2>/dev/null \
-        | grep -vE '^src/agentsfleetd/errors/error_registry\.zig$'
+      git ls-files -- $SOURCE_GLOB 2>/dev/null \
+        | grep -vE "^(${REGISTRY_RE})$" || true
       ;;
     *)
       printf "usage: %s [--staged|--all]\n" "$0" >&2
@@ -117,18 +153,40 @@ if [[ ${#USED_PATHS[@]} -eq 0 ]]; then
   exit 0
 fi
 
-used_codes=$(awk '
+used_codes=$(awk -v prefix="$PREFIX" '
   # Reset per-file so a trailing intentional-fake marker in the previous
   # file cannot carry skip_next=1 into the first line of the next file.
-  FNR == 1 { skip_next = 0 }
+  FNR == 1 { skip_next = 0; in_rs_test = 0; rs_open = 0; rs_depth = 0 }
+  # Rust keeps its unit tests INSIDE the file they cover, under
+  # `#[cfg(test)] mod tests { ... }`, so a negative test naming a code it
+  # expects to be refused reads as a raw literal in the production half of
+  # that same file. Same brace-depth shape as audits/ufs.sh.
+  FILENAME ~ /\.rs$/ {
+    if (in_rs_test) {
+      tmp = $0
+      rs_depth += gsub(/\{/, "{", tmp) - gsub(/\}/, "}", tmp)
+      if (!rs_open && index($0, "{") > 0) rs_open = 1
+      if (rs_open && rs_depth <= 0) in_rs_test = 0
+      next
+    }
+    if ($0 ~ /^[[:space:]]*#\[cfg\(test\)\]/ ||
+        $0 ~ /^[[:space:]]*#\[[A-Za-z_:]*test\]/) {
+      in_rs_test = 1; rs_open = 0; rs_depth = 0
+      next
+    }
+  }
   # Skip the line carrying the marker AND the next non-blank line (the
   # marker sits on the comment line above the code line in Zig style).
   /audit-error-codes: intentional-fake/ { skip_next = 1; next }
+  # A code NAMED in prose is a reference to history, not a call site: Rust doc
+  # comments routinely say which code a path used to return. Skipping them here
+  # matches the raw-literal scan below, which has always skipped comments.
+  /^[[:space:]]*\/\// { next }
   /^[[:space:]]*$/ { next }
   skip_next { skip_next = 0; next }
   {
     line = $0;
-    while (match(line, /UZ-[A-Z][A-Z0-9]*-[0-9][0-9][0-9][0-9]*/)) {
+    while (match(line, prefix "-[A-Z][A-Z0-9]*-[0-9][0-9][0-9][0-9]*")) {
       m = substr(line, RSTART, RLENGTH);
       # Reject codes whose digit run is followed by a word char (rejects
       # placeholder forms like UZ-INTERNAL-00X that grep would truncate).
@@ -153,7 +211,7 @@ used_count=0
 # ---------------------------------------------------------------------------
 orphans=$(comm -23 <(printf '%s\n' "$used_codes") <(printf '%s\n' "$declared_codes") | grep -v '^$' || true)
 if [[ -n "$orphans" ]]; then
-  fail "orphan codes (used but not declared in $REGISTRY):"
+  fail "orphan codes (used but not declared in ${REGISTRY_PATHS[*]}):"
   while IFS= read -r code; do
     [[ -z "$code" ]] && continue
     printf "        %s  refs:\n" "$code" >&2
@@ -188,20 +246,37 @@ fi
 #       2-segment pattern. We don't want a "UZ-X-Y-NNN" code reintroduced
 #      via a local const that the orphan pass silently ignores.
 # ---------------------------------------------------------------------------
-raw_leaks=$(awk '
-  FNR == 1 { skip_next = 0 }
+raw_leaks=$(awk -v prefix="$PREFIX" '
+  FNR == 1 { skip_next = 0; in_rs_test = 0; rs_open = 0; rs_depth = 0 }
+  # Rust keeps its unit tests INSIDE the file they cover, under
+  # `#[cfg(test)] mod tests { ... }`, so a negative test naming a code it
+  # expects to be refused reads as a raw literal in the production half of
+  # that same file. Same brace-depth shape as audits/ufs.sh.
+  FILENAME ~ /\.rs$/ {
+    if (in_rs_test) {
+      tmp = $0
+      rs_depth += gsub(/\{/, "{", tmp) - gsub(/\}/, "}", tmp)
+      if (!rs_open && index($0, "{") > 0) rs_open = 1
+      if (rs_open && rs_depth <= 0) in_rs_test = 0
+      next
+    }
+    if ($0 ~ /^[[:space:]]*#\[cfg\(test\)\]/ ||
+        $0 ~ /^[[:space:]]*#\[[A-Za-z_:]*test\]/) {
+      in_rs_test = 1; rs_open = 0; rs_depth = 0
+      next
+    }
+  }
   # Skip the line carrying the marker AND the next non-blank line.
   /audit-error-codes: intentional-fake/ { skip_next = 1; next }
   /^[[:space:]]*\/\// { next }
   /^[[:space:]]*$/ { next }
   skip_next { skip_next = 0; next }
   # Match any "UZ-XXX(-YYY)*-NNN" string literal.
-  /"UZ-[A-Z][A-Z0-9-]*-[0-9]+"/ {
+  $0 ~ "\"" prefix "-[A-Z][A-Z0-9-]*-[0-9]+\"" {
     print FILENAME ":" FNR ":" $0;
   }
 ' $(printf '%s\n' "${USED_PATHS[@]}" | grep -vE \
-    '^src/agentsfleetd/errors/|/_?test_harness\.zig$|_test\.zig$|^src/runner/engine/client_errors\.zig$|^src/zbench_fixtures\.zig$' \
-    || true) 2>/dev/null || true)
+    "$ALLOWLIST_RE" || true) 2>/dev/null || true)
 
 if [[ -n "$raw_leaks" ]]; then
   fail "raw UZ-* literals found outside the registry allowlist (must reference a registry symbol):"
@@ -215,7 +290,7 @@ fi
 # ---------------------------------------------------------------------------
 # 5. Verdict.
 # ---------------------------------------------------------------------------
-ok "registry: $declared_count declared, $used_count used"
+ok "registry (${RUNTIME:-unknown}): $declared_count declared, $used_count used"
 if [[ $FAIL -ne 0 ]]; then
   printf "\n🔴 ERROR REGISTRY GATE: violations found. Reference the registry symbol (e.g. \`error_codes.ERR_X\` or \`client_errors.ERR_X\` for the executor crate) instead of duplicating the literal.\n" >&2
   exit 1

package/core/operating-model.md

@@ -148,7 +148,7 @@ Guards fire pre-hoc regardless of lifecycle stage. Override: `<GATE>: SKIPPED pe
 | write auth-flow / token-minting files | `write_auth` | `dispatch/write_auth.md` — auth invariants; reads the product repo's `docs/AUTH.md` before · 🟣 delegated (product repo). | <!-- oracle-packs:domain.auth -->
 | write published docs / OpenAPI prose | `write_documentation` | `dispatch/write_documentation.md` → `docs/DOCUMENTATION_RULES.md` before narrower guides; page, fragment, API, changelog scopes differ · 🟣 delegated to repository pre-commit checks. | <!-- oracle-packs:domain.documentation -->
 | write a changelog entry | `write_changelog` | `dispatch/write_changelog.md` — changelog voice (one headline, no marketing words, `**Bold lead-noun**` bullets, history append-only); reads `docs/CHANGELOG_VOICE.md` · 🤔 judgment-only. | <!-- oracle-packs:domain.changelog -->
-| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; review dispositions; commands with real output. | <!-- oracle-packs:universal.authoring -->
+| write/update a PR or MR body or its session notes | `write_pr_description` | `dispatch/write_pr_description.md` — append numbered `Session notes`, `Review`, and `Make`; measured fenced diagrams; visual evidence from the lane's own artifacts; review dispositions; commands with real output. | <!-- oracle-packs:universal.authoring -->
 | claim "tests pass / ready / shipping" | `verify` | `dispatch/verify.md` — verification tiers (`make` canonical; package-scoped runners are **not** verification), done-message glyph format · 🤔 judgment-only, `VERIFY GATE: <target> skipped per environment constraint (reason: ...)` only when genuinely unrunnable. | <!-- oracle-packs:product.agentsfleet -->
 | name a stream/channel/Redis namespace/queue/RPC/Postgres schema, or describe a flow | `name_architecture` | `dispatch/name_architecture.md` — architecture-consult discipline; grep relevant `docs/architecture/` (chat brainstorming counts) · **no override** — doc wins until reconciled. | <!-- oracle-packs:universal.authoring -->
 | run a lifecycle stage (open→close a stream, worktree setup, milestone bootstrap) | `lifecycle` | `dispatch/lifecycle.md` — stage runbooks: CHORE(open/close) checklists, PLAN expansions, spec discipline, deferral format, pre-PR gates, LAND · 🤔 judgment-only. |

package/dispatch/write_pr_description.md

@@ -84,6 +84,37 @@ their numbers:
    0.003-0.005ms        0.1ms        1.0ms      12-21ms
 ```
 
+## Visual evidence
+
+A change to a surface a person looks at, or a failure a picture explains faster
+than a paragraph, carries the picture. A reviewer who can see the wall, the
+dialog or the red run decides in seconds what a description makes them
+reconstruct.
+
+**Take it from what already ran, not from a staged pose.** A lane that failed
+has already produced the image: `gh run download <id> -n <artifact>` yields
+Playwright's `test-failed-*.png`, its `trace.zip` and its `error-context.md`.
+Those are measured evidence of the state under review. A browser driven by hand
+is the fallback, for a surface no lane photographs.
+
+**Screenshot the claim, not the neighbourhood.** One image per assertion, and
+the assertion named in the caption — "one tile, not two" beats "the fleets
+page". Never crop a failure out of a frame that contained it.
+
+**Attaching is the author's step, and say so rather than pretending.** No forge
+accepts an image upload to a pull-request body over its command-line interface;
+`gh` and `glab` both have no such call. So the agent hands the file to the
+person and the person drags it in. What the agent MUST do in the body is make
+the evidence retrievable without the image: name the run id, the artifact and
+the path inside it, and quote the decisive line. A body that says
+`error-context.md:27 records unexpected value "hidden"` survives a screenshot
+nobody attached; a body that says "see screenshot" does not.
+
+**A before/after belongs in a fence, not in two images**, when the difference is
+countable — the diagram rules above already cover it, and a diagram diffs
+better than a pair of pictures. Use images for what only rendering shows:
+alignment, spacing, contrast, what a person actually sees.
+
 ## Review
 
 Lead with the review result. Record every finding with P0, P1, or P2 severity,
@@ -142,6 +173,11 @@ a green pipeline.
 <Useful measured diagram, at most 78 columns.>
 ```
 
+<Visual evidence, when a surface changed or a picture explains a failure:
+each image named with the assertion it carries and with the run, artifact and
+path it came from, plus the decisive line quoted so the claim survives an
+image nobody attached.>
+
 ## Review
 
 <P0/P1/P2 entries with dispositions, No findings., or not-run reason.>

package/docs/REST_API_DESIGN_GUIDELINES.md

@@ -1,7 +1,7 @@
 # REST API Design Guidelines — `agentsfleet/agentsfleetd`
 
 **Status:** Canonical instruction set. Read this before adding, modifying, or removing any HTTP endpoint.
-**Trigger:** the global instruction `HTTP handler or OpenAPI changes → read docs/REST_API_DESIGN_GUIDELINES.md first` fires when the diff touches `src/agentsfleetd/http/handlers/**`, `public/openapi/**`, or any `route_*` file. If you're an agent reading this — you got here because that trigger fired. Follow this doc as a checklist, not as background reading.
+**Trigger:** the global instruction `HTTP handler or OpenAPI changes → read docs/REST_API_DESIGN_GUIDELINES.md first` fires when the diff touches a handler, `public/openapi.json`, or any `route_*` file. If you're an agent reading this — you got here because that trigger fired. Follow this doc as a checklist, not as background reading.
 
 This is a goal-oriented instruction set. Each rule states the goal it serves so you can apply judgment at the edge cases instead of memorizing exceptions.
 
@@ -37,12 +37,12 @@ Run this checklist as part of `CHORE(close)` (per `~/.claude/CLAUDE.md` lifecycl
 - [ ] **Status codes** — 409 includes `current_state`; 412 includes `etag`; 429 includes `Retry-After` + `X-RateLimit-*` (§4)
 - [ ] **ETag/`If-Match`** wired for any resource with realistic concurrent edits (§4)
 - [ ] **Error responses** use the registry; `detail` follows hygiene rules (no IDs, no SQL, no paths, ≤200 chars) (§5)
-- [ ] **OpenAPI YAML** edited under `public/openapi/paths/<tag>.yaml`; tag is 1:1 with resource; file ≤400 lines (§6)
+- [ ] **OpenAPI document** regenerated from the build, not hand-edited; the coverage gate is green (§6)
 - [ ] **Route registered** in all six places (§7)
-- [ ] **Handler signature** matches `inner*(hx: Hx, req: *httpz.Request, ...)` (§8)
+- [ ] **Handler signature** takes only the extractors it reads and returns `Result<Response, Refusal>` (§8)
 - [ ] **Middleware policy** picked from the table; raw handlers carry first-10-lines comment (§7)
 - [ ] **Versioning** — added/renamed/removed surface listed in PR description; deprecation uses `Deprecation` + `Sunset` headers; new response fields declare `x-stability` (§9)
-- [ ] **Tests** — happy path + one error per `hx.fail` + idempotency double-PATCH + `Idempotency-Key` replay (where applicable) + ETag mismatch (§10)
+- [ ] **Tests** — happy path + one error per refusal + idempotency double-PATCH + `Idempotency-Key` replay (where applicable) + ETag mismatch (§10)
 - [ ] **Logging** — sensitive ID values are DEBUG-only or carry `// log-id-allowed:` comment; secret-shaped fields are write-only or one-time-read (§11)
 - [ ] **The repository's declared `verify.unit` command is clean** — the route-scope table's exhaustive match and its tests cover the auth gate matrix (§10)
 - [ ] **No file over 350 lines** (§10)
@@ -90,7 +90,7 @@ Nested paths express the containment relationship. Don't flatten — `/agents?wo
 
 Anything else MUST be modeled as `PATCH /resource/{id}` with a state field. "Convenience" is not a category. If you can't pick one of the three in one sentence, you don't have an operation.
 
-**Collision check** — before adding `POST /v1/.../{id}:verb`, grep the same resource's schema in `public/openapi/components/schemas.yaml` for an existing lifecycle field (`status`, `state`, `stage`, `lifecycle_state`). If one exists AND the new `:verb` would set it to a value that field can already hold, the operation is forbidden — use `PATCH /resource/{id}` body `{status: "<verb>"}` instead. Adding `:approve` when `status` already has an `approved` value is the canonical anti-pattern. The PR description MUST state the result of this grep ("no `status` field on `Approval`" or "`Approval.status` exists but `approved` is not a settable value via PATCH because <reason>").
+**Collision check** — before adding `POST /v1/.../{id}:verb`, grep the same resource's schema in `public/openapi.json` for an existing lifecycle field (`status`, `state`, `stage`, `lifecycle_state`). If one exists AND the new `:verb` would set it to a value that field can already hold, the operation is forbidden — use `PATCH /resource/{id}` body `{status: "<verb>"}` instead. Adding `:approve` when `status` already has an `approved` value is the canonical anti-pattern. The PR description MUST state the result of this grep ("no `status` field on `Approval`" or "`Approval.status` exists but `approved` is not a settable value via PATCH because <reason>").
 
 ### Path-param naming consistency
 
@@ -141,7 +141,6 @@ If the parent ID is in the path, never repeat it in the body.
 
 **Idempotency keys for non-idempotent POSTs.** Any POST that creates a billable, externally-visible, or side-effecting resource MUST accept an `Idempotency-Key` request header (UUIDv7 from the client). The server stores `(workspace_id, key) → response` for at least 24 hours and replays the prior response on duplicate. Endpoints exempt: pure RPC reads, internal-only POSTs. List which endpoints honor the key in the OpenAPI description.
 
-<!-- oracle-packs:start product.agentsfleet -->
 **Owner-approved workspace exception.** `POST /v1/workspaces` accepts no replay
 key. It requires a tenant-unique name and performs one tenant-scoped insert with
 a server-assigned ID. After an uncertain browser response, the dashboard
@@ -149,7 +148,6 @@ refreshes every cursor page from `GET /v1/tenants/me/workspaces`; the
 command-line interface performs one exact-name GET and does not retry the POST.
 A deliberate same-name retry returns 409 and cannot create a second row. Do not
 generalize this exception to other POST endpoints.
-<!-- oracle-packs:end -->
 
 **When in doubt:** if the client supplies the ID and the body fully describes the resource, use PUT. If the server assigns the ID, use POST. If only some fields change, use PATCH.
 
@@ -183,12 +181,10 @@ If you need a different shape, amend this doc first. Do not invent a parallel po
 
 The exact key set is `items`, `total`, `next_cursor` — no synonyms. `results`, `data`, `entries`, `nodes`, `records` are forbidden.
 
-<!-- oracle-packs:start product.agentsfleet -->
 Security-bound exception: `GET /v1/tenants/me/workspaces` also returns the
 authoritative `tenant_id`. Browser and command-line clients persist that value
 with the workspace list so a refreshed identity cannot mix local state from
 two tenants.
-<!-- oracle-packs:end -->
 
 - `items` — always present, always an array. Empty result is `200 {"items": []}` — never `204`.
 - `total` — always present as an `integer | null` field. `null` means "not computed" (page-bounded count would have been too expensive). The OpenAPI schema MUST declare `nullable: true`. Removing the field entirely is forbidden — it forces SDK consumers into branches.
@@ -219,7 +215,7 @@ GET /products?status=active&sort=-created_at&starting_after=01HZQ...&limit=50
   - **Time ranges:** `?created_after=<ts_ms>&created_before=<ts_ms>`. Bracket grammar (`?created_at[gte]=...`) is forbidden.
   - **No boolean explosions.** Don't add `?include_x=true&include_y=true` — use `?include=x,y` with a documented enum of legal values, OR don't expose a knob.
 - **Sorting:** `sort=field` ascending; `sort=-field` descending. Single sort key per request — no multi-key.
-- **Pagination — Stripe-style keyset only.** Request: `?starting_after=<resource_id>&limit=<int>`. Response: `next_cursor: <resource_id> | null` (the field is named `next_cursor` even though the request param is `starting_after`). Cursor encode/decode goes through the shared `src/agentsfleetd/fleet_runtime/keyset_cursor.zig` (`parse()`/`format()`) — mirror `fleets/list.zig`'s usage. `limit` parsing is currently per-handler (no shared query-parsing helper exists yet for this shape); mirror `fleets/list.zig`'s local `parseLimitFromQs`. Default `limit=50`, max `limit=100`. To page forward, send the response's `next_cursor` value back as the next request's `starting_after`. **Forbidden:** page-based `?page=&page_size=` (the `api_keys/list.zig` shape, backed by `pagination.zig::parsePageParams`, is legacy — do not copy it for new endpoints); custom request-side `?cursor=` names (the `approvals/list.zig` keyset shape predates this rule — do not copy it).
+- **Pagination — Stripe-style keyset only.** Request: `?starting_after=<resource_id>&limit=<int>`. Response: `next_cursor: <resource_id> | null` (the field is named `next_cursor` even though the request param is `starting_after`). Cursor encode/decode goes through `afd_core::paging::cursor`, and both the parameter name and the bounds are constants there: `QUERY_STARTING_AFTER`, `DEFAULT_LIMIT` (50) and `MAX_LIMIT` (100). Read the limit through that module rather than parsing the query string in a handler. To page forward, send the response's `next_cursor` value back as the next request's `starting_after`. **Forbidden:** page-based `?page=&page_size=`, and custom request-side `?cursor=` names. Both spellings predate this rule where they survive; do not copy either into a new endpoint.
 - **Sparse fieldsets / `?include=` / `?fields=`:** not supported in v1. If you need to slim a payload, design a smaller endpoint. Don't invent.
 
 ### Bulk operations
@@ -254,15 +250,18 @@ This rule is binding on responses AND requests. SDK consumers branch on `field =
 
 ## §4 — Response shape
 
-### Success — use `hx.ok`
+### Success — return the wire type
 
-```zig
-hx.ok(.ok, .{ .agent_id = id, .status = "active" });
-hx.ok(.created, .{ .agent_id = id, .key = raw_key });
-hx.ok(.accepted, .{ .status = "accepted", .event_id = event_id });
+```rust
+Ok(Json(FleetDetailResponse::from(&detail)).into_response())
+Ok((StatusCode::CREATED, Json(CreatedResponse { id, key })).into_response())
+Ok(StatusCode::NO_CONTENT.into_response())
 ```
 
-The `Hx` helper writes the JSON response with the right status code and content-type. Never call `hx.res.json(...)` directly except for SSE streams (and Slack's "ack-and-drop" pattern).
+The wire type owns the field names and `IntoResponse` writes the status and
+content-type. A response shape belongs in `afd_wire`, not spelled inline in a
+handler, so the same struct is what the OpenAPI document is generated from.
+Build a response by hand only for a Server-Sent Events stream.
 
 ### Status codes
 
@@ -324,15 +323,17 @@ For any resource where concurrent edits are realistic (anything mutable that two
 
 ### Use the error registry
 
-The error-code registry (`src/agentsfleetd/errors/error_entries.zig`) owns the HTTP status, RFC 7807 `title`, and `docs_uri`. Your handler supplies only the code and a human-readable `detail`:
+The error-code registry (`rustd/crates/afd_core/src/error_code.rs` and the family modules beside it) owns the HTTP status, RFC 7807 `title`, and `docs_uri`. Your handler supplies only the code and a human-readable `detail`:
 
-```zig
-hx.fail(ec.ERR_INVALID_REQUEST, "workspace_id must be a valid UUIDv7");
-hx.fail(ec.ERR_FORBIDDEN, "Workspace access denied");
-hx.fail(ec.ERR_AGENT_NOT_FOUND, ec.MSG_AGENT_NOT_FOUND);
+```rust
+Refusal::malformed(DETAIL_WORKSPACE_ID)          // the sentence is a constant
+Refusal::coded(FLEET_NOT_FOUND, DETAIL_NOT_FOUND)
+Refusal::preconditioned(error.code(), error.detail(), current)
 ```
 
-NOT `common.errorResponse(hx.res, "...", "...", req_id)`. NOT `hx.res.status = 400; hx.res.body = "{...}"`.
+Never assemble a `Problem` by hand and never write a status and body directly:
+the status, title and documentation link come from the registry entry, and a
+hand-built body is how two spellings of one error reach clients.
 
 If you need an error code that doesn't exist:
 
@@ -360,7 +361,7 @@ The title must be safe to render verbatim in a UI toast — think "what would I
 5. **Ban list — `detail` MUST NOT contain any of these substrings, even when paraphrased:**
    - Internal table/column names: `pg_`, `pg.`, table names from `schema/*.sql`, column names not exposed in the OpenAPI response.
    - SQL fragments: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `WHERE`, `JOIN`, `CONSTRAINT`, `relation does not exist`, `duplicate key value violates`.
-   - Code internals: `panic`, `unreachable`, `error.`, `.zig`, `src/`, `*.zig` line numbers, file paths starting with `/`, allocator names, struct names from non-public modules.
+   - Code internals: `panic`, `unwrap`, `error.`, a source path, a file extension, a line number, file paths starting with `/`, allocator names, struct names from non-public modules.
    - Stack traces, addresses (`0x...`), thread IDs, request-internal pointer values.
    - Secret-shaped strings: anything matching `sk_`, `pk_`, `Bearer `, `eyJ` (JWT), `op://`, hex blobs >16 chars.
    - Entity values: literal UUIDs, emails, raw bearer tokens, vault key names, file paths from the workspace.
@@ -370,19 +371,19 @@ The title must be safe to render verbatim in a UI toast — think "what would I
    - State: `"<noun> already exists"` / `"<noun> not found"` / `"<noun> expired"` — `Agent name already exists`, `token expired`.
    - Format help: `"<param>: use <format>"` — `invalid_since_format: use Go-style duration (15s, 30m, 2h, 7d) or RFC 3339 (YYYY-MM-DDTHH:MM:SSZ)`.
 
-When you write a new `hx.fail`, find the closest existing call site in `src/agentsfleetd/http/handlers/**` and copy its shape. Don't freelance.
+When you write a new refusal, find the closest existing call site under `rustd/crates/afd_api_*/src/handler/**` and copy its shape. Don't freelance.
 
 ### Internal 500s — direct calls
 
-For DB / pool / operation failures, use the helpers directly:
+A datastore or service failure is not a sentence a handler writes. Lift it with
+`Refusal::at`, naming the operation that failed:
 
-```zig
-common.internalDbUnavailable(hx.res, hx.req_id);   // pool.acquire failed
-common.internalDbError(hx.res, hx.req_id);         // query failed
-common.internalOperationError(hx.res, "detail", hx.req_id);
+```rust
+services.fleet_detail(&context, fleet_id).await.map_err(Refusal::at(FLEET_READ))?
 ```
 
-These are NOT wrapped on `Hx`.
+The operation constant is what identifies the failure in logs and telemetry;
+the caller gets the registry's 500 and no internal detail.
 
 ### Error response body (RFC 7807)
 
@@ -409,150 +410,163 @@ Don't invent other extensions without amending this doc.
 
 ## §6 — OpenAPI editing
 
-The source of truth lives under `public/openapi/`:
+**The document is generated. There is nothing to hand-edit.**
 
-```
-public/openapi/
-├── root.yaml                        # info, servers, tags, security, paths map with $refs
-├── paths/<tag>.yaml                 # one file per tag, hard cap 400 lines — split by sub-resource when exceeded
-└── components/
-    ├── schemas.yaml
-    ├── responses.yaml
-    └── security.yaml
-```
+`public/openapi.json` is emitted from the daemon's own handlers — the route
+table decides the paths and methods, `#[utoipa::path]` beside each handler
+carries the prose and the status codes, and the `afd_wire` types carry the
+schemas. The `public/openapi/` YAML tree this section used to describe was
+retired with the Zig daemon; a hand-edit to the JSON is reverted by the next
+regeneration and fails a test before it gets that far.
 
 ### Adding, renaming, or removing an endpoint
 
-1. Edit the relevant YAML under `public/openapi/paths/<tag>.yaml`.
-2. Add / rename / remove the corresponding `match()` arm in `src/agentsfleetd/http/router.zig`.
-3. Commit YAML + bundled JSON + `router.zig` together. Splitting these across commits leaves CI red.
-
-**Router ↔ openapi.json parity is reviewer-enforced.** There is no mechanical gate cross-checking that every `router.match()` arm has a documented openapi path or vice versa. When you add, rename, or remove a route, both surfaces must move in the same diff and the reviewer must verify it. The previous Python parity gate (`audits/check_openapi_sync.py`) and its data file (`route_manifest.zig`, deleted) were retired in M61_002.
+1. Add, rename or remove the [`Route`] variant and its template, and say which
+   methods it answers in that family's `verbs()`.
+2. Mount it in `rustd/crates/afd_api/src/router/mount.rs`.
+3. Put a `#[cfg_attr(feature = "openapi", utoipa::path(…))]` on the handler and
+   name it in that plane's `src/openapi.rs` collector.
+4. Regenerate and commit the artifact with the code:
 
-**Agent-edit recipe:** see `public/openapi/AGENTS.md` for copy-paste-ready rename / append / remove / update-description workflows.
-
----
-
-## §7 — Registering a route
+   ```bash
+   cd rustd && cargo run -q -p agentsfleetd --features openapi \
+     --bin agentsfleetd -- --no-banner openapi > ../public/openapi.json
+   ```
 
-Six places, in order. Steps 1–5 fail loudly at build/runtime; step 6 is reviewer-enforced — see §6 for the parity rule.
+**Parity is mechanical, not reviewer-enforced.** Three tests grade it, and the
+first is the one that used to be a review obligation:
 
-| Skipped step | Failure mode |
+| Test | What it refuses |
 |---|---|
-| 1 (`Route` variant) | Compile error in `route_table.zig::specFor()` — the `.my_endpoint` arm references an undefined enum variant. |
-| 2 (`match()` arm) | Runtime — your URL returns 404 even though the rest is wired; no compile error. |
-| 3 (`route_table.zig::specFor()`) | Compile error — exhaustive switch on `Route` union is missing your arm. |
-| 4 (`route_scopes.zig::requiredScopes()`) | Compile error — exhaustive switch on `Route` is missing your arm; the route can't be assigned a capability requirement until you do. |
-| 5 (invoke shim) | Compile error — `specFor` references `invoke.invokeMyEndpoint` which doesn't exist. |
-| 6 (OpenAPI YAML) | **No automated check.** Router ↔ openapi.json parity is reviewer-enforced (§6). Reviewer must confirm both surfaces moved in the same diff. |
+| `test_coverage_gate_rust_source` | a served route with no annotation, or an annotation for a route nobody mounts — named with its method and direction |
+| `test_openapi_build_is_the_source` | a committed artifact that is not what the build emits |
+| `test_documented_codes_match_refusals` | an operation that omits a refusal its guard or scope rung guarantees |
 
-If you only see #2's silent-404 failure mode, you've forgotten the matcher even though the route compiles. Test the URL after wiring.
+The prose is graded too: `scripts/check_documentation_rules.py` reads the
+generated document, so a description that breaks the wording rules fails
+`make lint-all`. Fix it at the annotation — or, for a schema description, at the
+`afd_wire` type's doc comment, which is what utoipa publishes. Rationale that is
+for maintainers rather than for API consumers belongs in a `//` comment beside
+it, which the document does not carry.
 
-1. **`src/agentsfleetd/http/routes.zig`** — add a variant to the `Route` union (with path params). `router.zig` re-exports it as `router.Route`; every other consumer imports through that re-export unchanged.
-2. **`src/agentsfleetd/http/router.zig::match()`** — add the path parser that returns your variant.
-3. **`src/agentsfleetd/http/route_table.zig::specFor()`** — map the variant to a `RouteSpec`:
+## §7 — Registering a route
 
-   ```zig
-   .my_endpoint => .{ .middlewares = registry.bearer(), .invoke = invoke.invokeMyEndpoint },
+**The router is built FROM the route table, not beside it.** `Route::all()` is
+walked once at startup and every template it yields is mounted, so a path
+cannot be served under a spelling the table does not carry, and it cannot be
+served under a guard its own row does not declare. Adding an endpoint is
+therefore a table edit plus a handler, in three places.
+
+1. **`rustd/crates/afd_http/src/route/<family>.rs`** — add a variant to the
+   family enum (`FleetRoute`, `TenantRoute`, `AdminRoute`, `WebhookRoute`,
+   `WorkspaceRoute`, `ConnectorRoute`, `RunnerRoute`, `RunnerOpsRoute`,
+   `AuthRoute`, `OpsRoute`) **and to that family's `ALL` array**. `ALL` is what
+   `Route::all()` iterates; a variant missing from it compiles and is never
+   mounted.
+
+2. **The same file's `meta()`** — return a `RouteMeta` for the variant:
+
+   ```rust
+   Self::MyEndpoint => (
+       RouteClass::Api,
+       fleet_path!("/my-endpoint"),
+       Scopes::rw(FLEET_READ, FLEET_WRITE),
+   ),
    ```
 
-4. **`src/agentsfleetd/http/route_scopes.zig::requiredScopes()`** — assign the capability requirement (an empty slice for authenticated-only, or `&NONE`/never-runs for a `none`-policy route):
+   `RouteMeta::new(guard, class, template, scopes)` closes over four of the five
+   facts; the fifth, `ownership`, is derived from the template by
+   `Ownership::of` and is not yours to pass.
 
-   ```zig
-   .my_endpoint => &MY_RESOURCE_WRITE,
-   ```
+3. **The plane crate** — write the handler under
+   `rustd/crates/afd_api_{tenant,operator,ingress,runner}/src/handler/**`, then
+   return it from that plane's `*_handler_for` arm (`fleet_handler_for`,
+   `admin_handler_for`, and their siblings in each plane's `lib.rs`).
+   `afd_api/src/router/mount.rs` dispatches families to planes with a total
+   match, so a new family cannot silently inherit another plane's
+   authentication.
 
-5. **The invoke shim** — add `pub fn invokeMyEndpoint` to `route_table_invoke.zig` or the sibling file for your domain (`route_table_invoke_<domain>.zig`; each keeps `route_table_invoke.zig` under the RULE FLL line cap and is imported + re-exported from there):
+4. **`public/openapi.json`** — add `#[cfg_attr(feature = "openapi", utoipa::path(…))]`
+   beside the handler and regenerate (§6).
 
-   ```zig
-   pub fn invokeMyEndpoint(hx: *Hx, req: *httpz.Request, route: router.Route) void {
-       if (req.method != .POST) { common.respondMethodNotAllowed(hx.res); return; }
-       my_handler.innerMyEndpoint(hx.*, req, route.my_endpoint);
-   }
-   ```
-
-6. **`public/openapi/paths/<tag>.yaml`** — add the endpoint (§6).
-
-### Matcher style — segment-based, not substring-based
-
-All path matchers operate on a canonical `Path` view: a stack-allocated array
-of segments parsed once at the dispatch boundary. The matcher functions
-themselves live in `src/agentsfleetd/http/route_matchers.zig` plus sibling
-per-domain files (`route_matchers_connectors.zig`, `route_matchers_fleet.zig`,
-`route_matchers_runner.zig`, `route_matchers_billing.zig`,
-`route_matchers_webhook.zig`) — same RULE FLL split as the invoke shims.
-Matchers compare by **segment count + segment[i] equality**. Disambiguation is
-shape-driven, not order-driven.
-
-**Pattern (mandatory for any new matcher):**
-
-```zig
-pub fn matchMyEndpoint(p: Path) ?MyRoute {
-    if (p.segs.len != N) return null;        // exact segment count
-    if (!p.eq(0, "literal-1")) return null;  // literal slots
-    if (!p.eq(2, "literal-2")) return null;
-    const id_a = p.param(1) orelse return null;  // path-param slots: param() rejects empty
-    const id_b = p.param(3) orelse return null;
-    return .{ .field_a = id_a, .field_b = id_b };
-}
-```
+| Skipped step | Failure mode |
+|---|---|
+| 1, the enum variant | Compile error — `meta()` is an exhaustive match over the family. |
+| 1, the `ALL` entry | **Silent.** The route compiles, is never walked, and answers 404. Nothing fails. Test the URL after wiring. |
+| 2 (`meta()` arm) | Compile error — the match is not total without it. |
+| 3 (`*_handler_for` arm) | The route is tabled and unmounted, so it answers 404 by design. `handler_for` returning `None` is the honest answer for a verb this binary does not serve; a 501 would claim the endpoint exists here. |
+| 4 (the document) | `test_coverage_gate_rust_source` fails, naming the route, the method and which side is missing it (§6). |
 
-**Banned in new matchers:**
-- `std.mem.startsWith` / `endsWith` / `indexOf` on the path string.
-- Suffix-driven dispatch (`if endsWith(path, "/foo")`).
-- Implicit segment boundaries via offset arithmetic.
-- Reservations encoded as call-site ordering ("must run matcher A before B").
-
-**Required properties of a matcher set:**
-- **Mutual exclusivity by structure.** Any two matchers must be reject-incompatible
-  by segment count or segment-equality predicates. If two matchers can both
-  fire on the same path, one of them needs a tighter predicate (e.g. an explicit
-  `if (p.eq(i, RESERVED)) return null` exclusion). Order in `match()` must not
-  decide correctness.
-- **Empty-segment safety.** `Path.parse` preserves empty segments from `//` and
-  trailing slashes. Matchers extract path-parameter slots via `param(idx)`,
-  which returns null on empty — empty IDs reject at the matcher, not the
-  handler.
-- **Semantic-named typed structs.** Each `Route` enum variant gets its own
-  struct with semantic field names (`credential_name`, `agent_id`, `grant_id`,
-  `memory_key`, `gate_id`, …). Parsing logic may be shared via a private
-  helper, but the public surface stays type-distinct.
-
-**Single API-version site.** The dispatcher in `router.zig::match()` calls
-`Path.parse(...)` once, checks `segs[0]` against the API version, then hands
-`p.tail(1)` to the version-specific matchers (`matchV1`, future `matchV2`).
-The string `"v1"` lives in exactly one place — that dispatch line. No matcher
-body checks the API version.
-
-### Middleware policy table — pick one at step 3
-
-The registry exposes exactly these six policies (`src/agentsfleetd/auth/middleware/mod.zig::MiddlewareRegistry`). Admin/operator capability is no longer a separate policy — it's data in the route→scope table (step 4), enforced by the single `require_scope` middleware that every authenticated chain composes with.
-
-| Policy | Use for |
-|--------|---------|
-| `auth_mw.MiddlewareRegistry.none` | Public endpoint; no auth, OR handler does its own (OAuth/connector callbacks, webhook receivers, Slack events ingress) |
-| `registry.bearer()` | Standard user-facing endpoint; Bearer token or `agt_t` API key + capability gate. The former bearer/admin/operator/platformAdmin chains collapsed into this one policy — `route_scopes.zig::requiredScopes()` decides what the principal must hold |
-| `registry.runnerBearer()` | Runner-token (`agt_r`) machine principal + capability gate; used by the `/v1/runners/me/*` self-plane, which requires `runner:self` |
-| `registry.webhookHmac()` | Approval webhook (HMAC-signed body) |
-| `registry.webhookSig()` | Per-agent HMAC signature for webhooks routed to a fleet (no Bearer fallback) |
-| `registry.svix()` | Svix v1 multi-sig HMAC (Clerk) |
+### Templates are low-cardinality, always
 
-Middleware runs BEFORE your handler: token verification, `hx.principal` population, and 401/403 short-circuits are already done when your `inner*` runs. For `none` policy routes, `hx.principal` is zero-valued — do not read it.
+`RouteMeta.template` is the `http.route` span attribute as well as the mount
+path. It carries `{workspace_id}`, `{fleet_id}` and their siblings as
+parameters and never a concrete value — a real path would put tenant identity
+into span attributes and give the tracing backend one route value per request.
 
-### Raw-handler exceptions
+`matchit`, the router underneath axum, **refuses a literal after a parameter
+inside one segment**, so a custom verb cannot be spelled `{id}:sync`. Where the
+Zig daemon and the shipped clients used that form, the Rust table spells it as
+its own segment (`/schedules/{schedule_id}/sync`) and the change travels with
+its clients in the same diff.
 
-Some endpoints register with the `none` middleware policy (step 3) and verify — or deliberately don't need to verify — inside the handler itself, instead of through a bearer/runner/HMAC chain. Each must carry an explanatory comment at the top of the file:
+### The five facts a route row carries
 
-| File | Reason | Comment |
-|------|--------|---------|
-| `src/agentsfleetd/http/handlers/health.zig` (`healthz`/`readyz`/`metrics`) | Unauthenticated by design — health/metrics | `// unauthenticated — health` (or equivalent) |
-| `src/agentsfleetd/http/handlers/auth/sessions.zig` | Per-function (create/poll/verify public; approve/delete are `registry.bearer()`-authed Clerk JWT, not raw) | per-function comments |
-| `src/agentsfleetd/http/handlers/auth/identity_events_clerk.zig` | Svix-signed `user.created` event, verified inline against `CLERK_WEBHOOK_SECRET` | `// Svix-verified — does not use bearer/HMAC middleware` |
-| `src/agentsfleetd/http/handlers/connectors/callback.zig` (+ provider hooks `src/agentsfleetd/http/handlers/connectors/github/callback.zig`, `src/agentsfleetd/http/handlers/connectors/slack/callback.zig`) | Generic OAuth-callback dispatcher; verifies the signed `state` param inline before delegating to the provider hook | `// OAuth callback — verifies signed state, not bearer` |
-| `src/agentsfleetd/http/handlers/connectors/slack/events.zig` | Slack Events API ingress; Slack v0 request signature only (no Bearer fallback) | `// Slack v0 signature-verified — mirrors the webhook plane` |
-| `src/agentsfleetd/http/handlers/ingress/qstash.zig` | QStash schedule ingress; QStash JSON Web Token signature only (no Bearer fallback) | `// QStash signature-verified — no bearer or generic webhook fallback` |
+| Fact | Type | What it decides |
+|---|---|---|
+| `guard` | `Guard` | What must be presented before a handler runs. |
+| `class` | `RouteClass` | `Ops` never sheds, `Stream` is capped separately because one Server-Sent Events connection is held for minutes, `Api` is subject to the in-flight ceiling. |
+| `template` | `&'static str` | The mount path and the `http.route` attribute. |
+| `scopes` | `Scopes` | `Always(&[…])` for one requirement, or `ByMethod { get, otherwise }` where reads are cheaper than writes. `otherwise` is always the more privileged of the pair, so a method nobody considered can only be refused too often. |
+| `ownership` | `Ownership` | Derived from the template. Which object named in the path must belong to the caller. |
+
+**Ownership is the half of authorization a handler used to have to remember.**
+Capability and ownership are independent questions — may you do this kind of
+thing, and is this particular thing yours. The Zig daemon answered the first in
+its route table and the second by calling `authorizeWorkspace` by hand at the
+top of every workspace handler, where forgetting it was a cross-tenant read
+with nothing failing. Here it is mounted from the route's own template, so
+forgetting is not a thing a handler can do.
+
+### Guard — pick one at step 2
+
+| Guard | Use for |
+|--------|---------|
+| `Guard::Open` | A probe, or a route authenticated by its own payload: the device-flow session endpoints, the connector callback, every webhook. |
+| `Guard::Bearer` | The standard tenant-plane credential — session bearer, `agt_t`, or `afc_`. The capability the principal must hold is the row's `scopes`, not a second guard. |
+| `Guard::RunnerBearer` | A runner-plane credential (`agt_r`). Refused for tenant callers by `afd_auth::Plane`, which is data rather than which router mounted it. |
+| `Guard::WebhookHmac` | An HMAC over the request body, keyed per fleet. |
+| `Guard::WebhookSignature` | The per-fleet webhook signature header. |
+| `Guard::Svix` | A Svix-signed delivery. |
+
+The layers run outside your handler and in a fixed order: **admission**
+outermost, because a shed must stay cheaper than the work it refuses;
+**authentication and the capability gate** next, so a handler never runs for a
+caller who should not reach it; **ownership** innermost, because it is the only
+one of the three that runs a statement. A caller who is over the ceiling or
+short a capability is refused before this daemon reaches Postgres for them.
+
+Each layer is decided while the router is BUILT, not per request: a route that
+is not metered has no admission layer in its stack to consult, and a route with
+no guard has no authenticator in its stack to reach.
+
+### `Guard::Open` routes verify their own callers
+
+An open route is not an unauthenticated one, except for the probes. The proof
+is the body or a signed parameter, which is why it cannot be checked before the
+body is read — and why those routes carry a buffer cap the bearer-proven ones
+do not need.
+
+| Route family | What verifies the caller instead |
+|------|------|
+| `OpsRoute` (`/healthz`, `/readyz`) | Nothing. Unauthenticated by design — an orchestrator that cannot reach these has no other way to ask. |
+| `AuthRoute::{CreateSession, PollSession, VerifySession}` | The device-flow code itself; approve and delete are `Guard::Bearer`. |
+| `WebhookRoute`, every variant | A signature over the body — per-fleet HMAC, the fleet signature header, or Svix. |
+| `ConnectorRoute` callback and events | A signed `state` parameter verified inline before the provider hook runs, or the provider's own request signature. |
 
-If you write a new raw handler, add it to this table AND add a first-10-lines comment in the file explaining why it's registered with `none` and what verifies the caller instead. A `none`-policy handler file lacking either its own verification call OR an explanatory comment in its first 10 lines is a bug — not an oversight.
+A new `Guard::Open` route states in its module documentation what verifies the
+caller instead. One that verifies nothing and says nothing is a bug, not an
+oversight.
 
 ### Reference implementations
 
@@ -560,74 +574,58 @@ When in doubt, mirror an existing handler:
 
 | Pattern | Look at |
 |---------|---------|
-| Simple list/get | `src/agentsfleetd/http/handlers/fleets/list.zig::innerListFleets` |
-| POST with body + validation | `src/agentsfleetd/http/handlers/fleets/create.zig::innerCreateFleet` |
-| DELETE with idempotency | `src/agentsfleetd/http/handlers/fleets/delete.zig::innerDeleteFleet` |
-| Admin-only | `src/agentsfleetd/http/handlers/admin/platform_keys.zig::innerGetAdminPlatformKeys` |
-| Multi-method on one path (GET/POST/PATCH/DELETE) | `src/agentsfleetd/http/handlers/fleets/secrets.zig` |
-| Workspace auth + tenant context | `src/agentsfleetd/http/handlers/workspaces/events.zig::innerListWorkspaceEvents` |
-| Webhook with inline auth | `src/agentsfleetd/http/handlers/webhooks/fleet.zig::innerReceiveWebhook` |
-| Streaming (SSE) | `src/agentsfleetd/http/handlers/fleets/events_stream.zig::innerEventsStream` |
-
----
+| Read, edit and purge one resource | `rustd/crates/afd_api_tenant/src/handler/fleet/detail.rs` |
+| Request parsing and its refusal sentences | `rustd/crates/afd_api_tenant/src/handler/fleet/detail_request.rs` |
+| Keyset pagination | `rustd/crates/afd_api_tenant/src/handler/tenant/models.rs` |
+| Platform plane, operator-held | `rustd/crates/afd_api_operator/src/handler/admin/platform_keys.rs` |
+| Streaming (Server-Sent Events) | `rustd/crates/afd_api_tenant/src/handler/stream.rs` |
+| Signature-proven ingress | `rustd/crates/afd_api_ingress/src/handler/webhook/receive_route.rs` |
+| A runner speaking for itself | `rustd/crates/afd_api_runner/src/handler/runner/lease.rs` |
 
 ## §8 — Handler signature rule
 
-Every HTTP handler in `agentsfleetd` follows this shape. Enforced by the repository's declared `verify.lint` command and by the dispatcher in `src/agentsfleetd/http/server.zig::dispatchMatchedRoute()`, which builds the per-request arena, runs the middleware chain, constructs `Hx`, and calls the route's invoke shim (§7) — a handler never constructs any of this itself.
-
-```zig
-pub fn innerMyEndpoint(hx: Hx, req: *httpz.Request, ...path_params) void {
-    // 1. validate inputs
-    // 2. db / state work (acquire via hx.ctx.pool.acquire(), release via hx.ctx.pool.release())
-    // 3. respond via hx.ok(...) or hx.fail(...)
+A handler is an axum handler. The router built it into a stack that has already
+admitted the request, proven the caller, checked the capability and confirmed
+ownership, so a handler receives what it needs as extractors and constructs
+none of it.
+
+```rust
+pub async fn my_endpoint<D: Services>(
+    State(services): State<Arc<D>>,
+    context: WorkspaceContext,
+    Path(path): Path<FleetPath>,
+    Json(body): Json<MyRequest>,
+) -> Result<Response, Refusal> {
+    // 1. parse and bound the inputs
+    // 2. call the service
+    // 3. return the wire type
 }
 ```
 
 ### Rules
 
-- **Name prefix `inner`** (never `handle`). The `invokeXxx` shim (§7 step 5) is the only public entry — your function is the inner implementation it calls after middleware has populated `hx`.
-- **First parameter: `hx: Hx`** — never `ctx: *Context`, `res: *Response`, `req_id: []const u8`, or an arena allocator. All of those live inside `hx`.
-- **Second parameter: `req: *httpz.Request`** — only if you actually read it (body, query, headers). Drop it if you only need path params.
-- **Path params come after `req`** — order matches the `Route` variant in `routes.zig` (§7 step 1).
-- **Return `void`.** Errors are written to the response; never return a Zig error.
+- **Take what you read, and nothing else.** `State` for services, the auth
+  context for the caller, `Path` for identifiers, `Json` or `Bytes` for a body.
+  A handler that does not read the body does not extract one.
+- **Return `Result<Response, Refusal>`**, or a wire type that implements
+  `IntoResponse`. `Refusal` carries the error code and the sentence; the
+  envelope is built for you.
+- **Bounds are declared on the request type**, with `garde`, not re-spelled per
+  handler. The refusal sentence a field earns is mapped from the path `garde`
+  reports.
+- **Never authenticate inside a handler.** The guard on the route's row did it.
+  Never call an ownership check by hand either; the template mounted it.
+- **Refusal sentences live beside the parser that produces them**, as
+  constants, so the test that asserts one reads it from the same place.
 
 ### What NOT to do
 
-- ❌ `handleMyEndpoint(ctx, req, res)` — old signature; don't add new ones.
-- ❌ Building an `ArenaAllocator` inside the handler — `hx.alloc` is already request-scoped (the dispatcher owns its lifetime).
-- ❌ `common.errorResponse(hx.res, ...)` — use `hx.fail(...)`.
-- ❌ `hx.res.json(body, .{})` or `res.status = 200; res.body = "{}"` — use `hx.ok(.ok, body)`. Acceptable only for SSE streams and Slack ack-and-drop.
-- ❌ Returning a Zig error from the handler — write to `hx.res` and return void.
-
-### `Hx` struct reference
-
-`Hx` is defined in `src/agentsfleetd/http/handlers/hx.zig`. Five fields, passed by value; three methods, each wrapping a distinct wire shape:
-
-```zig
-pub const Hx = struct {
-    alloc:     std.mem.Allocator,       // request-scoped arena, built by the dispatcher
-    principal: common.AuthPrincipal,    // populated by bearer/runner middleware; zero-value for none-policy routes
-    req_id:    []const u8,              // unique request ID
-    ctx:       *common.Context,         // pool, queue, oidc, telemetry, app_url
-    res:       *httpz.Response,         // response writer
-
-    pub fn ok(self: Self, status: std.http.Status, body: anytype) void;      // JSON envelope
-    pub fn fail(self: Self, code: []const u8, detail: []const u8) void;      // RFC 7807 error
-    pub fn noContent(self: Self) void;                                       // spec-compliant empty-body 204
-};
-```
-
-There is no `hx.db()`/`hx.releaseDb()`/`hx.redis()` — acquire the DB pool directly via `hx.ctx.pool.acquire()` / `hx.ctx.pool.release(conn)` (mirror `fleets/list.zig::innerListFleets`); for internal-500s and body-size checks call `common.internalDbError(hx.res, hx.req_id)` etc. directly (§5).
-
-Auth is 100% middleware-chain-driven (§7) — there are no `authenticated()`/`authenticatedWithParam()` comptime wrappers to pick between by path-param count. Every handler, regardless of how many path params it takes, receives its populated `Hx` the same way: the dispatcher builds it after the middleware chain runs and passes it to the invoke shim.
-
-### Guardrails on `hx.zig`
-
-- `hx.zig` stays small — methods are one-liners delegating to `common.zig`. No business logic in `hx.zig`.
-- A new method on `Hx` is justified only when ≥2 in-tree call sites exist **at merge time** — both verifiable by `rg` from `main`. The PR description MUST list both call sites as `path/to/file.zig:line`. "Two handlers will need this soon" is not a justification; ship the second caller in the same PR or keep the helper local.
-- Zero `ArenaAllocator.init` calls in handler files — the dispatcher (`server.zig::dispatchMatchedRoute()`) is the only place that owns the per-request arena's lifetime.
-
----
+- ❌ Reading a query string directly for `limit` or `starting_after` — use
+  `afd_core::paging`.
+- ❌ Building a `Problem` by hand — construct it from the declared error code so
+  the status, title and documentation link come from the registry (§5).
+- ❌ A second unique spelling of a capability check inside the handler body.
+- ❌ Re-parsing a path parameter the extractor already typed.
 
 ## §9 — Versioning
 
@@ -706,7 +704,7 @@ Before opening a PR touching any handler:
 - [ ] Cross-compile: `zig build -Dtarget=x86_64-linux && zig build -Dtarget=aarch64-linux`
 - [ ] the declared `verify.lint` command passes — every language gate the repository declares
 - [ ] Handler file ≤ 350 lines; split if it grows
-- [ ] Integration test covers the happy path AND at least one error path per `hx.fail` call in the handler
+- [ ] Integration test covers the happy path AND at least one error path per refusal the handler can return
 - [ ] PATCH endpoints have an idempotency test: same body issued twice → identical 200 + identical row state. Skip only if the spec's "Failure Modes" explicitly declares non-idempotent PATCH with a reason (§2)
 - [ ] POST endpoints accepting `Idempotency-Key` have a replay test: same key + same body → cached response; same key + different body → 4xx (§2)
 - [ ] Mutable resources have an ETag/`If-Match` test: stale `If-Match` → 412 with current `etag` returned (§4)

package/docs/RULE_ENFORCEMENT.md

@@ -7,14 +7,14 @@ regenerates this file and fails on any difference. To update it, run
 | Rule document | enforced by | judged | acknowledged | classified | trigger |
 |---|---|--:|--:|--:|---|
 | `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 11 | 13 | 30/30 | mechanical |
-| `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/73 | mechanical |
+| `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/65 | mechanical |
 | `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
 | `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/22 | latent |
 | `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
 | `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
 | `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/7 | uncited |
 | `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
-| **corpus** | | | | **30/287** | |
+| **corpus** | | | | **30/279** | |
 
 ## How to read this
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",

package/registry.json

@@ -296,10 +296,6 @@
     "product.agentsfleet": {
       "extensions": [],
       "managed_files": [
-        {
-          "source": "audits/cross-tier-rates.sh",
-          "target": "audits/cross-tier-rates.sh"
-        },
         {
           "source": "audits/design-tokens.sh",
           "target": "audits/design-tokens.sh"

package/audits/cross-tier-rates.sh

@@ -1,105 +0,0 @@
-#!/usr/bin/env bash
-# cross-tier-rates.sh — pin numeric parity of the rate constants
-# across the daemon + three TypeScript surfaces.
-#
-# RULE UFS extension. The shipped billing surface depends on these constants
-# having identical numeric values everywhere they appear:
-#
-#   RUN_NANOS_PER_SEC         — per-second run rate (both postures) in nanos
-#
-# Two free-trial constants were pinned here and are both gone. FREE_TRIAL_END_MS
-# went when the boundary moved onto the tenant row; FREE_TRIAL_STAGE_NANOS went
-# when the trial mechanism was removed outright, because a rate that could
-# silently price a metered slice to zero was worth deleting rather than
-# guarding. The free allowance is wallet credit now — a balance, not a rate —
-# so there is no cross-tier number to pin for it.
-#
-# Files (one definition site per constant per file):
-#
-#   rustd/crates/afd_billing/src/nanos.rs   — server enforces the charge
-#   ui/packages/website/src/lib/rates.ts    — pricing page display
-#   ui/packages/app/lib/types.ts            — dashboard display
-#   cli/src/constants/billing.ts    — `agentsfleet doctor --json` billing block
-#
-# A drift between any two = a billing-display lie or a server-vs-CLI disagreement.
-# The daemon is the source of truth (server enforces); the three TS surfaces echo it.
-#
-# Fires in: make harness-verify, make harness-verify-all.
-# Exits 0 clean, 1 on any drift.
-
-set -euo pipefail
-
-ROOT="$(git rev-parse --show-toplevel)"
-cd "$ROOT"
-
-readonly NAMES=(
-  RUN_NANOS_PER_SEC
-)
-
-readonly FILES=(
-  rustd/crates/afd_billing/src/nanos.rs
-  ui/packages/website/src/lib/rates.ts
-  ui/packages/app/lib/types.ts
-  cli/src/constants/billing.ts
-)
-
-# Extract the numeric value bound to `name` in `file`. Matches definition
-# sites only — `^(pub |export )?const NAME` — not usages elsewhere in the
-# file. Normalises: strips underscores (Zig `1_000_000`, TS `1_000_000`),
-# strips the bigint `n` suffix (TS `1_000_000n`), trims whitespace.
-extract_value() {
-  local file="$1" name="$2"
-  grep -E "^[[:space:]]*(pub |export )?const ${name}\\b" "$file" 2>/dev/null \
-    | head -1 \
-    | sed -E "s|.*=[[:space:]]*||; s|[;,].*||; s|//.*||; s|[[:space:]_n]||g"
-}
-
-FAIL=0
-violations=()
-
-printf "audit-cross-tier-rates: pinning %d constants across %d files\n" \
-  "${#NAMES[@]}" "${#FILES[@]}"
-
-for name in "${NAMES[@]}"; do
-  expected=""
-  expected_file=""
-  for file in "${FILES[@]}"; do
-    if [[ ! -f "$file" ]]; then
-      violations+=("MISSING_FILE: $file")
-      FAIL=1
-      continue
-    fi
-    val="$(extract_value "$file" "$name")"
-    if [[ -z "$val" ]]; then
-      violations+=("MISSING_CONST: $name not defined in $file")
-      FAIL=1
-      continue
-    fi
-    if [[ -z "$expected" ]]; then
-      expected="$val"
-      expected_file="$file"
-      continue
-    fi
-    if [[ "$val" != "$expected" ]]; then
-      violations+=("DRIFT: $name = $val in $file vs $expected in $expected_file")
-      FAIL=1
-    fi
-  done
-  if [[ -n "$expected" ]]; then
-    printf "  OK   %-26s = %s\n" "$name" "$expected"
-  fi
-done
-
-if [[ $FAIL -ne 0 ]]; then
-  printf "\nFAIL: cross-tier rate drift detected:\n" >&2
-  for v in "${violations[@]}"; do
-    printf "  %s\n" "$v" >&2
-  done
-  printf "\nFix: align all four files on the canonical Zig value\n" >&2
-  printf "     (rustd/crates/afd_billing/src/nanos.rs is the server-side enforcer).\n" >&2
-  exit 1
-fi
-
-printf "OK:   all %d rate constants pin across %d files\n" \
-  "${#NAMES[@]}" "${#FILES[@]}"
-exit 0