3 files changed, 81 insertions, 0 deletions
diff --git a/scripts/install-ai.sh b/scripts/install-ai.sh
index 7007eed..0c90f64 100755
--- a/scripts/install-ai.sh
+++ b/scripts/install-ai.sh
@@ -141,6 +141,13 @@ today="$(date +%Y-%m-%d)"
 sed "s|\[Project Name\]|$project_name|g; s|\[Date\]|$today|g" \
     "$CANONICAL/notes.org" > "$project/.ai/notes.org"
 
+# Seed AGENTS.md — the runtime-neutral agent entry file (thin pointer at
+# protocols.org, rules, and /name resolution) for Codex-style harnesses.
+# Seed-only, like CLAUDE.md: project-owned after bootstrap, never overwritten.
+if [ ! -e "$project/AGENTS.md" ]; then
+  cp "$REPO/claude-templates/AGENTS.md" "$project/AGENTS.md"
+fi
+
 # Tracking setup.
 case "$track_mode" in
   track)
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"
+}