@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/docs/features/integrations/browser-history.md

@@ -20,7 +20,6 @@ section: integrations
 tags:
   - integrations
   - observations
-  - browser-history
   - polling
   - autonomous
 status: stable
@@ -32,7 +31,7 @@ ask_examples:
   - How do I opt out of browser history?
 locale: en-US
 created: 2026-05-22
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - browser history
   - browser history poller
@@ -75,38 +74,41 @@ api_endpoints:
 
 # Browser History
 
-Aitne can read the SQLite history databases that Chrome, Chromium,
-Edge, Brave, Comet, and Atlas already maintain on disk, classify visits
-into categories, and use the result to notice what you've been
-researching, what you've been refreshing, and what comparison-shopping
-windows you're in. Everything stays local — no URLs, titles, or
-clicks leave the daemon.
+Every browser keeps a local history file (a small SQLite database) of
+the pages you visit. Aitne can read that file for Chrome, Chromium,
+Edge, Brave, Comet, and Atlas, sort each visit into a category, and use
+the result to notice what you've been researching, what pages you keep
+refreshing, and when you're comparison-shopping. Everything stays on
+your machine — no URLs, titles, or clicks leave the daemon.
 
 ## What It Does
 
-- **Reads visits** from the browser's own history DB on a 30-min
-  cadence (per browser, per profile) and inserts them into the
+- **Reads visits** from the browser's own history file every 30
+  minutes (per browser, per profile) and inserts them into the
   daemon's `browser_visits` table.
 - **Counts reloads** per `<domain>/<first-path>` into
-  `browser_reload_signals`. Surfaced via [`!checks`](../messaging/bang-commands.md)
-  for the agent-day and via the weekly review's "this week you
-  checked" block.
-- **Derives research clusters** when a topic crosses meaningful-visits
-  / foreground-time / distinct-domain thresholds. Clusters live in
-  `browser_research_clusters` with a slug, display name, journal at
-  `context/research/<slug>.md`, and a status (`active | dormant |
-  muted | concluded`).
-- **Offers engagement DMs** via the Two-Option Offer pattern when a
-  cluster qualifies: pick "research dive" (parallel web research +
-  summary) or "wiki summary" (Obsidian / Notion / local context).
-  Accept paths run through `routine.research_dispatch` /
-  `routine.research_wiki_summary`; decline silences offers for 14
+  `browser_reload_signals` — that is, how often you reopen the same
+  page. These show up via [`!checks`](../messaging/bang-commands.md)
+  for the current agent-day (Aitne's version of "today", which rolls
+  over in the early morning rather than at midnight) and in the weekly
+  review's "this week you checked" block.
+- **Derives research clusters** when a topic passes the thresholds for
+  meaningful visits, foreground reading time, and distinct domains. A
+  cluster is a group of related pages Aitne thinks you're actively
+  researching. Clusters live in `browser_research_clusters` with a
+  slug, display name, journal at `context/research/<slug>.md`, and a
+  status (`active | dormant | muted | concluded`).
+- **Offers a direct message** when a cluster qualifies, using the
+  Two-Option Offer pattern: pick "research dive" (parallel web research
+  plus a summary) or "wiki summary" (into Obsidian / Notion / local
+  context). Accepting runs `routine.research_dispatch` or
+  `routine.research_wiki_summary`; declining silences offers for 14
   days; mute / unmute / rename / conclude via [`!research`](../messaging/bang-commands.md).
-- **Detects shopping comparison windows** — 90-min sliding windows
-  containing ≥3 distinct ASINs surface as comparison sessions the
-  agent can summarise.
+- **Detects comparison-shopping sessions** — a 90-min sliding window
+  holding ≥3 distinct ASINs (Amazon product IDs) surfaces as a session
+  the agent can summarize for you.
 - **Powers the pre-morning digest** — yesterday's reading and reload
-  patterns feed the digest the morning routine reads.
+  patterns feed the digest that the morning routine reads.
 
 ## Privacy and Consent
 
@@ -116,9 +118,9 @@ clicks leave the daemon.
   (`/settings/integrations/browser-history`) page. The integration only
   supports `direct` (the daemon poller) or `disabled` — there is no
   delegated or native mode.
-- **Local-only.** No request leaves the daemon. The browser's
-  history file is opened read-only; the daemon never reaches into
-  cookies, login sessions, or profile dirs other than the history DB.
+- **Local-only.** No request leaves the daemon. The history file is
+  opened read-only, and the daemon never touches cookies, login
+  sessions, or any profile file other than that history database.
 - **Per-browser opt-in.** `browserHistoryBrowserOverrides` lets you
   force each detected browser on or off independently
   (`auto` / `forced-on` / `forced-off`).
@@ -134,17 +136,20 @@ clicks leave the daemon.
 
 ## How Clusters Qualify
 
-A research cluster qualifies when the combination of meaningful visits,
-foreground time, and distinct domains crosses the thresholds in
-`DEFAULT_OFFER_THRESHOLDS` (fixed defaults — `browserHistoryLifecycle`
-tunes the poller's check cadence, not these thresholds).
-On each tick the poller evaluates the offer triggers per active cluster
-(`evaluateOfferTriggers`) — this is where the 14-day, per-slug offer
-re-fire window lives — and the **offer rate-limit gate**
-(`gateOfferRateLimit`: daily offer cap, minimum gap between offers,
-quiet hours, and a 30-day decline backoff) must also approve before a
-Two-Option Offer DM is composed by the `routine.research_offer_dm`
-process key.
+A cluster qualifies once its meaningful visits, foreground time, and
+distinct-domain counts all cross the thresholds in
+`DEFAULT_OFFER_THRESHOLDS`. Those thresholds are fixed defaults;
+`browserHistoryLifecycle` tunes how often the poller checks, not the
+thresholds themselves.
+
+Qualifying does not guarantee a message. On each tick the poller runs
+the offer triggers for every active cluster (`evaluateOfferTriggers`),
+which hold the 14-day, per-slug window before the same cluster can be
+offered again. The **offer rate-limit gate** (`gateOfferRateLimit`) must
+then approve too — it enforces a daily offer cap, a minimum gap between
+offers, quiet hours, and a 30-day backoff after a decline. Only then
+does the `routine.research_offer_dm` process key compose the Two-Option
+Offer DM.
 
 Accepting either path clears every pending-offer row for that slug, so a
 later tick cannot re-offer the same cluster.
@@ -179,15 +184,15 @@ later tick cannot re-offer the same cluster.
 
 - **The settings page shows no browsers.** Open
   `/settings/integrations/browser-history` and run `aitne doctor` — the
-  platform detector might be failing to resolve the user's profile dir.
-  The daemon log line will name the candidate paths it tried.
+  detector may be unable to locate your browser's profile folder. The
+  daemon log line lists the candidate paths it tried.
 - **A cluster keeps re-offering.** Check the `lastResearchOfferAt` /
-  `lastWikiOfferAt` columns; the trigger evaluator uses those for the
-  14-day re-fire window (the rate-limit gate also reads them for its
+  `lastWikiOfferAt` columns; the trigger evaluator uses them for the
+  14-day re-fire window (and the rate-limit gate reads them for its
   30-day decline backoff). `!research decline <slug>` stamps both
   fields.
-- **`!checks` is empty.** That's the common case for a quiet day —
-  the reload signals are gated to the agent-day, not UTC.
+- **`!checks` is empty.** That's normal for a quiet day — the reload
+  signals are counted per agent-day, not per UTC day.
 
 ## Related
 

package/agent-assets/docs/features/integrations/calendar.md

@@ -19,7 +19,6 @@ section: integrations
 tags:
   - integrations
   - calendar
-  - core
   - observations
   - polling
 status: stable
@@ -33,7 +32,7 @@ ask_examples:
   - Which model handles detected calendar changes?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - calendar
   - google calendar
@@ -77,10 +76,11 @@ around them and DM you ahead of meetings that matter.
 - **Polls** Google Calendar on `calendarPollIntervalSeconds`; Outlook
   and Apple calendars are read on demand rather than polled.
 - **Records observations** when events change (add / move / remove),
-  consumed by the activity scan.
+  which the activity scan then reads.
 - **Surfaces today's events** to the morning routine so they land in
   `state/today.md` and the day's schedule file.
-- **Reads** events on demand for reactive turns ("am I free at 3?").
+- **Reads** events on demand when you ask a live question, such as
+  "am I free at 3?".
 
 The agent can create, move, or delete events when the operator asks
 (`POST`/`PATCH`/`DELETE /api/calendar/events`, all Autonomous-tier — no
@@ -108,9 +108,9 @@ an explicit request.
 ## Calendar Event Model
 
 The Calendar Event Model picker chooses the backend and model that
-runs when the **daemon-side poller detects a calendar change**. It binds
-the `calendar.change` ProcessKey. The poller's change detection reacts
-in two situations:
+runs when the **daemon-side poller detects a calendar change**. It is
+bound to the `calendar.change` ProcessKey (the internal name for this
+change-handling job). The poller reacts to a change in two situations:
 
 - An event was added, moved, or deleted between polls (recorded as a
   change observation; the activity scan picks it up).

package/agent-assets/docs/features/integrations/git.md

@@ -26,7 +26,7 @@ ask_examples:
   - How often does the daemon poll my repos?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - git
   - commit
@@ -53,31 +53,33 @@ api_endpoints:
 
 # Git
 
-Add local git repositories to a watched set; the daemon polls them
-and the activity scan decides whether the recent activity is worth
-flagging.
+Add local git repositories to a watched set. The daemon checks them
+on a schedule (it polls them), and the activity scan decides whether
+the recent activity is worth flagging.
 
 ## What It Does
 
-- **Polls** each watched repo every `gitPollIntervalSeconds`.
-- **Records observations** when new commits land between polls. The
-  commit author is included so agent-originated commits do not
-  re-surface to the agent (defended via `AgentWriteTracker`).
+- **Checks (polls)** each watched repo every `gitPollIntervalSeconds`
+  seconds.
+- **Records an observation** when new commits land between two checks.
+  It notes who authored each commit, so commits the agent made itself
+  are not shown back to it (enforced by `AgentWriteTracker`).
 - **Surfaces patterns**, not individual commits — three small commits
-  in an hour will not page you.
+  in an hour will not each trigger a notification.
 
 The agent never pushes, never amends, never force-resets. Read-only
 by design.
 
 ## When It Runs / How It Is Triggered
 
-- The poller is continuous.
-- The activity scan consumes the accumulated observations.
+- The poller runs continuously in the background.
+- The activity scan reads the observations it has collected.
 
 ## What It Outputs
 
-- An `observation` row per detected change set.
-- A summary in the activity scan's output when observations qualified.
+- One `observation` row for each detected set of changes.
+- A summary in the activity scan's output when those observations are
+  worth reporting.
 
 ## Where in the Dashboard
 

package/agent-assets/docs/features/integrations/github.md

@@ -29,7 +29,7 @@ ask_examples:
   - Where do I add a GitHub repo to watch?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - github
   - issue
@@ -61,14 +61,16 @@ context_files:
 
 # GitHub
 
-The daemon polls GitHub via the local `gh` CLI: review requests, CI
-failures on the default branch, security alerts, and assignments
-become DMs; everything else is recorded for the activity scan.
+The daemon polls GitHub through the local `gh` CLI. Four kinds of
+signal turn into a direct message (DM): review requests, CI failures
+on the default branch, security alerts, and assignments. Everything
+else is recorded for the activity scan instead of pinging you.
 
 ## What It Does
 
 - **Polls Notifications** every `githubPollIntervalSeconds` (default
-  1800s / 30 min) using ETag caching — 304 responses cost no
+  1800s / 30 min) using ETag caching, so when nothing has changed
+  GitHub returns a 304 ("not modified") and that poll costs no
   rate-limit quota.
 - **Polls workflow_runs** per watched GitHub repository, filtered by
   `status=failure`. Each repo's GitHub side comes from a unified
@@ -84,8 +86,8 @@ The agent never auto-comments, auto-merges, or pushes.
 ## High-priority events
 
 The agent will DM the user (priority `high`; during quiet hours the DM
-is deferred until they end rather than dropped — only `critical`
-safety messages break through) on:
+waits until quiet hours end rather than being dropped — only
+`critical` safety messages break through) on:
 
 - A teammate or bot **requested your review** on a PR — only when it
   looks time-sensitive (release-blocker keywords in the title, or the
@@ -149,9 +151,9 @@ Watched repos are no longer config keys. The old `gitRepos` /
 cutover — repos now live in the `repositories` table and are managed on
 **Connections → Repositories**. Per-repo polling cadence is set on
 **My Life → Git** and overrides the global interval for that repo's
-workflow-runs poll. The global interval is the floor — a per-repo
-cadence longer than it slows that repo down, while a shorter one
-still polls at the global tick.
+workflow-runs poll. The global interval is the floor: a per-repo
+cadence longer than the global one slows that repo down, but a shorter
+one still only polls at the global tick.
 
 ## When Something Goes Wrong
 

package/agent-assets/docs/features/integrations/mail.md

@@ -19,7 +19,6 @@ section: integrations
 tags:
   - integrations
   - mail
-  - core
 status: stable
 ask_examples:
   - How do I connect my Gmail to the agent?
@@ -27,7 +26,7 @@ ask_examples:
   - How do I add a second mail account?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - mail
   - gmail
@@ -60,46 +59,46 @@ context_files:
 
 # Mail
 
-Connect one or more mailboxes (Gmail, Outlook, Yahoo, or iCloud) and
-Aitne polls them, classifies incoming threads, and
-lets the agent search / label / read via the `mail` skill. Search is
-local — backed by SQLite FTS5 — so the agent doesn't need to round-trip
-the provider for every query.
+Connect one or more mailboxes (Gmail, Outlook, Yahoo, or iCloud). Aitne
+then polls them, sorts incoming threads, and lets the agent search,
+label, and read your mail through the `mail` skill. Search runs locally,
+backed by a SQLite full-text index (FTS5), so the agent doesn't have to
+call the provider every time you ask about your inbox.
 
 ## What It Does
 
-- **Read & search** existing threads (FTS5-backed local index).
-- **Classify** incoming messages — is it a travel booking, a receipt
-  attachment, a Kindle notebook export.
-- **Label** threads so the operator and the agent agree on triage state.
-- **Surface** the small set of mail items in the morning routine that
-  actually need owner action.
+- **Read & search** existing threads (from the local FTS5 index).
+- **Classify** incoming messages — for example, a travel booking, a
+  receipt attachment, or a Kindle notebook export.
+- **Label** threads so you and the agent agree on where each one stands.
+- **Surface** the few mail items in the morning routine that actually
+  need your attention.
 
-The agent **prefers drafts** over sending. By convention it creates a
-draft (`POST /mail/:account/drafts`) and lets you review and hit send
+The agent **prefers drafts** over sending. By default it writes a draft
+(`POST /mail/:account/drafts`) and leaves it for you to review and send
 yourself. Direct send (`POST /mail/:account/messages/send`) is *not*
-blocked — it is classified as an autonomous action, so the daemon does
-not DM you for approval first. The agent only sends directly when it
-judges you'd clearly want it to, and it tells you afterward; during the
-activity scan the `mail` skill is hard read-only (no sending, drafting,
-labeling, or filing).
+blocked — it counts as an autonomous action, so the daemon does not DM
+you for approval first. The agent only sends on its own when it's clear
+you'd want it to, and it tells you afterward. During the activity scan
+the `mail` skill is strictly read-only: no sending, drafting, labeling,
+or filing.
 
 ## When It Runs / How It Is Triggered
 
-- In `direct` mode a poller pulls new messages on a cadence. Gmail uses
-  `gmailPollIntervalSeconds` (default 600); all other accounts (Outlook,
-  Yahoo, iCloud) use `mailPollIntervalSeconds` (default 180).
-  The Gmail cadence is adjustable under **Settings → Infrastructure**.
-- The morning routine reads the labeled queue and decides which need
-  surfacing.
-- Reactive turns (you DM "what's in my mail?") use the `mail` skill on
-  demand.
+- In `direct` mode a poller checks for new messages on a set interval.
+  Gmail uses `gmailPollIntervalSeconds` (default 600); all other accounts
+  (Outlook, Yahoo, iCloud) use `mailPollIntervalSeconds` (default 180).
+  You can adjust the Gmail interval under **Settings → Infrastructure**.
+- The morning routine reads the labeled queue and picks which threads to
+  bring to your attention.
+- When you ask directly (you DM "what's in my mail?"), the agent uses the
+  `mail` skill on demand.
 
 ## Integration Modes
 
 Gmail and Outlook support all four integration modes
-(`direct | delegated | native | disabled`); each may sit in a
-different mode. Yahoo and iCloud have no integration-registry entry —
+(`direct | delegated | native | disabled`), and each account can sit in
+a different mode. Yahoo and iCloud have no integration-registry entry, so
 they are direct-only by design.
 
 | Provider | Direct | Delegated | Native | Notes |
@@ -109,9 +108,10 @@ they are direct-only by design.
 | Yahoo | ✓ | — | — | IMAP transport. Direct-only; never enters the delegated surface. |
 | iCloud | ✓ | — | — | IMAP transport. Direct-only; never enters the delegated surface. |
 
-Mode flips run through the §14.7 live probe + the per-key
-`runtime_state.integration_flip_lock:<key>`. Changing the main
-backend cascades unmatched `native` rows to `disabled`.
+Switching a provider between modes goes through the §14.7 live probe and
+a per-key lock (`runtime_state.integration_flip_lock:<key>`). If you
+change the main backend, any `native` rows it no longer matches fall back
+to `disabled`.
 
 See [Delegated Mode](../../concepts/delegated-mode.md) for the full
 mode lifecycle.
@@ -119,10 +119,10 @@ mode lifecycle.
 ## What It Outputs
 
 - New threads land in the local `mail_messages_index` table
-  (FTS-indexed via `fts_mail_messages`).
-- Labels/tags are written via the provider API when the agent applies
-  them (`POST /mail/:account/messages/:id/tags`).
-- A short "mail" section in `state/today.md` when items qualified.
+  (full-text indexed via `fts_mail_messages`).
+- Labels and tags are written back through the provider API when the
+  agent applies them (`POST /mail/:account/messages/:id/tags`).
+- A short "mail" section in `state/today.md` when items qualify.
 
 ## Where in the Dashboard
 
@@ -132,18 +132,20 @@ mode lifecycle.
 
 ## Configuration
 
-Per account you choose a provider kind (`gmail` / `outlook` / `yahoo` /
-`icloud`) plus credentials and an optional display label. You
+For each account you choose a provider kind (`gmail` / `outlook` /
+`yahoo` / `icloud`), plus credentials and an optional display label. You
 pick the kind, not the transport — Yahoo and iCloud connect over IMAP
-under the hood, but that is an implementation detail. The set of enabled
-providers is `enabledMailProviders` (default `["gmail"]`).
+behind the scenes, but that's an implementation detail you don't manage.
+The list of enabled providers is `enabledMailProviders` (default
+`["gmail"]`).
 
 ## When Something Goes Wrong
 
-- An **auth failure** points at expired credentials. The dashboard's
-  auth-health card flips to a warning. See [Auth Failed](../../troubleshooting/auth-failed.md).
-- A **classifier that misses** consistently — switch the model behind
-  it via the Gmail Classification Model card on `/connections/mail`.
+- An **auth failure** usually means the credentials have expired. The
+  dashboard's auth-health card turns to a warning. See
+  [Auth Failed](../../troubleshooting/auth-failed.md).
+- A **classifier that keeps guessing wrong** — switch the model behind it
+  from the Gmail Classification Model card on `/connections/mail`.
 
 ## Related
 

package/agent-assets/docs/features/integrations/notion.md

@@ -13,7 +13,6 @@ summary: |
 section: integrations
 tags:
   - integrations
-  - notion
   - knowledge
   - observations
 status: stable
@@ -24,7 +23,7 @@ ask_examples:
   - Why are my Notion routine fetches skipped?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-11
+updated: 2026-07-01
 keywords:
   - notion
   - page
@@ -48,21 +47,25 @@ api_endpoints:
 
 # Notion
 
-Aitne polls the configured Notion databases, records an
-observation on change, and the activity scan decides whether anything
-warrants surfacing. The agent can also read pages on demand through
+Aitne watches the Notion databases you configure. When a page changes,
+it records an *observation* (a short note that something happened), and
+the [activity scan](../routines/activity-scan.md) — the routine that
+periodically reviews recent activity — decides whether anything is worth
+surfacing to you. The agent can also read Notion pages on demand through
 the `notion` skill.
 
 ## What It Does
 
-- Polls Notion via the official API at `notionPollIntervalSeconds`.
-- Records an observation per detected change.
+- Checks Notion through the official API on the interval set by
+  `notionPollIntervalSeconds`.
+- Records one observation for each change it detects.
 - Lets the agent read pages on demand.
 
 ## When It Runs / How It Is Triggered
 
-Continuous polling in `direct` mode. In `delegated` / `native` / `disabled`
-modes the poller does not run — see Integration Modes below.
+The poller runs continuously, but only in `direct` mode. In the
+`delegated`, `native`, and `disabled` modes it does not run — see
+[Integration Modes](#integration-modes) below.
 
 ## Integration Modes
 
@@ -84,8 +87,9 @@ Notion supports all four integration modes (`direct` / `delegated` /
   `disabled`.
 - **`disabled`** — silence; no observations, no daemon access.
 
-Switching modes requires the integration flip-lock probe to pass
-(connector reachable, capabilities reported). See `POST /api/integrations/notion/probe`.
+Switching modes requires the integration flip-lock probe to pass — a
+quick check that the connector is reachable and reports its
+capabilities. See `POST /api/integrations/notion/probe`.
 
 ## Routine Fetch Targets
 

package/agent-assets/docs/features/integrations/obsidian.md

@@ -8,15 +8,14 @@ aliases:
   - knowledge vault
 category: features
 summary: |
-  Watch an Obsidian vault for new and changed notes. Changes record
-  observations the activity scan consumes; the agent can also read
-  notes on demand.
+  Watch an Obsidian vault for new and changed notes. Each change
+  records an observation that the activity scan later reviews; the
+  agent can also read notes on demand.
 section: integrations
 tags:
   - integrations
   - knowledge
   - observations
-  - obsidian
 status: stable
 ask_examples:
   - How do I connect my Obsidian vault?
@@ -24,7 +23,7 @@ ask_examples:
   - Why didn't the agent see my new note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-11
+updated: 2026-07-01
 keywords:
   - obsidian
   - vault
@@ -45,18 +44,22 @@ config_keys:
 
 # Obsidian
 
-Point Aitne at your Obsidian vault directory; new and changed notes
-record observations the activity scan consumes. The agent can read and
-write vault notes through the `external-services` skill.
+Point Aitne at your Obsidian vault folder (the directory where your
+notes live). When you add or change a note, Aitne records an
+observation — a short note-to-self that the
+[activity scan](../routines/activity-scan.md) reviews on its next run.
+The agent can also read and write vault notes through the
+`external-services` skill.
 
-Reads and writes go through the Obsidian app's CLI — the Obsidian app
-must be running, or vault read/write calls fail.
+Reads and writes go through the Obsidian app's own command-line tool
+(CLI), so the Obsidian app must be running — otherwise vault read and
+write calls fail.
 
 ## What It Does
 
-- Watches the vault for filesystem changes.
-- Filters out agent-originated writes via `AgentWriteTracker`.
-- Records observations for genuine operator edits.
+- Watches the vault folder for file changes.
+- Ignores writes the agent made itself, using `AgentWriteTracker`.
+- Records an observation for each edit you make by hand.
 
 ### Will it edit my notes?
 
@@ -70,10 +73,11 @@ its own output.
 ## When It Runs / How It Is Triggered
 
 Continuously — the watcher runs as long as the daemon is up and a vault
-path is configured (`externalObsidianWatch=true`). Saves are debounced
-by `obsidianDebounceSeconds` before an observation is recorded; the
-[activity scan](../routines/activity-scan.md) later consumes those
-observations.
+path is configured (`externalObsidianWatch=true`). After you save,
+Aitne waits `obsidianDebounceSeconds` before recording the change (a
+short pause called debouncing), so a burst of quick saves is folded
+into one observation. The [activity scan](../routines/activity-scan.md)
+picks up those observations on its next run.
 
 ## Where in the Dashboard
 
@@ -84,15 +88,15 @@ observations.
 | Setting | Default | Notes |
 |---|---|---|
 | `externalObsidianVaultPath` | unset | Vault directory; set in Connections → Notes. |
-| `externalObsidianWatch` | true | Set false to keep the path but stop recording changes (large-vault churn control). |
-| `obsidianDebounceSeconds` | 5 | How long to wait after a save before recording. |
+| `externalObsidianWatch` | true | Set false to keep the path but stop recording changes — handy for a large, busy vault. |
+| `obsidianDebounceSeconds` | 5 | How many seconds to wait after a save before recording. |
 
 ## When Something Goes Wrong
 
-- A vault read or write that failed: the Obsidian app must be running,
-  since reads and writes proxy through its CLI. Open Obsidian and retry.
-- A change that did not record: the debounce may have folded multiple
-  saves; the next one will fire.
+- A read or write failed: the Obsidian app must be running, because
+  reads and writes go through its CLI. Open Obsidian and try again.
+- A change didn't show up: the debounce pause may have folded several
+  saves together; the next save will record it.
 
 ## Related