@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/docs/features/memory-files/today.md

@@ -13,9 +13,7 @@ summary: |
   and the operator all read and append to it during the day.
 section: memory-files
 tags:
-  - core
   - memory
-  - today
 status: stable
 ask_examples:
   - What is in today.md?
@@ -23,7 +21,7 @@ ask_examples:
   - Why does today.md keep getting rewritten?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - today
   - day plan
@@ -48,9 +46,10 @@ context_files:
 
 ## In One Sentence
 
-The single live file for the current agent day — plan, log, tasks, and
-hand-off. The morning routine rebuilds it; everything else during the
-day appends to it.
+The single live file for the current agent day (the window the agent
+treats as "today") — its plan, log, tasks, and hand-off. The morning
+routine rebuilds it fresh each day; everything else during the day only
+appends to it.
 
 ## What It Does
 
@@ -58,12 +57,12 @@ today.md holds six sections, written in this order:
 
 - **User Schedule** — the day's calendar events.
 - **User Tasks** — today's external tasks plus agent-tracked to-dos.
-- **Agent Plan** — what the agent intends to work on today (each row is
-  registered as a schedule entry by the morning routine; mid-day
-  sessions may add rows for new signals or cancel ones whose premise
-  changed).
-- **Agent Notes** — look-ahead items and date-bound memos folded in from
-  inbox triage.
+- **Agent Plan** — what the agent means to work on today. The morning
+  routine turns each row into a schedule entry; a later session that day
+  can add rows for new signals or drop a row whose reason no longer
+  holds.
+- **Agent Notes** — upcoming items and date-specific memos pulled in from
+  inbox triage (the sorting of new incoming items).
 - **Agent Log** — what actually happened, appended throughout the day.
 - **Handoff** — what carries over to tomorrow.
 
@@ -73,17 +72,18 @@ today.md holds six sections, written in this order:
   rotates the previous day's file to `state/yesterday.md`).
 - The **activity scan** routes new observations into the right section
   and appends short status lines under Agent Log.
-- The **evening review** finalizes the file — it updates Agent Log and
+- The **evening review** closes out the file — it updates Agent Log and
   the Handoff section. (The daily journal itself is written the next
   morning, from the rotated file.)
 
 ## How It Is Written
 
-The agent never edits today.md with a file tool. All writes go through
-the daemon's context API — `PUT`/`PATCH /api/context/state/today` (the
-canonical, class-prefixed path). A `today-write-lock` serializes writes
-during the morning routine: while the lock is held, a write to
-`state/today` must carry the `X-Lock-Id` header or it is rejected.
+The agent never edits today.md with a file tool. Every write goes
+through the daemon's context API — `PUT`/`PATCH /api/context/state/today`
+(the canonical, class-prefixed path). A `today-write-lock` forces writes
+to happen one at a time during the morning routine: while the lock is
+held, any write to `state/today` must carry the `X-Lock-Id` header, or
+it is rejected.
 
 ## Where in the Dashboard
 

package/agent-assets/docs/features/memory-files/user-profile.md

@@ -18,8 +18,6 @@ summary: |
 section: memory-files
 tags:
   - memory
-  - profile
-  - core
 status: stable
 ask_examples:
   - What is identity/profile.md?
@@ -27,7 +25,7 @@ ask_examples:
   - Will the agent change my profile without asking?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - user profile
   - identity/profile.md
@@ -55,19 +53,21 @@ context_files:
 
 ## In One Sentence
 
-A stable profile of you — the agent reads it every session and
-silently appends durable facts you state in DMs.
+A steady profile of you. The agent reads it at the start of every
+session and quietly adds durable facts — things that stay true, like
+your role or your manager's name — that you mention in DMs.
 
 ## What It Does
 
 - Captures who you are, what you do, and who matters in your life.
-- Is pinned at the top of every session prompt, so the agent keeps
-  the same baseline understanding of you turn-to-turn.
-- Anchors a set of companion slices in the `identity/` directory that
-  split the dossier into topic-shaped files:
+- Sits at the top of every session prompt, so the agent keeps the same
+  baseline understanding of you from one message to the next.
+- Anchors a set of companion files — called slices — in the `identity/`
+  directory, one per topic:
   `identity/people.md`, `identity/work.md`, `identity/expertise.md`,
-  `identity/personal.md`, `identity/goals.md`. The agent loads these on
-  demand instead of inlining everything into every prompt.
+  `identity/personal.md`, `identity/goals.md`. The agent loads these
+  only when it needs them, instead of packing everything into every
+  prompt.
 
 > Older docs and exports may call these files `user/profile.md`,
 > `user/people.md`, and so on. `user/` is a legacy alias for
@@ -77,11 +77,11 @@ silently appends durable facts you state in DMs.
 ## When It Runs / How It Is Triggered
 
 - **Read continuously** — loaded at the start of every session.
-- **Written** silently, in the same turn, when you state a durable
-  fact about yourself in a DM ("remember that…", "I'm a…", "my
-  manager is…"), and during the profile sweep routine
-  (`routine.user_profile_sweep`), which catches facts the DM-time
-  capture missed and routes them into the appropriate
+- **Written** silently, within the same reply, when you state a
+  durable fact about yourself in a DM ("remember that…", "I'm a…",
+  "my manager is…"), and during the profile sweep routine
+  (`routine.user_profile_sweep`), which catches facts that the
+  in-chat capture missed and files them into the right
   `identity/*.md` slice.
 
 The agent never edits these files directly. It writes through the
@@ -106,7 +106,7 @@ To tell the agent a durable fact about yourself, just say it in a DM:
 > remember that my manager is Priya and we sync every Monday at 10am
 
 The agent silently appends a line to the relevant slice (here
-`identity/people.md`) in the same turn, and recalls it in future
+`identity/people.md`) right away, and recalls it in future
 sessions.
 
 ## When Something Goes Wrong

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

@@ -23,10 +23,8 @@ summary: |
   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?
@@ -37,7 +35,7 @@ ask_examples:
   - How do I accept a research-cluster offer?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - bang command
   - "!stop"
@@ -70,10 +68,12 @@ process_keys:
 
 # Bang Commands
 
-DM the agent a short word starting with `!` and the daemon answers
-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.
+DM the agent a short word that starts with `!` — the `!` symbol is
+nicknamed a "bang," which is where these commands get their name — and
+the daemon (the always-on local background service) answers it directly.
+No AI model runs, so there is no cost and no chat session is opened. Use
+bang commands to pause the agent, check spend, look at recent failures,
+manage research clusters, and list every command.
 
 ## Who Can Use Them
 
@@ -89,9 +89,9 @@ Pair your messaging app first; see
 | Command | What it does |
 |---|---|
 | `!help` | List every registered command — built-ins plus enabled user commands. |
-| `!stop` | Pause cron-driven autonomous work (activity scan, morning / evening / weekly routines, scheduled tasks). In-flight runs are **not** aborted. |
+| `!stop` | Pause cron-driven (scheduled) autonomous work: activity scan, the morning / evening / weekly routines, and scheduled tasks. Runs already in progress 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. |
+| `!close` | Close the active DM session for the current routing tuple (this platform + channel + thread) so the next DM starts a fresh conversation. |
 
 ### Tasks (detached background / browser work)
 
@@ -206,12 +206,12 @@ were hidden.
 
 ## How They Behave
 
-- **Exact match for atomic commands** (`!stop`, `!cost`, `!checks` —
-  each `!cost <backend>` variant is its own exact-match entry) and
-  **prefix match for parameterised ones**
-  (`!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.
+- **Exact match for atomic commands** — single words like `!stop`,
+  `!cost`, and `!checks`, where each `!cost <backend>` variant is its
+  own exact-match entry — and **prefix match for parameterised ones**
+  that take an argument (`!research accept <slug>`, `!compile @work
+  full`). Anything that spans more than one line 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 agent cost on built-ins.** No LLM is invoked for the
   daemon-side commands; one `bang_command` row is appended to

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

@@ -16,7 +16,6 @@ summary: |
   messaging app.
 section: messaging
 tags:
-  - core
   - messaging
   - dashboard
 status: stable
@@ -26,7 +25,7 @@ ask_examples:
   - Why are my dashboard chat replies different from my Telegram replies?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - chat
   - dashboard
@@ -55,13 +54,14 @@ ui_anchors:
 
 ## In One Sentence
 
-`/chat` is a browser-mounted DM with the agent — a fully featured
-conversational surface separate from any paired messaging app.
+`/chat` is a DM with the agent that lives in your browser — a fully
+featured chat, separate from any paired messaging app.
 
 ## What It Does
 
-- **Real-time** message stream over SSE — the same conversational
-  experience as a paired DM, but in the browser.
+- **Real-time** message stream over SSE (Server-Sent Events, a live
+  one-way feed from the daemon to your browser) — 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'`)
@@ -79,7 +79,7 @@ persisted 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
+**medium** (Claude Sonnet 5 by default) — the same tier as
 `message.dm`.
 
 ## Where in the Dashboard
@@ -113,3 +113,4 @@ demand when you send, never on a schedule. Its default tier is
 - [Messaging Overview](overview.md)
 - [Backends and Tiers](../../concepts/backends-and-tiers.md)
 - [Process Keys](../../concepts/process-keys.md)
+- [Keyboard Shortcuts](../../reference/keyboard-shortcuts.md)

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

@@ -26,7 +26,7 @@ ui_anchors:
   - /connections/messaging
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - discord
   - bot token
@@ -44,8 +44,9 @@ related:
 
 ## In One Sentence
 
-A Discord bot becomes the agent's surface; pair via DM after
-installing the bot in the developer portal.
+Aitne talks to you through a Discord bot you create. Set the bot up in
+Discord's developer portal, then link it to yourself by sending it a
+direct message.
 
 ## How to Set Up
 
@@ -57,8 +58,9 @@ installing the bot in the developer portal.
    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.
+6. From your own Discord account, DM the bot the magic phrase (the
+   short one-time pairing code Aitne shows you) to finish pairing. See
+   [Pairing & Magic Phrase](pairing-and-magic-phrase.md).
 
 ## What It Does
 

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

@@ -16,7 +16,6 @@ summary: |
   agent uses the same channel to send notifications back.
 section: messaging
 tags:
-  - core
   - messaging
   - integrations
   - pairing
@@ -29,7 +28,7 @@ ask_examples:
   - Can I send the agent a voice note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - messaging
   - dm
@@ -66,17 +65,17 @@ config_keys:
 
 # Messaging Overview
 
-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
+Direct messages (DMs) from a paired messaging app are Aitne's main way
+to talk with you: you message it, it answers; it messages you back 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 (Slack and Discord)**: @-mentioning the agent inside a
-  shared channel routes to the `message.mention` ProcessKey and is
-  answered the same way as a DM. Telegram and WhatsApp drop all non-DM
+  shared channel routes to the `message.mention` process key and is
+  answered the same way as a DM. Telegram and WhatsApp ignore all non-DM
   traffic (no group support).
 - **Outbound notifications**: routines and observations fire alerts
   back through the same channel.
@@ -94,16 +93,17 @@ so you can talk to the agent the same way you'd type.
 
 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.
+(`mpim`), and unrecognized senders never reach the agent. Two layers
+enforce this independently (defense in depth): the messaging adapter
+and the dispatcher each check the owner channel on their own.
 
 ## When It Runs / How It Is Triggered
 
-- The messaging adapter for each connected platform long-polls
-  (Telegram) or holds a persistent WebSocket connection (Slack,
-  Discord, WhatsApp) for incoming messages.
-- An incoming DM dispatches to the `message.dm` ProcessKey.
+- The messaging adapter for each connected platform watches for
+  incoming messages — Telegram by long-polling (repeatedly asking the
+  server for updates), Slack, Discord, and WhatsApp by holding an
+  always-open WebSocket connection.
+- An incoming DM dispatches to the `message.dm` process key.
 - 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).

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

@@ -17,7 +17,6 @@ summary: |
   to your owner identity so nobody else can impersonate you.
 section: messaging
 tags:
-  - core
   - messaging
   - pairing
   - safety
@@ -25,7 +24,7 @@ tags:
 status: stable
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - pairing
   - magic phrase
@@ -86,23 +85,24 @@ on the platform.
 
 ### The magic phrase (Slack, Discord)
 
-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.
+The dashboard generates a short, memorable phrase: four lowercase words
+joined by hyphens, drawn from a 64-word list. That makes it easy to type
+but hard to guess (24 bits of entropy). You DM that exact phrase to the
+bot. Matching is forgiving — it ignores case, punctuation, and emoji — but
+you have to send the phrase **by itself**. If you wrap it in a sentence
+("my phrase is apple-banana-cherry-date"), the agent replies asking you to
+send just the phrase on its own.
 
-The phrase is single-use and expires after **5 minutes**. If it lapses,
-regenerate a fresh one from the dashboard.
+The phrase works once and expires after **5 minutes**. If it runs out,
+generate a fresh one from the dashboard.
 
 ### Token pairing (Telegram, WhatsApp)
 
 Telegram and WhatsApp don't use a typed phrase:
 
-- **Telegram** encodes a high-entropy, single-use token in a QR / deep
+- **Telegram** hides a hard-to-guess, one-time token inside the QR / deep
   link. Tapping **START** sends `/start <token>` to the bot, which
-  promotes you to owner. The token is matched exactly and also expires
+  promotes you to owner. The token has to match 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

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

@@ -17,7 +17,6 @@ section: messaging
 tags:
   - messaging
   - integrations
-  - slack
   - pairing
 status: stable
 ask_examples:
@@ -26,7 +25,7 @@ ask_examples:
   - Can the agent listen in shared channels?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - slack
   - socket mode
@@ -49,18 +48,20 @@ config_keys:
 
 ## In One Sentence
 
-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.
+You add a Slack bot user to your workspace, and that bot is how you talk
+to the agent: DMs you send the bot are treated as owner messages, and
+`@`-mentions of the bot in channels are treated as mentions — but only
+when they come from the one paired owner.
 
 ## What It Does
 
-- Listens for **DMs** to the bot (owner reactive path).
+- Listens for **DMs** to the bot — your direct messages to the agent.
 - Listens for **`@`-mentions of the bot** in channels you've added it to.
 - Sends notifications back to your owner DM.
 
-The adapter runs over Slack **Socket Mode** (a WebSocket), so Aitne does
-not need a public inbound URL or webhook endpoint.
+The adapter connects to Slack over **Socket Mode**, a WebSocket (a
+persistent two-way link Slack opens to Aitne). Because Slack does the
+reaching-out, Aitne needs no public inbound URL or webhook endpoint.
 
 ## Single-Owner Scope
 

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

@@ -13,7 +13,6 @@ section: messaging
 tags:
   - messaging
   - integrations
-  - telegram
 status: stable
 config_keys:
   - telegramOwnerChatId
@@ -24,7 +23,7 @@ ask_examples:
   - Where do I get a Telegram bot token?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - telegram
   - telegram bot
@@ -45,14 +44,15 @@ token, scan the pairing QR code.
 
 ## What It Does
 
-- 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.
+- Receives your incoming direct messages so the agent can react to them (owner DMs only — group chats are ignored).
+- Sends the agent's notifications and replies back to the same Telegram chat.
 
 ## When It Runs / How It Is Triggered
 
-Before pairing, nothing listens. Once you paste the bot token and complete
-QR / deep-link pairing, Aitne long-polls Telegram's Bot API continuously for new
-direct messages.
+Before pairing, nothing listens. Once you paste the bot token and finish pairing
+(scan the QR code or tap the deep link), Aitne continuously long-polls Telegram's
+Bot API — it keeps an open request that returns the moment a new direct message
+arrives.
 
 ## Where in the Dashboard
 

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

@@ -17,7 +17,6 @@ summary: |
 section: messaging
 tags:
   - messaging
-  - whatsapp
   - integrations
   - pairing
 status: stable
@@ -27,7 +26,7 @@ ask_examples:
   - Why does WhatsApp say the device is unlinked?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - whatsapp
   - qr code
@@ -57,10 +56,11 @@ messages that flow exactly like Telegram.
 
 ## How It Works
 
-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:
+Aitne connects to WhatsApp as a **linked device** — the same "linked
+devices" feature in the WhatsApp mobile app that powers WhatsApp Web. It does
+not use the WhatsApp Cloud API or a paid bridge such as Twilio. There is no
+business account, no bot token, and no inbound webhook (a public URL that
+WhatsApp would call) to expose:
 
 - 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.

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

@@ -15,7 +15,6 @@ summary: |
   answer "what happened" and "what was said".
 section: operations
 tags:
-  - core
   - operations
   - audit
   - dashboard
@@ -26,7 +25,7 @@ ask_examples:
   - How do I find why a routine failed?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - activity
   - conversations
@@ -53,9 +52,9 @@ ui_anchors:
 
 ## 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.
+The agent logs every session, action, and outcome to a local SQLite
+database and shows them as the Activity timeline; the matching
+message-by-message detail lives one click deeper under Conversations.
 
 ## What It Does
 
@@ -71,10 +70,11 @@ Each row links to the underlying conversation when one exists.
 
 ## How It Works
 
-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).
+Activity never runs anything on its own — it only mirrors what already
+happened (a read-only view). Every other event in the system writes to
+it as a side effect, landing in three SQLite tables: `agent_actions`
+(what happened), plus `conversation_sessions` and `messages` (what was
+said).
 
 ## What You See
 

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

@@ -9,12 +9,11 @@ aliases:
   - human in the loop
 category: features
 summary: |
-  A few high-blast-radius actions queue as approvals. The action
-  blocks until you click Approve on the dashboard Overview page;
-  the approval card stays visible there regardless of quiet hours.
+  A few high-impact actions queue as approvals. The action blocks
+  until you click Approve on the dashboard Overview page; the
+  approval card stays visible there regardless of quiet hours.
 section: operations
 tags:
-  - core
   - safety
   - operations
 status: stable
@@ -24,7 +23,7 @@ ask_examples:
   - Where do I approve a pending action?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - approval
   - approve tier
@@ -47,9 +46,10 @@ api_endpoints:
 
 ## In One Sentence
 
-A small set of high-blast-radius actions queue as approvals; the
-agent waits for you to click **Approve** on the dashboard before it
-proceeds.
+A small set of high-impact actions — the ones that could cause
+real harm if they ran by mistake — queue as approvals. The agent
+waits for you to click **Approve** on the dashboard before it runs
+one.
 
 ## How It Works
 
@@ -84,10 +84,11 @@ Deny asks for confirmation before discarding the item.
 ## When Something Goes Wrong
 
 - **A stale approval you never answered:** a pending approval is
-  discarded once the agent day rolls over (the next 04:00 local
-  boundary) — it's marked skipped rather than replayed after the
-  day turns. If that happens, redo the request that triggered it
-  (for example, re-send the DM or re-run the routine).
+  discarded once the agent day rolls over — the moment "today"
+  resets, at 04:00 local time by default. It is marked skipped
+  rather than replayed after the day turns. If that happens, redo
+  the request that triggered it (for example, re-send the DM or
+  re-run the routine).
 
 ## Related