diff --git a/ahk/README.md b/ahk/README.md
new file mode 100644
index 0000000..149629e
--- /dev/null
+++ b/ahk/README.md
@@ -0,0 +1,36 @@
+# ahk/ — Game-console AutoHotkey bridge
+
+This folder is the home for the **AutoHotkey scripts** that bridge PQS to the FS
+game console. **The scripts are not yet recovered** — this is a placeholder so
+they land in version control the moment they surface.
+
+## What these scripts do
+
+PQS does not control the pods directly. On the console operator's PC, AutoHotkey
+scripts:
+
+1. Read the plain-text output of PQS endpoints:
+   - [`getFSgame.php`](../getFSgame.php) — next mission's settings, newline-delimited.
+   - [`getFSplayers.php`](../getFSplayers.php) — 16 CSV lines (one per pod slot):
+     `active,callsign,rosterNum,team,unit`.
+2. **Keyboard-inject** those values into the game console UI.
+3. The game console then configures the physical pods.
+
+See [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) §4 "How the mission
+reaches the pods" for full context.
+
+## Why this matters
+
+The **real output contract** of `getFSgame.php` / `getFSplayers.php` (exact field
+order, line count, delimiters, timing) is defined by these scripts — not by the
+PHP, which can only be *inferred*. Recovering them is a prerequisite before
+changing anything about how missions reach the pods.
+
+## When you recover the scripts
+
+- Drop the `.ahk` file(s) here.
+- Note which machine they ran on and how they were launched (startup, hotkey,
+  scheduled, manual).
+- Record the AutoHotkey version (v1 vs v2 syntax differ significantly).
+- Document, from the script, the exact expected layout of each `getFS*.php`
+  response so the contract is captured even if the game console changes.