feat: support hot-updatable agents through the registry

.gitattributes

@@ -1,2 +1,8 @@
 * text=auto eol=lf
 packaging/windows/licenses/* binary
+
+# Preserve the exact source bytes pinned by the registry lock on every platform.
+vendor/agent-registry/** -text
+# The generated index is compared byte-for-byte by the offline registry checker.
+src/agents/bundled.rs text eol=lf
+docs/next/api/herdr-api.schema.json text eol=lf

.github/workflows/distribution.yml

@@ -8,17 +8,20 @@ on:
       - "docs/next/website/**"
       - "docs/preview/**"
       - "docs/versions/**"
-      - "scripts/agent_detection_manifest_check.py"
       - "scripts/config_reference_check.py"
       - "scripts/docs/**"
       - "scripts/docs_translation_parity.py"
       - "scripts/preview.py"
-      - "scripts/test_agent_detection_manifest_check.py"
       - "scripts/test_config_reference_check.py"
       - "scripts/test_docs_translation_parity.py"
       - "scripts/test_preview.py"
-      - "src/detect/manifest_update.rs"
-      - "src/detect/manifests/**"
+      - "src/agents/**"
+      - "scripts/fixtures/agent-registry-snapshot-v1.json"
+      - "vendor/agent-registry/**"
+      - "src/agents/bundled.rs"
+      - "scripts/agent_registry_vendor.py"
+      - "scripts/test_agent_registry_vendor.py"
+      - "src/config/**"
   push:
     branches: [master]
     paths:
@@ -27,17 +30,20 @@ on:
       - "docs/next/website/**"
       - "docs/preview/**"
       - "docs/versions/**"
-      - "scripts/agent_detection_manifest_check.py"
       - "scripts/config_reference_check.py"
       - "scripts/docs/**"
       - "scripts/docs_translation_parity.py"
       - "scripts/preview.py"
-      - "scripts/test_agent_detection_manifest_check.py"
       - "scripts/test_config_reference_check.py"
       - "scripts/test_docs_translation_parity.py"
       - "scripts/test_preview.py"
-      - "src/detect/manifest_update.rs"
-      - "src/detect/manifests/**"
+      - "src/agents/**"
+      - "scripts/fixtures/agent-registry-snapshot-v1.json"
+      - "vendor/agent-registry/**"
+      - "src/agents/bundled.rs"
+      - "scripts/agent_registry_vendor.py"
+      - "scripts/test_agent_registry_vendor.py"
+      - "src/config/**"
 
 permissions:
   contents: read
@@ -67,7 +73,7 @@ jobs:
 
       - name: Validate published contract
         run: |
-          python3 scripts/agent_detection_manifest_check.py --require-published
+          python3 scripts/agent_registry_vendor.py --check
           python3 scripts/config_reference_check.py
           python3 scripts/docs_translation_parity.py --docs-root docs/next/website/src/content/docs
           node scripts/docs/versions.mjs check
@@ -76,7 +82,7 @@ jobs:
       - name: Test contract tooling
         run: |
           python3 -m unittest \
-            scripts.test_agent_detection_manifest_check \
+            scripts.test_agent_registry_vendor \
             scripts.test_config_reference_check \
             scripts.test_docs_translation_parity \
             scripts.test_preview

.github/workflows/release.yml

@@ -185,7 +185,7 @@ jobs:
       - name: Validate release inputs
         run: |
           python3 scripts/changelog.py validate-product-announcement
-          python3 scripts/agent_detection_manifest_check.py --require-all-published
+          python3 scripts/agent_registry_vendor.py --check
           python3 scripts/config_reference_check.py
           node scripts/docs/versions.mjs check
           node scripts/docs/preview.mjs check

.github/workflows/website-deploy.yml

@@ -8,7 +8,6 @@ on:
       - ".github/workflows/website-deploy.yml"
       - "docs/preview/**"
       - "docs/versions/**"
-      - "src/detect/manifests/**"
       - "distribution/**"
 
 permissions:

AGENTS.md

@@ -32,7 +32,7 @@ These instructions are layered.
 - **No god objects.** If a module is doing too many things, split it. `app/` is already split into state, actions, and input. Keep it that way.
 - **Platform code is isolated.** OS-specific behavior lives in the matching `src/platform/<os>.rs` file, with only shared traits, types, wrappers, and testable contracts in `src/platform/mod.rs`. Core modules don't have `#[cfg(target_os)]`.
 - **Detection is decoupled.** The detector reads a screen snapshot, never touches the parser or viewport state.
-- **Screen detection is evidence-based.** When changing `src/detect/manifests/`, first capture the relevant bottom-buffer state with `herdr agent read <pane> --source detection --format text` and, when styling or alternate screen behavior matters, `--format ansi`. Decide which visible controls are invariant, which are alternatives, and encode them as explicit AND/OR gates. Do not match whole-pane incidental text, and do not use the user-visible viewport for agent status because users can scroll it.
+- **Screen detection is evidence-based.** When changing `agents/<canonical-id>/detection.toml` in `herdrdev/agent-registry`, first capture the relevant bottom-buffer state with `herdr agent read <pane> --source detection --format text` and, when styling or alternate screen behavior matters, `--format ansi`. Decide which visible controls are invariant, which are alternatives, and encode them as explicit AND/OR gates. Do not match whole-pane incidental text, and do not use the user-visible viewport for agent status because users can scroll it.
 - **UI patterns should be reused.** Herdr is a mouse-first TUI. New dialogs, onboarding, settings, and post-update flows should follow the existing UI/UX language and interaction patterns instead of inventing one-off screens. Prefer reusing existing modal/screen structure, affordances, and close actions so the app feels consistent.
 
 ### Multiplicative performance paths
@@ -196,11 +196,11 @@ manual testing, reset `C:\work\repo` back to a clean checkout before finishing.
 
 ## Agent Detection Updates
 
-Agent detection changes should use the manifest hot-reload loop. Use the project-local `herdr-throwaway-repro` skill to create a disposable named session and drive the real agent UI through Herdr's CLI/API into the target state. Read the pane with `herdr agent read <pane> --source detection --format text` and inspect matching with `herdr agent explain <pane> --json`. Update the bundled manifest in `src/detect/manifests/<agent>.toml`, copy that manifest to the local override path at `~/.config/herdr/agent-detection/<agent>.toml`, then run `herdr server reload-agent-manifests` against the session under test. Before writing the override, check whether one already exists; never overwrite or remove a pre-existing override without alignment. Once the rule is correct, remove the temporary override or restore the previous one exactly so the committed bundled manifest remains the source of truth.
+Agent detection changes should use the manifest hot-reload loop. Use the project-local `herdr-throwaway-repro` skill to create a disposable named session and drive the real agent UI through Herdr's CLI/API into the target state. Read the pane with `herdr agent read <pane> --source detection --format text` and inspect matching with `herdr agent explain <pane> --json`. Update the source manifest in `agents/<canonical-id>/detection.toml` in the agent registry checkout, copy that manifest to the local override path at `~/.config/herdr/agent-detection/<canonical-id>.toml`, then run `herdr server reload-agent-manifests` against the session under test. Agent folders use registry canonical IDs, including `agy` for Antigravity and `copilot` for GitHub Copilot. Before writing the override, check whether one already exists; never overwrite or remove a pre-existing override without alignment. Once the rule is correct, remove the temporary override or restore the previous one exactly so the registry source remains authoritative. Refresh Herdr's pinned copy with `just agent-registry-sync <registry-checkout>`; do not hand-edit `vendor/agent-registry/`. Builds use only that vendored snapshot and never fetch the registry.
 
 Do not add large agent-specific full-screen fixture suites for routine manifest tuning. Keep Rust tests focused on manifest parsing, rule semantics, skip-state semantics, source precedence, cache reload behavior, and update flow. Use live pane reads for agent-specific screen evidence.
 
-`distribution/agent-detection/` is the remotely published catalog for released clients. Keep changes for already released agents aligned with their bundled manifests unless the validator records an exact compatibility exception. A newly bundled agent that current stable clients cannot identify may remain unpublished behind an exact version-and-digest exception, but it must be added to the catalog and the exception removed before the first stable release that ships it. `just release-docs-check` enforces that no unpublished exceptions remain.
+`distribution/agent-detection/` is a legacy published catalog for released clients. Leave those public assets untouched; do not synchronize them with registry source or add compatibility exceptions. Herdr owns semantic validation (`just agent-registry-validate`); `just agent-registry-check` verifies vendored integrity offline. Reviewed immutable snapshots can be imported offline with `just agent-registry-sync-snapshot <file> <sha256> </absolute/matching/herdr>`; the matching binary validates the exact bytes and compiled integration boundary before the existing rollback-safe vendor path runs. R2 publication remains a separate, explicitly approved operation, never part of normal builds/checks.
 
 ## Vendored libghostty-vt
 

Cargo.toml

@@ -11,8 +11,10 @@ keywords = ["terminal", "tui", "ai", "agents", "multiplexer"]
 categories = ["command-line-utilities"]
 include = [
     "src/**/*",
+    "vendor/agent-registry/**/*",
     "assets/sounds/*",
     "docs/next/api/herdr-api.schema.json",
+    "scripts/fixtures/agent-registry-snapshot-v1.json",
     "skills/herdr/SKILL.md",
     "distribution/install.ps1",
     "README.md",