pidge-cli 0.15.0 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.15.2 — #280 the skill self-heals
+
+#280 — the local skill self-heals: any pidge command silently refreshes
+`.claude/skills/pidge/SKILL.md` when the skill revision or manifest version is newer than
+what's installed, so onboarded agents always run the latest skill.
+
+- **feat:** a bumpable `SKILL_REVISION` constant + the live manifest version are baked into a
+  first-line marker (`<!-- pidge-skill rev=R manifest=N -->`) of every generated `SKILL.md`.
+  `ensureSkillFresh()` (run from `checkManifestNews`, which already fires on every command via
+  the `x-pidge-manifest-version` header) compares the installed marker against this CLI's spine
+  and the server's manifest; when either is newer it silently regenerates the skill and prints
+  one stderr note. Only an EXISTING skill is refreshed (never auto-created), at most once per
+  process, fully best-effort (a refresh failure never breaks your command), and `QUIET_NAG`
+  suppresses the note (the regenerate still happens).
+- **note:** this composes with `@latest` — an agent on `npx pidge-cli@latest` picks up a new
+  `SKILL_REVISION` and self-heals the spine on its next command. A PINNED CLI still self-heals
+  on a server manifest bump (via the header) but can't gain a newer hand-authored spine without
+  updating the CLI. BUMP `SKILL_REVISION` in any future sprint that edits the SKILL.md spine.
+
+## 0.15.1 — #274-D skill polish
+
+skill polish — catalog-first actions, write-for-the-lock-screen (banner = title+body; body_markdown is detail-only), good-report guidance; gold examples now set a plain --body.
+
 ## 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.

package/bin/pidge.js

@@ -562,8 +562,17 @@ function fetchT(url, opts = {}, timeoutMs = 30000) {
 // 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 = 46;
+// #280: the hand-authored skill SPINE version. BUMP whenever the SKILL.md spine
+// (the non-generated prose in installSkill) changes — an existing install whose
+// baked marker is older than this self-heals on its next pidge command, so an
+// onboarded agent always runs the latest skill without any human action. Start at 1.
+const SKILL_REVISION = 1;
 const NAG_TTL_MS = 24 * 60 * 60 * 1000; // #241: at most one nag per 24 h
 let newsWarned = false;
+// #280: the self-heal runs at most ONCE per process (one regeneration, even when
+// many commands/poll-ticks call checkManifestNews). Non-stale checks stay cheap +
+// repeatable; this only latches once an actual heal is attempted.
+let skillHealed = 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
@@ -581,9 +590,14 @@ function writeState(patch) {
   } catch { /* best-effort — the nag just won't persist its throttle */ }
 }
 
-function checkManifestNews(res) {
-  if (QUIET_NAG || newsWarned) return;
+async function checkManifestNews(res) {
   const ver = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
+  // #280: the self-heal runs on EVERY command (its own once-guard + cheap
+  // first-line read), BEFORE the nag throttle below — it must fire even when the
+  // server isn't ahead of KNOWN_MANIFEST_VERSION (a pure spine bump) and even
+  // under QUIET_NAG (which only silences the stderr note, never the regenerate).
+  await ensureSkillFresh(ver);
+  if (QUIET_NAG || newsWarned) return;
   // (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
@@ -607,6 +621,38 @@ function checkManifestNews(res) {
   console.error(`pidge: the server has NEW capabilities (manifest v${ver}; this CLI knows v${KNOWN_MANIFEST_VERSION}) — pidge is a thin pipe, so you can use any new /notify field RIGHT NOW via --param KEY=VALUE. Read the catalog (whats_new) in the public manifest:  curl $PIDGE_URL/api/v1/manifest  (public; add -H "Authorization: Bearer $PIDGE_TOKEN" to also see your channel's config). Updating the CLI only matters to gain native flags:  npx pidge-cli@latest  (a pinned ref never self-updates). Silence this with --quiet-nag or PIDGE_QUIET_NAG=1.`);
 }
 
+// #280: STRUCTURAL self-heal — keep the LOCAL skill current with zero human action.
+// The installed .claude/skills/pidge/SKILL.md is written once at onboarding and then
+// goes stale silently (a CLI/skill improvement gives an onboarded agent no signal, so
+// it keeps running the old skill). This silently regenerates it when EITHER trigger
+// fires: this CLI's hand-authored spine moved (SKILL_REVISION > the baked rev) OR the
+// server's manifest moved (serverManifestVersion > the baked manifest) — caught from
+// the x-pidge-manifest-version header that already rides every response. So the agent's
+// NEXT session is always current. Only REFRESHES an existing skill (creating one is
+// onboarding's job, never a side effect of an unrelated command), runs at most once per
+// process, and is wholly best-effort: any failure is swallowed — a skill refresh must
+// NEVER break the user's actual command.
+async function ensureSkillFresh(serverManifestVersion) {
+  if (skillHealed) return;
+  try {
+    // Resolve the path the SAME way installSkill does (cwd-relative).
+    const file = path.join(process.cwd(), '.claude', 'skills', 'pidge', 'SKILL.md');
+    if (!fs.existsSync(file)) return; // don't auto-create — only refresh an existing skill
+    const firstLine = fs.readFileSync(file, 'utf8').split('\n', 1)[0] || '';
+    const revM = firstLine.match(/rev=(\d+)/);
+    const manM = firstLine.match(/manifest=(\d+)/);
+    const installedRev = revM ? parseInt(revM[1], 10) : 0;
+    const installedManifest = manM ? parseInt(manM[1], 10) : 0;
+    const stale = SKILL_REVISION > installedRev || (serverManifestVersion || 0) > installedManifest;
+    if (!stale) return;
+    skillHealed = true; // latch BEFORE the network write — attempt the heal at most once
+    const r = await installSkill(BASE, TOKEN); // silent: it already writes the file
+    // Respect QUIET_NAG/PIDGE_QUIET_NAG for the note only — we STILL regenerated.
+    if (!QUIET_NAG)
+      console.error(`pidge: refreshed your local Pidge skill (rev ${SKILL_REVISION}, manifest v${r.manifest_version}) — your next session will use it.`);
+  } catch { /* best-effort — a skill refresh must never break the user's command */ }
+}
+
 // ---------------------------------------------------------------------------
 // #119: the health ledger of one blocking session (wait/ask/listen). Drives
 //   (a) automatic DEGRADE from held ?wait= polls to plain GETs after
@@ -976,7 +1022,7 @@ async function doNotify(extra = {}) {
   } catch (e) {
     die(`pidge: send failed (network): ${e.message}`, 2);
   }
-  checkManifestNews(res);
+  await checkManifestNews(res);
   const ok = res.status >= 200 && res.status < 300;
   let info = {};
   try { info = JSON.parse(raw); } catch { /* leave {} */ }
@@ -1100,7 +1146,7 @@ async function doWait(cid, { timeout, interval }) {
     const askedAt = Date.now();
     try {
       const res = await fetchT(url, { headers }, (waitS + 10) * 1000);
-      checkManifestNews(res);
+      await checkManifestNews(res);
       if (res.status === 200) {
         health.ok();
         const data = await res.json().catch(() => ({}));
@@ -1414,7 +1460,7 @@ async function runContract() {
   } catch (e) {
     die(`pidge: contract set failed (network): ${e.message}`, 2);
   }
-  checkManifestNews(res);
+  await checkManifestNews(res);
   if (!(res.status >= 200 && res.status < 300)) die(`pidge: contract set failed (${res.status}): ${body}`, 2);
   // stdout = ONLY the operating_contract, never the raw channel JSON. The
   // /channels PATCH echoes the whole channel — INCLUDING "key":"hld_…" — and
@@ -1464,7 +1510,7 @@ async function doSelftest() {
     const res = await fetchT(`${BASE}/api/v1/selftest`, {
       method: 'POST', headers, body: JSON.stringify({ window_seconds: windowS }),
     });
-    checkManifestNews(res);
+    await checkManifestNews(res);
     if (res.status < 200 || res.status >= 300) die(`pidge: selftest: the server refused (${res.status}) — is your key valid? try \`pidge doctor\``, 2);
     fired = await res.json();
   } catch (e) {
@@ -1537,7 +1583,7 @@ async function runDoctor(base = BASE, token = TOKEN, sourceLabel = null) {
     process.exit(2);
   }
   const { res, data } = out;
-  checkManifestNews(res);
+  await checkManifestNews(res);
   if (res.status === 401) {
     console.error('pidge doctor: server reachable but the key is INVALID/REVOKED — re-onboard: ask your human for a fresh claim code (Pidge app → Canais → o canal → copiar prompt de setup)');
     process.exit(2);
@@ -1719,7 +1765,8 @@ async function installSkill(base = BASE, token = TOKEN) {
   const profileTable = (m.profiles && m.profiles.decision_table) || [];
   const notes = m.notes || [];
   const exits = (m.cli && m.cli.output) || '';
-  const skill = `---
+  const skill = `<!-- pidge-skill rev=${SKILL_REVISION} manifest=${m.manifest_version} -->
+---
 name: pidge
 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.
 ---
@@ -1748,6 +1795,13 @@ Every send is **a TYPE + a markdown body + an OPTIONAL response**. The TYPE (one
 
 ⭐ \`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.
 
+## Write for the lock screen (what the human actually sees)
+
+The banner shows your **\`--title\`** and **\`--body\`** (plain text). **\`--body-markdown\` does NOT appear on the banner** — it's the in-app detail screen only. So:
+- **Always give a concise \`--body\`** — the one-line human-readable gist. A title-only send can show as an empty banner (just your channel name).
+- Put the rich part (tables, lists, code, an image) in **\`--body-markdown\`** (and/or \`--image\`) — the human sees it when they tap in.
+- A good send: **title = the answer at a glance · body = the few facts they need to decide/act · body-markdown = the rich detail · ONE ask.** Never ship a title-only notification.
+
 ## Approval has two paths — know which one you're in
 
 **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.
@@ -1760,7 +1814,7 @@ Every send is **a TYPE + a markdown body + an OPTIONAL response**. The TYPE (one
 
 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\`.
+- **Buttons** — reach for a BUILT-IN catalog action FIRST; they're tappable right on the lock-screen banner. Decisions: \`--actions yes,no\` · \`approve,reject\` · \`accept,decline\` · \`later\`; plus \`done\`, \`snooze\`, \`reply\`. Use \`--custom-action id:label\` ONLY when none fit — **custom labels (and any destructive/Face-ID action) render detail-only**, so the human must open the app to answer instead of tapping the banner.
 - **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\`.
@@ -1779,12 +1833,14 @@ Need a TYPED reply (a time/value/name)? \`--actions reply\` ALONE — never \`ye
 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.
+9. **Banner-first + catalog-first.** Give a real \`--body\` (the banner shows title+body, never body-markdown), and fit decisions into a catalog action (\`yes,no\`/\`approve,reject\`) before inventing a custom label (custom = a tap-through, not a banner tap).
 
 ## Gold examples (full commands)
 
 Pendency with a real table → \`important\`:
 \`\`\`bash
 pidge important --title "Weekly metrics ready" \\
+  --body "Signups 1,204 (+8%) · churn 1.9% (−0.3pp) · table inside" \\
   --body-markdown $'| Metric | This week | Δ |\\n|---|---|---|\\n| Signups | 1,204 | +8% |\\n| Churn | 1.9% | −0.3pp |' \\
   --actions reply
 \`\`\`
@@ -1792,7 +1848,8 @@ pidge important --title "Weekly metrics ready" \\
 Blocking decision → ask→wait loop (handle exit 3):
 \`\`\`bash
 pidge important --title "Run the schema migration?" \\
-  --body-markdown "Dropping \\\`legacy_orders\\\` (412k rows, archived 2025). Not reversible. Safe mid-deploy?" \\
+  --body "Drops legacy_orders (412k rows), not reversible. Safe mid-deploy?" \\
+  --body-markdown "Dropping \\\`legacy_orders\\\` (412k rows, archived 2025). **Not reversible.** Safe to run 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
 \`\`\`
@@ -1800,19 +1857,22 @@ pidge important --title "Run the schema migration?" \\
 Agent-initiated approval (money) → \`pidge approval\`:
 \`\`\`bash
 pidge approval --title "Place \\$4,200 purchase order?" \\
-  --body-markdown "Vendor: Acme · PO #4471 · moves real money." \\
+  --body "Acme · PO #4471 · \\$4,200 — moves real money" \\
+  --body-markdown "Vendor: Acme · PO #4471 · **\\$4,200**, 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"
+pidge event --event-at "2026-06-30T15:00:00-03:00" --title "Call with accountant" \\
+  --body "3pm tomorrow with the accountant"
 \`\`\`
 
 Long markdown without shell-quoting pain → pipe it:
 \`\`\`bash
-generate_report | pidge important --title "Report ready" --body-markdown-file - --actions reply
+generate_report | pidge important --title "Report ready" \\
+  --body "Q2 report ready — revenue, churn, and 3 risks inside" --body-markdown-file - --actions reply
 \`\`\`
 
 ## Gotchas we already paid for
@@ -1823,6 +1883,7 @@ generate_report | pidge important --title "Report ready" --body-markdown-file -
 - **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.
+- **The banner ≠ the detail screen.** Lock-screen banner = \`title\` + \`body\` (plain). \`body_markdown\`/images render only when the human taps in. A send with only \`--title\` can look empty on the lock screen — always include a \`--body\`.
 
 ## How it intrudes (profiles — the human owns them)
 
@@ -1867,7 +1928,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
     }
     case 'whoami': {
       const { res, data } = await fetchWhoami().catch((e) => { die(`pidge: whoami failed (network): ${e.message}`, 2); });
-      checkManifestNews(res);
+      await checkManifestNews(res);
       if (res.status !== 200) die(`pidge: whoami failed (${res.status}): ${JSON.stringify(data)}`, 2);
       console.log(JSON.stringify(data, null, 2));
       console.error(`pidge: you are canal "${data.channel && data.channel.name}" · ${data.devices ?? '?'} device(s)`);
@@ -2003,7 +2064,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
       } catch (e) {
         die(`pidge: cancel failed (network): ${e.message}`, 2);
       }
-      checkManifestNews(res);
+      await checkManifestNews(res);
       console.log(raw);
       if (res.status >= 200 && res.status < 300) {
         console.error(`pidge: cancelled ${cid} — nothing will fire`);
@@ -2032,7 +2093,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
       } catch (e) {
         die(`pidge: ack failed (network): ${e.message}`, 2);
       }
-      checkManifestNews(res);
+      await checkManifestNews(res);
       console.log(raw);
       if (!(res.status >= 200 && res.status < 300)) die(`pidge: ack failed (${res.status}): ${raw}`, 2);
       let adata = {};
@@ -2071,7 +2132,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
       } catch (e) {
         die(`pidge: inbox failed (network): ${e.message}`, 2);
       }
-      checkManifestNews(res);
+      await checkManifestNews(res);
       console.log(raw);
       if (!(res.status >= 200 && res.status < 300)) die(`pidge: inbox failed (${res.status})`, 2);
       let data = {};
@@ -2180,7 +2241,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
           draining = true;
           try {
             const res = await fetchT(`${BASE}/api/v1/messages${queueQs}`, { headers });
-            checkManifestNews(res);
+            await checkManifestNews(res);
             if (res.status === 200) {
               health.ok();
               const msgs = (await res.json().catch(() => ({}))).messages || [];
@@ -2239,7 +2300,7 @@ A turn-based agent (Claude Code, anything invoked on demand) stays COMMANDABLE w
           if (waitS > 0) qs.set('wait', String(waitS));
           if (v.all) qs.set('all', 'true');
           const res = await fetchT(`${BASE}/api/v1/messages${qs.size ? `?${qs}` : ''}`, { headers }, (waitS + 10) * 1000);
-          checkManifestNews(res);
+          await checkManifestNews(res);
           if (res.status === 200) {
             health.ok();
             const data = await res.json().catch(() => ({}));

package/package.json

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