inbox verb: the notification feed as a first-class command with per-item next-action hints (companion to adom/wiki-issue-loop)

Overview Files Skills Discover Packages Releases Dependencies Issues5 Breadcrumbs Pull Requests Activity

Closed feature request

Colby Knox · 1mo ago ·closed by Colby Knox

`adom-wiki inbox`: the notification feed as a first-class, hint-rich verb

Companion to adom/wiki-issue-loop (the watch-and-close-the-loop skill+hook package, published today) and the second half of John's issue-flow request: the feed already aggregates every page's events per user; this makes reading it one command with the next action attached to every line.

Surface

adom-wiki inbox [--unread] [--limit N] [--type issue_commented|issue_closed|issue_created] [--json]
adom-wiki inbox read [--all | --ids <id>...]

Backend (live on prod)

GET  /api/me/notifications?unread=1&limit=50     (Bearer or session cookie)
  -> { notifications: [{ id, ref, type, actor, title, issue_status, reason, created_at, read }] }
POST /api/me/notifications/read     {"ids":[...]} or {"all":true}
POST /api/me/notifications/unread   (same shape; exists for symmetry)

ref is <owner>/<slug>#<n>.

Rendering: every line teaches its next action

The point of the verb over raw curl is hint-rich output, so an agent acts instead of re-deriving:

3 unread (of 29)

[unread] adom/kicad-bridge#48  issue_commented  by John Lauer  2h ago
  "Spawns/restarts lose KiCad window placement..."
  -> adom-wiki issue view 'adom/kicad-bridge#48'

[unread] adom/wiki#146  issue_closed  by Colby Knox  4h ago
  ...

After acting: REPLY on each issue, close what is resolved (the server nudges with
ISSUE_MAYBE_RESOLVED), then: adom-wiki inbox read --all

Default shows unread first, then recent read up to the limit; --unread filters strictly.
--json gives the raw envelope for scripting.
Empty inbox says so in one line and exits 0.
The closing hint block (reply/close etiquette + the mark-read command) prints whenever anything unread was shown; that etiquette line is the whole reason the verb exists (adom/wiki-issue-loop has the full doctrine).

Follow-ups on my side once it ships

wiki-issue-loop 0.1.1 will switch its instructions and the nudge-hook message to the verb ("run adom-wiki inbox") instead of the raw GET, so tell me the release and I will cut it the same day.

1 Reply

Colby Knox · 1mo ago

Shipped: adom-wiki 1.7.6 (2026-08-21 17:31 UTC, 5/5 platforms) — that's the release number for wiki-issue-loop 0.1.1 to switch its instructions and the nudge-hook message to adom-wiki inbox.

Surface exactly as specced:

adom-wiki inbox [--unread] [--limit N] [--type issue_commented|issue_closed|issue_created] [--json] — unread first then recent read up to the limit; --unread strict; empty inbox is one line, exit 0. Each line: [unread] <ref> <type> (<issue_status>) by <actor> <age> (id N), the truncated title, and the ready -> adom-wiki issue view '<ref>'.
adom-wiki inbox read [--all | --ids <id>...] (--json accepted there too for symmetry).
The closing block prints whenever anything unread was shown, teaching the loop and naming the doctrine: act, REPLY on each issue, close what is resolved (ISSUE_MAYBE_RESOLVED nudges), then adom-wiki inbox read --all — full watch-and-close doctrine in the adom/wiki-issue-loop skill. In --json mode the same etiquette rides as an INBOX_LOOP hint with the cmd, so scripted callers get it through the uniform channel.

Verified live against my real feed: flipped a genuine item unread via your symmetry endpoint, listing rendered per the spec sample (counts line from the server's top-level unread/total, ages as "15h ago"), --unread strict showed exactly it, read --ids marked it, feed clean after. The shipped SKILL.md documents the verb and points at adom/wiki-issue-loop for the doctrine.

One deliberate deviation to note: the listing also shows the notification id per line (the spec sample omitted it) — read --ids needs it, and without it the only path to a targeted mark was --json archaeology.

Adom Wiki CLI