@aitne-sh/aitne 0.1.0

package/agent-assets/docs/features/operations/backend-routing.md

@@ -0,0 +1,62 @@
+---
+schema_version: 1
+slug: features/operations/backend-routing
+title: Backend Routing
+id: backend-routing
+aliases:
+  - router
+  - main fallback
+  - failover
+category: features
+summary: |
+  BackendRouter resolves each ProcessKey to a (main, fallback) backend
+  pair and a tier. On BackendQuotaError or BackendDecisiveFailure, the
+  main backend's session fails over to the fallback's.
+section: operations
+tags:
+  - core
+  - operations
+  - backends
+status: stable
+ask_examples:
+  - What happens when my Claude quota is exhausted?
+  - Why did my routine run on Codex when I picked Claude?
+  - How do fallbacks work?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/backends-and-tiers
+  - features/operations/cost-tracking
+---
+
+# Backend Routing
+
+## In One Sentence
+
+Each ProcessKey resolves to a `(main, fallback)` pair and a tier; on
+quota or decisive failure, the dispatcher transitions to the fallback
+mid-run.
+
+## What It Does
+
+- Reads the `process_backend_config` table to find the binding.
+- Falls back to the default tier map when no override exists.
+- Re-materializes the session workdir for the fallback backend's
+  instruction file and skill set.
+
+## Where in the Dashboard
+
+- **Settings → Models** is the unified surface for picking main and
+  fallback per ProcessKey.
+- **Activity** rows show which backend actually served each turn after
+  fallback resolution.
+
+## When Something Goes Wrong
+
+- A `fallback-failed` notification: both backends rejected the run.
+  Most often a credentials issue on both sides.
+
+## Related
+
+- [Backends and Tiers](../../concepts/backends-and-tiers.md)

package/agent-assets/docs/features/operations/cost-tracking.md

@@ -0,0 +1,59 @@
+---
+schema_version: 1
+slug: features/operations/cost-tracking
+title: Cost Tracking
+id: cost-tracking
+aliases:
+  - analytics
+  - cost rollup
+category: features
+summary: |
+  The Analytics page rolls cost up by ProcessKey, by backend, and by
+  agent day. The sidebar footer shows the running daily total.
+section: operations
+tags:
+  - core
+  - cost
+  - operations
+status: stable
+ask_examples:
+  - How much did the agent cost me today?
+  - Which routines are the most expensive?
+  - How do I cap autonomous spending?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/costs-and-quotas
+config_keys:
+  - autonomousDailyCostCapUsd
+---
+
+# Cost Tracking
+
+## In One Sentence
+
+A rolling rollup of token-cost per session, indexed by ProcessKey,
+backend, and agent day.
+
+## What It Does
+
+- Records per-execute cost into `agent_actions`.
+- Aggregates into the Analytics page's charts.
+- Surfaces the running daily total in the sidebar footer.
+
+## Where in the Dashboard
+
+- **Analytics** is the rollup.
+- **Settings → Models → Cost Guardrails** holds
+  `autonomousDailyCostCapUsd`.
+
+## When Something Goes Wrong
+
+- A cost number that looks wrong: cross-check against the backend's
+  own dashboard. Aitne's count is its best estimate from
+  per-call token math.
+
+## Related
+
+- [Costs and Quotas](../../concepts/costs-and-quotas.md)

package/agent-assets/docs/features/operations/notifications.md

@@ -0,0 +1,69 @@
+---
+schema_version: 1
+slug: features/operations/notifications
+title: Notifications
+id: notifications
+aliases:
+  - notify
+  - notification
+  - alerts
+category: features
+summary: |
+  Notifications are the agent's outbound DMs to the operator. They
+  fire from routines, observations, and approvals. Quiet hours and
+  rate limits gate the flow.
+section: operations
+tags:
+  - core
+  - notifications
+  - operations
+status: stable
+ask_examples:
+  - When does the agent send me a notification?
+  - How do I limit how often it notifies me?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/operations/quiet-hours
+  - features/operations/approvals
+  - features/messaging/overview
+config_keys:
+  - maxNotificationsPerHour
+  - maxNotificationsPerDay
+  - batchIntervalMinutes
+  - primaryPlatform
+---
+
+# Notifications
+
+## In One Sentence
+
+Outbound DMs the agent sends through the paired messaging app, gated
+by quiet hours and rate limits.
+
+## What It Does
+
+- Routines and observations enqueue notifications.
+- Quiet hours hold notifications until the window ends.
+- Per-hour and per-day rate limits cap the volume.
+- Batching folds multiple small alerts into a single message.
+
+## Configuration
+
+| Setting | Default |
+|---|---|
+| `maxNotificationsPerHour` | 3 |
+| `maxNotificationsPerDay` | 12 |
+| `batchIntervalMinutes` | 15 |
+| `primaryPlatform` | first paired |
+
+## When Something Goes Wrong
+
+- A notification you expected: check the rate-limit counters and the
+  quiet-hours window.
+
+## Related
+
+- [Quiet Hours](quiet-hours.md)
+- [Approvals](approvals.md)

package/agent-assets/docs/features/operations/quiet-hours.md

@@ -0,0 +1,106 @@
+---
+schema_version: 1
+slug: features/operations/quiet-hours
+title: Quiet Hours
+id: quiet-hours
+aliases:
+  - do not disturb
+  - dnd
+  - notifications off
+  - silent hours
+category: features
+summary: |
+  A nightly silent window during which the agent suppresses
+  notifications. Routines still run, but their output queues until
+  morning instead of waking you.
+section: operations
+tags:
+  - operations
+  - notifications
+  - core
+status: stable
+ask_examples:
+  - How do I stop notifications at night?
+  - When does the agent go silent?
+  - Will routines still run during quiet hours?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - quiet hours
+  - dnd
+  - quietHoursStart
+  - quietHoursEnd
+related:
+  - features/operations/notifications
+  - features/operations/approvals
+  - concepts/agent-day
+ui_anchors:
+  - /settings/schedule
+config_keys:
+  - quietHoursStart
+  - quietHoursEnd
+---
+
+# Quiet Hours
+
+## In One Sentence
+
+Set a nightly window (default 22:00 → 08:00) during which the agent
+batches notifications instead of pushing them to the messaging app
+in real time.
+
+## What It Does
+
+During quiet hours:
+
+- **Notifications** are queued, not sent. They flush at the end of the
+  window or get folded into the morning routine's "good morning" message.
+- **Routines** keep running. The morning routine fires at
+  `dayBoundaryHour` (the same time the agent-day rolls over) — even
+  if that falls inside quiet hours, the routine runs and its output
+  is batched until the window ends.
+- **Reactive DMs** still respond. Quiet hours only suppress
+  *agent-initiated* messages.
+
+## When It Runs / How It Is Triggered
+
+Continuously. Every notification dispatcher checks `quietHoursStart`
+and `quietHoursEnd` against the current local time before sending.
+The window is allowed to wrap midnight (22:00 → 08:00 is the default
+shape).
+
+## What It Outputs
+
+- An empty notification queue during the window.
+- A consolidated "while you were away" summary at flush time when
+  many notifications batched up.
+
+## Where in the Dashboard
+
+- **Settings → Schedule** holds `quietHoursStart` and `quietHoursEnd`.
+  The form refuses windows that overlap the active hours.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `quietHoursStart` | `"22:00"` | `HH:MM` local time string. |
+| `quietHoursEnd` | `"08:00"` | `HH:MM` local time string. |
+| `batchIntervalMinutes` | `15` | How often the batched flush runs once awake. |
+
+## When Something Goes Wrong
+
+- An **important** notification that you expected to wake you
+  during quiet hours: Aitne does not have a notify-anyway
+  override yet (Approvals are the only thing that bypass quiet hours).
+  If you need real-time night alerts for, say, a critical mail label,
+  the workaround is to disable quiet hours.
+- A notification that fired *after* the window ended but feels stale:
+  check `batchIntervalMinutes` — if you set it long, the flush can
+  lag the window end by several minutes.
+
+## Related
+
+- [Notifications](notifications.md) — the broader notification model.
+- [Approvals](approvals.md) — the only tier that bypasses quiet hours.

package/agent-assets/docs/features/operations/schedule-approaching.md

@@ -0,0 +1,60 @@
+---
+schema_version: 1
+slug: features/operations/schedule-approaching
+title: Schedule Approaching
+id: schedule-approaching
+aliases:
+  - schedule reminders
+  - approaching event
+category: features
+summary: |
+  Lightweight pre-event nudges fire when a calendar event is close
+  enough to remind the operator about. The lead time is configurable.
+section: operations
+tags:
+  - operations
+  - calendar
+  - notifications
+status: stable
+ask_examples:
+  - How does the agent remind me about meetings?
+  - Can I change the lead time?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/integrations/calendar
+  - features/operations/notifications
+---
+
+# Schedule Approaching
+
+## In One Sentence
+
+Pre-event reminders fire on a configurable lead time before each
+calendar event.
+
+## What It Does
+
+- Watches the calendar event queue.
+- Fires a notification N minutes before each event.
+- Optionally includes the travel-time estimate when the event has
+  a location and the travel-time skill is enabled.
+
+## When It Runs / How It Is Triggered
+
+The scheduler keeps a sorted view of upcoming events; a tick at the
+event's lead-time mark fires the notification.
+
+## Where in the Dashboard
+
+- **Settings → Schedule** holds the lead-time options.
+
+## When Something Goes Wrong
+
+- A reminder you expected: confirm the calendar integration is
+  reading the right calendar (some operators have multiple).
+
+## Related
+
+- [Calendar](../integrations/calendar.md)

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

@@ -0,0 +1,101 @@
+---
+schema_version: 1
+slug: features/routines/custom-routines
+title: Custom Routines
+id: custom-routines
+aliases:
+  - custom routine
+  - cron routine
+  - user routine
+category: features
+summary: |
+  Beyond the built-in morning / evening / weekly / monthly / hourly
+  routines, the operator can define custom routines that fire on any
+  cron schedule.
+section: routines
+tags:
+  - routine
+  - autonomous
+  - advanced
+status: stable
+ask_examples:
+  - How do I add a custom routine?
+  - What can a custom routine do?
+  - Can I disable a custom routine?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - guides/add-a-custom-routine
+  - concepts/routines
+process_keys:
+  - routine.custom.<slug>
+---
+
+# Custom Routines
+
+## In One Sentence
+
+Operator-defined routines fire at any cron schedule, run under the
+backend the operator picks (light / heavy tier), and are bounded by
+the same safety layers as the built-ins.
+
+## What It Does
+
+- Runs a vault-file-defined check list at a cron schedule.
+- Resolves the backend at fire time from the chosen tier (no concrete
+  model picker — tier resolution mirrors the built-in routines).
+- Logs its run to Activity exactly like a built-in routine.
+
+## When It Runs / How It Is Triggered
+
+The cron expression in the routine's vault file
+`routines/custom/<slug>.md`. The custom-routine scheduler watches the
+file and re-reads the frontmatter on every change.
+
+## What It Outputs
+
+- Whatever the check list produces — a context-file write, a
+  notification, a no-op.
+
+## Where in the Dashboard
+
+- **Settings → Routines** is the operator surface for adding,
+  editing, and disabling. (The `/connections/routines` URL is a
+  back-compat alias that redirects here.)
+
+## Configuration
+
+Each custom routine is a Markdown file under
+`~/.personal-agent/context/routines/custom/<slug>.md` whose
+frontmatter carries:
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | `rule` | Always `rule` for custom routines. |
+| `slug` | string | Kebab-case; matches the file stem and the ProcessKey suffix. |
+| `cron` | string | Standard 5-field cron expression (e.g. `0 11 * * 2`). |
+| `process_key` | `routine.custom.<slug>` | Must match the slug. |
+| `enabled` | boolean | Disable without deleting by setting `false`. |
+| `backend_tier` | `light` \| `heavy` | Drives BackendRouter tier resolution. |
+| `max_budget_usd` | number | Per-execute USD cap (e.g. `0.05`). |
+
+The body holds the `## Checks` section the agent runs through on each
+fire. Hand-editing the file is fully supported — the watcher picks up
+changes without a daemon restart.
+
+> **Distinct from `recurring_schedules`.** The `recurring_schedules`
+> table powers DM-style scheduled tasks (`agent.task` /
+> `agent.dm_task`) — e.g. "remind me at 9am every weekday". Those
+> use a structured `RecurrenceRule` (frequency + time + dayOf*) and
+> are managed via `POST /api/recurring-schedules`. They are not the
+> same surface as `routine.custom.<slug>`.
+
+## When Something Goes Wrong
+
+- A cron expression that resolves to "never": the routine appears in
+  the list but never fires. The dashboard shows next-fire as N/A.
+
+## Related
+
+- [Add a Custom Routine](../../guides/add-a-custom-routine.md)

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

@@ -0,0 +1,81 @@
+---
+schema_version: 1
+slug: features/routines/evening-review
+title: Evening Review
+id: evening-review
+aliases:
+  - evening routine
+  - end of day
+  - retro
+category: features
+summary: |
+  The evening review fires once per day at 18:00 local time. It writes
+  the day's retrospective into the agent journal and rolls up unfinished
+  items for tomorrow's plan.
+section: routines
+tags:
+  - routine
+  - autonomous
+  - daily
+  - light-tier
+status: stable
+ask_examples:
+  - When does the evening review run?
+  - What does the evening review write?
+  - How do I disable it?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - evening review
+  - retro
+  - end of day
+related:
+  - concepts/routines
+  - features/memory-files/agent-journal
+  - features/routines/morning-routine
+process_keys:
+  - routine.evening_review
+---
+
+# Evening Review
+
+## In One Sentence
+
+A light-tier routine that fires daily at 18:00 local time and writes
+the day's retro into the journal.
+
+## What It Does
+
+- Reads the day's `today.md`, the journal entries, the activity feed.
+- Writes a short retrospective into `agent/journal.md`.
+- Surfaces uncompleted carry-over items the morning routine should
+  re-pick-up tomorrow.
+
+## When It Runs / How It Is Triggered
+
+Every day at **18:00 local time**, exactly once. The cron expression
+is fixed in `packages/daemon/src/core/scheduler.ts` and is not
+operator-configurable.
+
+## What It Outputs
+
+- An `agent/journal.md` entry.
+- A "today wraps up here" notification (subject to quiet hours).
+
+## Where in the Dashboard
+
+- **Connections → Journal** shows the appended entry.
+
+## Configuration
+
+This routine has no operator-tunable knobs. The fire time and tier
+are fixed in code.
+
+## When Something Goes Wrong
+
+- A journal that **stops growing**: see [Auth Failed](../../troubleshooting/auth-failed.md) — the routine may be hitting a quota wall.
+
+## Related
+
+- [agent/journal.md](../memory-files/agent-journal.md)

package/agent-assets/docs/features/routines/hourly-check.md

@@ -0,0 +1,85 @@
+---
+schema_version: 1
+slug: features/routines/hourly-check
+title: Hourly Check
+id: hourly-check
+aliases:
+  - hourly
+  - observation consumer
+category: features
+summary: |
+  A light-tier routine that fires every hour during active hours and
+  consumes accumulated observations from the polling integrations.
+section: routines
+tags:
+  - routine
+  - autonomous
+  - light-tier
+status: stable
+ask_examples:
+  - What does the hourly check do?
+  - When does it run?
+  - How do I tune the threshold?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - hourly
+  - observations
+  - polling
+related:
+  - concepts/observations
+  - concepts/routines
+process_keys:
+  - routine.hourly_check
+config_keys:
+  - hourlyCheckEnabled
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckActiveStartHour
+  - hourlyCheckActiveEndHour
+  - hourlyCheckMinObservations
+---
+
+# Hourly Check
+
+## In One Sentence
+
+A light-tier routine that empties the observations queue and decides
+whether the accumulated changes warrant a notification.
+
+## What It Does
+
+- Reads pending `observations` rows.
+- Decides whether the pattern adds up to something worth surfacing.
+- Either appends to `today.md` or sends a notification (or both).
+
+## When It Runs / How It Is Triggered
+
+Every `hourlyCheckIntervalMinutes` (default 60), inside the active
+window (`hourlyCheckActiveStartHour` to `hourlyCheckActiveEndHour`).
+Skips when the morning routine is in progress; an atomic flag
+prevents two hourly checks from running at once.
+
+## What It Outputs
+
+- Updates to `today.md`.
+- Notifications when warranted.
+
+## Configuration
+
+| Setting | Default |
+|---|---|
+| `hourlyCheckEnabled` | true |
+| `hourlyCheckIntervalMinutes` | 60 |
+| `hourlyCheckActiveStartHour` | 4 |
+| `hourlyCheckActiveEndHour` | 24 (end-exclusive, ≡ midnight) |
+| `hourlyCheckMinObservations` | 1 |
+
+## When Something Goes Wrong
+
+- Skipped hourly checks below the min-observations threshold are
+  expected. The daemon log shows the skip reason.
+
+## Related
+
+- [Observations](../../concepts/observations.md)

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

@@ -0,0 +1,65 @@
+---
+schema_version: 1
+slug: features/routines/monthly-review
+title: Monthly Review
+id: monthly-review
+aliases:
+  - monthly retro
+category: features
+summary: |
+  Once a month, the agent rolls up the four weekly retros into a
+  single monthly synthesis under monthly/<YYYY-MM>.md.
+section: routines
+tags:
+  - routine
+  - autonomous
+  - light-tier
+status: stable
+ask_examples:
+  - When does the monthly review fire?
+  - Where do monthly retros live?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/routines/weekly-review
+process_keys:
+  - routine.monthly_review
+---
+
+# Monthly Review
+
+## In One Sentence
+
+Light-tier monthly retro that synthesizes the four weekly reviews into
+a single monthly file.
+
+## What It Does
+
+- Reads the past month of weekly retros.
+- Surfaces threads, recurring patterns, and unfinished pushes.
+- Writes the synthesis into `monthly/<YYYY-MM>.md`.
+
+## When It Runs / How It Is Triggered
+
+The **last day of the calendar month at 18:00 local time**. The schedule
+is fixed in `packages/daemon/src/core/scheduler.ts` and is not
+operator-configurable.
+
+## What It Outputs
+
+- A single `monthly/<YYYY-MM>.md` file.
+
+## Configuration
+
+This routine has no operator-tunable knobs. The fire time, day-of-month,
+and tier are fixed in code.
+
+## When Something Goes Wrong
+
+- A late-month install will skip the first month's retro because
+  there are not four weekly retros to synthesize yet.
+
+## Related
+
+- [Weekly Review](weekly-review.md)