@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -7,63 +7,130 @@ aliases:
   - magic phrase
   - pairing
   - owner pairing
+  - pair my messaging account
 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.
+  Pair a messaging account to Aitne so the daemon knows which DM channel
+  belongs to you, the owner. Slack and Discord use a one-time "magic
+  phrase" you DM from the app; Telegram uses a QR / deep-link token;
+  WhatsApp links the device by scanning a QR. All of them bind the channel
+  to your owner identity so nobody else can impersonate you.
 section: messaging
 tags:
   - core
   - messaging
   - pairing
   - safety
+  - setup
 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
+updated: 2026-05-28
 keywords:
   - pairing
   - magic phrase
-  - owner
+  - owner channel
+  - QR pairing
+  - impersonation
+ask_examples:
+  - How do I pair my Telegram account?
+  - What is the magic phrase?
+  - Can someone else impersonate me as the owner?
+  - Why didn't my pairing DM work?
+ui_anchors:
+  - /connections/messaging
 related:
   - features/messaging/overview
+  - features/messaging/slack
+  - features/messaging/telegram
+  - features/messaging/discord
+  - features/messaging/whatsapp
+  - troubleshooting/messaging-not-pairing
 ---
 
 # Pairing and Magic Phrase
 
-## In One Sentence
+## In one sentence
+
+The dashboard hands you a one-time secret (a typed phrase, a QR code, or
+a deep link, depending on the platform); you send or scan it from the
+messaging app you want to pair; the daemon records that channel as your
+owner channel.
+
+## Why pairing exists
+
+The agent only talks to one person — you, the owner. Pairing is how the
+daemon learns which DM channel is yours.
+
+- **Impersonation protection.** A random bot or stranger can't open a DM
+  and claim the owner role without the secret. Only someone who can see
+  the dashboard can complete the pairing.
+- **One identity, many channels.** Pair Slack, Telegram, Discord, and
+  WhatsApp separately; all of them map to the same owner identity. A DM
+  to any paired channel reaches the agent, and notifications can go out on
+  whichever channels you've configured.
+
+## How each platform pairs
+
+Pairing starts the same way everywhere — open
+**Connections → Messaging** (`/connections/messaging`), find the
+platform's card, and click its pairing button. What you do next depends
+on the platform.
+
+| Platform | Mechanism | What you do |
+|---|---|---|
+| **Slack** | Magic phrase | Dashboard shows a 4-word phrase (e.g. `apple-banana-cherry-date`). DM that phrase to the bot, by itself. |
+| **Discord** | Magic phrase | Same as Slack — DM the displayed phrase to the bot. |
+| **Telegram** | QR / deep link | Dashboard shows a QR code that opens a `https://t.me/<bot>?start=<token>` link. Tap **START** in Telegram. |
+| **WhatsApp** | Device QR | Dashboard shows a QR code; scan it from WhatsApp on your phone (Linked Devices). |
+
+### The magic phrase (Slack, Discord)
 
-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.
+The dashboard generates a short, memorable phrase of four lowercase words
+joined by hyphens, drawn from a 64-word list (24 bits of entropy). You DM
+that exact phrase to the bot. Matching is tolerant — it ignores case,
+punctuation, and emoji — but the phrase must be **sent by itself**. If you
+wrap it in a sentence ("my phrase is apple-banana-cherry-date"), the agent
+will reply asking you to send the phrase on its own.
 
-## What It Does
+The phrase is single-use and expires after **5 minutes**. If it lapses,
+regenerate a fresh one from the dashboard.
 
-- 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.
+### Token pairing (Telegram, WhatsApp)
 
-## When It Runs / How It Is Triggered
+Telegram and WhatsApp don't use a typed phrase:
 
-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.
+- **Telegram** encodes a high-entropy, single-use token in a QR / deep
+  link. Tapping **START** sends `/start <token>` to the bot, which
+  promotes you to owner. The token is matched exactly and also expires
+  after 5 minutes.
+- **WhatsApp** uses WhatsApp's own linked-device flow — you scan a QR from
+  your phone to attach the daemon as a device. Set the owner phone number
+  first, then click **Pair device** and scan.
 
-## Where in the Dashboard
+## Where in the dashboard
 
-- **Connections → Messaging** is the pairing surface.
+**Connections → Messaging** (`/connections/messaging`) is the single
+pairing surface. Each platform has its own card with a step-by-step setup
+(create the app / paste tokens / pair) and a live status indicator that
+flips to "paired" once the channel is bound.
 
-## When Something Goes Wrong
+## When something goes wrong
 
-- Phrase expired: regenerate it from the dashboard.
-- DM was sent in a group: pairing only works in direct messages.
+- **Phrase or token expired.** The window is 5 minutes. Regenerate from the
+  dashboard and try again.
+- **"Send the pairing phrase by itself" reply.** You wrapped the phrase in
+  other text. Send just the four words.
+- **DM was sent in a group.** Pairing — and all agent messaging — only works
+  in direct messages. Group chats are out of scope by design.
+- **Still not pairing?** See
+  [Messaging not pairing](../../troubleshooting/messaging-not-pairing.md).
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Slack setup](slack.md)
+- [Telegram setup](telegram.md)
+- [Discord setup](discord.md)
+- [WhatsApp setup](whatsapp.md)
+- [Messaging not pairing (troubleshooting)](../../troubleshooting/messaging-not-pairing.md)

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

@@ -3,49 +3,114 @@ schema_version: 1
 slug: features/messaging/slack
 title: Slack
 id: slack
+aliases:
+  - slack bot
+  - slack adapter
+  - slack pairing
+  - slack DM
 category: features
 summary: |
-  Pair a Slack workspace by installing a bot user, pasting tokens
-  into Aitne, and DMing the magic phrase.
+  Connect a Slack workspace by creating a bot app with Socket Mode,
+  pasting a bot token and an app-level token into Aitne, then DMing
+  the magic phrase to pair yourself as owner.
 section: messaging
 tags:
   - messaging
-  - integration
+  - integrations
+  - slack
+  - pairing
 status: stable
 ask_examples:
   - How do I pair Slack?
+  - Why does the agent need two Slack tokens?
   - Can the agent listen in shared channels?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - slack
+  - socket mode
+  - bot token
+  - app token
+  - magic phrase
+  - owner channel
+  - messaging adapter
 related:
   - features/messaging/overview
   - features/messaging/pairing-and-magic-phrase
+ui_anchors:
+  - /connections/messaging
+config_keys:
+  - primaryPlatform
+  - slackOwnerUserId
 ---
 
 # 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.
+A Slack bot user becomes the agent's surface in your workspace: DMs to
+the bot are owner messages, and `@`-mentions of the bot in channels are
+mention events — but only from the one paired owner.
 
 ## What It Does
 
-- Listens for DMs (owner reactive path).
-- Listens for `@personalagent` mentions in shared channels.
-- Sends notifications to the owner DM.
+- Listens for **DMs** to the bot (owner reactive path).
+- Listens for **`@`-mentions of the bot** in channels you've added it to.
+- Sends notifications back to your owner DM.
 
-## Where in the Dashboard
+The adapter runs over Slack **Socket Mode** (a WebSocket), so Aitne does
+not need a public inbound URL or webhook endpoint.
 
-- **Connections → Messaging → Slack** holds bot tokens, channel info,
-  and the magic-phrase pairing flow.
+## Single-Owner Scope
+
+Aitne is a single-owner agent by design. Only messages from the paired
+owner are processed; everything else is dropped silently. Multi-person
+DMs (`mpim`) are rejected outright, so a mention inside a group thread
+never produces a reply visible to non-owners.
+
+A channel mention only fires when the message text contains the bot's
+actual user reference (e.g. `<@U0123ABCD>`, rendered as `@YourBotName`).
+A plain text string like `@personalagent` is not a real Slack mention and
+will not trigger anything.
+
+## Setup
+
+Everything happens under **Connections → Messaging** in the dashboard
+(the Slack card). There are three steps:
+
+1. **Create the Slack app.** Click *Open Slack app builder* — Aitne
+   pre-fills the manifest with the right scopes and Socket Mode enabled.
+   Create the app and install it to your workspace.
+2. **Paste two tokens.** Slack issues two tokens for a Socket Mode app:
+   - a **bot token** (`xoxb-...`) — the bot's identity and API access, and
+   - an **app-level token** (`xapp-...`) — authorizes the Socket Mode
+     WebSocket connection.
+
+   Paste both, then use *Test token* to confirm Aitne can reach the bot.
+3. **Pair with the magic phrase.** Click *Generate pairing phrase*, then
+   DM that exact phrase to the bot from your own Slack account. The first
+   account that sends the matching phrase becomes the owner. See
+   [Pairing and the Magic Phrase](pairing-and-magic-phrase.md) for how
+   the challenge works.
+
+To route notifications to Slack by default, set Slack as your primary
+platform (`primaryPlatform`). The owner's Slack user id is stored as
+`slackOwnerUserId` once pairing succeeds.
 
 ## When Something Goes Wrong
 
-- Bot does not respond: check that the workspace bot has been added
-  to the channel where the DM is happening.
+- **Bot never responds to a DM.** Confirm both tokens are saved and *Test
+  token* succeeds. A failing app-level token (`xapp-`) means the Socket
+  Mode connection never opens, so no events arrive.
+- **Mentions in a channel are ignored.** Make sure the bot has been added
+  to that channel, and that you're mentioning the bot itself (autocomplete
+  `@YourBotName`), not typing a plain word.
+- **Pairing phrase isn't accepted.** Send the phrase by itself, with no
+  surrounding sentence — a wrapped phrase won't match. See the pairing
+  doc for the full rules.
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Pairing and the Magic Phrase](pairing-and-magic-phrase.md)

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

@@ -12,15 +12,25 @@ summary: |
 section: messaging
 tags:
   - messaging
-  - integration
-  - core
+  - integrations
+  - telegram
 status: stable
+config_keys:
+  - telegramOwnerChatId
+ui_anchors:
+  - /connections/messaging
 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
+updated: 2026-05-28
+keywords:
+  - telegram
+  - telegram bot
+  - bot token
+  - telegram pairing
+  - messaging adapter
 related:
   - features/messaging/pairing-and-magic-phrase
   - features/messaging/overview
@@ -35,12 +45,14 @@ token, type the magic phrase.
 
 ## What It Does
 
-- Acts as the agent's reactive surface for incoming DMs.
-- Receives outbound notifications.
+- Acts as the agent's reactive surface for your incoming direct messages (owner DMs only — group chats are ignored).
+- Delivers the agent's outbound notifications and replies back to the same Telegram chat.
 
 ## When It Runs / How It Is Triggered
 
-Continuously listening to Telegram's long-polling API once paired.
+Before pairing, nothing listens. Once you paste the bot token and complete
+magic-phrase pairing, Aitne long-polls Telegram's Bot API continuously for new
+direct messages.
 
 ## Where in the Dashboard
 
@@ -57,7 +69,14 @@ Continuously listening to Telegram's long-polling API once paired.
 
 - Bot replied to in a group instead of a DM: group chats are filtered
   out by design; the agent only listens to direct messages.
+- No reply at all after DMing the magic phrase: confirm the bot has a username
+  set via @BotFather (/setname) — the daemon refuses to build the pairing deep
+  link otherwise.
+- Pairing never completes: re-check the token in Connections → Messaging →
+  Telegram, then DM the magic phrase from your own account. See
+  [Pairing & Magic Phrase](pairing-and-magic-phrase.md).
 
 ## Related
 
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Messaging Overview](overview.md)

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

@@ -3,46 +3,111 @@ schema_version: 1
 slug: features/messaging/whatsapp
 title: WhatsApp
 id: whatsapp
+aliases:
+  - whatsapp bot
+  - whatsapp adapter
+  - whatsapp pairing
+  - whatsapp linked device
 category: features
 summary: |
-  Pair WhatsApp via the Cloud API or a bridge service. Once paired, DMs
-  to the configured number are owner messages.
+  Link WhatsApp by scanning a QR code with your phone, the same way the
+  WhatsApp desktop app links. No Cloud API, business account, or webhook
+  is involved. Once linked, DMs to your own number are owner messages and
+  flow exactly like Telegram.
 section: messaging
 tags:
   - messaging
-  - integration
+  - whatsapp
+  - integrations
+  - pairing
 status: stable
 ask_examples:
   - Can I use WhatsApp with Aitne?
-  - How do I set up the WhatsApp Cloud API?
+  - How do I link WhatsApp by scanning a QR code?
+  - Why does WhatsApp say the device is unlinked?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - whatsapp
+  - qr code
+  - linked devices
+  - owner phone
+  - e.164
+  - messaging adapter
+  - baileys
 related:
   - features/messaging/overview
+  - features/messaging/pairing-and-magic-phrase
+config_keys:
+  - whatsappEnabled
+  - whatsappOwnerPhone
+  - whatsappAuthDir
+ui_anchors:
+  - /connections/messaging
 ---
 
 # WhatsApp
 
 ## In One Sentence
 
-A WhatsApp Cloud API number can act as the agent's owner surface; DMs
-flow exactly like Telegram.
+Link WhatsApp by scanning a QR code with your phone — the same flow as
+WhatsApp's own desktop/web app — and DMs to your number become owner
+messages that flow exactly like Telegram.
 
-## What It Does
+## How It Works
 
-- Receives WhatsApp messages routed through the configured number.
-- Sends notifications back through the same channel.
+Aitne connects to WhatsApp as a **linked device** (the multi-device feature
+in the WhatsApp mobile app), not through the WhatsApp Cloud API or a paid
+bridge such as Twilio. There is no business account, no bot token, and no
+inbound webhook to expose:
 
-## Where in the Dashboard
+- You scan a QR code once to link the daemon as a device on your account.
+- Incoming WhatsApp messages arrive over the linked-device connection.
+- The agent replies and sends notifications back through the same channel.
+- It is **owner-only**: only DMs involving your one configured number are
+  accepted. Self-DMs you send from another linked device are also accepted,
+  so you can talk to the agent from your own number without a second account.
+  All other senders are dropped.
 
-- **Connections → Messaging → WhatsApp**.
+## Setup
+
+You configure WhatsApp from the dashboard — there is no `aitne` CLI command
+for it.
+
+1. Go to **Connections → Messaging → WhatsApp**.
+2. Set the **Owner phone** in E.164 format (e.g. `+818012345678`). This is
+   required before you can enable WhatsApp.
+3. (Optional) Set the **Auth dir** — where the linked-device credentials are
+   stored. Defaults to `~/.personal-agent/whatsapp/auth`.
+4. Click **Enable WhatsApp**, then **Pair device**. A QR code appears.
+5. On your phone: open **WhatsApp → Settings → Linked Devices → Link a
+   device**, and scan the QR code.
+
+Once the status shows connected, message your own number and the agent
+responds.
+
+### Configuration keys
+
+| Key | Meaning |
+|---|---|
+| `whatsappEnabled` | Master on/off (default `false`). |
+| `whatsappOwnerPhone` | Owner number in E.164 format. Validated; must start with `+` and 8–15 digits. |
+| `whatsappAuthDir` | Directory holding linked-device credentials. |
 
 ## 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).
+- **QR code expired.** Each QR is short-lived and rotates. Click **Refresh
+  QR** in the dashboard to get a new one, then scan it.
+- **WhatsApp says the device is unlinked**, or pairing keeps failing. Click
+  **Reset connection** in the dashboard. This wipes the cached pairing data
+  in the auth dir so you can scan a fresh QR from scratch.
+- **Session logged out.** If WhatsApp logs the device out (account banned,
+  device conflict, or you unlinked it from the phone), the connection stops
+  retrying and surfaces an error. Use **Reset connection**, then **Pair
+  device** again.
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Pairing and the Magic Phrase](pairing-and-magic-phrase.md)

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

@@ -18,6 +18,7 @@ tags:
   - core
   - operations
   - audit
+  - dashboard
 status: stable
 ask_examples:
   - Where can I see what the agent did today?
@@ -25,7 +26,7 @@ ask_examples:
   - How do I find why a routine failed?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - activity
   - conversations
@@ -36,6 +37,12 @@ related:
   - features/operations/notifications
   - features/operations/cost-tracking
   - features/operations/backend-routing
+config_keys:
+  - executeTimeoutMinutes
+process_keys:
+  - routine.morning_routine
+api_endpoints:
+  - POST /api/system/purge-history
 ui_anchors:
   - /
   - /activity
@@ -54,7 +61,7 @@ detail lives one click deeper under Conversations.
 
 Activity is the unified view of:
 
-- **Routines**: morning, evening, weekly, monthly, hourly fires.
+- **Routines**: morning, evening, weekly, hourly fires.
 - **Reactive sessions**: DMs, dashboard chat, mentions.
 - **Background actions**: notifications sent, mail labeled, schedule
   files written.
@@ -62,15 +69,16 @@ Activity is the unified view of:
 
 Each row links to the underlying conversation when one exists.
 
-## When It Runs / How It Is Triggered
+## How It Works
 
-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`).
+Activity has no trigger of its own — it is a read-only projection.
+Every other event in the system writes to it as a side effect, landing
+in three SQLite tables: `agent_actions` (what happened), and
+`conversation_sessions` + `messages` (what was said).
 
-## What It Outputs
+## What You See
 
-- A timeline filterable by event type, ProcessKey, backend, outcome.
+- A timeline filterable by event type, ProcessKey, backend, and outcome.
 - Per-row cost, token counts, and turn count.
 - A direct link to the message transcript for any session.
 
@@ -81,21 +89,42 @@ written to as a side-effect of every other event in the system
 - **Conversations (`/conversations/<id>`)** opens a single session's
   message-by-message transcript.
 
+To read the morning routine's full reply, open Activity, filter to the
+`routine.morning_routine` row, and click through to its conversation —
+the transcript holds the agent's complete output, not just the summary
+that reached your DM.
+
 ## 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`.
+are connected.
+
+Retention is unlimited locally — the SQLite database keeps every row
+forever. To prune history without losing your configuration, use
+`POST /api/system/purge-history` (it clears `agent_actions`,
+`conversation_sessions`, and `messages` but leaves settings and the
+context vault intact). To wipe everything, `aitne uninstall --wipe-data`
+removes the whole `~/.personal-agent` data directory after a `WIPE`
+confirmation.
 
 ## 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.
+To find why a routine failed, open Activity, filter the outcome to
+**failed**, and open the offending row. Its outcome label tells you the
+failure class; the linked conversation shows the exact error and the
+turn it happened on.
+
+Common outcome labels:
+
+- **"timed out"** — a backend or SDK hang. `executeTimeoutMinutes`
+  (`/settings/models`) is the wall-clock cap.
+- **"fallback"** — the main backend failed and routing moved to the
+  fallback; the detail carries the `BackendQuotaError` or
+  `BackendDecisiveFailure` that triggered it.
+- **"blocked_absolute"** — the absolute-block layer refused a tool call.
+  The detail names which tool and why (logged as
+  `agent_actions.action_type='blocked_absolute'`).
 
 ## Related