Updated README.md for project.

README.md

@@ -1,111 +1,186 @@
 # ThreeGate
 
-**ThreeGate** is a compartmentalized architecture for building **secure, local AI assistants** that perform goal-directed tasks *without* relying on autonomous agents or trusting large language models to behave safely.
+**ThreeGate** is a security-first architecture for local, agent-assisted research and analysis.
 
-ThreeGate separates **thinking**, **retrieval**, and **execution** into distinct, least-privileged components with enforced trust boundaries.
+It is designed to support *useful* agent behavior while strictly limiting blast radius by enforcing
+**three independent security gates** between reasoning, retrieval, and execution.
 
-> If prompt injection is inevitable, safety must come from structure.
+The system is intentionally conservative: capability is earned incrementally, audited at every boundary,
+and never co-located with reasoning.
 
 ---
 
-## What ThreeGate Is
+## Core Design Goal
 
-ThreeGate is:
+> Enable powerful local research assistance **without** granting an AI system uncontrolled execution,
+> network access, or persistence.
 
-- A **reference architecture** for secure local assistants
+ThreeGate is especially suited to:
-- A **defense-in-depth design** against prompt injection, tool abuse, and data exfiltration
+- academic and technical research assistants
-- A **human-governed system**, not an autonomous agent
+- policy analysis
-- Designed for **single-user, local operation**
+- code review and synthesis
-- Explicitly extensible to multiple roles (research, policy analysis, data science, auditing)
+- data transformation and ranking tasks
+
+It is *not* intended to run autonomous agents with self-directed persistence or open-ended tool use.
 
 ---
 
-## What ThreeGate Is Not
+## The Three Gates (Non-Negotiable)
 
-ThreeGate is **not**:
+### Gate 1 — **CORE (Reasoning & Synthesis)**
 
-- An autonomous agent framework
+- No network access
-- A self-modifying system
+- No execution capability
-- A browsing-and-executing AI loop
+- Consumes *only validated artifacts*
-- A cloud-first or multi-tenant platform
+- Produces analysis, summaries, and *Tool Requests* for human approval
-- A system that trusts LLM outputs without validation
+
+CORE is the only place where LLM reasoning occurs.
 
 ---
 
-## Core Insight
+### Gate 2 — **FETCH (Controlled Retrieval)**
 
-Most unsafe AI systems fail because they allow a single component to:
+- HTTPS only
+- Strict domain allowlist
+- Proxy-enforced egress
+- Size-capped and content-typed retrieval
+- Emits **Research Packets** only (never executable instructions)
 
-> **Read untrusted input, reason about it, and immediately act on the world.**
+FETCH treats *all external content as hostile data*.
-
-ThreeGate prevents this by enforcing **three independent gates**:
-
-1. **FETCH** — retrieves untrusted external content
-2. **CORE** — performs reasoning and synthesis
-3. **TOOL-EXEC** — executes code, only when explicitly approved
-
-No component crosses more than one gate.
 
 ---
 
-## High-Level Architecture
+### Gate 3 — **TOOL-EXEC (Constrained Execution)**
 
-     Internet
+Execution is split into **two distinct backends**:
-         ↑
+
-    [ Managed Proxy ]
+#### TOOL-EXEC-Lite (Monty)
-         ↑
+- Python-subset interpreter
-     FETCH (retrieval)
+- No filesystem
-         ↓
+- No environment
-    Research Packets
+- No network
-         ↓
+- No subprocess
-     CORE (analysis)
+- No external functions (by default)
-         ↓
+- Stdio-only inputs/outputs
- (optional, human-approved)
+
-	 ↓
+Used for:
- TOOL-EXEC (sandboxed execution)
+- JSON transformations
+- ranking/scoring
+- small algorithms
+- validation helpers
+
+This is the **default execution lane**.
+
+#### TOOL-EXEC-Heavy (ERA microVM)
+- Full isolation via microVM
+- Used only when Monty cannot express the task
+- Requires explicit justification
+
+Both execution lanes:
+- Require human-approved Tool Requests
+- Emit **Tool Results** as immutable artifacts
+- Are never allowed to feed results back into FETCH or execute recursively
 
 ---
 
-## Initial Target Role
+## Data Flow (One-Way, Audited)
-
-The first concrete role implemented using ThreeGate is a:
-
-**Secure Local Research Assistant**
-
-Capabilities:
-- Scholarly retrieval (controlled, allowlisted)
-- Analysis and writing
-- Optional sandboxed computation
-- No autonomous browsing or execution
-
----
-
-## Repository Structure (Initial)
 
 ```
-ThreeGate/
+
-├── README.md
+External Sources
-├── docs/
+↓
-│ ├── architecture.md
+FETCH
-│ ├── threat-model.md
+↓  (Research Packets)
-│ └── why-this-is-safer.md
+handoff/
+↓
+CORE
+↓  (Approved Tool Requests)
+TOOL-EXEC
+↓  (Tool Results)
+handoff/
+↓
+CORE
+
+```
+
+No component both **decides** and **acts**.
+
+---
+
+## Artifact Types
+
+### Research Packet
+- Markdown + strict front matter
+- Metadata, bounded excerpts, provenance
+- No instructions, no executable content
+- Validated before CORE ingestion
+
+### Tool Request
+- Human-approved
+- Backend-specific (`ERA` or `monty`)
+- Declarative constraints
+- No self-modifying behavior
+
+### Tool Result
+- Immutable output
+- Captured stdout/stderr
+- Content hashes
+- Treated as untrusted data by CORE
+
+---
+
+## Security Principles (Do Not Violate)
+
+- No reasoning component may execute code
+- No execution component may reason or fetch
+- Network access is centralized and audited
+- Redirects are never trusted without re-validation
+- All cross-gate artifacts are hostile by default
+- Escalation of capability is a security change
+
+---
+
+## Repository Structure (Key Paths)
+
+```
+
+core/                 # CORE consumers (read-only)
+fetch/                # FETCH retrievers (proxy-bound)
+tool-exec/
+monty/              # TOOL-EXEC-Lite (pure compute)
+era/                # TOOL-EXEC-Heavy (microVM)
+tools/                # Validators and shared helpers
+policy/               # Human-readable enforcement rules
+infra/                # Docker, proxy, firewall scaffolding
+docs/                 # Architecture and operator guides
+
 ```
 
 ---
 
 ## Status
 
-This repository is in **early specification and reference implementation phase**.
+This repository currently provides:
+- Full FETCH scaffolding with allowlisted, size-capped retrieval
+- Crossref DOI metadata ingestion
+- Redirect-safe URL fetching
+- Monty execution backend (pure compute)
+- ERA execution stubs
+- Validators enforcing backend-specific rules
 
-The design is intentionally conservative. Convenience features are added *only* when they preserve trust boundaries.
+It is suitable for **local research workflows** and **controlled experimentation**.
 
 ---
 
-## License & Philosophy
+## Philosophy
 
-ThreeGate favors:
+ThreeGate assumes:
-- Explicit over implicit authority
+- LLMs are powerful but non-deterministic
-- Structural safety over behavioral promises
+- External content is adversarial by default
-- Human-in-the-loop over automation
+- Execution is the highest-risk capability
+- Separation of duties beats clever sandboxing
+
+The goal is not to build an autonomous agent.
+The goal is to build a *trustworthy assistant*.
+```
 
-If a feature weakens a trust boundary, it does not belong here.