# VeilCLI — Project Guide

This guide covers everything you need to set up, configure, and operate VeilCLI.

---

## Contents

| Doc | Topic |
|-----|-------|
| [01-quickstart.md](01-quickstart.md) | Install, create your first agent, run your first request |
| [02-folder-structure.md](02-folder-structure.md) | The `.veil/` workspace layout explained |
| [03-configuration.md](03-configuration.md) | `settings.json` + `auth.json` — every field |
| [04-agents.md](04-agents.md) | `agent.json`, `AGENT.md`, and all 4 agent modes |
| [05-cli.md](05-cli.md) | `veil` CLI commands reference |
| [06-tools.md](06-tools.md) | All 28 built-in tools |
| [07-permissions.md](07-permissions.md) | Tool permission system — allow/deny/ask |
| [08-memory.md](08-memory.md) | Persistent memory and context compaction |
| [09-multi-agent.md](09-multi-agent.md) | Multi-agent orchestration patterns |

---

## Architecture Overview

```
┌─────────────────────────────────────────┐
│             REST API (Express)           │
│  /agents  /sessions  /orchestration     │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│              Core Runtime               │
│  router.js → loop.js → tool registry   │
│  prompt assembly → LLM client           │
└──────────┬────────────────┬────────────┘
           │                │
┌──────────▼──────┐  ┌──────▼──────────┐
│  SQLite (db)    │  │  File system     │
│  sessions       │  │  .veil/agents/ │
│  messages       │  │  .veil/memory/ │
│  agent_messages │  │  .veil/auth.json│
│  todos          │  │  settings.json   │
│  trace_events   │  └─────────────────┘
└─────────────────┘
```

**Key concepts:**
- **Workspace** — any directory with a `.veil/` folder. One server instance per workspace.
- **Agent** — a folder in `.veil/agents/<name>/` with `agent.json` + `AGENT.md`.
- **Session** — a conversation thread. Created automatically per chat turn.
- **Sub-agent** — a chat session spawned by another agent via `agent_spawn`.