@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -14,22 +14,25 @@ summary: |
   notification spam.
 section: integrations
 tags:
-  - integration
+  - integrations
   - git
-  - observation
+  - 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,36 +7,60 @@ 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:
-  - integration
+  - integrations
   - github
-  - observation
+  - 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
+  - pull request
+  - 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.
@@ -44,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.
 
@@ -66,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
@@ -84,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
 
@@ -123,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

@@ -17,7 +17,7 @@ summary: |
   transport, not a separately exposed provider kind.)
 section: integrations
 tags:
-  - integration
+  - integrations
   - mail
   - core
 status: stable
@@ -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-05-28
 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,52 @@ 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).
 - 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 +129,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 +146,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

@@ -12,31 +12,45 @@ summary: |
   Changes record observations consumed by the hourly check.
 section: integrations
 tags:
-  - integration
+  - integrations
+  - notion
   - knowledge
-  - observation
+  - 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
 
@@ -46,23 +60,49 @@ records observations on change.
 
 ## When It Runs / How It Is Triggered
 
-Continuous polling.
+Continuous polling in `direct` mode. In `delegated` / `native` / `disabled`
+modes the poller does not run — see Integration Modes below.
+
+## Integration Modes
+
+Notion supports all four integration modes (`direct` / `delegated` /
+`native` / `disabled`), selected from **Connections → Knowledge**.
+
+- **`direct`** — the daemon polls Notion itself, records change
+  observations, and the hourly check consumes them.
+- **`delegated`** — a delegated-sync worker runs on opt-in cadences;
+  observations are recorded the same way but on a different
+  schedule (see [Delegated Mode](../../concepts/delegated-mode.md)).
+- **`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
+  `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
+(connector reachable, capabilities reported). See `POST /api/integrations/notion/probe`.
 
 ## Where in the Dashboard
 
-- **Connections → Knowledge** holds the integration token and target
-  databases.
+- **Connections → Knowledge** holds the integration token, target
+  databases, and the mode picker.
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `notionPollIntervalSeconds` | 300 | Polling interval. |
+| `notionPollIntervalSeconds` | 300 | Polling interval (direct mode only). |
 
 ## When Something Goes Wrong
 
 - Notion's API rate-limits aggressively at high poll frequency. Stay
   ≥ 300 seconds.
+- "No observations" in `native` mode is expected — observations flow
+  only when the main backend POSTs them during a session.
 
 ## Related
 

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

@@ -13,9 +13,10 @@ summary: |
   notes on demand.
 section: integrations
 tags:
-  - integration
+  - integrations
   - knowledge
-  - observation
+  - observations
+  - obsidian
 status: stable
 ask_examples:
   - How do I connect my Obsidian vault?
@@ -23,7 +24,12 @@ ask_examples:
   - Why didn't the agent see my new note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - obsidian
+  - vault
+  - vault watcher
+  - obsidian observer
 related:
   - features/integrations/notion
   - features/routines/hourly-check
@@ -31,15 +37,20 @@ related:
 ui_anchors:
   - /connections/knowledge
 config_keys:
+  - externalObsidianVaultPath
+  - externalObsidianVaultName
+  - externalObsidianWatch
   - obsidianDebounceSeconds
 ---
 
 # Obsidian
 
-## In One Sentence
+Point Aitne at your Obsidian vault directory; new and changed notes
+record observations the hourly check consumes. The agent can read and
+write vault notes through the `external-services` skill.
 
-Point Aitne at your Obsidian vault directory; new and changed
-notes record observations the hourly check consumes.
+Reads and writes go through the Obsidian app's CLI — the Obsidian app
+must be running, or vault read/write calls fail.
 
 ## What It Does
 
@@ -47,9 +58,22 @@ notes record observations the hourly check consumes.
 - Filters out agent-originated writes via `AgentWriteTracker`.
 - Records observations for genuine operator edits.
 
+### Will it edit my notes?
+
+The agent reads on demand and can create, append to, overwrite, or
+delete notes when you ask it to (via the `external-services` skill). It
+never edits your vault unprompted. When the agent does write, the
+watcher does not treat its own writes as new observations —
+`AgentWriteTracker` suppresses them — so the agent does not re-observe
+its own output.
+
 ## When It Runs / How It Is Triggered
 
-Continuously. The watcher is debounced by `obsidianDebounceSeconds`.
+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
+[hourly check](../routines/hourly-check.md) later consumes those
+observations.
 
 ## Where in the Dashboard
 
@@ -59,10 +83,14 @@ Continuously. The watcher is debounced by `obsidianDebounceSeconds`.
 
 | Setting | Default | Notes |
 |---|---|---|
+| `externalObsidianVaultPath` | unset | Vault directory; set in Connections → Knowledge. |
+| `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. |
 
 ## 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.