diff --git a/.claude/skills/upstream-first/SKILL.md b/.agents/skills/upstream-first/SKILL.md
similarity index 100%
rename from .claude/skills/upstream-first/SKILL.md
rename to .agents/skills/upstream-first/SKILL.md
diff --git a/.claude/skills/upstream-first b/.claude/skills/upstream-first
new file mode 120000
index 0000000..1f32bb1
--- /dev/null
+++ b/.claude/skills/upstream-first
@@ -0,0 +1 @@
+../../.agents/skills/upstream-first
\ No newline at end of file
diff --git a/.tangled/workflows/ci.yml b/.tangled/workflows/ci.yml
index 68903c5..71a7d38 100644
--- a/.tangled/workflows/ci.yml
+++ b/.tangled/workflows/ci.yml
@@ -23,7 +23,7 @@ steps:
 
   - name: check formatting
     command: |
-      /tangled/workspace/.zig/zig fmt --check .
+      /tangled/workspace/.zig/zig fmt --check build.zig build.zig.zon src tools/loadgen/build.zig tools/loadgen/build.zig.zon tools/loadgen/src
 
   - name: unit tests (debug)
     command: |
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6be970e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,8 @@
+# stream
+
+Zig port of Jetstream v2. `docs/semantic-parity.md` records what is proved
+against the pinned upstream version.
+
+- For port behavior changes, follow `.agents/skills/upstream-first/SKILL.md`.
+- Run `zig fmt --check build.zig build.zig.zon src tools/loadgen/build.zig tools/loadgen/build.zig.zon tools/loadgen/src`, `zig build test`, `zig build`, and the relevant contract check from `just --list`.
+- Keep deployment and operational claims aligned with `docs/` and verified live state.