✨ feat: add agent integration and local integration documentation

- Introduced comprehensive guides for agent integration and local integration for SettlerEngine.
- Added `agents.md` to detail the HTTP handshake process for payment signatures.
- Created `local-integration.md` to explain local communication using UDS and SQLite persistence.
- Updated `intro.md` to link to the new documents and highlight local integration features.

Author: nathfavoursagent

docs/docs/agents.md

@@ -0,0 +1,57 @@
+# Agent Integration Guide
+
+AI Agents can integrate with SettlerEngine to perform autonomous, cryptographically secure payments for digital resources.
+
+## 1. The HTTP Handshake (x402)
+
+When an agent hits a protected endpoint, it receives an `HTTP 402 Payment Required` response.
+
+### Step A: Receive Challenge
+```json
+{
+  "status": 402,
+  "title": "Payment Required",
+  "description": "This resource requires a valid x402 payment signature.",
+  "payment": {
+    "amount": "1000000",
+    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "network": "84532",
+    "recipient": "0x1234567890AbcdEF1234567890aBcdef12345678",
+    "nonce": "c4e9de00cbdd804fdc7fd131701a2975"
+  }
+}
+```
+
+### Step B: Sign Intent to Pay
+The agent must sign an EIP-712 message containing the following fields:
+- `recipient`: The merchant wallet address.
+- `amount`: Atomic units of the asset.
+- `asset`: Contract address of the token (e.g., USDC).
+- `nonce`: The unique session identifier provided in the challenge.
+- `deadline`: A Unix timestamp after which the signature is invalid.
+
+### Step C: Retry with X-Payment
+The agent sends the original request again, including the `X-Payment` header with the JSON-encoded `intent` and `signature`.
+
+```http
+GET /protected-resource HTTP/1.1
+X-Payment: {"intent": {...}, "signature": "0x..."}
+```
+
+## 2. Local Integration (Unix Domain Sockets)
+
+For agents running on the same host as SettlerEngine, the Unix Domain Socket (UDS) provides a low-latency, secure channel.
+
+### Socket Location
+- **Linux**: `~/.config/settlerengine/settler.sock`
+- **macOS**: `~/Library/Application Support/settlerengine/settler.sock`
+
+### Benefits of UDS
+- **Zero Network Overhead**: Faster communication for high-frequency agents.
+- **Local Trust**: No need for complex network configurations or TLS for local traffic.
+- **Persistence**: Verified states are automatically cached in the local SQLite database.
+
+## 3. Best Practices for Agents
+- **Nonce Management**: Always use the most recent nonce provided in the 402 challenge.
+- **Deadline Handling**: Set a reasonable deadline (e.g., +5 minutes) to avoid signature expiration during processing.
+- **Error Handling**: Be prepared to handle signature verification failures by requesting a new nonce.

docs/docs/intro.md

@@ -7,7 +7,12 @@ SettlerEngine is a protocol-agnostic settlement layer for the next generation of
 - **x402 Protocol:** Handshake and verification lifecycle for machine-to-machine payments.
 - **Hexagonal Architecture:** Decoupling domain core from external infrastructure.
 - **Statelessness:** Relying on cryptographic signatures and the blockchain as the source of truth.
+- **Local Integration:** High-performance UDS and SQLite persistence for co-located agents.
 
 ## Getting Started
 
-Refer to the internal modules and the `settler-proxy` for integration details.
+- [Agent Integration Guide](./agents.md)
+- [Local Integration & UDS](./local-integration.md)
+- [Architecture Overview](./architecture.md)
+- [x402 Protocol Deep Dive](./x402.md)
+

docs/docs/local-integration.md

@@ -0,0 +1,58 @@
+# Local Integration & UDS
+
+SettlerEngine provides a robust local communication interface for co-located services and agents.
+
+## Data Directory Structure
+
+The engine stores its state and socket in a dedicated directory based on the OS standard (`os.UserConfigDir`):
+
+```bash
+settlerengine/
+├── settler.db   # SQLite3 database (CGO-free)
+└── settler.sock # Unix Domain Socket
+```
+
+## Unix Domain Socket (UDS) Protocol
+
+The `settler.sock` allows local processes to interact with the engine. 
+
+### Connection Example (Go)
+```go
+package main
+
+import (
+	"net"
+	"log"
+)
+
+func main() {
+	conn, err := net.Dial("unix", "/path/to/settler.sock")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer conn.Close()
+	
+	// Write and read protocol messages...
+}
+```
+
+## Persistence via SQLite
+
+SettlerEngine uses a CGO-free implementation of SQLite (`modernc.org/sqlite`) to ensure compatibility across all environments without needing a C toolchain.
+
+### Verified Payments Table
+The engine persists every verified signature to ensure idempotency and prevent replay attacks across restarts.
+
+```sql
+CREATE TABLE verified_payments (
+    signature TEXT PRIMARY KEY,
+    signer TEXT NOT NULL,
+    amount TEXT NOT NULL,
+    asset TEXT NOT NULL,
+    nonce TEXT NOT NULL,
+    verified_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Automatic Cleanup
+Signatures are validated against their EIP-712 deadlines even when retrieved from the database. The engine performs periodic cleanup of expired session nonces.