@newsails/veil-cli 1.0.1

package/docs/api/07-memory.md

@@ -0,0 +1,186 @@
+# Memory API
+
+Read, write, and delete agent and global memory files via HTTP.
+
+Memory files are plain Markdown stored under `.veil/memory/`. They are injected into the agent's system prompt at session start.
+
+---
+
+## Agent Memory
+
+### `GET /agents/:name/memory`
+
+List all memory files for an agent.
+
+```bash
+curl http://localhost:5050/agents/assistant/memory
+```
+
+**Response:**
+```json
+{
+  "agentName": "assistant",
+  "files": [
+    { "name": "MEMORY.md", "size": 1240, "modified": "2025-03-04T12:00:00.000Z" }
+  ]
+}
+```
+
+---
+
+### `GET /agents/:name/memory/:file`
+
+Read a specific memory file.
+
+```bash
+curl http://localhost:5050/agents/assistant/memory/MEMORY.md
+```
+
+**Response:**
+```json
+{
+  "agentName": "assistant",
+  "file": "MEMORY.md",
+  "content": "## Notes\n\nProject uses port 5050."
+}
+```
+
+**Errors:** `404 NOT_FOUND` if file does not exist.
+
+---
+
+### `PUT /agents/:name/memory/:file`
+
+Write or replace a memory file. Creates the file if it does not exist.
+
+```bash
+curl -X PUT http://localhost:5050/agents/assistant/memory/MEMORY.md \
+  -H "Content-Type: application/json" \
+  -d '{"content": "## Project Notes\n\nThis project uses port 5050."}'
+```
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `content` | string | ✓ | Full Markdown content to write |
+
+**Response:**
+```json
+{
+  "agentName": "assistant",
+  "file": "MEMORY.md",
+  "size": 47
+}
+```
+
+**Errors:** `400 VALIDATION_ERROR` if `content` is not a string or filename is invalid.
+
+---
+
+### `DELETE /agents/:name/memory/:file`
+
+Delete a memory file.
+
+```bash
+curl -X DELETE http://localhost:5050/agents/assistant/memory/MEMORY.md
+```
+
+**Response:**
+```json
+{ "agentName": "assistant", "file": "MEMORY.md", "status": "deleted" }
+```
+
+**Errors:** `404 NOT_FOUND` if file does not exist.
+
+---
+
+---
+
+## Global Memory
+
+Global memory files are shared across all agents. Stored at `.veil/memory/`.
+
+### `GET /memory`
+
+List all global memory files.
+
+```bash
+curl http://localhost:5050/memory
+```
+
+**Response:**
+```json
+{
+  "files": [
+    { "name": "MEMORY.md", "size": 512, "modified": "2025-03-04T12:00:00.000Z" }
+  ]
+}
+```
+
+---
+
+### `GET /memory/:file`
+
+Read a global memory file.
+
+```bash
+curl http://localhost:5050/memory/MEMORY.md
+```
+
+**Response:**
+```json
+{
+  "file": "MEMORY.md",
+  "content": "## Global Notes\n\nShared across all agents."
+}
+```
+
+---
+
+### `PUT /memory/:file`
+
+Write or replace a global memory file.
+
+```bash
+curl -X PUT http://localhost:5050/memory/MEMORY.md \
+  -H "Content-Type: application/json" \
+  -d '{"content": "## Global Notes\n\nUpdated content."}'
+```
+
+**Response:**
+```json
+{
+  "file": "MEMORY.md",
+  "size": 35
+}
+```
+
+---
+
+### `DELETE /memory/:file`
+
+Delete a global memory file.
+
+```bash
+curl -X DELETE http://localhost:5050/memory/MEMORY.md
+```
+
+**Response:**
+```json
+{ "file": "MEMORY.md", "status": "deleted" }
+```
+
+---
+
+## File Name Rules
+
+Memory file names must match the pattern `[a-z0-9A-Z_-]+.md`. Path traversal (`../`) is rejected with `400 VALIDATION_ERROR`.
+
+---
+
+## Notes
+
+- Agent-scoped files: `.veil/memory/agents/<name>/<file>`
+- Global files: `.veil/memory/<file>`
+- Changes take effect on the **next session** — currently running sessions are not affected.
+- To seed an agent's memory before first run, use this API to write a `MEMORY.md` file.

package/docs/api/08-settings.md

@@ -0,0 +1,133 @@
+# Settings API
+
+Read and live-update workspace configuration via HTTP. No server restart required.
+
+---
+
+## `GET /settings`
+
+Returns settings for the workspace. API keys are **redacted** (shown as `sk-…xxxx`).
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `level` | string | Which layer to read. Default: `merged` |
+
+**Level values**
+
+| Value | Source file | Description |
+|-------|-------------|-------------|
+| `merged` | *(all layers)* | Full effective settings — defaults → global → project → local merged. **(default)** |
+| `project` | `.veil/settings.json` | Project-level overrides only |
+| `global` | `~/.veil/settings.json` | User-level global overrides only |
+| `local` | `.veil/settings.local.json` | Local machine overrides only (gitignored) |
+
+**Response**
+```json
+{
+  "level": "merged",
+  "exists": true,
+  "path": null,
+  "settings": {
+    "port": 5050,
+    "models": {
+      "main": {
+        "base_url": "https://openrouter.ai/api/v1",
+        "api_key": "sk-…1234",
+        "model": "anthropic/claude-sonnet-4-5"
+      }
+    },
+    "permissions": { "allow": [], "deny": [], "ask": [] },
+    "memory": { "enabled": true, "maxLines": 500 },
+    "maxIterations": 20,
+    "maxDurationSeconds": 300
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `level` | The level that was read |
+| `exists` | Whether the settings file exists on disk (`false` for `merged` is never returned) |
+| `path` | Absolute path to the file (`null` for `merged`) |
+| `settings` | The settings object (raw file contents for non-merged levels; `{}` if file absent) |
+
+**Examples**
+```bash
+# Full merged settings (default)
+curl http://localhost:5050/settings
+
+# Only what's in .veil/settings.json
+curl http://localhost:5050/settings?level=project
+
+# Only what's in ~/.veil/settings.json
+curl http://localhost:5050/settings?level=global
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 INVALID_LEVEL` | `level` is not one of the valid values |
+
+---
+
+## `PUT /settings`
+
+Validate and write settings to the specified level file. Immediately live-reloads merged settings — all subsequent requests use the new effective values.
+
+**Query parameters**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `level` | string | Which file to write. Default: `project`. `merged` is not writable. |
+
+| Value | Writes to |
+|-------|----------|
+| `project` | `.veil/settings.json` **(default)** |
+| `global` | `~/.veil/settings.json` |
+| `local` | `.veil/settings.local.json` |
+
+**Request body:** A valid settings object (see [Configuration guide](../guide/03-configuration.md)). Validated against the settings schema before writing.
+
+**Response**
+```json
+{
+  "status": "updated",
+  "level": "project",
+  "path": "/home/user/workspace/.veil/settings.json",
+  "settings": { ... }
+}
+```
+
+`settings` in the response is the full **merged** effective settings after the write.
+
+**Examples**
+```bash
+# Write to project settings (default)
+curl -X PUT http://localhost:5050/settings \
+  -H "Content-Type: application/json" \
+  -d '{"maxIterations": 30, "memory": {"enabled": true}}'
+
+# Write to global settings
+curl -X PUT "http://localhost:5050/settings?level=global" \
+  -H "Content-Type: application/json" \
+  -d '{"models": {"main": {"model": "anthropic/claude-sonnet-4-5"}}}'
+```
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `400 INVALID_LEVEL` | `level` is `merged` (read-only) or not a valid value |
+| `400 VALIDATION_ERROR` | Body fails schema validation (field-level error messages included) |
+
+---
+
+## Notes
+
+- The settings layer stack is: **defaults → global → project → local**. Each layer overrides the previous.
+- Model credentials (`api_key`) must be set via `auth.json` — not via this endpoint.
+- Live reload only affects in-memory settings. Currently running tasks/loops see the old settings until they complete.
+- `PUT` with `?level=local` is useful for machine-specific overrides that should not be committed to version control.

package/docs/api/09-models.md

@@ -0,0 +1,119 @@
+# Models
+
+The models API exposes the local model index built from OpenRouter's public model catalogue. It is used internally to populate `context_size_limit` on new sessions and to fall back to a calculated cost when the LLM provider does not return a `usage.cost` field in its response.
+
+The index is stored in `config/models.json` and loaded once at startup (cached in memory). Refresh it any time with `POST /models/refresh` or `npm run fetch-models`.
+
+---
+
+## GET /models
+
+Returns the full model index.
+
+**Response**
+```json
+{
+  "updated_at": "2026-03-06T03:00:00.000Z",
+  "models": [
+    {
+      "id": "anthropic/claude-sonnet-4.6",
+      "name": "Anthropic: Claude Sonnet 4.6",
+      "context_length": 1000000,
+      "max_completion_tokens": 128000,
+      "pricing": {
+        "prompt": 0.000003,
+        "completion": 0.000015,
+        "cache_read": 0.0000003,
+        "cache_write": 0.00000375
+      },
+      "input_modalities": ["text", "image"],
+      "output_modalities": ["text"]
+    }
+  ]
+}
+```
+
+**Model object fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | OpenRouter model identifier (e.g. `anthropic/claude-sonnet-4.6`) |
+| `name` | string | Human-readable display name |
+| `context_length` | integer\|null | Context window size in tokens |
+| `max_completion_tokens` | integer\|null | Maximum output tokens the provider allows |
+| `pricing.prompt` | number | Price per input token in USD |
+| `pricing.completion` | number | Price per output token in USD |
+| `pricing.cache_read` | number | Price per cached input token (0 if not applicable) |
+| `pricing.cache_write` | number | Price per cache-write token (0 if not applicable) |
+| `input_modalities` | string[] | Supported input types (e.g. `["text", "image"]`) |
+| `output_modalities` | string[] | Supported output types |
+
+**Example**
+```bash
+curl http://localhost:5050/models
+```
+
+---
+
+## GET /models/:provider/:name
+
+Get a single model by its two-part ID.
+
+**Path parameters**
+
+| Param | Description |
+|-------|-------------|
+| `provider` | Provider slug, e.g. `anthropic` |
+| `name` | Model slug, e.g. `claude-sonnet-4.6` |
+
+**Response** — same shape as a single entry from `GET /models`
+
+**Error responses**
+
+| Code | Condition |
+|------|-----------|
+| `404 MODEL_NOT_FOUND` | Model ID not in the local index |
+
+**Example**
+```bash
+curl http://localhost:5050/models/anthropic/claude-sonnet-4.6
+```
+
+---
+
+## POST /models/refresh
+
+Re-fetch the full model list from OpenRouter and reload the in-memory cache.
+
+Internally runs `scripts/fetch-models.js`, which writes the result to `config/models.json`.
+
+**Response**
+```json
+{
+  "refreshed": true,
+  "updated_at": "2026-03-06T03:15:22.000Z",
+  "models": [ ... ]
+}
+```
+
+**Example**
+```bash
+curl -X POST http://localhost:5050/models/refresh
+```
+
+---
+
+## CLI Shortcut
+
+```bash
+npm run fetch-models
+```
+
+Runs the same fetch script directly, without starting the server.
+
+---
+
+## Internal Usage
+
+- **`context_size_limit` on sessions** — when a new session is created (`POST /sessions` or first chat turn), `createSession` looks up the model in the index and stores its `context_length` as `context_size_limit` on the session row.
+- **Cost fallback in the loop** — after each LLM turn, if the API response does not include a `usage.cost` field (or returns `0`), the loop calculates an estimated cost using `pricing.prompt`, `pricing.completion`, and `pricing.cache_read` from the index.