@aitne-sh/aitne 0.1.0

package/agent-assets/docs/features/messaging/dashboard-chat.md

@@ -0,0 +1,93 @@
+---
+schema_version: 1
+slug: features/messaging/dashboard-chat
+title: Dashboard Chat
+id: dashboard-chat
+aliases:
+  - chat
+  - in-browser chat
+  - dashboard chat
+  - /chat
+category: features
+summary: |
+  The /chat page is an in-browser DM channel. It uses its own
+  ProcessKey (dashboard.chat) and binds to whichever backend the
+  operator picked on /settings/models — independent of the paired
+  messaging app.
+section: messaging
+tags:
+  - core
+  - messaging
+  - dashboard
+status: stable
+ask_examples:
+  - What does /chat do that DMs don't?
+  - How is dashboard chat different from a Telegram DM?
+  - Why are my dashboard chat replies different from my Telegram replies?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - chat
+  - dashboard
+  - in-browser
+related:
+  - features/messaging/overview
+  - concepts/backends-and-tiers
+  - features/operations/activity-and-conversations
+ui_anchors:
+  - /chat
+---
+
+# Dashboard Chat
+
+## In One Sentence
+
+`/chat` is a browser-mounted DM with the agent — a fully featured
+conversational surface separate from any paired messaging app.
+
+## What It Does
+
+- **Real-time** message stream over SSE.
+- **Tool progress** rendered inline (which tool, which file, which
+  endpoint) so you can watch the agent work.
+- **Session history** persisted to SQLite (`scope='dashboard_chat'`)
+  and visible from Activity → Conversations.
+- **Independent backend binding** — `dashboard.chat` is its own
+  ProcessKey, so the model used here can differ from the one your
+  Telegram DM uses.
+
+## When It Runs / How It Is Triggered
+
+Whenever you press send. The page connects to `POST /api/chat/messages`
+to enqueue and `GET /api/chat/stream` to listen.
+
+## What It Outputs
+
+- Inline tool calls and replies.
+- Persisted messages under the chat session.
+
+## Where in the Dashboard
+
+- **Chat (`/chat`)** is the live surface.
+- **Conversations** lets you re-open a past session.
+
+## Configuration
+
+- **Settings → Models** lets you pick which backend `dashboard.chat`
+  binds to (default: same as `message.dm`, but operator-overridable).
+- **Settings → Models → Session Timeouts → Dashboard Timeout** is the
+  per-session wall-clock cap for `/chat`.
+
+## When Something Goes Wrong
+
+- A **stalled session** with no progress: check Activity for the
+  session row — it may be waiting for an SSE event the daemon
+  dropped.
+- A **chat that uses the wrong model**: check `/settings/models` —
+  `dashboard.chat`'s row is independent from `message.dm`'s.
+
+## Related
+
+- [Messaging Overview](overview.md)
+- [Backends and Tiers](../../concepts/backends-and-tiers.md)

package/agent-assets/docs/features/messaging/discord.md

@@ -0,0 +1,50 @@
+---
+schema_version: 1
+slug: features/messaging/discord
+title: Discord
+id: discord
+category: features
+summary: |
+  Pair Discord by creating a bot in the developer portal, pasting the
+  token into Aitne, and DMing the magic phrase from your
+  Discord account.
+section: messaging
+tags:
+  - messaging
+  - integration
+status: stable
+ask_examples:
+  - How do I pair Discord?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/overview
+  - features/messaging/pairing-and-magic-phrase
+---
+
+# Discord
+
+## In One Sentence
+
+A Discord bot becomes the agent's surface; pair via DM after
+installing the bot in the developer portal.
+
+## What It Does
+
+- Listens for DMs from the paired owner.
+- Listens for mentions in shared servers.
+- Sends notifications back via DM.
+
+## Where in the Dashboard
+
+- **Connections → Messaging → Discord**.
+
+## When Something Goes Wrong
+
+- DMs disabled in the operator's privacy settings: enable "Allow
+  direct messages from server members".
+
+## Related
+
+- [Messaging Overview](overview.md)

package/agent-assets/docs/features/messaging/overview.md

@@ -0,0 +1,111 @@
+---
+schema_version: 1
+slug: features/messaging/overview
+title: Messaging Overview
+id: messaging-overview
+aliases:
+  - messaging
+  - dms
+  - direct messages
+  - messaging apps
+  - notifications
+category: features
+summary: |
+  Pair Aitne with one or more messaging apps (Telegram, Slack,
+  Discord, WhatsApp). DMs become the primary reactive channel; the
+  agent uses the same channel to send notifications back.
+section: messaging
+tags:
+  - core
+  - messaging
+status: stable
+ask_examples:
+  - How do I pair my phone with the agent?
+  - Which messaging apps does the agent support?
+  - Why didn't I get a notification?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - messaging
+  - dm
+  - pairing
+  - telegram
+  - slack
+  - discord
+  - whatsapp
+related:
+  - features/messaging/pairing-and-magic-phrase
+  - features/messaging/telegram
+  - features/messaging/slack
+  - features/messaging/discord
+  - features/messaging/whatsapp
+  - features/messaging/dashboard-chat
+  - features/operations/notifications
+  - features/operations/quiet-hours
+ui_anchors:
+  - /connections
+  - /connections/messaging
+  - /settings/connections
+  - /settings/commands
+---
+
+# Messaging Overview
+
+## In One Sentence
+
+Aitne treats DMs from a paired messaging app as its primary
+reactive surface — you message it, it answers; it messages you when a
+notification fires.
+
+## What It Does
+
+- **Reactive DMs**: the agent answers every direct message you send.
+- **Mentions**: in shared channels, @-mentioning the agent answers
+  the same way (group chat is filtered out by design — DMs only).
+- **Outbound notifications**: routines and observations fire alerts
+  back through the same channel.
+- **Magic-phrase pairing**: the operator types a one-time phrase to
+  bind their account to the agent (anti-impersonation).
+
+Aitne is **single-owner** by design. Any DM that does not
+match a paired owner channel is dropped (defense in depth — the
+adapter and the dispatcher both check).
+
+## When It Runs / How It Is Triggered
+
+- The messaging adapter for each connected platform polls / receives
+  webhooks for incoming messages.
+- An incoming DM dispatches to the `message.dm` ProcessKey.
+- An incoming mention dispatches to `message.mention`.
+- Notifications fire as a side-effect of routines and observations
+  reaching the notifier (subject to quiet hours and rate limits).
+
+## What It Outputs
+
+- Replies in the operator's chosen messaging app.
+- Notification messages, batched during quiet hours.
+
+## Where in the Dashboard
+
+- **Connections (`/connections`)** is the unified pairing page.
+- **Connections → Messaging (`/connections/messaging`)** lists each
+  app's status, owner channel, and rate limit settings.
+
+## Configuration
+
+- Per-app: bot token / OAuth, owner channel, optional default channel.
+- Global: `primaryPlatform` (the fallback when multiple apps are paired).
+
+## When Something Goes Wrong
+
+- An **un-paired DM**: the agent ignores it. Pair the app from
+  `/connections/messaging` first.
+- A **notification you expected but did not get**: check quiet hours
+  on `/settings/schedule`.
+
+## Related
+
+- [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Dashboard Chat](dashboard-chat.md) — the in-browser equivalent.
+- [Notifications](../operations/notifications.md)

package/agent-assets/docs/features/messaging/pairing-and-magic-phrase.md

@@ -0,0 +1,69 @@
+---
+schema_version: 1
+slug: features/messaging/pairing-and-magic-phrase
+title: Pairing and Magic Phrase
+id: pairing-and-magic-phrase
+aliases:
+  - magic phrase
+  - pairing
+  - owner pairing
+category: features
+summary: |
+  Pair your messaging account to Aitne by typing a one-time
+  "magic phrase" the dashboard generates. The phrase binds the channel
+  to your owner identity so impersonation is impossible.
+section: messaging
+tags:
+  - core
+  - messaging
+  - pairing
+  - safety
+status: stable
+ask_examples:
+  - How do I pair my Telegram account?
+  - What is the magic phrase?
+  - Can someone else impersonate me?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - pairing
+  - magic phrase
+  - owner
+related:
+  - features/messaging/overview
+---
+
+# Pairing and Magic Phrase
+
+## In One Sentence
+
+The dashboard prints a one-time phrase; you DM that phrase to the
+agent from the messaging app you want to pair; the daemon records the
+channel as your owner channel.
+
+## What It Does
+
+- Prevents drive-by impersonation: a bot can't open a DM and pretend
+  to be the operator without the phrase.
+- Multiple paired channels (e.g. Telegram + Slack) all map to the
+  same owner identity.
+
+## When It Runs / How It Is Triggered
+
+The phrase is generated when the operator clicks "Pair" on
+`/connections/messaging`. The daemon listens for the phrase from any
+incoming DM until paired or the phrase expires.
+
+## Where in the Dashboard
+
+- **Connections → Messaging** is the pairing surface.
+
+## When Something Goes Wrong
+
+- Phrase expired: regenerate it from the dashboard.
+- DM was sent in a group: pairing only works in direct messages.
+
+## Related
+
+- [Messaging Overview](overview.md)

package/agent-assets/docs/features/messaging/slack.md

@@ -0,0 +1,51 @@
+---
+schema_version: 1
+slug: features/messaging/slack
+title: Slack
+id: slack
+category: features
+summary: |
+  Pair a Slack workspace by installing a bot user, pasting tokens
+  into Aitne, and DMing the magic phrase.
+section: messaging
+tags:
+  - messaging
+  - integration
+status: stable
+ask_examples:
+  - How do I pair Slack?
+  - Can the agent listen in shared channels?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/overview
+  - features/messaging/pairing-and-magic-phrase
+---
+
+# Slack
+
+## In One Sentence
+
+A Slack bot user becomes the agent's surface in your workspace; DMs
+to the bot are owner messages, mentions in channels are mention events.
+
+## What It Does
+
+- Listens for DMs (owner reactive path).
+- Listens for `@personalagent` mentions in shared channels.
+- Sends notifications to the owner DM.
+
+## Where in the Dashboard
+
+- **Connections → Messaging → Slack** holds bot tokens, channel info,
+  and the magic-phrase pairing flow.
+
+## When Something Goes Wrong
+
+- Bot does not respond: check that the workspace bot has been added
+  to the channel where the DM is happening.
+
+## Related
+
+- [Messaging Overview](overview.md)

package/agent-assets/docs/features/messaging/telegram.md

@@ -0,0 +1,63 @@
+---
+schema_version: 1
+slug: features/messaging/telegram
+title: Telegram
+id: telegram
+aliases:
+  - telegram bot
+category: features
+summary: |
+  Pair Telegram by creating a bot via @BotFather, pasting the token
+  into Aitne, and DMing the magic phrase.
+section: messaging
+tags:
+  - messaging
+  - integration
+  - core
+status: stable
+ask_examples:
+  - How do I pair Telegram?
+  - Where do I get a Telegram bot token?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/pairing-and-magic-phrase
+  - features/messaging/overview
+---
+
+# Telegram
+
+## In One Sentence
+
+The fastest messaging app to pair: create a Telegram bot, paste the
+token, type the magic phrase.
+
+## What It Does
+
+- Acts as the agent's reactive surface for incoming DMs.
+- Receives outbound notifications.
+
+## When It Runs / How It Is Triggered
+
+Continuously listening to Telegram's long-polling API once paired.
+
+## Where in the Dashboard
+
+- **Connections → Messaging → Telegram**.
+
+## Configuration
+
+| Field | Notes |
+|---|---|
+| Bot Token | From @BotFather. |
+| Owner Channel | Auto-set on successful magic-phrase pairing. |
+
+## When Something Goes Wrong
+
+- Bot replied to in a group instead of a DM: group chats are filtered
+  out by design; the agent only listens to direct messages.
+
+## Related
+
+- [Pairing & Magic Phrase](pairing-and-magic-phrase.md)

package/agent-assets/docs/features/messaging/whatsapp.md

@@ -0,0 +1,48 @@
+---
+schema_version: 1
+slug: features/messaging/whatsapp
+title: WhatsApp
+id: whatsapp
+category: features
+summary: |
+  Pair WhatsApp via the Cloud API or a bridge service. Once paired, DMs
+  to the configured number are owner messages.
+section: messaging
+tags:
+  - messaging
+  - integration
+status: stable
+ask_examples:
+  - Can I use WhatsApp with Aitne?
+  - How do I set up the WhatsApp Cloud API?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/overview
+---
+
+# WhatsApp
+
+## In One Sentence
+
+A WhatsApp Cloud API number can act as the agent's owner surface; DMs
+flow exactly like Telegram.
+
+## What It Does
+
+- Receives WhatsApp messages routed through the configured number.
+- Sends notifications back through the same channel.
+
+## Where in the Dashboard
+
+- **Connections → Messaging → WhatsApp**.
+
+## When Something Goes Wrong
+
+- WhatsApp's webhook timed out: check that the daemon is reachable
+  from the WhatsApp side (the simplest way is a tunnel during dev).
+
+## Related
+
+- [Messaging Overview](overview.md)

package/agent-assets/docs/features/operations/activity-and-conversations.md

@@ -0,0 +1,105 @@
+---
+schema_version: 1
+slug: features/operations/activity-and-conversations
+title: Activity and Conversations
+id: activity-and-conversations
+aliases:
+  - activity feed
+  - conversations
+  - history
+  - audit log
+category: features
+summary: |
+  The Activity view is the audit timeline of everything the agent did;
+  Conversations is the per-session message transcript. Together they
+  answer "what happened" and "what was said".
+section: operations
+tags:
+  - core
+  - operations
+  - audit
+status: stable
+ask_examples:
+  - Where can I see what the agent did today?
+  - Where do I read the morning routine's full reply?
+  - How do I find why a routine failed?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - activity
+  - conversations
+  - audit
+  - timeline
+  - sessions
+related:
+  - features/operations/notifications
+  - features/operations/cost-tracking
+  - features/operations/backend-routing
+ui_anchors:
+  - /
+  - /activity
+  - /conversations
+---
+
+# Activity and Conversations
+
+## In One Sentence
+
+Every agent session, action, and outcome is logged to SQLite and
+surfaced as the Activity timeline; the matching message-by-message
+detail lives one click deeper under Conversations.
+
+## What It Does
+
+Activity is the unified view of:
+
+- **Routines**: morning, evening, weekly, monthly, hourly fires.
+- **Reactive sessions**: DMs, dashboard chat, mentions.
+- **Background actions**: notifications sent, mail labeled, schedule
+  files written.
+- **Failures**: timeouts, fallbacks, blocked tool calls, quota errors.
+
+Each row links to the underlying conversation when one exists.
+
+## When It Runs / How It Is Triggered
+
+There is no trigger — Activity is a read-only projection. It is
+written to as a side-effect of every other event in the system
+(`agent_actions` / `conversation_sessions` / `messages`).
+
+## What It Outputs
+
+- A timeline filterable by event type, ProcessKey, backend, outcome.
+- Per-row cost, token counts, and turn count.
+- A direct link to the message transcript for any session.
+
+## Where in the Dashboard
+
+- **Overview (`/`)** shows the most recent few activity rows.
+- **Activity (`/activity`)** is the full searchable timeline.
+- **Conversations (`/conversations/<id>`)** opens a single session's
+  message-by-message transcript.
+
+## Configuration
+
+There is nothing to configure on the Activity view itself; what shows
+up is a function of which routines are enabled and which integrations
+are connected. Retention is unlimited locally — the SQLite database
+keeps everything until you `pa stop && rm ~/.personal-agent/data/personal_agent.db`.
+
+## When Something Goes Wrong
+
+- A row showing **"timed out"** points at a backend or SDK hang.
+  `executeTimeoutMinutes` (`/settings/models`) is the wall-clock cap.
+- A row showing **"fallback"** means main backend failed; check the
+  detail for the `BackendQuotaError` / `BackendDecisiveFailure`.
+- A row showing **"blocked_absolute"** means the absolute-block layer
+  refused a tool call. The detail names which tool and why.
+
+## Related
+
+- [Notifications](notifications.md) — what the agent told you about,
+  separate from what it did.
+- [Cost Tracking](cost-tracking.md) — the cost-rollup view.
+- [Backend Routing](backend-routing.md) — how main → fallback resolves.

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

@@ -0,0 +1,58 @@
+---
+schema_version: 1
+slug: features/operations/approvals
+title: Approvals
+id: approvals
+aliases:
+  - approve tier
+  - approval queue
+  - human in the loop
+category: features
+summary: |
+  Approve-tier actions block until the operator clicks approve in
+  the dashboard. They bypass quiet hours.
+section: operations
+tags:
+  - core
+  - safety
+  - operations
+status: stable
+ask_examples:
+  - What is an approval?
+  - Why is the agent waiting for me?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/safety-and-execution
+  - features/operations/notifications
+---
+
+# Approvals
+
+## In One Sentence
+
+A small set of high-blast-radius actions queue as approvals; the
+agent waits for an operator click before proceeding.
+
+## What It Does
+
+- Blocks the action.
+- Shows it on the Overview page's approval card.
+- Sends a notification (bypasses quiet hours by design).
+- Resumes when the operator approves.
+
+## Where in the Dashboard
+
+- **Overview** shows the count badge.
+- The approvals card lists pending items with diff previews.
+
+## When Something Goes Wrong
+
+- An approval that hangs: the agent's session may have timed out.
+  The action expires when the session does; the operator must redo
+  the request that produced it.
+
+## Related
+
+- [Safety and Execution](../../concepts/safety-and-execution.md)