@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/runtime-skills/apx-image/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: apx-image
+scope: optional
+description: Generate images from a text prompt with `apx image`, routed to a local, LAN, or cloud diffusion server. Load when asked to draw, render, illustrate, or make a picture, logo sketch, thumbnail, or cover; to pick between image engines; to set image size, steps, guidance, seed, or a negative prompt; or when an image engine is unreachable or ignoring options.
+---
+
+# apx-image
+
+`apx image` turns a prompt into a file. It is a thin CLI over the daemon's `POST /api/images/generate`, which routes to whichever engine is configured and reachable — so the same command works against a diffusion server on this machine, a box on the network, or a cloud key, without the caller knowing which.
+
+## Usage
+
+```bash
+apx image "a green origami fox on a white background"
+apx image "portrait of a fox" --size 768x512 --steps 8 --cfg 1.0 --out fox.png
+apx image "a logo sketch" --provider a1111 --seed 123 --json
+apx image "cover art" --negative "text, watermark" --count 2 --open
+apx image providers                      # what is configured and reachable
+apx image capabilities --provider sdcpp  # models, samplers, schedulers
+```
+
+Without `--out`, the file lands in `~/.apx/images/<date>/` and the path is printed on stdout. **Nothing is written into a project checkout unless `--out` says so.**
+
+## Engines
+
+| id | Dialect | Notes |
+|---|---|---|
+| `a1111` | `POST /sdapi/v1/txt2img`, synchronous | The universal one: AUTOMATIC1111, Forge, SD.Next, Draw Things on macOS, stable-diffusion.cpp. Carries every sampling knob. |
+| `sdcpp` | `POST /sdcpp/v1/img_gen` + job polling | stable-diffusion.cpp's native queue. The socket closes immediately and the job is polled, so a queued render never looks like a hung request. One checkpoint per server. |
+| `openai` | `POST /v1/images/generations` | Cloud (`gpt-image-1` / `dall-e-3`), or any OpenAI-compatible server when `base_url` is set. |
+| `mock` | none | Offline test engine, always last and always available. |
+
+Add any number of extra endpoints under `images.custom.<slug>`, each naming the dialect it speaks in `kind`. They surface as `custom:<slug>`.
+
+## Routing
+
+Engines are tried in `images.order` and the first reachable one draws — the same chain/single model as TTS. Set `images.mode` to `single` plus `images.provider` to pin one. `--provider` overrides the routing for one call. A configured but unreachable server is skipped rather than failing the call.
+
+```bash
+apx config set --global images.a1111.base_url http://127.0.0.1:7860
+apx config set --global images.a1111.defaults '{"steps":8,"cfg_scale":1}'
+```
+
+Settings live in `~/.apx/config.json` under `images.*`, and the same settings have a screen at **Settings → Images** in the web panel.
+
+## Options resolve in four layers
+
+`images.defaults` → `images.<engine>.defaults` → the call. Later wins. Steps and guidance belong to the **engine**, not to the prompt: a turbo checkpoint wants about 8 steps at cfg 1, a standard one 20 at cfg 7, and putting that in the engine's block means no caller has to remember it.
+
+## Not every engine honors every option
+
+The OpenAI dialect has no steps, guidance, sampler, scheduler, seed or negative prompt. stable-diffusion.cpp hosts one checkpoint and cannot switch models. Whatever an engine cannot honor is **reported** after the run (`ignored` in `--json`) instead of being silently dropped — so a picture that came out wrong can be traced to the dialect rather than the prompt.
+
+## Don't
+
+- Don't call a diffusion server directly with `curl` when an engine is configured — routing, defaults, the seed report and the ignored-options report all live behind `apx image`, and a raw call has none of them.
+- Don't reach for Ollama: it serves language and vision models and cannot generate images at all. On macOS point the `a1111` engine at Draw Things' HTTP API, or any local A1111-compatible server, instead.
+- Don't set steps or guidance in `images.defaults` when several engines are configured — they belong to `images.<engine>.defaults`, because the right value depends on the checkpoint that server loaded.
+- Don't ask the `openai` engine for a negative prompt or a fixed seed and assume it took: check `ignored`.
+- Don't write generated images into a repository by default — leave them in `~/.apx/images/` and pass `--out` only when a file is genuinely wanted on disk somewhere.

package/src/core/runtime-skills/apx-integrations/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: apx-integrations
+description: "APX connectors (integrations/plugins) — Asana, Google Calendar, GitHub, Obsidian, WhatsApp. Load when a connector tool says \"not connected\" / \"read-only\" / \"not authorized\", or the user wants to connect/configure/check a plugin. NOT the same as MCP servers (apx-mcp) or the Telegram channel (apx-telegram). Triggers: 'connect Asana/Calendar/GitHub', 'why can't you see my calendar', 'integration not connected', 'plugins tab', 'read-only calendar'."
+---
+
+# apx-integrations
+
+A **connector** (a.k.a. integration / plugin) is a stored, per-project connection to an external service — Asana, Google Calendar, GitHub, Obsidian. It gives the agent's tools live access to that service. It is a **different mechanism** from an MCP server (`apx-mcp`) and from the Telegram channel (`apx-telegram`, a channel, not a plugin).
+
+Catalog source of truth: `src/core/integrations/catalog.js`. Adding a plugin = drop a module in `plugins/` + register it in `PLUGIN_SERVICES` — no route changes.
+
+## The catalog
+
+| slug | name | auth | State |
+|---|---|---|---|
+| `asana` | Asana | token (PAT) | ✅ implemented |
+| `calendar` | Google Calendar | **user OAuth** | ✅ implemented |
+| `github` | GitHub | token | ✅ implemented |
+| `obsidian` | Obsidian | path (local Vault) | ✅ implemented — has a CLI |
+| `whatsapp` | WhatsApp | QR pairing | ⏳ `coming_soon` — do not attempt to connect |
+
+## The one rule: connecting happens OUT OF BAND
+
+**The agent cannot connect a plugin itself.** It cannot paste a token, pick a Vault folder, or complete an OAuth consent screen. Connection is done by the user in the **web panel → Integrations → Plugins** (the generic `PluginConnect` form). Your job is to *guide the user there and then re-check*, never to invent a connect command.
+
+- The **only** connector with a CLI is Obsidian: `apx obsidian …` (a thin client over the same daemon routes — configure/validate/status/sync/remove).
+- There is **no** `apx integrations` / `apx plugins connect` command. ⚠️ `apx plugins` is a **different, unrelated** thing (it lists *daemon* plugins at `/api/plugins`) — don't confuse it for connectors.
+
+## Reading the tool errors (this is the main reason you're here)
+
+The connector-backed tools (`calendar_*`, `asana_*`, `github_*`, `obsidian_*`) throw errors written to be relayed verbatim-ish to the user. Recognize them and tell the user the exact next step:
+
+| Error says… | What it means | Tell the user |
+|---|---|---|
+| "…is not connected. Ask the user to connect it in the web panel → Integrations → Plugins → X" | No usable record for this project | Open the panel, connect X. |
+| "The calendar isn't authorized yet." | Configured but no `refresh_token` (OAuth not completed) | Finish the "Connect with Google" step in the panel. |
+| "connected read-only … enable write access" | Calendar `write_access: false` | Toggle write access in the panel, then retry. |
+| "No Asana workspace selected." | Token valid, workspace not chosen | Pick the workspace in the panel. |
+
+Don't retry the tool in a loop against one of these — the fix is a human action in the panel.
+
+## Scope precedence: project → default(global)
+
+`resolveIntegration()` (`src/core/integrations/store.js`) resolves per project: the project's **own** enabled+active record wins; otherwise the **default** project's record is inherited. So a connector configured once on the `default` project works for every project that hasn't overridden it — the same "global = default project" pattern as MCPs (`apx-mcp`). Records live in the per-project integrations store (like tasks); the API redacts secrets in responses.
+
+## Google Calendar specifics (user OAuth, not a service account)
+
+Calendar acts **as the user** (invites + Google Meet), so it uses OAuth, not a key:
+
+1. User creates a Google Cloud OAuth app and enters `client_id` + `client_secret` in the panel.
+2. Panel runs the consent flow (`action: authorize` → Google → redirect back to `/api/integrations/oauth/callback`), which stores a `refresh_token`. APX caches short-lived access tokens from it.
+3. `write_access` toggle (default on) = create/edit events, invites, Meet. Off = read-only. `meet` toggle adds a Meet link on create.
+4. The calendar is always the account's own `primary` — there is nothing to pick.
+
+Tools: `calendar_list_events`, `calendar_find_slot`, `calendar_create_event` (invitees + Meet), `calendar_update_event`. See `plugins/calendar.js` + `plugins/_google-oauth.js`.
+
+## Daemon API (for reference — the panel and `apx obsidian` use these)
+
+```
+GET    /api/projects/:pid/integrations                     # configured, this project (+ scope)
+GET    /api/projects/:pid/integrations/catalog             # what's available
+GET    /api/projects/:pid/integrations/:slug
+POST   /api/projects/:pid/integrations/:slug/configure     # save creds/config
+POST   /api/projects/:pid/integrations/:slug/validate      # verify against the provider, persist result
+POST   /api/projects/:pid/integrations/:slug/action/:action  # plugin action (asana list workspaces, calendar authorize)
+POST   /api/projects/:pid/integrations/:slug/deactivate    # disable, keep creds
+DELETE /api/projects/:pid/integrations/:slug               # remove entirely
+GET    /api/integrations/oauth/callback                    # OAuth redirect target (signed state, no bearer)
+```
+
+`?scope=project|global` selects which store the write lands in.
+
+## Don't
+
+- Don't tell the user to "run a command" to connect a token/OAuth plugin — there's a CLI only for Obsidian. Everything else is the web panel.
+- Don't confuse `apx plugins` (daemon plugins list) with connectors. Different subsystem.
+- Don't treat a connector as an MCP. If the user wants to *register an MCP server*, that's `apx-mcp`.
+- Don't try to connect `whatsapp` — it's `coming_soon` (needs a QR-pairing bridge APX doesn't ship yet).
+  This is the CONNECTOR, not the `whatsapp` **channel**: a phone-side bridge already posts incoming
+  WhatsApp messages to the super-agent with `channel: "whatsapp"`, and that works. Never answer a
+  message that arrived on it with "WhatsApp is not supported yet".
+- Don't retry a tool after a "not connected / read-only / not authorized" error — surface the panel step and stop.

package/src/core/runtime-skills/apx-mcp/SKILL.md

@@ -13,24 +13,28 @@ APX exposes MCP servers via three scopes; resolution priority **runtime > shared
 | `runtime` | `~/.apx/projects/<apxId>/mcps.json` (chmod 0600) | no | yes | Per-project — tokens, machine-specific endpoints |
 | `global` | `~/.apx/mcps.json` | n/a | yes | Machine-wide, not tied to a project |
 
+## Super-agent tool
+
+The super-agent registers an MCP with the **`add_mcp`** tool (name + `command`/`args`/`env` for stdio, or `url`/`headers` for http; `scope` = runtime | shared | global, default runtime) — no shelling to `apx mcp add`. Then `list_mcp_tools` to see what it exposes and `call_mcp` to run one. Secrets go in `runtime`/`global` scope, never `shared` (committed).
+
 ## Concrete CLI calls
 
 ```bash
 # List (defaults to all scopes)
-apx mcp list --project iacrmar
-apx mcp list --scope runtime --project iacrmar
-apx mcp list --scope shared  --project iacrmar
+apx mcp list --project acme
+apx mcp list --scope runtime --project acme
+apx mcp list --scope shared  --project acme
 apx mcp list --scope global
 
 # Inspect sources and conflicts
-apx mcp check --project iacrmar
+apx mcp check --project acme
 
 # Add — shared (commit to repo)
-apx mcp add filesystem --command npx --project iacrmar \
+apx mcp add filesystem --command npx --project acme \
   -- -y @modelcontextprotocol/server-filesystem .
 
 # Add — runtime (per-project, local, secrets safe)
-apx mcp add github --scope runtime --project iacrmar \
+apx mcp add github --scope runtime --project acme \
   --command npx --env GITHUB_TOKEN=ghp_xxx \
   -- -y @modelcontextprotocol/server-github
 
@@ -40,12 +44,12 @@ apx mcp add brave --scope global \
   -- -y @modelcontextprotocol/server-brave-search
 
 # Remove (pass --scope when not in default: shared inside APC project, else global)
-apx mcp remove filesystem --project iacrmar
-apx mcp remove github     --scope runtime --project iacrmar
+apx mcp remove filesystem --project acme
+apx mcp remove github     --scope runtime --project acme
 
 # Toggle (defaults to owning scope)
-apx mcp enable  filesystem --project iacrmar
-apx mcp disable filesystem --project iacrmar
+apx mcp enable  filesystem --project acme
+apx mcp disable filesystem --project acme
 
 # Discover tools — list catalog, then inspect one tool's schema
 apx mcp tools filesystem                     # table: tool name + description
@@ -66,20 +70,47 @@ Default if unclear: `shared` inside an APC project, `global` outside.
 
 ## Command shapes by transport
 
+Two transports. `--command` = local process (stdio), `--url` = remote endpoint (http).
+There is no third option, and no flag outside this list — if a shape isn't here,
+run `apx help mcp add` instead of guessing.
+
 ```bash
-# stdio MCP (most common — npx, uvx, node, python)
+# stdio MCP — a local process (npx, uvx, node, python)
 apx mcp add <name> --command npx -- -y <package-or-flag-list>
 apx mcp add <name> --command uvx -- <python-cli-name>
 apx mcp add <name> --command python -- /abs/path/to/server.py
 
-# Env vars (one --env per var)
+# stdio env vars (one --env per var)
 apx mcp add <name> --command npx \
   --env GITHUB_TOKEN=ghp_xxx \
   --env GITHUB_OWNER=manuel \
   -- -y @modelcontextprotocol/server-github
+
+# http MCP — a remote streamable-HTTP endpoint. No command, no npx, no install.
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime
+
+# http with auth headers (repeatable; "Name: value" or Name=value both parse)
+apx mcp add <name> --url https://mcp.example.com/mcp --scope runtime \
+  --header "Authorization: Bearer $TOKEN" \
+  --header "X-Workspace: acme"
+```
+
+Everything after `--` is forwarded verbatim as args to a stdio command. Quote carefully.
+`--env` and `--` args are stdio-only; `--header` is http-only — mixing them errors.
+
+Remote servers almost always carry a token, so they belong in `--scope runtime`
+(chmod 0600, never committed). Read the token from the environment rather than
+pasting it: `--header "Authorization: Bearer $TOKEN"`.
+
+## After adding: prove it works
+
+```bash
+apx mcp tools <name>     # spawns/connects and lists tools — this is the real check
+apx mcp logs <name>      # if the above is empty or errors: request/response log
 ```
 
-Everything after `--` is forwarded verbatim as args. Quote carefully.
+`apx mcp add` only writes JSON — it never contacts the server. An MCP that "was
+added fine" but has no tools is a failed connection, not a successful install.
 
 ## Anti-examples
 
@@ -99,7 +130,7 @@ apx mcp remove github          # errors if github lives in runtime
 ## Debugging
 
 ```bash
-apx mcp check --project iacrmar      # scopes seen + which files exist
+apx mcp check --project acme      # scopes seen + which files exist
 apx mcp tools <name>                 # spawn server + list its tools (proves init works)
 apx mcp logs <name>                  # spawn/init event log + stderr tail
 apx mcp run <name> <tool> '{...}'    # call a tool for real

package/src/core/runtime-skills/apx-mcp-builder/SKILL.md

@@ -54,7 +54,7 @@ pip install fastmcp
 # or: uv tool install fastmcp
 
 apx mcp add my-server \
-  --command uv --project iacrmar \
+  --command uv --project acme \
   -- run python /abs/path/my_server.py
 ```
 
@@ -106,7 +106,7 @@ await server.connect(new StdioServerTransport());
 
 ```bash
 apx mcp add my-server \
-  --command npx --project iacrmar \
+  --command npx --project acme \
   -- -y my-server-package
 ```
 
@@ -122,7 +122,7 @@ apx mcp add my-server \
 
 ```bash
 apx mcp add github \
-  --scope runtime --project iacrmar \
+  --scope runtime --project acme \
   --command npx \
   --env GITHUB_TOKEN=ghp_xxx \
   --env GITHUB_OWNER=manuel \
@@ -165,7 +165,7 @@ apx mcp logs my-server
 apx log -f
 
 # Scopes / files / env APX sees
-apx mcp check --project iacrmar
+apx mcp check --project acme
 ```
 
 ## Don't

package/src/core/runtime-skills/apx-profile/SKILL.md

@@ -33,11 +33,13 @@ apx profile install secretary         # a bundled id
 apx profile install ./my-profile      # a local package directory
 apx profile use secretary             # activates + installs its routines
 apx profile use tutor --force         # replace whatever is active
+apx profile sync                      # re-read the active package from disk (after an APX update)
 
 # Configure — this is where white-label happens
 apx profile config                                  # show current settings
-apx profile config --set day_open_at="30 8 * * 1-5"
+apx profile config --set day_open_schedule="30 8 * * 1-5"
 apx profile config --set nudge_budget_per_day=3 --set quiet_hours=22:00-07:30
+apx profile config --set watch_schedule="0 */2 * * *" --set formality=vos
 apx profile config --interactive                    # walk the whole schema
 
 # Health and removal
@@ -96,6 +98,25 @@ settings, not core behaviour. If the answer is "it shouldn't have", the fix is u
   `profile_name`) or a schema property **with a default**. A property declared without a
   default is rejected, because it would silently render as an empty string.
 
+**In `routines/*.json`, settings render as VALUES, not as text.** The file is parsed first
+and each string leaf rendered after, so a setting carrying quotes (a shell command with JSON
+arguments, say) cannot break the document. Two consequences worth knowing:
+
+- A `pre_commands` / `post_commands` entry that renders empty is dropped entirely, so an
+  optional command is just a setting defaulting to `""` — no empty shell step, no pre phase.
+- `{{pre_output}}` is left alone by the renderer and filled by the routine runner at run
+  time. That is how a routine hands itself data without spending a tool call or a permission
+  on it — the secretary's `calendar_command` is the live example.
+
+## A package updates, its installed routines do not
+
+The prompt block is rendered every turn, so it improves the moment APX updates. Routines are
+records in the super-agent's store, written at install time — nothing carries a better anchor
+across. `apx profile sync` re-renders them from the package on disk, leaving settings and
+activation alone; `apx profile doctor` reports the drift so it is not silent. A routine the
+owner edited is skipped forever, by design, which also means a profile SETTING that lands in
+a routine stops taking effect on that routine once they have touched it.
+
 ## Channel overlays
 
 `channels/<ch>.md` is rendered and appended after the core `channels/<ch>.md`, only on that
@@ -115,7 +136,11 @@ install. Check the real number with `apx profile show <id>` or
 
 `GET /api/profiles` · `GET /api/profiles/:id` (includes `preview`) · `GET /api/profiles/doctor` ·
 `POST /api/profiles/install` · `POST /api/profiles/use` · `POST /api/profiles/off` ·
-`PATCH /api/profiles/config` · `DELETE /api/profiles/:id`
+`POST /api/profiles/sync` (re-applies a package's routines after an update — `apx profile sync`) ·
+`PATCH /api/profiles/config` · `DELETE /api/profiles/:id` ·
+`POST /api/profiles/readopt` (force the active profile's routines back to the package, past the
+user_modified/user_owned skips sync respects — `{ routine }` targets one, omit for all; the
+web "Re-sync routines" button. It discards local edits to the affected routines.)
 
 ## Gotchas
 

package/src/core/runtime-skills/apx-project/SKILL.md

@@ -40,7 +40,7 @@ Every `project config` write triggers `POST /api/admin/reload` so the daemon pic
 
 ## `<project>` argument resolution
 
-Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
+Accepted: numeric id (`1`), exact name from `.apc/project.json` (`acme`), absolute path, relative path (resolved from cwd). The CLI's `resolveProjectId()` does fuzzy id/name/path matching. If "project not found", run `apx project list` first.
 
 ## What lives where
 
@@ -49,6 +49,7 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
 ├── AGENTS.md                                   ← agent definitions (committed)
 └── .apc/
     ├── project.json                            ← { apxId, name, ... }
+    ├── memory.md                               ← curated project memory (committed, human-written)
     ├── agents/<slug>.md
     ├── skills/<slug>.md or <slug>/SKILL.md
     ├── mcps.json                               ← shared MCPs (committed)
@@ -56,6 +57,7 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
     └── config.json                             ← project-only overrides (edited by `project config`)
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
+├── memory.md                                   ← local project memory (what `remember` writes)
 ├── messages/YYYY-MM-DD.jsonl
 ├── agents/<slug>/{memory.md, sessions/, conversations/}
 ├── routines.json
@@ -64,6 +66,25 @@ Accepted: numeric id (`1`), exact name from `.apc/project.json` (`iacrmar`), abs
 └── mcps.json                                   ← per-project runtime MCPs (local, may hold tokens)
 ```
 
+## Project memory — two files, and you write only one
+
+What the PROJECT knows lives in two places, and the difference is a safety boundary:
+
+| File | Committed? | Written by |
+|---|---|---|
+| `~/.apx/projects/<apxId>/memory.md` | Never | You, with `remember` + `project` |
+| `<repo>/.apc/memory.md` | Yes, git carries it | The owner, by hand, after reading it |
+
+Write with `remember` and a `project` — never by creating a memory file yourself. A `MEMORY.md` at the repo root, or any other name, is read by nothing.
+
+```
+remember(note: "Northwind runs on Postgres in production", project: "northwind")
+```
+
+It lands in the local file on purpose. A note you write automatically can carry something the owner pasted into a chat, and a committed file is forever — APC keeps private runtime memory out of `.apc/`, which is only for curated facts that are safe for the team. If a fact belongs in the repo, say so and let the owner promote it from the Memories screen; do not write `.apc/memory.md` yourself unless they explicitly ask.
+
+Read either with `read_file`. Both are shown in the project's Memories screen and both are indexed for retrieval. For facts that matter on every channel, call `remember` with no `project` — those go to your own notebook.
+
 ## Anti-examples
 
 ```bash
@@ -74,7 +95,7 @@ mkdir -p /path/repo/.apc && echo "{...}" > /path/repo/.apc/project.json
 # Use `apx init <path>` then `apx project add <path>`.
 
 # DON'T set super_agent.model to a model lacking an engine key.
-apx project config set iacrmar super_agent.model gemini:gemini-1.5-pro
+apx project config set acme super_agent.model gemini:gemini-1.5-pro
 # ↑ Fails at first call unless engines.gemini.api_key is set.
 ```
 

package/src/core/runtime-skills/apx-routine/SKILL.md

@@ -13,11 +13,18 @@ A scheduled APX task. Scheduler ticks every 5s. Each routine has a `kind`, `sche
 |---|---|---|
 | `heartbeat` | no | "Still alive" marker. No LLM. |
 | `shell` | no | Pure shell. Stdout captured. |
-| `exec_agent` | **no** | Loads agent prompt, sends `spec.prompt`, returns text. Single LLM call. |
+| `exec_agent` | **agent allowlist** | Loads that project agent and runs `spec.prompt`. By default the agent uses its own resolved tools (its `tools:` field, or the broad capability default when it declares none). Persists a conversation. A **non-empty** routine `allowed_tools` overrides the card. For the one-shot text path (no tools at all), set `spec.no_tools: true` — see the gotcha below. |
+| `watch` | **agent allowlist** | Deterministic detection first, then a model judgement step over `spec.prompt`. A watcher, not a cron+LLM. Needs `spec.prompt`. |
 | `super_agent` | **all** | Default agent with full tool registry. Multi-iteration loop. |
-| `telegram` | n/a | Sends hardcoded text via Telegram plugin. |
+| `telegram` | n/a | Sends hardcoded text via Telegram plugin. `spec.text` is the message body — the automation header is NOT prepended to it. |
 
-Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent) → `super_agent`; pure shell → `shell`; fixed Telegram poke → `telegram`.
+Rule: a project agent that must *do* work (read files, Asana, compact a ledger) → `exec_agent`; orchestration as the super-agent → `super_agent`; text-only + shell delivery → `exec_agent` with `spec.no_tools: true`; pure shell → `shell`; fixed Telegram poke → `telegram`.
+
+### `allowed_tools` vs `no_tools` (read before you copy a skeleton)
+
+- `allowed_tools` **non-empty** → overrides the agent's card for this routine.
+- `allowed_tools: []` → **no override; the agent runs with its OWN resolved tools.** This is NOT "no tools" — and `[]` is exactly what `apx routine add` writes when you pass no `--allowed-tools`, so an ordinary create already gives the agent its tools.
+- `spec.no_tools: true` → the deliberate opt-out: a single text-only call, no tools, for the "write one sentence, `post_commands` deliver it" pattern.
 
 ## Schedule grammar
 
@@ -40,7 +47,18 @@ Rule: text from model → `exec_agent`; orchestration (MCPs, files, multi-agent)
 }
 ```
 
-Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run.
+Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_output}}` in `spec.prompt` / `spec.text` and `$APX_PRE_OUTPUT` (plus `$APX_PRE_OUTPUT_FILE` for big payloads) → handler runs, result becomes `$APX_LLM_OUTPUT` → `post_commands` run. `{{pre_output}}` is always substituted — with no pre_commands it renders empty, never as literal braces.
+
+## Automation header (native — don't hand-roll the date)
+
+The runner prepends a native **automation header** to the top of `spec.prompt` on every LLM-backed run (`core/routines/header.js`, built in `core/routines/runner.js`). It carries: routine name + id, the routine's memory path, `last_run_at` and this run's start — each clock given twice, machine-friendly (ISO + epoch ms, UTC) and human-friendly in the owner's `config.user.timezone` / `.locale`.
+
+This **replaces the old `echo "…date…"` pre_command + `{{pre_output}}` trick** for "what time / day is it". Do NOT add a shell pre_command just to feed the model the date — it already opens on who it is and what "now" is. The header is NOT prepended to a `telegram` routine's `spec.text` (that string is the message body, sent verbatim).
+
+## Iteration budget
+
+- A routine that **reports to Telegram** (its `post_commands` send via Telegram, so `send_telegram` is auto-suppressed) uses `super_agent.telegram_max_iters` (default `TELEGRAM_TOOL_ITERS`, a high runaway backstop) and normally runs until work is done.
+- Any **other** routine runs effectively **uncapped** to completion (`super_agent.routine_max_iters`, default `ROUTINE_UNCAPPED_TOOL_ITERS`): background work nobody is watching (Magui filling a backlog) must finish, not get cut at the chat budget. Only the `post_command` Telegram sink marks a routine telegram-bound — a routine whose *agent* sends a summary at the end is still uncapped.
 
 ## Anti-example: double-reply
 
@@ -52,12 +70,12 @@ Pipeline: `pre_commands` run sequentially → combined stdout becomes `{{pre_out
 }
 ```
 
-Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent`:
+Sends **two** messages: one from agent's `send_telegram` tool, one from `post_commands`. The runner auto-suppresses `send_telegram` when post contains `apx telegram send`, but the clean fix is `exec_agent` with tools off (`spec.no_tools: true` — NOT `allowed_tools: []`, which leaves the agent's tools on):
 
 ```json
 {
   "kind": "exec_agent",
-  "spec": { "agent": "default", "prompt": "The weather is {{pre_output}}. One friendly sentence." },
+  "spec": { "agent": "default", "no_tools": true, "prompt": "The weather is {{pre_output}}. One friendly sentence." },
   "post_commands": ["apx telegram send \"$APX_LLM_OUTPUT\""]
 }
 ```
@@ -66,12 +84,12 @@ Sends **two** messages: one from agent's `send_telegram` tool, one from `post_co
 
 ```bash
 # Always pin --project; never use default for real ones
-apx routine list --project iacrmar
-apx routine get  weather-bariloche --project iacrmar
+apx routine list --project acme
+apx routine get  weather-bariloche --project acme
 
 # Create — exec_agent + shell delivery
 apx routine add weather-bariloche \
-  --project iacrmar \
+  --project acme \
   --kind exec_agent \
   --schedule "every:24h" \
   --spec '{"agent":"default","prompt":"The weather is {{pre_output}}. One friendly sentence."}' \
@@ -80,17 +98,17 @@ apx routine add weather-bariloche \
 
 # Create — super-agent with tools
 apx routine add daily-status \
-  --project iacrmar \
+  --project acme \
   --kind super_agent \
   --schedule "0 9 * * *" \
   --spec '{"prompt":"List projects with pending tasks and send me a short summary via Telegram."}' \
   --permission-mode automatico
 
 # Toggle / run / remove
-apx routine enable  weather-bariloche --project iacrmar
-apx routine disable weather-bariloche --project iacrmar
-apx routine run     weather-bariloche --project iacrmar     # force-trigger now
-apx routine remove  weather-bariloche --project iacrmar
+apx routine enable  weather-bariloche --project acme
+apx routine disable weather-bariloche --project acme
+apx routine run     weather-bariloche --project acme     # force-trigger now
+apx routine remove  weather-bariloche --project acme
 ```
 
 ## `--project` is non-negotiable
@@ -99,7 +117,7 @@ Routines live in `~/.apx/projects/<apxId>/routines.json`. Without `--project`, t
 
 ## `skip_prompt_on`
 
-Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/routines.js`). Post-commands always run.
+Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `src/core/routines/runner.js`). Post-commands always run.
 
 | Value | Skips LLM when… |
 |---|---|
@@ -112,16 +130,21 @@ Gates the LLM call based on `pre_commands` (`shouldSkipPrompt` in `host/daemon/r
 ## Debugging
 
 ```bash
-apx routine history weather-bariloche --project iacrmar    # last runs
+apx routine history weather-bariloche --project acme    # last runs
 apx log -f                                                  # tail unified log
 apx messages tail --channel routine -n 20                   # routine-channel messages
+
+# Routine memory (the file named in the automation header)
+apx routine memory show weather-bariloche --project acme    # read it
+apx routine memory add  weather-bariloche "note" --project acme   # append a note
+apx routine memory path weather-bariloche --project acme    # print its path
 ```
 
 "Sends nothing" usually means: `enabled: false`, `next_run_at` in the future, or empty LLM text (check `apx messages` or `result.text`).
 
 ## Don't
 
-- Use `super_agent` when `exec_agent` would do — it loops, calls tools, costs more.
+- Use `super_agent` when a project agent should own the work — `exec_agent` runs that agent with tools and the chat lands under their name.
 - Write `apx telegram send` inside a `super_agent` prompt — agent calls `send_telegram` AND post_commands fire. Pick one.
 - Hardcode model names in `spec` without reason — routines inherit `super_agent.model` (with router fallback).
 - Put credentials in `spec`. Use `~/.apx/config.json` engines and reference by provider.