Merge pull request #4 from PredicateSystems/p4

P4: Documentation

Author: rcholic

README.md

@@ -80,21 +80,192 @@ SecureAgent
     └── RuntimeAgent (orchestration, pre-action hook)
 ```
 
-## Policy Example
+## Sidecar Prerequisite (Optional)
+
+The [Predicate Authority Sidecar](https://github.com/PredicateSystems/predicate-authority-sidecar) is **only required if you need pre-action authorization**—real-time policy evaluation that blocks unauthorized actions before they execute.
+
+| Feature | Sidecar Required? |
+|---------|-------------------|
+| Pre-action authorization (`strict`/`permissive` modes) | **Yes** |
+| Debug tracing (`debug` mode) | No |
+| Audit logging (`audit` mode) | No |
+| Policy development & testing | No |
+
+If you only need debug tracing or audit logging, you can skip the sidecar entirely.
+
+### Starting the Sidecar
+
+**Docker (Recommended):**
+
+```bash
+docker run -d -p 8787:8787 ghcr.io/predicatesystems/predicate-authorityd:latest
+```
+
+**Or download binary:**
+
+```bash
+# macOS (Apple Silicon)
+curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-darwin-arm64.tar.gz | tar -xz
+./predicate-authorityd --port 8787
+
+# Linux x64
+curl -fsSL https://github.com/PredicateSystems/predicate-authority-sidecar/releases/latest/download/predicate-authorityd-linux-x64.tar.gz | tar -xz
+./predicate-authorityd --port 8787
+```
+
+**Verify:**
+
+```bash
+curl http://localhost:8787/health
+# {"status":"ok"}
+```
+
+The sidecar handles policy evaluation in <25ms with zero egress—no data leaves your infrastructure.
+
+## Flexible Verification
+
+Use pre-execution authorization and post-execution verification **independently or together**:
+
+| Pattern | Use Case | Sidecar? |
+|---------|----------|----------|
+| Pre-execution only | Block unauthorized actions | Yes |
+| Post-execution only | Verify outcomes after completion | No |
+| Both (full loop) | Block + verify for max safety | Yes |
+
+**Pre-execution only** (policy without `require_verification`):
+
+```yaml
+rules:
+  - action: "browser.*"
+    resource: "https://amazon.com/*"
+    effect: allow
+```
+
+**Post-execution only** (debug mode, no sidecar):
+
+```python
+secure_agent = SecureAgent(agent=agent, mode="debug")
+secure_agent.run()
+secure_agent.trace_verification("cart_not_empty", passed=True)
+```
+
+**Both** (policy with `require_verification`):
+
+```yaml
+rules:
+  - action: "browser.click"
+    resource: "*checkout*"
+    effect: allow
+    require_verification:
+      - element_exists: "#order-confirmation"
+```
+
+## Debug Mode
+
+Debug mode provides human-readable trace output for troubleshooting:
+
+```python
+secure_agent = SecureAgent(
+    agent=agent,
+    policy="policy.yaml",
+    mode="debug",
+    trace_format="console",  # or "json"
+    trace_file="trace.jsonl",  # optional file output
+)
+```
+
+Console output shows:
+- Session start/end with framework and policy info
+- Each step with action and resource
+- Policy decisions (ALLOWED/DENIED) with reason codes
+- Snapshot diffs (before/after state changes)
+- Verification results (PASS/FAIL)
+
+For JSON trace output (machine-parseable):
+
+```python
+secure_agent = SecureAgent(
+    agent=agent,
+    mode="debug",
+    trace_format="json",
+    trace_file="trace.jsonl",
+)
+```
+
+## Policy Reference
+
+### Basic Structure
+
+```yaml
+# policies/example.yaml
+rules:
+  - action: "<action_pattern>"
+    resource: "<resource_pattern>"
+    effect: allow | deny
+    require_verification:  # optional
+      - <predicate>
+```
+
+### Action Patterns
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `browser.*` | All browser actions | click, type, navigate |
+| `browser.click` | Specific action | Only click events |
+| `api.call` | API tool calls | HTTP requests |
+| `*` | Wildcard (all actions) | Catch-all rules |
+
+### Resource Patterns
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `https://example.com/*` | URL prefix match | All pages on domain |
+| `*checkout*` | Contains match | Any checkout-related URL |
+| `button#submit` | CSS selector | Specific element |
+| `*` | Wildcard (all resources) | Catch-all |
+
+### Verification Predicates
+
+```yaml
+require_verification:
+  # URL checks
+  - url_contains: "/checkout"
+  - url_matches: "^https://.*\\.amazon\\.com/.*"
+
+  # DOM state checks
+  - element_exists: "#cart-items"
+  - element_text_contains:
+      selector: ".total"
+      text: "$"
+
+  # Custom predicates
+  - predicate: "cart_not_empty"
+```
+
+### Policy Example
 
 ```yaml
 # policies/shopping.yaml
 rules:
+  # Allow browsing Amazon
   - action: "browser.*"
     resource: "https://amazon.com/*"
     effect: allow
 
+  # Allow checkout with verification
   - action: "browser.click"
     resource: "*checkout*"
     effect: allow
     require_verification:
       - url_contains: "/checkout"
+      - element_exists: "#cart-items"
+
+  # Block external links
+  - action: "browser.navigate"
+    resource: "https://external.com/*"
+    effect: deny
 
+  # Default deny
   - action: "*"
     resource: "*"
     effect: deny