@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,170 @@
+---
+schema_version: 1
+slug: features/integrations/github
+title: GitHub
+id: github
+aliases:
+  - github integration
+  - github poller
+  - github notifications
+category: features
+summary: |
+  GitHub is the remote-side counterpart to the Git integration. The
+  daemon polls the user's notifications feed and watched-repo CI failures
+  via the local `gh` CLI, recording observations and DM-ing the user
+  about high-priority signals (review requests, default-branch CI failures,
+  Dependabot alerts, assignments). The agent never auto-comments,
+  auto-merges, or pushes.
+section: integrations
+tags:
+  - integration
+  - github
+  - observation
+  - 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?
+  - Why isn't the GitHub poller firing?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-28
+keywords:
+  - github
+  - notifications
+  - workflow_run
+  - review_requested
+  - gh cli
+related:
+  - features/integrations/git
+  - features/routines/hourly-check
+  - concepts/observations
+ui_anchors:
+  - /connections/repositories
+config_keys:
+  - githubPollIntervalSeconds
+  - gitRepos
+  - githubRepos
+---
+
+# GitHub
+
+## In One Sentence
+
+The daemon polls GitHub Notifications + watched-repo CI failures via
+the local `gh` CLI, surfacing high-priority signals as DMs and feeding
+everything else into the hourly check.
+
+## How It Works
+
+GitHub access is **delegated to the local `gh` CLI** rather than carried
+by a daemon-side personal access token. Authentication happens once via
+`gh auth login`; the daemon shells out to `gh api …` per poll. This
+keeps secrets in the OS keychain that `gh` already manages, and lines
+up with the future delegated-mode story (Claude / Codex / Gemini will
+share the same auth path).
+
+Two cadences run on a single timer:
+
+1. **Notifications** — `gh api notifications` with ETag caching.
+   304 Not Modified responses cost zero rate quota.
+2. **Workflow runs** — per watched GitHub repo (any explicit
+   `owner/repo` entry in the GitHub card, plus any entry in the
+   Git Repositories card whose `origin` resolves to GitHub),
+   `gh api repos/<owner>/<name>/actions/runs?status=failure`.
+
+When `githubRepos` is non-empty, notification processing is scoped to
+those `owner/repo` entries. When it is empty, the poller preserves the
+older behavior and processes the authenticated user's unread
+notifications globally.
+
+The classifier maps each event to either a `recordObservation` call
+(for the hourly check to coalesce) or both an observation **and** an
+EventBus emit (for high-priority signals that warrant a direct DM).
+
+## High-priority events
+
+| Trigger | Event type | Task-flow |
+|---|---|---|
+| `notifications.reason === "review_requested"` | `github.pull_request.review_requested` | `github.pull_request.review_requested.md` |
+| `notifications.reason === "assign"` | `github.assigned` | `github.assigned.md` |
+| `notifications.reason === "security_alert"` | `github.security_alert` | `github.security_alert.md` |
+| Workflow run failure on default branch | `github.workflow_run.failed` | `github.workflow_run.failed.md` |
+
+Feature-branch CI failures stay observation-only (LOW priority) — they
+are the developer's normal feedback loop, not interruption-worthy.
+
+## Cold-start safety
+
+On first start with a fresh database, the workflow-runs path records
+the latest failures without emitting direct events. This prevents the
+user from waking up to 30 stale CI-failure DMs after enabling the
+integration while still warming the idempotency table. Notifications are
+inherently cold-start-safe because GitHub returns only currently-unread
+notifications.
+
+## Idempotency
+
+Every emission goes through a pre-check: `SELECT 1 FROM observations
+WHERE source = ? AND ref = ?` covers both consumed and pending rows.
+If a `review_requested` notification stays unread for an hour and you
+poll every 10 minutes, the user is DM'd **once**, not six times.
+
+## Where in the Dashboard
+
+- **Connections → GitHub** shows the integration status, the
+  `gh auth login` reminder, explicit `owner/repo` watched repos, and
+  event model routing cards.
+- **Git Repositories** on the same page lists local clone paths whose
+  GitHub remotes are also watched for workflow failures.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `githubPollIntervalSeconds` | 600 | Both notifications and workflow_runs poll on this cadence. Restart-required (the timer is captured at construction time). |
+| `gitRepos` | `[]` | Local repo paths. The poller derives `owner/name` via `git remote get-url origin` for each entry whose remote is on GitHub. |
+| `githubRepos` | `[]` | Direct remote repos in `owner/repo` form. Enables workflow polling without a local clone and scopes GitHub notification processing when non-empty. |
+
+## When Something Goes Wrong
+
+- **`gh` CLI not found.** The daemon log shows `\`gh\` CLI is not on
+  PATH — install via \`brew install gh\` (or platform equivalent),
+  then \`gh auth login\``. Polls stay quiet (exponential backoff up
+  to 16 ticks ≈ 2.6 hours at default cadence) until `gh` is
+  reachable.
+- **Authentication expired.** `gh auth status` non-zero produces
+  a `GitHub poll failed (auth)` warning per backoff cycle. Log in
+  again with `gh auth login`.
+- **No DMs for a known PR review request.** Confirm the notification
+  is actually surfaced via `gh api notifications` from your shell —
+  if it's missing there too, GitHub's own notification routing has
+  filtered it (watch / mention settings on the source repo).
+- **Wrong default branch detection.** The poller queries
+  `gh api repos/<o>/<r> --jq .default_branch` once at startup. If
+  this lookup fails (rate limit, transient network), the cached
+  default is `main`. Restart the daemon after the issue clears to
+  re-resolve.
+
+## Backend routing
+
+High-priority GitHub events are first-class process keys:
+
+- `github.pull_request.review_requested`
+- `github.assigned`
+- `github.security_alert`
+- `github.workflow_run.failed`
+
+Configure them under **Connections → Git & Code** or **Settings →
+Models → Process Routing**. Each row can route to Claude Code, Codex,
+or Gemini CLI, with the same fallback, auth-health, turn-limit, and
+cost-audit behavior as other autonomous processes.
+
+## Related
+
+- [Git](git.md) — local repo file watcher (separate observer).
+- [Hourly Check](../routines/hourly-check.md) — consumer of
+  observation-only signals.
+- [Observations](../../concepts/observations.md) — the storage
+  contract this poller writes against.

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

@@ -0,0 +1,106 @@
+---
+schema_version: 1
+slug: features/integrations/mail
+title: Mail
+id: mail
+aliases:
+  - email
+  - gmail
+  - outlook
+  - mail integration
+category: features
+summary: |
+  Mail integration lets the agent read, label, classify, and search
+  your inbox across Gmail, Outlook, Yahoo, and iCloud. Mail is
+  proxied through the daemon — no provider library lives in the
+  agent. (Yahoo / iCloud connect via IMAP under the hood; IMAP is the
+  transport, not a separately exposed provider kind.)
+section: integrations
+tags:
+  - integration
+  - mail
+  - core
+status: stable
+ask_examples:
+  - How do I connect my Gmail to the agent?
+  - Can the agent send mail on my behalf?
+  - How do I add a second mail account?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - mail
+  - gmail
+  - outlook
+  - yahoo
+  - icloud
+  - inbox
+  - labels
+related:
+  - guides/connect-a-new-mail-account
+  - features/routines/morning-routine
+ui_anchors:
+  - /connections/mail
+api_endpoints:
+  - /api/mail
+---
+
+# 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.
+
+## What It Does
+
+- **Read & search** existing threads (FTS5-backed local index).
+- **Classify** incoming messages — does this need owner attention,
+  is it a marketing list, is it a receipt.
+- **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.
+
+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.
+
+## When It Runs / How It Is Triggered
+
+- A poller pulls new messages every `gmailPollIntervalSeconds` (or the
+  per-provider equivalent) — see 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.
+
+## 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.
+
+## Where in the Dashboard
+
+- **Connections → Mail** is the per-account configuration: providers,
+  credentials, polling, label setup.
+
+## 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.
+
+## 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** a sender consistently — add a manual
+  label rule on `/connections/mail`.
+
+## Related
+
+- [Connect a new mail account](../../guides/connect-a-new-mail-account.md)
+- [Morning Routine](../routines/morning-routine.md)

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

@@ -0,0 +1,69 @@
+---
+schema_version: 1
+slug: features/integrations/notion
+title: Notion
+id: notion
+aliases:
+  - notion database
+  - notion integration
+category: features
+summary: |
+  Watch a Notion database (or a curated set of pages) for changes.
+  Changes record observations consumed by the hourly check.
+section: integrations
+tags:
+  - integration
+  - knowledge
+  - observation
+status: stable
+ask_examples:
+  - How do I connect Notion?
+  - Will Notion notify me on every page change?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/integrations/obsidian
+  - features/routines/hourly-check
+ui_anchors:
+  - /connections/knowledge
+config_keys:
+  - notionPollIntervalSeconds
+---
+
+# Notion
+
+## In One Sentence
+
+A Notion integration polls a configured database / page set and
+records observations on change.
+
+## What It Does
+
+- Polls Notion via the official API at `notionPollIntervalSeconds`.
+- Records an observation per detected change.
+- Lets the agent read pages on demand.
+
+## When It Runs / How It Is Triggered
+
+Continuous polling.
+
+## Where in the Dashboard
+
+- **Connections → Knowledge** holds the integration token and target
+  databases.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `notionPollIntervalSeconds` | 300 | Polling interval. |
+
+## When Something Goes Wrong
+
+- Notion's API rate-limits aggressively at high poll frequency. Stay
+  ≥ 300 seconds.
+
+## Related
+
+- [Obsidian](obsidian.md)

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

@@ -0,0 +1,71 @@
+---
+schema_version: 1
+slug: features/integrations/obsidian
+title: Obsidian
+id: obsidian
+aliases:
+  - obsidian vault
+  - knowledge vault
+category: features
+summary: |
+  Watch an Obsidian vault for new and changed notes. Changes record
+  observations the hourly check consumes; the agent can also read
+  notes on demand.
+section: integrations
+tags:
+  - integration
+  - knowledge
+  - observation
+status: stable
+ask_examples:
+  - How do I connect my Obsidian vault?
+  - Will the agent edit my notes?
+  - Why didn't the agent see my new note?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/integrations/notion
+  - features/routines/hourly-check
+  - concepts/observations
+ui_anchors:
+  - /connections/knowledge
+config_keys:
+  - obsidianDebounceSeconds
+---
+
+# Obsidian
+
+## In One Sentence
+
+Point Aitne at your Obsidian vault directory; new and changed
+notes record observations the hourly check consumes.
+
+## What It Does
+
+- Watches the vault for filesystem changes.
+- Filters out agent-originated writes via `AgentWriteTracker`.
+- Records observations for genuine operator edits.
+
+## When It Runs / How It Is Triggered
+
+Continuously. The watcher is debounced by `obsidianDebounceSeconds`.
+
+## Where in the Dashboard
+
+- **Connections → Knowledge** to point at the vault directory.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `obsidianDebounceSeconds` | 5 | How long to wait after a save before recording. |
+
+## When Something Goes Wrong
+
+- A change that did not record: the debounce may have folded multiple
+  saves; the next one will fire.
+
+## Related
+
+- [Notion](notion.md)

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

@@ -0,0 +1,178 @@
+---
+schema_version: 1
+slug: features/lifestyle/git
+title: My Life — Git
+id: my-life-git
+aliases:
+  - my life git
+  - per-repo git
+  - git management page
+  - daily git management
+  - git triggers
+  - repo polling cadence
+category: features
+summary: |
+  The /git page (sidebar: My Life › Git) is the per-repository control
+  surface: override polling cadence, define event-driven triggers, and
+  enable daily git management (overview MD + per-day journal entry) for
+  each registered repository.
+section: lifestyle
+tags:
+  - lifestyle
+  - git
+  - github
+  - automation
+  - observation
+status: stable
+ask_examples:
+  - What is the My Life › Git page for?
+  - How do I tighten polling cadence for one repo?
+  - Does daily git management need a local clone?
+  - Can the agent poll a GitHub repo with no local checkout?
+  - What's the difference between Polling, Triggers, and Daily git management?
+  - Where does the daily journal get written?
+  - What happens if a scan fails repeatedly?
+locale: en-US
+created: 2026-05-05
+updated: 2026-05-05
+keywords:
+  - my life
+  - git
+  - repository
+  - polling
+  - trigger
+  - daily git management
+  - overview
+  - journal
+related:
+  - features/integrations/git
+  - features/integrations/github
+  - features/routines/hourly-check
+  - concepts/observations
+ui_anchors:
+  - /git
+  - /connections/repositories
+config_keys:
+  - gitPollIntervalSeconds
+---
+
+# My Life — Git
+
+## In One Sentence
+
+A per-repository control panel for everything Git/GitHub: tighten the
+polling cadence on a single repo, attach event-driven triggers, and
+opt in to **daily git management** (a curated overview MD plus a
+once-a-day journal entry).
+
+## What It Does
+
+The page lists every repository registered on
+**Connections → Repositories** and exposes three collapsible sections
+per repo:
+
+1. **Polling** — overrides the global `gitPollIntervalSeconds` for
+   this repository alone. Useful when one repo is high-traffic and
+   you want it scanned more aggressively (or vice-versa). Also shows
+   the most recent observations gathered from that repo's polling
+   sources.
+2. **Triggers** — fire when matching Git or GitHub events arrive on
+   this repository. Triggers run **alongside** the project-wide
+   task-flow defaults, not in place of them. Each trigger has a
+   workdir mode (`local-clone` or `ephemeral`); local-clone triggers
+   require the repository to have a `localPath`.
+3. **Daily git management** — opt-in per repo. When enabled, the
+   `repository-management-cron` observer fires `git.project.update`
+   roughly once every 24 hours. The session writes/refreshes a
+   curated `git/<slug>/overview.md` and appends a per-day entry under
+   `git/<slug>/journal/YYYY-MM-DD.md` if there was activity.
+
+The agent never pushes, amends, or force-resets. Read-only by design.
+
+## When It Runs / How It Is Triggered
+
+- **Polling** runs continuously on the per-repo cadence (or the global
+  default). Observations land in the `observations` table; the hourly
+  check coalesces them.
+- **Triggers** fire when the matching event arrives on the EventBus.
+- **Daily git management** is dispatched by `RepositoryManagementCron`,
+  which iterates the `repository_management` table once an hour and
+  emits a `scheduled.task` (`git.project.update`) for any enabled row
+  whose `last_scan_at` is more than 24 hours old.
+
+## What It Outputs
+
+- **Polling** → `observation` rows (one per detected change set) +
+  trigger fires when a trigger's match conditions are satisfied.
+- **Triggers** → an autonomous session whose task-flow is selected
+  by the trigger's process key.
+- **Daily git management** → `git/<slug>/overview.md` (refreshed each
+  scan) and `git/<slug>/journal/YYYY-MM-DD.md` (appended for the day,
+  only when activity warrants it).
+
+## Where in the Dashboard
+
+- **My Life → Git** (`/git`) — this page.
+- **Connections → Repositories** (`/connections/repositories`) —
+  register a repo (link a `localPath` and/or `owner/repo`),
+  rename, set `local-only`, delete.
+- **Knowledge** (`/knowledge?path=git/<slug>/overview`) — quick links
+  on each repo card open the generated overview / today's journal.
+
+## Configuration
+
+| Setting | Where | Notes |
+|---|---|---|
+| `gitPollIntervalSeconds` | global config | Default poll cadence applied when no per-repo override is set. |
+| Per-repo polling override | `/git` → Polling | Stored on the repository row; null means "use global". |
+| Triggers | `/git` → Triggers | Per-repo, multiple. Each has match conditions, workdir mode, process key. |
+| Daily git management toggle | `/git` → Daily git management | Stored in `repository_management` table. Requires `localPath`. |
+
+## Local Clone Requirement
+
+Two of the three sections behave differently depending on whether the
+repository has a `localPath`:
+
+- **Polling** does **not** require a local clone. A repository that
+  carries only `githubOwner` / `githubRepo` is polled remote-side via
+  `gh` (workflow runs, notifications). A repository that carries only
+  a `localPath` is polled locally for new commits. A repository that
+  has both is polled both ways.
+- **Triggers** with `workdirMode: "local-clone"` require a `localPath`
+  on the parent repository (enforced when the trigger is created and
+  again if you try to clear `localPath` while such a trigger exists).
+  Triggers with `workdirMode: "ephemeral"` work without a local clone.
+- **Daily git management** is **local-clone-bound for v1**. The
+  toggle is disabled and the dashboard surfaces "No local clone — link
+  one to enable this feature." Internally the
+  `listManagementDueForScan` query filters on `r.local_path IS NOT
+  NULL`, so even a stale `enabled = 1` row will not fire without a
+  local path.
+
+## When Something Goes Wrong
+
+- **The toggle is greyed out with "No local clone".** Add a
+  `localPath` on **Connections → Repositories**, then return.
+- **`Last status` shows `failed` and `Failure streak` keeps climbing.**
+  The cron still iterates but the dispatched session is failing —
+  open the latest conversation under that repo's tile, or check
+  **Activity** for the `git.project.update` run. A high streak does
+  not prevent further scans (the cron retries on the next interval).
+- **`Last scan` is "never" but the row is enabled.** Either the cron
+  has not ticked yet (default tick is 1 hour) or the row has no local
+  path — confirm the local clone link.
+- **A new commit does not show up under Polling → recent
+  observations.** Confirm the poll has fired since the commit
+  (check `Last scan`-style timestamps), and remember the agent's own
+  writes are filtered out (see `AgentWriteTracker`) — make sure the
+  commit was authored by you.
+
+## Related
+
+- [Git integration](../integrations/git.md) — the underlying observer
+  contract and `gitPollIntervalSeconds` semantics.
+- [GitHub integration](../integrations/github.md) — remote-side data
+  (notifications, workflow runs) reachable via `gh` even without a
+  local clone.
+- [Hourly check](../routines/hourly-check.md) — the routine that
+  consumes the observations this page's polling generates.

package/agent-assets/docs/features/lifestyle/reading.md

@@ -0,0 +1,93 @@
+---
+schema_version: 1
+slug: features/lifestyle/reading
+title: Reading
+id: reading
+aliases:
+  - reading list
+  - books
+  - read later
+category: features
+summary: |
+  Track books and Kindle highlights in a SQLite-backed reading list
+  surfaced at /reading. The schema covers title/author/status plus a
+  separate reading_highlights table populated from Kindle clipping
+  imports.
+section: lifestyle
+tags:
+  - lifestyle
+  - reading
+  - memory
+status: stable
+ask_examples:
+  - How do I add a book to my reading list?
+  - Can the agent recommend something from my reading list?
+  - Where do reading-list items get stored?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - reading
+  - books
+  - articles
+  - read later
+related:
+  - features/memory-files/user-profile
+  - features/lifestyle/receipts
+  - features/lifestyle/travel-bookings
+ui_anchors:
+  - /reading
+---
+
+# Reading
+
+## In One Sentence
+
+A reading list backed by the `books` and `reading_highlights` SQLite
+tables: imports Kindle clippings, tracks status (`reading`/`finished`/etc.),
+and surfaces the working set at `/reading`.
+
+## What It Does
+
+- **Add** items by DM ("agent, add 'The Soul of a New Machine' to my
+  reading list") — the agent inserts into `books` via the daemon
+  `/api/books` route.
+- **Import Kindle highlights** via `POST /api/books/import-clippings`,
+  which parses a `My Clippings.txt` paste and populates the
+  `reading_highlights` table linked back to `books.id`.
+- **List** what's outstanding on `/reading`.
+- **Mark complete** — the agent updates the row's `status` and
+  `completed_at` columns.
+- **Recommend** from the list during reactive turns when context
+  invites it.
+
+There is no Markdown context file for the reading list; the durable
+record is the SQLite row. If you want a parallel copy in your external
+Obsidian or Notion vault, ask the agent to write one — the list itself
+stays canonical in the database.
+
+## When It Runs / How It Is Triggered
+
+Reactive only. There is no autonomous reading-list routine in the
+default install — the operator drives the list shape.
+
+## What It Outputs
+
+- Rows in the `books` table (with status, dates, optional rating /
+  notes) and linked rows in `reading_highlights`.
+- A clean operator-facing view on `/reading`.
+
+## Where in the Dashboard
+
+- **Reading (`/reading`)** is the operator surface.
+
+## When Something Goes Wrong
+
+- A **missing add**: check the Activity row's tool calls — the agent
+  hits `/api/books`, so a network or quota error there will surface in
+  the audit log even when the chat reply looked fine.
+
+## Related
+
+- [Receipts](receipts.md)
+- [Travel Bookings](travel-bookings.md)