docs: clarify protocol and release manifest rules

2 files changed, 5 insertions, 54 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 5cc0410d..22e3c771 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,7 +44,7 @@ just test               # cargo nextest + maintenance script tests
 just check              # formatting check + cargo nextest + maintenance script tests
 ```
 
-Default flow: run `just check` before committing.
+Default flow: run `just check` before committing. Do not commit until `just check` passes locally unless Can explicitly accepts a narrower validation for that commit.
 
 Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior to `AppState` or `Workspace`, it should be testable with `AppState::test_new()` and `Workspace::test_new()` — no PTYs.
 
@@ -93,3 +93,7 @@ The release workflow must publish these four assets:
 ```
 
 The app update check and the in-app **What's New** flow both depend on that exact manifest shape.
+
+Do not edit `website/latest.json` during normal feature, fix, or test work. It describes the latest published release binaries, not the current unreleased source tree. The release workflow updates it after release assets are published.
+
+When changing the server/client wire protocol, bump `src/server/protocol.rs::PROTOCOL_VERSION` and update all hardcoded protocol expectations and manual protocol fixtures in tests. Keep protocol test expectations intentionally explicit so compatibility changes are reviewed instead of silently following the constant.
diff --git a/KITTY_GRAPHICS_PRD.md b/KITTY_GRAPHICS_PRD.md
deleted file mode 100644
index 178e81ba..00000000
--- a/KITTY_GRAPHICS_PRD.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Kitty graphics support PRD
-
-## Goal
-
-Herdr should let pane programs use the Kitty graphics protocol without raw passthrough. Each pane remains a normal libghostty-backed terminal. Herdr reads pane-local image state from libghostty, translates it into the composed outer terminal layout, and paints images in the host terminal.
-
-## Non-goals for the first phase
-
-The first phase does not make the headless server/client protocol image-aware. It does not preserve images across detach/reattach. It does not guarantee scrollback image history. It does not support file, temporary-file, or shared-memory image media. It does not support arbitrary non-pane UI images.
-
-## Task 1: local pane graphics
-
-Visible panes in the attached local UI can display Kitty graphics. A hidden workspace or tab may accumulate libghostty image state while hidden; when it becomes visible, herdr repaints the visible placements for that pane. Pane splits, tab bar, sidebar, borders, zoom, and resizing are handled by mapping pane-local viewport coordinates into the outer terminal coordinates.
-
-Acceptance criteria:
-
-- Each visible pane in the active workspace/tab can receive direct Kitty image commands and render the image in its pane.
-- Hidden panes do not paint into the host terminal while hidden.
-- Switching tabs/workspaces clears stale host-terminal images and paints the newly visible pane placements.
-- Resizing, splitting, closing, or zooming panes clears stale placements and repaints from libghostty state.
-- Herdr does not forward raw pane Kitty escape sequences to the outer terminal.
-- Image storage remains pane-local in libghostty and host-terminal image IDs are namespaced by herdr.
-- File, temp-file, and shared-memory media stay disabled.
-
-Implementation shape:
-
-- Bind libghostty Kitty graphics and system APIs used by the embedder.
-- Install a process-global PNG decoder if PNG payload support is enabled.
-- Enable a bounded Kitty image storage limit on pane terminals.
-- Pass real host cell pixel geometry to libghostty resize and PTY resize.
-- After the ratatui text frame is drawn, query visible pane placements, clip to each pane inner rect, and emit host Kitty graphics commands for those placements.
-- Clear herdr-owned host image IDs before repainting to avoid stale images after layout changes.
-
-## Task 2: multiplexer-complete graphics
-
-Detached clients, reattached clients, multiple clients, scrollback image history, and client-specific host-terminal caches are supported. This is the hard tmux-class part because herdr must synchronize image state across clients that have independent terminal image caches.
-
-Acceptance criteria:
-
-- A newly attached client receives enough image metadata/data to reconstruct the current visible placements without waiting for the pane app to redraw.
-- Multiple attached clients can render the same pane image state with separate host-terminal image ID namespaces.
-- Scrolling a pane moves, clips, hides, and reveals images consistently with text scrollback.
-- Hidden tabs/workspaces retain state without leaking host-terminal images into visible clients.
-- Server/client protocol has explicit image messages or an equivalent terminal-graphics stream with size limits and cache lifecycle.
-- Images are deleted when panes close, workspaces disappear, clients detach, or host-terminal geometry invalidates placements.
-
-Implementation shape:
-
-- Extend the headless protocol beyond `FrameData` cells to carry image descriptors and payloads or pre-encoded Kitty graphics commands.
-- Track per-client image caches and ID allocation.
-- Add viewport-aware image rendering for scrollback, including virtual/placeholder placements if required.
-- Add backpressure and size limits for large images.
-- Add tests around tab switches, detach/reattach, multiple clients, and scrollback.