@pmndrs/pine 0.0.0-stage → 0.1.1

package/docs/references/configuration.md

@@ -0,0 +1,229 @@
+# Configuration
+
+Everything pine needs is in its home directory: `~/.pine` by default, or `$PINE_HOME`, or
+`--home <dir>` on the command line.
+
+```
+~/.pine/
+  pine.json            global settings, routes, schedules, global MCP servers and event sources
+  models.json          optional: your own model servers, in pi's format
+  .env                 secrets, referenced from the JSON files as ${NAME}
+  auth.json            provider credentials, written by `pine login`
+  USER.md              what all agents know about you; in every agent's prompt, kept by the main agent
+  agents/
+    main/
+      agent.json       this agent's settings
+      workspace/       its working folder, unless agent.json points elsewhere
+        AGENTS.md      its purpose and how it works  ┐ read into its prompt,
+        SOUL.md        who it is                     │ written by the agent itself
+        MEMORY.md      what should outlive a talk    ┘ (agents.md)
+      AGENTS.md        optional: rules of yours the agent cannot change
+      skills/          skills only this agent has
+      conversations/   what was set up for one conversation alone (its skills); made when needed
+      extensions/      pi extensions only this agent loads
+      sessions/        conversation history (written by pine)
+  skills/              skills for all agents; no entry needed (the main agent adds them with add_skill)
+  sources/             source types the main agent registered (pine's own copies)
+  sandbox/             per-agent private home and generated sandbox profiles (written by pine)
+  data/                event log, task queue, media, control token, files of event sources (written by pine)
+```
+
+`pine check` validates names, references, paths, models and the entries of sources and
+schedules, prints what each agent ends up with, and lists anything that
+weakens the defences. Problems are reported together, each with the file it is in.
+
+Paths in `pine.json` are relative to the home directory; paths in `agent.json` are relative to
+that agent's folder. `~` works in both.
+
+## Secrets
+
+Write `${NAME}` or `${NAME:-fallback}` anywhere in a string in `pine.json` or `agent.json`.
+Values come from `<home>/.env` first, then from the environment of the daemon. A missing
+variable without a fallback is a configuration error.
+
+`.env` is read by pine only. Its values are not exported to the daemon's environment, so
+agent shells and MCP servers do not inherit them; they are also removed from events, messages
+and log lines if they ever appear there (values of 8 characters or more). Keep the file at
+mode 600 (`pine init` sets that).
+
+pine writes to `.env` itself in one case: when an agent sets up an event source that has a
+password or secret, the value is stored there as `PINE_SOURCE_<NAME>_<AGENT>_<OPTION>` (without
+the agent for a source of all agents), and the configuration holds only the `${...}` reference.
+Removing the source removes the entry. See [sources.md](sources.md).
+
+## pine.json
+
+```json
+{
+  "main": "main",
+  "logLevel": "info",
+  "defaults": { "model": "local/deepseek-v4.1-flash", "thinking": "off" },
+  "limits": { "maxConcurrentRuns": 2 },
+  "security": { "approvalTimeout": "5m" },
+  "http": { "host": "127.0.0.1", "port": 7463, "hooks": {} },
+  "mcp": {},
+  "sources": {},
+  "sourceTypes": {},
+  "subscribe": [],
+  "extensions": [],
+  "skills": [],
+  "routes": [],
+  "schedules": []
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `main` | none | Id of the main agent. It may delegate to every other agent unless its `agent.json` says otherwise, and it is the only one that can create agents and set things up for all agents ([setup.md](setup.md)). Without this key, the agent called `main` (or else the first one) has those setup rights, but nobody delegates by default. |
+| `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent`. Logs go to stderr; a daemon started inside the terminal UI logs to `data/pine.log`. |
+| `dataDir` | `data` | Where the database, media and control token live. |
+| `defaults.model` | none | `provider/model-id` from `models.json`: the model of every agent whose `agent.json` names none. There is no built-in fallback: an agent with neither is a configuration error, which `pine check` and the start of pine report. |
+| `defaults.thinking` | `off` | Reasoning level for models that can reason: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
+| `defaults.mode` | `auto` | `manual`, `auto` or `bypass`: how much agents do without asking. See [security.md](security.md). |
+| `defaults.bashTimeoutSec` | `300` | Longest a shell command may run. The model cannot raise it. |
+| `defaults.taskTimeoutSec` | `1800` | Longest a task may run before it is aborted. |
+| `defaults.idleMs` | `15m` | A live session without work is closed after this (and resumed from disk later). |
+| `defaults.settings` | `{}` | pi settings applied to every agent, for example `{ "compaction": { "reserveTokens": 8000 } }`. |
+| `limits.maxConcurrentRuns` | `2` | Model slots: how many runs talk to the model server at once. Match it to the server's parallel slots. |
+| `limits.maxDelegationDepth` | `3` | How deep a chain of delegations may go. |
+| `limits.maxDownloadMb` | `200` | Largest file the `download` tool fetches. |
+| `limits.maxEventHops` | `8` | Events further than this from an outside trigger are not routed. |
+| `limits.maxQueuedPerAgent` | `50` | New tasks are refused when an agent has this many waiting. |
+| `limits.maxEventChars` | `20000` | Longest text of an untrusted event in a prompt (at least 1000). Your own messages and delegated tasks are cut at ten times this. |
+| `limits.modelHeadersTimeoutMs` | `10m` | How long the model server may take to start answering. |
+| `limits.modelStreamIdleMs` | `5m` | How long a started answer may go silent before the request is dropped. |
+| `limits.eventRetentionDays` | `30` | Older events are deleted, and so are the copies kept of conversations that were reset. |
+| `limits.conversationDays` | `7` | A conversation in which nothing was said for this long is removed with its history, unless it is an agent's main conversation, pinned, open in a tab, subscribed to an event source, or has a schedule of its own. `0`: never. |
+| `security.approvalTimeout` | `5m` | An unanswered approval request counts as "no" after this. |
+| `security.taint` | `session` | How long a session stays tainted: until reset (`session`), until the task ends (`run`), or never (`off`). See [security.md](security.md). |
+| `security.taintTools` | `[]` | Tool name globs whose results count as outside content, besides MCP servers marked `taints`. |
+| `security.bypassWhenTainted` | `false` | Keep bypass mode in force in a session that has read outside content. Off, such a session asks again. |
+| `http` | on, loopback, port 7463 | Control API and webhooks. `false` turns it off (the CLI's client commands then do not work). |
+| `http.host`, `http.port` | `127.0.0.1`, `7463` | Where the control API listens. Anything but loopback is reported by `pine check`. |
+| `http.token` | generated | Bearer token of the control API. When unset, pine generates one into `data/http-token`. |
+| `http.hooks.<name>` | none | A webhook at `POST /hook/<name>`: `{ "secret": "...", "topic": "hook/<name>" }`, or `"open": true` instead of a secret to accept anyone who can reach the port. See [events.md](events.md). For a webhook an agent subscribes to, use a `webhook` source instead. |
+| `mcp` | `{}` | Global MCP servers. See [mcp.md](mcp.md). |
+| `sources` | `{}` | Event sources every agent can subscribe to. See [sources.md](sources.md). |
+| `sourceTypes` | `{}` | Source types of your own: a name and the module that implements it, e.g. `{ "doorbell": "./sources/doorbell.ts" }`. The module says which options it takes, and agents can then set up sources of that type by tool call. The main agent adds entries here with `add_source_type`, pointing at the copy pine keeps in `sources/` of its home. |
+| `subscribe` | `[]` | Subscriptions for all agents: every agent that can use the source is woken in its main conversation. |
+| `extensions` | `[]` | Paths of pi extensions loaded into every agent's sessions. |
+| `skills` | `[]` | Further folders of skills for every agent, for skills that lie outside pine's home. Not needed for `skills/` in pine's home: what is there is for every agent without an entry, and so is what the main agent adds with `add_skill`. Agents cannot replace or remove a skill that is named here. |
+| `routes` | `[]` | See [events.md](events.md). |
+| `schedules` | `[]` | What happens at a time. One with a `task` wakes every agent with it; one without only publishes an event. The main agent adds entries with `add_schedule`. See [events.md](events.md). |
+
+Two things that older setups had are configuration errors now, each reported with what to
+write instead: a `plugins` list that is not empty, and an event source of `"type": "timer"`
+(that is a schedule).
+
+Durations are a number of milliseconds or a string such as `"90s"`, `"15m"`, `"2h"`, `"1d"`.
+
+## agent.json
+
+Every key is optional; `{}` is a valid agent.
+
+```json
+{
+  "description": "Contract law; knows the case files",
+  "workspace": "~/dev/gonzo",
+  "model": "local/deepseek-v4.1-flash",
+  "tools": ["read", "bash", "edit", "write", "grep", "find", "ls"],
+  "mcp": { "library": { "command": "library-mcp" } },
+  "globalMcp": ["web"],
+  "delegates": [],
+  "subagents": { "maxParallel": 3 },
+  "sandbox": { "network": false, "read": ["~/Documents/law-library"] }
+}
+```
+
+### Identity and model
+
+| Key | Default | Meaning |
+|---|---|---|
+| `description` | empty | One line other agents see when they choose whom to delegate to. Write it for them. |
+| `workspace` | `agents/<id>/workspace` | The agent's working folder. `AGENTS.md`, `SOUL.md` and `MEMORY.md` at its top are the agent's instructions and are loaded into its prompt. Must exist when you set it. |
+| `context` | `[]` | Further instruction files to load into the system prompt. |
+| `model`, `thinking` | from `defaults` | Per-agent model and thinking level. |
+| `settings` | from `defaults.settings` | pi settings for this agent. `agents/<id>/settings.json` is honoured as well. |
+| `taskTimeoutSec`, `idleMs` | from `defaults` | Per-agent overrides. |
+
+### Tools and extensions
+
+| Key | Default | Meaning |
+|---|---|---|
+| `tools` | `read`, `bash`, `edit`, `write` | Which of pi's built-in tools the agent gets: any of `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. |
+| `mcp` | `{}` | MCP servers only this agent has. An entry with the name of a global server replaces it for this agent. An entry with `"session": "<conversation>"` was added for that conversation alone and is removed with it ([setup.md](setup.md)). |
+| `globalMcp` | `true` | `true`: every global server that includes this agent. `false`: none. A list of names: exactly those. |
+| `sources` | `{}` | Event sources only this agent can subscribe to. An entry with `"session": "<conversation>"` was set up for that conversation alone and is removed with it. See [sources.md](sources.md). |
+| `subscribe` | `[]` | What this agent is subscribed to: a list of names, an object with `note`, `when`, `throttle`, `debounce` per source, or a list of entries with `source` and, for one conversation only, `session`. The agent's `subscribe` tool and `pine subscribe` write here. |
+| `schedules` | `[]` | What this agent does at set times: `{ "name", "cron" or "every" or "at", "task" }`, with `"session": "<conversation>"` for one conversation. The agent adds entries with `add_schedule`. See [events.md](events.md). |
+| `extensions`, `skills` | `[]` | Further pi extension files and skill folders for this agent. Its own `skills/` folder needs no entry. |
+| `bashTimeoutSec` | from `defaults` | Longest shell command. |
+| `bashDeny` | `[]` | Regular expressions; a shell command matching one is refused. A convenience, not a boundary: the sandbox is the boundary. |
+
+### Working with other agents
+
+| Key | Default | Meaning |
+|---|---|---|
+| `delegates` | `["*"]` for the agent that `main` in `pine.json` names, else `[]` | Agents this one may hand tasks to. |
+| `subagents` | on, 4 in parallel | `false`, or `{ "maxParallel": 4, "tools": [...], "mcp": true }`. `tools` narrows what sub-agents get. |
+| `publish` | `[]` | Topic patterns the `publish_event` tool may publish on. Empty: the agent has no such tool. |
+| `state.read` | `["#"]` | State keys the agent may read. |
+| `state.write` | `["agent/<id>/#"]` | State keys the agent may write. |
+| `state.inject` | `[]` | State keys shown to the agent in every turn. |
+
+### Containment
+
+| Key | Default | Meaning |
+|---|---|---|
+| `mode` | from `defaults` | `manual`: every action waits for approval. `auto`: works inside the sandbox and asks for the rest. `bypass`: never asks, and reaches your whole account. |
+| `sandbox` | on | `false` runs shell and file tools with the daemon's full rights. Do not, unless the machine itself is disposable. |
+| `sandbox.network` | `false` | Shell commands may use the network. |
+| `sandbox.read`, `sandbox.write` | `[]` | Further folders the agent may read / write, besides its workspace. |
+| `sandbox.sharedTmp` | `true` | Allow `/tmp` and the user's temp folder. |
+| `sandbox.env` | `{}` | Extra environment variables for the agent's shell. Do not put secrets here; the agent can read them. |
+| `trustWorkspace` | `false` | `true` lets pi load `.pi/extensions`, `.pi/settings.json` and skills from the workspace. That is code execution inside the daemon for whoever can write there, the agent included. |
+| `approve` | `[]` | Tool calls that always need your approval: `"tool"` or `"tool:argument-glob"`, for example `"bash:*git push*"`. |
+| `approveWhenTainted` | `["publish_event", "send"]` | Tool calls that need approval once the session has seen outside content. |
+| `untrusted` | read-only profile | What a run started by an untrusted event may use: `{ "tools": ["read","grep","find","ls"], "mcp": [], "delegates": [], "publish": [], "stateWrite": false, "subagents": false }`. `false` refuses such runs. |
+
+## models.json
+
+This is pi's own file; pine passes it through. It is only needed for model servers of your own:
+pi already knows the hosted providers (OpenCode, Anthropic, OpenAI and many more), and
+`pine login <provider>` supplies their credentials. `pine init` writes two providers: `dev`
+(Claude through `claude -p`, served by `pine dev-model`; the example's `defaults.model` is
+`dev/claude-haiku`) and `local` for llama.cpp. The `local` entry:
+
+```json
+{
+  "providers": {
+    "local": {
+      "name": "llama-server",
+      "baseUrl": "http://127.0.0.1:8080/v1",
+      "api": "openai-completions",
+      "apiKey": "none",
+      "models": [
+        {
+          "id": "deepseek-v4.1-flash",
+          "contextWindow": 65536,
+          "maxTokens": 8192,
+          "input": ["text"],
+          "reasoning": true,
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+          "compat": { "supportsStore": false, "supportsDeveloperRole": false, "maxTokensField": "max_tokens", "thinkingFormat": "deepseek" }
+        }
+      ]
+    }
+  }
+}
+```
+
+- Refer to a model as `provider/id`, here `local/deepseek-v4.1-flash`.
+- `contextWindow` must match what the server was started with (`-c`), or compaction triggers at
+  the wrong time.
+- Add `"image"` to `input` only for a model that accepts images; agents then receive the
+  pictures that Telegram and watched folders deliver.
+- The `compat` flags stop pi from sending fields a plain llama-server may reject. They have not
+  been verified against a real llama-server yet; see [stack.md](stack.md).
+- pi's documentation for this file is in
+  `node_modules/@earendil-works/pi-coding-agent/docs/models-configuration.md`.

package/docs/references/events.md

@@ -0,0 +1,263 @@
+# Events, routes and schedules
+
+> To let an agent react to a folder, a device or a web request, you usually do not need this
+> page: ask it, or configure a [source](sources.md) and have the agent subscribe. To have it do
+> something at a time, ask it too: see "Schedules" below. Routes are for rules of your own:
+> setting state, chaining events, single model calls.
+
+## Topics
+
+A topic is a slash-separated name. Patterns use `+` for exactly one level and `#` for the rest:
+
+| Pattern | Matches |
+|---|---|
+| `cam/front/motion` | only that topic |
+| `cam/+/motion` | `cam/front/motion`, `cam/back/motion` |
+| `source/#` | everything below `source`, and `source` itself |
+| `#` | everything |
+
+Where events come from:
+
+| Source | Topics | Trust |
+|---|---|---|
+| Webhook `POST /hook/<name>` | `hook/<name>` (or the hook's `topic`) | untrusted |
+| Event sources ([sources.md](sources.md)) | `source/<name>/<event>`, or `source/<name>@<agent>/<event>` for an agent's own | untrusted; owner for a source whose entry says `"trust": "owner"` (`add_source` writes that for `telegram`, whose account you pair) |
+| `pine emit`, `POST /events` | whatever you name | owner |
+| Schedules | `timer/<name>`, or `timer/<name>@<agent>` for an agent's own | owner |
+| Agents (`publish_event`) | topics in the agent's `publish` list | owner, or untrusted if the run was restricted |
+| pine | `agent/...`, `state/...`, `approval/...`, `pine/...` | untrusted |
+
+Watch them:
+
+```bash
+pine events -f
+```
+
+```bash
+pine events --topic "source/#" --limit 50
+```
+
+## Routes
+
+A route is an entry in `routes` in `pine.json`.
+
+```json
+{
+  "name": "front-door",
+  "on": "source/house/message",
+  "when": { "payload.topic": "house/door/front", "payload.value.open": true, "state.house/mode": "away" },
+  "throttleMs": "5m",
+  "agent": "house",
+  "prompt": "The front door was opened at {{time}} while the house is in away mode.",
+  "session": "new",
+  "reply": { "topic": "out/source/telegram" }
+}
+```
+
+Here `house` is an `mqtt` source and `telegram` a `telegram` source, both in `pine.json`
+([sources.md](sources.md)). For a source an agent set up for itself the topic carries the
+agent's name: `out/source/telegram@main`.
+A route does not subscribe to anything, so a source it relies on needs `"start": "always"`
+unless a conversation is subscribed to it anyway.
+
+| Key | Meaning |
+|---|---|
+| `name` | For logs and errors. Default `route<n>`. |
+| `on` | A topic pattern or a list of them. |
+| `when` | A filter; every entry must hold. See below. |
+| `debounceMs` | Wait until no matching event has arrived for this long, then handle the last one. For bursts (a camera uploading five images). |
+| `throttleMs` | Handle one event, then ignore matching ones for this long. For repeating alarms. |
+| `key` | Template for what counts as "the same" for debounce and throttle. Default `{{topic}}`. |
+| `set` | Write shared state: `{ "house/mode": "{{payload.value}}" }`. `null`, or a value that is exactly one `{{path}}` that finds nothing, deletes the key. |
+| `publish` | Publish another event: `{ "topic": "...", "payload": {...} }`. Without `payload` the original payload is passed on; after a `call` it is `{ "text": <the answer>, "of": <the original payload> }`. |
+| `call` | One model call: `{ "prompt": "...", "system": "...", "model": "provider/id" }`. Its answer is `{{result}}`. |
+| `agent` | Give an agent a task. |
+| `prompt` | The task text. Default: the payload's `text`, or the payload as JSON. |
+| `session` | Session key template. Default `main`. `new` for one-off work. |
+| `whenBusy` | `queue` (default) or `steer`. |
+| `priority` | Higher runs first when model slots are scarce. Default 10 for owner events, 0 otherwise. |
+| `reply` | Where the agent's answer goes: `{ "topic": "...", "payload": {...} }`. Default: the event's own reply target. `false`: nowhere. |
+| `trust` | Override the event's trust. `"owner"` gives events on this route the agent's full tool set: only for sources nobody else can write to. `pine check` lists such routes. |
+
+A route needs at least one of `set`, `publish`, `call`, `agent`. They run in the order `set`,
+`call`, `publish`, `agent`, so one route can classify with `call` and pass the result on with
+`publish`. `call` and `agent` cannot be in the same route: publish the result and let a second
+route start the agent, as in the example below.
+
+### Templates
+
+`{{path}}` is replaced in `prompt`, `session`, `key`, `set`, `publish`, `reply` and `call`.
+
+| Path | Value |
+|---|---|
+| `payload`, `payload.a.b` | The event's payload or a field of it |
+| `topic`, `source`, `id`, `ts`, `time` | Event fields; `time` is local, `YYYY-MM-DD HH:MM:SS` |
+| `state.<key>` | Shared state, for example `{{state.house/mode}}` |
+| `result` | The answer of the route's `call` |
+
+A value that is exactly one `{{path}}` keeps its type (a number stays a number); inside longer
+text, objects become JSON and missing values become empty.
+
+### Filters
+
+`when` maps a path to a value (equality) or to conditions:
+
+```json
+{
+  "payload.value.temperature": { "gt": 30 },
+  "payload.value.room": { "in": ["kitchen", "boiler"] },
+  "payload.text": { "regex": "^alarm", "flags": "i" },
+  "state.house/mode": { "ne": "home" },
+  "payload.value.battery": { "exists": true }
+}
+```
+
+Conditions: `eq`, `ne`, `in`, `gt`, `gte`, `lt`, `lte`, `exists`, `contains`, `regex` (with
+optional `flags`).
+
+### The cheapest handler that is enough
+
+A full agent turn costs seconds of model time. Most events do not need one.
+
+```json
+[
+  { "on": "source/house/message", "when": { "payload.topic": "house/mode" }, "set": { "house/mode": "{{payload.value}}" } },
+
+  { "on": "source/cam/added",
+    "debounceMs": "4s",
+    "call": { "system": "You look at one camera image. Answer in one line: PERSON, VEHICLE, ANIMAL or NOTHING, then a short description.",
+              "prompt": "Camera file {{payload.file}}" },
+    "publish": { "topic": "cam/classified", "payload": { "file": "{{payload.file}}", "verdict": "{{result}}" } } },
+
+  { "on": "cam/classified",
+    "when": { "payload.verdict": { "regex": "^(PERSON|VEHICLE)" }, "state.house/mode": "away" },
+    "agent": "house", "session": "new",
+    "prompt": "Camera saw: {{payload.verdict}} ({{payload.file}}). The house is in away mode.",
+    "reply": { "topic": "out/source/telegram" } }
+]
+```
+
+The first route never calls the model. The second makes one call per burst of images (a `call`
+receives the event's images if the model accepts them). Only a person or a vehicle while nobody
+is home reaches an agent.
+
+Text from untrusted events is prefixed for the agent with a line saying where it came from and
+that it is data, and is cut at `limits.maxEventChars`. That line is a courtesy; the protection
+is that the run has fewer tools (see [security.md](security.md)).
+
+## Schedules
+
+A schedule is something that happens because of the time: again and again, or once. It is the
+fourth thing an agent can be given by asking, next to event sources, MCP servers and skills,
+and it has the same three scopes ([setup.md](setup.md)).
+
+### Ask the agent
+
+> Every weekday at seven, check my mail and tell me on Telegram what matters.
+
+> Remind me at five to call the dentist.
+
+> In twenty minutes, look whether the build is through.
+
+The agent calls its `add_schedule` tool with a name, the time and the task in its own words:
+`cron` for set times ("every weekday at six in the evening" is `"0 18 * * 1-5"`), `every` for an
+interval, `at` or `in` for a reminder that happens once. When it is time, it is woken with that
+task, also when you are not there, and does it. What it starts
+counts as your wish: the agent has its usual tools, and nothing is marked as outside content.
+
+| Said | Who is woken | You are asked |
+|---|---|---|
+| in a side conversation | That conversation; the schedule goes when the conversation is removed | No |
+| in the agent's main conversation, or "as an agent" | The agent's main conversation | Only from a side conversation |
+| "all agents" | Every agent, each in its main conversation. Only the main agent can do this | Yes |
+
+In a conversation that has read outside content you are asked in every case, and the dialog
+shows the task: what a web page says must not become something that is done every hour.
+
+| Tool | |
+|---|---|
+| `schedules` | What is scheduled for this agent, in which conversation, and when each is next due. |
+| `add_schedule` `name` `task` + one of `cron`, `every`, `at`, `in` [`scope`] | Schedules it. `cron`: set times; `every`: an interval, at least a minute; `at`: once, at a local time (`2026-12-24 17:00`); `in`: once, after this long (`20m`). |
+| `remove_schedule` `name` | Ends one. This conversation's own goes without a question. |
+
+A schedule that happens once removes itself when it has fired. A one-off, or a `cron` schedule
+with a task, that was due while pine was not running is done once when pine starts again, and
+the agent is told that it comes late. An `every` schedule simply starts counting again. `pine
+schedules` lists everything that is scheduled.
+
+A name is unique among all schedules; a task has at most 4000 characters; an interval an agent
+sets is at least a minute; a time in the past is refused. In manual mode you are asked for
+every `add_schedule` and `remove_schedule`.
+
+### In the files
+
+```json
+"schedules": [
+  { "name": "brief", "cron": "30 7 * * 1-5", "task": "Prepare the morning brief and send it to me on Telegram." },
+  { "name": "dentist", "at": "2026-11-12T17:00", "task": "Remind me to call the dentist." },
+  { "name": "printer-check", "every": "10m" }
+]
+```
+
+In an `agent.json` this is that agent's schedule (add `"session": "<conversation>"` for one
+conversation, otherwise its main one). In `pine.json` a schedule with a task wakes every
+agent; one without a task only publishes an event.
+
+| Key | Meaning |
+|---|---|
+| `name` | Required. Starts with a lowercase letter, then lowercase letters, digits, `-` and `_`; 40 characters at most. The event is published on `timer/<name>` (`timer/<name>@<agent>` for an agent's own) unless `topic` says otherwise. |
+| `cron` | Five fields, local time: minute, hour, day of month, month, day of week (0 or 7 is Sunday). Lists, ranges and steps work: `*/15 8-18 * * 1-5`. |
+| `every` | A fixed interval instead. |
+| `at` | Once, at this local time. The entry is removed when it has fired. If pine was not running at that time, it fires when pine starts again, and the agent is told that it comes late. |
+| `task` | What the agent is to do. Required in an `agent.json`. |
+| `session` | In an `agent.json`: the conversation that is woken. Default: the main one. |
+| `payload` | Fields added to the event's payload (`name` and `scheduled` are always there; `late` when it comes late, `task` when it has one). |
+| `catchUp` | For `cron`: fire once at startup if a time passed while the daemon was down, marked as late. Default: `true` with a task, `false` without. (`at` always catches up; `every` never does.) |
+
+### Schedules and routes
+
+Every schedule also publishes an event, trusted as yours, so a route can act on it. For a
+schedule without a task that is all it does:
+
+```json
+{ "on": "timer/printer-check", "call": { "prompt": "..." } }
+```
+
+A route is the way to do something other than an agent's turn at a time: set state, publish,
+or one model call without tools. For "wake the agent and let it do this", give the schedule a
+task instead; no route is needed.
+
+## Webhooks
+
+```json
+"http": { "hooks": { "doorbell": { "secret": "${DOORBELL_SECRET}" } } }
+```
+
+`POST http://127.0.0.1:7463/hook/doorbell` then publishes `hook/doorbell` with the request body
+as payload (parsed JSON, or `{ "text": ... }`). The caller proves itself with either
+
+- `Authorization: Bearer <secret>`, or
+- an HMAC-SHA256 of the body with the secret, hex-encoded, in `X-Hub-Signature-256: sha256=<hex>`
+  (the GitHub convention) or `X-Signature`.
+
+A hook needs a secret; `"open": true` instead of a secret accepts anyone who can reach the port
+and is reported by `pine check`. Unknown hook names get 404. Each hook accepts at most 120
+requests a minute and bodies up to 1 MB. Webhook events are untrusted even when the signature
+is right: the signature says who sent it, not that its content is safe to obey.
+
+To receive webhooks from outside your network, put a tunnel or reverse proxy in front and
+forward only `/hook/`.
+
+A hook here only publishes an event; a route decides what happens. For a webhook that wakes an
+agent directly, use a source of type `webhook` ([sources.md](sources.md)): it answers under
+`/hook/` too, while an agent is subscribed. A hook in `http.hooks` with the same name comes
+first.
+
+## When nothing happens
+
+1. `pine events --topic "<pattern>"`: did the event arrive, and on which topic?
+2. `pine tasks`: was a task created? `pine task <id>` shows its prompt, result and error.
+3. `pine events --topic "pine/#"`: `pine/route-failed` carries the reason a route could not act,
+   for example an agent that refuses untrusted events or a full queue.
+4. Daemon log (stderr): a line `dropped ... after N hops` means a loop was cut.
+5. A filter that never matches is usually a wrong path: look at the real payload in step 1.