pidge-cli 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.15.0 — #274 CLI redesign (F1)
+
+-m/--body-markdown-file input chain, --gated, English hello, --template off the help menu (still accepted), nag knows v46, --wait defaults to 60 min for decisions.
+
+F3/F4: skill rewritten (two approval paths, English gold examples, no content_template menu, appendix from v46); setup → skill → hello fuse with graceful-degrade.
+
+## 0.14.0 — 2026-06-28
+
+The married vocabulary (perfis) — the CLI now speaks the SAME language as the server
+(manifest v42) and the app: ONE list of 5 message types, with RESPONSE as a separate
+axis. No scripts break — the old names keep working as aliases.
+
+- **feat:** the typed sends are renamed to the canonical 5 — `pidge message` ·
+  `important` · `urgent` · `event` · `live` (message←fyi, important←report, urgent←alert;
+  event/live unchanged). `important` is the recommended default. The wire sends the new
+  `template_kind`. (perfis-S1)
+- **feat (compat):** the OLD names still work as aliases — `pidge fyi`→message,
+  `report`→important, `alert`→urgent — mapped to the new type, with a one-line rename
+  note on stderr. Muscle-memory and existing scripts are untouched. (perfis-S1)
+- **feat:** RESPONSE is now its own axis, composing on ANY type — `--actions`/
+  `--custom-action` (buttons) + the new **`--wait`** (block until the human answers,
+  then print `chosen_action` JSON; without it = fire-and-forget). This is the explicit
+  "send-and-go vs wait". (perfis-S2)
+- **feat:** `pidge ask` is now the shortcut for `important --wait` (still REQUIRES a way
+  to answer; preserved behavior). There is no `ask` TYPE in the married catalog — asking
+  is a type + buttons + wait. (perfis-S2)
+- **feat:** `pidge approval` — a new go/no-go RECIPE = `important` + Approve/Reject +
+  Face ID on Approve + `--wait`. Sent as `custom_actions` (only custom actions carry
+  `biometric`, and a custom id can't reuse a built-in like approve/reject — so the ids
+  are `grant`/`deny`). Pass your own `--actions`/`--custom-action` to override the
+  pair. (perfis-S2)
+- **docs:** USAGE, per-command help and the generated `SKILL.md` rewritten around the two
+  axes (type + response) — mirrors the human's app, drops the dead fyi/report framing.
+- **chore:** `KNOWN_MANIFEST_VERSION` 36 → 42 (the live server), silencing the news nag.
+
 ## 0.13.1 — 2026-06-26
 
 Polish from an agent E2E (2026-06-26). No breaking changes.

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.14.0** — the **married vocabulary** (perfis): the CLI now speaks the same
+> language as the server (manifest v42) and the app. **One list of 5 types** —
+> `pidge message · important · urgent · event · live` (message←fyi, important←report,
+> urgent←alert; old names still work as aliases). **RESPONSE is a separate axis**:
+> `--actions`/`--custom-action` add buttons on ANY type, and **`--wait`** blocks until
+> the human answers — the explicit *send-and-go vs wait*. `pidge ask` is now the shortcut
+> for `important --wait`; new **`pidge approval`** = important + Approve/Reject + Face
+> ID + wait. `important` is the recommended default.
+>
 > **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
@@ -113,39 +122,73 @@ export PIDGE_TOKEN=hld_xxx                          # your channel's bearer key
 # (or skip the exports: the CLI reads ~/.config/pidge/env — KEY=VALUE — so the
 #  key never has to appear in an agent's chat; explicit env vars win)
 
-# Send AND wait for the answer (the one an agent wants):
-npx pidge-cli ask \
-  --title "Aprovar deploy?" --actions yes,no,reply --timeout 600
+# Just inform — fire-and-forget (clears when the human opens it):
+npx pidge-cli message --title "Build green" --body "2m12s"
+
+# A pendency they should resolve — the DEFAULT type ("waiting-for-you" card):
+npx pidge-cli important --title "Review PR #42" --url https://github.com/…/pull/42
 
-# Urgent — escalates to an AlarmKit alarm if the human doesn't answer in minutes:
+# Send AND wait for the answer (the one an agent wants) — = important + --wait:
 npx pidge-cli ask \
-  --title "Posso rodar a migration?" --profile escalating --actions yes,no
+  --title "Approve deploy?" --actions yes,no,reply --timeout 600
+
+# A go/no-go with Face ID — the approval RECIPE (= important + Approve/Reject + wait):
+npx pidge-cli approval --title "Deploy to production?"
+
+# Urgent — breaks through silent/Focus; --escalate forces an AlarmKit alarm:
+npx pidge-cli urgent --title "Balance dropped below $5k" --escalate
 
 # A thing with a known time — push at T−lead + a lock-screen countdown to the event:
-npx pidge-cli notify \
-  --title "Reunião com o time" --profile event --event-at "2026-06-10T15:00:00"
+npx pidge-cli event \
+  --title "Team meeting" --event-at "2026-06-10T15:00:00"
 
 # A chart you generated — uploaded for you, shown on the banner + feed:
-npx pidge-cli notify --title "Gráfico pronto" --image ./chart.png
+npx pidge-cli message --title "Chart ready" --image ./chart.png
 
 # A real artifact — the human previews it on the phone, shares it, saves to Files:
-npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
+npx pidge-cli important --title "Report" --file ./report.xlsx
 ```
 
-`ask` prints the chosen action as JSON to **stdout** and exits `0`:
+`ask`/`approval` (and any `--wait` send) print the chosen action as JSON to
+**stdout** and exit `0`:
 
 ```json
 { "kind": "acted", "action_id": "yes", "label": "Sim", "text": null,
   "at": "2026-06-08T18:19:51Z", "snooze_until": null }
 ```
 
+## Two axes: the TYPE + the RESPONSE
+
+You pick **one type** (how much it may intrude — the human already configured how each
+arrives), then ORTHOGONALLY decide the **response** (buttons? wait or not?).
+
+**Axis 1 — type** (the married catalog of 5):
+
+| Type | For | Clears when |
+|---|---|---|
+| `pidge message` | just inform, no action | the human OPENS it |
+| `pidge important` ⭐ | a pendency they should resolve (the DEFAULT) | **Feito** |
+| `pidge urgent` | wake them now (rare, real); `--escalate` = AlarmKit alarm | Feito (cuts the alarm) |
+| `pidge event --event-at <ISO>` | a thing with a known time (countdown LA) | passed / Feito |
+| `pidge live` | track something live (Live Activity) | you end it |
+
+**Axis 2 — response** (composes on ANY type): `--actions yes,no` / `--custom-action`
+add buttons (free text is always available); `--wait` blocks until the human answers
+(else fire-and-forget — the answer arrives later in `pidge listen --all`). Two shortcuts
+bundle both: **`pidge ask`** = `important --wait` (needs `--actions`); **`pidge approval`**
+= `important` + Approve/Reject + Face ID + `--wait`.
+
+> Old names still work as **aliases**: `fyi`→message, `report`→important, `alert`→urgent.
+
 ## Commands
 
 | Command | What it does |
 |---|---|
+| `message` / `important` / `urgent` / `event` / `live` | The 5 message types (axis 1). Fire-and-forget by default; add `--actions`/`--wait` (axis 2) to ask for a reply. `important` is the recommended default. |
+| `ask` | `important --wait` shortcut: send **and block** until the human answers; prints the chosen action JSON. Requires a way to answer (`--actions`/`--custom-action`/`--template`). |
+| `approval` | Go/no-go RECIPE: `important` + Approve (Face ID) / Reject + `--wait`. Pass your own `--actions` to override the pair. |
 | `hello` | **v0.11.0 (#217):** your channel's **first-contact WOW** — send the onboarding handshake **and block** until the human confirms. The server narrates a 3-stage Live Activity on the lock screen (Conectando → toque para confirmar → Concluído ✓) so they *see* the agent→human→agent loop close. Run it as your **first** contact on a fresh channel. A thin `ask --template onboarding` wrapper with friendly default copy. |
-| `ask` | Send a notification **and block** until the human answers; prints the chosen action JSON. The default for agents. |
-| `notify` | Send only. Prints the raw 201 JSON; the `correlation_id` + warnings go to stderr. |
+| `notify` | **Deprecated** — send without a type (the server picks the channel default). Prefer a typed send. Prints the raw 201 JSON; the `correlation_id` + warnings go to stderr. |
 | `wait <correlation_id>` | Block on an already-sent notification until it's answered. |
 | `cancel <correlation_id>` | Cancel a **still-scheduled** notification before it fires (idempotent; 409 once it reached the phone). |
 | `inbox` | What you sent: list, `--pending` slice, or `--summary` (counts + answer latency). |
@@ -188,11 +231,11 @@ WebSocket  →  ?wait= long-poll (capped 25 s server-side)  →  plain GETs ever
 --body TEXT             the message shown on the banner
 --body-markdown MD      rich body for the tap-through detail screen
 --subtitle TEXT
---profile ID            delivery profile — the HUMAN owns what each one does:
-                        default · event (needs --event-at; countdown Live Activity) ·
-                        escalating (alarm if unanswered minutes after delivery) ·
-                        the user's custom profiles. See the manifest's `profiles`.
---event-at ISO8601      WHEN the thing happens (a FACT; required by profile event)
+--profile ID            low-level alias of the TYPE — the HUMAN owns what each does:
+                        message · important · urgent · event (needs --event-at) ·
+                        live · the user's custom profiles. Prefer the typed
+                        subcommands above; an explicit --profile still wins.
+--event-at ISO8601      WHEN the thing happens (a FACT; required by event)
 --lead-minutes N        notify/start the countdown N min before event_at (5–240)
 --urgency LEVEL         normal | persistent | alarm (low-level — prefer --profile)
 --image PATH_OR_URL     image on the banner + feed: a local path is uploaded for you
@@ -207,13 +250,16 @@ WebSocket  →  ?wait= long-poll (capped 25 s server-side)  →  plain GETs ever
                         '[{"id":"approve","label":"Aprovar agora"},{"id":"defer","label":"Depois"}]'
 --custom-action SPEC    "id:label[:destructive][:confirm][:biometric][:terminal]"
                         (repeatable — your own buttons; composes with --actions JSON)
+--wait                  RESPONSE axis: block until the human answers (ANY type), then
+                        print chosen_action JSON. Without it: fire-and-forget (the
+                        answer arrives later in `pidge listen --all`). ask/approval imply it.
 --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)
 --collapse-key KEY      replace/update a prior notification
 --param KEY=VALUE       pass ANY raw /notify field (repeatable) — future server
                         fields work day-one, no CLI update needed
---timeout SECONDS       ask: default 600 · wait: default 300
+--timeout SECONDS       how long --wait blocks (ask/approval: template suggestion ~3600 · wait: 300)
 --interval SECONDS      FALLBACK poll cadence (default 30) — normally unused: WS or
                         the server-held long-poll (?wait=25) make answers ~instant
 --realtime              force the WebSocket (Node ≥22); --no-realtime = polling only
@@ -224,9 +270,10 @@ WebSocket  →  ?wait= long-poll (capped 25 s server-side)  →  plain GETs ever
 - **`ask` prints `correlation_id=<cid>` as its FIRST stderr line** (minted client-side
   when you don't pass one) — a killed `ask` always leaves the handle behind, so you
   can `pidge wait <cid>` instead of re-sending.
-- **stdout is always machine-readable.** `notify` → the raw 201 JSON; `ask`/`wait` →
-  the `chosen_action` JSON. Everything human (warnings, the correlation_id, snooze
-  notices, armed-escalation and policy-degrade narration) goes to **stderr**.
+- **stdout is always machine-readable.** A fire-and-forget send → the raw 201 JSON; a
+  `--wait` send / `ask` / `approval` / `wait` → the `chosen_action` JSON. Everything
+  human (warnings, the correlation_id, snooze notices, armed-escalation and
+  policy-degrade narration) goes to **stderr**.
 - **Exit codes:** `0` answered · `3` timed out (= *no answer yet*, NOT a failure —
   back off and retry later) · `4` timed out **without one healthy round-trip all
   session** (the CHANNEL looks broken — server/network — tell your human) ·
@@ -234,11 +281,11 @@ WebSocket  →  ?wait= long-poll (capped 25 s server-side)  →  plain GETs ever
 - **Responses are one-and-done.** Every answer closes the notification EXCEPT a
   **snooze** (or a reschedule that set a new time), which re-fires later. `ask`/`wait`
   keep polling through a snooze and print `snooze_until` so you can schedule a re-check.
-- **Profiles degrade, never reject.** An over-ceiling profile is delivered at the
-  channel's allowed level — read `degraded`/`degrade_reason` in the 201 (narrated on
-  stderr). That's the human's policy working; don't retry harder.
-- **`ask --profile tracking` is refused** — tracking is Live-Activity-only and never
-  produces an answer.
+- **Types degrade, never reject.** An over-ceiling type is delivered at the channel's
+  allowed level — read `degraded`/`degrade_reason` in the 201 (narrated on stderr).
+  That's the human's policy working; don't retry harder.
+- **`--wait` / `ask` on `live` is refused** — `live` is status-only and never produces
+  an answer.
 - A genuine follow-up question is a **new** notification, never a second answer on
   the same one.
 

package/bin/pidge.js

@@ -11,14 +11,25 @@
 //    ~/.config/pidge/env — KEY=VALUE — is read instead, so the key can live
 //    OUTSIDE the agent's chat/context entirely, #57)
 //
-//   # send AND block until the human answers, then print the chosen action as JSON
-//   pidge ask --title "Aprovar deploy?" --actions yes,no,reply --timeout 600
+//   TWO AXES (perfis, manifest v40+): (1) the TYPE — one married list of 5 the
+//   human configured how to receive: message · important · urgent · event · live;
+//   (2) the RESPONSE — buttons (--actions/--custom-action) + send-and-go vs wait
+//   (--wait blocks until the human answers). Response composes onto ANY type.
 //
-//   # urgent: escalates to an AlarmKit alarm if unanswered (see the manifest's profiles)
-//   pidge ask --title "Posso rodar a migration?" --profile escalating --actions yes,no
+//   # just inform — fire-and-forget (prints the raw 201)
+//   pidge message --title "Build green" --body "2m12s"
 //
-//   # a thing with a known time: push at T−lead + a lock-screen countdown to the event
-//   pidge notify --title "Reunião com o time" --profile event --event-at "2026-06-10T15:00:00"
+//   # a pendency the human should resolve (the DEFAULT type) + block on the answer
+//   pidge important --title "Approve deploy?" --actions yes,no,reply --wait
+//
+//   # a go/no-go decision with Face ID — the approval RECIPE (= important + wait + gate)
+//   pidge approval --title "Deploy to production?"
+//
+//   # urgent: breaks through silent/Focus, escalates to an AlarmKit alarm
+//   pidge urgent --title "Balance dropped below $5k" --escalate
+//
+//   # a thing with a known time: push at T−lead + a lock-screen countdown
+//   pidge event --title "Team meeting" --event-at "2026-06-10T15:00:00"
 //
 //   # block on an already-sent notification (by correlation_id)
 //   pidge wait order-7 --timeout 300
@@ -96,7 +107,8 @@ const OPTIONS = {
   help: { type: 'boolean', short: 'h' },
   title: { type: 'string' },
   body: { type: 'string' },
-  'body-markdown': { type: 'string' },
+  'body-markdown': { type: 'string', short: 'm' },
+  'body-markdown-file': { type: 'string' },   // a path, or "-" to read stdin (#274)
   subtitle: { type: 'string' },
   template: { type: 'string' },                // content/action pattern (manifest `templates`)
   profile: { type: 'string' },                 // delivery profile id (manifest `profiles`)
@@ -104,6 +116,7 @@ const OPTIONS = {
   '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)
+  gated: { type: 'boolean' },                  // #274: one Face-ID confirm action (replaces content_template:sensitive)
   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)
@@ -119,6 +132,9 @@ const OPTIONS = {
   param: { type: 'string', multiple: true },   // key=value escape hatch → raw /notify field
   timeout: { type: 'string' },
   interval: { type: 'string' },
+  // perfis-S2 response axis: --wait blocks until the human answers (composes on
+  // ANY type — send-and-go vs wait). ask/approval imply it.
+  wait: { type: 'boolean' },
   // inbox flags (#83)
   pending: { type: 'boolean' },
   summary: { type: 'boolean' },
@@ -163,14 +179,20 @@ 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.
-  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)
+  AXIS 1 — TYPE (the married list of 5; the human configured how each arrives):
+  pidge message   [options]               just inform, no action — clears when the human OPENS it
+  pidge important [options]  ⭐DEFAULT     a pendency the human should resolve ("waiting-for-you" card)
+  pidge urgent    [options]               breaks through silent/Focus; --escalate forces an AlarmKit alarm
+  pidge event     [options]               a scheduled thing — needs --event-at (countdown Live Activity)
+  pidge live      [options]               an in-flight task with incremental updates (Live Activity)
+  AXIS 2 — RESPONSE (composes on ANY type above): --actions/--custom-action add
+  buttons; text reply is ALWAYS available; --wait blocks until the human answers
+  (send-and-go vs --wait). Two shortcuts bundle both axes:
+  pidge ask      [options]                = important + --wait; needs --actions (prints chosen_action JSON)
+  pidge approval [options]                = important + Approve/Reject + Face ID + --wait (a go/no-go)
+  COMPAT aliases (old names still work → mapped to the new type):
+  pidge fyi→message · report→important · alert→urgent  (event/live unchanged)
+  pidge notify [options]                  DEPRECATED — send without a type; prefer a TYPE above
   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)
@@ -217,13 +239,12 @@ OPTIONS (notify / ask)
   --body TEXT              message shown on the banner
   --body-markdown MD       rich body for the tap-through detail screen
   --subtitle TEXT
-  --template ID            content/action pattern — WHAT you're asking: context (FYI,
-                           no buttons) · decision (yes/no/reply) · approval · reminder ·
-                           nudge · sensitive (gated, Face ID). Composes with --profile.
-  --profile ID             delivery profile (the HUMAN owns what it does): default ·
-                           event (needs --event-at; countdown Live Activity) ·
-                           escalating (alarm if unanswered minutes after delivery) ·
-                           the user's custom profiles. See the manifest's \`profiles\`.
+  --gated                  add a Face-ID confirm on the consequential action (money/deletion)
+  --body-markdown-file F   read the markdown body from a file (or "-" for stdin)
+  --profile ID             low-level alias of the TYPE axis (the HUMAN owns what it
+                           does): message · important · urgent · event · live ·
+                           the user's custom profiles. Prefer the typed subcommands
+                           above; an explicit --profile still wins. See the manifest.
   --event-at ISO8601       WHEN the thing happens (a FACT; required by profile event)
   --lead-minutes N         notify/start countdown N min before event_at (5–240)
   --urgency LEVEL          normal | persistent | alarm (low-level — prefer --profile)
@@ -233,9 +254,13 @@ OPTIONS (notify / ask)
                            shares 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           RESPONSE axis — comma list: yes,no,approve,reject,accept,
+                           decline,later,done,snooze,reschedule,reply,mute (or a JSON
+                           array of custom {id,label} objects). Composes on ANY type.
   --custom-action SPEC     "id:label[:destructive][:confirm][:biometric][:terminal]" (repeatable)
+  --wait                   RESPONSE axis — block until the human answers (any type),
+                           then print chosen_action JSON. Without it: fire-and-forget
+                           (the answer arrives later in \`pidge listen --all\`). ask/approval imply it.
   --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)
@@ -247,7 +272,8 @@ OPTIONS (notify / ask)
   --collapse-key KEY       replace/update a prior notification
   --param KEY=VALUE        pass ANY raw /notify field (repeatable) — future server
                            fields work without a CLI update; the manifest is the contract
-  --timeout SECONDS        ask: 600 · wait: 300
+  --timeout SECONDS        how long --wait blocks (ask/approval: template's suggestion,
+                           ~3600 for a decision · wait: 300) — explicit always wins
   --interval SECONDS       FALLBACK poll cadence (default 30) — normally unused: WS or
                            the server-held long-poll (?wait=25) make answers ~instant
 
@@ -262,17 +288,18 @@ ENV
                 shared ~/.config/pidge/env (single-agent only).
 
 OUTPUT
-  stdout is machine-readable (notify→201 JSON; ask/wait→chosen_action JSON);
-  human notices go to stderr. Exit: 0 answered · 3 timed out (no answer yet,
-  not a failure) · 4 timed out WITHOUT ONE healthy round-trip all session (the
-  CHANNEL looks broken — server/network — not the human ignoring you: surface
-  it instead of retrying blindly, #119) · 2 error · 1 usage.
-
-Responses are one-and-done EXCEPT snooze/reschedule (they re-fire); ask/wait keep
-polling through a snooze and print snooze_until. Follow-up = a NEW notification.
-An over-ceiling profile is delivered DEGRADED, never rejected — read the 201's
-degraded/degrade_reason (narrated on stderr). profile "tracking" is Live-Activity-
-only: it never produces an answer, so \`ask\` refuses it.
+  stdout is machine-readable (a fire-and-forget send→the raw 201 JSON; a --wait
+  send / ask / approval / wait→chosen_action JSON); human notices go to stderr.
+  Exit: 0 answered · 3 timed out (no answer yet, not a failure) · 4 timed out
+  WITHOUT ONE healthy round-trip all session (the CHANNEL looks broken —
+  server/network — not the human ignoring you: surface it instead of retrying
+  blindly, #119) · 2 error · 1 usage.
+
+Responses are one-and-done EXCEPT snooze/reschedule (they re-fire); a --wait send
+keeps polling through a snooze and prints snooze_until. Follow-up = a NEW
+notification. An over-ceiling type is delivered DEGRADED, never rejected — read
+the 201's degraded/degrade_reason (narrated on stderr). \`live\` is status-only:
+it never produces an answer, so --wait/ask refuse it.
 
 Full spec (the contract — always current): GET $PIDGE_URL/api/v1/manifest`;
 
@@ -288,19 +315,21 @@ 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',
+  'body-markdown-file': '--body-markdown-file F   read the markdown body from a file (or "-" for stdin) — avoids shell-quoting long markdown',
   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)',
+  gated: '--gated                  add a Face-ID confirm on the consequential action (money/deletion). Pair with a louder profile if it must also be loud.',
+  profile: '--profile ID             low-level alias of the TYPE (the human owns it): message · important · urgent · event · live · custom',
+  'event-at': '--event-at ISO8601       WHEN the thing happens (required by 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',
+  urgency: '--urgency LEVEL          normal | persistent | alarm (low-level — prefer the typed subcommand)',
+  escalate: '--escalate               urgent: 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',
+  actions: '--actions LIST|JSON      RESPONSE axis: comma list from the catalog (yes,no,reply) OR a JSON array of {"id","label"} custom actions — composes on ANY type',
   'custom-action': '--custom-action SPEC     "id:label[:destructive][:confirm][:biometric][:terminal]" (repeatable)',
+  wait: '--wait                  RESPONSE axis: block until the human answers (any type), then print chosen_action JSON (ask/approval imply it)',
   '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)',
@@ -308,7 +337,7 @@ const OPTION_DOCS = {
   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)',
+  timeout: '--timeout SECONDS        how long --wait blocks (ask/approval: template suggestion ~3600 · 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)',
@@ -330,11 +359,14 @@ const OPTION_DOCS = {
   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',
+// Content flags shared by every send.
+const CONTENT_OPTS = ['title', 'body', 'body-markdown', 'body-markdown-file', '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'];
+// Typed sends also carry the RESPONSE axis: --wait (block on the answer) + the
+// blocking knobs. (`live` is status-only — it never answers, so it skips these.)
+const SEND_OPTS = [...CONTENT_OPTS, 'gated', 'wait', 'timeout', 'interval', 'realtime', 'no-realtime'];
 
 const HELP = {
   setup: {
@@ -356,50 +388,75 @@ const HELP = {
   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.',
+    body: 'First contact on a fresh channel: send the debut handshake and block until your human confirms. The server narrates a 3-stage Live Activity.',
     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],
+  // AXIS 1 — the married catalog of 5 (perfis-S1/S2). The TYPE you pick IS how the
+  // human configured it to arrive. RESPONSE (--actions/--wait) composes on any of them.
+  message: {
+    summary: 'just inform — passive info the human reads when they want; no action (clears when they OPEN it).',
+    usage: 'pidge message --title TEXT [--body TEXT | --body-markdown MD] [--image PATH] [--url URL]',
+    body: 'Fire-and-forget by default (stdout is the raw 201). Use it for logs, registros and neutral summaries. Need a decision? add --actions + --wait, or use `pidge important`/`pidge approval`. (Replaces the old `fyi`.)',
+    opts: [...SEND_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],
+  important: {
+    summary: '⭐ the DEFAULT — a pendency the human should resolve ("waiting-for-you" card; clears on Done).',
+    usage: 'pidge important --title TEXT [--actions yes,no,reply] [--wait] [--body-markdown MD]',
+    body: 'Fire-and-forget by default; add --actions/--custom-action for quick-tap buttons and --wait to block until the human answers (prints chosen_action JSON). The most-used type — on the fence between informing and asking, pick this. (Replaces the old `report`.)',
+    opts: [...SEND_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'],
+  urgent: {
+    summary: 'breaks through silent/Focus; --escalate forces an AlarmKit alarm. Use for the real and inadiável (<1/day).',
+    usage: 'pidge urgent --title TEXT [--escalate] [--actions yes,no] [--wait]',
+    body: 'A contract of trust: reserve it for what truly can\'t wait. --escalate asks for an AlarmKit alarm that rings through silent + Focus (the human\'s settings still decide). Once DELIVERED an urgent only stops when answered — you can\'t abort it. (Replaces the old `alert`.)',
+    opts: [...SEND_OPTS, 'escalate'],
   },
   event: {
-    summary: 'surface a scheduled thing with a known time — countdown Live Activity (#246 type event → Evento).',
+    summary: 'a scheduled thing with a known time — countdown Live Activity (needs --event-at).',
     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'],
+    opts: [...SEND_OPTS],
   },
   live: {
-    summary: 'track an in-flight task (deploy/build/trip) with incremental updates (#246 type live → Live Activity).',
+    summary: 'track an in-flight task (deploy/build/trip) with incremental updates (Live Activity). Status-only — never answers.',
     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.',
+    body: 'Fire-and-forget. Records the live type; the LA-as-primitive is being built — today the send is delivered as a normal notification. Use judgement, not a recipe: show what the human WANTS to watch evolve.',
     opts: [...CONTENT_OPTS],
   },
+  // AXIS 2 — the two response shortcuts (bundle a type + buttons + --wait).
+  ask: {
+    summary: 'a DECISION — = important + --wait; needs --actions. Blocks until the human answers (prints chosen_action JSON).',
+    usage: 'pidge ask --title TEXT --actions yes,no,reply [--reply-to URL] [options]',
+    body: 'Shorthand for important --wait that REQUIRES a way to answer — --actions (catalog or JSON) or --custom-action. Holds a WebSocket (or polls) until a TERMINAL answer; a snooze/reschedule re-fires.',
+    opts: [...CONTENT_OPTS, 'timeout', 'interval', 'realtime', 'no-realtime'],
+  },
+  approval: {
+    summary: 'a go/no-go RECIPE — = important + Approve/Reject + Face ID on Approve + --wait.',
+    usage: 'pidge approval --title TEXT [--body-markdown MD] [options]',
+    body: 'The easy shortcut for an explicit approval: injects an Approve (Face-ID gated) / Reject pair and blocks on the answer. Pass your own --actions/--custom-action to override the default pair. A gated action is detail-screen only (the banner shows no quick buttons by design — gotcha #19).',
+    opts: [...CONTENT_OPTS, 'timeout', 'interval', 'realtime', 'no-realtime'],
+  },
+  // COMPAT aliases — old names map to the new type (kept so scripts don't break).
+  fyi: {
+    summary: 'COMPAT alias of `pidge message` (renamed in 0.14 — the married catalog). Still works; prefer `message`.',
+    usage: 'pidge fyi … (→ pidge message …)',
+    opts: [...SEND_OPTS],
+  },
+  report: {
+    summary: 'COMPAT alias of `pidge important` (renamed in 0.14). Still works; prefer `important`.',
+    usage: 'pidge report … (→ pidge important …)',
+    opts: [...SEND_OPTS],
+  },
+  alert: {
+    summary: 'COMPAT alias of `pidge urgent` (renamed in 0.14). Still works; prefer `urgent`.',
+    usage: 'pidge alert … (→ pidge urgent …)',
+    opts: [...SEND_OPTS, 'escalate'],
+  },
   notify: {
-    summary: 'DEPRECATED (0.13.x) — send WITHOUT a type; the server falls back to fyi. Use a typed send instead.',
+    summary: 'DEPRECATED — send WITHOUT a type; the server falls back to its default. 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],
+    body: 'Kept for compat — it warns and still sends (no template_kind; the server picks the channel default). Prefer `pidge message/important/urgent/event/live` (or the `ask`/`approval` shortcuts).',
+    opts: [...SEND_OPTS],
   },
   wait: {
     summary: 'block on an already-sent notification until it is answered (prints chosen_action JSON).',
@@ -504,7 +561,7 @@ 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 on stderr — the agent re-reads the
 // manifest (whats_new) and learns the new capabilities without polling.
-const KNOWN_MANIFEST_VERSION = 36;
+const KNOWN_MANIFEST_VERSION = 46;
 const NAG_TTL_MS = 24 * 60 * 60 * 1000; // #241: at most one nag per 24 h
 let newsWarned = false;
 
@@ -781,7 +838,13 @@ 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;
-  if (v['body-markdown'] !== undefined) body.body_markdown = v['body-markdown'];
+  if (v['body-markdown-file'] !== undefined) {
+    body.body_markdown = v['body-markdown-file'] === '-'
+      ? fs.readFileSync(0, 'utf8')
+      : fs.readFileSync(v['body-markdown-file'], 'utf8');
+  } else if (v['body-markdown'] !== undefined) {
+    body.body_markdown = v['body-markdown'];
+  }
   if (v.subtitle !== undefined) body.subtitle = v.subtitle;
   if (v.template !== undefined) body.template = v.template;
   if (v.profile !== undefined) body.profile = v.profile;
@@ -818,6 +881,15 @@ function buildBody(extra = {}) {
   for (const spec of v['custom-action'] || []) customActions.push(customActionFromSpec(spec));
   if (customActions.length) body.custom_actions = customActions;
 
+  // #274: --gated synthesizes ONE Face-ID confirm on the consequential action
+  // (money/deletion) — the replacement for the retired content_template:sensitive.
+  // Skip if the agent already supplied a biometric action (don't double-gate).
+  if (v.gated && !(body.custom_actions || []).some((c) => c.biometric)) {
+    body.custom_actions = (body.custom_actions || []).concat([
+      { id: 'confirm_action', label: 'Confirm', style: 'destructive', confirm: true, biometric: true, terminal: true },
+    ]);
+  }
+
   // #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);
@@ -932,23 +1004,83 @@ async function doNotify(extra = {}) {
   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);
+// The RESPONSE axis (perfis-S2): true when the send carries SOME way for the human
+// to answer with a tap — built-in actions, custom actions, or a content --template
+// that supplies them. Free-text reply is ALWAYS available, so this is only about
+// buttons. `ask` requires it; `approval` injects a default pair when it's absent.
+const hasAnswerAffordance = () =>
+  v.actions !== undefined || (v['custom-action'] || []).length > 0 || v.template !== undefined;
+
+// The `approval` recipe's default button pair (perfis-S2 follow-up). Sent as
+// CUSTOM actions, NOT built-ins: only custom_actions can carry `biometric` (Face
+// ID), and a custom id may NOT reuse a built-in id like approve/reject (the server
+// 422s "collides with a built-in") — so the ids are grant/deny. Face ID gates the
+// consequential "Approve"; "Reject" is the safe (destructive-styled) out. A gated
+// action is detail-screen only (no banner buttons — gotcha #19), by design.
+const APPROVAL_ACTIONS = [
+  { id: 'grant', label: 'Approve', biometric: true, terminal: true },
+  { id: 'deny', label: 'Reject', style: 'destructive', terminal: true },
+];
+
+// The married catalog of 5 (perfis-S1): one send, stamped with the canonical
+// `template_kind` (message/important/urgent/event/live). The RESPONSE axis is
+// orthogonal: with `wait:false` it's fire-and-forget (print the raw 201, exit);
+// with `wait:true` it mints a cid, sends, and BLOCKS until a terminal answer
+// (print chosen_action JSON). `requireAnswerable` gates `ask`. `extra` carries
+// raw fields (urgent's escalate:true, approval's injected custom_actions).
+async function doTypedSend(kind, { wait = false, extra = {}, requireAnswerable = false, label = kind } = {}) {
+  if (!v.title) die('pidge: --title is required', 1);
+  // `live` is status-only — it never produces an answer, so --wait would block the
+  // full timeout believing the human is deciding. Refuse it (mirror the old ask guard).
+  if (wait && (kind === 'live' || v.profile === 'tracking'))
+    die(`pidge: \`${label}\`${kind === 'live' ? '' : ' --profile tracking'} can't --wait — ${kind === 'live' ? '`live` is' : 'tracking is'} status-only and never produces an answer (drop --wait, or ask with a real type)`, 1);
+  if (requireAnswerable && !hasAnswerAffordance())
+    die(`pidge: --actions required for ${label}. Add buttons with --actions yes,no (or approve,reject) or --custom-action id:label.`, 1);
+
+  if (!wait) {
+    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);
+  }
+
+  // --wait: the cid is minted CLIENT-side when not given, and printed as the FIRST
+  // stderr line (greppable) — a killed/crashed wait 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({ template_kind: kind, ...extra });
+  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 (human
+  // decisions take 30-40 min; a 600 s default misreads them as silence). Explicit wins.
+  let timeout = num(v.timeout, NaN);
+  if (!Number.isFinite(timeout)) {
+    if (info.suggested_ask_timeout) {
+      timeout = info.suggested_ask_timeout;
+      console.error(`pidge: timeout ${Math.round(timeout / 60)} min — suggested by template ${info.template || v.template} (override with --timeout)`);
+    } else if (info.requires_action) {
+      timeout = 3600;   // #274/#132: a human decision (buttons present) takes 30-40 min, not 600 s of "silence"
+      console.error(`pidge: no template suggestion — defaulting --wait to 60 min for a decision (override with --timeout)`);
+    } else {
+      timeout = 600;
+    }
+  }
+  await waitForAnswer(cid, { timeout, interval: num(v.interval, 30) });
+}
+
+// A compat alias (perfis-S1): the OLD type name still works, mapped to the new
+// canonical one — a one-line note points at the rename so muscle-memory migrates.
+function warnRenamed(oldName, newName) {
+  console.error(`pidge: \`pidge ${oldName}\` was renamed → use \`pidge ${newName}\` (the married catalog of 5; the alias keeps working).`);
 }
 
-// #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).
+// `pidge notify` / `pidge send` (no type) are deprecated — they still send, and the
+// server falls back to the channel default. Prefer a typed send. Warning is local.
 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.`);
+  console.error(`pidge: \`pidge ${name}\` is deprecated — use a TYPE instead: message · important · urgent · event · live (or the ask/approval shortcuts; see \`pidge help\`). It still sends (no template_kind ⇒ the server picks the channel default).`);
 }
 
 // Poll GET /notifications/:cid until a TERMINAL answer, print chosen_action JSON to
@@ -1457,9 +1589,9 @@ async function runDoctor(base = BASE, token = TOKEN, sourceLabel = null) {
     console.error(`pidge doctor: realtime: INDISPONÍVEL — ${rt.reason}. O \`listen\` degrada pra polling (funciona, menos instantâneo); use --no-realtime pra fixar o piso.`);
   }
   // #229: lead with `pidge hello` — the first-contact WOW (send + wait in one),
-  // the same debut the /agent-setup guide leads with. It's a thin wrapper over
-  // `ask --template onboarding` (the underlying mechanism, if you need it raw).
-  console.error('pidge doctor: all good — try: pidge hello   (first-contact WOW — send + wait in one; equivalent: pidge ask --template onboarding)');
+  // the same debut the /agent-setup guide leads with. (#274: no --template hint —
+  // `pidge hello` IS the entry point; the content_template surface is off the menu.)
+  console.error('pidge doctor: all good — try: pidge hello   (first-contact WOW — send + wait in one)');
   console.log(JSON.stringify({ ok: true, base_url: base, channel: data.channel, devices, manifest_version: data.manifest_version, realtime }));
   process.exit(0);
 }
@@ -1526,6 +1658,7 @@ async function runSetup() {
     console.log(`export PIDGE_URL=${finalBase}`);
     console.log(`export PIDGE_TOKEN=${data.key}`);
     console.error(`pidge: canal "${channelName}" — modo POR-AGENTE (nada gravado em disco). Cole as duas linhas no ambiente de lançamento DESTE agente (systemd/launcher/cron/profile). Cada agente tem a SUA chave; perdeu, é só pegar outro código no app e re-rodar (a chave do canal é a MESMA). NÃO rode --print de dentro de um agente — a chave apareceria no contexto dele.`);
+    await fuseSkillAndHello(finalBase, data.key);
     await runDoctor(finalBase, data.key, 'fresh claim (per-agent env — not stored on disk)');
     return;
   }
@@ -1546,102 +1679,180 @@ async function runSetup() {
   }
   if (!AGENT_ID)
     console.error('pidge: este é o arquivo COMPARTILHADO (single-agent). Vai rodar 2+ agentes nesta máquina? Dê a cada um PIDGE_AGENT=<id> no launch (arquivo isolado por agente) — senão eles enviam como o mesmo canal.');
+  await fuseSkillAndHello(finalBase, data.key);
   await runDoctor(finalBase, data.key, CONFIG_FILE);
 }
 
-// skill install (#110e): persistent Pidge knowledge for Claude Code agents —
-// a skill generated FROM the live manifest (so it can't drift), versioned with
-// manifest_version (re-run to update; whats_new is the changelog).
-async function runSkillInstall() {
+// #274 F4: setup → skill → hello. Best-effort, run right BEFORE the post-setup
+// doctor (runDoctor process.exit()s, so this can't trail it). A skill-install
+// failure is ONE stderr line — NEVER a `--help`/USAGE dump (the graceful-degrade
+// invariant). `pidge hello` stays a printed NEXT step: we don't auto-fire a push
+// the human didn't ask for. base+key are the freshly-claimed ones (the manifest
+// is public, so this works even on the --print path where no token is on disk).
+async function fuseSkillAndHello(base, token) {
+  try {
+    const r = await installSkill(base, token);
+    console.error(`pidge: skill written to ${r.file} (manifest v${r.manifest_version}) — your future sessions in this project know Pidge now`);
+  } catch (e) {
+    console.error(`pidge: skill install skipped (${e.message}) — run \`pidge skill install\` later.`);
+  }
+  console.error('pidge: next → `pidge hello` to send your first handshake and watch it confirm on the lock screen.');
+}
+
+// skill install (#110e; rewritten #274 F3): persistent Pidge knowledge for AI
+// agents — the live manifest's APPENDIX (profiles / notes / exits) wrapped around
+// a HAND-AUTHORED, failure-mode-first spine. The dead content_template
+// `decision_table` is NEVER pulled again, so even an old manifest can't reinject
+// the v46 collision. Non-exiting: RETURNS {file, manifest_version} and THROWS on
+// failure, so callers (`skill install` AND the setup fuse) choose die-vs-degrade.
+async function installSkill(base = BASE, token = TOKEN) {
+  const hdrs = { authorization: `Bearer ${token}`, 'content-type': 'application/json' };
   let res, m;
   try {
-    res = await fetchT(`${BASE}/api/v1/manifest`, { headers });
+    res = await fetchT(`${base}/api/v1/manifest`, { headers: hdrs });
     m = await res.json();
   } catch (e) {
-    die(`pidge: could not read the manifest: ${e.message}`, 2);
+    throw new Error(`could not read the manifest: ${e.message}`);
   }
-  if (res.status !== 200) die(`pidge: manifest read failed (${res.status})`, 2);
-  const table = (m.templates && m.templates.decision_table) || [];
+  if (res.status !== 200) throw new Error(`manifest read failed (${res.status})`);
+  // The ONLY generated parts (the appendix). m.templates.* is deliberately UNREAD.
   const profileTable = (m.profiles && m.profiles.decision_table) || [];
   const notes = m.notes || [];
   const exits = (m.cli && m.cli.output) || '';
   const skill = `---
 name: pidge
-description: Send rich, actionable iPhone notifications to your human and get their decision back (Pidge). Use when finishing long tasks (report), needing a decision/approval, sending FYIs with substance, or anything time-anchored. Also covers reading the human's replies/messages back.
+description: Send rich, actionable iPhone notifications to your human and get their decision back (Pidge). Every send is a TYPE (message/important/urgent/event/live) plus an OPTIONAL response (buttons + send-and-go vs wait). Use when finishing long tasks, needing a decision/approval, sending updates with substance, or anything time-anchored. Also covers reading the human's replies back.
 ---
 
 # Pidge — notify your human, get answers back
 
-Generated from manifest v${m.manifest_version} of ${BASE} — re-run \`pidge skill install\` to update (any API response header X-Pidge-Manifest-Version > ${m.manifest_version} means there's news).
+Generated from manifest v${m.manifest_version} of ${BASE} — re-run \`pidge skill install\` to update (any API response header \`X-Pidge-Manifest-Version\` > ${m.manifest_version} means there's news).
 
-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).
+All commands: \`npx pidge-cli …\` (Node ≥18; reads \`~/.config/pidge/env\` — no token in your context). Not set up? Run \`pidge doctor\`. Onboard with \`pidge setup --claim <code>\` (the human copies the code from the Pidge app), then \`pidge hello\`.
 
-## Choose the right type (REQUIRED in 0.14+)
+## One breath
 
-Every send needs a type. Pick by intent:
+Every send is **a TYPE + a markdown body + an OPTIONAL response**. The TYPE (one of five) decides how much it may intrude — the human already configured how each arrives. The RESPONSE (buttons? wait or not?) is a second, orthogonal axis. **There is no content "template" to choose.**
 
-| 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..." |
+## THE PICKER — situation → exact command
 
-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.)
+| Your situation | Run |
+|---|---|
+| Just inform — a result/log, no action needed | \`pidge message\` |
+| A pendency they should act on (can wait) ⭐ DEFAULT | \`pidge important\` |
+| You need a decision and CAN'T proceed without it | \`pidge important --actions yes,no --wait\` |
+| YOU are asking for a formal go/no-go (money/risk) | \`pidge approval\` |
+| A thing with a known TIME | \`pidge event --event-at <ISO8601>\` |
+| A live status you'll keep updating | \`pidge live\` |
+| WAKE them now — rare, real, <1/day | \`pidge urgent\` |
 
-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.
+⭐ \`important\` is the default. On the fence between informing and asking, pick \`important\`. \`message\` is only for a true no-action FYI. (\`fyi\`/\`report\`/\`ask\`/\`alert\` still work as silent aliases → message/important/important/urgent.) Run \`pidge <type> --help\` for each one's flags.
 
-## Pick the right send (decision table)
+## Approval has two paths — know which one you're in
 
-${table.map((r) => `- ${r}`).join('\n')}
+**Path A — YOU request it (\`pidge approval\`).** You decided this needs a human sign-off. \`pidge approval\` = \`important\` + an **Approve** (Face-ID gated) / **Reject** pair + \`--wait\`. You send it, you block, and you get \`chosen_action.action_id: "grant"\` (approved) or \`"deny"\` (rejected) back. Use it for money, deletions, irreversible actions.
 
-## How it intrudes (profiles — the human owns them)
+**Path B — your HUMAN requires it (a profile knob).** In the app, the human can turn ON **"Require approval · Face ID"** on any profile (the \`ack_requires_biometric\` knob — **OFF by default everywhere**). When it's ON for, say, \`important\`, then **every ordinary send on that profile silently becomes an Approve-with-Face-ID decision** — even a plain \`pidge important\` with no buttons. The server injects a single \`approve\` action, so the send reads back \`actions:["approve"], requires_action:true, acknowledgeable:false\`, the banner is detail-only, and **the human's tap reaches you as \`chosen_action.action_id: "approve"\`** (poll / webhook / \`pidge listen --all\`). You didn't ask — they imposed it.
 
-${profileTable.map((r) => `- ${r}`).join('\n')}
+**Same screen ("Approve + Face ID"), opposite origin: you REQUEST (A, ids \`grant\`/\`deny\`) vs they REQUIRE (B, id \`approve\`).** To tell at runtime: a send that comes back \`acknowledgeable:false\` + \`requires_action:true\` when you didn't add buttons means Path B is on for that profile — treat the \`approve\` as the positive decision it is. (To check a profile's knob ahead of time, read \`ack_requires_biometric\` from the live manifest: \`curl $PIDGE_URL/api/v1/manifest -H "Authorization: Bearer $PIDGE_TOKEN"\` → \`profiles\`.) Caution: Path B on a busy profile means one approval per send — the human's deliberate high-trust choice.
 
-## The contract
+## The response axis (composes on ANY type)
 
-${notes.map((n) => `- ${n}`).join('\n')}
+Asking for a reply is orthogonal to the type — you don't need \`approval\` to get a button.
+- **Free text** is always available; the human can write back on anything.
+- **Buttons** are optional on any type: \`--actions yes,no\` (catalog) or \`--custom-action id:label\`.
+- **Face ID** on a consequential action: \`--gated\` injects one confirm-with-Face-ID button (use it for money/deletion). It does NOT change loudness — pair with a louder profile if it must also be loud. A flag, not a type.
+- **send-and-go vs wait** — the choice that decides how YOU work:
+  - *send-and-go* (default): fire and continue; the answer arrives later in \`pidge listen --all\`.
+  - *wait*: \`--wait\` (or \`pidge ask\`) **blocks** until they tap. Use it when you can't proceed.
+- **Exit codes on a \`--wait\`/\`ask\`:** \`0\` = answered (\`chosen_action\` JSON on stdout) · **\`3\` = no answer yet → NOT a failure** (back off, or treat a blocking go/no-go as "no/hold" and re-ask later) · \`2\` = error.
 
-## Getting answers
+Need a TYPED reply (a time/value/name)? \`--actions reply\` ALONE — never \`yes,no,reply\` together (the human taps the easy button and you get a useless "Yes"). ONE question per send.
 
-- \`pidge ask …\` blocks and prints chosen_action JSON; \`pidge wait <cid>\` blocks on an existing send.
-- \`pidge listen\` blocks until the human MESSAGES you from the app (composer) — run it when idle.
-- ${exits}
+## Anti-slop rules (judgment a recipe can't teach)
 
-## Stay "always-on" while you're turn-based (#244)
+1. **One send = one fact = one ask.** Never two questions in a notification.
+2. **Default to \`important\`.** \`message\` only for true no-action FYIs; \`urgent\` is a contract, not a volume knob — **<1/day**, abuse caps your channel.
+3. **There is no content-template menu.** Every send is type + markdown + optional buttons. If you're reaching for \`--template context/report/digest/sensitive\`, stop — that surface is gone (the field still parses as silent back-compat, but don't teach or rely on it).
+4. **Typed answer? \`--actions reply\` ALONE** — never \`yes,no,reply\` together.
+5. **Trust the 201 echo over your intent** — \`degraded\`/\`render_mode\`/\`registered_devices\`. \`registered_devices:0\` ⇒ it went nowhere; don't wait.
+6. **Don't spam to signal importance.** Consolidate into one markdown body; use \`--collapse-key\` for self-replacing progress, \`--thread\` only for follow-ups over time.
+7. **Be listening when the answer lands, or you lose it.** Ack only AFTER the work is durably done.
+8. **English only, phone-friendly markdown.** Narrow tables (they render), no emoji-spam.
 
-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:
+## Gold examples (full commands)
 
-### Path 1 — an interactive listening window (active session)
+Pendency with a real table → \`important\`:
 \`\`\`bash
-pidge listen --follow --timeout 300   # hold for 5 min (--timeout is SECONDS), printing messages as they arrive
+pidge important --title "Weekly metrics ready" \\
+  --body-markdown $'| Metric | This week | Δ |\\n|---|---|---|\\n| Signups | 1,204 | +8% |\\n| Churn | 1.9% | −0.3pp |' \\
+  --actions reply
 \`\`\`
-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:
+Blocking decision → ask→wait loop (handle exit 3):
 \`\`\`bash
-pidge listen --timeout 50   # block up to 50s for a message, print it, exit 0 (exit 3 = nothing this tick)
+pidge important --title "Run the schema migration?" \\
+  --body-markdown "Dropping \\\`legacy_orders\\\` (412k rows, archived 2025). Not reversible. Safe mid-deploy?" \\
+  --actions yes,no --wait --timeout 3600
+# exit 0 → read chosen_action.action_id (yes|no); exit 3 → no answer, treat as NO / hold, re-ask
 \`\`\`
-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).
+Agent-initiated approval (money) → \`pidge approval\`:
+\`\`\`bash
+pidge approval --title "Place \\$4,200 purchase order?" \\
+  --body-markdown "Vendor: Acme · PO #4471 · moves real money." \\
+  --wait --timeout 3600
+# = important + Approve(Face ID)/Reject + wait; chosen_action.action_id: grant|deny
+\`\`\`
+
+Time-anchored → \`event\` (needs \`--event-at\` in the human's tz):
+\`\`\`bash
+pidge event --event-at "2026-06-30T15:00:00-03:00" --title "Call with accountant"
+\`\`\`
+
+Long markdown without shell-quoting pain → pipe it:
+\`\`\`bash
+generate_report | pidge important --title "Report ready" --body-markdown-file - --actions reply
+\`\`\`
+
+## Gotchas we already paid for
+
+- **There is no \`pidge reply\`.** \`reply\` is a built-in action id, not a command. To answer the human's composer message, send a normal \`pidge message --thread <id>\` reusing the message's \`thread_id\`.
+- **\`urgent\` is a trust contract, not a button.** It arms an AlarmKit alarm; once delivered you **cannot abort it** (\`pidge cancel\` → 409). Real + unpostponable only, <1/day. Never test it without warning the human.
+- **A 201 ≠ "seen."** \`registered_devices:0\` goes nowhere; \`delivered\` is APNs dispatch, not eyes; only \`seen_at\`/an answer is the human.
+- **The ask reply-vs-yes/no trap.** \`--actions yes,no,reply\` lets the human dodge a typed answer with one tap — use \`--actions reply\` alone when you need text.
+- **\`event\` is quiet today** — \`event --event-at\` schedules; the countdown LA-as-primitive is still being built.
+- **content_template still parses as input** (back-compat) but is OFF the menu — if a legacy habit sends \`--template report\`, it silently maps; don't rely on it, don't teach it.
+
+## How it intrudes (profiles — the human owns them)
+
+${profileTable.map((r) => `- ${r}`).join('\n')}
+
+## The contract
+
+${notes.map((n) => `- ${n}`).join('\n')}
+
+## Getting answers
+
+- \`pidge ask …\` blocks and prints \`chosen_action\` JSON; \`pidge wait <cid>\` blocks on an existing send.
+- \`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
+
+A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE without a daemon:
+- **Active session:** \`pidge listen --follow --timeout 300\` holds for 5 min, printing messages as they arrive. \`--follow\` traps the turn — use it only when you intend to sit and wait.
+- **Supervisor poll (24/7):** a cron/systemd timer invokes you every N min; each tick runs ONE one-shot \`pidge listen --timeout 50\` (block up to 50s, print, exit 0; exit 3 = nothing this tick), do the work, \`pidge ack --up-to <id>\`, sleep. \`--timeout\` is always SECONDS. Do NOT background \`pidge listen\` with \`&\`.
 
 ## Full spec
 
-\`curl $PIDGE_URL/api/v1/manifest -H "Authorization: Bearer $PIDGE_TOKEN"\` — the always-current contract (fields, templates, custom actions, media, threads, realtime).
+\`curl $PIDGE_URL/api/v1/manifest -H "Authorization: Bearer $PIDGE_TOKEN"\` — the always-current contract (fields, profiles, custom actions, media, threads, realtime).
 `;
   const dir = path.join(process.cwd(), '.claude', 'skills', 'pidge');
   fs.mkdirSync(dir, { recursive: true });
   const file = path.join(dir, 'SKILL.md');
   fs.writeFileSync(file, skill);
-  console.error(`pidge: skill written to ${file} (manifest v${m.manifest_version}) — your future sessions in this project know Pidge now`);
-  console.log(JSON.stringify({ ok: true, file, manifest_version: m.manifest_version }));
-  process.exit(0);
+  return { file, manifest_version: m.manifest_version };
 }
 
 (async () => {
@@ -1669,15 +1880,27 @@ Each poll is one of your turns: pick up the message, do the work, \`pidge ack --
     }
     case 'skill': {
       if (parsed.positionals[1] !== 'install') die('pidge: usage: pidge skill install', 1);
-      await runSkillInstall();
-      break;
+      let r;
+      try { r = await installSkill(); } catch (e) { die(`pidge: ${e.message}`, 2); }
+      console.error(`pidge: skill written to ${r.file} (manifest v${r.manifest_version}) — your future sessions in this project know Pidge now`);
+      console.log(JSON.stringify({ ok: true, file: r.file, manifest_version: r.manifest_version }));
+      process.exit(0);
     }
-    // #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);
+    // === AXIS 1 — the married catalog of 5 (perfis-S1/S2). Each stamps the
+    // canonical template_kind. AXIS 2 (response) is orthogonal: --actions/
+    // --custom-action add buttons, --wait blocks on the answer (else fire-and-
+    // forget). notify/send = the deprecated typeless path; ask/approval = the
+    // two shortcuts that bundle a type + response. ===
+    case 'message':
+      await doTypedSend('message', { wait: !!v.wait });
+      break;
+    case 'important':
+      await doTypedSend('important', { wait: !!v.wait });
+      break;
+    case 'urgent':
+      // --escalate ⇒ escalate:true (ask the Urgente profile for an AlarmKit alarm
+      // that breaks through silent/Focus; the human's profile still decides).
+      await doTypedSend('urgent', { wait: !!v.wait, extra: v.escalate ? { escalate: true } : {} });
       break;
     case 'event': {
       // event needs a TIME — validate locally (ISO8601) so the agent fails fast
@@ -1686,17 +1909,37 @@ Each poll is one of your turns: pick up the message, do the work, \`pidge ack --
         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');
+      await doTypedSend('event', { wait: !!v.wait });
       break;
     }
+    case 'live':
+      // status-only — pass --wait through so doTypedSend REFUSES it loudly (it
+      // never produces an answer); without --wait it's fire-and-forget.
+      await doTypedSend('live', { wait: !!v.wait });
+      break;
+    // --- compat aliases (perfis-S1): old type names → the new canonical 5. They
+    // map to the new template_kind and still honor --wait/--actions, so scripts
+    // and muscle-memory keep working; a one-line note points at the new name.
+    case 'fyi':
+      warnRenamed('fyi', 'message');
+      await doTypedSend('message', { wait: !!v.wait, label: 'fyi' });
+      break;
+    case 'report':
+      warnRenamed('report', 'important');
+      await doTypedSend('important', { wait: !!v.wait, label: 'report' });
+      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 } : {});
+      warnRenamed('alert', 'urgent');
+      await doTypedSend('urgent', { wait: !!v.wait, extra: v.escalate ? { escalate: true } : {}, label: 'alert' });
       break;
-    case 'live':
-      await doTypedNotify('live');
+    // `approval` = the RECIPE (perfis-S2 follow-up): important + Approve/Reject
+    // (Face ID on Approve) + --wait. A shortcut for an explicit go/no-go; the human
+    // can override the pair with their own --actions/--custom-action.
+    case 'approval': {
+      const extra = hasAnswerAffordance() ? {} : { custom_actions: APPROVAL_ACTIONS };
+      await doTypedSend('important', { wait: true, extra, label: 'approval' });
       break;
+    }
     case 'notify':
     case 'send': {
       warnDeprecatedSend(command);
@@ -1717,8 +1960,8 @@ Each poll is one of your turns: pick up the message, do the work, \`pidge ack --
       if (v.profile === 'tracking')
         die('pidge: `hello --profile tracking` makes no sense — the handshake waits for a confirmation, which tracking (Live-Activity-only) never produces', 1);
       v.template = 'onboarding';
-      if (v.title === undefined) v.title = 'Seu agente está pronto 🐦';
-      if (v.body === undefined) v.body = 'Toque em Feito ✓ para confirmar que me recebeu — você vai ver o teste fechar na tela.';
+      if (v.title === undefined) v.title = 'Your agent is ready 🐦';
+      if (v.body === undefined) v.body = 'Tap Done ✓ to confirm you received me — proves the round-trip works.';
       const cid = v['correlation-id'] || crypto.randomUUID();
       v['correlation-id'] = cid;
       console.error(`pidge: correlation_id=${cid}`);
@@ -1733,40 +1976,11 @@ Each poll is one of your turns: pick up the message, do the work, \`pidge ack --
       break;
     }
     case 'ask': {
-      // Send, then block on the answer in one shot. stdout = ONLY chosen_action JSON.
-      // tracking is Live-Activity-only: it NEVER produces a chosen_action, so an ask
-      // would block the full timeout believing the human is deciding.
-      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({ 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
-      // (human decisions take 30-40 min in the wild; a 600 s default misread
-      // them as silence). Explicit --timeout always wins.
-      let timeout = num(v.timeout, NaN);
-      if (!Number.isFinite(timeout)) {
-        if (info.suggested_ask_timeout) {
-          timeout = info.suggested_ask_timeout;
-          const mins = Math.round(timeout / 60);
-          console.error(`pidge: timeout ${mins} min — suggested by template ${info.template || v.template} (override with --timeout)`);
-        } else {
-          timeout = 600;
-        }
-      }
-      await waitForAnswer(cid, { timeout, interval: num(v.interval, 30) });
+      // `ask` = the preserved shortcut: important + --wait + REQUIRES a way to
+      // answer. There is no `ask` TYPE in the married catalog (manifest v40+) —
+      // asking is "a type + buttons + wait". The legacy alias keeps working because
+      // it always ships with buttons. `live`/tracking is refused (it never answers).
+      await doTypedSend('important', { wait: true, requireAnswerable: true, label: 'ask' });
       break;
     }
     case 'wait': {
@@ -2052,8 +2266,8 @@ Each poll is one of your turns: pick up the message, do the work, \`pidge ack --
       break;
     }
     default:
-      // #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);
+      // Name the bad command and point at the married catalog + the two response
+      // shortcuts (a friendlier landing than dumping the whole USAGE on a typo).
+      die(`pidge: unknown subcommand '${command}'. Types: message · important · urgent · event · live (response: --actions/--wait, or the ask/approval shortcuts). pidge --help`, 1);
   }
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pidge-cli",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",