@aitne-sh/aitne 0.1.12 → 0.1.13

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

package/agent-assets/docs/features/routines/activity-scan.md

@@ -20,7 +20,6 @@ tags:
   - autonomous
   - observations
   - polling
-  - activity-scan
 status: stable
 ui_anchors:
   - /agents/activity-scan
@@ -34,7 +33,7 @@ ask_examples:
   - How do I tune the gate's freshness window?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - hourly
   - observations
@@ -70,11 +69,13 @@ config_keys:
 
 # Activity Scan
 
-A medium-tier routine that drains the observations queue every interval
-during active hours and decides whether the accumulated change
-pattern warrants notifying you or appending to `state/today.md`. The
-"decide" step is a four-layer gate designed to keep quiet days quiet
-without missing the moment when something piles up.
+A medium-tier routine that runs every interval during your active
+hours (the daily window when the agent is allowed to work). Each run
+empties the pending observations queue and decides whether the changes
+that piled up are worth notifying you about or just worth logging to
+`state/today.md`. That "decide" step is a four-layer gate, built to
+keep quiet days quiet without missing the moment something actually
+matters.
 
 ## When It Runs
 
@@ -89,7 +90,8 @@ The legacy `activityScan*` config keys are deprecated fallbacks (see
   (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
   self-recovery and the activity scan resumes after the morning
   routine succeeds).
-- **Skips** when another activity scan is in flight (atomic flag).
+- **Skips** when another activity scan is already running (an atomic
+  in-flight flag stops two runs from overlapping).
 - **Skips** when accumulated signal is below the agent's **min
   observations** threshold and the heartbeat window
   (`activityScanHeartbeatHours`) hasn't elapsed.
@@ -119,9 +121,10 @@ Telemetry: `agent_actions.detail.harvest_ran` /
 
 ### Layer 2 — Signal compute
 
-`computeActivityScanSignals` reads the observation table mode-blind —
-it filters by source-prefix sets derived from
-`INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
+`computeActivityScanSignals` reads the observation table mode-blind
+(it does not care which integration mode wrote a row) — it filters by
+source-prefix sets derived from `INTEGRATION_DESCRIPTORS`, never by
+`actor`. Signal categories
 include unread-mail / event-change / repo-change / browser-history
 clusters; each category produces a (count, last-seen, summary)
 tuple. The pre-pass freshness gate from Layer 1 is what guarantees

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

@@ -22,7 +22,6 @@ tags:
   - agents
   - autonomous
   - scheduler
-  - advanced
 status: deprecated
 ask_examples:
   - What happened to my custom routines?
@@ -31,7 +30,7 @@ ask_examples:
   - How do I create a recurring task now?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - custom routine
   - routine.custom.<slug>
@@ -73,19 +72,21 @@ once, at the first daemon start after the upgrade.
 - Recurring work you define is now an **Agent**: a
   `policies/agents/<slug>/agent.md` file that appears on the
   **Agents** page (`/agents`) with its schedule, an enable toggle, run
-  metrics, execution history, and a **Run now** button — surfaces
+  metrics, execution history, and a **Run now** button — features
   custom routines never had. See
   [Create a Recurring Agent](../../guides/add-a-custom-routine.md).
 
 ## The One-Time Migration
 
-At the first daemon start after the upgrade — and only once, guarded
-by a persisted flag — every file under `policies/routines/custom/` is
+The first time the daemon (Aitne's background service) starts after
+the upgrade — and only that once, guarded by a saved flag so it can
+never run twice — every file under `policies/routines/custom/` is
 examined:
 
 - A **valid routine becomes a user Agent** at
   `policies/agents/<slug>/agent.md` carrying over:
-  - the same **cron expression** (pinned to your configured timezone),
+  - the same **cron expression** (the schedule rule, pinned to your
+    configured timezone),
   - the same **model tier** (`backend_tier` → the Agent's tier),
   - the same **per-run budget** (`max_budget_usd`),
   - the same **enabled state** — a disabled routine migrates disabled.
@@ -95,7 +96,8 @@ examined:
   it came from (`Migrated from custom routine "<slug>".`).
 - The **source file is never deleted.** It is rewritten in place with
   `enabled: false` and a `migrated_to_agent: <slug>` marker in its
-  frontmatter, so it is visibly inert while your content is preserved.
+  frontmatter, so you can plainly see it no longer runs while your
+  original content is preserved.
 
 ### Collisions and invalid files
 

package/agent-assets/docs/features/routines/evening-review.md

@@ -17,8 +17,6 @@ section: routines
 tags:
   - routines
   - autonomous
-  - daily
-  - core
 status: stable
 ask_examples:
   - When does the evening review run?
@@ -27,7 +25,7 @@ ask_examples:
   - How do I disable the evening review?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - evening review
   - retro
@@ -89,10 +87,11 @@ rather than producing a chatty end-of-day report.
 
 ## When It Runs / How It Is Triggered
 
-Every day at **18:00 local time**, exactly once. The cron expression
-(`0 18 * * *`) is fixed in `packages/daemon/src/core/scheduler.ts`; the
-fire time is not operator-configurable. Like every autonomous cron, the
-run is skipped while the agent is paused (`!stop`) or setup is incomplete.
+Every day at **18:00 local time**, exactly once. The schedule — a cron
+expression (`0 18 * * *`, the standard five-field way to write "18:00 every
+day") — is fixed in `packages/daemon/src/core/scheduler.ts`, so you can't
+change the fire time. Like every autonomous routine, the run is skipped
+while the agent is paused (`!stop`) or setup is not finished.
 
 ## What It Outputs
 

package/agent-assets/docs/features/routines/morning-routine.md

@@ -16,8 +16,7 @@ section: routines
 tags:
   - routines
   - autonomous
-  - daily
-  - core
+  - scheduler
 status: stable
 ask_examples:
   - When does morning routine run?
@@ -26,7 +25,7 @@ ask_examples:
   - What model does morning routine use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - morning
   - day plan
@@ -63,9 +62,10 @@ context_files:
 
 ## In One Sentence
 
-Once per agent day, at `dayBoundaryHour` local time, Aitne
-rebuilds `state/today.md` and the day's schedule from your calendar, mail,
-roadmap, and recent observations.
+Once per agent day (the daily window that starts when "today" rolls
+over), at `dayBoundaryHour` local time, Aitne rebuilds `state/today.md`
+and the day's schedule from your calendar, mail, roadmap, and recent
+observations.
 
 ## What It Does
 
@@ -74,16 +74,17 @@ It runs as a **two-stage pipeline**, with both stages dispatched in
 parallel:
 
 - **Stage A** (`routine.morning_routine_today`, medium tier) rebuilds
-  `state/today.md`, walks the roadmap, fans out the day's schedule, and
-  self-reports structured metadata.
-- **Stage B** (`routine.morning_routine_journal`, lite tier) authors
+  `state/today.md`, walks the roadmap, fans out the day's schedule (queues
+  each of today's scheduled tasks), and reports structured metadata about
+  the run.
+- **Stage B** (`routine.morning_routine_journal`, lite tier) writes
   yesterday's daily journal at `journal/daily/<yesterday>.md` from a
-  daemon-prepared skeleton, then drops the run's audit-trail paragraph
-  into `journal/agent.md`.
+  daemon-prepared skeleton, then appends the run's audit-trail paragraph
+  to `journal/agent.md`.
 
-Every downstream routine for the next 24 hours reads Stage A's output,
-so a bad morning briefing degrades the entire day — hence the
-medium-tier ceiling on Stage A even after the split.
+Every routine that runs over the next 24 hours reads Stage A's output, so
+a bad morning briefing drags down the whole day. That is why Stage A stays
+capped at the medium tier even after the split.
 
 Within Stage A, the work proceeds in this order:
 
@@ -103,12 +104,12 @@ so a post-midnight install does not run two morning routines back-to-back.
 There is no separate `morningRoutineHour` — the morning routine and the
 agent-day rollover are the same instant.
 
-There is no separate "initial" process key. The first morning after
-setup is detected inline by Stage A from the absence of `state/yesterday.md`;
-the daemon injects a `<roadmap_skeleton>` block carrying the pre-aggregated
-Annual Goals / Quarterly Focus / Preparation Timeline facts so Stage A
-can populate the wizard's placeholder roadmap on medium tier instead of
-paying for a one-shot high-tier session. (The dedicated
+There is no separate "initial" process key. Stage A detects the first
+morning after setup on its own, from the missing `state/yesterday.md` file.
+The daemon then injects a `<roadmap_skeleton>` block carrying the
+pre-aggregated Annual Goals / Quarterly Focus / Preparation Timeline facts,
+so Stage A can fill in the wizard's placeholder roadmap on the medium tier
+instead of paying for a one-shot high-tier session. (The dedicated
 `routine.morning_routine_initial` process key — along with its high-tier
 seed — was retired in Phase 7, 2026-05-16; the first-run branch now flows
 through the parent `routine.morning_routine` envelope.)
@@ -135,7 +136,7 @@ through the parent `routine.morning_routine` envelope.)
 | `dayBoundaryHour` | `4` | Both the agent-day boundary and the morning-routine fire time. See [Agent Day](../../concepts/agent-day.md). |
 | Stage A tier (`routine.morning_routine_today`) | medium (Sonnet 5) | Synthesises `state/today.md` + the day's roadmap fan-out. Adjustable per-row in Settings → Models. |
 | Stage B tier (`routine.morning_routine_journal`) | lite (Haiku 4.5) | Authors `journal/daily/<date>.md` and the `journal/agent.md` audit paragraph. |
-| Stage A max turns / budget | 50 turns / $1.50 | Per-execute envelope for `routine.morning_routine_today`. Adjustable in Settings → Models. |
+| Stage A max turns / budget | 50 turns / $2.00 | Per-execute envelope for `routine.morning_routine_today`. Adjustable in Settings → Models. |
 | Stage B max turns / budget | 20 turns / $0.30 | Per-execute envelope for `routine.morning_routine_journal`. |
 
 The parent `routine.morning_routine` key keeps its own envelope (50 turns / $2.00) for the pipeline entry point. Codex and Gemini backends scale the dollar caps by a per-tier factor (lite ×2.5, medium ×1.5); the router enforces the cap before token costs accumulate.