From 20e944f7d487a55555854a30811ce03df91b026e Mon Sep 17 00:00:00 2001
From: Josh Rzemien <joshua.k.rzemien@gmail.com>
Date: Mon, 23 Feb 2026 16:20:28 -0500
Subject: [PATCH] docs: sync runtime env and security documentation

---
 .env.example                |  6 ++++++
 AGENTS.md                   |  8 ++++++++
 README.md                   | 17 +++++++++++++----
 docs/security-middleware.md |  4 ++--
 4 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/.env.example b/.env.example
index bc7c462..024278c 100644
--- a/.env.example
+++ b/.env.example
@@ -6,6 +6,7 @@ CODEX_SKIP_GIT_CHECK=true
 MCP_CONFIG_PATH=./mcp.config.json
 
 # Anthropic Claude Agent SDK
+# CLAUDE_CODE_OAUTH_TOKEN takes precedence over ANTHROPIC_API_KEY when both are set.
 CLAUDE_CODE_OAUTH_TOKEN=
 ANTHROPIC_API_KEY=
 CLAUDE_MODEL=
@@ -34,6 +35,7 @@ AGENT_PORT_LOCK_DIR=.ai_ops/locks/ports
 AGENT_DISCOVERY_FILE_RELATIVE_PATH=.agent-context/resources.json
 
 # Security middleware
+# AGENT_SECURITY_VIOLATION_MODE: hard_abort | validation_fail
 AGENT_SECURITY_VIOLATION_MODE=hard_abort
 AGENT_SECURITY_ALLOWED_BINARIES=git,npm,node,cat,ls,pwd,echo,bash,sh
 AGENT_SECURITY_COMMAND_TIMEOUT_MS=120000
@@ -42,3 +44,7 @@ AGENT_SECURITY_ENV_INHERIT=PATH,HOME,TMPDIR,TMP,TEMP,LANG,LC_ALL
 AGENT_SECURITY_ENV_SCRUB=
 AGENT_SECURITY_DROP_UID=
 AGENT_SECURITY_DROP_GID=
+
+# Runtime-injected (do not set manually):
+# AGENT_REPO_ROOT, AGENT_WORKTREE_PATH, AGENT_WORKTREE_BASE_REF,
+# AGENT_PORT_RANGE_START, AGENT_PORT_RANGE_END, AGENT_PORT_PRIMARY, AGENT_DISCOVERY_FILE
diff --git a/AGENTS.md b/AGENTS.md
index 2283ebe..f589202 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,6 +47,14 @@
   - `AGENT_SECURITY_ENV_SCRUB`
   - `AGENT_SECURITY_DROP_UID`
   - `AGENT_SECURITY_DROP_GID`
+- Runtime-injected resource context (provided by provisioning; do not set in `.env`):
+  - `AGENT_REPO_ROOT`
+  - `AGENT_WORKTREE_PATH`
+  - `AGENT_WORKTREE_BASE_REF`
+  - `AGENT_PORT_RANGE_START`
+  - `AGENT_PORT_RANGE_END`
+  - `AGENT_PORT_PRIMARY`
+  - `AGENT_DISCOVERY_FILE`
 
 ## Documentation Standards
 - Update `README.md` for user-facing behavior.
diff --git a/README.md b/README.md
index 3d27508..16f6da8 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,6 @@ npm run dev -- claude "List potential improvements."
 `AgentManifest` (schema `"1"`) validates:
 
 - supported topologies (`sequential`, `parallel`, `hierarchical`, `retry-unrolled`)
-- persona definitions and tool-clearance metadata
 - persona definitions and tool-clearance policy (validated by shared Zod schema)
 - relationship DAG and unknown persona references
 - strict pipeline DAG
@@ -130,8 +129,8 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - `OPENAI_API_KEY`
 - `OPENAI_BASE_URL`
 - `CODEX_SKIP_GIT_CHECK`
-- `CLAUDE_CODE_OAUTH_TOKEN` (preferred for Claude auth)
-- `ANTHROPIC_API_KEY`
+- `CLAUDE_CODE_OAUTH_TOKEN` (preferred for Claude auth; takes precedence over `ANTHROPIC_API_KEY`)
+- `ANTHROPIC_API_KEY` (used when `CLAUDE_CODE_OAUTH_TOKEN` is unset)
 - `CLAUDE_MODEL`
 - `CLAUDE_CODE_PATH`
 - `MCP_CONFIG_PATH`
@@ -163,7 +162,7 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 
 ### Security Middleware
 
-- `AGENT_SECURITY_VIOLATION_MODE`
+- `AGENT_SECURITY_VIOLATION_MODE` (`hard_abort` or `validation_fail`)
 - `AGENT_SECURITY_ALLOWED_BINARIES`
 - `AGENT_SECURITY_COMMAND_TIMEOUT_MS`
 - `AGENT_SECURITY_AUDIT_LOG_PATH`
@@ -172,6 +171,16 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - `AGENT_SECURITY_DROP_UID`
 - `AGENT_SECURITY_DROP_GID`
 
+### Runtime-Injected (Do Not Configure In `.env`)
+
+- `AGENT_REPO_ROOT`
+- `AGENT_WORKTREE_PATH`
+- `AGENT_WORKTREE_BASE_REF`
+- `AGENT_PORT_RANGE_START`
+- `AGENT_PORT_RANGE_END`
+- `AGENT_PORT_PRIMARY`
+- `AGENT_DISCOVERY_FILE`
+
 Defaults are documented in `.env.example`.
 
 ## Quality Gate
diff --git a/docs/security-middleware.md b/docs/security-middleware.md
index 9dc8eac..092a543 100644
--- a/docs/security-middleware.md
+++ b/docs/security-middleware.md
@@ -7,8 +7,8 @@ This middleware provides a first-pass hardening layer for agent-executed shell c
 ## Components
 
 - `src/security/shell-parser.ts`
-  - Uses `bash-parser` to parse shell scripts and extract command-level data from `Command` and `Word` nodes.
-  - Traverses nested constructs (logical operators, pipelines, subshells, command expansions) so chained commands are fully visible to policy checks.
+  - Uses async `sh-syntax` (mvdan/sh parser) as a hard parser gate before validation.
+  - Performs fail-closed token-level command extraction and blocks unsupported expansions/subshell constructs.
 - `src/security/schemas.ts`
   - Zod schemas for shell policies, tool clearance policies, execution env policy, and security violation handling mode.
 - `src/security/rules-engine.ts`