@aitne-sh/aitne 0.1.8 → 0.1.10

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

@@ -10,16 +10,18 @@ aliases:
 category: features
 summary: |
   The calendar integration pulls your events into Aitne so the
-  morning routine, schedule files, and travel-time skill can reason
-  about your day. The Connections → Calendar page also picks the
-  backend that handles approaching-event notifications and observed
-  calendar changes (Calendar Event Model) — that picker only applies
-  when the integration runs in direct mode.
+  morning routine and schedule files can reason about your day.
+  The Connections → Calendar page also picks the backend that handles
+  observed calendar changes (the Calendar Event Model card, binding
+  calendar.change) — that picker only applies when the integration runs
+  in direct mode.
 section: integrations
 tags:
   - integrations
   - calendar
   - core
+  - observations
+  - polling
 status: stable
 ask_examples:
   - How do I connect my Google Calendar?
@@ -28,10 +30,10 @@ ask_examples:
   - What is the Calendar Event Model setting on the Connections page?
   - Why is the Calendar Event Model card missing when my calendar is delegated?
   - Will Aitne notice calendar changes while my calendar is delegated?
-  - Which model handles approaching-event reminders?
+  - Which model handles detected calendar changes?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-28
+updated: 2026-06-07
 keywords:
   - calendar
   - google calendar
@@ -47,25 +49,28 @@ keywords:
 related:
   - features/routines/morning-routine
   - features/memory-files/schedule
+  - features/operations/schedule-approaching
   - concepts/delegated-mode
   - concepts/process-keys
   - concepts/observations
 ui_anchors:
   - /connections/calendar
 api_endpoints:
-  - /api/calendar
+  - /api/calendar/calendars
+  - /api/calendar/events
+  - /api/calendar/freebusy
 config_keys:
   - calendarPollIntervalSeconds
 process_keys:
   - calendar.change
+  - schedule.approaching
 ---
 
 # Calendar
 
-## In One Sentence
-
-Pull events from one or more calendars (Google Calendar today, more
-backends planned) so Aitne can plan your day around them.
+Aitne pulls events from one or more calendars (Google Calendar,
+Outlook Calendar, and Apple Calendar) so it can build today's plan
+around them and DM you ahead of meetings that matter.
 
 ## What It Does
 
@@ -73,11 +78,13 @@ backends planned) so Aitne can plan your day around them.
 - **Records observations** when events change (add / move / remove),
   consumed by the hourly check.
 - **Surfaces today's events** to the morning routine so they land in
-  `today.md` and the day's schedule file.
+  `state/today.md` and the day's schedule file.
 - **Reads** events on demand for reactive turns ("am I free at 3?").
 
-The agent can create events when the operator asks (a `notify`-tier
-action). It does not auto-schedule on its own.
+The agent can create, move, or delete events when the operator asks
+(`POST`/`PATCH`/`DELETE /api/calendar/events`, all Autonomous-tier — no
+approval prompt). It does not auto-schedule on its own; it acts only on
+an explicit request.
 
 ## When It Runs / How It Is Triggered
 
@@ -99,22 +106,24 @@ action). It does not auto-schedule on its own.
 ## Calendar Event Model
 
 The Calendar Event Model picker chooses the backend and model that
-runs when the agent reacts to a calendar event. It binds the
-`calendar.change` ProcessKey, which fires from the calendar poller in
-three situations:
+runs when the **daemon-side poller detects a calendar change**. It binds
+the `calendar.change` ProcessKey, which fires in two situations:
 
-- An event is about to start (the operator gets an approaching-event
-  reminder).
 - An event was added, moved, or deleted between polls (recorded as a
   change observation; the hourly check picks it up).
-- An event was created far in advance (long-horizon events nudge the
-  roadmap-refresh routine so `roadmap.md` can build a preparation
-  timeline).
+- An event was created far in advance (long-horizon events more than 14
+  days out nudge the roadmap-refresh routine so `plans/roadmap.md` can
+  build a preparation timeline).
+
+Approaching-event reminders are a separate flow: they fire on the
+`schedule.approaching` ProcessKey, not `calendar.change`, and are not
+configured by this card. See [Schedule Approaching](../operations/schedule-approaching.md).
 
-Light tier is the default and almost always sufficient — these flows
-are classification and scheduling, not generation. The default backend
-is whichever you picked as your main backend during setup; you can
-override per-process here if you want a different mix.
+Light tier (Haiku 4.5 / gpt-5.4-mini) is the default and almost always
+sufficient — these flows are event classification at low cost, not
+generation. The default backend is whichever you picked as your main
+backend during setup; you can override per-process here if you want a
+different mix.
 
 The picker is **only meaningful when Google Calendar runs in direct
 mode.** In delegated mode the daemon hands off all Google Calendar
@@ -157,7 +166,8 @@ rather than an env-style setting; the underlying state lives in the
 ## Related
 
 - [Morning Routine](../routines/morning-routine.md)
-- [daily/ files](../memory-files/schedule.md)
+- [Schedule files](../memory-files/schedule.md)
+- [Schedule Approaching](../operations/schedule-approaching.md)
 - [Delegated Mode](../../concepts/delegated-mode.md)
-- [ProcessKeys](../../concepts/process-keys.md)
+- [Process Keys](../../concepts/process-keys.md)
 - [Observations](../../concepts/observations.md)

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

@@ -17,19 +17,22 @@ tags:
   - integrations
   - git
   - observations
+  - polling
 status: stable
 ask_examples:
   - How do I add a git repo to watch?
   - Will the agent message me on every commit?
   - Can the agent push to my repos?
+  - How often does the daemon poll my repos?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - git
   - commit
   - repository
   - observer
+  - polling
 related:
   - features/integrations/github
   - features/routines/hourly-check
@@ -38,12 +41,17 @@ ui_anchors:
   - /connections/repositories
 config_keys:
   - gitPollIntervalSeconds
+process_keys:
+  - git.push.detected
+  - git.lifecycle.poll
+api_endpoints:
+  - /api/git/log
+  - /api/git/diff
+  - /api/git/show
 ---
 
 # Git
 
-## In One Sentence
-
 Add local git repositories to a watched set; the daemon polls them
 and the hourly check decides whether the recent activity is worth
 flagging.
@@ -72,19 +80,22 @@ by design.
 
 ## Where in the Dashboard
 
-- **Connections → Git** lists the watched paths and last-poll times.
+- **Connections → Repositories** lists the watched paths and last-poll
+  times. Git repos are managed as part of the unified Repositories
+  surface (the same place that links a local checkout to its GitHub
+  remote).
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `gitPollIntervalSeconds` | 300 | How often to scan watched repos. |
+| `gitPollIntervalSeconds` | 3600 | How often to scan watched repos. |
 
 ## When Something Goes Wrong
 
 - A **missing observation** for a commit you just made: check that the
-  repo path is actually watched on `/connections/git` and that the
-  poll has fired since.
+  repo path is actually watched on `/connections/repositories` and that
+  the poll has fired since (it runs every `gitPollIntervalSeconds`).
 - A repo that **never appears** in observations: the agent's own
   writes are filtered out (see `AgentWriteTracker`); make sure the
   commit was authored by you, not by an agent session.

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

@@ -7,25 +7,29 @@ aliases:
   - github integration
   - github poller
   - github notifications
+  - github delegated mode
 category: features
 summary: |
   GitHub is the remote-side counterpart to the Git integration. The
   daemon polls notifications and CI failures via the local `gh` CLI;
   high-priority signals (review requests, default-branch CI failures,
-  security alerts, assignments) become direct DMs.
+  security alerts, assignments) become direct DMs. Watched repos are
+  registered as unified Repository rows, not config keys.
 section: integrations
 tags:
   - integrations
   - github
   - observations
+  - polling
 status: stable
 ask_examples:
   - How do I connect GitHub?
   - Will the agent message me on every CI failure?
   - Can the agent reply to GitHub issues?
+  - Where do I add a GitHub repo to watch?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-28
+updated: 2026-05-28
 keywords:
   - github
   - issue
@@ -33,17 +37,30 @@ keywords:
   - PR review
   - workflow run
   - security alert
+  - delegated mode
+  - gh cli
+  - repositories
 related:
   - features/integrations/git
   - concepts/observations
+  - concepts/delegated-mode
 ui_anchors:
   - /connections/repositories
+config_keys:
+  - githubPollIntervalSeconds
+api_endpoints:
+  - PATCH /api/integrations/github
+process_keys:
+  - github.pull_request.review_requested
+  - github.assigned
+  - github.security_alert
+  - github.workflow_run.failed
+context_files:
+  - state/today.md
 ---
 
 # GitHub
 
-## In One Sentence
-
 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 hourly check.
@@ -51,10 +68,14 @@ become DMs; everything else is recorded for the hourly check.
 ## What It Does
 
 - **Polls Notifications** every `githubPollIntervalSeconds` (default
-  600s) using ETag caching — 304s cost no rate-limit quota.
-- **Polls workflow_runs** per watched GitHub repository on the same
-  cadence, filtered by `status=failure`. Watched repos can come from a
-  local clone's GitHub `origin` or from an explicit `owner/repo` entry.
+  1800s / 30 min) using ETag caching — 304 responses cost no
+  rate-limit quota.
+- **Polls workflow_runs** per watched GitHub repository, filtered by
+  `status=failure`. Each repo's GitHub side comes from a unified
+  **Repository** row (a `owner/repo` remote, optionally paired with a
+  local clone — see [Setup](#setup)). Per-repo cadence overrides apply
+  to the workflow-runs side; the notifications poll always runs at the
+  global cadence.
 - **DMs the user** on the four high-priority triggers below; quieter
   signals are coalesced into the hourly check summary.
 
@@ -73,17 +94,17 @@ depending on your notify-skill settings) on:
   observation-only — they're the normal developer feedback loop).
 
 Each DM follows the notify skill's awareness-gate: if the agent already
-sees you triaging it in `today.md`, it stays silent and just logs.
+sees you triaging it in `state/today.md`, it stays silent and just logs.
 
 ## Setup
 
 1. Install `gh`: `brew install gh` on macOS; see
    [cli.github.com](https://cli.github.com/) for other platforms.
 2. Authenticate: `gh auth login` (browser flow).
-3. Add `owner/repo` entries to **Connections → GitHub**, or add local
-   repository paths to **Connections → Git Repositories**. For local
-   paths, the poller derives `owner/name` from each repo's `origin`
-   remote — non-GitHub remotes are silently skipped.
+3. Register the repos to watch on **Connections → Repositories**. Each
+   row links an `owner/repo` GitHub remote, an optional local clone, or
+   both. If you link only a local clone, the poller derives `owner/name`
+   from its `origin` remote — non-GitHub remotes are silently skipped.
 4. Restart the daemon (the poll interval is captured at start time).
 
 The daemon does NOT need a personal access token in its keychain — it
@@ -91,27 +112,39 @@ re-uses whatever `gh` already has.
 
 ## Cold-start behavior
 
-The first time the daemon polls a watched repo, it records the latest
-failed workflow runs **without emitting any events**. This prevents a
-flood of DMs about historical CI failures the user has already triaged.
-New failures landing after that warm-up are surfaced normally.
+The first time the daemon polls a watched repo's **workflow runs**, it
+records the latest failures **without emitting any events**. This
+prevents a flood of DMs about historical CI failures you have already
+triaged. New failures landing after that warm-up are surfaced normally.
+
+The notifications side needs no warm-up: GitHub returns only unread
+items, so there is no historical backlog to suppress.
 
 ## Where in the Dashboard
 
-- **Connections → GitHub** shows status and the `gh auth login`
-  hint.
-- **Connections → GitHub** controls explicit `owner/repo` watched repos.
-  When this list is non-empty, notification processing is scoped to it.
-- **Connections → Git Repositories** controls local clone paths whose
-  GitHub remotes are watched for workflow_run failures.
+Everything lives on **Connections → Repositories**
+(`/connections/repositories`):
+
+- The GitHub integration card shows status, the `gh auth login` hint,
+  and the integration mode picker (see [Modes](#modes)).
+- Each repository row links an `owner/repo` GitHub remote and/or a
+  local clone. When at least one row has a GitHub remote, notification
+  processing is scoped to those repos.
+- Per-repo polling cadence, automation triggers, and daily git
+  management are configured on **My Life → Git** (`/git`), not here.
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `githubPollIntervalSeconds` | 600 (10 min) | Both poll cadences. Lower for faster review-request alerts at the cost of slightly more rate-limit budget. **Restart-required.** |
-| `gitRepos` | `[]` | Local repo paths to watch. |
-| `githubRepos` | `[]` | Direct remote repos in `owner/repo` form. Also scopes notification processing when non-empty. |
+| `githubPollIntervalSeconds` | 1800 (30 min) | Global poll cadence. Lower for faster review-request alerts at the cost of slightly more rate-limit budget. **Restart-required.** |
+
+Watched repos are no longer config keys. The old `gitRepos` /
+`githubRepos` settings were removed at the unified-repositories
+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.
 
 ## When Something Goes Wrong
 
@@ -130,16 +163,34 @@ New failures landing after that warm-up are surfaced normally.
   poller pre-checks `observations(source, ref)` before every emit. If
   it does, file a bug with the notification id.
 
-## Delegated mode (coming soon)
-
-A future release will let Claude Code, Codex, or Gemini CLI handle
-GitHub directly via their native MCP / `gh` integrations, optionally
-replacing the daemon-side poller. Most users won't need this — the
-built-in poller already covers the common surface — but it'll be
-useful if you'd rather skip the daemon-side polling entirely.
+## Modes
+
+GitHub supports three integration modes: `direct` (default),
+`delegated`, and `disabled`. Native mode is not offered — the
+backend-side connectors are read-only `gh` CLI wrappers that do not
+need a daemon-spawned poller's bookkeeping.
+
+- **direct** — the daemon's `GitHubPoller` runs as described above.
+  Use this when you want the daemon to own the poll schedule and to
+  emit DMs without the main backend having to wake up.
+- **delegated** — the delegated-sync worker invokes the chosen
+  backend's read-only `gh` CLI surface on opt-in cadences (see
+  [Delegated Mode](../../concepts/delegated-mode.md) and
+  `docs/design/appendices/delegated-sync-opt-in.md`). The daemon
+  poller stays off; the lite-tier delegated session takes the polling
+  cost.
+- **disabled** — neither the poller nor the delegated worker runs;
+  the integration is silent.
+
+Pick the mode from the GitHub card on **Connections → Repositories**.
+Mode changes go through the standard `PATCH /api/integrations/github`
+flip-lock so the poller and the delegated worker never run
+simultaneously.
 
 ## Related
 
 - [Git](git.md) — local repo file watcher (separate observer).
 - [Hourly Check](../routines/hourly-check.md) — the consumer of
   non-DM-priority observations.
+- [Delegated Mode](../../concepts/delegated-mode.md) — how the
+  `delegated` mode polls without a daemon poller.

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

@@ -27,7 +27,7 @@ ask_examples:
   - How do I add a second mail account?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
   - mail
   - gmail
@@ -36,22 +36,35 @@ keywords:
   - icloud
   - inbox
   - labels
+  - native mode
+  - delegated
+  - direct
+  - fts5
 related:
   - guides/connect-a-new-mail-account
   - features/routines/morning-routine
+  - concepts/delegated-mode
 ui_anchors:
   - /connections/mail
 api_endpoints:
   - /api/mail
+  - /api/mail/accounts
+  - /api/mail/search
+config_keys:
+  - enabledMailProviders
+  - mailPollIntervalSeconds
+  - gmailPollIntervalSeconds
+context_files:
+  - state/today.md
 ---
 
 # Mail
 
-## In One Sentence
-
-Connect one or more mailboxes; the daemon polls them, classifies
-incoming threads, and lets the agent read / label / search via the
-`mail` skill.
+Connect one or more mailboxes (Gmail, Outlook, Yahoo, iCloud, or any
+IMAP server) 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.
 
 ## What It Does
 
@@ -62,24 +75,53 @@ incoming threads, and lets the agent read / label / search via the
 - **Surface** the small set of mail items in the morning routine that
   actually need owner action.
 
-The agent does **not** send mail on your behalf. Drafting is supported
-(via the provider's draft API where available) but sending is an
-operator action.
+The agent **prefers drafts** over sending. By convention it creates a
+draft (`POST /mail/:account/drafts`) and lets you review and hit 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
+hourly check the `mail` skill is hard read-only (no sending, drafting,
+labeling, or filing).
 
 ## When It Runs / How It Is Triggered
 
-- A poller pulls new messages every `gmailPollIntervalSeconds` (or the
-  per-provider equivalent) — see Settings → Advanced.
+- In `direct` mode a poller pulls new messages on a cadence. Gmail uses
+  `gmailPollIntervalSeconds` (default 600); IMAP-backed accounts (Yahoo,
+  iCloud, generic IMAP) use `mailPollIntervalSeconds` (default 180).
+  Adjust both under **Settings → Advanced**.
 - 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.
 
+## Integration Modes
+
+Mail supports all four integration modes
+(`direct | delegated | native | disabled`); each provider may sit in a
+different mode.
+
+| Provider | Direct | Delegated | Native | Notes |
+|---|---|---|---|---|
+| Gmail | ✓ | ✓ | ✓ (descriptor-driven) | Native mode uses Google's official Gmail MCP connector on the main backend; the connector POSTs observations back via `/api/observations`. |
+| Outlook | ✓ | ✓ | ✓ (user-managed) | Native mode requires you to install your own MCP / skill harness on the main backend (`userManagedConnector: true`); the probe synthesises a user-managed result and skips the missing-variant gate. |
+| Yahoo | ✓ | ✓ | — | IMAP transport. No native MCP variant. |
+| iCloud | ✓ | ✓ | — | IMAP transport. No native MCP variant. |
+| Generic IMAP | ✓ | ✓ | — | IMAP transport. No native MCP variant. |
+
+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`.
+
+See [Delegated Mode](../../concepts/delegated-mode.md) for the full
+mode lifecycle.
+
 ## What It Outputs
 
-- New threads land in the local `messages` table (FTS-indexed).
+- New threads land in the local `mail_messages_index` table
+  (FTS-indexed via `fts_mail_messages`).
 - Classification labels are written via the provider API.
-- A short "mail" section in `today.md` when items qualified.
+- A short "mail" section in `state/today.md` when items qualified.
 
 ## Where in the Dashboard
 
@@ -88,10 +130,11 @@ operator action.
 
 ## Configuration
 
-Per-account settings: provider kind (`gmail` / `outlook` / `yahoo` /
-`icloud`), credential store, label conventions, polling interval.
-Yahoo and iCloud use IMAP transport internally; the operator picks
-the kind, not the transport.
+Per account you choose a provider kind (`gmail` / `outlook` / `yahoo` /
+`icloud`) plus credentials, label conventions, and polling interval. 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"]`).
 
 ## When Something Goes Wrong
 
@@ -104,3 +147,4 @@ the kind, not the transport.
 
 - [Connect a new mail account](../../guides/connect-a-new-mail-account.md)
 - [Morning Routine](../routines/morning-routine.md)
+- [Delegated Mode](../../concepts/delegated-mode.md)

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

@@ -13,36 +13,44 @@ summary: |
 section: integrations
 tags:
   - integrations
+  - notion
   - knowledge
   - observations
 status: stable
 ask_examples:
   - How do I connect Notion?
   - Will Notion notify me on every page change?
+  - What does Notion native mode do?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - notion
   - page
   - database
   - notion observer
   - notion poller
+  - integration modes
 related:
   - features/integrations/obsidian
   - features/routines/hourly-check
+  - concepts/delegated-mode
+  - concepts/observations
 ui_anchors:
   - /connections/knowledge
 config_keys:
   - notionPollIntervalSeconds
+api_endpoints:
+  - POST /api/integrations/:key/probe
+  - POST /api/observations
 ---
 
 # Notion
 
-## In One Sentence
-
-A Notion integration polls a configured database / page set and
-records observations on change.
+Aitne polls a configured Notion database or page set, records an
+observation on change, and the hourly check decides whether anything
+warrants surfacing. The agent can also read pages on demand through
+the `notion` skill.
 
 ## What It Does
 
@@ -68,7 +76,11 @@ Notion supports all four integration modes (`direct` / `delegated` /
 - **`native`** — the main backend reaches Notion through its own MCP
   connector on demand; the daemon does no polling. Observations
   flow in only when the main backend POSTs them in-turn via
-  `/api/observations`. Available with Claude (`mcp__notion__*`).
+  `POST /api/observations`. Supported when the main backend is
+  Claude, Codex, or Gemini (each ships a Notion connector — e.g.
+  Claude's is `mcp__claude_ai_Notion__*`). OpenCode hosts no native
+  connectors, so selecting it as the main backend cascades Notion to
+  `disabled`.
 - **`disabled`** — silence; no observations, no daemon access.
 
 Switching modes requires the integration flip-lock probe to pass