From e1e1c86c84de58f465a66491565f974ace0a176c Mon Sep 17 00:00:00 2001
From: "black.terminal" <64269417+subkoks@users.noreply.github.com>
Date: Fri, 3 Jul 2026 22:21:09 +0100
Subject: [PATCH] docs(codex): add repo-level Codex guidance

---
 .codex/config.toml |  5 +++++
 .gitignore         |  5 +++++
 AGENTS.md          | 21 +++++++++++++++++++++
 README.md          |  4 ++++
 4 files changed, 35 insertions(+)
 create mode 100644 .codex/config.toml
 create mode 100644 AGENTS.md

diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 0000000..871c290
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,5 @@
+# Repo-local Codex defaults for this workspace.
+
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+allow_login_shell = true
diff --git a/.gitignore b/.gitignore
index fae3a9e..e8ab2bb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,8 @@ build/
 # Claude Code (commit shared settings; ignore machine-local perms + transcripts)
 .claude/*
 !.claude/settings.json
+
+# Codex CLI
+!.codex/
+.codex/*
+!.codex/config.toml
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b59396b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,21 @@
+# AGENTS.md
+
+Repo-specific instructions for Codex CLI and other agents working in this repository.
+
+## Scope
+
+- This repo ships security skills, an auditor agent, and install/update scripts.
+- Read `README.md` and `CLAUDE.md` before editing.
+- Keep changes small and security-focused. Prefer updating the canonical skill/agent source over generated outputs.
+
+## Operating rules
+
+- Feature branches only; one logical change per commit.
+- Keep the security auditor read-only by default.
+- Preserve the SSH-only remote policy documented in `CLAUDE.md`.
+- Use repo-local `.codex/config.toml` for Codex workspace defaults.
+
+## Codex CLI notes
+
+- Codex CLI should treat this file as the repo guidance source.
+- If a change affects generated skill or agent artifacts, update the canonical source under `skills/` or `agents/`, not the downstream mirror.
diff --git a/README.md b/README.md
index ee46138..d2cc0fc 100644
--- a/README.md
+++ b/README.md
@@ -219,6 +219,10 @@ blackterminal-security/
 
 Uses the standard **SKILL.md / agent** package format supported by 30+ AI coding tools.
 
+## Codex CLI
+
+Codex CLI should read the root `AGENTS.md` and use the repo-local `.codex/config.toml` defaults in this workspace.
+
 | Tool | Skills | Subagent | Notes |
 |------|--------|----------|-------|
 | Claude Code | ✅ | ✅ | Full skill + agent support |