Docs update

docs/execution_backends.md

@@ -0,0 +1,116 @@
+# Execution Backends in ThreeGate
+
+ThreeGate deliberately separates *reasoning* from *execution* and further subdivides execution
+into **two distinct backends** with different risk profiles.
+
+This document explains when and why each backend exists, and how escalation decisions should be made.
+
+---
+
+## Overview
+
+| Backend | Purpose | Risk Level | Default |
+|-------|---------|------------|---------|
+| Monty (TOOL-EXEC-Lite) | Pure compute, data transforms | Low | ✅ Yes |
+| ERA (TOOL-EXEC-Heavy) | General execution in microVM | Higher | ❌ No |
+
+---
+
+## Monty (TOOL-EXEC-Lite)
+
+### What Monty Is
+Monty is a restricted Python-subset interpreter designed for agentic toolchains.
+It provides *programmability without host access*.
+
+### Capabilities
+- Arithmetic and control flow
+- Lists, dicts, loops
+- Deterministic transformations over provided inputs
+- Captured stdout / return value
+
+### Explicitly Not Allowed
+- Filesystem access
+- Network access
+- Environment variables
+- Subprocesses
+- Dynamic imports
+- External functions (unless explicitly added by policy)
+
+### Intended Use Cases
+- Ranking or scoring items
+- JSON or CSV-like data transformations
+- Parsing and normalization
+- Small algorithms that would otherwise require custom code
+
+### Why Monty Is the Default
+- Minimal blast radius
+- No persistence
+- No I/O side effects
+- Fast startup
+- Designed specifically to avoid “agent escape hatches”
+
+### Security Note
+Monty is *not* a sandbox replacement for arbitrary Python.
+It is a **capability-limited interpreter**.
+Any addition of external functions is a security boundary change.
+
+---
+
+## ERA (TOOL-EXEC-Heavy)
+
+### What ERA Is
+ERA executes tasks inside a microVM with strong isolation guarantees.
+
+### Capabilities
+- Full Python or binary execution
+- File I/O via explicit mounts
+- Larger memory and runtime allowances
+- Future support for specialized tools
+
+### When ERA Is Justified
+Use ERA **only** when:
+- The task cannot be expressed in Monty’s subset
+- File-based artifacts are required
+- External binaries are unavoidable
+- The operator explicitly approves escalation
+
+### Why ERA Is Not the Default
+- Larger attack surface
+- More complex lifecycle
+- Higher operational cost
+- More difficult to audit than pure compute
+
+ERA exists as an *escape hatch*, not a baseline.
+
+---
+
+## Escalation Rules (Non-Negotiable)
+
+1. **Attempt Monty first**
+2. If Monty cannot express the task, document why
+3. Require explicit human approval for ERA
+4. Treat ERA outputs as untrusted data on return
+5. Never allow ERA to initiate further execution or retrieval
+
+---
+
+## Anti-Patterns
+
+🚫 Automatically choosing ERA  
+🚫 Allowing Monty to access files or network  
+🚫 Re-running execution results as instructions  
+🚫 Chaining execution backends without human approval  
+
+---
+
+## Summary
+
+ThreeGate’s execution model is deliberately asymmetric:
+
+- Monty provides *safe programmability*
+- ERA provides *controlled power*
+- CORE never executes
+- FETCH never executes
+- No backend is autonomous
+
+This separation is foundational to ThreeGate’s security model.

docs/quickstart.md

@@ -10,11 +10,24 @@ This is a *non-destructive* smoke test:
 
 ---
 
+⚠️ Important: Execution Backends
+
+ThreeGate supports two execution backends:
+
+- `monty` (default): pure compute, safest
+- `ERA`: microVM, higher risk, explicit approval required
+
+If you are unsure, use Monty.
+
+---
+
 ## Prerequisites
 
 - Docker + Docker Compose v2
 - Python 3 (stdlib only; no pip deps)
-- (Optional for tool-exec example) ERA `agent` CLI installed and available in PATH
+- (Optional for tool-exec example 'hello') ERA `agent` CLI installed and available in PATH
+- (Optional for tool-exec example 'json sum') Monty 'agent' CLI installed and available in PATH
+- Either a local LLM hosted via an OpenAI-compatible endpoint or OpenAI API key
 
 ---