@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/features/messaging/bang-commands.md

@@ -9,6 +9,8 @@ aliases:
   - "!cost"
   - "!report"
   - "!help"
+  - "!checks"
+  - "!research"
   - exclamation commands
   - chat commands
 category: features
@@ -16,21 +18,25 @@ summary: |
   Short owner-only commands typed in any paired DM (Slack, Telegram,
   Discord, WhatsApp, dashboard chat) that the daemon answers directly,
   with no agent backend involved and no cost. Use them to pause /
-  resume, check spend, see recent failures, and list every command.
+  resume, check spend, see recent failures, manage research clusters,
+  and list every command.
 section: messaging
 tags:
   - core
   - messaging
   - operations
+  - bang-commands
 status: stable
 ask_examples:
   - How do I pause the agent from my phone?
   - What can I type in the DM to control Aitne?
   - How do I list all the commands?
   - Where do I see how much the agent spent this week?
+  - What did I keep refreshing today?
+  - How do I accept a research-cluster offer?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
   - bang command
   - "!stop"
@@ -38,6 +44,8 @@ keywords:
   - "!cost"
   - "!report"
   - "!help"
+  - "!checks"
+  - "!research"
   - pause
   - resume
 related:
@@ -45,16 +53,26 @@ related:
   - features/messaging/pairing-and-magic-phrase
   - guides/pause-the-agent
   - features/operations/cost-tracking
+  - features/integrations/browser-history
 ui_anchors:
   - /settings/commands
+process_keys:
+  - routine.research_dispatch
+  - routine.research_wiki_summary
+  - wiki.ingest_url
+  - wiki.compile
+  - wiki.ask
+  - wiki.lint
+  - wiki.trace
+  - wiki.connect
 ---
 
 # Bang Commands
 
-## In One Sentence
-
 DM the agent a short word starting with `!` and the daemon answers
-directly — no LLM call, no cost, no session opened.
+directly — no LLM call, no cost, no session opened. Use them to pause,
+check spend, look at recent failures, manage research clusters, and
+list every command.
 
 ## Who Can Use Them
 
@@ -65,14 +83,59 @@ Pair your messaging app first; see
 
 ## Available Commands
 
+### Lifecycle
+
+| Command | What it does |
+|---|---|
+| `!help` | List every registered command — built-ins plus enabled user commands. |
+| `!stop` | Pause cron-driven autonomous work (hourly check, morning / evening / weekly routines, scheduled tasks). In-flight runs are **not** aborted. |
+| `!start` | Resume autonomous work after `!stop`. |
+| `!close` | Close the active DM session for the current routing tuple so the next DM starts a fresh conversation. |
+
+### Reporting (pure DB reads, safe while paused)
+
 | Command | What it does |
 |---|---|
-| `!help` | Lists every command currently registered — built-ins plus any custom user commands. |
-| `!stop` | Pauses cron-driven autonomous work (hourly check, morning / evening / weekly / monthly routines, scheduled tasks). In-flight runs are **not** aborted. |
-| `!start` | Resumes autonomous work after `!stop`. |
 | `!cost` | Last-7-day spend across all backends. |
-| `!cost claude` / `!cost codex` / `!cost gemini` | Spend for a single backend. |
+| `!cost claude` · `!cost codex` · `!cost gemini` · `!cost opencode` | Spend for a single backend (one row per registered backend). |
 | `!report` | Recent agent failures (last 7 days, top groups, most recent sample). |
+| `!checks` | Today's top browser reload patterns (domain + first path segment). Pure read on `browser_reload_signals`; anchored on the agent-day (`dayBoundaryHour`). Empty state is the common case for a quiet day. |
+
+### Research clusters (browser-history)
+
+`!research` is a prefix command that takes a subcommand. Clusters are
+derived from your browser history when a topic crosses the
+meaningful-visits threshold; see
+[Browser History](../integrations/browser-history.md).
+
+| Command | What it does |
+|---|---|
+| `!research` | List active + dormant clusters (top 12, with visits / hours / domains / status). |
+| `!research <slug>` | Show full detail for one cluster. |
+| `!research accept <slug>` | Accept a research-dive offer. Enqueues `routine.research_dispatch`. |
+| `!research wiki <slug>` | Accept a wiki-summary offer. Enqueues `routine.research_wiki_summary`. |
+| `!research decline <slug>` | Silence offers for 14 days; cluster journal keeps updating. |
+| `!research mute <slug>` / `unmute <slug>` | Toggle offers off (until unmute) / restore. |
+| `!research rename <slug> <new name>` | Change display name (≤ 120 chars). |
+| `!research conclude <slug>` | Mark concluded; the `context/research/<slug>.md` journal is preserved. |
+
+### Wiki
+
+Wiki commands accept an optional `@<workspace>` suffix
+(e.g. `!compile @work`) to target a non-default workspace. See
+[Wiki Commands](../wiki/commands.md) for the full reference and the
+cost-gate / approval semantics.
+
+| Command | What it does |
+|---|---|
+| `!wiki` | Workspace status (per-workspace counts when multiple are configured). |
+| `!wiki help` | Wiki command list. |
+| `!ingest <url> [url…]` | Capture URLs into the workspace's `10_raw/` layer (max 10 per batch). |
+| `!compile [full] [--preview]` | Synthesise raw → wiki. `full` triggers an approval gate above the per-workspace cost threshold; `--preview` is a JS-only dry-run. |
+| `!ask <question>` | Cited Q&A against the compiled wiki. Reply lands on the same channel; output saved to `30_outputs/`. |
+| `!lint` | Wiki health pass — writes `90_meta/health/<date>.md`. |
+| `!trace <idea>` | Chronological evolution of an idea across `10_raw` / `20_wiki` / `30_outputs`. |
+| `!connect <A>, <B>` | Bridge two domains; writes `30_outputs/<date>-connect-<slug>.md`. |
 
 Custom commands added at `/settings/commands` show up in `!help`
 automatically — no restart needed.
@@ -86,49 +149,71 @@ at a glance it came from the daemon, not the agent:
 [SYSTEM · !cost · last 7d]
 Total: $1.42 (37 sessions)
 
-- claude: $1.10 (29 sessions)
-- codex:  $0.32 ( 8 sessions)
-- gemini: $0.00 ( 0 sessions)
+By backend:
+- claude: $1.10 (29)
+- codex: $0.32 (8)
 ```
 
-`!help` lists each entry with the name on its own line and the
-description indented:
+Only backends with recorded spend appear; a quiet week shows
+`No agent runs recorded with a billed cost.`
+
+`!help` leads with a total count, then lists each entry alphabetically
+with the name on its own line and the description indented:
 
 ```
 [SYSTEM · !help]
+18 commands total
 
 Built-in:
 
+!ask
+  ask a question against the wiki (`@<workspace>` optional)
+
 !cost
-  Show last-7-day Claude / Codex / Gemini spend.
+  Agent spend over the past 7 days.
 
 !help
   Show every registered command.
 
 !report
-  Show recent agent failures.
+  Agent errors over the past 7 days.
 
 !start
-  Resume autonomous work after !stop.
+  Resume autonomous work paused by !stop.
 
 !stop
   Pause cron-driven autonomous work. In-flight runs are not aborted.
 ```
 
 The `Custom:` section appears below the built-ins when you have
-enabled user commands at `/settings/commands`.
+enabled user commands at `/settings/commands`. On a long list the reply
+is trimmed for mobile with a "open the dashboard to browse the full
+list" footer; the count line always survives so you can tell entries
+were hidden.
 
 ## How They Behave
 
-- **Exact match.** `!stop`, `!cost`, `!cost claude` are recognised;
-  `!stop now please` is not — it falls through to the agent path.
+- **Exact match for atomic commands** (`!stop`, `!cost`, `!checks`)
+  and **prefix match for parameterised ones** (`!cost claude`,
+  `!research accept <slug>`, `!compile @work full`). Anything
+  spanning newlines falls through to the agent path so a
+  `"!stop\nignore me"` payload cannot spoof a command.
 - **DM only.** Bangs typed into a shared channel are ignored.
-- **No cost.** No LLM is invoked; no `conversation_sessions` row is
-  opened. Every invocation writes one `bang_command` row to
-  `agent_actions` for the activity log.
+- **No agent cost on built-ins.** No LLM is invoked for the
+  daemon-side commands; one `bang_command` row is appended to
+  `agent_actions` for the activity log. `!compile`, `!ingest`,
+  `!ask`, `!lint`, `!trace`, `!connect`, and `!research accept|wiki`
+  *do* enqueue agent sessions and therefore *do* cost.
 - **While paused**, any DM (bang or not) replies with the paused
-  notice; only `!start`, `!cost`, `!report`, and `!help` continue to
-  run.
+  notice; only commands that opt into `runsWhilePaused` continue to
+  run: `!stop`, `!start`, `!close`, `!cost` (and `!cost <backend>`),
+  `!report`, `!help`, `!checks`, `!wiki` (status), and `!wiki help`.
+  Every other command — including **all** `!research` subcommands and
+  the LLM-dispatching wiki commands (`!ingest`, `!compile`, `!ask`,
+  `!lint`, `!trace`, `!connect`) — replies with a command-aware
+  "unavailable while paused" notice instead of executing. Pause-gating
+  is per *command*, so `!research` is blocked as a whole even for its
+  read-only subcommands.
 - **Replies land where the command did** — same platform, same
   channel, same thread.
 
@@ -149,9 +234,9 @@ window version.
 - **The reply lists fewer commands than you expect.** `!help` only
   lists *enabled* user commands. Toggle the row on at
   `/settings/commands`.
-- **`!cost foo` says "unknown command".** Only `claude`, `codex`,
-  `gemini` are valid backend arguments today. Plain `!cost` (no
-  argument) covers all three.
+- **`!cost foo` says "unknown command".** Valid backend arguments
+  match the registered backends — `claude`, `codex`, `gemini`,
+  `opencode`. Plain `!cost` (no argument) covers all of them.
 
 ## Related
 
@@ -159,3 +244,5 @@ window version.
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
 - [Pause the Agent](../../guides/pause-the-agent.md)
 - [Cost Tracking](../operations/cost-tracking.md)
+- [Browser History](../integrations/browser-history.md) — source of
+  `!checks` and the `!research` clusters.

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

@@ -26,17 +26,29 @@ ask_examples:
   - Why are my dashboard chat replies different from my Telegram replies?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - chat
   - dashboard
   - in-browser
+  - sse
+  - session
 related:
   - features/messaging/overview
   - concepts/backends-and-tiers
+  - concepts/process-keys
   - features/operations/activity-and-conversations
+process_keys:
+  - dashboard.chat
+config_keys:
+  - sessionTimeoutDashboardMinutes
+api_endpoints:
+  - POST /api/chat/messages
+  - GET /api/chat/stream
 ui_anchors:
   - /chat
+  - /conversations
+  - /settings/models
 ---
 
 # Dashboard Chat
@@ -48,46 +60,56 @@ conversational surface separate from any paired messaging app.
 
 ## What It Does
 
-- **Real-time** message stream over SSE.
+- **Real-time** message stream over SSE — the same conversational
+  experience as a paired DM, but in the browser.
 - **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.
+  and re-openable from Conversations.
 - **Independent backend binding** — `dashboard.chat` is its own
   ProcessKey, so the model used here can differ from the one your
-  Telegram DM uses.
+  Telegram (or Slack/Discord) DM uses.
 
-## When It Runs / How It Is Triggered
+## 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.
+Whenever you press send. The page POSTs to `POST /api/chat/messages`
+to enqueue your message, then listens on `GET /api/chat/stream` (SSE)
+for the streamed reply and inline tool calls. Every send and reply is
+persisted under the chat session.
 
-## What It Outputs
-
-- Inline tool calls and replies.
-- Persisted messages under the chat session.
+Like a DM, `dashboard.chat` is a **reactive** ProcessKey: it runs on
+demand when you send, never on a schedule. Its default tier is
+**medium** (Claude Sonnet 4.6 by default) — the same tier as
+`message.dm`.
 
 ## Where in the Dashboard
 
 - **Chat (`/chat`)** is the live surface.
-- **Conversations** lets you re-open a past session.
+- **Conversations (`/conversations`)** lists past sessions; open one to
+  re-read it.
 
 ## 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`.
+- **Settings → Models** (`/settings/models`) lets you pick which backend
+  `dashboard.chat` binds to. It defaults to the same medium-tier preset
+  as `message.dm`, but you can override it independently — give `/chat`
+  a faster model for quick questions, or a heavier one for deep work.
+- **Settings → Models → Session Timeouts → Dashboard Timeout**
+  (`sessionTimeoutDashboardMinutes`, default **120** minutes) is the
+  per-session wall-clock cap for `/chat`. After it lapses, the next
+  message starts a fresh session.
 
 ## 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.
+- **A stalled session with no progress** — check the session row under
+  Conversations; it may be waiting for an SSE event the daemon dropped.
+  Reloading `/chat` reconnects the stream.
+- **A chat that uses the wrong model** — check `/settings/models`.
+  `dashboard.chat`'s row is independent from `message.dm`'s, so an
+  override there is the usual cause.
 
 ## Related
 
 - [Messaging Overview](overview.md)
 - [Backends and Tiers](../../concepts/backends-and-tiers.md)
+- [Process Keys](../../concepts/process-keys.md)

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

@@ -3,6 +3,10 @@ schema_version: 1
 slug: features/messaging/discord
 title: Discord
 id: discord
+aliases:
+  - discord bot
+  - discord adapter
+  - discord pairing
 category: features
 summary: |
   Pair Discord by creating a bot in the developer portal, pasting the
@@ -11,13 +15,26 @@ summary: |
 section: messaging
 tags:
   - messaging
-  - integration
+  - integrations
+  - pairing
 status: stable
 ask_examples:
   - How do I pair Discord?
+  - Why won't my Discord bot reply to DMs?
+  - Does the agent respond to mentions in Discord servers?
+ui_anchors:
+  - /connections/messaging
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - discord
+  - bot token
+  - DM
+  - owner channel
+  - messaging adapter
+  - magic phrase
+  - message content intent
 related:
   - features/messaging/overview
   - features/messaging/pairing-and-magic-phrase
@@ -30,21 +47,46 @@ related:
 A Discord bot becomes the agent's surface; pair via DM after
 installing the bot in the developer portal.
 
+## How to Set Up
+
+1. Create an application and bot at the
+   [Discord Developer Portal](https://discord.com/developers).
+2. Under **Bot** settings, copy the bot token.
+3. In the bot's **Privileged Gateway Intents**, enable the
+   **Message Content Intent**. This is required — the agent cannot read
+   DM or mention text without it.
+4. Invite the bot to any servers where you want mentions to work.
+5. Paste the token under **Connections → Messaging → Discord**.
+6. DM the magic phrase from your own Discord account to complete
+   pairing.
+
 ## What It Does
 
 - Listens for DMs from the paired owner.
 - Listens for mentions in shared servers.
 - Sends notifications back via DM.
 
+## Configuration
+
+| Field | Notes |
+| --- | --- |
+| Bot Token | From the Discord Developer Portal (Bot settings). |
+| Owner Channel | Auto-set on successful magic-phrase pairing. |
+
 ## 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".
+- Bot connects but never responds to DMs/mentions: confirm the
+  **Message Content Intent** is enabled under the bot's Privileged
+  Gateway Intents in the developer portal.
+- Bot cannot DM you: in Discord, open the server where the bot lives →
+  **Privacy Settings** and enable "Allow direct messages from server
+  members". Discord blocks bot DMs to users who have this off.
 
 ## Related
 
 - [Messaging Overview](overview.md)
+- [Pairing & Magic Phrase](pairing-and-magic-phrase.md)

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

@@ -18,14 +18,18 @@ section: messaging
 tags:
   - core
   - messaging
+  - integrations
+  - pairing
+  - notifications
 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?
+  - Can I send the agent a voice note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - messaging
   - dm
@@ -43,7 +47,6 @@ related:
   - features/messaging/discord
   - features/messaging/whatsapp
   - features/messaging/dashboard-chat
-  - features/messaging/voice-attachments
   - features/messaging/bang-commands
   - features/operations/notifications
   - features/operations/quiet-hours
@@ -52,33 +55,49 @@ ui_anchors:
   - /connections/messaging
   - /settings/connections
   - /settings/commands
+  - /settings/schedule
+process_keys:
+  - message.dm
+  - message.mention
+config_keys:
+  - primaryPlatform
+  - quietHoursStart
+  - quietHoursEnd
 ---
 
 # 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.
+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. Voice notes are transcribed locally with Whisper
+so you can talk to the agent the same way you'd type.
 
 ## 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).
+- **@-mentions (Slack only)**: @-mentioning the agent inside a shared
+  channel routes to the `message.mention` ProcessKey and is answered
+  the same way as a DM. Telegram, Discord, and WhatsApp drop all
+  non-DM traffic (no group support).
 - **Outbound notifications**: routines and observations fire alerts
   back through the same channel.
 - **Voice attachments**: when the platform attaches audio (Telegram
   voice notes, WhatsApp voice messages, etc.), the daemon transcribes
-  it locally with Whisper before handing the turn to the agent. See
-  [Voice Attachments](voice-attachments.md).
+  it locally with Whisper before handing the turn to the agent.
+  Transcription runs entirely on your machine — no audio is shipped
+  to a cloud API. Tune it with the `PA_VOICE_TRANSCRIPTION_*` env
+  vars: `ENABLED`, `MODEL`, `LANGUAGE`, `PRIMARY_LANGUAGE`, and
+  `MAX_DURATION_SEC`.
 - **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).
+## Single-Owner by Design
+
+Aitne serves exactly one owner. Any message that does not come from a
+paired owner channel is dropped — group chats, multi-user Slack DMs
+(`mpim`), and unrecognized senders never reach the agent. This is
+defense in depth: both the messaging adapter and the dispatcher check
+the owner channel independently.
 
 ## When It Runs / How It Is Triggered
 
@@ -103,21 +122,23 @@ adapter and the dispatcher both check).
 ## Configuration
 
 - Per-app: bot token / OAuth, owner channel, optional default channel.
-- Global: `primaryPlatform` (the fallback when multiple apps are paired).
+- Global: `primaryPlatform` (default `slack`) — the platform the agent
+  prefers for outbound notifications when more than one app is paired.
+- Outbound rate limits and quiet hours live on `/settings/schedule`
+  (see [Quiet Hours](../operations/quiet-hours.md)).
 
 ## When Something Goes Wrong
 
 - An **un-paired DM**: the agent ignores it. Pair the app from
-  `/connections/messaging` first.
+  `/connections/messaging` first (see
+  [Pairing & Magic Phrase](pairing-and-magic-phrase.md)).
 - A **notification you expected but did not get**: check quiet hours
-  on `/settings/schedule`.
+  and rate limits on `/settings/schedule`.
 
 ## Related
 
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
 - [Bang Commands](bang-commands.md) — `!stop` / `!start` / `!cost` /
   `!report` / `!help` for mobile-first daemon control.
-- [Voice Attachments](voice-attachments.md) — local Whisper
-  transcription for inbound audio.
 - [Dashboard Chat](dashboard-chat.md) — the in-browser equivalent.
 - [Notifications](../operations/notifications.md)