Empty-inbox discovery tip

What it is

A one-time, gentle card in the Omniscio Inbox that tells you your inbox can be cleared by archiving the items you're done with. It appears at most once, ever — the first time your inbox has genuinely piled up and you haven't yet started using archiving. It carries an "Archive this tip" button that archives the card itself, so you see the gesture happen on the spot. It never archives anything else: the sessions it counted are still waiting on you, so clearing those stays your call.

The Inbox fills with sessions that need your attention (Needs You / Error / Stalled), plus alerts and approvals. Archiving an item files it into the Archived view (still searchable) and removes it from the Inbox, so archiving is how you take the Inbox back toward zero. Many people don't realize this, so their Inbox grows without bound — this tip surfaces the capability at the moment it is useful, then gets out of the way.

Where to find it

It arrives in the Inbox, as a card, at most once ever — there is nothing to switch on. It only appears once your Inbox has piled up and you have not yet started archiving.

How it behaves

When it appears

All of these must be true (checked once, at app startup):

• Your visible Inbox has ~15 or more items waiting for attention — the same count the app badge shows, so snoozed, hidden, and behind-the-scenes items don't count.
• You have never archived a session (zero archived items) — the signal that you may not know archiving exists.
• You haven't already seen this tip (it shows at most once, ever).
• Tips & Guidance is on (Settings → Notifications).

If you already archive things, or your inbox is small, or you've seen it before, it never appears. Because it is gated on "zero archived items," the moment you archive anything it can never fire again.

How to clear your inbox (what the tip points you to)

• Press Archive this tip on the card itself — that is the same gesture, performed once so you can see it.
• Open a session you're finished with and archive it, or select several and archive them together.
• Archived sessions stay searchable in the Archived view, so nothing is lost.
• Your Inbox drops back toward zero. See archive-a-session.md for the full archiving mechanic.

Turning it off

There is no dedicated toggle — it is a one-time card that self-limits to a single appearance, so there is nothing to keep switching off. To suppress it, turn off Tips & Guidance in Settings → Notifications. The Allow agents to raise inbox alerts switch (Settings → Features) does not affect it. Developers can also set the AMC_DISABLE_EMPTY_INBOX_TIP environment kill switch.

For agents

How it works (for agents)

maybeSurfaceEmptyInboxTip (src/main/services/app/empty-inbox-tip-alert.ts) runs once from the startup-task registry. It gates, in order, on the AMC_DISABLE_EMPTY_INBOX_TIP env kill switch → Tips & Guidance → the one-shot emptyInboxTipSeen setting → the visible attention count (countSessionsByStatus([...ATTENTION_STATUSES], true, { excludeHiddenTags: true }), the SAME count the OS badge uses, so it matches what the user sees) reaching EMPTY_INBOX_TIP_MIN_ATTENTION (15) → countArchivedSessions() === 0 (the archive-usage signal; no new counter or migration). On fire it raises ONE deduped inbox card via the canonical one-call raiseAgentAlert helper (which absorbs the dedup push and its own non-fatal catch) and sets emptyInboxTipSeen (the dedupKey is the idempotency backstop). The card has exactly one button, Archive this tip, which archives the card itself and nothing else. Its copy explains the archive gesture and stops there — it does NOT close with "This tip appears only once.", in any of the 35 shipped languages (a tip teaches the thing; it does not narrate its own lifecycle). The copy is pinned by tests/unit/services/empty-inbox-tip-alert.test.ts and the all-languages rule by tests/unit/lint/tip-copy-and-action.test.ts. Any error is swallowed; it can never break startup. Full invariants: .claude/memory/contracts/empty-inbox-tip-contract.md.

Related

• archive-a-session.md — the archiving mechanic this tip points you to.
• snooze-an-inbox-item.md — the other way to take a row out of the Inbox (temporarily).
• inbox-overview.md — how the Inbox groups and counts items.