feat(runtime): add the thin-pointer AGENTS.md agent entry file

claude-templates/AGENTS.md points any harness at protocols.org, the rules locations, and the /name-to-file resolution rule, and tells it to degrade per each rule's documented fallback instead of skipping gates. make install links it to ~/.codex/AGENTS.md (new CODEX_DIR stanza) and install-ai.sh seeds a project-owned copy at bootstrap, never overwriting an existing one. The rulesets root carries a tracked symlink as dogfood. Five new bats tests cover the link idiom and the seeding. This resolves the generic-instruction-file blocker from the runtime spec, and velox picks up the global link on its next session's make install.

2 files changed, 74 insertions, 0 deletions

diff --git a/scripts/tests/install-agents-entry.bats b/scripts/tests/install-agents-entry.bats
new file mode 100644
index 0000000..03343a6
--- /dev/null
+++ b/scripts/tests/install-agents-entry.bats
@@ -0,0 +1,51 @@
+#!/usr/bin/env bats
+# make install must link the runtime-neutral agent entry file (AGENTS.md)
+# into CODEX_DIR so Codex-style harnesses bootstrap from the same
+# protocols/rules/skills the Claude side reads. The thin-pointer shape and
+# the decision trail live in docs/design/2026-07-13-runtime-portability-
+# inventories.org and the generic-agent-runtime task.
+
+setup() {
+    REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+    TMPHOME="$(mktemp -d)"
+}
+
+teardown() {
+    rm -rf "$TMPHOME"
+}
+
+run_install() {
+    make -C "$REPO_ROOT" install \
+        SKILLS_DIR="$TMPHOME/skills" \
+        RULES_DIR="$TMPHOME/rules" \
+        HOOKS_DIR="$TMPHOME/hooks" \
+        CLAUDE_DIR="$TMPHOME/claude" \
+        CODEX_DIR="$TMPHOME/codex" \
+        LOCAL_BIN="$TMPHOME/bin"
+}
+
+@test "install links AGENTS.md into CODEX_DIR" {
+    run run_install
+    [ "$status" -eq 0 ]
+    [ -L "$TMPHOME/codex/AGENTS.md" ]
+    grep -q "protocols.org" "$TMPHOME/codex/AGENTS.md"
+}
+
+@test "install is idempotent on the agent entry (second run skips)" {
+    run run_install
+    [ "$status" -eq 0 ]
+    run run_install
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"skip  AGENTS.md (already linked)"* ]]
+    [ -L "$TMPHOME/codex/AGENTS.md" ]
+}
+
+@test "install warns on a non-symlink AGENTS.md collision and leaves it alone" {
+    mkdir -p "$TMPHOME/codex"
+    echo "hand-written entry" > "$TMPHOME/codex/AGENTS.md"
+    run run_install
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"WARN  AGENTS.md exists and is not a symlink"* ]]
+    [ ! -L "$TMPHOME/codex/AGENTS.md" ]
+    grep -q "hand-written entry" "$TMPHOME/codex/AGENTS.md"
+}
diff --git a/scripts/tests/install-ai.bats b/scripts/tests/install-ai.bats
index 8e91770..a7eb3c0 100644
--- a/scripts/tests/install-ai.bats
+++ b/scripts/tests/install-ai.bats
@@ -149,3 +149,26 @@ EOF
   [ -d "$TEST_HOME/code/pickme/.ai" ]
   [ ! -d "$TEST_HOME/code/skipme/.ai" ]
 }
+
+@test "install-ai: seeds AGENTS.md at the project root" {
+  mkdir -p "$TEST_HOME/code/fresh"
+  (cd "$TEST_HOME/code/fresh" && git init -q)
+
+  run bash "$INSTALL_AI" --gitignore "$TEST_HOME/code/fresh"
+
+  [ "$status" -eq 0 ]
+  [ -f "$TEST_HOME/code/fresh/AGENTS.md" ]
+  grep -q "protocols.org" "$TEST_HOME/code/fresh/AGENTS.md"
+}
+
+@test "install-ai: never overwrites an existing AGENTS.md" {
+  mkdir -p "$TEST_HOME/code/fresh"
+  (cd "$TEST_HOME/code/fresh" && git init -q)
+  echo "project-owned entry file" > "$TEST_HOME/code/fresh/AGENTS.md"
+
+  run bash "$INSTALL_AI" --gitignore "$TEST_HOME/code/fresh"
+
+  [ "$status" -eq 0 ]
+  grep -q "project-owned entry file" "$TEST_HOME/code/fresh/AGENTS.md"
+  ! grep -q "protocols.org" "$TEST_HOME/code/fresh/AGENTS.md"
+}