@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/docs/features/operations/backend-routing.md

@@ -14,7 +14,6 @@ summary: |
   main backend's session fails over to the fallback's mid-run.
 section: operations
 tags:
-  - core
   - operations
   - backends
   - routing
@@ -25,7 +24,7 @@ ask_examples:
   - How do fallbacks work?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - backend routing
   - BackendRouter
@@ -55,64 +54,66 @@ related:
 
 ## In One Sentence
 
-Every job carries a ProcessKey. The router resolves that key to a
-`(main, fallback)` backend pair plus a tier — and if the main backend
-hits a quota wall or a decisive failure, the dispatcher transitions to
-the fallback mid-run, then DMs you that it happened.
+Every job carries a ProcessKey (a label saying what kind of work it is).
+The router turns that key into a `(main, fallback)` backend pair plus a
+tier — and if the main backend runs out of quota or hits a decisive
+failure, the dispatcher switches to the fallback partway through the run,
+then DMs you that it happened.
 
 ## How It Resolves a Backend
 
-The router never picks a model itself. The dispatcher hands it a
-ProcessKey, and `BackendRouter` resolves the binding in this order:
+The router never picks a model on its own. The dispatcher hands it a
+ProcessKey, and `BackendRouter` works out the binding in this order:
 
-1. Read the `process_backend_config` table for a per-key override
+1. Check the `process_backend_config` table for a per-key override
    (`main_backend` / `main_model` / `fallback_backend` / `fallback_model`).
-2. If no override exists, fall back to the ProcessKey's **default tier**
-   (`lite` → Haiku-class, `medium` → Sonnet-class, `high` → Opus-class)
-   and the seeded backend for that tier.
-3. `dashboard.docs_qa` is **tier-locked to `medium`** — an operator pin
-   can't move it.
+2. If there is no override, use the ProcessKey's **default tier** (a
+   size band: `lite` → Haiku-class, `medium` → Sonnet-class, `high` →
+   Opus-class) and the backend seeded for that tier.
+3. `dashboard.docs_qa` is **tier-locked to `medium`** — pinning it in the
+   dashboard can't move it.
 
 Only one ProcessKey — `delegated_task_heavy` — defaults to the `high`
-tier, and it is opt-in (gated by the `delegatedTaskHeavyEnabled` flag).
-No install-time surface defaults to Opus.
+tier, and it is opt-in (turned on by the `delegatedTaskHeavyEnabled`
+flag). Nothing you get at install time defaults to Opus.
 
 ## What Happens on Failover
 
-The two failover signals are `BackendQuotaError` (the backend hit a
-usage/budget limit) and `BackendDecisiveFailure` (auth failure, model
-unavailable, policy-denied, timeout, or turn-limit). When the main
-backend raises either:
-
-- The router **re-materializes the session workdir** for the fallback
-  backend — writing its instruction file (`AGENTS.md` for Codex,
-  `GEMINI.md` for Gemini, etc.) and skill set into the shared dir. Without
-  this step a Claude → Codex fallover would leave only `CLAUDE.md` and
-  `.claude/skills/`, and the fallback would run blind.
-- The fallback then executes with the same prompt and any
-  per-session tool overrides applied to the main run.
-- On success, you get a **low-priority DM** noting the main backend
-  failed and the fallback served the turn.
+Two signals trigger a failover: `BackendQuotaError` (the backend hit a
+usage or budget limit) and `BackendDecisiveFailure` (an auth failure,
+an unavailable model, a policy-denied request, a timeout, or a
+turn-limit). When the main backend raises either one:
+
+- The router **rebuilds the working directory** for the fallback
+  backend — writing that backend's instruction file (`AGENTS.md` for
+  Codex, `GEMINI.md` for Gemini, and so on) and its skill set into the
+  shared folder. Skip this step and a Claude → Codex failover would find
+  only `CLAUDE.md` and `.claude/skills/`, so the fallback would run
+  blind.
+- The fallback then runs with the same prompt and any per-session tool
+  overrides that applied to the main run.
+- If it succeeds, you get a **low-priority DM** noting that the main
+  backend failed and the fallback served the turn.
 - If the fallback *also* fails, you get a higher-priority notification:
   `Backend execution failed: <key> encountered <kind> on <main>, then
-  <kind> on <fallback>.` This is usually a credentials problem on both
+  <kind> on <fallback>.` This usually means a credentials problem on both
   sides.
 
 ## Where in the Dashboard
 
-- **[Settings → Models](/settings/models)** is the unified surface for
-  picking the main and fallback backend (and tier) per ProcessKey.
+- **[Settings → Models](/settings/models)** is the one place to pick the
+  main and fallback backend (and tier) for each ProcessKey.
 - **[Activity](/activity)** rows show which backend actually served each
-  turn after fallback resolution, so you can see when a fallover fired.
+  turn once fallback was resolved, so you can spot when a failover fired.
 
 ## When Something Goes Wrong
 
 - **A `Backend execution failed` notification** means both the main and
   the fallback rejected the run. Check authentication for both backends
-  first — re-authorize from the dashboard if needed.
-- **A routine ran on the "wrong" backend** is usually a fallover: the
+  first, and re-authorize from the dashboard if needed.
+- **A routine ran on the "wrong" backend** is usually a failover: the
   main backend was over quota, so the fallback served it. The Activity
-  row will confirm which backend ran.
+  row confirms which backend ran.
 
 ## Related
 

package/agent-assets/docs/features/operations/browser-tasks.md

@@ -20,7 +20,6 @@ summary: |
 section: operations
 tags:
   - operations
-  - browser-automation
   - safety
 status: beta
 ask_examples:
@@ -32,7 +31,7 @@ ask_examples:
   - Where do I see the screenshots from a browser task?
 locale: en-US
 created: 2026-06-16
-updated: 2026-06-16
+updated: 2026-07-01
 keywords:
   - browser tasks
   - browser-task
@@ -73,46 +72,49 @@ api_endpoints:
 A **browser task** is an open-ended action you ask the agent to carry
 out on the web — "send a contact form on Amazon's contact-us page",
 "check the price of X", "fill in this signup". Each task runs in a
-sandboxed sub-agent with **one browser tab to itself**, under allowlist
-enforcement, a payment-path block, and a screenshot trace. The
-**Browser Tasks** page (`/browser-tasks`) is the operational surface
-where every run shows up — what is queued, running, waiting on you, or
-finished.
-
-This is different from two neighbouring surfaces:
-
-- **[Browser History](browser-history)** reads your *existing* Chrome
-  passively (research clusters, revisit nudges). It never drives a
-  browser.
-- **[Managed Chromium / B-4](managed-chromium)** is the heavily-gated,
-  default-off *purchase-confirmation* flow. Browser tasks are the
-  general-purpose, non-purchasing actions; a final purchase confirm is
-  the one thing they hand off to the B-4 token primitive.
+*sandboxed sub-agent* (an isolated, throwaway helper the agent spins
+up) that gets **one browser tab to itself**, guarded by an allowlist, a
+payment-path block, and a screenshot trace of every step. The **Browser
+Tasks** page (`/browser-tasks`) is where every run shows up — what is
+queued, running, waiting on you, or finished.
+
+Browser tasks are different from two related features:
+
+- **[Browser History](../integrations/browser-history.md)** only
+  *reads* your existing Chrome history, passively (research clusters,
+  revisit nudges). It never drives a browser.
+- **[Managed Chromium / B-4](managed-chromium.md)** is the
+  heavily-gated, default-off flow for *confirming a purchase*. Browser
+  tasks handle the general-purpose, non-purchasing actions; the one
+  thing they hand off to the B-4 token flow is a final purchase
+  confirmation.
 
 ## Starting a Task
 
-You don't start a task from this page — you ask in **DM** or `/chat`:
+You don't start a task from this page — you ask in a **DM** or in
+`/chat`:
 
 > "Send a contact form on Amazon's contact-us page saying my order
 > #123 never arrived."
 
 The agent creates the task (`POST /api/browser-task`), opens a tab, and
-works the goal step by step. You can also **schedule** one to run later
-(it appears here when it fires). The page itself is a read + monitor
-surface: filter, search, open a run, or cancel it.
+works toward the goal step by step. You can also **schedule** one to
+run later — it shows up here when it fires. The page itself is just for
+watching and managing runs: filter, search, open a run, or cancel it.
 
 ## Reading the Page
 
-- **Tasks awaiting you** — a strip pinned to the top that only appears
+- **Tasks awaiting you** — a strip pinned to the top that appears only
   when one or more tasks are blocked on your input. It links straight
-  to the run that needs you. The same signal drives the nav red-dot and
-  the persistent shell banner, so they stay in lock-step.
-- **Filter chips** — narrow by state (`All`, `Active`, or a specific
-  state) and by **site**. `Active` means any non-terminal task.
-- **Search** — free-text match over the task description.
+  to the run that needs you. The same signal drives the red dot in the
+  nav and the banner across the top of the app, so they always agree.
+- **Filter chips** — narrow the list by state (`All`, `Active`, or one
+  specific state) and by **site**. `Active` means any task that hasn't
+  finished yet.
+- **Search** — free-text match against the task description.
 - **Table** — one row per task: state, description (click to open the
-  run), site, originating channel, created time, and duration. Active
-  rows expose a **Cancel** button.
+  run), site, the channel it came from, created time, and duration.
+  Active rows show a **Cancel** button.
 
 Click any row to open the **run detail** (`/browser-tasks/:id`): the
 step-by-step event log and the **screenshot trace** the sub-agent
@@ -120,8 +122,9 @@ captured along the way.
 
 ## Task States
 
-A task moves through a small state machine. Non-terminal states are
-still in flight; terminal states are done.
+A task moves through a small set of states. Some are *non-terminal*
+(the task is still going); the rest are *terminal* (the task is
+finished and won't change).
 
 | State | Meaning |
 | --- | --- |
@@ -135,50 +138,53 @@ still in flight; terminal states are done.
 | `timeout` | Exceeded its time budget. |
 | `abandoned` | A pending task expired in the queue before it could start (see `browserTaskPendingQueueTimeoutMinutes`). |
 
-When a task is `awaiting_user` or `final_confirm`, **answer in the DM
-the agent sent you** — that is the loop that unblocks it. The dashboard
-strip and banner are just where you notice it.
+When a task is `awaiting_user` or `final_confirm`, **reply in the DM
+the agent sent you** — that reply is what unblocks it. The dashboard
+strip and banner are just where you notice it needs you.
 
 ## Cancelling
 
-Active tasks have a **Cancel** button (and `POST
+Active tasks have a **Cancel** button (which calls `POST
 /api/browser-task/:id/cancel`). Cancelling releases the browser context
-immediately and DMs you a confirmation. Terminal tasks can't be
-cancelled — there is nothing left to stop.
+(the task's tab) right away and DMs you a confirmation. A finished
+(terminal) task can't be cancelled — there is nothing left to stop.
 
 ## Safety Model (why it's safe to let it drive)
 
-Browser tasks inherit the project's structural browser defences — there
-is **no hardcoded category/brand denylist**:
+Browser tasks inherit the project's structural browser defenses. There
+is **no hardcoded category or brand denylist** — the safety is built
+into how a task runs, not a list of banned sites:
 
 1. **One sandboxed tab per task.** Tasks don't share a browser context,
    so one task can't read another's session.
-2. **Allowlist enforcement + hostname denylist.** Navigation is
-   constrained; you manage blocked hostnames via
+2. **Allowlist enforcement plus a hostname denylist.** Where a task may
+   navigate is restricted; you manage the blocked hostnames via
    `browserTaskHostnameDenylist`.
-3. **IP egress layer (not configurable).** Navigations that resolve to
-   private, loopback, link-local, or cloud-metadata addresses are
-   denied at the egress chokepoint — defence-in-depth against SSRF.
+3. **IP egress layer (not configurable).** If a navigation resolves to
+   a private, loopback, link-local, or cloud-metadata address, it is
+   blocked at the network exit point — defense-in-depth against SSRF
+   (server-side request forgery, where a request is tricked into
+   reaching an internal address).
 4. **Payment-path block.** A URL-pattern matcher trips at form-submit
-   time on payment-handoff paths, so a task can't silently push a
+   time on payment-handoff paths, so a task can't quietly push a
    transaction through. An actual purchase requires the separate,
-   default-off [B-4 token flow](managed-chromium).
-5. **Human-in-the-loop gates.** Anything ambiguous or consequential
-   surfaces as `awaiting_user` / `final_confirm` and waits for your DM.
+   default-off [B-4 token flow](managed-chromium.md).
+5. **Human-in-the-loop gates.** Anything ambiguous or high-stakes
+   pauses as `awaiting_user` or `final_confirm` and waits for your DM.
 
-See **[Safety and Execution](../../concepts/safety-and-execution)** and
-the **[Safety Model](../../concepts/safety-model)** for the full
+See **[Safety and Execution](../../concepts/safety-and-execution.md)**
+and the **[Safety Model](../../concepts/safety-model.md)** for the full
 picture.
 
 ## Configuration
 
 These keys live in the editable config (Settings → Infrastructure):
 
-- `browserTaskMaxConcurrent` — how many tasks may run at once; the rest
-  queue (`pending`).
+- `browserTaskMaxConcurrent` — how many tasks may run at the same time;
+  any extras wait in the queue (`pending`).
 - `browserTaskPendingQueueTimeoutMinutes` — how long a `pending` task
-  waits before it is `abandoned`.
-- `browserTaskRespectQuietHours` — when on, tasks defer during your
-  quiet hours rather than running overnight.
-- `browserTaskHostnameDenylist` — hostnames a task may never navigate
-  to (user-managed; there is no shipped default brand/category list).
+  waits in the queue before it is marked `abandoned`.
+- `browserTaskRespectQuietHours` — when on, tasks hold off during your
+  quiet hours instead of running overnight.
+- `browserTaskHostnameDenylist` — hostnames a task may never visit (you
+  manage this list; nothing is blocked here by default).

package/agent-assets/docs/features/operations/cost-tracking.md

@@ -16,7 +16,6 @@ summary: |
   autonomous spend.
 section: operations
 tags:
-  - core
   - cost
   - operations
 status: stable
@@ -27,7 +26,7 @@ ask_examples:
   - What is the difference between the daily and monthly cost cap?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - cost tracking
   - analytics
@@ -97,9 +96,10 @@ Open **Analytics**. It has two tabs:
 - **Metrics** (`/analytics?tab=metrics`) — operational health: activity
   volume, execution breakdown, error rates, notification throughput.
 
-Note on delegated work: only **cross-backend** delegated calls show up as
-separate runs. Same-backend delegated/native calls roll up under the
-parent session's totals.
+Note on delegated work (when a run hands part of its job to a helper
+model): only **cross-backend** delegated calls show up as separate runs.
+Same-backend delegated/native calls roll up under the parent session's
+totals.
 
 ### Sidebar footer (running daily total)
 

package/agent-assets/docs/features/operations/managed-chromium.md

@@ -20,8 +20,6 @@ section: operations
 tags:
   - operations
   - safety
-  - browser-automation
-  - experimental
 status: experimental
 ask_examples:
   - What is B-4?
@@ -31,7 +29,7 @@ ask_examples:
   - How do I block a site from managed Chromium?
 locale: en-US
 created: 2026-05-22
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - managed chromium
   - browser automation
@@ -66,16 +64,18 @@ api_endpoints:
 
 # Managed Chromium (B-4)
 
-B-4 is the experimental purchase-confirmation flow. When you've asked
-the agent to "buy X" or "complete the checkout", and the vendor is on
-your B-4 allowlist, the daemon spawns a managed Chromium profile,
-fills the cart, and pauses for an explicit one-time token from your
-DM before clicking the final confirm. **It is default-off**, gated
-behind every safety check the project ships, and not surfaced in the
-public dashboard until the upstream B-3 surface (browser-history
-research) has been stable for six weeks.
-
-This page is written so it's safe to read whether you've enabled it
+B-4 is the experimental purchase-confirmation flow. When you ask the
+agent to "buy X" or "complete the checkout", and the vendor is on your
+B-4 allowlist (the short list of sites you have explicitly approved),
+the daemon (Aitne's always-on background service) opens a managed
+Chromium profile, fills the cart, and then stops. It waits for a
+one-time token that you send back in a DM (direct message) before it
+clicks the final confirm button. **It is default-off**, sits behind
+every safety check the project ships, and stays hidden in the public
+dashboard until the upstream B-3 surface (browser-history research)
+has run smoothly for six weeks.
+
+This page is written so it's safe to read whether you've turned it on
 or not.
 
 ## What's Actually Gated
@@ -93,16 +93,15 @@ Before B-4 can run, every one of these must be true:
 3. At least one **primary DM channel** is set (Slack / Telegram /
    Discord / WhatsApp). The single-use token is delivered there; the
    dashboard never shows the raw token.
-4. The **site is on your B-4 allowlist**. Per-site enablement happens
-   via `PATCH /api/browser-automation/sites/:siteKey/b4-config`
-   (Approve). Sites not in the allowlist cannot run a B-4 flow even
-   if the master toggle is on.
+4. The **site is on your B-4 allowlist**. You enable each site one at
+   a time via `PATCH /api/browser-automation/sites/:siteKey/b4-config`
+   (Approve). A site that isn't on the allowlist can't run a B-4 flow,
+   even when the master toggle is on.
 5. The **site is signed in** through the B-2.5 per-site sign-in
    flow (`POST /api/browser-automation/sites/:siteKey/connect` →
    sign in by hand in the spawned UI Chromium →
-   `POST .../finalize`). The daemon stores the profile in a
-   restricted directory the absolute-block layer protects from any
-   skill.
+   `POST .../finalize`). The daemon keeps the profile in a locked-down
+   directory that no skill can reach (the absolute-block layer).
 
 ## Structural Defences (no hardcoded category denylist)
 
@@ -117,8 +116,10 @@ category list:
    navigation that resolves to a private (RFC1918), loopback,
    link-local, multicast, cloud-metadata (`169.254.169.254`), or the
    IPv6 equivalents is denied at the egress chokepoint
-   (`shouldDenyEgress` in `egress-denylist.ts`). This is the
-   defence-in-depth against SSRF — it cannot be turned off.
+   (`shouldDenyEgress` in `egress-denylist.ts`). This is the extra
+   layer of defence against SSRF (server-side request forgery, where a
+   request is tricked into reaching an internal address) — it cannot be
+   turned off.
 2. **Payment-path blocker.** A URL-pattern matcher
    (`payment-path-blocker.ts`) trips at form-submit time on
    payment-handoff paths so the agent can't silently push a

package/agent-assets/docs/features/operations/notifications.md

@@ -14,7 +14,6 @@ summary: |
   rate limits gate the flow.
 section: operations
 tags:
-  - core
   - notifications
   - operations
 status: stable
@@ -23,7 +22,7 @@ ask_examples:
   - How do I limit how often it notifies me?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - notification
   - notify
@@ -54,15 +53,16 @@ api_endpoints:
 
 ## In One Sentence
 
-Outbound DMs the agent sends through the paired messaging app, gated
-by quiet hours and rate limits.
+Outbound DMs the agent sends you through your paired messaging app,
+held back by quiet hours and capped by rate limits.
 
 ## What It Does
 
-- Routines, observations, and approvals enqueue notifications.
-- Quiet hours hold notifications until the window ends.
-- Per-hour and per-day rate limits cap the volume.
-- Batching folds multiple small alerts of the same event type into a
+- Routines, observations, and approvals line up notifications to send.
+- Quiet hours (your do-not-disturb window) hold notifications until the
+  window ends.
+- Per-hour and per-day rate limits cap how many you get.
+- Batching folds several small alerts of the same event type into a
   single message.
 
 ## How a Notification Flows
@@ -74,13 +74,13 @@ by quiet hours and rate limits.
 4. It is sent to the operator over `primaryPlatform` (or, when set, the
    exact channels in `defaultNotificationPlatforms`).
 
-Explicit agent notifications (`POST /api/notify`) ride the same gates
-with one difference: inside quiet hours they are **deferred, not
-dropped** — the full message is queued as a scheduled DM that fires
-when the window ends (visible under Schedule), and repeat sends from
-the same agent overnight coalesce into one combined DM. Outside quiet
-hours the per-hour / per-day caps apply; a capped call is rejected
-(`rate_limited`) rather than silently queued, so the agent can adapt.
+Explicit agent notifications (`POST /api/notify`) go through the same
+checks, with one difference: inside quiet hours they are **deferred,
+not dropped** — the full message is queued as a scheduled DM that fires
+when the window ends (visible under Schedule), and repeat sends from the
+same agent overnight merge into one combined DM. Outside quiet hours the
+per-hour / per-day caps apply; a capped call is rejected (`rate_limited`)
+rather than silently queued, so the agent can adapt.
 
 ### Safety categories always get through
 

package/agent-assets/docs/features/operations/quiet-hours.md

@@ -17,7 +17,6 @@ section: operations
 tags:
   - operations
   - notifications
-  - core
 status: stable
 ask_examples:
   - How do I stop notifications at night?
@@ -25,7 +24,7 @@ ask_examples:
   - Will routines still run during quiet hours?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - quiet hours
   - dnd
@@ -57,14 +56,14 @@ alerts still get through.
 
 ## What It Does
 
-Quiet hours only gate *agent-initiated* proactive notifications. During
+Quiet hours only affect *proactive* notifications — the messages the
+agent starts on its own. They do not touch replies you asked for. During
 the window:
 
 - **A normal proactive notification is suppressed.** If nothing of the
-  same event type was sent recently, the message goes straight to the
-  notification path, sees that it is quiet hours, and is logged as
-  `suppressed` — it is **dropped, not held**. You will not receive it
-  later.
+  same event type was sent recently, the message reaches the send step,
+  finds that quiet hours are active, and is logged as `suppressed` — it
+  is **dropped, not held**. You will not receive it later.
 - **An explicit agent notification (`POST /api/notify`) is deferred,
   not dropped.** When an agent session calls the notify endpoint inside
   the window, the full message is queued as a scheduled DM that fires
@@ -76,11 +75,11 @@ the window:
   end (or released immediately when the new window no longer covers
   the current time).
 - **A notification already in a batch queue is deferred, not dropped.**
-  Aitne batches repeat notifications of the same event type within
-  `batchIntervalMinutes`. When a batch is pending and quiet hours are
-  active, the flush is pushed to the wall-clock moment the window ends,
-  so that combined message arrives when you wake instead of being
-  suppressed.
+  Aitne groups repeat notifications into batches (see
+  [Notifications](notifications.md) for how batching works). When a batch
+  is pending and quiet hours are active, its flush is pushed to the
+  wall-clock moment the window ends, so the combined message arrives when
+  you wake instead of being suppressed.
 - **Reactive DMs still respond.** A direct reply to your message
   bypasses quiet hours, rate limits, and batching entirely.
 - **Safety-category alerts still wake you.** Notifications tagged
@@ -111,9 +110,9 @@ the window:
 
 Continuously. Every proactive notification checks `quietHoursStart` and
 `quietHoursEnd` against the current local time (in the configured
-timezone) before sending. The window may wrap midnight — the default
-`22:00` → `08:00` is an overnight shape. Setting start equal to end
-(e.g. `00:00` / `00:00`) disables quiet hours.
+timezone) before sending. The window may cross midnight — the default
+`22:00` → `08:00` is an overnight window. Setting start equal to end
+(e.g. `00:00` / `00:00`) turns quiet hours off.
 
 ## Where in the Dashboard
 

package/agent-assets/docs/features/operations/schedule-approaching.md

@@ -26,7 +26,7 @@ ask_examples:
   - Why didn't I get a reminder before my meeting?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - schedule approaching
   - pre-event reminder
@@ -49,16 +49,17 @@ Pre-event reminders fire 15 minutes before each calendar event.
 
 ## What It Does
 
-- Watches upcoming calendar events and fires a notification ~15
+- Watches upcoming calendar events and sends a notification ~15
   minutes before each one. The lead time is fixed in
-  `imminent-event-scheduler.ts` (not a config key today).
-- Emits one `schedule.approaching` event per item via the EventBus
-  when the event is `≤ 15 minutes` away. The event is handled at the
-  `medium` tier.
-- Deduplicates via the `imminent_event_notifications` table, keyed on
-  the provider's stable event id, so the same event never fires twice
-  across reschedules, restarts, or repeated poll cycles. Rows are
-  pruned after 24 hours.
+  `imminent-event-scheduler.ts` (there is no config key for it today).
+- When an event is `≤ 15 minutes` away, it emits one
+  `schedule.approaching` event per item on the EventBus (the daemon's
+  internal message bus). That event is handled at the `medium` tier.
+- To avoid duplicate reminders, it records each fired event in the
+  `imminent_event_notifications` table, keyed on the provider's stable
+  event id. The same event never fires twice across reschedules,
+  restarts, or repeated poll cycles, and rows are pruned after 24
+  hours.
 
 ## How It Is Triggered
 
@@ -71,10 +72,11 @@ integration mode:
   direct mode and the delegated-sync worker in delegated mode).
 - **`native` mode** — the daemon does not poll, so it reads
   `observations` rows instead. These are posted by the agent's
-  native-mode `routine.fetch_window` pre-pass. Because that pre-pass
-  refreshes on the activity-scan tick (~60-minute cadence), events
-  scheduled with less than ~60 minutes of lead time may miss their
-  reminder. Direct mode (5-minute poll) does not have this limit.
+  native-mode `routine.fetch_window` pre-pass (the pre-run scan that
+  gathers fresh context). Because that pre-pass only refreshes on the
+  activity-scan tick (~60-minute cadence), an event scheduled with
+  less than ~60 minutes of lead time can miss its reminder. Direct
+  mode, which polls every 5 minutes, does not have this limit.
 
 Cross-source dedup is automatic: snapshot and observation rows for the
 same event share the provider's event id, so they collapse into one