# Quick Start (Safe Skeleton)

This quickstart brings up the **ThreeGate skeleton stack** and runs the **tool-exec example** locally.

This is a *non-destructive* smoke test:
- no real LLM integration
- no real fetching
- no real ERA I/O mounting
- validates that directory layout + policies + validators are coherent

---

## 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

---

## 1) Prepare volumes

From repo root:

```sh
mkdir -p infra/volumes/{core-workspace,fetch-workspace,proxy-cache}
mkdir -p infra/volumes/handoff/{inbound-to-core,inbound-to-fetch,quarantine}
mkdir -p infra/volumes/dropbox/pdfs_in
mkdir -p infra/volumes/tool-exec/{requests_in,results_out}
````

(These directories may already exist if you committed `.gitkeep` files.)

---

## 2) Make scripts executable

```sh
make perms
```

---

## 3) Start the skeleton stack

```sh
make compose-up
docker ps --format "table {{.Names}}\t{{.Status}}"
```

Expected:

* `threegate-core`
* `threegate-fetch`
* `threegate-tool-exec`
* `threegate-proxy`
* `threegate-rolemesh`

These are placeholders and will simply idle.

---

## 4) Run validator smoke tests

No packets exist yet, but these commands should run without error:

```sh
make validate-packets
make validate-tool-requests
make validate-tool-results
```

---

## 5) Run TOOL-EXEC example (optional)

This runs a simple Python print command via the ERA wrapper.

```sh
make tool-exec-example
```

Result artifacts should appear in:

* `infra/volumes/tool-exec/results_out/`

Then validate tool results and promote them to CORE inbound:

```sh
make validate-tool-results
ls -1 infra/volumes/handoff/inbound-to-core
```

---

## 6) Stop the stack

```sh
make compose-down
```

---

## Next Steps (when moving beyond skeleton)

1. Implement FETCH packetizer (allowlisted domains + Research Packet creation)
2. Implement TOOL-EXEC safe data transfer (stdin/stdout protocol or guest volumes with strict allowlists)
3. Integrate RoleMesh-Gateway and a local/proxied LLM endpoint
4. Add systemd units for boot-time firewall enforcement + periodic validation

---

## Safety Notes

* Do not enable `/dev/kvm` passthrough into TOOL-EXEC until you decide whether TOOL-EXEC should run as host service vs container.
* Keep proxy allowlist narrow and auditable.
* Treat any schema relaxation as a security change.