@timqi/pier 0.0.1 → 0.0.3

package/docs/deploy.md

@@ -24,17 +24,15 @@ you want the unit to say something different.
 ## Prerequisites
 
 - Node 24 or newer (`node:sqlite` is used unflagged).
-- The `sqlite3` CLI, for the off-machine backup and password steps below. Pier
-  itself does not need it.
-- A checkout, built once:
-
-```sh
-git clone git@github.com:timqi/pier.git ~/pier
-cd ~/pier && npm ci && npm run build
-```
-
-The unit below runs the build output, so a deploy is always "update the
-checkout, rebuild, restart" — never "run from source".
+- A user-writable global npm prefix. The updater runs as you, so an initial
+  install that needed `sudo npm install -g` cannot later update itself.
+- The `sqlite3` CLI is optional, for the off-machine backup and password steps
+  below. Pier itself and its automatic update backup do not need it.
+- Pier installed globally: `npm install -g @timqi/pier`. The unit runs that
+  installed entry point, so a deploy is `pier update`. A checkout
+  (`git clone` + `npm ci && npm run build`) is the *develop* path; point the
+  unit's `ExecStart` at its `dist/main.js` if you run one as the service, and
+  update it with the "From a checkout" steps under Updating.
 
 ## The unit
 
@@ -44,7 +42,7 @@ or as a dedicated system user means an agent that cannot touch the files you
 wanted it to work on.
 
 `~/.config/systemd/user/pier.service` — what `pier service install` generates,
-with your node and your entry point filled in:
+with your absolute Node and package paths filled in:
 
 ```ini
 [Unit]
@@ -55,29 +53,33 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=%h/pier
-# An absolute path on purpose: systemd starts with a minimal PATH, so a node
-# installed by nvm/fnm/asdf is not on it. `command -v node` gives you this.
-ExecStart=/usr/bin/node dist/main.js
-Environment=NODE_ENV=production
+WorkingDirectory=%h
+# Absolute paths on purpose: systemd starts with a minimal PATH, so a node
+# installed by nvm/fnm/asdf is not on it — the installer fills in the node
+# that installed Pier and the globally installed entry point.
+ExecStart="/absolute/path/to/node" "/absolute/npm/prefix/lib/node_modules/@timqi/pier/dist/main.js"
+Environment="NODE_ENV=production"
 # Loopback by default. Put a reverse proxy in front before widening this —
 # whoever reaches this port can drive an agent that runs a shell.
-Environment=HOST=127.0.0.1
-Environment=PORT=3141
-# Where the database, the boards and the generated password hash live.
-Environment=PIER_HOME=%h/.pier
+Environment="HOST=127.0.0.1"
+Environment="PORT=3141"
 Restart=always
 RestartSec=2
-# The journal is where the first-run password is printed, so keep it readable.
 StandardOutput=journal
 StandardError=journal
-# Otherwise every line is tagged "node"; this makes `journalctl -t pier` work.
 SyslogIdentifier=pier
 
 [Install]
 WantedBy=default.target
 ```
 
+`--pier-home` adds a quoted `PIER_HOME` environment line. Paths with spaces and
+literal systemd `%` specifiers are escaped. `pier service install` also writes an
+updater unit containing the exact npm executable currently on `PATH`. Re-run with
+`--force` after changing service settings or the Node/npm installation; it
+rewrites both units and restarts the running service. The limits drop-in remains
+operator-owned and is never overwritten.
+
 Enable it, and tell logind to keep your user manager alive after you log out —
 without lingering, every scheduled task stops when your SSH session ends:
 
@@ -167,7 +169,9 @@ journalctl --user -u pier --since -1h | grep 'tasks:'   # one area
 ```
 
 Every line is `area: message` — `core`, `agent`, `tasks`, `slack`, `telegram`,
-`channels`, `web`, `auth`, `boards`, `client`, `pier` — so an area is a grep
+`channels`, `slack.tool`, `auth`, `boards`, `client`, `db`, `drain`, `secrets`,
+`settings`, `credentials`, `update`, `web.providers`, `pier` — so an area is a
+grep
 and a level is a `-p`. The level reaches journald as a syslog priority prefix, which Pier
 emits only when systemd says the output is a journal (`$JOURNAL_STREAM`); run
 in a terminal, the same lines carry a timestamp and a level word instead.
@@ -214,42 +218,105 @@ new password is generated and printed:
 
 ```sh
 sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'
-systemctl --user restart pier
+pier restart
 ```
 
 Changing the password invalidates every session cookie: the cookies are signed
 with the stored hash.
 
+## Restarting and reloading
+
+```sh
+pier restart          # finish active work, then restart the service
+pier reload           # apply channel config and recycle idle sessions in place
+```
+
+Both commands signal the installed systemd service; they are not foreground
+process controls. `pier restart` refuses new messages and root Task runs, waits
+up to five minutes for active work, then exits for `Restart=always` to start the
+next process. At the deadline it records every aborted IM turn first, and the
+next process posts that note after its adapter starts. Cleanup after the deadline
+has one shared 10-second bound regardless of how many sessions are stuck.
+
+`pier reload` does not stop active work. It reloads Slack and Telegram adapters
+and immediately evicts idle sessions nobody is watching, so their next message
+opens with current agent files and configuration. Streaming sessions and
+sessions held by an open workbench stay attached until their normal eviction.
+
+An ordinary `systemctl --user restart pier` and `pier update` remain fast,
+hard-stop paths. Let active work finish first when using either one.
+
 ## Updating
 
-Manually, which is also exactly what an automated update has to do:
+```sh
+pier update           # installs the latest release; hard-stops/restarts Pier
+pier update --check   # only says whether one exists
+```
+
+The workbench footer says the same thing without being asked: the server checks
+`registry.npmjs.org` every six hours in the background, and the version turns
+into `v0.0.1 → 0.0.2` when there is something newer. A failed check is silent
+by design — an offline box is not a broken one.
+
+From a checkout instead, stop and back up before replacing the build:
 
 ```sh
+systemctl --user stop pier
+pier backup
 cd ~/pier
-git fetch --tags && git checkout v0.2.0   # a tag, not a branch
+git fetch --tags && git checkout v0.0.2   # a tag, not a branch
 npm ci && npm run build
-systemctl --user restart pier
+systemctl --user start pier
+```
+
+For a service install, `pier update` stops Pier first; it does not use the
+graceful `pier restart` path. The Console's **Update now** and the automatic
+path do: both drain (new work refused, running turns finished, the rest
+ledgered for the next boot to report) before the updater unit is started.
+
+Either way the updater snapshots the database to
+`~/.pier/db/pier.db.release.bak` before npm touches the package. This happens for
+every release, including releases with no schema change. If installation or
+backup fails, the updater unit still tries to start the previously installed
+service and reports the failure in its journal.
+
+### Automatic updates
+
+Off by default. Switched on from the version panel, it checks every 15 minutes
+and hands over only when all three hold: the switch is on, a newer release
+exists, and the instance is idle (nothing streaming, no task run in flight).
+systemd only — without the unit there is nothing to hand the install to.
+
+The unit records **absolute** paths to the node and npm that installed Pier,
+because systemd's PATH has neither. That pins it to one directory of one version
+manager: with fnm or nvm, `fnm uninstall v24` deletes the Node that `ExecStart`
+names while the running process survives (Linux keeps a deleted binary mapped).
+Pier checks those paths at boot and before every handover, and reports it in the
+journal and in the version panel rather than letting the next restart fail:
+
+```
+pier service install --force    # re-records the current node and npm
 ```
 
 A newer Pier brings its own schema up on the next start: the migrations run in
 one transaction before the port opens, and the version they leave behind is
-stamped in the database. Before touching an existing database it snapshots it
-to `~/.pier/db/pier.db.v<N>.bak` (`N` = the schema it was at), so the step you
-cannot forget is the one you never take. **Upgrades only.** Start an older Pier
-on a database a newer one has migrated and it refuses to run rather than write
-tables it does not understand — the way back down is that `.bak`:
+stamped in the database. It also snapshots the immediately preceding schema to
+`~/.pier/db/pier.db.v<N>.bak` (`N` = the schema it was at). **Upgrades only.**
+Start an older Pier on a database a newer one has migrated and it refuses to run
+rather than write tables it does not understand — the way back down is either
+the release backup or that schema snapshot:
 
 ```sh
 systemctl --user stop pier
-cd ~/.pier/db && rm -f pier.db pier.db-wal pier.db-shm && cp pier.db.v1.bak pier.db
-# then check out the Pier that speaks schema 1 again
+cd ~/.pier/db && rm -f pier.db pier.db-wal pier.db-shm && cp pier.db.release.bak pier.db
+# then reinstall the Pier release that created that backup
 ```
 
-The three newest snapshots are kept and older ones removed as later upgrades
-supersede them; each is a full copy of the database, so size grows with the
-database, not with the number of releases. They sit next to the database and
-therefore protect against a bad upgrade, not against a lost disk — an
-off-machine copy is still yours to take.
+The release backup is replaced atomically on each update. The three newest
+schema snapshots are also kept and older ones removed as later migrations
+supersede them. Each is a full copy of the database. They sit next to the
+database and therefore protect against a bad upgrade, not against a lost disk —
+an off-machine copy is still yours to take.
 
 ### Can it update itself?
 
@@ -259,32 +326,33 @@ in `pier.service`'s cgroup, so an update script spawned by Pier dies halfway
 through — sometimes after unpacking and before restarting, which is the one
 outcome worse than not updating.
 
-So the update runs as its own unit. `~/.config/systemd/user/pier-update.service`:
+So installation writes a second unit and `pier update` starts it after recording
+the running service's effective `PIER_HOME` in a runtime drop-in. That includes
+an operator environment override, so the updater cannot back up one database and
+migrate another. `~/.config/systemd/user/pier-update.service`:
 
 ```ini
 [Unit]
-Description=Update Pier to the latest tag
+Description=Update Pier to the latest published version
 
 [Service]
 Type=oneshot
-WorkingDirectory=%h/pier
-ExecStart=/bin/sh -lc 'git fetch --tags && git checkout "$(git describe --tags --abbrev=0 origin/main)" && npm ci && npm run build'
-ExecStartPost=/bin/sh -lc 'systemctl --user restart pier'
+ExecStart=systemctl --user stop pier.service
+ExecStart=/path/to/node /path/to/pier/dist/cli.js backup
+ExecStart=/path/to/node /recorded/path/to/npm install -g @timqi/pier@latest
+ExecStopPost=systemctl --user start pier.service
 ```
 
-Pier can then trigger an update with a single call that survives its own
-restart, because the work happens in a different cgroup:
-
-```sh
-systemctl --user start pier-update.service
-```
+`pier update` triggers that unit with a call that survives Pier's restart because
+the work happens in a different cgroup. Starting the unit directly is unsupported:
+the command first records the effective database home used by the running service.
 
 Deliberately **not** a `systemd.timer`. An unattended update is a machine that
-rewrites its own code from the network while holding your API keys, and it
-interrupts whatever session was mid-turn to do it. The intended shape is that
-Pier notices a newer release and says so (not built yet), while starting the
-update stays a decision someone makes. `Restart=always` above is what makes
-that decision cheap — the service comes back on its own.
+rewrites its own code from the network while holding your API keys, and its hard
+stop interrupts whatever session was mid-turn. Pier notices a newer release
+and says so in the workbench footer; starting the update stays a decision someone
+makes. The updater's `ExecStopPost` is what brings the service back after both
+success and failure.
 
 ## Remote access
 
@@ -294,14 +362,24 @@ elsewhere, pick a tunnel rather than a wider bind:
 - `ssh -L 3141:localhost:3141 server` — nothing to configure, nothing exposed.
 - Tailscale, or Cloudflare Tunnel — no open port, and TLS terminates outside.
 - A reverse proxy (Caddy, nginx) if you want a real hostname. Terminate TLS
-  there and pass `X-Forwarded-For`; Pier's login throttle counts per forwarded
-  client, and its session cookie is marked `Secure` when the proxy reports
-  `X-Forwarded-Proto: https`.
+  there, preserve the external `Host` (or pass `X-Forwarded-Host`), and pass
+  `X-Forwarded-For`; Pier uses the external host for write-origin checks and
+  counts login failures per forwarded client. Its session cookie is marked
+  `Secure` when the proxy reports `X-Forwarded-Proto: https`.
 
 ## Backups
 
-Two paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
-session map, workbench state, settings, the password hash) and
-`~/.pier/boards/`. Copy the database with `sqlite3 ... "VACUUM INTO '…'"`
-rather than `cp`, which under WAL can miss the most recent commits. Pi's own session history lives under its
-config directory (`PI_CODING_AGENT_DIR`, `~/.pi/agent` by default).
+Three paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
+session map, workbench state, settings, the password hash, and the sealed
+provider credentials and channel tokens), `~/.pier/master.key` (the key that
+seals them — without it the database's sealed values are unreadable), and
+`~/.pier/boards/`. `pier.db.release.bak` is the latest automatic pre-update copy.
+For off-machine backups, use `sqlite3 ... "VACUUM INTO '…'"` rather than `cp`,
+which under WAL can miss the most recent commits. Pi's own session history lives
+under `~/.pier/pi` (Pier sets `PI_CODING_AGENT_DIR` there unless the environment
+already names another directory).
+
+Inbound chat attachments (photos, uploads from any surface) accumulate under
+`~/.pier/inbox/<channel>/` and are never deleted by Pier — a transcript may
+reference them indefinitely. Prune old files by hand (or a cron) when disk
+matters; a pruned file degrades to a broken attachment link, nothing else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
   "license": "AGPL-3.0-only",
   "repository": "github:timqi/pier",

package/skills/pier-boards/SKILL.md

@@ -38,18 +38,23 @@ Those four fields are the whole manifest.
 
 `"public": true` serves the board at `/p/<slug>/` **with no password**. Set it
 only if the user asked for a public or shareable board *in this request*;
-otherwise leave it `false`, say the board is private, and mention that Console →
-Boards flips it. Never publish credentials, internal paths, personal data or
-anything the user has not seen.
+otherwise leave it `false` and say the board is private. Never publish personal
+data or anything the user has not seen.
 
-The message announcing the board carries **one clickable link** — a bare path is
-not something a person can open, and a board nobody reached was not delivered.
+Asked to make an existing board public? Flip `"public"` to `true` in
+`board.json` and reply with the `/p/<slug>/` link — that is the whole answer.
+No verification step, no narrating the edit, no restating what the page holds.
+
+The message announcing the board carries **one bare URL** — paste the address
+itself, never `[title](url)`: link labels get mangled or truncated on some chat
+surfaces, and the title is already on the page. No filesystem paths either —
+`…/boards/<slug>/board.json` means nothing to the reader.
 `<pier>/AGENTS.md` gives you the address, so there is nothing to look up:
 
 | The user asked for | Send |
 | --- | --- |
-| a board, nothing about sharing | `[Weekly digest](https://pier.example.com/boards/weekly-digest/)` — behind the Pier password |
-| a **public** board | `[Weekly digest](https://pier.example.com/p/weekly-digest/)` — no password |
+| a board, nothing about sharing | `https://pier.example.com/boards/weekly-digest/` — behind the Pier password; Console → Boards makes it public |
+| a **public** board | `https://pier.example.com/p/weekly-digest/` — no password |
 
 Never both: the pair invites pasting the password-free URL of a board that was
 never meant to leave the workspace, and `/p/<slug>/` 404s unless the manifest
@@ -180,6 +185,10 @@ what makes it read as signal.
 
 ## Rules
 
+- **No secrets, ever.** Tokens, API keys, credentials, internal hostnames and
+  private paths never go into a board — not in the page, not in a `<details>`
+  fold, not in a code sample. A private board is one Console toggle from
+  public, so write every page as if it already were.
 - **Static and self-contained.** Everything the page needs lives under `site/`
   with relative paths. No CDN, no external fonts, no analytics, no `fetch()` —
   a published board is served under a CSP that blocks all of it, so an external

package/skills/pier-help/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: pier-help
+description: How Pier itself works — durable sessions and what survives a restart, how messages and files reach you from Slack and Telegram, in-chat commands (/stop, /settings, /bind), interrupting a running turn, and what only the operator's Console can change. Read before explaining Pier's behavior or advising a user on how to use it.
+---
+
+# How Pier works
+
+Pier is the workspace this session runs in: agent sessions behind chat
+surfaces — a web workbench and IM channels (Slack and Telegram today) — plus
+scheduled tasks, subagents and boards. Answer questions about it from the
+facts below. If the answer is not here, say you do not know how this instance
+is configured rather than guessing: the Console (Pier's admin web UI) is the
+operator's source of truth.
+
+## Sessions and persistence
+
+- One durable session per conversation: a web chat, a Slack thread, a
+  Telegram chat or topic. The mapping survives restarts — the next message
+  lands in the same transcript with its context intact.
+- Idle sessions leave memory but keep their transcript; they resume
+  transparently on the next message. Never promise that a restart or a pause
+  wipes context.
+- A fresh start is explicit: "New session" in the chat settings panel or the
+  web UI. The old transcript remains readable from the web workbench.
+- The web workbench can also rewind to an earlier user turn and re-prompt;
+  IM surfaces cannot.
+- A long session does not hit a wall: when the context fills, Pi compacts it
+  automatically — older turns become a summary. The transcript on disk keeps
+  everything, but detail can leave *your* context, so a very old turn is worth
+  re-reading rather than recalling. The web session header shows context used
+  and how much is left.
+
+## Files and images the user sends
+
+- A photo or file sent on any surface (web paste, Telegram photo/document,
+  Slack upload) is saved to `$PIER_HOME/inbox/` and reaches you as a trailing
+  `[name](file:///…)` line on the message — a path, not the content.
+- Read it with the read tool only when it matters to the task: every read
+  puts the content in your context for good. An image you never read costs
+  nothing.
+- The file stays on disk after the conversation moves on; link it back
+  (`[name](file:///…)`) whenever the user asks for it again.
+
+## Messages while you are working
+
+- On the web, a message sent mid-turn queues as a follow-up and lands after
+  the turn; a leading `!` interrupts instead — `!wrong file, stop` is injected
+  into the running turn as a steer.
+- From an IM chat, every mid-turn message steers the running turn directly —
+  no `!` needed, and a leading `!` is just content.
+- `/stop` aborts the current turn outright.
+
+## In-chat commands and the settings panel
+
+- `/settings` — or an addressed message with no text at all (a bare mention,
+  an empty DM) — opens a panel: model, reasoning level, new session
+  (optionally in a chosen directory), stop. Slack also accepts the bare words
+  `stop`, `settings`, `bind <code>`.
+- Panel taps never reach you. The next-step buttons under your own replies
+  do — a click arrives as an ordinary user message with that label.
+
+## What a turn looks like from outside
+
+- Telegram and Slack put a 👀 on the message that started a turn and take it
+  off when the turn settles; a restart and a periodic sweep clear stragglers.
+  A 👀 that never clears means the turn died, not that you are still thinking.
+- Every finished reply carries its cost: elapsed time and the context size at
+  completion (`1m14s · 32K tok`) — a running total, not this turn's spend. IM
+  shows it as a footer line, the web on hover.
+- A reply past the platform's message cap is split across several messages
+  (Telegram ~3.8k chars); the footer and the next-step buttons ride the last
+  one.
+
+## Who may talk (groups and binding)
+
+- Group messages pass a per-chat gate the operator sets: it can require a
+  mention, require the sender to be bound, or both. Dropped messages are
+  logged, never answered.
+- Binding: the operator issues a code in the Console; the user DMs the bot
+  `/bind <code>` (Slack: `bind <code>`). Codes expire after ~10 minutes.
+- An unbound DM sender is told how to bind at most once per 10 minutes;
+  their other messages are dropped. "The bot ignores my DMs" usually means
+  not bound.
+
+## Service restart, reload and update
+
+- `pier restart` is the graceful systemd path: it refuses new work, waits up to
+  five minutes for active turns and Task runs, then restarts. If the deadline
+  aborts an IM turn, the next process tells that conversation.
+- `pier reload` stays in-process: channel adapters re-read configuration and
+  idle, unwatched sessions reopen with current agent files on their next
+  message. Streaming or watched sessions are not interrupted.
+- `pier update` is deliberately different: the separate updater hard-stops the
+  service, backs up the database, replaces the package, and starts it again.
+  It can interrupt active work. All three are operator shell commands for an
+  installed Linux systemd service, not tools available to the agent.
+
+## Only the Console can change
+
+Channel tokens and connections, per-chat gate policies, bind codes, provider
+logins and credentials, the public address, security unlock. You have no tool
+for any of these: point the user at the Console instead of improvising.
+
+## The rest of the surface
+
+- Chat conventions — next-step buttons, `file://` attachments, staying
+  silent, `[name<id> time]` sender headers — are in `<pier>/AGENTS.md`,
+  already in your context.
+- Delegating and scheduling work: the pier-tasks skill. Reading and posting
+  Slack: pier-slack. Presenting a report as a page: pier-boards.

package/skills/pier-slack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-slack
-description: Read and write Slack through Pier's slack tool — a channel's history for a time range, one thread, posting into a thread, and the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
+description: Read and write Slack through Pier's slack tool — a channel's history for a time range, one thread, posting into a thread, deleting a message Pier posted, and the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
 ---
 
 # Reading and writing Slack
@@ -31,8 +31,9 @@ wanted. `not_in_channel` means someone must run `/invite @Pier`.
 You already have them:
 
 - **The person talking to you** — a message may start with `[name<id> time]`,
-  added by Pier, not typed by them. It appears only when the speaker or the day
-  changes, so the last one you saw still applies.
+  added by Pier, not typed by them. It appears only on a change — new speaker,
+  a time gap, a new day — so the last one you saw still applies (a gap alone
+  shows as time only, like `[14:23]`).
 - **Anyone in a transcript** — every line carries `name[id]`.
 - **This channel and thread** — from `context`.
 
@@ -96,6 +97,22 @@ Going top-level takes the explicit `"none"`: a channel's main flow is wider
 than a thread. A `thread_ts` is never inherited across a change of `channel`.
 The response carries `ts` and `threadTs` for replying under what you posted.
 
+## Deleting
+
+```json
+{"operation":"delete","channel":"#ops","ts":"1717243800.000100"}
+```
+
+Slack only lets Pier delete what **its own bot** posted — a person's message
+answers `cant_delete_message`, and the answer is to ask them, not to retry.
+
+- `ts` is always explicit. There is no "delete the last one" and no default
+  from the thread you are in: the wrong `ts` cannot be undone.
+- A `ts` means nothing outside the conversation it came from — pass the
+  `channel` it was read in.
+- Deleting a thread parent does not remove its replies. Say what you removed;
+  a message vanishing with no word looks like a Slack bug to everyone watching.
+
 ## Message syntax
 
 `text` is **standard markdown** and Slack renders it natively: `**bold**`,

package/skills/pier-tasks/SKILL.md

@@ -70,18 +70,25 @@ history) — every prompt must be self-contained: paths, acceptance criteria,
 expected output format. Branching and retries are your own logic between
 turns.
 
-## Choosing a model
-
-Omit `launch.model` to inherit your own model — the right default. Override
-only when the task profile clearly differs:
-
-- `anthropic/claude-opus-5` — hardest reasoning: architecture, gnarly debugging
-- `anthropic/claude-fable-5` — long autonomous implementation runs
-- `anthropic/claude-sonnet-5` — balanced default: implementation, review
-- `anthropic/claude-haiku-5` — cheap and fast: listings, extraction, simple checks
-- `openai/gpt-5.6` series (e.g. `gpt-5.6-sol`) — cross-vendor second opinion
-
-An unknown id fails with the available models listed in the error.
+## Choosing a model and thinking level
+
+Omit `launch.model` to inherit your own model — the right default. When the
+task profile clearly differs, adjust in this order:
+
+- **Harder reasoning → raise `launch.thinking` first**, on the inherited
+  model (`off` … `minimal` `low` `medium` `high` `xhigh` `max`). It needs no
+  model name and is usually cheaper than switching models.
+- **Cheap bulk work** (listings, extraction, simple checks) → the same
+  provider's smallest current model, with thinking low or off.
+- **Cross-vendor second opinion** → another vendor's flagship.
+
+Never write a model id from memory — catalogs move under you.
+`{"operation":"models"}` is the authority: it returns the deployment's menu —
+operator-pinned models when set (`source:"menu"`), each with an intent note
+and often a usual `thinking` level, the curated live catalog otherwise
+(`source:"catalog"`). Prefer a pinned entry whose note matches the task and
+start from its thinking level. A wrong id still fails with the available
+list in the error, so a stale guess costs one call.
 
 ## Mid-run control