@aitne-sh/aitne 0.1.8 → 0.1.9

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

@@ -23,22 +23,31 @@ ask_examples:
   - How do I limit how often it notifies me?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - notification
   - notify
   - quiet hours
   - rate limit
   - notification batch
+  - safety category
 related:
   - features/operations/quiet-hours
   - features/operations/approvals
   - features/messaging/overview
+ui_anchors:
+  - /activity?tab=notifications
+  - /connections/messaging
 config_keys:
   - maxNotificationsPerHour
   - maxNotificationsPerDay
   - batchIntervalMinutes
   - primaryPlatform
+  - defaultNotificationPlatforms
+  - quietHoursStart
+  - quietHoursEnd
+api_endpoints:
+  - POST /api/notify
 ---
 
 # Notifications
@@ -50,26 +59,58 @@ by quiet hours and rate limits.
 
 ## What It Does
 
-- Routines and observations enqueue notifications.
+- 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 into a single message.
+- Batching folds multiple small alerts of the same event type into a
+  single message.
+
+## How a Notification Flows
+
+1. A routine, observation, or approval enqueues a notification.
+2. Quiet hours and rate limits decide whether it is suppressed.
+3. If it survives, batching may hold it briefly to merge with siblings
+   of the same event type; otherwise it is delivered immediately.
+4. It is sent to the operator over `primaryPlatform` (or, when set, the
+   exact channels in `defaultNotificationPlatforms`).
+
+### Safety categories always get through
+
+Notifications tagged `security`, `deadline`, `error`, or `critical`
+**bypass quiet hours, rate limits, and batching** — they are delivered
+immediately on at least one paired channel. So even during a quiet-hours
+window or after the hourly cap is spent, a genuine alert still reaches
+you. Replies to a direct message you sent also bypass these gates.
 
 ## Configuration
 
-| Setting | Default |
-|---|---|
-| `maxNotificationsPerHour` | 3 |
-| `maxNotificationsPerDay` | 12 |
-| `batchIntervalMinutes` | 15 |
-| `primaryPlatform` | first paired |
+`PATCH /api/config` keys (defaults shown):
+
+| Setting | Default | What it controls |
+|---|---|---|
+| `maxNotificationsPerHour` | 3 | Per-hour cap on non-safety notifications. |
+| `maxNotificationsPerDay` | 12 | Per-day cap on non-safety notifications. |
+| `batchIntervalMinutes` | 15 | Window for folding same-type alerts into one message. |
+| `quietHoursStart` | `"22:00"` | Start of the hold window (local time). |
+| `quietHoursEnd` | `"08:00"` | End of the hold window (local time). |
+| `primaryPlatform` | `"slack"` | Default channel notifications are delivered to. |
+| `defaultNotificationPlatforms` | `[]` (empty) | When non-empty, deliver only to these exact channels instead of the default fan-out. |
+
+The agent can also emit a one-off notification via `POST /api/notify`
+(a module capability, not directly agent-forgeable).
 
 ## When Something Goes Wrong
 
-- A notification you expected: check the rate-limit counters and the
-  quiet-hours window.
+- **A notification you expected never arrived:** check the rate-limit
+  counters (`maxNotificationsPerHour` / `maxNotificationsPerDay`) and the
+  quiet-hours window — a non-safety alert can be suppressed by either.
+  Safety-category alerts (`error`/`critical`/`security`/`deadline`) are
+  never suppressed, so a missing one points at delivery/pairing instead.
+- **Too many notifications:** lower the per-hour / per-day caps or widen
+  the batch window so more small alerts collapse into one message.
 
 ## Related
 
 - [Quiet Hours](quiet-hours.md)
 - [Approvals](approvals.md)
+- [Messaging Overview](../messaging/overview.md)

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

@@ -10,9 +10,9 @@ aliases:
   - silent hours
 category: features
 summary: |
-  A nightly silent window during which the agent suppresses
-  notifications. Routines still run, but their output queues until
-  morning instead of waking you.
+  A nightly silent window during which the agent holds back its own
+  proactive notifications. Routines still run, reactive DMs still
+  reply, and safety-category alerts still wake you.
 section: operations
 tags:
   - operations
@@ -25,21 +25,25 @@ ask_examples:
   - Will routines still run during quiet hours?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - quiet hours
   - dnd
   - quietHoursStart
   - quietHoursEnd
+  - batchIntervalMinutes
+  - safety category
 related:
   - features/operations/notifications
   - features/operations/approvals
+  - features/routines/morning-routine
   - concepts/agent-day
 ui_anchors:
   - /settings/schedule
 config_keys:
   - quietHoursStart
   - quietHoursEnd
+  - batchIntervalMinutes
 ---
 
 # Quiet Hours
@@ -47,60 +51,79 @@ config_keys:
 ## In One Sentence
 
 Set a nightly window (default 22:00 → 08:00) during which the agent
-batches notifications instead of pushing them to the messaging app
-in real time.
+holds back its proactive notifications instead of pushing them to your
+messaging app in real time — while reactive replies and safety-category
+alerts still get through.
 
 ## What It Does
 
-During quiet hours:
-
-- **Notifications** are queued, not sent. They flush at the end of the
-  window or get folded into the morning routine's "good morning" message.
-- **Routines** keep running. The morning routine fires at
-  `dayBoundaryHour` (the same time the agent-day rolls over) — even
-  if that falls inside quiet hours, the routine runs and its output
-  is batched until the window ends.
-- **Reactive DMs** still respond. Quiet hours only suppress
-  *agent-initiated* messages.
+Quiet hours only gate *agent-initiated* proactive notifications. 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.
+- **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.
+- **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
+  `security`, `deadline`, `error`, or `critical` (and any `critical`-
+  priority event) bypass the quiet-hours gate. There is no separate
+  "notify anyway" toggle — the category *is* the override.
+- **Routines keep running.** The morning routine fires at
+  `dayBoundaryHour` (the same time the agent-day rolls over). With the
+  defaults — boundary `04`, quiet hours `22:00`→`08:00` — that 04:00 run
+  lands inside quiet hours, so it runs normally but its proactive output
+  is held back or suppressed like any other notification.
 
 ## When It Runs / How It Is Triggered
 
-Continuously. Every notification dispatcher checks `quietHoursStart`
-and `quietHoursEnd` against the current local time before sending.
-The window is allowed to wrap midnight (22:00 → 08:00 is the default
-shape).
-
-## What It Outputs
-
-- An empty notification queue during the window.
-- A consolidated "while you were away" summary at flush time when
-  many notifications batched up.
+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.
 
 ## Where in the Dashboard
 
-- **Settings → Schedule** holds `quietHoursStart` and `quietHoursEnd`.
-  The form refuses windows that overlap the active hours.
+**Settings → Schedule** holds `quietHoursStart` and `quietHoursEnd`,
+shown as a red band on the same 24-hour slider as the hourly-check
+active window. There is **no overlap validation** — quiet hours and the
+active window are allowed to overlap, and the morning routine fires
+regardless of where the bands sit.
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `quietHoursStart` | `"22:00"` | `HH:MM` local time string. |
-| `quietHoursEnd` | `"08:00"` | `HH:MM` local time string. |
-| `batchIntervalMinutes` | `15` | How often the batched flush runs once awake. |
+| `quietHoursStart` | `"22:00"` | `HH:MM` 24-hour local-time string. Set equal to `quietHoursEnd` to disable. |
+| `quietHoursEnd` | `"08:00"` | `HH:MM` 24-hour local-time string. May be earlier than start (overnight window). |
+| `batchIntervalMinutes` | `15` | How often a pending batch flushes. During quiet hours the flush is deferred to the window end. |
 
 ## When Something Goes Wrong
 
-- An **important** notification that you expected to wake you
-  during quiet hours: Aitne does not have a notify-anyway
-  override yet (Approvals are the only thing that bypass quiet hours).
-  If you need real-time night alerts for, say, a critical mail label,
-  the workaround is to disable quiet hours.
-- A notification that fired *after* the window ended but feels stale:
-  check `batchIntervalMinutes` — if you set it long, the flush can
-  lag the window end by several minutes.
+- **You expected an important alert to wake you but nothing came.**
+  Only the safety categories (`security`, `deadline`, `error`,
+  `critical`) bypass quiet hours. A regular proactive notification that
+  isn't already batched is dropped, not delayed. If you need real-time
+  night alerts for, say, a critical mail label, either ensure that path
+  emits a safety-category notification or disable quiet hours.
+- **A notification fired after the window ended but feels stale.**
+  Check `batchIntervalMinutes` — a long interval means a deferred batch
+  flush can lag the window end by several minutes. The deferral targets
+  the exact window-end minute, then the cooldown applies on top.
 
 ## Related
 
 - [Notifications](notifications.md) — the broader notification model.
-- [Approvals](approvals.md) — the only tier that bypasses quiet hours.
+- [Approvals](approvals.md) — the bearer-token approval tier (distinct
+  from the safety-category bypass above).
+- [Morning Routine](../routines/morning-routine.md) — why the 04:00 run
+  lands inside the default quiet window.

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

@@ -8,29 +8,37 @@ aliases:
   - approaching event
 category: features
 summary: |
-  Lightweight pre-event nudges fire when a calendar event is close
-  enough to remind the operator about. The 15-minute lead time is
-  fixed in code today.
+  Lightweight pre-event nudges fire ~15 minutes before each calendar
+  event. The lead time is fixed in code today (no config key). Works
+  in direct, delegated, and native integration modes; only disabled
+  mode suppresses reminders.
 section: operations
 tags:
   - operations
   - calendar
   - notifications
+  - scheduler
+  - observations
 status: stable
 ask_examples:
   - How does the agent remind me about meetings?
   - What is the pre-event reminder lead time?
+  - Why didn't I get a reminder before my meeting?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - schedule approaching
   - pre-event reminder
-  - departure time
-  - ETA reminder
+  - imminent event
+  - meeting reminder
+  - lead time
+process_keys:
+  - schedule.approaching
 related:
   - features/integrations/calendar
   - features/operations/notifications
+  - concepts/observations
 ---
 
 # Schedule Approaching
@@ -41,33 +49,55 @@ Pre-event reminders fire 15 minutes before each calendar event.
 
 ## What It Does
 
-- Watches the calendar event queue.
-- Fires a notification ~15 minutes before each event (fixed in
-  `imminent-event-scheduler.ts`; not currently a config key).
-- Optionally includes the travel-time estimate when the event has
-  a location and the travel-time skill is enabled.
-- Deduplicates via the `imminent_event_notifications` table so the
-  same event never fires twice across reschedules / poll cycles.
+- Watches upcoming calendar events and fires 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.
 
-## When It Runs / How It Is Triggered
+## How It Is Triggered
 
-The scheduler keeps a sorted view of upcoming events from the
-`integration_snapshots` table and emits one `schedule.approaching`
-event per item via the EventBus when the event is ≤ 15 minutes away.
+The scheduler ticks every 60 seconds and reads two sources for events
+in the `[now, now + 15min]` window, depending on the calendar
+integration mode:
+
+- **`direct` and `delegated` modes** — events come from the
+  `integration_snapshots` table (written by the calendar poller in
+  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 hourly-check 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.
+
+Cross-source dedup is automatic: snapshot and observation rows for the
+same event share the provider's event id, so they collapse into one
+`imminent_event_notifications` entry.
 
 ## Where in the Dashboard
 
-- Reminders surface on the connected messaging app and in the
-  Activity feed. There is no dashboard setting for lead time today.
+Reminders surface on the connected messaging app and in the Activity
+feed. There is no dashboard setting for the lead time today.
 
 ## When Something Goes Wrong
 
-- A reminder you expected: confirm the calendar integration is
-  reading the right calendar (some operators have multiple), and
-  that the calendar is running in `direct` mode — in `delegated` /
-  `native` / `disabled` modes the daemon does not emit approaching
-  reminders.
+If a reminder you expected never arrived:
+
+- Confirm the calendar integration is reading the right calendar —
+  some operators connect several.
+- Check the integration mode. Reminders fire in `direct`, `delegated`,
+  and `native` modes; only `disabled` mode suppresses them entirely.
+- In `native` mode, short-notice events (< ~60 min lead time) can be
+  missed because observations refresh on the hourly-check cadence.
 
 ## Related
 
 - [Calendar](../integrations/calendar.md)
+- [Notifications](notifications.md)
+- [Observations](../../concepts/observations.md)

package/agent-assets/docs/features/routines/custom-routines.md

@@ -11,69 +11,104 @@ category: features
 summary: |
   Beyond the built-in morning / evening / weekly / hourly routines,
   the operator can define custom routines that fire on any cron
-  schedule.
+  schedule. Each routine is a Markdown file under
+  policies/routines/custom/, runs under the tier the operator picks,
+  and is bounded by the same safety layers as the built-ins.
 section: routines
 tags:
   - routines
   - autonomous
+  - scheduler
+  - core
   - advanced
 status: stable
 ask_examples:
   - How do I add a custom routine?
   - What can a custom routine do?
   - Can I disable a custom routine?
+  - Which tier does a custom routine run under?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - custom routine
   - routine.custom.<slug>
   - user-defined routine
   - scheduled task
   - recurring schedule
+  - cron routine
 related:
   - guides/add-a-custom-routine
   - concepts/routines
+  - features/memory-files/schedule
+prerequisites:
+  - concepts/routines
 process_keys:
   - routine.custom.<slug>
+context_files:
+  - policies/routines/custom/<slug>.md
+api_endpoints:
+  - PUT /api/context/*
+  - POST /api/recurring-schedules
+ui_anchors:
+  - /settings/routines
+  - /connections/routines
 ---
 
 # Custom Routines
 
 ## In One Sentence
 
-Operator-defined routines fire at any cron schedule, run under the
-backend the operator picks (light / heavy tier), and are bounded by
-the same safety layers as the built-ins.
+Operator-defined routines fire on any cron schedule, run under the
+tier the operator picks (`lite` / `medium` / `high`), and are bounded
+by the same safety layers as the built-ins.
 
 ## What It Does
 
-- Runs a vault-file-defined check list at a cron schedule.
+- Runs a vault-file-defined check list on a cron schedule.
 - Resolves the backend at fire time from the chosen tier (no concrete
   model picker — tier resolution mirrors the built-in routines).
 - Logs its run to Activity exactly like a built-in routine.
 
-## When It Runs / How It Is Triggered
+## When It Runs
 
 The cron expression in the routine's vault file
-`routines/custom/<slug>.md`. The custom-routine scheduler watches the
-file and re-reads the frontmatter on every change.
+`policies/routines/custom/<slug>.md` drives the cadence. The scheduler
+wires one `node-cron` job per enabled routine at startup and fires a
+`routine.custom.<slug>` event on each tick.
+
+It is a **standard 5-field cron expression** (`min hour day-of-month
+month day-of-week`); for example `0 11 * * 2` is every Tuesday at
+11:00 local time, in your configured timezone.
+
+## How Changes Are Picked Up
+
+There is **no filesystem watcher**. The scheduler reloads only when a
+write goes through the context API — a `PUT` / `PATCH` / `DELETE`
+under `policies/routines/custom/` triggers an automatic re-diff of the
+registered jobs against what is on disk, so edits made through the
+dashboard, the API, or the agent take effect without a daemon restart.
+
+A raw file edit that bypasses the API (for example, opening the `.md`
+in an external editor) is *not* picked up until the next API write to
+that directory or a daemon restart. Prefer editing through **Settings
+→ Routines** or the context API.
 
 ## What It Outputs
 
 - Whatever the check list produces — a context-file write, a
-  notification, a no-op.
+  notification, or a no-op.
 
 ## Where in the Dashboard
 
-- **Settings → Routines** is the operator surface for adding,
-  editing, and disabling. (The `/connections/routines` URL is a
-  back-compat alias that redirects here.)
+- **Settings → Routines** (`/settings/routines`) is the operator
+  surface for adding, editing, and disabling. `/connections/routines`
+  is an equivalent page that opens the same surface.
 
 ## Configuration
 
 Each custom routine is a Markdown file under
-`~/.personal-agent/context/routines/custom/<slug>.md` whose
+`~/.personal-agent/context/policies/routines/custom/<slug>.md` whose
 frontmatter carries:
 
 | Field | Type | Notes |
@@ -82,13 +117,46 @@ frontmatter carries:
 | `slug` | string | Kebab-case; matches the file stem and the ProcessKey suffix. |
 | `cron` | string | Standard 5-field cron expression (e.g. `0 11 * * 2`). |
 | `process_key` | `routine.custom.<slug>` | Must match the slug. |
-| `enabled` | boolean | Disable without deleting by setting `false`. |
-| `backend_tier` | `light` \| `heavy` | Drives BackendRouter tier resolution. |
-| `max_budget_usd` | number | Per-execute USD cap (e.g. `0.05`). |
+| `enabled` | boolean (`true` / `false`) | Disable without deleting by setting `false`. |
+| `backend_tier` | `lite` \| `medium` \| `high` | Drives BackendRouter tier resolution. Legacy `light` (→ `medium`) and `heavy` (→ `high`) are still accepted for files written before the rename. |
+| `max_budget_usd` | number | Per-execute USD cap; must be a positive number (e.g. `0.05`). |
+
+Every field above is required; the body must contain a `## Checks`
+section — a routine that is missing any of them is rejected at write
+time with a validation error.
+
+The `## Checks` section is the list the agent runs through on each
+fire. To change a routine, write through the context API (the
+dashboard, the API, or the agent), which triggers an automatic reload
+as described above — no daemon restart is needed.
+
+### Example
+
+A `tuesday-standup-prep` routine at
+`policies/routines/custom/tuesday-standup-prep.md`:
+
+```markdown
+---
+type: rule
+slug: tuesday-standup-prep
+cron: "0 11 * * 2"
+process_key: routine.custom.tuesday-standup-prep
+enabled: true
+backend_tier: medium
+max_budget_usd: 0.10
+---
+
+## Checks
+
+- Summarize commits I pushed since last Tuesday.
+- List any calendar events for the rest of the week that mention
+  "standup" or "review".
+- If there is anything noteworthy, DM me a short prep note.
+```
 
-The body holds the `## Checks` section the agent runs through on each
-fire. Hand-editing the file is fully supported — the watcher picks up
-changes without a daemon restart.
+This fires every Tuesday at 11:00 (your configured timezone), runs
+under the `medium` tier (Sonnet on the Claude backend), and stops
+spending once the run reaches $0.10.
 
 > **Distinct from `recurring_schedules`.** The `recurring_schedules`
 > table powers DM-style scheduled tasks (`agent.task` /