@newsails/veil-cli 1.0.1

package/docs/guide/01-quickstart.md

@@ -0,0 +1,220 @@
+# Quickstart
+
+Get VeilCLI running and talk to your first agent in under 5 minutes.
+
+---
+
+## Prerequisites
+
+- **Node.js ≥ 18.3.0** — check with `node --version`
+- An **OpenAI-compatible API key** — [OpenRouter](https://openrouter.ai) works out of the box
+
+---
+
+## Step 1 — Install
+
+```bash
+npm install -g @newsails/veil-cli
+```
+
+Verify:
+```bash
+veil --version
+# VeilCLI v0.1.0
+```
+
+---
+
+## Step 2 — Create a Workspace
+
+A workspace is any directory with a `.veil/` folder.
+
+```bash
+mkdir ~/my-workspace && cd ~/my-workspace
+mkdir -p .veil/agents/hello
+```
+
+---
+
+## Step 3 — Configure Auth
+
+```bash
+# Save your API key to the project workspace
+veil login --key sk-or-v1-YOUR_KEY_HERE
+
+# Or save it globally (shared across all workspaces)
+veil login --key sk-or-v1-YOUR_KEY_HERE --global
+```
+
+This writes to `.veil/auth.json`:
+```json
+{
+  "models": {
+    "main": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key": "sk-or-v1-...",
+      "model": ""
+    }
+  }
+}
+```
+
+You also need to specify the model. Edit `.veil/auth.json`:
+```json
+{
+  "models": {
+    "main": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key": "sk-or-v1-YOUR_KEY",
+      "model": "moonshotai/kimi-k2.5"
+    }
+  }
+}
+```
+
+Any [OpenRouter model slug](https://openrouter.ai/models) works. Popular choices:
+- `moonshotai/kimi-k2.5` — fast, capable, tool-calling
+- `anthropic/claude-3.5-sonnet` — excellent reasoning
+- `google/gemini-2.0-flash-001` — very fast
+- `meta-llama/llama-3.3-70b-instruct` — open model
+
+---
+
+## Step 4 — Create Your First Agent
+
+Create `.veil/agents/hello/agent.json`:
+
+```json
+{
+  "name": "hello",
+  "description": "A friendly conversational agent",
+  "model": "moonshotai/kimi-k2.5",
+  "temperature": 0.7,
+  "reasoning": "medium",
+  "memory": { "enabled": false },
+  "modes": {
+    "chat": { "enabled": true },
+    "task": { "enabled": true }
+  }
+}
+```
+
+Create `.veil/agents/hello/AGENT.md`:
+
+```markdown
+You are Hello, a friendly and concise assistant.
+
+Be helpful, clear, and direct. Keep responses short unless asked for detail.
+```
+
+---
+
+## Step 5 — Start the Server
+
+```bash
+cd ~/my-workspace
+veil start
+# VeilCLI v0.1.0 started on port 5050
+# Project: /home/user/my-workspace
+# Agents: 1 | PID: 12345
+```
+
+Options:
+```bash
+veil start --port 5051          # custom port
+veil start --folder /other/dir  # different workspace
+veil start --secret mytoken     # require auth header
+```
+
+---
+
+## Step 6 — Chat!
+
+```bash
+# Check health
+curl http://localhost:5050/health
+
+# Send a chat message
+curl -X POST http://localhost:5050/agents/hello/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What is 2 + 2?"}'
+```
+
+Response:
+```json
+{
+  "sessionId": "sess_4f3a1b9c2d8e7f01",
+  "message": {
+    "role": "assistant",
+    "content": "2 + 2 = 4."
+  },
+  "tokenUsage": { "input": 120, "output": 8, "cache": 0 }
+}
+```
+
+Continue the conversation by passing `sessionId` back:
+```bash
+curl -X POST http://localhost:5050/agents/hello/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "And multiply that by 3?", "sessionId": "sess_4f3a1b9c2d8e7f01"}'
+```
+
+---
+
+## Step 7 — Run a Task
+
+Tasks run asynchronously. Great for anything that needs multiple LLM steps or tool use.
+
+First, give your agent tools by updating `agent.json`:
+```json
+{
+  "name": "hello",
+  "model": "moonshotai/kimi-k2.5",
+  "modes": {
+    "chat": { "enabled": true },
+    "task": {
+      "enabled": true,
+      "permissions": {
+        "allow": ["read_file", "list_dir", "bash"]
+      }
+    }
+  }
+}
+```
+
+Then run a task:
+```bash
+# Create task (returns immediately)
+curl -X POST http://localhost:5050/agents/hello/task \
+  -H "Content-Type: application/json" \
+  -d '{"input": "How many files are in the current directory?"}'
+
+# Poll until done
+curl http://localhost:5050/tasks/task_c0ab38d8377cdd47
+```
+
+---
+
+## Interactive CLI Client
+
+If you have the `connect.js` TUI client, you can explore everything interactively:
+
+```bash
+node /path/to/VeilCli_TESTS/cli-app/connect.js
+```
+
+Or jump straight to a chat session:
+```bash
+node connect.js chat hello
+```
+
+See [the connect.js README](../guide/05-cli.md#interactive-tui-client) for full usage.
+
+---
+
+## What's Next
+
+- [Folder Structure](02-folder-structure.md) — understand every file in `.veil/`
+- [Configuration](03-configuration.md) — all settings explained
+- [Agent Configuration](04-agents.md) — full `agent.json` reference
+- [Built-in Tools](06-tools.md) — what your agents can do

package/docs/guide/02-folder-structure.md

@@ -0,0 +1,185 @@
+# Folder Structure
+
+Every VeilCLI workspace is a directory with a `.veil/` subfolder. Here is the complete layout:
+
+---
+
+## Workspace Layout
+
+```
+my-workspace/
+└── .veil/
+    ├── auth.json               ← API keys and model config
+    ├── settings.json           ← Server and runtime settings
+    ├── settings.local.json     ← Local overrides (gitignore this)
+    ├── data.db                 ← SQLite database (sessions, tasks, messages)
+    ├── runtime.pid             ← PID of the running server
+    │
+    ├── agents/
+    │   └── <agent-name>/
+    │       ├── agent.json      ← Agent configuration (required)
+    │       ├── AGENT.md        ← System prompt / personality (required)
+    │       ├── SOUL.md         ← Optional extra identity layer
+    │       └── tools/          ← Optional custom tools for this agent
+    │           └── my_tool.js
+    │
+    ├── memory/
+    │   ├── MEMORY.md           ← Project-level (global) memory
+    │   └── agents/
+    │       └── <agent-name>/
+    │           └── MEMORY.md   ← Per-agent memory
+    │
+    └── heartbeats/
+        └── <agent-name>.md     ← Daemon agent instructions (read each tick)
+```
+
+---
+
+## File Descriptions
+
+### `auth.json`
+
+Stores API credentials. Separated from `settings.json` so you can gitignore it independently.
+
+```json
+{
+  "models": {
+    "main": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key": "sk-or-v1-...",
+      "model": "moonshotai/kimi-k2.5"
+    },
+    "compact": null,
+    "title": null
+  }
+}
+```
+
+Model roles:
+- **`main`** — used for all agent LLM calls (required)
+- **`compact`** — used for context compaction summaries (falls back to `main`)
+- **`title`** — used to generate task/session titles (falls back to `main`)
+
+---
+
+### `settings.json`
+
+Runtime configuration. See [Configuration Reference](03-configuration.md) for all fields.
+
+```json
+{
+  "port": 5050,
+  "maxIterations": 20,
+  "maxDurationSeconds": 120,
+  "permissions": {
+    "allow": [],
+    "deny": [],
+    "ask": []
+  }
+}
+```
+
+---
+
+### `settings.local.json`
+
+Same format as `settings.json`. Applied last (highest priority among file layers). Useful for developer overrides that should not be committed. Add to `.gitignore`.
+
+---
+
+### `data.db`
+
+SQLite database file. Contains all sessions, messages, tasks, task events, todos, agent messages, and task subscriptions. Created automatically on first run.
+
+**Do not edit manually.** If you need to reset state, stop the server and delete this file — it will be recreated.
+
+---
+
+### `runtime.pid`
+
+Contains the process ID of the running server. Written by `veil start`, removed by `veil stop` / graceful shutdown. If it exists but the process is gone, it is a stale PID file and can be deleted.
+
+---
+
+### `agents/<name>/agent.json`
+
+Agent configuration. JSON Schema-validated on load. See [Agent Configuration](04-agents.md).
+
+---
+
+### `agents/<name>/AGENT.md`
+
+The agent's system prompt. Loaded and injected into every conversation for this agent. Supports variables:
+
+| Variable | Resolves to |
+|----------|-------------|
+| `$AGENT_FOLDER` | Absolute path to the agent's folder |
+| `$PROJECT_ROOT` | Absolute path to the workspace root |
+
+Example:
+```markdown
+You are Analyst, a code analysis agent.
+
+Your working directory is $PROJECT_ROOT.
+Your files are in $AGENT_FOLDER.
+```
+
+---
+
+### `agents/<name>/SOUL.md`
+
+Optional. An additional identity/personality layer merged into the system prompt after `AGENT.md`. Useful for separating static capabilities from dynamic persona.
+
+---
+
+### `agents/<name>/tools/`
+
+Optional directory for agent-specific custom tools. Each file must export `{ schema, execute }` following the same pattern as the built-in tools. These tools are available only to this agent.
+
+---
+
+### `memory/MEMORY.md`
+
+Project-level shared memory. Written by agents using `memory_write` with `scope: "global"`. Injected into the system prompt of agents that have memory enabled.
+
+---
+
+### `memory/agents/<name>/MEMORY.md`
+
+Per-agent memory. Written by agents using `memory_write` with `scope: "agent"` (default). Only injected for that agent.
+
+---
+
+### `heartbeats/<agent-name>.md`
+
+Instructions file for daemon agents. Read at the start of each scheduled tick and used as the agent's task input for that run. If the file doesn't exist, a default instruction is used.
+
+---
+
+## Global Config
+
+VeilCLI also reads from a global config directory at `~/.veil/`:
+
+```
+~/.veil/
+├── auth.json       ← Global API keys (overridden by project auth.json)
+└── settings.json   ← Global defaults (overridden by project settings.json)
+```
+
+The global config is useful for sharing an API key across multiple workspaces without duplicating it. See [Settings Layers](03-configuration.md#settings-layers).
+
+---
+
+## What to Gitignore
+
+Add these to `.gitignore` in your workspace:
+
+```gitignore
+.veil/data.db
+.veil/runtime.pid
+.veil/auth.json
+.veil/settings.local.json
+.veil/memory/
+```
+
+Keep `agents/`, `settings.json`, and `heartbeats/` in version control.

package/docs/guide/03-configuration.md

@@ -0,0 +1,252 @@
+# Configuration Reference
+
+VeilCLI uses two config files per workspace: `auth.json` for credentials and `settings.json` for everything else.
+
+---
+
+## Settings Layers
+
+Settings are loaded and merged in this order (each layer overrides the previous):
+
+```
+1. Built-in defaults
+2. ~/.veil/settings.json     (global settings)
+3. ~/.veil/auth.json          (global credentials)
+4. .veil/settings.json        (project settings)
+5. .veil/auth.json            (project credentials)
+6. .veil/settings.local.json  (local overrides, gitignored)
+7. CLI flags                    (--port, --secret, etc.)
+```
+
+This means you can set a default model in `~/.veil/auth.json` and override it per-project in `.veil/auth.json`.
+
+---
+
+## `auth.json`
+
+Stores API credentials. Keep this out of version control.
+
+```json
+{
+  "models": {
+    "main": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key": "sk-or-v1-...",
+      "model": "moonshotai/kimi-k2.5"
+    },
+    "compact": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_key": "sk-or-v1-...",
+      "model": "google/gemini-flash-1.5-8b"
+    },
+    "title": null
+  }
+}
+```
+
+### Model roles
+
+| Role | Purpose | Fallback |
+|------|---------|----------|
+| `main` | All agent LLM calls | — (required) |
+| `compact` | Context compaction summaries | Falls back to `main` |
+| `title` | Generate task/session titles | Falls back to `main` |
+
+### Model config fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `base_url` | string | API base URL (default: `https://openrouter.ai/api/v1`) |
+| `api_key` | string | API key |
+| `model` | string | Model identifier string, e.g. `moonshotai/kimi-k2.5` |
+| `temperature` | number | Override temperature (0–2) |
+| `reasoning` | string | Override reasoning mode: "minimal", "low", "medium", "high" |
+| `maxTokens` | integer | Override max output tokens |
+
+### Shortcut: `veil login`
+
+```bash
+veil login --key sk-or-v1-...          # writes to .veil/auth.json
+veil login --key sk-or-v1-... --global # writes to ~/.veil/auth.json
+```
+
+---
+
+## `settings.json`
+
+Full runtime configuration. All fields are optional — omitting any field uses the default.
+
+### Top-level fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | integer | `5050` | HTTP server port |
+| `secret` | string \| null | `null` | If set, all API requests must include `X-Veil-Secret: <secret>` |
+| `maxIterations` | integer | `20` | Default max LLM loop iterations per task/chat turn |
+| `maxDurationSeconds` | integer | `120` | Default max wall-clock seconds per task |
+| `maxConcurrentTasks` | integer | `10` | Max tasks running in parallel |
+| `maxSubAgentDepth` | integer | `5` | Max depth of nested `agent_spawn` calls |
+
+### `models`
+
+Can also be specified in `settings.json` (alongside or instead of `auth.json`):
+
+```json
+{
+  "models": {
+    "main": { "base_url": "...", "api_key": "...", "model": "..." }
+  }
+}
+```
+
+### `permissions`
+
+Global tool permission policy applied to all agents (unless overridden per-agent or per-mode).
+
+```json
+{
+  "permissions": {
+    "allow": ["*"],
+    "deny": ["bash"],
+    "ask": ["write_file"]
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allow` | string[] | Tools explicitly allowed. Use `["*"]` to allow all. |
+| `deny` | string[] | Tools explicitly denied. Takes priority over `allow`. |
+| `ask` | string[] | Tools that require human approval before executing. Settings-level only. |
+
+See [Permissions](07-permissions.md) for the full layering explanation.
+
+### `hooks`
+
+Shell commands to run before/after every tool execution:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": "/path/to/pre-hook.sh",
+    "PostToolUse": "/path/to/post-hook.sh"
+  }
+}
+```
+
+The hook receives tool name and input as environment variables. Set to `null` to disable.
+
+### `compaction`
+
+Controls automatic context window management:
+
+```json
+{
+  "compaction": {
+    "threshold": 0.8,
+    "observationMaskingTurns": 10
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `threshold` | number | `0.8` | Fraction of context window (0.1–1.0) that triggers compaction |
+| `observationMaskingTurns` | integer | `10` | Number of recent turns to keep tool results visible; older ones are masked |
+
+See [Memory & Compaction](08-memory.md).
+
+### `memory`
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "maxLines": 500
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Whether memory files are injected into system prompts |
+| `maxLines` | integer | `500` | Max lines to read from a memory file |
+
+### `storage.retention`
+
+Controls how long sessions and tasks are kept in SQLite:
+
+```json
+{
+  "storage": {
+    "retention": {
+      "sessions": { "maxAgeDays": 90, "maxCount": 10000 },
+      "tasks":    { "maxAgeDays": 30, "maxCount": 5000 }
+    }
+  }
+}
+```
+
+### `mcpServers`
+
+Configuration for Model Context Protocol (MCP) servers:
+
+```json
+{
+  "mcpServers": {
+    "my-mcp": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}
+```
+
+MCP tools are available to agents that list the server name in their `modes.<mode>.mcpServers` array (whitelist-only).
+
+### `ably`
+
+Enable Ably for remote API access (e.g. from external clients over the internet):
+
+```json
+{
+  "ably": {
+    "enabled": true,
+    "key": "xVLya.AblyKey"
+  }
+}
+```
+
+---
+
+## Complete Example
+
+```json
+{
+  "port": 5051,
+  "secret": "my-dev-secret",
+  "maxIterations": 25,
+  "maxDurationSeconds": 180,
+  "maxConcurrentTasks": 5,
+  "maxSubAgentDepth": 3,
+  "permissions": {
+    "allow": ["read_file", "list_dir", "bash", "web_search", "web_fetch"],
+    "deny": [],
+    "ask": ["write_file", "edit_file"]
+  },
+  "compaction": {
+    "threshold": 0.75,
+    "observationMaskingTurns": 8
+  },
+  "memory": {
+    "enabled": true,
+    "maxLines": 300
+  },
+  "storage": {
+    "retention": {
+      "sessions": { "maxAgeDays": 30, "maxCount": 5000 },
+      "tasks":    { "maxAgeDays": 14, "maxCount": 2000 }
+    }
+  }
+}
+```