From ca33b7031241a942eaa32d228c01ad9b7cc3a031 Mon Sep 17 00:00:00 2001
From: KingKDot <why_are_you_looking_at_this@stoppeeping.com>
Date: Thu, 30 Jul 2026 15:51:58 -0500
Subject: [PATCH] AI has to know ts

---
 AGENTS.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1cdf734
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,109 @@
+# Repository instructions for AI agents
+
+These instructions apply to the entire repository.
+
+## Wire protocol changes
+
+The server and client share a versioned MessagePack contract. Treat
+`protocol/wire-contract.json` as the canonical source of truth. Do not manually
+edit either generated artifact:
+
+- `Overlord-Server/src/generated/wire-contract.ts`
+- `Overlord-Client/cmd/agent/wire/wire_contract_generated.go`
+
+When adding a command or message type, update the appropriate array in
+`protocol/wire-contract.json` in the same change as its implementation.
+
+### Breaking changes to a specific command
+
+A breaking change to an existing command must receive a new command version.
+Never silently change the version 1 payload or semantics.
+
+Changes that require a new command version include:
+
+- removing or renaming a field;
+- changing a field's type, units, default, valid range, or meaning;
+- making a previously optional field required;
+- changing command result or failure semantics.
+
+For the affected command, update `commandVersioning.overrides` in
+`protocol/wire-contract.json`:
+
+1. If the command has no override, add one with `latestVersion: 2`.
+2. If it already has an override, increment `latestVersion` by exactly one.
+3. Add a `changes` entry whose key is the new version.
+4. Set `breaking` to `true` and provide non-empty `summary` and `migration`
+   text describing the wire change and how an older payload maps to the new
+   one.
+5. Keep versions contiguous. Do not delete or rewrite documentation for an
+   already released version.
+
+Example for a command moving from version 1 to version 2:
+
+```json
+"desktop_start": {
+  "latestVersion": 2,
+  "changes": {
+    "2": {
+      "breaking": true,
+      "summary": "Replace numeric quality with a named profile",
+      "migration": "Map quality 1-40 to low, 41-80 to balanced, and 81-100 to high"
+    }
+  }
+}
+```
+
+Implement and retain handlers for every supported version. At target-aware
+server send sites, use `versionCommandForClient` so the server selects the
+highest mutually supported version. Once a command supports multiple versions,
+it must not be encoded without an explicit negotiated `commandVersion`.
+
+Add compatibility tests covering at least:
+
+- the old command version and payload;
+- the new command version and payload;
+- version negotiation with old and new clients;
+- migration or rejection behavior at the compatibility boundary.
+
+Update tests that intentionally assert version ranges, including
+`Overlord-Server/src/protocol-contract.test.ts`,
+`Overlord-Server/src/command-compatibility.test.ts`, and
+`Overlord-Client/cmd/agent/wire/wire_contract_test.go`, when applicable.
+
+### Additive and protocol-wide changes
+
+Adding an optional field without changing existing behavior is additive and
+does not require a command-version bump.
+
+Removing or redefining a non-command wire value, changing message framing or
+encoding, or otherwise breaking the overall wire contract requires incrementing
+`protocolVersion` in `protocol/wire-contract.json`. Preserve compatibility with
+older protocol versions or add an explicit rejection path and tests. Increment
+`schemaVersion` only when the structure of `wire-contract.json` itself changes;
+update `protocol/wire-contract.schema.json` in the same change.
+
+## Generate and verify protocol artifacts
+
+After every edit to `protocol/wire-contract.json`, run these commands from the
+repository root:
+
+```text
+bun scripts/generate-wire-protocol.ts
+bun scripts/generate-wire-protocol.ts --check
+```
+
+Commit the JSON contract and both regenerated artifacts together. Before
+finishing, also run:
+
+```text
+cd Overlord-Server
+bun run typecheck
+bun test src/protocol-contract.test.ts src/command-compatibility.test.ts
+
+cd ../Overlord-Client
+go test ./cmd/agent/wire
+```
+
+Run additional focused tests for every server sender, client handler, and
+payload migration changed by the new command version. Consult
+`protocol/README.md` for the complete compatibility policy.