@action-llama/action-llama 0.13.5 → 0.13.7

package/agent-docs/AGENTS.md

@@ -1,6 +1,6 @@
 # Action Llama Reference
 
-Action Llama is a CLI tool for running LLM agents as automated scripts. Agents run on cron schedules and/or in response to webhooks (GitHub, Sentry, Linear, Mintlify). Each agent is an LLM session that receives a system prompt (ACTIONS.md), gets credentials injected, and runs inside an isolated Docker container. The scheduler manages agent lifecycles, and a gateway HTTP server handles webhooks, resource locking, agent-to-agent calls, and an optional web dashboard.
+CLI for running LLM agents on cron/webhooks. Docker isolation, ACTIONS.md prompt, credentials. Gateway: webhooks, locking, agent calls, dashboard.
 
 Package: `@action-llama/action-llama`. CLI binary: `al`.
 
@@ -19,38 +19,23 @@ my-project/
     Dockerfile             # Custom Docker image for this agent (optional)
 ```
 
-Agent names are derived from the directory name. `"default"` is a reserved name and cannot be used as an agent name.
-
-## Agent Docs
-
-| File | Scope | Purpose |
-|------|-------|---------|
-| `ACTIONS.md` | Per-agent (required) | System prompt injected as the LLM's system message at runtime |
-| `AGENTS.md` | Project root | Shared instructions loaded by `al chat` (interactive console only — not injected into automated runs) |
-| `CLAUDE.md` | Project root | Instructions for AI development tools (Claude Code, etc.). Not read by Action Llama at runtime. |
+Agent names derive from directory name. `"default"` is reserved.
 
 ### ACTIONS.md — Writing Tips
 
-- Write as direct instructions to an LLM: "You are an automation agent. Your job is to..."
-- Use numbered steps for the workflow — be specific about what commands to run
-- Reference `<agent-config>` for parameter values instead of hardcoding repo names, labels, etc.
-- Handle both trigger types if the agent uses both schedule and webhooks
-- Use `al-status` at natural milestones so operators can see progress in the TUI/dashboard
-- Use `al-rerun` when the agent completed work and there may be more items in the backlog
-- Keep it concise — the system prompt consumes tokens every run
+- Direct LLM instructions; numbered steps; reference `<agent-config>` for params
+- `al-status` at milestones, `al-rerun` when backlog remains; keep concise
 
 ## Prompt Assembly
 
-Understanding how the prompt is assembled is critical for writing effective ACTIONS.md files. The LLM receives two messages:
+The LLM receives two messages:
 
 ### System message
 
-The contents of `ACTIONS.md` are sent as the system prompt. If the agent has locking or calling skills enabled (determined by the scheduler based on gateway availability and agent config), **skill blocks** are appended to teach the agent how to use those capabilities.
+`ACTIONS.md` is the system prompt. With gateway, **skill blocks** appended:
 
 #### Locking skill block (injected when gateway is available)
 
-The following is prepended when the agent may need resource locking:
-
 ```xml
 <skill-lock>
 ## Skill: Resource Locking
@@ -99,8 +84,6 @@ rlock-heartbeat "github issue acme/app#42"
 
 #### Calling skill block (injected when gateway is available)
 
-The following is prepended when agent-to-agent calling is available:
-
 ```xml
 <skill-call>
 ## Skill: Agent-to-Agent Calls
@@ -150,11 +133,9 @@ echo "Line 1\nLine 2" | al-return
 
 ### User message
 
-The user message is built from a **static skeleton** (baked into the Docker image at build time) plus a **dynamic suffix** (passed at runtime based on trigger type).
+Static skeleton + dynamic suffix. Static blocks:
 
-The static skeleton contains these XML blocks in order:
-
-**`<agent-config>`** — JSON of the `[params]` table from `agent-config.toml`:
+**`<agent-config>`** — `[params]` as JSON:
 
 ```xml
 <agent-config>
@@ -162,7 +143,7 @@ The static skeleton contains these XML blocks in order:
 </agent-config>
 ```
 
-**`<credential-context>`** — Lists available environment variables and tools based on the agent's credentials. Also includes git clone protocol guidance and the anti-exfiltration policy:
+**`<credential-context>`** — env vars, tools, anti-exfiltration:
 
 ```xml
 <credential-context>
@@ -183,7 +164,7 @@ Use standard tools directly: `gh` CLI, `git`, `curl`.
 </credential-context>
 ```
 
-**`<environment>`** — Filesystem constraints:
+**`<environment>`** — Filesystem:
 
 ```xml
 <environment>
@@ -194,7 +175,7 @@ All write operations (git clone, file creation, etc.) must target `/tmp`.
 </environment>
 ```
 
-**Dynamic suffix** — appended based on trigger type:
+**Dynamic suffix** — by trigger type:
 
 | Trigger | Suffix |
 |---------|--------|
@@ -203,7 +184,7 @@ All write operations (git clone, file creation, etc.) must target `/tmp`.
 | Webhook | `<webhook-trigger>` block with event JSON, then `"A webhook event just fired. Review the trigger context above and take appropriate action."` |
 | Agent call | `<agent-call>` block with caller/context JSON, then `"You were called by the "<name>" agent. Review the call context above, do the requested work, and use al-return to send back your result."` |
 
-**`<webhook-trigger>`** example (webhook runs only):
+**`<webhook-trigger>`** example:
 
 ```json
 {
@@ -225,7 +206,7 @@ All write operations (git clone, file creation, etc.) must target `/tmp`.
 }
 ```
 
-**`<agent-call>`** example (agent call runs only):
+**`<agent-call>`** example:
 
 ```json
 {
@@ -236,7 +217,7 @@ All write operations (git clone, file creation, etc.) must target `/tmp`.
 
 ## config.toml
 
-The project-level `config.toml` lives at the root of your Action Llama project. All sections and fields are optional — sensible defaults are used for anything you omit.
+Project root. All sections optional — sensible defaults apply.
 
 ### Full Annotated Example
 
@@ -302,7 +283,7 @@ endpoint = "https://telemetry.example.com/v1"   # OpenTelemetry endpoint
 
 ### `[model]` — Default LLM
 
-Default model configuration inherited by all agents that don't define their own `[model]` section in `agent-config.toml`.
+Default for agents without `[model]` in agent-config.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -313,7 +294,7 @@ Default model configuration inherited by all agents that don't define their own
 
 ### `[local]` — Docker Container Settings
 
-Controls local Docker container isolation.
+Local Docker container settings.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -324,7 +305,7 @@ Controls local Docker container isolation.
 
 ### `[gateway]` — HTTP Server
 
-The gateway starts automatically when Docker mode or webhooks are enabled. It handles health checks, webhook reception, credential serving (local Docker only), resource locking, and the shutdown kill switch.
+Starts automatically when Docker mode or webhooks enabled.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -333,14 +314,14 @@ The gateway starts automatically when Docker mode or webhooks are enabled. It ha
 
 ### `[webhooks.<name>]` — Webhook Sources
 
-Named webhook sources that agents can reference in their `[[webhooks]]` triggers. Each source defines a provider type and an optional credential for signature validation.
+Named sources agents reference in `[[webhooks]]` triggers.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `type` | string | Yes | Provider type: `"github"`, `"sentry"`, `"linear"`, or `"mintlify"` |
-| `credential` | string | No | Credential instance name for HMAC signature validation (e.g. `"MyOrg"` maps to `github_webhook_secret:MyOrg`). Omit for unsigned webhooks. |
+| `credential` | string | No | Instance name for HMAC validation (e.g. `"MyOrg"` -> `github_webhook_secret:MyOrg`). Omit for unsigned. |
 
-Agents reference these sources by name in their `agent-config.toml`:
+Agents reference by name:
 
 ```toml
 [[webhooks]]
@@ -356,7 +337,7 @@ events = ["issues"]
 
 ## agent-config.toml
 
-Each agent has an `agent-config.toml` file in its directory. The agent name is derived from the directory name and should not be included in the config.
+Per-agent config. Name derives from directory.
 
 ### Full Annotated Example
 
@@ -458,41 +439,25 @@ sentryProjects = ["web-app", "api"]
 | `preflight` | array | No | Array of preflight steps that run before the LLM session. |
 | `params` | table | No | Custom key-value params injected into the prompt as `<agent-config>` |
 
-*At least one of `schedule` or `webhooks` is required (unless `scale = 0`). *Required within `[model]` if the agent defines its own model block (otherwise inherits from project `config.toml`).
+*Need `schedule` or `webhooks` (unless `scale=0`). *Required in `[model]` if defined.
 
 ### Scale
 
-The `scale` field controls how many instances of an agent can run concurrently.
-
-- **Default**: 1 (only one instance can run at a time)
-- **Minimum**: 0 (disables the agent — no runners, cron jobs, or webhook bindings are created)
-- **Maximum**: No hard limit, but consider system resources and model API rate limits
-
-How it works:
-
-1. **Scheduled runs**: If a cron trigger fires but all agent instances are busy, the scheduled run is skipped with a warning
-2. **Webhook events**: If a webhook arrives but all instances are busy, the event is queued (up to `workQueueSize` limit in global config, default: 100)
-3. **Agent calls**: If one agent calls another but all target instances are busy, the call is queued in the same work queue
-
-Each parallel instance uses a separate Docker container, has independent logging, and may consume LLM API quota concurrently.
+Default: 1. Set 0 to disable. Busy: scheduled skipped, webhooks/calls queued.
 
 ### Timeout
 
-The `timeout` field controls the maximum runtime for an agent invocation. When the timeout expires, the container is terminated with exit code 124.
-
-**Resolution order:** `agent-config.toml timeout` → `config.toml [local].timeout` → `900` (default)
+Max runtime per invocation. Container terminated with exit 124 on expiry.
 
-This means you can set a project-wide default in `[local].timeout` and override it per-agent.
+Resolves: agent -> project `[local].timeout` -> `900`.
 
 ### Preflight
 
-Preflight steps run mechanical data-staging tasks after credentials are loaded but before the LLM session starts. They fetch data, clone repos, or run commands to prepare the workspace so the agent starts with everything it needs — instead of spending tokens fetching context at runtime.
+Stage data after credentials load, before LLM session.
 
-Steps run **sequentially** in the order they appear in `agent-config.toml`, **inside the container** (or host process in `--no-docker` mode) after credential/env setup. Providers write files to disk — your ACTIONS.md references the staged files.
+Sequential, inside container. `${VAR_NAME}` interpolation in params.
 
-Environment variable interpolation is supported: `${VAR_NAME}` in string params is resolved against `process.env` (which already has credentials injected).
-
-Each `[[preflight]]` entry has these fields:
+Fields:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -502,7 +467,7 @@ Each `[[preflight]]` entry has these fields:
 
 #### `shell` provider
 
-Runs a command via `/bin/sh`. Optionally captures stdout to a file.
+Runs a command via `/bin/sh`.
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -519,7 +484,7 @@ output = "/tmp/context/issues.json"
 
 #### `http` provider
 
-Fetches a URL and writes the response body to a file.
+Fetches a URL, writes response to file.
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -541,7 +506,7 @@ headers = { Authorization = "Bearer ${INTERNAL_TOKEN}" }
 
 #### `git-clone` provider
 
-Clones a git repository. Short `"owner/repo"` names are expanded to `git@github.com:owner/repo.git`; full URLs are passed through. Git credentials (SSH key, HTTPS token) are already configured from the agent's credentials.
+`"owner/repo"` expands to `git@github.com:owner/repo.git`.
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -560,14 +525,11 @@ branch = "main"
 depth = 1
 ```
 
-Notes:
-- The `shell` provider is the escape hatch — anything a built-in provider doesn't cover can be expressed as a shell command
-- There is no per-step timeout — steps are bounded by the container-level timeout
-- Environment variables set inside `shell` child processes do not propagate back to the agent's `process.env`
+`shell` is the escape hatch. No per-step timeout. Shell env vars don't propagate back (see [Environment variable persistence](#environment-variable-persistence) for a workaround).
 
 ### Webhook Trigger Fields
 
-Each `[[webhooks]]` entry has a required `source` field referencing a named webhook source from the project's `config.toml`. All filter fields below are optional. Omit all of them to trigger on everything from that source. All specified filters use AND logic — all must match for the agent to trigger.
+Required `source` from `config.toml`. Filters optional (AND logic).
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -614,68 +576,19 @@ Each `[[webhooks]]` entry has a required `source` field referencing a named webh
 | `actions` | string[] | Event actions: failed, succeeded, etc. |
 | `branches` | string[] | Only for these branches |
 
-### TOML Syntax Reminders
-
-- Strings: `key = "value"`
-- Arrays: `key = ["a", "b"]`
-- Tables (objects): `[tableName]` on its own line, followed by key-value pairs
-- Array of tables: `[[arrayName]]` on its own line — each block is one entry in the array
-- Inline tables: `headers = { Authorization = "Bearer ${TOKEN}" }`
-- Comments: `# comment`
-
-Example with multiple webhooks (each `[[webhooks]]` is a separate trigger):
-
-```toml
-[[webhooks]]
-source = "my-github"
-events = ["issues"]
-actions = ["labeled"]
-labels = ["agent"]
-
-[[webhooks]]
-source = "my-github"
-events = ["pull_request"]
-
-[[webhooks]]
-source = "my-sentry"
-resources = ["error", "event_alert"]
-```
-
 ### Model Configuration
 
-The `[model]` section is optional — agents inherit the default model from the project's `config.toml`. Only add `[model]` to an agent config if you want to override the default for that specific agent. If an agent defines its own `[model]` section, it fully overrides the project default — there is no field-level merging.
+Optional. If defined, fully overrides project default (no merging).
 
 ## Credentials
 
-Credentials are stored in `~/.action-llama/credentials/<type>/<instance>/<field>`. Each credential type is a directory containing one file per field. Reference them in `agent-config.toml` by type name (e.g. `"github_token"`) for the `default` instance, or use `"type:instance"` for a named instance (e.g. `"git_ssh:botty"`).
+Path: `~/.action-llama/credentials/<type>/<instance>/<field>`.
 
-**IMPORTANT:** Agents MUST NEVER ask users for credentials directly (API keys, tokens, passwords, etc.). Agents MUST NEVER run `al doctor` or interact with the credential system on behalf of the user. If a credential is missing at runtime, the agent should report the error and stop — the user will run `al doctor` and `al start` themselves.
+**Agents MUST NEVER ask for credentials or run `al doctor`. Missing = report and stop.**
 
 ### How credentials work
 
-1. **Configuration**: List credential types in your agent's `agent-config.toml`:
-   ```toml
-   credentials = ["github_token", "git_ssh"]
-   ```
-
-2. **Storage**: Credential values live in `~/.action-llama/credentials/<type>/<instance>/<field>`. Each field is a plain text file.
-
-3. **Injection**: When an agent runs, the credentials it requires are mounted into the container at `/credentials/<type>/<instance>/<field>` and key values are injected as environment variables.
-
-4. **Git identity**: The `git_ssh` credential includes `username` and `email` fields. These are injected as `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL` and `GIT_COMMITTER_NAME`/`GIT_COMMITTER_EMAIL` env vars at runtime, so `git commit` works without requiring `git config`.
-
-5. **LLM credentials**: The LLM credential (e.g. `anthropic_key`) does not need to be listed in the agent's `credentials` array — it is loaded automatically based on the `[model]` config.
-
-### Named instances
-
-Each credential type supports named instances. Reference `"git_ssh"` for the default instance, or `"git_ssh:botty"` for a named instance:
-
-```
-~/.action-llama/credentials/git_ssh/default/id_rsa
-~/.action-llama/credentials/git_ssh/default/username
-~/.action-llama/credentials/git_ssh/botty/id_rsa
-~/.action-llama/credentials/git_ssh/botty/username
-```
+List in `agent-config.toml`. Mounted at `/credentials/...`, key values as env vars. `git_ssh` sets `GIT_AUTHOR_*`/`GIT_COMMITTER_*`. LLM creds auto-loaded from `[model]`.
 
 ### Agent runtime credentials
 
@@ -710,11 +623,11 @@ Each credential type supports named instances. Reference `"git_ssh"` for the def
 | `linear_webhook_secret` | `secret` | Shared secret for Linear webhook verification |
 | `mintlify_webhook_secret` | `secret` | Shared secret for Mintlify webhook verification |
 
-Used by the gateway for payload verification — not injected into agent containers. The gateway automatically loads secrets from all credential instances and uses them to verify incoming webhook payloads.
+Gateway only — not in agent containers.
 
 ### Infrastructure credentials
 
-These are used by CLI commands (provisioning, deployment) and are not injected into agent containers.
+CLI only (provisioning, deployment).
 
 | Type | Fields | Description |
 |------|--------|-------------|
@@ -734,7 +647,7 @@ These are used by CLI commands (provisioning, deployment) and are not injected i
 
 ## Models
 
-Action Llama supports 8 LLM providers. Each agent can use a different provider and model — configure a project-wide default in `config.toml` under `[model]`, and override per agent in `agent-config.toml`.
+8 providers. Default in `config.toml [model]`, override per agent.
 
 | Provider | Credential | Example Models | Auth Types |
 |----------|-----------|---------------|------------|
@@ -758,94 +671,37 @@ Action Llama supports 8 LLM providers. Each agent can use a different provider a
 | `high` | Deep reasoning |
 | `xhigh` | Maximum reasoning budget |
 
-If omitted, thinking is not explicitly configured. For non-Anthropic providers, `thinkingLevel` is ignored.
-
-### Model inheritance
-
-Agents without a `[model]` section inherit from the project `config.toml`. If an agent defines its own `[model]`, it fully overrides the project default — there is no field-level merging between the two.
-
-```
-config.toml               → [model] provider = "anthropic", model = "claude-sonnet-4-20250514"
-dev/agent-config.toml      → (no [model] section — inherits Claude Sonnet)
-reviewer/agent-config.toml → [model] provider = "openai", model = "gpt-4o"
-devops/agent-config.toml   → [model] provider = "groq", model = "llama-3.3-70b-versatile"
-```
-
-The LLM credential does not need to be listed in the agent's `credentials` array — it is loaded automatically based on the `[model]` config.
+Non-Anthropic providers ignore `thinkingLevel`.
 
 ## Webhooks
 
-Agents can be triggered by webhooks in addition to (or instead of) cron schedules. Four providers are supported: GitHub, Sentry, Linear, and Mintlify.
-
-### Defining webhook sources
-
-Webhook sources are defined once in the project's `config.toml`. Each source has a name, a provider type, and an optional credential for signature validation:
-
-```toml
-[webhooks.my-github]
-type = "github"
-credential = "MyOrg"          # credential instance name (github_webhook_secret:MyOrg)
-
-[webhooks.my-sentry]
-type = "sentry"
-credential = "SentryProd"     # credential instance name (sentry_client_secret:SentryProd)
-
-[webhooks.my-linear]
-type = "linear"
-credential = "LinearMain"     # credential instance name (linear_webhook_secret:LinearMain)
-
-[webhooks.my-mintlify]
-type = "mintlify"
-credential = "MintlifyMain"   # credential instance name (mintlify_webhook_secret:MintlifyMain)
-```
+Webhook triggers for agents.
 
 ### Runtime flow
 
-1. The gateway receives a webhook POST request at `/webhooks/<type>` (e.g. `/webhooks/github`)
-2. It verifies the payload signature using secrets loaded from the credential instances defined in `config.toml` webhook sources
-3. It parses the event into a `WebhookContext` (source, event, action, repo, etc.)
-4. It matches the context against each agent's webhook triggers (AND logic — all specified filter fields must match; omitted fields are not checked)
-5. Matching agents are triggered with the webhook context injected into their prompt as a `<webhook-trigger>` block
-
-### Webhook endpoints
-
-| Provider | Endpoint |
-|----------|----------|
-| GitHub | `/webhooks/github` |
-| Sentry | `/webhooks/sentry` |
-| Linear | `/webhooks/linear` |
-| Mintlify | `/webhooks/mintlify` |
-
-### Queue behavior
-
-If all runners for a matching agent are busy, webhook events are queued (up to `workQueueSize`, default: 100). Scheduled runs are skipped if all busy.
-
-### Hybrid agents
-
-Agents can have both `schedule` and `webhooks`. Scheduled runs poll for work proactively; webhook runs respond to events immediately.
+POST `/webhooks/<type>` -> verify -> match triggers (AND) -> trigger agent. Busy: queued.
 
 ## Agent Commands
 
-Agents have access to shell commands for signaling the scheduler, calling other agents, and coordinating with resource locks. These commands are installed at `/app/bin/` (baked into the Docker image) and added to `PATH` at container startup. The preamble skill blocks (see Prompt Assembly above) teach agents the commands and their response formats.
+At `/app/bin/` (in `PATH`). Skill blocks teach usage.
 
 ### Signal commands
 
-Signal commands write signal files that the scheduler reads after the session ends.
+Write signal files for scheduler.
 
 #### `al-rerun`
 
-Request an immediate rerun to drain remaining backlog. Without this, the scheduler treats the run as complete and waits for the next scheduled tick.
+Request immediate rerun to drain backlog.
 
 ```bash
 al-rerun
 ```
 
-- Only applies to **scheduled** runs. Webhook-triggered and agent-called runs do not re-run.
-- Reruns continue until the agent completes without calling `al-rerun`, hits an error, or reaches the `maxReruns` limit (default: 10).
+Scheduled only. Until no `al-rerun`, error, or `maxReruns` (10).
 
 #### `al-status "<text>"`
 
-Update the status text shown in the TUI and web dashboard.
+Update status text in TUI/dashboard.
 
 ```bash
 al-status "reviewing PR #42"
@@ -854,85 +710,71 @@ al-status "found 3 issues to work on"
 
 #### `al-return "<value>"`
 
-Return a value to the calling agent. Used when this agent was invoked via `al-call`.
+Return a value to the calling agent (when invoked via `al-call`).
 
 ```bash
 al-return "PR looks good. Approved with minor suggestions."
 al-return '{"approved": true, "comments": 2}'
 ```
 
-For multiline results, pipe via stdin:
+For multiline, pipe via stdin:
 
 ```bash
 echo "Line 1\nLine 2" | al-return
 ```
 
-The calling agent receives this value when it calls `al-wait`.
-
 #### `al-exit [code]`
 
-Terminate the agent with an exit code indicating an unrecoverable error. Defaults to exit code 15.
+Terminate with exit code (default: 15).
 
 ```bash
 al-exit          # exit code 15
 al-exit 1        # exit code 1
 ```
 
-Standard exit codes: 10 (auth failure), 11 (permission denied), 12 (rate limited), 13 (config error), 14 (dependency error), 15 (unrecoverable), 16 (user abort).
+Codes: 10=auth, 11=perm, 12=rate, 13=config, 14=dep, 15=unrecoverable, 16=abort.
 
 ### Call commands
 
-Agent-to-agent calls allow agents to delegate work and collect results. These commands require the gateway (`GATEWAY_URL` must be set).
+Require gateway.
 
 #### `al-call <agent>`
 
-Call another agent. Pass context via stdin. Returns a JSON response with a `callId`.
+Call another agent. Pass context via stdin.
 
 ```bash
 echo "Review PR #42 on acme/app" | al-call reviewer
 ```
 
-**Response:**
-
 ```json
 {"ok": true, "callId": "abc123"}
-```
-
-**Errors:**
-
-```json
 {"ok": false, "error": "self-call not allowed"}
 {"ok": false, "error": "queue full"}
 ```
 
 #### `al-check <callId>`
 
-Non-blocking status check on a call. Never blocks.
+Non-blocking status check.
 
 ```bash
 al-check abc123
 ```
 
-**Response:**
-
 ```json
 {"status": "pending"}
-{"status": "running"}
 {"status": "completed", "returnValue": "PR approved."}
 {"status": "error", "error": "timeout"}
 ```
 
 #### `al-wait <callId> [...] [--timeout N]`
 
-Wait for one or more calls to complete. Polls every 5 seconds. Default timeout: 900 seconds.
+Wait for calls. Polls every 5s. Default timeout: 900s.
 
 ```bash
 al-wait abc123 --timeout 600
 al-wait abc123 def456 --timeout 300
 ```
 
-**Response:**
-
 ```json
 {
   "abc123": {"status": "completed", "returnValue": "PR approved."},
@@ -957,436 +799,123 @@ echo "$RESULTS" | jq ".\"$TEST_ID\".returnValue"
 
 #### Call rules
 
-- An agent cannot call itself (self-calls are rejected)
-- If all runners for the target agent are busy, the call is queued (up to `workQueueSize`, default: 100)
-- Call chains are allowed (A calls B, B calls C) up to `maxCallDepth` (default: 3)
-- Called runs do not re-run — they respond to the single call
-- The called agent receives an `<agent-call>` block with the caller name and context
-- To return a value, the called agent uses `al-return`
+No self-calls. Chains up to `maxCallDepth` (3). Use `al-return` to respond.
 
 ### Lock commands
 
-Resource locks prevent multiple agent instances from working on the same resource. The underlying shell commands are `rlock`, `runlock`, and `rlock-heartbeat`.
+Prevent duplicate work across instances.
 
 #### `rlock`
 
-Acquire an exclusive lock on a resource.
+Acquire exclusive lock.
 
 ```bash
 rlock "github issue acme/app#42"
 ```
 
-**Success:**
+Responses:
 
 ```json
 {"ok": true}
-```
-
-**Already held:**
-
-```json
 {"ok": false, "holder": "dev-abc123", "heldSince": "2025-01-15T10:30:00Z"}
-```
-
-**Already holding another lock:**
-
-```json
 {"ok": false, "reason": "already holding lock on ..."}
-```
-
-**Deadlock detected:**
-
-```json
 {"ok": false, "reason": "possible deadlock detected", "cycle": ["dev-abc", "github pr acme/app#10", "dev-def", "deploy api-prod"]}
 ```
 
 #### `runlock`
 
-Release a lock. Only the holder can release.
+Release a lock (holder only).
 
 ```bash
 runlock "github issue acme/app#42"
 ```
 
-**Success:**
-
 ```json
 {"ok": true}
-```
-
-**Not holder:**
-
-```json
 {"ok": false, "reason": "not the lock holder"}
 ```
 
 #### `rlock-heartbeat`
 
-Reset the TTL on a held lock. Use during long-running work to prevent the lock from expiring.
+Reset TTL on held lock during long work.
 
 ```bash
 rlock-heartbeat "github issue acme/app#42"
 ```
 
-**Success:**
-
 ```json
 {"ok": true, "expiresAt": "2025-01-15T11:00:00Z"}
 ```
 
 #### Lock behavior
 
-- Each container gets a unique per-run secret. Lock requests are authenticated with this secret, so only the container that acquired a lock can release or heartbeat it.
-- When a container exits — whether it finishes successfully, hits an error, or times out — all of its locks are released automatically by the scheduler.
-- An agent can hold **at most one lock at a time**. Release your current lock before acquiring another.
-- Locks expire automatically after `lockTimeout` seconds (default: 1800 / 30 minutes) if not refreshed via heartbeat.
-- Use descriptive keys: `"github issue acme/app#42"`, `"deploy api-prod"`
+Per-run secret auth. Auto-release on exit. **One at a time**. Expire after `lockTimeout` (1800s).
 
 #### Lock graceful degradation
 
-When `GATEWAY_URL` is not set (e.g. non-containerized local runs), lock commands exit 0 with `{"ok":true}` — graceful degradation so agents work without a gateway.
-
-Call commands (`al-call`, `al-check`, `al-wait`) exit 5 when `GATEWAY_URL` is not set — they require a gateway.
+No gateway: locks degrade gracefully (exit 0). Calls exit 5.
 
 ## CLI Commands
 
-### `al new <name>`
-
-Creates a new Action Llama project. Runs interactive setup to configure credentials and LLM defaults.
-
-```bash
-npx @action-llama/action-llama new my-project
-```
-
-Creates:
-- `my-project/package.json` — with `@action-llama/action-llama` dependency
-- `my-project/.gitignore`
-- `my-project/.workspace/` — runtime state directory
-- Credential files in `~/.action-llama/credentials/`
-
-### `al doctor`
-
-Checks all agent credentials and interactively prompts for any that are missing. Discovers agents in the project, collects their credential requirements (plus any webhook secret credentials), and ensures each one exists on disk. Also generates a gateway API key if one doesn't exist yet.
-
-Additionally validates webhook trigger field configurations to catch common errors like using `repository` instead of `repos`, misspelled field names, or invalid field types.
-
-```bash
-al doctor
-al doctor -E production
-```
+### `al new <name>` — Create project
 
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name — pushes credentials to server and reconciles IAM |
+### `al doctor` — Check/prompt for missing credentials. `-E` pushes to server.
 
-### `al run <agent>`
+### `al run <agent>` — Single run for testing (`-H` headless)
 
-Manually triggers a single agent run. The agent runs once and the process exits when it completes. Useful for testing, debugging, or one-off runs without starting the full scheduler.
+### `al start` — Start scheduler (`-w` dashboard, `-e` expose, `-H` headless, `--port <N>`)
 
-```bash
-al run dev
-al run reviewer -p ./my-project
-al run dev -E production
-al run dev --headless
-```
+### `al stop` — Stop scheduler (in-flight runs finish)
 
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-| `-H, --headless` | Non-interactive mode (no TUI, no credential prompts) |
+### `al stat` — Agent status overview
 
-### `al start`
+### `al logs <agent>` — View logs (`-n`, `-f`, `-d`, `-r`, `-i`)
 
-Starts the scheduler. Runs all agents on their configured schedules and listens for webhooks.
+### `al pause/resume [name]` — Pause/resume scheduler or agent
 
-```bash
-al start
-al start -w                   # Enable web dashboard
-al start -e                   # VPS deployment: expose gateway publicly
-al start --port 3000          # Custom gateway port
-al start -H                   # Headless (no TUI)
-```
+### `al kill <target>` — Kill agent or instance
 
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-| `-w, --web-ui` | Enable web dashboard |
-| `-e, --expose` | Bind gateway to `0.0.0.0` (public) while keeping local-mode features |
-| `-H, --headless` | Non-interactive mode (no TUI, no credential prompts) |
-| `--port <number>` | Gateway port (overrides `[gateway].port` in config) |
+### `al chat [agent]` — Interactive console (with agent: credentials injected)
 
-### `al stop`
+### `al push [agent]` — Deploy via SSH (full or hot-reload single agent)
 
-Stops the scheduler and clears all pending agent work queues. Sends a stop signal to the gateway. In-flight runs continue until they finish, but no new runs will start.
-
-```bash
-al stop
-al stop -E production
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-
-### `al stat`
-
-Shows status of all discovered agents in the project. Displays each agent's schedule, credentials, webhook configuration, and queue depth.
-
-```bash
-al stat
-al stat -E production
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-
-### `al logs <agent>`
-
-View log files for a specific agent.
-
-```bash
-al logs dev
-al logs dev -n 100            # Show last 100 entries
-al logs dev -f                # Follow/tail mode
-al logs dev -d 2025-01-15    # Specific date
-al logs dev -r                # Raw JSON log output
-al logs dev -i abc123         # Specific instance
-al logs dev -E production     # Remote agent logs
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-| `-n, --lines <N>` | Number of log entries (default: 50) |
-| `-f, --follow` | Tail mode — watch for new entries |
-| `-d, --date <YYYY-MM-DD>` | View a specific date's log file |
-| `-r, --raw` | Raw JSON log output (no formatting) |
-| `-i, --instance <id>` | Filter to a specific instance ID |
-
-### `al pause [name]`
-
-Pause the scheduler or a single agent. Without a name, pauses the entire scheduler — all cron jobs stop firing. With a name, pauses that agent — its cron job stops firing and webhook events are ignored. In-flight runs continue until they finish. Requires the gateway.
-
-```bash
-al pause                              # Pause the scheduler
-al pause dev                          # Pause a single agent
-al pause dev -E production
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-
-### `al resume [name]`
-
-Resume the scheduler or a single agent. Without a name, resumes the entire scheduler. With a name, resumes that agent — its cron job resumes firing and webhooks are accepted again.
-
-```bash
-al resume                             # Resume the scheduler
-al resume dev                         # Resume a single agent
-al resume dev -E production
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-
-### `al kill <target>`
-
-Kill an agent (all running instances) or a single instance by ID. Tries the target as an agent name first; if not found, falls back to instance ID. This does **not** pause the agent — if it has a schedule, a new run will start at the next cron tick. To fully stop an agent, pause it first, then kill.
-
-```bash
-al kill dev                           # Kill all instances of an agent
-al kill my-agent-abc123               # Kill a single instance by ID
-al kill dev -E production
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name |
-
-### `al chat [agent]`
-
-Open an interactive console. Without an agent name, opens the project-level console for creating and managing agents. With an agent name, opens an interactive session scoped to that agent's environment — credentials are loaded and injected as environment variables (e.g. `GITHUB_TOKEN`, `GIT_SSH_COMMAND`), and the working directory is set to the agent's directory.
-
-```bash
-al chat                # project-level console
-al chat dev            # interactive session with dev agent's credentials
-```
-
-| Option | Description |
-|--------|-------------|
-| `[agent]` | Agent name — loads its credentials and environment |
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-When running in agent mode, the command probes the gateway and warns if it is not reachable:
-
-```
-Warning: No gateway detected at http://localhost:8080. Resource locks, agent calls, and signals are unavailable.
-Start the scheduler with `al start` to enable these features.
-```
-
-The agent's ACTIONS.md is loaded as reference context but is **not** auto-executed — you drive the session interactively.
-
-### `al push [agent]`
-
-Deploy your project to a server over SSH. Requires a `[server]` section in your environment file.
-
-```bash
-al push -E production                    # Full project push
-al push dev -E production                # Push only the dev agent (hot-reloaded)
-al push --dry-run -E production          # Preview what would be synced
-al push --creds-only -E production       # Sync only credentials
-```
-
-Without an agent name, pushes the entire project and can restart the remote service. With an agent name, pushes only that agent's files and credentials — the running scheduler detects the change and hot-reloads the agent without a full restart.
-
-| Option | Description |
-|--------|-------------|
-| `[agent]` | Agent name — push only this agent (hot-reloaded, no restart) |
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment with `[server]` config |
-| `--dry-run` | Show what would be synced without making changes |
-| `--no-creds` | Skip credential sync |
-| `--creds-only` | Sync only credentials (skip project files) |
-| `--files-only` | Sync only project files (skip credentials) |
-| `-a, --all` | Sync project files, credentials, and restart service |
-| `--force-install` | Force `npm install` even if dependencies appear unchanged |
+`--dry-run`, `--no-creds`, `--creds-only`, `--files-only`, `-a`, `--force-install`.
 
 ### Environment commands
 
-#### `al env init <name>`
-
-Create a new environment configuration file at `~/.action-llama/environments/<name>.toml`.
-
-```bash
-al env init production --type server
-```
-
-| Option | Description |
-|--------|-------------|
-| `--type <type>` | Environment type: `server` |
-
-#### `al env list`
-
-List all configured environments.
-
-#### `al env show <name>`
-
-Display the contents of an environment configuration file.
-
-#### `al env set [name]`
-
-Bind the current project to an environment by writing the environment name to `.env.toml`. Omit the name to unbind.
-
-```bash
-al env set production        # Bind project to "production"
-al env set                   # Unbind project from any environment
-```
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-#### `al env check <name>`
-
-Verify that an environment is provisioned and configured correctly. Checks SSH connectivity, Docker availability, and server readiness.
-
-#### `al env prov [name]`
-
-Provision a new VPS and save it as an environment. Supports Vultr and Hetzner. If the name is omitted, you'll be prompted for one.
+#### `al env init <name>` — Create at `~/.action-llama/environments/<name>.toml`
 
-#### `al env deprov <name>`
+#### `al env list` / `al env show <name>` — List or show environments
 
-Tear down a provisioned environment. Stops containers, cleans up remote credentials, optionally deletes DNS records, and optionally deletes the VPS instance if it was provisioned via `al env prov`.
+#### `al env set [name]` — Bind/unbind project to environment (`.env.toml`)
 
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-#### `al env logs [name]`
+#### `al env check <name>` — Verify SSH, Docker, server readiness
 
-View server system logs (systemd journal) via SSH. If the name is omitted, uses the project's bound environment.
+#### `al env prov [name]` — Provision VPS (Vultr/Hetzner)
 
-```bash
-al env logs production
-al env logs production -n 200     # Last 200 lines
-al env logs production -f          # Follow mode
-```
+#### `al env deprov <name>` — Tear down environment
 
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-n, --lines <N>` | Number of log lines (default: 50) |
-| `-f, --follow` | Tail mode — watch for new entries |
+#### `al env logs [name]` — Server logs via SSH (`-n`, `-f`)
 
 ### Credential commands
 
-#### `al creds ls`
-
-Lists all stored credentials grouped by type, showing field names but not values.
-
-#### `al creds add <ref>`
-
-Add or update a credential. Runs the interactive prompter with validation for the credential type.
+#### `al creds ls` — List credentials (names, not values)
 
-```bash
-al creds add github_token              # adds github_token:default
-al creds add github_webhook_secret:myapp
-al creds add git_ssh:prod
-```
+#### `al creds add <ref>` — Add/update (`github_token` or `git_ssh:prod`)
 
-The `<ref>` format is `type` or `type:instance`. If no instance is specified, defaults to `default`. If the credential already exists, you'll be prompted to update it.
+#### `al creds rm <ref>` — Remove credential
 
-#### `al creds rm <ref>`
-
-Remove a credential from disk.
-
-```bash
-al creds rm github_token               # removes github_token:default
-al creds rm github_webhook_secret:myapp
-```
-
-#### `al creds types`
-
-Browse available credential types interactively. Presents a searchable list of all built-in credential types. On selection, shows the credential's fields, environment variables, and agent context, then offers to add it immediately.
+#### `al creds types` — Browse credential types
 
 ### Agent commands
 
-#### `al agent new`
-
-Interactive wizard to create a new agent from a template. Prompts for agent type (dev, reviewer, devops, or custom), agent name, and then runs `al agent config` to configure the new agent.
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-
-#### `al agent config <name>`
+#### `al agent new` — Create from template (dev, reviewer, devops, custom)
 
-Interactively configure an existing agent. Opens a menu to edit each section of `agent-config.toml`: credentials, model, schedule, webhooks, and params. Runs `al doctor` on completion to validate the configuration.
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
+#### `al agent config <name>` — Configure agent interactively
 
 ### Global options
 
-These options are available on most commands:
-
-| Option | Description |
-|--------|-------------|
-| `-p, --project <dir>` | Project directory (default: `.`) |
-| `-E, --env <name>` | Environment name (also `AL_ENV` env var or `environment` field in `.env.toml`) |
+`-p <dir>` (project, default `.`) and `-E <name>` (env, also `AL_ENV` or `.env.toml`).
 
 ## Docker
 
@@ -1400,11 +929,11 @@ al-project-base:latest     ← project Dockerfile (skipped if unmodified from ba
 al-<agent>:latest          ← per-agent Dockerfile (if present)
 ```
 
-If the project Dockerfile is unmodified (bare `FROM al-agent:latest`), the middle layer is skipped — agents build directly on `al-agent:latest`.
+Bare project Dockerfile skips middle layer.
 
 ### Base image contents
 
-The base image (`al-agent:latest`) is built from `node:20-alpine` and includes:
+Built from `node:20-alpine`:
 
 | Package | Purpose |
 |---------|---------|
@@ -1415,19 +944,11 @@ The base image (`al-agent:latest`) is built from `node:20-alpine` and includes:
 | `ca-certificates` | HTTPS for git, curl, npm |
 | `openssh-client` | SSH for `GIT_SSH_COMMAND` — git clone/push over SSH |
 
-The base image also copies the compiled Action Llama application (`dist/`) and installs its npm dependencies.
-
-Entry point: `node /app/dist/agents/container-entry.js`
-
-Shell commands are baked into the image at `/app/bin/` (al-rerun, al-status, al-return, al-exit, al-call, al-check, al-wait, rlock, runlock, rlock-heartbeat).
+Entry: `node /app/dist/agents/container-entry.js`. Commands at `/app/bin/`.
 
 ### Dockerfile conventions
 
-- `FROM al-agent:latest` — the build pipeline automatically rewrites the `FROM` line to point at the correct base
-- Switch to `root` for package installs, back to `node` (uid 1000) for the entry point
-- Alpine base: use `apk add --no-cache`
-- Agent images are named `al-<agent-name>:latest` (e.g. `al-dev:latest`) and are rebuilt on every `al start`
-- The build context is the Action Llama package root (not the project directory), so `COPY` paths reference the package's `dist/`, `package.json`, etc.
+`FROM al-agent:latest` (auto-rewritten). Images: `al-<name>:latest`.
 
 #### Project Dockerfile example
 
@@ -1453,11 +974,7 @@ USER node
 
 #### Standalone Dockerfile (full control)
 
-If you need full control, the requirements are:
-1. Node.js 20+
-2. `/app/dist/agents/container-entry.js` must exist
-3. `ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]`
-4. `USER node` (uid 1000) for compatibility
+Needs Node.js 20+, entry.js, `USER node`.
 
 ```dockerfile
 FROM node:20-alpine
@@ -1471,11 +988,11 @@ USER node
 ENTRYPOINT ["node", "/app/dist/agents/container-entry.js"]
 ```
 
-The entry point reads `AGENT_CONFIG`, `PROMPT`, `GATEWAY_URL`, and `SHUTDOWN_SECRET` from environment variables, and credentials from `/credentials/`.
+Reads `AGENT_CONFIG`, `PROMPT`, `GATEWAY_URL` from env.
 
 ### Container filesystem
 
-All agents run in isolated containers with a read-only root filesystem, dropped capabilities, non-root user, and resource limits.
+Read-only root, non-root user, resource limits.
 
 | Path | Mode | Contents |
 |------|------|----------|
@@ -1487,34 +1004,25 @@ All agents run in isolated containers with a read-only root filesystem, dropped
 | `/workspace` | read-write (2GB) | Persistent workspace |
 | `/home/node` | read-write (64MB) | Home directory |
 
-### Docker config options
-
-These go in `config.toml` under `[local]`:
+### Environment variable persistence
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `local.image` | `"al-agent:latest"` | Base Docker image name |
-| `local.memory` | `"4g"` | Memory limit per container |
-| `local.cpus` | `2` | CPU limit per container |
-| `local.timeout` | `900` | Max container runtime in seconds |
+Write to `/tmp/env.sh` to persist environment variables across bash commands:
 
-## Gateway API
-
-The gateway is the HTTP server that runs alongside the scheduler. It handles webhooks, serves the web dashboard, and exposes control and status APIs used by CLI commands and the dashboard.
-
-The gateway starts automatically when needed — either when webhooks are configured, when `--web-ui` is passed to `al start`, or when Docker container communication is required. The port is controlled by the `[gateway].port` setting in `config.toml` (default: `8080`).
-
-### Authentication
+```bash
+echo 'export REPO="owner/repo"' > /tmp/env.sh
+echo 'export ISSUE_NUMBER=42' >> /tmp/env.sh
+gh issue view $ISSUE_NUMBER --repo $REPO
+```
 
-The gateway API is protected by an API key. The same key is used for both browser sessions and CLI access.
+File is automatically sourced before each bash command.
 
-**Key location:** `~/.action-llama/credentials/gateway_api_key/default/key`
+See `[local]` in config.toml for Docker configuration options.
 
-The key is generated automatically by `al doctor` or on first `al start`. To view or regenerate it, run `al doctor`.
+## Gateway API
 
-**CLI access:** CLI commands (`al stat`, `al pause`, `al resume`, `al kill`) automatically read the API key from the credential store and send it as a `Bearer` token in the `Authorization` header.
+Auto-starting HTTP server. Port: `[gateway].port`.
 
-**Browser access:** The web dashboard uses cookie-based authentication. After logging in with the API key, an `al_session` cookie is set (HttpOnly, SameSite=Strict) so all subsequent requests — including SSE streams — are authenticated automatically.
+API key at `~/.action-llama/credentials/gateway_api_key/default/key`.
 
 ### Protected routes
 
@@ -1528,16 +1036,16 @@ The key is generated automatically by `al doctor` or on first `al start`. To vie
 
 ### Control API
 
-All control endpoints use `POST` and require authentication.
+All `POST`, require auth.
 
-**Scheduler control:**
+**Scheduler:**
 
 | Endpoint | Description |
 |----------|-------------|
 | `POST /control/pause` | Pause the scheduler (all cron jobs) |
 | `POST /control/resume` | Resume the scheduler |
 
-**Agent control:**
+**Agents:**
 
 | Endpoint | Description |
 |----------|-------------|
@@ -1550,7 +1058,7 @@ All control endpoints use `POST` and require authentication.
 
 ### SSE Streams
 
-Live updates use **Server-Sent Events (SSE)**:
+Live updates via **SSE**:
 
 | Endpoint | Description |
 |----------|-------------|
@@ -1566,31 +1074,9 @@ Live updates use **Server-Sent Events (SSE)**:
 
 ## Web Dashboard
 
-Action Llama includes an optional web-based dashboard for monitoring agents in your browser. It provides a live view of agent statuses and streaming logs.
-
-### Enabling
-
-Pass `-w` or `--web-ui` to `al start`:
-
-```bash
-al start -w
-```
-
-The dashboard URL is shown in the TUI header once the scheduler starts:
-
-```
-Dashboard: http://localhost:8080/dashboard
-```
+Enable with `al start -w`. URL: `http://localhost:<port>/dashboard`. Login with gateway API key.
 
-The port is controlled by the `[gateway].port` setting in `config.toml` (default: `8080`).
-
-### Authentication
-
-The dashboard is protected by the gateway API key. Navigate to `http://localhost:8080/dashboard` and you'll be redirected to a login page where you paste your API key. On success, an `al_session` cookie is set (HttpOnly, SameSite=Strict).
-
-### Main Page — `/dashboard`
-
-Displays a live overview of all agents:
+### `/dashboard`
 
 | Column | Description |
 |--------|-------------|
@@ -1602,24 +1088,13 @@ Displays a live overview of all agents:
 | Next Run | When the next scheduled run will happen |
 | Actions | **Run** (trigger an immediate run) and **Enable/Disable** (toggle the agent) |
 
-The header includes a **Pause/Resume** button for the scheduler and a **Logout** link. Below the table, a **Recent Activity** section shows the last 20 log lines across all agents.
-
-All data updates in real time via Server-Sent Events (SSE) — no manual refresh needed.
-
-### Agent Logs — `/dashboard/agents/<name>/logs`
-
-Displays a live-streaming log view for a single agent. Logs follow automatically by default (new entries scroll into view as they arrive). Features:
-
-- **Follow mode** — enabled by default, auto-scrolls. Scrolling up pauses follow; scrolling back to the bottom re-enables it.
-- **Clear** — clears the log display (does not delete log files).
-- **Connection status** — shows whether the SSE connection is active.
-- **Log levels** — color-coded: green for INFO, yellow for WARN, red for ERROR.
+Pause/Resume, Recent Activity. SSE updates.
 
-On initial load, the last 100 log entries from the agent's log file are displayed, then new entries stream in as they are written. No additional dependencies or frontend build steps are required — the dashboard is rendered as plain HTML with inline CSS and JavaScript.
+### `/dashboard/agents/<name>/logs` — Live streaming agent logs
 
 ## Environments
 
-Projects are portable — cloud infrastructure details live outside the project directory using a three-layer config merge system (later values win, deep merge).
+Three-layer config merge (later wins):
 
 | Layer | File | Scope | Contents |
 |-------|------|-------|----------|
@@ -1627,15 +1102,9 @@ Projects are portable — cloud infrastructure details live outside the project
 | 2 | `.env.toml` | Project (gitignored) | `environment` field to select env, can override any config value |
 | 3 | `~/.action-llama/environments/<name>.toml` | Machine | `[server]` (SSH push deploy), `gateway.url`, `telemetry.endpoint` |
 
-`[cloud]` and `[server]` must be in Layer 3 (environment file). Placing `[cloud]` in `config.toml` is an error. `[cloud]` and `[server]` are mutually exclusive within an environment.
+`[cloud]`/`[server]` must be Layer 3. Mutually exclusive.
 
-### Environment selection priority
-
-`-E`/`--env <name>` flag > `AL_ENV` env var > `.env.toml` `environment` field.
-
-### Environment types
-
-For `al env init`: `server`.
+Priority: `-E` flag > `AL_ENV` env var > `.env.toml`. Type: `server`.
 
 ### Server environment example
 
@@ -1651,23 +1120,21 @@ expose = true
 
 ### VPS credential sync
 
-When deploying to a VPS, credentials are transferred to the remote server via SSH. The remote layout mirrors the local one: `~/.action-llama/credentials/{type}/{instance}/{field}`. No external secrets manager is needed — same trust model as SSH access.
+Credentials synced via SSH.
 
 ## Running Agents
 
-Start all agents with `al start` (or `npx al start`). This starts the scheduler which runs all discovered agents on their configured schedules/webhooks. There is no per-agent start command — `al start` always starts the entire project.
+`al start` runs all agents. No per-agent start.
 
 ### Automatic re-runs
 
-When a scheduled agent runs `al-rerun`, the scheduler immediately re-runs it. This continues until the agent completes without `al-rerun` (no more work), hits an error, or reaches the `maxReruns` limit. This way an agent drains its work queue without waiting for the next cron tick.
-
-Webhook-triggered and agent-triggered runs do not re-run — they respond to a single event.
+`al-rerun` triggers re-run until done/error/`maxReruns`. Webhook/call runs don't re-run.
 
 ## Exit Codes
 
 ### Shell command exit codes
 
-All gateway-calling shell commands (`rlock`, `runlock`, `rlock-heartbeat`, `al-call`, `al-check`, `al-wait`) share a common exit code scheme. **Always check exit codes** — do not assume success.
+**Always check exit codes.**
 
 | Exit | Meaning | HTTP | When |
 |------|---------|------|------|
@@ -1697,10 +1164,4 @@ All gateway-calling shell commands (`rlock`, `runlock`, `rlock-heartbeat`, `al-c
 | 15 | Unrecoverable (default) |
 | 16 | User abort |
 
-Shell command codes (0-12) don't overlap with agent codes (10-16) or POSIX signal codes (128+).
-
-**Lock commands** (`rlock`, `runlock`, `rlock-heartbeat`) exit 0 with `{"ok":true}` when `GATEWAY_URL` is unset (graceful degradation for local/non-containerized runs).
-
-**Call commands** (`al-call`, `al-check`, `al-wait`) exit 5 when `GATEWAY_URL` is unset — they require a gateway.
-
-**Timeout:** Container terminated by timeout exits with code 124.
+Timeout: exit 124.