@aitne-sh/aitne 0.1.8 → 0.1.10

package/agent-assets/docs/concepts/safety-and-execution.md

@@ -19,7 +19,8 @@ section: safety
 tags:
   - core
   - safety
-  - cost
+  - operations
+  - backends
 status: stable
 ask_examples:
   - What is the difference between Safe and Allow mode?
@@ -27,7 +28,7 @@ ask_examples:
   - How do I see what tools the agent is allowed to use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - safety
   - safe mode
@@ -35,18 +36,23 @@ keywords:
   - absolute block
   - disallowed tools
   - approval
+  - execution mode
+  - risk tier
 related:
+  - concepts/safety-model
   - concepts/skills
   - features/operations/approvals
   - reference/disallowed-tools
 ui_anchors:
   - /settings/advanced
+  - /settings/models
 config_keys:
   - disallowedTools
   - allowedToolsOverride
   - claudeExecutionPermissionMode
   - codexExecutionPermissionMode
   - geminiExecutionPermissionMode
+  - opencodeExecutionPermissionMode
 ---
 
 # Safety and Execution Modes
@@ -57,10 +63,13 @@ Three layers gate what the agent can do:
 
 1. **Skill `allowed-tools`** — the visible toolset for that session.
 2. **Execution mode** — Safe (strict permission checks, sandboxes)
-   or Allow (SDK bypass, sandbox off). Per-backend.
-3. **Always-disallowed** — a hard floor. Recursive deletes, sudo,
+   or Allow (SDK bypass, sandbox off). Set per-backend.
+3. **Always-disallowed** — a hard floor. Recursive deletes, `sudo`,
    secret-file reads / writes are denied unconditionally regardless
-   of mode.
+   of mode, and neither a skill nor Allow mode can widen past it.
+
+A fourth idea — the **risk tier** — sits on top of the daemon API and
+decides whether a *write* runs on its own or waits for your approval.
 
 ## Why This Concept Exists
 
@@ -72,37 +81,57 @@ disallowed-tools floor.
 
 ## Definitions
 
-- **Safe mode**: the default. Strict permission checks, Claude curl/jq
-  hooks, Codex workspace-write sandbox, Gemini whitelist TOML.
+- **Safe mode**: the default. Strict permission checks, plus a
+  backend-specific enforcement layer — Claude curl/jq hooks, the Codex
+  workspace-write sandbox, the Gemini whitelist TOML, and the OpenCode
+  permission block.
 - **Allow mode**: the looser posture. SDK bypass, sandbox off, minimal
-  TOML. The absolute-block layer still holds.
+  TOML. The absolute-block layer still holds in Allow mode, so the
+  destructive-ops floor never opens. Set independently per backend, so
+  one backend can run Allow while the others stay Safe.
 - **Absolute block**: the unconditional layer. `ALWAYS_DISALLOWED_TOOLS`
   in `src/safety/always-disallowed.ts`. Cannot be widened by skills,
   by config, or by allow-mode.
-- **Risk tier**: `read`, `notify`, `approve`. Read = autonomous. Notify
-  = the agent proceeds after DMing the operator. Approve = blocked
-  until the operator clicks approve in the dashboard.
+- **Risk tier**: every daemon-API operation carries one of three tiers —
+  `autonomous`, `read_sensitive`, or `approve`. *Autonomous* runs without a
+  prompt. *Read-sensitive* reads (email, calendar, notes, context files) are
+  the same blast radius as autonomous but are gated by a read token when
+  `enforceReadToken` is on. *Approve* is blocked until you confirm with a
+  bearer token (the dashboard does this when you click Approve). There is no
+  separate "notify" tier — that behaviour now lives in the skill prompts: for
+  potentially destructive actions the agent DMs you first, then proceeds. See
+  [Safety model](safety-model.md) for the full taxonomy.
 
 ## Concrete Examples
 
-| Action | Risk tier |
+The daemon API is the agent's only write path, so most of its own writes are
+`autonomous` (the memory chokepoint validates and snapshots them). The
+absolute-block layer and Approve tier are where the agent is actually stopped.
+
+| Action | What gates it |
 |---|---|
-| Read `today.md` | read |
-| Append to `agent/journal.md` | notify |
-| Send a DM | notify |
-| Update `roadmap.md` | approve |
-| Recursive delete | absolute-block (refused) |
-| `chmod` on a daemon-owned file | absolute-block |
+| Read `state/today.md` | `read_sensitive` (read token if `enforceReadToken`) |
+| Append to `journal/agent.md` | `autonomous` — daemon API write |
+| Update `plans/roadmap.md` | `autonomous`, plus a roadmap write-lock |
+| Send a DM | `autonomous`; destructive follow-ups DM you first |
+| Configure an automation trigger | `approve` — needs a bearer token |
+| `chmod` on a daemon-owned file | Safe-mode disallowed (allowed in Allow mode) |
+| Recursive delete (`rm -rf`), `sudo`, secret-file read | absolute-block (refused in both modes) |
 
 ## Where You See It in the Dashboard
 
-- **Settings → Advanced** holds `disallowedTools`, `allowedToolsOverride`,
-  and the per-backend execution mode switch.
-- **Activity** logs every blocked tool call as `action_type='blocked_absolute'`.
+- **Settings → Advanced** holds the `disallowedTools` and
+  `allowedToolsOverride` tool-policy lists.
+- **Settings → Models & Cost** holds the per-backend Safe / Allow
+  **Execution Mode** switch (you can also set it in the setup wizard).
+- **Activity** logs every absolute-blocked tool call as
+  `action_type='blocked_absolute'`.
 - **Approvals** is where Approve-tier actions queue when they fire.
 
 ## Related
 
+- [Safety model](safety-model.md) — the full risk-tier taxonomy and where
+  each API endpoint is classified.
 - [Skills](skills.md) — where each session's per-task `allowed-tools` lives.
 - [Approvals](../features/operations/approvals.md) — the operator-side
   surface for Approve-tier actions.

package/agent-assets/docs/concepts/safety-model.md

@@ -12,19 +12,20 @@ aliases:
   - on-demand retrospective
 category: concepts
 summary: |
-  Aitne's safety model collapsed from four tiers to two: most
-  actions run autonomously, a small set of posture-changing operations
-  require explicit Approve. The previous Notify tier (DM the operator
-  before / during a write) was abolished — the operator's `deniedTools`
-  list is now the primary defense, and "what did the agent do?" is
-  answered on demand via `GET /api/agent/actions` instead of pushed as
-  a daily digest.
+  Aitne's risk classifier dropped from three write tiers to two: most
+  actions run autonomously, and a small set of posture-changing
+  operations require explicit Approve. The previous Notify tier (DM the
+  operator before / during a write) was abolished — the operator's
+  `deniedTools` list is now the primary defense, and "what did the
+  agent do?" is answered on demand via `GET /api/agent/actions` instead
+  of pushed as a daily digest. (The read-gating `ReadSensitive` tier is
+  unchanged.)
 section: safety
 tags:
   - core
   - safety
   - integrations
-  - skills
+  - audit
 status: stable
 ask_examples:
   - Why doesn't the agent ask before sending an email anymore?
@@ -33,7 +34,7 @@ ask_examples:
   - Where do I see what the agent has been doing?
 locale: en-US
 created: 2026-04-26
-updated: 2026-05-17
+updated: 2026-06-07
 keywords:
   - deniedTools
   - safety floor
@@ -50,10 +51,16 @@ related:
   - reference/disallowed-tools
 ui_anchors:
   - /connections
-  - /settings/cost
-config_keys:
-  - integrations
-  - deniedTools
+  - /connections/mail
+  - /connections/calendar
+  - /analytics
+api_endpoints:
+  - GET /api/agent/actions
+  - POST /api/integrations/:key/exec
+  - PATCH /api/integrations/:key
+context_files:
+  - policies/integrations.md
+  - journal/agent.md
 ---
 
 # Safety Model (deniedTools + Approve Tier)
@@ -67,8 +74,8 @@ The risk classifier has two write tiers, not three:
   delete event, …) and for normal context writes.
 - **Approve** — agent must present a Bearer token issued through the
   dashboard. Reserved for posture-changing daemon configuration:
-  flipping integration modes, swapping the main backend, deleting
-  backends, wiping config.
+  flipping integration modes, swapping the main backend, enabling/
+  disabling backends, wiping config.
 - (`ReadSensitive` is the third tier, but it gates *reads* of personal
   data — orthogonal to write notifications. It is unchanged.)
 
@@ -123,27 +130,26 @@ of "report to me" events. Information about what the agent did is
   bare `*`.
 - **`/api/integrations/:key/exec`** — the cross-backend chokepoint
   (task mode; the RPC-style `/invoke` route was retired 2026-05-01,
-  see `docs/design/17-delegated-mode-v2.md` §4.2). Enforces `deniedTools`
-  server-side by filtering the integration's `capabilityTools` through
-  the deny list before spawning the delegated backend, so the
-  task-mode planner can only pick from the allowed surface. A
-  fully-denied surface short-circuits with `errorClass: "denied_tool"`
-  before any subprocess spawn.
+  see `docs/design/17-delegated-mode-v2.md` §4.2). It enforces
+  `deniedTools` server-side — see the *Where the Defenses Apply* table
+  below for the exact mechanism.
 - **`agent_actions`** — SQLite table of every agent action. Direct +
-  cross-backend rows are full-fidelity (current cross-backend writes
+  cross-backend rows are full-fidelity (cross-backend task-mode writes
   emit `delegated_task.run` / `delegated_task.exec` /
-  `delegated_task.tool_step`; legacy rows from before 2026-05-01 carry
-  `delegated_proxy.invoke`). Same-backend native MCP rolls up to
+  `delegated_task.tool_step`; the `delegated_proxy.invoke` row type
+  carries both legacy rows from the retired RPC `/invoke` route and
+  the hourly drift-detection probes still written by the
+  delegated-sync worker). Same-backend native MCP rolls up to
   `mcp_tool_calls` + the parent session row.
 
 ## Where the Defenses Apply
 
 | Path | Enforcement |
 |---|---|
-| Direct mode (`/api/mail/*`, `/api/calendar/*`) | Route handler middleware checks `deniedTools` against the materialized skill body's `allowed-tools` list (frontmatter). |
+| Direct mode (`/api/mail/*`, `/api/calendar/*`) | `deniedTools` is **inert** — the daemon runs the poller and the agent calls the daemon API through its direct-mode skill, so there is no per-tool deny surface. The list only persists for a future flip to delegated mode. Direct-mode safety comes from the route-level risk tiers (Approve gates posture-changing writes) and the always-disallowed layer, not `deniedTools`. |
 | Cross-backend (`/api/integrations/:key/exec`) | Invoker filters the integration's `capabilityTools` through `deniedTools` before spawning the delegated backend so the task-mode planner can only pick from the allowed surface. A fully-denied surface short-circuits with `errorClass: "denied_tool"`; individual tool denials surface as the same error from the invoker's `resolveAllowedToolPatterns`. |
 | Same-backend / native MCP — Claude | `collectSessionDeniedTools` merges the deny patterns into the SDK's `disallowedTools` array at `query()` time. Same code path covers both delegated same-backend and native — they share the in-session MCP surface. |
-| Same-backend / native MCP — Gemini | Patterns are folded into `generateAdminPolicy`'s TOML deny rules (priority 1000). |
+| Same-backend / native MCP — Gemini | Patterns are folded into `generateAdminPolicy`'s TOML deny rules (priority 936 — above the registry-driven native allows, below the absolute-block layer). |
 | Same-backend / native MCP — Codex | **Prose-only.** Codex bundles its connector apps into the binary; there is no per-tool deny config and the workspace-write sandbox does not match MCP tool calls. Skill prose lists the denied tools explicitly. Operators who require strict deny on Gmail / Calendar should pick a non-Codex DM backend or route those integrations through `delegated` cross-backend mode (which IS deny-enforced at `/exec`). |
 
 ## Recommended Starter Denylists
@@ -220,26 +226,29 @@ When the operator asks "what did you do yesterday?" / "have you sent
 anything from Gmail this week?" the agent calls:
 
 ```bash
-curl 'http://localhost:8321/api/agent/actions?since=2026-04-25T00:00:00Z&kind=delegated_task.run&kind=delegated_task.tool_step&limit=50'
+curl 'http://localhost:8321/api/agent/actions?since=2026-04-25T00:00:00Z&kind=delegated_task.exec&kind=delegated_task.tool_step&limit=50'
 ```
 
 and answers in conversation. The endpoint:
 
 - Lives at `Autonomous` tier — the agent reads only its own audit
   trail, no operator data.
-- Accepts `since`, `kind` (repeat for multiple values, e.g.
-  `?kind=a&kind=b`), `limit` (default 50, max 200).
-- Redacts values via the standard secret-redaction utility before
-  serializing.
-- Returns rows from `agent_actions`, optionally joined with
-  `mcp_tool_calls` when `kind=mcp` (same-backend / native MCP).
-
-Common `kind` values for the cross-backend proxy: `delegated_task.run`
-(one row per `/exec` call), `delegated_task.exec` (the planner's
-chosen tool), `delegated_task.tool_step` (each individual tool call
-inside the task). The legacy `delegated_proxy.invoke` rows persist
-from before 2026-05-01 — include them if the `since` window crosses
-that date.
+- Accepts `since` (ISO-8601; defaults to the last 24h if omitted),
+  `kind` (an `action_type` filter — repeat for multiple values, e.g.
+  `?kind=a&kind=b`), and `limit` (default 50, max 200).
+- Redacts the free-text `error` / `detail` fields via the standard
+  secret-redaction utility before serializing.
+- Returns rows from `agent_actions` only. Same-backend / native MCP
+  calls surface as their own `action_type` rows (e.g. `kind=mcp`);
+  the per-call detail lives in `mcp_tool_calls`, which this endpoint
+  does not join — query it separately if you need step-level fidelity.
+
+Common `kind` values for the cross-backend proxy: `delegated_task.exec`
+(one header row per `/exec` call), `delegated_task.run` (one header row
+per generic `/run` call), `delegated_task.tool_step` (each individual
+tool call inside the task). The `delegated_proxy.invoke` rows cover the
+retired RPC `/invoke` route plus the delegated-sync worker's hourly
+drift-detection probes — include them when you want that surface too.
 
 This **replaces** the rejected daily-digest pattern. Reasons:
 
@@ -248,7 +257,7 @@ This **replaces** the rejected daily-digest pattern. Reasons:
 - The operator does not have to manage the agent's reporting calendar.
 
 The optional fallback — extending the existing morning routine to
-summarize yesterday's `agent_actions` into `agent/journal.md` — is
+summarize yesterday's `agent_actions` into `journal/agent.md` — is
 deferred until the on-demand path proves insufficient.
 
 ## What Stayed Approve-Tier
@@ -262,21 +271,23 @@ Approve still gates:
 
 - `PATCH /api/integrations/:key` — mode / `delegatedBackend` /
   `deniedTools` changes.
-- `PUT /api/backends/main`, `DELETE /api/backends/:id`.
+- `PUT /api/backends/main`, `POST /api/backends/:id/enable`,
+  `POST /api/backends/:id/disable`.
 - `PATCH /api/config` for fields that wipe protections.
 - `/api/system/*` — config reset, history purge, factory reset.
 
 ## Where You See It in the Dashboard
 
-- **Connections → \<integration\> → Tool Permissions** — the
+- **Connections → \<integration\> → Tool Permissions**
+  (e.g. `/connections/mail`, `/connections/calendar`) — the
   `deniedTools` editor with the starter list pre-populated. Above the
-  editor, the safety guidance prose explains each entry and which the
-  team recommends keeping.
-- **Settings → Cost → Delegated proxy facet** — only cross-backend
-  invocations show here; same-backend rolls up under the parent
-  session.
-- **Activity / Audit** — every action with full attribution, queried
-  the same way the agent queries `GET /api/agent/actions`.
+  editor, the safety guidance prose explains each entry and which ones
+  are recommended to keep.
+- **Analytics** (`/analytics`) — spend and the delegated-task facet;
+  only cross-backend invocations show here, while same-backend MCP
+  rolls up under the parent session.
+- **Activity** (`/activity`) — every action with full attribution,
+  the same audit trail the agent reads via `GET /api/agent/actions`.
 
 ## Related
 

package/agent-assets/docs/concepts/skills.md

@@ -18,15 +18,17 @@ tags:
   - skills
   - safety
   - knowledge
+  - backends
 status: stable
 ask_examples:
   - What skills does the agent have?
   - How do I add a new skill?
   - Why does the agent refuse to run a tool?
   - How does skill self-optimization work?
+  - Where do skill overlays live?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-06-07
 keywords:
   - SKILL.md
   - allowed-tools
@@ -45,6 +47,15 @@ ui_anchors:
   - /knowledge
   - /connections/mcp
   - /settings/self-learning
+process_keys:
+  - dashboard.docs_qa
+  - routine.skill_curation
+config_keys:
+  - allowedToolsOverride
+  - disallowedTools
+api_endpoints:
+  - GET /api/skills
+  - GET /api/skills/manifest/:processKey
 ---
 
 # Skills
@@ -63,7 +74,7 @@ The agent runs against a real machine. Without scoped permissions, a
 "please summarize my mail" turn could in principle invoke `Bash(rm)`,
 post to your social accounts, or rewrite arbitrary files. Skills fix
 that by making the available toolset task-shaped: the morning routine
-loads the routines/observations/today/schedule skills; a docs question
+loads the context/today/observations/schedule skills; a docs question
 loads only `docs-search`. Tools outside the allow-list aren't even
 visible to the model.
 
@@ -71,9 +82,11 @@ visible to the model.
 
 - **SKILL.md**: the Markdown file that defines a single skill. Lives
   under `agent-assets/skills/<slug>/SKILL.md` in the repo and is
-  materialized into each session workdir as `.claude/skills/<slug>/SKILL.md`
-  (Codex uses `.codex/skills/`, Gemini uses `.gemini/skills/`, OpenCode
-  reuses `.claude/skills/` per V2 of docs/design/appendices/opencode-backend.md).
+  materialized into each session workdir under a per-backend namespace —
+  `.claude/skills/<slug>/` for Claude, `.codex/skills/` for Codex,
+  `.gemini/skills/` for Gemini, and `.opencode/skills/` for OpenCode.
+  The frontmatter (`name`, `description`, `allowed-tools`) is byte-identical
+  across all four; only the destination directory changes.
 - **`allowed-tools`**: a YAML list in the skill's frontmatter naming
   tools and patterns the session may use. Patterns like
   `Bash(curl http://localhost:8321/api/context/*)` are the daemon's
@@ -86,7 +99,7 @@ visible to the model.
 
 ## Concrete Examples
 
-- `today` — read and rewrite `today.md`.
+- `today` — read and rewrite `state/today.md`.
 - `schedule` — produce per-date schedule files from the calendar.
 - `mail` — search and label messages via the daemon's mail proxy.
 - `docs-search` — read-only fetch over the docs corpus, used only by
@@ -97,26 +110,29 @@ visible to the model.
 
 Skills aren't frozen. A background process — **skill curation** —
 watches how your knowledge layout drifts (file moves, new
-sub-folders, schema tweaks in `user/`, `projects/`, etc.) and
-proposes JSON **overlays** that update specific sections of the
+sub-folders, schema tweaks under `identity/`, `plans/projects/`, etc.)
+and proposes JSON **overlays** that update specific sections of the
 relevant skill: knowledge layout, routing tables, frontmatter
 schema, search recipes, convention notes, cross-references.
 
-Overlays live at `<dataDir>/overlays/<skill>/<section-id>.json` and
-are merged in by the SkillsCompiler at session-init. The original
+Overlays live at `<dataDir>/skill-curation-overlays/<slug>/<section_id>.json`
+and are merged in by the SkillsCompiler at session-init. The original
 `SKILL.md` files in `agent-assets/skills/` are never rewritten;
-disabling the overlay (or deleting the JSON file) reverts to the
+disabling self-learning (or deleting the JSON file) reverts to the
 seed payload immediately.
 
 The optimizer agent runs in an isolated workdir with a tightly
 scoped toolset (`Bash(curl http://localhost:8321/api/skill-curation/*)`,
-`Read`) and an auto-revert safety net — if the next run sees more
-drift signals than the previous overlay generated, the section is
-reverted and frozen for two cycles.
-
-Curation cadence, manual-run trigger, and the per-skill exclusion
-list are surfaced at **Settings → Self-learning**
-(`/settings/self-learning`).
+`Read`) and an auto-revert safety net: each cadence cycle the daemon
+re-checks recently-applied overlays, and any section that has
+accumulated *more* drift signal weight after the overlay was applied
+than before is rolled back automatically and frozen for two cycles to
+stop thrashing. This is the only roll-back path — there is no
+per-proposal approve/reject API, just the on/off toggle.
+
+Skill curation is **off by default**. The master toggle, curation
+cadence, manual-run trigger, and the per-skill exclusion list are all
+surfaced at **Settings → Self-learning** (`/settings/self-learning`).
 
 ## Where You See It in the Dashboard
 

package/agent-assets/docs/features/integrations/browser-history.md

@@ -0,0 +1,196 @@
+---
+schema_version: 1
+slug: features/integrations/browser-history
+title: Browser History
+id: browser-history
+aliases:
+  - browser history
+  - browsing history
+  - research clusters
+  - reload memory
+  - B-3
+category: features
+summary: |
+  Local-only poller that reads the browser's own SQLite databases
+  (Chrome / Chromium / Edge / Brave / Comet / Atlas), records visits as
+  observations, derives research clusters from sustained reading
+  patterns, and surfaces what you keep refreshing. Nothing leaves the
+  daemon.
+section: integrations
+tags:
+  - integrations
+  - observations
+  - browser-history
+  - polling
+  - autonomous
+status: stable
+ask_examples:
+  - How does Aitne use my browser history?
+  - What is a research cluster?
+  - What does `!checks` show?
+  - Does my browsing data go anywhere?
+  - How do I opt out of browser history?
+locale: en-US
+created: 2026-05-22
+updated: 2026-06-07
+keywords:
+  - browser history
+  - browser history poller
+  - research cluster
+  - reload signal
+  - "!checks"
+  - "!research"
+  - shopping comparison
+  - two-option offer
+  - local-only
+related:
+  - features/messaging/bang-commands
+  - features/integrations/notion
+  - features/operations/managed-chromium
+  - features/routines/weekly-review
+  - features/routines/morning-routine
+ui_anchors:
+  - /settings/integrations/browser-history
+config_keys:
+  - browserHistoryConsentAccepted
+  - browserHistoryBrowserOverrides
+  - browserHistoryCategories
+  - browserHistoryRetentionDays
+  - browserHistorySearchQueryRetentionDays
+  - browserHistoryLifecycle
+  - browserHistoryResearchDomainAllowlist
+  - browserHistoryResearchDomainDenylist
+process_keys:
+  - routine.research_cluster_update
+  - routine.research_offer_dm
+  - routine.research_dispatch
+  - routine.research_wiki_summary
+api_endpoints:
+  - GET /api/browser-history/status
+  - GET /api/browser-history/research-clusters
+  - POST /api/browser-history/offers/:slug/accept
+  - POST /api/browser-history/offers/:slug/decline
+  - GET /api/browser-history/reloads/weekly
+---
+
+# Browser History
+
+Aitne can read the SQLite history databases that Chrome, Chromium,
+Edge, Brave, Comet, and Atlas already maintain on disk, classify visits
+into categories, and use the result to notice what you've been
+researching, what you've been refreshing, and what comparison-shopping
+windows you're in. Everything stays local — no URLs, titles, or
+clicks leave the daemon.
+
+## What It Does
+
+- **Reads visits** from the browser's own history DB on a 30-min
+  cadence (per browser, per profile) and inserts them into the
+  daemon's `browser_visits` table.
+- **Counts reloads** per `<domain>/<first-path>` into
+  `browser_reload_signals`. Surfaced via [`!checks`](../messaging/bang-commands.md)
+  for the agent-day and via the weekly review's "this week you
+  checked" block.
+- **Derives research clusters** when a topic crosses meaningful-visits
+  / foreground-time / distinct-domain thresholds. Clusters live in
+  `browser_research_clusters` with a slug, display name, journal at
+  `context/research/<slug>.md`, and a status (`active | dormant |
+  muted | concluded`).
+- **Offers engagement DMs** via the Two-Option Offer pattern when a
+  cluster qualifies: pick "research dive" (parallel web research +
+  summary) or "wiki summary" (Obsidian / Notion / local context).
+  Accept paths run through `routine.research_dispatch` /
+  `routine.research_wiki_summary`; decline silences offers for 14
+  days; mute / unmute / rename / conclude via [`!research`](../messaging/bang-commands.md).
+- **Detects shopping comparison windows** — 90-min sliding windows
+  containing ≥3 distinct ASINs surface as comparison sessions the
+  agent can summarise.
+- **Powers the pre-morning digest** — yesterday's reading and reload
+  patterns feed the morning routine's pre-pass digest.
+
+## Privacy and Consent
+
+- **Default off.** The integration does not start until the operator
+  flips `browserHistoryConsentAccepted = true` on the
+  **Settings → Integrations → Browser History**
+  (`/settings/integrations/browser-history`) page. The integration only
+  supports `direct` (the daemon poller) or `disabled` — there is no
+  delegated or native mode.
+- **Local-only.** No request leaves the daemon. The browser's
+  history file is opened read-only; the daemon never reaches into
+  cookies, login sessions, or profile dirs other than the history DB.
+- **Per-browser opt-in.** `browserHistoryBrowserOverrides` lets you
+  enable / disable each detected browser independently and override
+  the DB path for atypical installs.
+- **Per-category gate.** `browserHistoryCategories` controls which
+  visit categories (research / shopping / news / dev / entertainment / …) get
+  ingested. Categories you exclude are dropped at ingest time, not
+  filtered later.
+- **Retention.** `browserHistoryRetentionDays` (visits) and
+  `browserHistorySearchQueryRetentionDays` (search queries) cap the
+  on-disk window; older rows are deleted on the next ingest tick.
+- **Domain controls.** `browserHistoryResearchDomainAllowlist` /
+  `…Denylist` filter which domains can qualify a research cluster.
+
+## How Clusters Qualify
+
+A research cluster qualifies when the combination of meaningful visits,
+foreground time, and distinct domains crosses the thresholds in
+`DEFAULT_OFFER_THRESHOLDS` (tunable via `browserHistoryLifecycle`).
+On each tick the poller evaluates the offer triggers per active cluster
+(`evaluateOfferTriggers`); once the **per-cluster offer rate-limit gate**
+(`gateOfferRateLimit`) approves — this is the 14-day, per-slug offer
+backoff, not the daemon-wide session gate that Phase 9 removed — a
+Two-Option Offer DM is composed by the `routine.research_offer_dm`
+process key.
+
+Accepting either path clears every pending-offer row for that slug, so a
+later tick cannot re-offer the same cluster.
+
+## Owner Controls
+
+| Surface | What it does |
+|---|---|
+| `!checks` | Today's top reload patterns (pure DB read, safe while paused). |
+| `!research` | List active + dormant clusters. |
+| `!research <slug>` | Show one cluster's detail. |
+| `!research accept <slug>` | Enqueue `routine.research_dispatch`. |
+| `!research wiki <slug>` | Enqueue `routine.research_wiki_summary`. |
+| `!research decline <slug>` | Silence offers for 14 days. |
+| `!research mute <slug>` / `unmute` | Toggle offers off (until unmute) / restore. |
+| `!research rename <slug> <new name>` | Change display name. |
+| `!research conclude <slug>` | Mark concluded; preserve the journal. |
+| Natural-language reply to an offer DM | The `browser-history-respond` skill bridges into the same `/api/browser-history/offers/<slug>/{accept,decline}` call. |
+
+## When It Runs
+
+| Signal | Cadence | Source |
+|---|---|---|
+| Visit ingest | Every 30 min per browser profile | `BrowserHistoryPoller` |
+| Cluster engagement evaluation | Same tick as visit ingest | `pipeline/offer-triggers.ts` |
+| Shopping-comparison window scan | Same tick, 7-day lookback | `SHOPPING_COMPARISON_WINDOW_MS` constants |
+| Nightly journal append | Agent-day boundary | `routine.research_cluster_update` (lite tier, one row per active cluster per day) |
+| Weekly reload-memory block | Friday weekly review | `routine.weekly_review` reads `/api/browser-history/reloads/weekly` |
+| Pre-morning digest | Morning routine pre-pass | Yesterday's reading + reloads feed the digest block |
+
+## When Something Goes Wrong
+
+- **The settings page shows no browsers.** Open
+  `/settings/integrations/browser-history` and run `aitne doctor` — the
+  platform detector might be failing to resolve the user's profile dir.
+  The daemon log line will name the candidate paths it tried.
+- **A cluster keeps re-offering.** Check the `lastResearchOfferAt` /
+  `lastWikiOfferAt` columns; the rate-limit gate uses those for the
+  14-day backoff. `!research decline <slug>` stamps both fields.
+- **`!checks` is empty.** That's the common case for a quiet day —
+  the reload signals are gated to the agent-day, not UTC.
+
+## Related
+
+- [Managed Chromium](../operations/managed-chromium.md) — separate
+  experimental flow for *driving* a Chromium profile (B-4), not
+  reading browser history.
+- [Weekly Review](../routines/weekly-review.md)
+- [Morning Routine](../routines/morning-routine.md)
+- [Bang Commands](../messaging/bang-commands.md)
+- [Glossary: Research Cluster](../../glossary.md#research-cluster)