docs: collapse action enums to deny | steer | observe (#35)

* docs: collapse action enums from 5 to 3 (deny, steer, observe)

Update all documentation to reflect the consolidated action types.
Legacy values allow/warn/log are now normalized to observe on input.

* docs: remove backward compatibility notes for legacy action values

Author: lan17

concepts/controls.mdx

@@ -282,15 +282,11 @@ Fields:
 
 - `decision`: The enforcement action to take
 
-  - `"allow"` - Continue execution (useful for allowlist controls)
-
   - `"deny"` - Hard stop execution (blocks the request)
 
   - `"steer"` - Provides corrective guidance to help agents satisfy control requirement
 
-  - `"warn"` - Log a warning but continue execution
-
-  - `"log"` - Log the match for observability only
+  - `"observe"` - Record the match for audit and observability without blocking execution
 
 - `metadata`: Optional additional context (JSON object)
 
@@ -308,12 +304,12 @@ Agent Control uses "deny wins" logic: if **any** enabled control with a `deny` a
 }
 ```
 
-### Example 2: Warn without blocking
+### Example 2: Observe without blocking
 
 ```json
 {
   "action": {
-    "decision": "warn"
+    "decision": "observe"
   }
 }
 ```

concepts/evaluators/built-in-evaluators.mdx

@@ -217,7 +217,7 @@ pip install agent-control-evaluators[galileo]
   }
 }
 
-// Flag potential hallucinations (warn but allow)
+// Flag potential hallucinations (observe, non-blocking)
 {
   "name": "galileo.luna2",
   "config": {

concepts/overview.mdx

@@ -144,7 +144,7 @@ An **Action** defines what happens when a control matches.
 
 2. **Steer second** — if any `steer` control matches (and no deny), steering context is returned.
 
-3. **Allow/warn/log** — observability actions that do not block execution.
+3. **Observe** — non-blocking observability action that does not affect execution.
 
 ## Learn more
 

core/reference.mdx

@@ -70,17 +70,15 @@ Controls → Agents
 |--------|----------|
 | `deny` | Block the request/response, raise `ControlViolationError` |
 | `steer` | Raise `ControlSteerError` with steering context for correction and retry |
-| `allow` | Permit execution (no effect if a `deny` control also matches) |
-| `warn` | Log a warning but allow execution |
-| `log` | Silent logging for monitoring only |
+| `observe` | Record the match for audit and observability without blocking execution |
 
 Priority semantics:
 
 1. **Deny wins** — if any `deny` control matches, execution is blocked.
 
 2. **Steer second** — if any `steer` control matches (and no deny), steering context is returned.
 
-3. **Allow/warn/log** — observability actions that do not block execution.
+3. **Observe** — non-blocking observability action that does not affect execution.
 
 You can read more in [Concepts](/concepts/overview)
 

examples/agent-control-demo.mdx

@@ -104,7 +104,7 @@ Controls are defined on the server with:
 
 - Scope: When to check (step types, stages: pre or post)
 - Condition: What and how to check
-- Action: What to do (allow, deny, steer, warn, log)
+- Action: What to do (deny, steer, observe)
 
 Example from `setup_controls.py`:
 
@@ -160,7 +160,7 @@ Controls can be updated on the server without code changes:
 
 - Enable or disable controls
 - Update patterns and rules
-- Change enforcement decisions (deny to warn)
+- Change enforcement decisions (deny to observe)
 - Add new controls to existing agents
 
 ## Configuration

examples/deepeval.mdx

@@ -480,7 +480,7 @@ You can create specialized evaluators for specific use cases:
 3. **Configuration**: Pydantic models provide type-safe, validated configuration
 4. **Registration**: The `@register_evaluator` decorator handles registration automatically
 5. **Integration**: Evaluators work seamlessly with agent-control's policy system
-6. **Control Logic**: `matched=True` triggers the action (deny/allow), so invert when quality passes
+6. **Control Logic**: `matched=True` triggers the action (deny/observe), so invert when quality passes
 
 ## Troubleshooting
 

examples/langchain-sql.mdx

@@ -135,7 +135,7 @@ The SQL is evaluated using the `sql` evaluator:
 - Parses the query
 - Checks for blocked operations (DROP, DELETE, etc.)
 - Validates LIMIT clauses
-- Returns deny/allow decision
+- Returns deny/observe decision
 
 ### 4. Fail-Safe Error Handling
 
@@ -200,11 +200,11 @@ Agent Control Server
     ↓
 SQL Evaluator Execution
     ↓
-DENY (blocks DROP) or ALLOW (safe query)
+DENY (blocks DROP) or PASS (safe query)
     ↓
 Back to Decorator
     ↓
-Raise ControlViolationError (DENY) or Execute (ALLOW)
+Raise ControlViolationError (DENY) or Execute (PASS)
 ```
 
 ## Files

examples/steer-action-demo.mdx

@@ -1,18 +1,17 @@
 ---
 title: Steer Action Demo
-description: Banking transfer agent showcasing allow, deny, warn, and steer actions.
+description: Banking transfer agent showcasing observe, deny, and steer actions.
 ---
 
 A realistic AI banking agent that processes wire transfers with compliance controls, fraud detection, and approval workflows.
 
 ## What This Demonstrates
 
-This example shows all three AgentControl action types in a real-world banking scenario:
+This example shows the three Agent Control action types in a real-world banking scenario:
 
-- Allow: Auto-approve simple, low-risk transfers
 - Deny: Hard-block compliance violations (OFAC sanctions, high fraud)
-- Warn: Log suspicious activity without blocking (new recipients)
 - Steer: Guide agent through approval workflows (2FA, manager approval)
+- Observe: Record suspicious activity for audit without blocking (new recipients)
 
 ## Understanding Steer Actions
 
@@ -26,7 +25,7 @@ Key difference from deny:
 ## Demo Flow
 
 ```text
-Request Transfer → Steer Triggered → Correct Issue → Retry Transfer → Allow Success
+Request Transfer → Steer Triggered → Correct Issue → Retry Transfer → Success
 ```
 
 ## Quick Start
@@ -75,11 +74,11 @@ Expected:
 
 ## What You Will Learn
 
-- When to use deny vs warn vs steer actions
+- When to use deny vs steer vs observe actions
 - How to integrate human feedback (2FA, approvals) into agent workflows
 - How structured steering context enables deterministic agent workflows
 - Real-world compliance patterns (OFAC, AML, fraud prevention)
-- The steer to correct to retry to allow lifecycle
+- The steer → correct → retry lifecycle
 
 ## How It Works
 
@@ -89,7 +88,7 @@ The agent uses AgentControl to gate wire transfers through five controls:
 |---|---|---|
 | OFAC Sanctions | Deny | Destination is sanctioned country |
 | High Fraud | Deny | Fraud score > 0.8 |
-| New Recipient | Warn | Recipient not in known list |
+| New Recipient | Observe | Recipient not in known list |
 | 2FA Required | Steer | Amount >= 10,000 without 2FA |
 | Manager Approval | Steer | Amount >= 10,000 without approval |
 
@@ -141,7 +140,7 @@ Key fields:
 
 ## Files
 
-- `setup_controls.py` - Creates the five banking controls (deny, warn, steer)
+- `setup_controls.py` - Creates the five banking controls (deny, steer, observe)
 - `autonomous_agent_demo.py` - Interactive agent with deterministic steer handling
 
 ## Source Code

integrations/crewai.mdx

@@ -30,7 +30,7 @@ Add guardrails without refactoring existing CrewAI crews. The decorator wraps yo
 Keep CrewAI's built-in guardrails for response quality and agent behavior, while Agent Control handles hard security enforcement at tool boundaries.
 
 **4. Production-grade compliance**
-Built-in evaluators for PII detection, unauthorized access prevention, and custom business logic with deny/allow/steer actions.
+Built-in evaluators for PII detection, unauthorized access prevention, and custom business logic with deny/steer/observe actions.
 
 ### Common Use Cases
 

integrations/langchain.mdx

@@ -30,7 +30,7 @@ Add guardrails without refactoring existing LangChain code. The decorator wraps
 Choose server-side execution for centralized controls and audit logs, or SDK-local execution for offline operation and lower latency.
 
 **4. Production-grade safety**
-Built-in evaluators for SQL injection, regex patterns, PII detection, and custom business logic with deny/allow/steer actions.
+Built-in evaluators for SQL injection, regex patterns, PII detection, and custom business logic with deny/steer/observe actions.
 
 ### Common Use Cases