pidge-cli 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.13.0 — 2026-06-25
+
+Template system (#246) — the agent now declares an intent TYPE; the server maps it to
+the human's delivery profile (the human never sees the type). Soft-rollout: typeless
+sends still work in 0.13.x (server falls back to `fyi`); 0.14 will require a type.
+
+- **feat:** 6 type subcommands — `pidge fyi` · `report` · `ask` · `event` · `alert` ·
+  `live`. Each stamps `template_kind` on the `/notify` payload. fyi/report/event/alert/
+  live are fire-and-forget (like `notify`); `ask` send+waits for the answer. (#246)
+- **feat:** `pidge notify` (and `pidge send`) is **deprecated** with a local warning —
+  it still works for one minor (0.13.x; the server falls back to `fyi`) and will 422 in
+  0.14. Use a typed send instead. (#246)
+- **feat:** local validation before the round-trip — `ask` requires a way to answer
+  (`--actions`, `--custom-action`, or a `--template` that supplies them); `event`
+  requires a valid ISO8601 `--event-at`. Friendly exit-1 errors, nothing sent. (#246)
+- **feat:** `alert --escalate` adds `escalate: true` (ask the Urgente profile for an
+  AlarmKit alarm that breaks through silent/Focus; the human's profile decides). (#246)
+- **feat:** an unknown subcommand now points at the type catalog instead of dumping the
+  whole USAGE; `pidge <type> --help` shows each typed send's own flags. (#246)
+- **docs:** `pidge skill install` writes a **"Choose the right type"** catalog table
+  into the generated `SKILL.md`. (#246)
+
+## 0.12.0 — 2026-06-25
+
+CLI bugs batch, all reported by an agent in real production use. No breaking changes.
+
+- **fix:** `pidge <sub> --help` shows the SUBCOMMAND's own help (its synopsis + own
+  flags), not the global USAGE dump — e.g. `pidge ask --help` now leads with ask's
+  `--actions`/`--timeout` instead of burying them. `pidge --help` and `pidge help`
+  still show the full command overview; `pidge help <cmd>` is the focused form. (#240)
+- **feat:** the "server has new capabilities" manifest-version nag is throttled to
+  **once per 24 h** (cached in `~/.config/pidge/state.json`, per-agent when
+  `PIDGE_AGENT` is set) and only re-fires when the server version actually changed —
+  no more a nag on every call. New `--quiet-nag` flag and `PIDGE_QUIET_NAG=1` env to
+  silence it entirely (scripts/CI). (#241)
+- **feat:** `--actions` accepts a **JSON array** of custom `{id,label,…}` actions for
+  custom labels — `--actions '[{"id":"approve","label":"Aprovar agora"},{"id":"defer","label":"Deixa pra amanhã"}]'`.
+  A leading `[` selects JSON; bad JSON / a missing `id`/`label` is a friendly LOCAL
+  error (exit 1, nothing sent). The short form `--actions yes,no,reply` is unchanged,
+  and JSON composes with `--custom-action`. (#242)
+- **docs:** the manifest re-read instruction (the version nag) now shows the
+  **authenticated** curl — `curl -H "Authorization: Bearer $PIDGE_TOKEN" $PIDGE_URL/api/v1/manifest`
+  — so an agent that follows it doesn't take a 401. (#243)
+- **docs:** `pidge skill install` now writes an **"always-on for turn-based agents"**
+  recipe into the generated `SKILL.md` — an interactive listening window
+  (`pidge listen --follow`) and a no-daemon supervisor poll (looped one-shot
+  `pidge listen`). (#244)

package/README.md

@@ -11,6 +11,15 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > current spec (fields, profiles, guarantees). This CLI is a thin pipe over it — any
 > new server field works without a CLI update via `--param key=value`.
 
+> **New in v0.12.0** — CLI bugs batch (all reported by an agent in real use): **`pidge
+> <sub> --help`** now shows that subcommand's own help (its flags), not the global dump
+> (#240); the **manifest-version nag is throttled to once / 24 h** (cached in
+> `~/.config/pidge/state.json`) with `--quiet-nag` / `PIDGE_QUIET_NAG=1` to silence it
+> (#241); **`--actions` accepts a JSON array** of custom `{id,label}` actions for custom
+> labels (#242, the short `yes,no,reply` form unchanged); the nag's manifest re-read
+> example now shows the **`Authorization: Bearer`** header so it doesn't 401 (#243); and
+> `skill install` writes an **"always-on for turn-based agents"** recipe (#244).
+>
 > **New in v0.9.0** (ships with Pidge manifest v27): **`listen` no longer consumes on
 > read** — a read message is DELIVERED, and you `ack` it after the work (a ~10-min
 > server lease re-serves un-acked messages, so a crash never loses one; `--ack-on-read`
@@ -192,10 +201,12 @@ WebSocket  →  ?wait= long-poll (capped 25 s server-side)  →  plain GETs ever
                         and saves on the phone; uploaded automatically (≤25 MB)
 --url URL               deep link the app opens when the user taps (PR, dashboard, log)
 --copy TEXT             value offered as tap-to-copy on the detail (code, token)
---actions LIST          comma list: yes,no,approve,reject,accept,decline,later,
-                        done,snooze,reschedule,reply,mute
+--actions LIST|JSON     comma list of catalog ids: yes,no,approve,reject,accept,
+                        decline,later,done,snooze,reschedule,reply,mute — OR a JSON
+                        array of custom actions for your own labels:
+                        '[{"id":"approve","label":"Aprovar agora"},{"id":"defer","label":"Depois"}]'
 --custom-action SPEC    "id:label[:destructive][:confirm][:biometric][:terminal]"
-                        (repeatable — your own buttons)
+                        (repeatable — your own buttons; composes with --actions JSON)
 --deliver-at ISO8601    schedule for later
 --reply-to URL          also POST the answer to your webhook (HMAC-signed)
 --correlation-id ID     idempotency + routing key (auto-generated if omitted)

package/bin/pidge.js

@@ -103,6 +103,7 @@ const OPTIONS = {
   'event-at': { type: 'string' },              // WHEN the thing happens (profile event)
   'lead-minutes': { type: 'string' },          // notify/countdown lead before event_at
   urgency: { type: 'string' },                 // normal | persistent | alarm (low-level — prefer --profile)
+  escalate: { type: 'boolean' },               // #246: alert type — force an AlarmKit alarm (escalate:true)
   image: { type: 'string' },                   // banner+feed image: local path → uploaded; URL → as-is
   file: { type: 'string' },                    // real artifact (xlsx/pdf/csv…): local path → uploaded
   url: { type: 'string' },                     // deep link the app opens on tap (#45)
@@ -126,6 +127,7 @@ const OPTIONS = {
   // realtime (#118): WS by default when the runtime has a WebSocket (Node ≥22)
   realtime: { type: 'boolean' },               // force WS (warn+fallback if unavailable)
   'no-realtime': { type: 'boolean' },          // polling only
+  'quiet-nag': { type: 'boolean' },            // #241: silence the manifest-version nag for this run
   // onboarding v2 (#110)
   claim: { type: 'string' },                   // setup --claim <single-use code>
   // #157 P2: listen keeps going after a batch (supervisor loop, one process)
@@ -161,8 +163,14 @@ USAGE
                                           narrated LIVE on the lock screen by a 3-stage Live Activity
                                           (Conectando → toque para confirmar → Concluído ✓). send + wait
                                           in one — run it as your FIRST contact on a fresh channel.
-  pidge ask    [options]                  send AND wait for the answer (prints chosen_action JSON)
-  pidge notify [options]                  send only (prints the 201 JSON)
+  TYPED SENDS (#246 — pick the one that matches your INTENT):
+  pidge fyi    [options]                  passive info, no action — log/registro (template_kind fyi)
+  pidge report [options]                  a curated result the human will want to read now (report)
+  pidge ask    [options]                  a DECISION — send AND wait; needs --actions (prints chosen_action JSON)
+  pidge event  [options]                  a scheduled thing with a time — needs --event-at (event)
+  pidge alert  [options]                  an anomaly/error; --escalate forces an AlarmKit alarm (alert)
+  pidge live   [options]                  an in-flight task with incremental updates (live)
+  pidge notify [options]                  DEPRECATED (0.13.x) — send without a type (server falls back to fyi)
   pidge wait   <correlation_id> [options] block on an already-sent notification
   pidge cancel <correlation_id>           cancel a still-scheduled notification (#56)
   pidge inbox  [--pending|--summary|--all|--limit N]   what you sent: list, pending slice, or counts+latency (#83)
@@ -268,6 +276,191 @@ only: it never produces an answer, so \`ask\` refuses it.
 
 Full spec (the contract — always current): GET $PIDGE_URL/api/v1/manifest`;
 
+// ---------------------------------------------------------------------------
+// #240: per-subcommand help. `pidge <cmd> --help` (and `pidge help <cmd>`) must
+// show the focused help for THAT command — its synopsis, what it does, and only
+// the flags that apply — instead of dumping the global USAGE (the bug an agent
+// hit: `pidge ask --help` listed the global flags, burying ask's own
+// --actions/--timeout). The global USAGE stays the no-command / `pidge --help`
+// view. One option dictionary feeds both so the text can't drift.
+// ---------------------------------------------------------------------------
+const OPTION_DOCS = {
+  title: '--title TEXT             (required) the headline',
+  body: '--body TEXT              the message shown on the banner',
+  'body-markdown': '--body-markdown MD       rich body for the tap-through detail screen',
+  subtitle: '--subtitle TEXT          a secondary line under the title',
+  template: '--template ID            content/action pattern: context · decision · approval · reminder · nudge · sensitive',
+  profile: '--profile ID             delivery profile (the human owns it): default · event · escalating · custom',
+  'event-at': '--event-at ISO8601       WHEN the thing happens (required by profile event)',
+  'lead-minutes': '--lead-minutes N         notify/countdown N min before event_at (5–240)',
+  urgency: '--urgency LEVEL          normal | persistent | alarm (low-level — prefer --profile)',
+  escalate: '--escalate               alert: force an AlarmKit alarm that breaks through silent/Focus',
+  image: '--image PATH_OR_URL      banner+feed image: a local path is uploaded; an https URL is sent as-is',
+  file: '--file PATH              a real artifact (xlsx/pdf/csv…) uploaded for the human (≤25 MB)',
+  url: '--url URL                deep link the app opens on tap (PR, dashboard, log)',
+  copy: '--copy TEXT              tap-to-copy value on the detail screen',
+  actions: '--actions LIST|JSON      comma list from the catalog (yes,no,reply) OR a JSON array of {"id","label"} custom actions',
+  'custom-action': '--custom-action SPEC     "id:label[:destructive][:confirm][:biometric][:terminal]" (repeatable)',
+  'deliver-at': '--deliver-at ISO8601     schedule the send for later',
+  'reply-to': '--reply-to URL           also POST the answer to your webhook (HMAC-signed)',
+  'correlation-id': '--correlation-id ID      idempotency + routing key (auto-generated if omitted)',
+  thread: '--thread ID              conversation handle (#49): same id ⇒ one strand on the phone',
+  after: '--after CID              decision queue (#157): held until that notification is answered',
+  'collapse-key': '--collapse-key KEY       replace/update a prior notification',
+  param: '--param KEY=VALUE        pass ANY raw /notify field (repeatable) — the manifest is the contract',
+  timeout: '--timeout SECONDS        how long to block (ask: 600 · wait: 300 · listen: 600)',
+  interval: '--interval SECONDS       FALLBACK poll cadence (default 30) — normally unused (WS/long-poll)',
+  realtime: '--realtime               force the realtime WebSocket (warn + fall back to polling if unavailable)',
+  'no-realtime': '--no-realtime            polling only (skip the WebSocket)',
+  pending: '--pending                only delivered + still-unanswered notifications',
+  summary: '--summary                counts + answer latency (one call)',
+  'all-inbox': '--all                    whole-account scope (not just this channel)',
+  'all-listen': '--all                    single ear: also hear notification ANSWERS, not just messages (#131)',
+  limit: '--limit N                cap the number of rows',
+  claim: '--claim CODE             the single-use setup code (the human copies it from the Pidge app)',
+  'url-base': '--url BASE               the Pidge server base URL (default https://pidge.sh)',
+  print: '--print                  emit `export …` lines instead of writing a file (per-agent; you run it)',
+  force: '--force                  overwrite a shared config owned by another channel',
+  'listen-mode': '--listen-mode MODE       declare how you operate: turn_based | persistent | external_daemon',
+  follow: '--follow                 KEEP listening until --timeout (supervisor-only; traps a turn-based agent)',
+  'ack-on-read': '--ack-on-read            consume messages on read (pre-0.9 immediate-consume)',
+  'up-to': '--up-to ID               process every message up to this id',
+  ids: '--ids a,b                process this comma-list of ids',
+  renew: '--renew                  heartbeat the visibility-timeout lease instead of processing',
+  window: '--window N               reachability window in seconds (default 30)',
+  'quiet-nag': '--quiet-nag              silence the "server has new capabilities" nag for this run',
+};
+// Content flags shared by notify / ask / hello.
+const CONTENT_OPTS = ['title', 'body', 'body-markdown', 'subtitle', 'template', 'profile',
+  'event-at', 'lead-minutes', 'urgency', 'image', 'file', 'url', 'copy', 'actions',
+  'custom-action', 'deliver-at', 'reply-to', 'correlation-id', 'thread', 'after',
+  'collapse-key', 'param'];
+
+const HELP = {
+  setup: {
+    summary: 'one-shot onboarding (#110): exchange a single-use claim code for the channel key, store it, run doctor.',
+    usage: 'pidge setup --claim CODE [--url BASE] [--print] [--force] [--listen-mode MODE]',
+    body: 'The CLI writes the key itself (chmod 600) — it never appears on screen or in the agent\'s chat. MULTI-AGENT: set PIDGE_AGENT=<id> at each agent\'s launch for an isolated config.',
+    opts: ['claim', 'url-base', 'print', 'force', 'listen-mode'],
+  },
+  doctor: {
+    summary: 'validate the setup WITHOUT exposing secrets (env source, server, key, device reach, realtime probe).',
+    usage: 'pidge doctor',
+    opts: [],
+  },
+  whoami: {
+    summary: 'which channel does this key speak for (prints the identity JSON).',
+    usage: 'pidge whoami',
+    opts: [],
+  },
+  hello: {
+    summary: 'first-contact WOW (#217): your channel\'s debut handshake, narrated live by a 3-stage Live Activity. send + wait in one.',
+    usage: 'pidge hello [options]',
+    body: 'A thin wrapper over `ask --template onboarding` with friendly default copy. Run it as your FIRST contact on a fresh channel.',
+    opts: [...CONTENT_OPTS, 'timeout', 'interval', 'realtime', 'no-realtime'],
+  },
+  fyi: {
+    summary: 'send passive info the human can read later — no action (#246 type fyi → profile Mensagem).',
+    usage: 'pidge fyi --title TEXT [--body TEXT | --body-markdown MD] [--image PATH] [--url URL]',
+    body: 'Fire-and-forget: stdout is the raw 201. Use it for logs, registros and neutral summaries — if you need a DECISION use `pidge ask`.',
+    opts: [...CONTENT_OPTS],
+  },
+  report: {
+    summary: 'send a curated result/digest the human will want to read now (#246 type report → Relevante).',
+    usage: 'pidge report --title TEXT [--body-markdown MD] [--image PATH] [--url URL]',
+    body: 'Fire-and-forget, like fyi, but flagged as worth reading now (the feed gives it a highlighted hairline).',
+    opts: [...CONTENT_OPTS],
+  },
+  ask: {
+    summary: 'ask the human a yes/no/choice and block until they answer (#246 type ask → Relevante + ação badge).',
+    usage: 'pidge ask --title TEXT --actions yes,no,reply [--reply-to URL] [options]',
+    body: 'Sends, then holds a WebSocket (or polls) until a TERMINAL answer. REQUIRES a way to answer — --actions (catalog or JSON), --custom-action, or a --template that supplies them. A snooze/reschedule re-fires (ask keeps waiting, prints snooze_until). profile "tracking" is refused (it never produces an answer).',
+    opts: [...CONTENT_OPTS, 'timeout', 'interval', 'realtime', 'no-realtime'],
+  },
+  event: {
+    summary: 'surface a scheduled thing with a known time — countdown Live Activity (#246 type event → Evento).',
+    usage: 'pidge event --title TEXT --event-at ISO8601 [--lead-minutes N] [--body-markdown MD]',
+    body: 'REQUIRES --event-at (ISO8601, e.g. 2026-06-26T14:00-03:00 — no offset ⇒ the user\'s timezone). --lead-minutes (5–240) starts the countdown N min before.',
+    opts: [...CONTENT_OPTS],
+  },
+  alert: {
+    summary: 'flag an anomaly/error needing attention; --escalate forces an AlarmKit alarm (#246 type alert → Urgente).',
+    usage: 'pidge alert --title TEXT [--body TEXT | --body-markdown MD] [--escalate]',
+    body: 'Fire-and-forget. The channel\'s Urgente profile decides the modality; --escalate asks for an AlarmKit alarm that breaks through silent/Focus (the human\'s profile still has the final say).',
+    opts: [...CONTENT_OPTS, 'escalate'],
+  },
+  live: {
+    summary: 'track an in-flight task (deploy/build/trip) with incremental updates (#246 type live → Live Activity).',
+    usage: 'pidge live --title TEXT [--body TEXT] [--lead-minutes N]',
+    body: 'Fire-and-forget. Records the live type; the LA-as-primitive is being built — today the send is delivered as a normal notification.',
+    opts: [...CONTENT_OPTS],
+  },
+  notify: {
+    summary: 'DEPRECATED (0.13.x) — send WITHOUT a type; the server falls back to fyi. Use a typed send instead.',
+    usage: 'pidge notify [options]',
+    body: 'Kept for one minor for compat retro — it warns and still sends (template_kind defaults to fyi server-side; 0.14 will 422). Prefer `pidge fyi/report/ask/event/alert/live`.',
+    opts: [...CONTENT_OPTS],
+  },
+  wait: {
+    summary: 'block on an already-sent notification until it is answered (prints chosen_action JSON).',
+    usage: 'pidge wait <correlation_id> [options]',
+    opts: ['timeout', 'interval', 'realtime', 'no-realtime'],
+  },
+  cancel: {
+    summary: 'cancel a still-scheduled notification before it fires (#56; idempotent; 409 once it reached the phone).',
+    usage: 'pidge cancel <correlation_id>',
+    opts: [],
+  },
+  inbox: {
+    summary: 'what you sent: the list (default), the pending slice, or counts + answer latency (#83).',
+    usage: 'pidge inbox [--pending | --summary] [--all] [--limit N]',
+    opts: ['pending', 'summary', 'all-inbox', 'limit'],
+  },
+  listen: {
+    summary: 'block until the human MESSAGES you from the app, print, ACK after the work, exit (#48).',
+    usage: 'pidge listen [--timeout N] [--all] [--ack-on-read] [--follow]',
+    body: 'One-shot by design (loop it, don\'t daemonize). #170: a read message is DELIVERED (gray ✓✓), NOT done — ack it AFTER the work with `pidge ack --up-to <id>` (a ~10-min lease re-serves un-acked messages, so a crash never loses one).',
+    opts: ['timeout', 'all-listen', 'ack-on-read', 'follow', 'interval', 'realtime', 'no-realtime'],
+  },
+  ack: {
+    summary: 'mark messages PROCESSED (green ✓✓) after you handled them, or --renew the lease on a long task (#170).',
+    usage: 'pidge ack --up-to <id> | --ids a,b [--renew]',
+    opts: ['up-to', 'ids', 'renew'],
+  },
+  contract: {
+    summary: 'DECLARE how you operate (#182) — ADVISORY, never policy (the human SEES if you honor it).',
+    usage: 'pidge contract set <key>=<value> | pidge contract show',
+    body: 'Keys: keep_connection_alive, mirror_in_origin_session, listen_mode=turn_based|persistent|external_daemon, quiet_when_idle. An unknown key / bad value is rejected locally (exit 1).',
+    opts: [],
+  },
+  selftest: {
+    summary: 'prove your listener works by ROUND-TRIP (#205): fire a nonce, run the listener, confirm it acks in time.',
+    usage: 'pidge selftest [--window N]',
+    body: 'PASS exit 0 / FAIL exit 2 (with the likely cause). Run it as the last onboarding step + whenever sends seem to go unheard.',
+    opts: ['window'],
+  },
+  skill: {
+    summary: 'write .claude/skills/pidge/SKILL.md generated from the live manifest (persistent Pidge knowledge for Claude Code).',
+    usage: 'pidge skill install',
+    opts: [],
+  },
+};
+
+// Render the focused help for one command, or the global USAGE when the topic is
+// unknown / absent (so `pidge --help` and `pidge help` keep the full overview).
+function helpFor(topic) {
+  const h = HELP[topic];
+  if (!h) return USAGE;
+  const lines = [`pidge ${topic} — ${h.summary}`, '', 'USAGE', `  ${h.usage}`];
+  if (h.body) { lines.push('', h.body); }
+  if (h.opts && h.opts.length) {
+    lines.push('', 'OPTIONS');
+    for (const key of h.opts) lines.push(`  ${OPTION_DOCS[key] || key}`);
+  }
+  lines.push('', 'Run `pidge --help` for all commands; GET $PIDGE_URL/api/v1/manifest is the full contract (Bearer auth).');
+  return lines.join('\n');
+}
+
 let parsed;
 try {
   parsed = parseArgs({ options: OPTIONS, allowPositionals: true });
@@ -276,9 +469,18 @@ try {
 }
 const v = parsed.values;
 const command = parsed.positionals[0];
-
-// `pidge --help` / `-h` / `help` → full help on stdout, exit 0. No command → stderr, exit 1.
-if (v.help || command === 'help') { console.log(USAGE); process.exit(0); }
+// #241: silence the manifest-version nag entirely (per run via --quiet-nag, or
+// per environment via PIDGE_QUIET_NAG=1) — for scripts and CI where the nudge is noise.
+const QUIET_NAG = !!v['quiet-nag'] || process.env.PIDGE_QUIET_NAG === '1';
+
+// Help on stdout, exit 0. #240: `pidge <cmd> --help` / `pidge help <cmd>` show the
+// FOCUSED help for that command (its synopsis + own flags); `pidge --help` / `help`
+// with no command show the global USAGE. No command at all → USAGE on stderr, exit 1.
+if (v.help || command === 'help') {
+  const topic = command === 'help' ? parsed.positionals[1] : command;
+  console.log(helpFor(topic));
+  process.exit(0);
+}
 if (!command) { console.error(USAGE); process.exit(1); }
 // `setup` is the command that CREATES the token config — it must run without one.
 if (!TOKEN && command !== 'setup')
@@ -300,17 +502,48 @@ function fetchT(url, opts = {}, timeoutMs = 30000) {
 }
 
 // The server advertises its manifest version on every response. When it's newer
-// than what this CLI shipped knowing, nudge ONCE on stderr — the agent re-reads
-// the manifest (whats_new) and learns the new capabilities without polling.
+// than what this CLI shipped knowing, nudge on stderr — the agent re-reads the
+// manifest (whats_new) and learns the new capabilities without polling.
 const KNOWN_MANIFEST_VERSION = 31;
+const NAG_TTL_MS = 24 * 60 * 60 * 1000; // #241: at most one nag per 24 h
 let newsWarned = false;
+
+// #241: a tiny per-install state cache (~/.config/pidge/state.json, per-agent
+// when PIDGE_AGENT is set — same dir as the env file). Best-effort: a read-only
+// fs just means the throttle falls back to once-per-process. Date is fine here
+// (this is the CLI process, not a workflow script).
+function stateFilePath() { return path.join(pidgeConfigDir(), 'state.json'); }
+function readState() {
+  try { return JSON.parse(fs.readFileSync(stateFilePath(), 'utf8')) || {}; } catch { return {}; }
+}
+function writeState(patch) {
+  try {
+    const next = { ...readState(), ...patch };
+    fs.mkdirSync(pidgeConfigDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(stateFilePath(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  } catch { /* best-effort — the nag just won't persist its throttle */ }
+}
+
 function checkManifestNews(res) {
-  const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
-  if (v > KNOWN_MANIFEST_VERSION && !newsWarned) {
-    newsWarned = true;
-    // #119: a pinned npx ref never updates itself — give the CONCRETE command.
-    console.error(`pidge: the server has NEW capabilities (manifest v${v}; this CLI knows v${KNOWN_MANIFEST_VERSION}) — re-read GET $PIDGE_URL/api/v1/manifest (see whats_new) and UPDATE the CLI: npm i -g pidge-cli@latest  (npx users: run npx pidge-cli@latest, a pinned ref never self-updates)`);
+  if (QUIET_NAG || newsWarned) return;
+  const ver = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
+  // (c) only when the server is ahead of what THIS CLI knows.
+  if (!(ver > KNOWN_MANIFEST_VERSION)) return;
+  // #241 throttle: nag at most once per 24 h, and after that window only when the
+  // server version actually CHANGED — so 5 calls in a row (or a steady server)
+  // don't re-spam. A recent OR unchanged record suppresses; the record's seenAt is
+  // stamped only on a real nag (suppressed runs don't roll the 24 h clock forward).
+  const last = readState().manifestVersion;
+  if (last && last.seenAt) {
+    const recent = (Date.now() - Date.parse(last.seenAt)) < NAG_TTL_MS; // (a)
+    const unchanged = last.value === ver;                               // (b)
+    if (recent || unchanged) { newsWarned = true; return; }
   }
+  newsWarned = true;
+  writeState({ manifestVersion: { value: ver, seenAt: new Date().toISOString() } });
+  // #119: a pinned npx ref never updates itself — give the CONCRETE command.
+  // #243: show the AUTHENTICATED curl so re-reading the manifest doesn't 401.
+  console.error(`pidge: the server has NEW capabilities (manifest v${ver}; this CLI knows v${KNOWN_MANIFEST_VERSION}) — re-read the contract:  curl -H "Authorization: Bearer $PIDGE_TOKEN" $PIDGE_URL/api/v1/manifest  (see whats_new), then UPDATE the CLI: npm i -g pidge-cli@latest  (npx users: run npx pidge-cli@latest, a pinned ref never self-updates). Silence this with --quiet-nag or PIDGE_QUIET_NAG=1.`);
 }
 
 // ---------------------------------------------------------------------------
@@ -487,8 +720,52 @@ function probeRealtime(base, token) {
   });
 }
 
-// Map CLI flags → the /notify JSON body, including only what was provided.
-function buildBody() {
+// #242: a custom action id is lowercase letters, digits and underscore (≤40) —
+// the same rule the server enforces, validated LOCALLY so a typo fails fast.
+const CUSTOM_ACTION_ID = /^[a-z0-9_]{1,40}$/;
+
+// --custom-action "id:label[:destructive][:confirm][:biometric][:terminal]"
+function customActionFromSpec(spec) {
+  const [id, label, ...flags] = spec.split(':');
+  // #157 P2: fail fast locally — the rule is stable and the server 422 costs a
+  // round-trip an agent then has to interpret.
+  if (!CUSTOM_ACTION_ID.test(id || '')) {
+    die(`pidge: --custom-action id ${JSON.stringify(id)} is invalid — lowercase letters, digits and underscore only (^[a-z0-9_]{1,40}$)`, 1);
+  }
+  const ca = { id, label };
+  if (flags.includes('destructive')) ca.style = 'destructive';
+  if (flags.includes('confirm')) ca.confirm = true;
+  if (flags.includes('biometric')) ca.biometric = true;
+  if (flags.includes('terminal')) ca.terminal = true;
+  return ca;
+}
+
+// #242: one item of a JSON --actions array → a custom_actions spec. Validates
+// {id,label} and passes the optional gating fields the server understands.
+function customActionFromJson(item, i) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    die(`pidge: --actions[${i}] must be an object with "id" and "label" (e.g. {"id":"approve","label":"Aprovar agora"})`, 1);
+  }
+  if (typeof item.id !== 'string' || !CUSTOM_ACTION_ID.test(item.id)) {
+    die(`pidge: --actions[${i}].id ${JSON.stringify(item.id)} is invalid — lowercase letters, digits and underscore only (^[a-z0-9_]{1,40}$)`, 1);
+  }
+  if (typeof item.label !== 'string' || !item.label.trim()) {
+    die(`pidge: --actions[${i}].label is required — a non-empty string`, 1);
+  }
+  const ca = { id: item.id, label: item.label };
+  if (item.sf_symbol !== undefined) ca.sf_symbol = item.sf_symbol;
+  if (item.style !== undefined) ca.style = item.style;
+  if (item.destructive) ca.style = 'destructive';
+  if (item.confirm !== undefined) ca.confirm = !!item.confirm;
+  if (item.biometric !== undefined) ca.biometric = !!item.biometric;
+  if (item.terminal !== undefined) ca.terminal = !!item.terminal;
+  return ca;
+}
+
+// Map CLI flags → the /notify JSON body, including only what was provided. `extra`
+// carries subcommand-supplied raw fields (#246: the typed sends' template_kind and
+// alert's escalate) — merged below, before the --param escape hatch.
+function buildBody(extra = {}) {
   if (!v.title) die('pidge: --title is required', 1);
   const body = { title: v.title };
   if (v.body !== undefined) body.body = v.body;
@@ -507,25 +784,31 @@ function buildBody() {
   if (v.thread !== undefined) body.thread_id = v.thread;
   if (v.after !== undefined) body.after = v.after;
   if (v['collapse-key'] !== undefined) body.collapse_key = v['collapse-key'];
-  if (v.actions !== undefined) body.actions = v.actions.split(',').filter(Boolean);
-
-  const customs = v['custom-action'] || [];
-  if (customs.length) {
-    body.custom_actions = customs.map((spec) => {
-      const [id, label, ...flags] = spec.split(':');
-      // #157 P2: fail fast locally — the rule is stable and the server 422
-      // costs a round-trip an agent then has to interpret.
-      if (!/^[a-z0-9_]{1,40}$/.test(id || '')) {
-        die(`pidge: --custom-action id ${JSON.stringify(id)} is invalid — lowercase letters, digits and underscore only (^[a-z0-9_]{1,40}$)`, 1);
-      }
-      const ca = { id, label };
-      if (flags.includes('destructive')) ca.style = 'destructive';
-      if (flags.includes('confirm')) ca.confirm = true;
-      if (flags.includes('biometric')) ca.biometric = true;
-      if (flags.includes('terminal')) ca.terminal = true;
-      return ca;
-    });
+
+  // --actions: the short comma form (built-in catalog ids → body.actions) OR a
+  // JSON array of custom {id,label,…} specs (#242 → body.custom_actions). A
+  // leading '[' selects JSON; bad JSON is a friendly LOCAL error (exit 1), never
+  // a silent fall-through that drops the labels and sends a plain notification.
+  // --custom-action specs APPEND to whatever the JSON form produced, so both can coexist.
+  const customActions = [];
+  if (v.actions !== undefined) {
+    const trimmed = v.actions.trim();
+    if (trimmed.startsWith('[')) {
+      let arr;
+      try { arr = JSON.parse(trimmed); }
+      catch (e) { die(`pidge: --actions looks like JSON but didn't parse (${e.message}). Use a JSON array of {"id","label"} objects, or the short form yes,no,reply`, 1); }
+      if (!Array.isArray(arr)) die('pidge: --actions JSON must be an ARRAY of {"id","label"} objects', 1);
+      arr.forEach((item, i) => customActions.push(customActionFromJson(item, i)));
+    } else {
+      body.actions = trimmed.split(',').filter(Boolean);
+    }
   }
+  for (const spec of v['custom-action'] || []) customActions.push(customActionFromSpec(spec));
+  if (customActions.length) body.custom_actions = customActions;
+
+  // #246: subcommand-supplied raw fields (template_kind, alert's escalate). Applied
+  // before the --param loop so a raw --param can still override in a pinch.
+  Object.assign(body, extra);
 
   // Escape hatch: any raw /notify field, so a NEW server field documented in the
   // manifest works the day it ships — no CLI release needed. JSON values parse
@@ -597,8 +880,8 @@ async function resolveMedia(body) {
 // POST /notify. Returns { ok, info, raw }. Emits to STDERR what an agent most
 // needs to KNOW (0 devices / no banner buttons / an armed alarm / a policy
 // degrade), so stdout stays free for machine output.
-async function doNotify() {
-  const payload = buildBody();
+async function doNotify(extra = {}) {
+  const payload = buildBody(extra);
   await resolveMedia(payload);
   let res, raw;
   try {
@@ -637,6 +920,25 @@ async function doNotify() {
   return { ok, info, raw };
 }
 
+// #246: the typed send subcommands (fyi/report/event/alert/live) share notify's
+// fire-and-forget shape — stamp template_kind, POST, print the raw 201, exit
+// (0 ok / 2 failed). `ask` is the one type that send+waits (it needs a decision)
+// and so keeps its own case. `extra` carries alert's escalate:true.
+async function doTypedNotify(kind, extra = {}) {
+  const { ok, info, raw } = await doNotify({ template_kind: kind, ...extra });
+  console.log(raw);
+  if (ok && info.correlation_id)
+    console.error(`pidge: correlation_id=${info.correlation_id} (use: pidge wait ${info.correlation_id})`);
+  process.exit(ok ? 0 : 2);
+}
+
+// #246: `pidge notify` / `pidge send` (no type) are deprecated for ONE minor
+// (0.13.x) — they still send, and the server falls back to template_kind "fyi"
+// (soft-rollout). 0.14 will 422 a typeless send. The warning is local (stderr).
+function warnDeprecatedSend(name) {
+  console.error(`pidge: \`pidge ${name}\` is deprecated — use a TYPE instead: fyi · report · ask · event · alert · live (see \`pidge help\`). Server-side fallback to \`fyi\` continues in 0.13.x; will be removed in 0.14.`);
+}
+
 // Poll GET /notifications/:cid until a TERMINAL answer, print chosen_action JSON to
 // stdout, exit 0. A snooze (snooze / reschedule-to-a-time) is non-terminal — it
 // re-fires — so keep waiting through it. Exits 3 on timeout.
@@ -1262,6 +1564,24 @@ Generated from manifest v${m.manifest_version} of ${BASE} — re-run \`pidge ski
 
 All commands: \`npx pidge-cli …\` (Node ≥18; reads ~/.config/pidge/env — no token in context). Not set up? \`pidge doctor\` tells you; onboard with \`pidge setup --claim <code>\` (the human copies the code from the Pidge app).
 
+## Choose the right type (REQUIRED in 0.14+)
+
+Every send needs a type. Pick by intent:
+
+| You want to... | Use | Example |
+|---|---|---|
+| Log something the human can read later, no action | \`pidge fyi\` | "Build completed in 2m12s" |
+| Deliver a curated result/digest worth reading now | \`pidge report\` | "Daily standup summary" |
+| Ask the human a yes/no/choice — block until they answer | \`pidge ask\` | "Approve deploy v3.2?" with \`--actions yes,no\` |
+| Surface a scheduled thing (with time) | \`pidge event\` | "Sprint review 14h" with \`--event-at ...\` |
+| Anomaly/error needing attention; add \`--escalate\` for AlarmKit | \`pidge alert\` | "API 503 errors spiked" |
+| Track an in-flight task with incremental updates | \`pidge live\` | "Deploy v3.2 — building..." |
+
+If unsure: \`fyi\` for passive info, \`ask\` if you need a decision. NEVER use \`pidge send\`
+without a type — in 0.14 it'll 422. (In 0.13.x it warns locally + server falls back to fyi.)
+
+Available CLI commands (typed sends): \`pidge fyi\` · \`pidge report\` · \`pidge ask\` · \`pidge event\` · \`pidge alert\` · \`pidge live\` (and \`pidge notify\`, deprecated). Run \`pidge <type> --help\` for each one's own flags.
+
 ## Pick the right send (decision table)
 
 ${table.map((r) => `- ${r}`).join('\n')}
@@ -1280,6 +1600,25 @@ ${notes.map((n) => `- ${n}`).join('\n')}
 - \`pidge listen\` blocks until the human MESSAGES you from the app (composer) — run it when idle.
 - ${exits}
 
+## Stay "always-on" while you're turn-based (#244)
+
+A turn-based agent (Claude Code, ChatGPT, anything that only runs when invoked) can still be COMMANDABLE by your human. Two ways, neither needs a daemon:
+
+### Path 1 — an interactive listening window (active session)
+\`\`\`bash
+pidge listen --follow --timeout 300   # hold for 5 min (--timeout is SECONDS), printing messages as they arrive
+\`\`\`
+Good while you're actively working. You stay online until the window closes. \`--follow\` is supervisor-style — it traps the turn — so only use it when you intend to sit and wait.
+
+### Path 2 — a supervisor that polls, no daemon (24/7)
+A \`cron\` job or \`systemd\` timer invokes you every N minutes; each tick runs ONE one-shot listen and exits:
+\`\`\`bash
+pidge listen --timeout 50   # block up to 50s for a message, print it, exit 0 (exit 3 = nothing this tick)
+\`\`\`
+Each poll is one of your turns: pick up the message, do the work, \`pidge ack --up-to <id>\`, then sleep until the next tick. Real always-on without being a daemon. With Claude Code, the built-in \`/loop\` (auto-wake every N min) drives the same loop.
+
+> \`--timeout\` is always SECONDS (not "5m"). One-shot \`pidge listen\` is the polling primitive — loop it from your supervisor; do NOT background it with \`&\` (an orphaned listener eats the queue).
+
 ## Full spec
 
 \`curl $PIDGE_URL/api/v1/manifest -H "Authorization: Bearer $PIDGE_TOKEN"\` — the always-current contract (fields, templates, custom actions, media, threads, realtime).
@@ -1321,7 +1660,34 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       await runSkillInstall();
       break;
     }
-    case 'notify': {
+    // #246: typed sends — fyi/report/event/alert/live stamp template_kind and
+    // fire-and-forget. ask is separate (it send+waits). notify/send are the
+    // deprecated typeless path (server falls back to fyi during the soft-rollout).
+    case 'fyi':
+    case 'report':
+      await doTypedNotify(command);
+      break;
+    case 'event': {
+      // event needs a TIME — validate locally (ISO8601) so the agent fails fast
+      // instead of taking the server's event_at_required 422 round-trip.
+      if (v['event-at'] === undefined)
+        die('pidge: --event-at required for event. Use ISO8601: --event-at 2026-06-26T14:00-03:00', 1);
+      if (Number.isNaN(Date.parse(v['event-at'])))
+        die(`pidge: --event-at ${JSON.stringify(v['event-at'])} is not a valid ISO8601 datetime. Use e.g. --event-at 2026-06-26T14:00-03:00`, 1);
+      await doTypedNotify('event');
+      break;
+    }
+    case 'alert':
+      // --escalate ⇒ escalate:true (ask the channel's Urgente profile for an
+      // AlarmKit alarm that breaks through silent/Focus; the human's profile decides).
+      await doTypedNotify('alert', v.escalate ? { escalate: true } : {});
+      break;
+    case 'live':
+      await doTypedNotify('live');
+      break;
+    case 'notify':
+    case 'send': {
+      warnDeprecatedSend(command);
       const { ok, info, raw } = await doNotify();
       console.log(raw);
       if (ok && info.correlation_id)
@@ -1361,13 +1727,18 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       if (v.profile === 'tracking')
         die('pidge: `ask --profile tracking` makes no sense — tracking never produces an answer (use the live_activities API; need a decision? send a real profile)', 1);
       if (!v.title) die('pidge: --title is required', 1);
+      // #246: an ask DECLARES a decision — it must say HOW the human answers.
+      // --actions (catalog or JSON), --custom-action, or a --template that supplies
+      // them all satisfy it; none ⇒ a local error (the spec's "no hidden default").
+      if (v.actions === undefined && !(v['custom-action'] || []).length && v.template === undefined)
+        die('pidge: --actions required for ask. Use --actions yes,no,reply or a JSON array.', 1);
       // The cid is minted CLIENT-side when not given, and printed as the FIRST
       // stderr line (greppable) — a killed/crashed ask always leaves the handle
       // behind, so the agent can `pidge wait <cid>` instead of re-sending.
       const cid = v['correlation-id'] || crypto.randomUUID();
       v['correlation-id'] = cid;
       console.error(`pidge: correlation_id=${cid}`);
-      const { ok, info } = await doNotify();
+      const { ok, info } = await doNotify({ template_kind: 'ask' });
       if (!ok) process.exit(2);
       console.error(`pidge: sent (${info.registered_devices} device(s)) — waiting on ${cid}`);
       // #132: no --timeout ⇒ obey the template's suggestion from the 201 echo
@@ -1669,6 +2040,8 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       break;
     }
     default:
-      die(USAGE, 1);
+      // #246: name the bad command and point at the type catalog (a friendlier
+      // landing than dumping the whole USAGE on a typo).
+      die(`pidge: unknown subcommand '${command}'. Try: fyi · report · ask · event · alert · live · notify (deprecated). pidge --help`, 1);
   }
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pidge-cli",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",
@@ -18,6 +18,7 @@
   "files": [
     "bin",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {