@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/reference/config.md

@@ -3,72 +3,279 @@ schema_version: 1
 slug: reference/config
 title: Config Reference
 id: config-ref
+aliases:
+  - config
+  - AgentConfig
+  - settings keys
+  - runtime config
 category: reference
 summary: |
-  All AgentConfig fields, their types, and where each is set
-  (environment, database settings table, or in-process default).
+  Source-of-truth map for AgentConfig — where each field is set
+  (env, dashboard PATCH, OS keychain), which fields require a restart,
+  and pointers to the canonical key tuples in shared/.
 section: config
 tags:
+  - core
   - reference
   - config
+  - operations
+  - backends
 status: stable
 ask_examples:
   - What configuration keys does the agent expose?
   - Where does config get loaded from?
+  - How do I change the day boundary?
+  - Which config keys are runtime-editable from the dashboard?
+  - Which keys need a daemon restart?
+  - Where is the pre-pass freshness window set?
+  - What is the default daily cost cap?
 locale: en-US
+keywords:
+  - AgentConfig
+  - applyConfigUpdates
+  - EDITABLE_RUNTIME_KEY_TUPLE
+  - RESTART_REQUIRED_KEY_TUPLE
+  - dayBoundaryHour
+  - hourlyCheckIntervalMinutes
+  - quietHoursStart
+  - quietHoursEnd
+  - executeTimeoutMinutes
+  - autonomousDailyCostCapUsd
+  - allowedToolsOverride
+  - voiceTranscriptionEnabled
+  - hourlyCheckPrePassFreshnessMinutes
+  - vaultMode
+  - PA_DATA_DIR
+  - PA_API_PORT
+config_keys:
+  - dayBoundaryHour
+  - timezone
+  - primaryLanguage
+  - vaultMode
+  - hourlyCheckEnabled
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckPrePassFreshnessMinutes
+  - quietHoursStart
+  - quietHoursEnd
+  - maxNotificationsPerHour
+  - maxNotificationsPerDay
+  - maxConcurrentSessions
+  - maxReactiveSessions
+  - executeTimeoutMinutes
+  - autonomousDailyCostCapUsd
+  - autonomousMonthlyCostCapUsd
+  - disallowedTools
+  - allowedToolsOverride
+  - claudeExecutionPermissionMode
+  - enabledMailProviders
+  - voiceTranscriptionEnabled
+  - advisorEnabled
+  - advisorModel
+api_endpoints:
+  - PATCH /api/config
+  - POST /api/voice/install
+ui_anchors:
+  - /settings/advanced
+  - /settings/models
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 related:
   - reference/api
+  - reference/cli-commands
+  - reference/disallowed-tools
+  - concepts/safety-and-execution
 ---
 
 # Config Reference
 
-The full schema is `AgentConfig` in `packages/daemon/src/config.ts`.
-A subset listed in `applyConfigUpdates` is mutable at runtime via
-`PATCH /api/config`. The rest must be set via env or restart.
+The full `AgentConfig` schema lives in
+`packages/daemon/src/config.ts`. Three canonical tuples in
+`packages/shared/src/editable-config-keys.ts` govern what is editable
+and when:
+
+- **`EDITABLE_RUNTIME_KEY_TUPLE`** — the ~80 keys mutable at runtime
+  via `PATCH /api/config`. Both the daemon and the dashboard import
+  from this tuple so the accepted-key set is enforced at compile time
+  in both packages.
+- **`RESTART_REQUIRED_KEY_TUPLE`** — runtime-editable keys whose
+  change does not apply to a running worker (the dashboard renders a
+  restart-required badge for these).
+- **`EDITABLE_BOOTSTRAP_KEY_TUPLE`** — `apiPort` only, written to
+  `.env` because it's read before the daemon binds.
+
+Anything not in those tuples must be set via env or restart.
+
+## Where Each Field Comes From
+
+| Source | What lives there |
+|---|---|
+| `.env` | `PA_DATA_DIR`, `PA_API_PORT`, log level, the bootstrap port from `EDITABLE_BOOTSTRAP_KEY_TUPLE`. Chmod 0600 on first launch; never store secrets here. |
+| OS keychain | All secrets — backend API keys, messaging tokens, OAuth grants. Resolved via `PlatformSecretStore` (macOS Keychain / Windows DPAPI / Linux libsecret or AES-GCM file). |
+| `settings` DB table | Runtime-edited values from `EDITABLE_RUNTIME_KEY_TUPLE`, merged on top of env at boot via `mergeRuntimeSettingsFromDb`. |
+| `runtime_state` DB table | Operational state that the agent or daemon writes (pause flag, integration flip locks, pre-pass freshness, B-4 toggles). Not editable as config. |
 
 ## Selected Keys
 
-| Key | Type | Default |
+A representative slice of `EDITABLE_RUNTIME_KEY_TUPLE` — the full list
+of ~80 keys is in `editable-config-keys.ts`. Names below are exact and
+case-sensitive.
+
+### Identity and timezone
+
+| Key | Type | Notes |
+|---|---|---|
+| `agentDisplayName` | string | What the agent calls itself in DMs. |
+| `character` | string | Persona key (one of the entries in `agent-assets/agent-profiles/`). |
+| `timezone` | IANA tz | Empty falls back to the system tz. |
+| `dayBoundaryHour` | 0–9 | Default `4`. Controls the agent-day rollover (must be an early-morning hour). |
+| `primaryLanguage` | BCP-47 | Output language for DMs, journal, and Obsidian writes. Templates stay English-headered. |
+| `vaultMode` | enum | Where context lives — `plain` (default; `<dataDir>/context`) or `obsidian` (an external Obsidian vault). |
+
+### Hourly check and gate
+
+| Key | Type | Notes |
+|---|---|---|
+| `hourlyCheckEnabled` | boolean | Default `true`. |
+| `hourlyCheckIntervalMinutes` | number | Default `60`. |
+| `hourlyCheckActiveStartHour` | 0–23 | Default `4`. |
+| `hourlyCheckActiveEndHour` | 1–24 | End-exclusive; `24` ≡ midnight. |
+| `hourlyCheckMinObservations` | number | Default `1`. |
+| `hourlyCheckStage2Enabled` | boolean | cost-reduction-structural §B Stage 2 toggle. |
+| `hourlyCheckHeartbeatHours` | number | Quiet-day heartbeat cadence. |
+| `hourlyCheckLowSignalPendingCeiling` | number | Low-signal ceiling before forcing dispatch. |
+| `hourlyCheckPrePassFreshnessMinutes` | number | Layer-1 freshness window — `harvestForGate` skips a per-integration fetch if `runtime_state.pre_pass_last_run:<key>` is fresher. |
+
+### Notifications and quiet hours
+
+| Key | Type | Notes |
+|---|---|---|
+| `quietHoursStart` / `quietHoursEnd` | `HH:MM` | Defaults `"22:00"` / `"08:00"`. |
+| `maxNotificationsPerHour` | number | Default `3`. |
+| `maxNotificationsPerDay` | number | Default `12`. |
+| `batchIntervalMinutes` | number | Notification batching window. |
+| `primaryPlatform` | enum | Channel the agent defaults to for new DMs. |
+| `defaultNotificationPlatforms` | enum[] | Fan-out set. |
+
+### Sessions and execution
+
+| Key | Type | Notes |
+|---|---|---|
+| `maxConcurrentSessions` | number | Default `3`. |
+| `maxReactiveSessions` | number | Sub-cap reserved for DM/mention work. |
+| `executeTimeoutMinutes` | number | Per-execute wall-clock cap. |
+| `sessionTimeoutDmMinutes` / `…ChannelMinutes` / `…DashboardMinutes` | number | Idle TTLs per surface. |
+| `historyInjectionMaxMessages` / `…MaxTokens` | number | History-window caps for next-turn injection. |
+| `autonomousDailyCostCapUsd` / `…MonthlyCostCapUsd` | number / null | Spend ceilings for autonomous work; default `null` (off). When set, must be positive. The daily cap makes the dispatcher skip autonomous sessions once the day's cumulative cost exceeds it — reactive DMs/mentions always pass through. The monthly cap is a notifications-only soft cap (no dispatcher enforcement). Distinct from the removed Phase-9 `maxDailyCostUsd`, which blanket-blocked every session. |
+
+### Safety and execution mode
+
+| Key | Type | Notes |
 |---|---|---|
-| `timezone` | IANA tz | `""` (falls back to system tz, e.g. `America/New_York`) |
-| `dayBoundaryHour` | 0–23 | `4` |
-| `hourlyCheckEnabled` | boolean | `true` |
-| `hourlyCheckIntervalMinutes` | number | `60` |
-| `hourlyCheckActiveStartHour` | 0–23 | `4` |
-| `hourlyCheckActiveEndHour` | 1–24 | `24` (end-exclusive; `24` ≡ midnight) |
-| `hourlyCheckMinObservations` | number | `1` |
-| `quietHoursStart` | `HH:MM` string | `"22:00"` |
-| `quietHoursEnd` | `HH:MM` string | `"08:00"` |
-| `maxNotificationsPerHour` | number | `3` |
-| `maxNotificationsPerDay` | number | `12` |
-| `batchIntervalMinutes` | number | `15` |
-| `executeTimeoutMinutes` | number | `60` |
-| `maxConcurrentSessions` | number | `3` |
-| `disallowedTools` | string[] | absolute-block defaults |
-| `allowedToolsOverride` | string[] | empty |
-| `autonomousDailyCostCapUsd` | number | `0` (off) |
-
-The runtime-mutable subset can be edited from `/settings/*`. Restart-only
-fields (e.g. `apiPort`) require `pa restart`.
-
-### Routine schedule keys do not exist
-
-Morning, evening, weekly, and monthly routines fire at fixed times in
-`packages/daemon/src/core/scheduler.ts`. There is no `morningRoutineHour`,
-`eveningReviewHour`, `weeklyReviewDay`, or `monthlyReviewHour` config key.
+| `disallowedTools` | string[] | Hard-deny tool matchers (Safe-mode strict set). |
+| `allowedToolsOverride` | string[] | Runtime widening — cannot widen past `ALWAYS_DISALLOWED_TOOLS`. |
+| `claudeExecutionPermissionMode` | `"safe"`/`"allow"` | Per-backend Safe/Allow posture. |
+| `codexExecutionPermissionMode` | `"safe"`/`"allow"` | Same; allow mode cannot enforce absolute-block on shell. |
+| `geminiExecutionPermissionMode` | `"safe"`/`"allow"` | Same. |
+| `opencodeExecutionPermissionMode` | `"safe"`/`"allow"` | Per-backend mode for OpenCode. |
+
+### Pre-pass and observation summarizer
+
+| Key | Type | Notes |
+|---|---|---|
+| `prePassMaxAttemptsPerIntegration` | number | Retry cap per integration in the routine pre-pass. |
+| `prePassBackoffMs` | number | Backoff between retries. |
+| `prePassRetryEscalationTier` | enum | Tier to escalate to on partial / failure. |
+| `prePassFanOutConcurrency` | number | Parallel integrations during pre-pass fan-out. |
+| `prePassMaxBudgetUsdPerIntegration` | number | Budget cap per integration per routine. |
+| `prePassMaxBudgetUsdPerRoutine` | number | Aggregate budget cap per routine. |
+| `prePassRetryOnPartial` | boolean | Whether partial results trigger a retry. |
+| `observationSummarizerEnabled` | boolean | cost-reduction-structural §A — observation summariser worker on/off. |
+| `observationSummarizerConcurrency` / `…MaxCallsPerMinute` / `…QueueLimit` / `…TimeoutMs` | number | Summariser tuning. **Restart-required** (worker captures these at boot). |
+
+### Mail / calendar / git / browser-history polling
+
+| Key | Type | Notes |
+|---|---|---|
+| `mailPollIntervalSeconds` / `mailIdleEnabled` / `mailIdleInstabilityThreshold` / `mailIdleFallbackRecoveryMinutes` / `mailMaxMessagesPerPoll` / `mailAuthFailureRetryHours` | various | Mail-poller knobs (multi-provider). |
+| `enabledMailProviders` | enum[] | Which providers participate. One or more of `gmail`, `outlook`, `yahoo`, `icloud`. Default `["gmail"]`. |
+| `vipMailSenders` | string[] | Sender list that bumps mail priority. |
+| `outlookDeltaPageSize` / `outlookGraphConcurrency` | number | Outlook Graph API tuning. |
+| `imapReconnectBaseMs` / `imapReconnectMaxMs` | number | IMAP reconnect backoff. |
+| `gmailPollIntervalSeconds` | number | Gmail-specific cadence (restart-required). |
+| `calendarPollIntervalSeconds` | number | Google Calendar poll interval. |
+| `notionPollIntervalSeconds` | number | Notion poll interval. |
+| `gitPollIntervalSeconds` / `githubPollIntervalSeconds` | number | Git / GitHub cadences (both restart-required — `GitWatcher` / `GitHubPoller` bind at construction). |
+| `browserHistoryConsentAccepted` | boolean | B-3 consent gate — must be `true` for the poller to start. |
+| `browserHistoryBrowserOverrides` | object | Per-browser opt-in/out and DB-path overrides. |
+| `browserHistoryCategories` | enum[] | Visit-category allowlist. |
+| `browserHistoryRetentionDays` / `…SearchQueryRetentionDays` | number | Retention windows. |
+| `browserHistoryLifecycle` | object | Cluster lifecycle thresholds. |
+| `browserHistoryResearchDomainAllowlist` / `…Denylist` | string[] | Domain filters for cluster qualification. |
+
+### Voice transcription
+
+| Key | Type | Notes |
+|---|---|---|
+| `voiceTranscriptionEnabled` | boolean | Whisper local transcription for voice attachments. Default `false`. Restart-required when the env var is set; live-flip via `POST /api/voice/install` (downloads weights with progress UI). |
+| `voiceTranscriptionPrimaryLanguage` | BCP-47 | Fallback language after Whisper's auto-detect. Live-applied on the next inbound audio attachment. |
+
+### Delegated tasks
+
+| Key | Type | Notes |
+|---|---|---|
+| `delegatedTaskModeEnabled` | boolean | Master kill switch for the `/api/integrations/:key/exec` task-mode endpoints. Default `false`; mutable at runtime so an emergency disable needs no restart. |
+| `delegatedTaskMaxPerDay` | number | Per-day quota. |
+| `delegatedTaskDefaultMaxToolCalls` / `…DefaultMaxBudgetUsd` / `…DefaultTimeoutMs` | various | Per-task defaults. |
+| `delegatedTaskHeavyEnabled` | boolean | Approve-tier opt-in gate for the heavy variant. |
+| `delegatedTaskStructuredOutputEnabled` / `…CacheEnabled` / `…CacheTtlSeconds` / `…CacheMaxEntries` / `…SubprocessPoolEnabled` / `…SubprocessPoolTtlSeconds` | various | Phase-3 optimisation kill switches (independent). |
+| `delegatedProxyMaxConcurrent` | number | Concurrency cap for the proxy worker. |
+
+### Advisor
+
+| Key | Type | Notes |
+|---|---|---|
+| `advisorEnabled` | boolean | SDK advisor toggle. |
+| `advisorModel` | string / null | Model id; default `null`. Validated against `ADVISOR_ALLOWED_MODELS`, which the SDK pins to `claude-sonnet-4-6` and `claude-opus-4-6` only. Newer Opus generations (`claude-opus-4-7`, `claude-opus-4-8`) are silently skipped by the SDK advisor path — see `docs/advisor.md`. |
+
+## Routine Schedule Times Are Not Configurable
+
+The morning, evening, weekly, and monthly routines fire at fixed times
+defined in `packages/daemon/src/core/scheduler.ts`. There is no
+`morningRoutineHour`, `eveningReviewHour`, or `weeklyReviewDay` key — to
+shift the whole day, change `dayBoundaryHour` instead.
 
 | Routine | Trigger |
 |---|---|
-| `routine.morning_routine` | daily at `dayBoundaryHour` |
-| `routine.evening_review` | daily at `18:00` local |
-| `routine.weekly_review` | Friday `18:00` local |
-| `routine.monthly_review` | last day of month at `18:00` local |
+| `routine.morning_routine` | Daily at `dayBoundaryHour` (default 04:00). |
+| `routine.evening_review` | Daily at `18:00` local. |
+| `routine.weekly_review` | Friday `19:00` local (one hour after the evening review). |
+| `routine.monthly_review` | Last day of the month at `18:00` local, but **disabled by default** (`monthlyReviewEnabled = false`). |
+
+The hourly check is the one autonomous routine with a configurable
+cadence (`hourlyCheckIntervalMinutes`) and active window
+(`hourlyCheckActiveStartHour` / `…ActiveEndHour`).
+
+## Restart-Required Keys
+
+The `RESTART_REQUIRED_KEY_TUPLE` covers fields whose new value is
+written through `applyConfigUpdates` but does not apply to a running
+worker — the dashboard renders a badge prompting an `aitne restart`.
+The current list:
 
-Only the hourly check has a configurable cadence (`hourlyCheckIntervalMinutes`)
-and an active window (`hourlyCheckActiveStartHour` / `…ActiveEndHour`).
+- `apiPort` (env-only)
+- `externalObsidianVaultName` / `externalObsidianVaultPath` / `externalObsidianWatch`
+- `primaryVaultPath` / `primaryVaultName`
+- `slackOwnerUserId` / `telegramOwnerChatId` / `discordOwnerUserId`
+- `whatsappEnabled` / `whatsappOwnerPhone` / `whatsappAuthDir`
+- `notionDatabaseIds`
+- `gmailPollIntervalSeconds` / `gitPollIntervalSeconds` / `githubPollIntervalSeconds`
+- `delegatedProbeIntervalMinutes`
+- `voiceTranscriptionEnabled` (only when `PA_VOICE_TRANSCRIPTION_ENABLED` env is set)
+- `observationSummarizerEnabled` / `…Concurrency` / `…MaxCallsPerMinute` / `…QueueLimit` / `…TimeoutMs`
 
 ## Related
 
 - [API](api.md)
+- [CLI Commands](cli-commands.md)
+- [Disallowed Tools](disallowed-tools.md)
+- [Safety and Execution](../concepts/safety-and-execution.md)

package/agent-assets/docs/reference/disallowed-tools.md

@@ -3,23 +3,40 @@ schema_version: 1
 slug: reference/disallowed-tools
 title: Disallowed Tools (Reference)
 id: disallowed-tools-ref
+aliases:
+  - disallowed tools
+  - blocked tools
+  - deny list
+  - absolute block
 category: reference
 summary: |
   The absolute-block tool patterns. Cannot be widened by config or
   by skill-level allow-lists. Mirrors src/safety/always-disallowed.ts.
-section: disallowed-tools
+section: reference
 tags:
   - reference
   - safety
+  - core
+  - audit
 status: stable
 ask_examples:
   - What can the agent never run?
   - Can I unblock a tool in the absolute-block list?
+  - Why can't the agent read my .env or SSH keys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-26
+updated: 2026-05-28
+keywords:
+  - disallowedTools
+  - deniedTools
+  - absolute block
+  - always-disallowed
+  - Bash(rm -rf)
+  - PreToolUse
+  - blocked_absolute
 related:
   - concepts/safety-and-execution
+  - concepts/safety-model
 ---
 
 # Disallowed Tools
@@ -39,20 +56,25 @@ or `allowedToolsOverride`. Source of truth:
 | Recursive delete | `Bash(rm -rf *)`, `Bash(rm -r *)`, `Bash(rm -R*)`, `Bash(rm -fr*)`, `Bash(rm --recursive*)`, plus the bypass-coverage family of every short-flag bundle containing `r`/`R` (see source) |
 | Privilege escalation | `Bash(sudo *)`, `Bash(doas *)`, `Bash(su *)` |
 | Pipe-to-shell RCE | `Bash(curl * | sh*)`, `Bash(curl * | bash*)`, `Bash(wget * | sh*)`, `Bash(wget * | bash*)`, `Bash(bash <(*)*)`, `Bash(sh <(*)*)`, `Bash(bash<*)`, `Bash(sh<*)`, `Bash(eval *)`, `Bash(source *)` |
-| Platform secret-management CLIs | `Bash(security *)` (macOS Keychain), `Bash(secret-tool *)` (libsecret), `Bash(cmdkey *)` (Windows Credential Manager) |
-| Secret-file reads | `Read(.env)`, `Read(.env.*)`, `Read(**/.env)`, `Read(id_rsa*)`, `Read(id_ed25519*)`, `Read(~/.ssh/**)`, `Read(~/.gnupg/**)`, `Read(~/.aws/**)`, `Read(~/.config/gcloud/**)`, `Read(~/.config/gh/hosts.yml)`, `Read(~/.netrc)`, `Read(~/Library/Keychains/**)`, `Read(~/.local/share/keyrings/**)` |
+| Platform secret-management CLIs | `Bash(security *)` (macOS Keychain), `Bash(secret-tool *)` (libsecret), `Bash(cmdkey *)` (Windows Credential Manager), `Bash(certutil *)` and `Bash(rundll32.exe *)` (Windows DPAPI / vault dump) |
+| Secret-file reads | `Read(.env)`, `Read(.env.*)`, `Read(**/.env)`, `Read(**/.env.*)`, `Read(id_rsa*)`, `Read(id_ed25519*)`, `Read(~/.ssh/**)`, `Read(~/.gnupg/**)`, `Read(~/.aws/**)`, `Read(~/.config/gcloud/**)`, `Read(~/.config/gh/hosts.yml)`, `Read(~/.netrc)`, `Read(~/Library/Keychains/**)`, `Read(~/.local/share/keyrings/**)` |
 | Daemon-managed secret surfaces | `Read(~/.personal-agent/backups/**)`, `Read(~/.personal-agent/whatsapp/auth/**)`, `Read(~/.personal-agent/secrets/**)` |
-| Secret-file writes | `Write(...)` and `Edit(...)` mirrors of every secret-file Read pattern above |
+| Browser-history profile dirs | `Bash(sqlite3 *)`, `Bash(curl file://*)`, `Bash(cp ~/Library/Application Support/Google/Chrome/*)` (Chrome / Chromium / Edge / Brave / Comet / Atlas on macOS, Linux, and `/mnt/c/Users/*` for WSL), plus the matching `Read(...)` patterns — access goes through `/api/browser-history/*` only |
+| Managed-Chromium profile dirs | `Read(~/.personal-agent/chromium-sync/**)`, `chromium-automation{,-anon,-auth,-purchase}/**`, and `Bash(cp …)` / `mv` / `tar` / `zip` / `rsync` of `~/.personal-agent/chromium-*` — protects the daemon-owned OAuth refresh token |
+| Anthropic-cloud managed agents | `CronCreate`, `CronList`, `CronDelete`, `RemoteTrigger`, `PushNotification` — Aitne is local-first; cloud-scheduled agents would bypass the audit log, MD memory, quiet hours, and cost telemetry |
+| Secret-file writes | `Write(...)` and `Edit(...)` mirrors of every Read pattern in the secret-file and profile-dir rows above |
 
 Plain `curl` / `wget` are intentionally **not** in this list — skills
 rely on `curl http://localhost:<port>/api/...` as the daemon-API
-chokepoint for memory writes.
+chokepoint for memory writes (including the browser-history and
+managed-Chromium chokepoints above).
 
 > **Codex allow-mode gap.** Codex CLI has no hook or admin-policy
 > surface for shell commands, so allow mode runs under
 > `--dangerously-bypass-approvals-and-sandbox` and the absolute-block
-> layer can't enforce on Codex there. See
-> `docs/design/09-safety-cost.md` §6.4 for the accepted gap.
+> layer can't enforce on Codex there. Claude, Gemini, and OpenCode
+> enforce it in every mode. See [Safety and Execution](../concepts/safety-and-execution.md)
+> for the accepted gap.
 
 ## Default strict-mode list (relaxable)
 
@@ -69,8 +91,18 @@ Every absolute-block match is logged as
 `agent_actions(action_type='blocked_absolute')` with a redacted form
 of the offending argument and the matched category. The classifier
 that produces the category is `classifyAbsoluteBlock` in
-`src/safety/always-disallowed.ts`.
+`src/safety/always-disallowed.ts`; browser-profile and managed-Chromium
+attempts route through `classifyChromiumTokenAccess` /
+`looksLikeBrowserProfileBash` in the same module.
+
+The `blocked_absolute` row is written on Claude (a PreToolUse `block`
+hook on top of the SDK `disallowedTools` glob list) and on Codex,
+Gemini, and OpenCode (a stream observer that classifies each attempted
+command, recording `result='partial'`). You can review these in
+`aitne audit` (e.g. `aitne audit --type blocked_absolute`) or under
+[Activity](/activity?tab=system) in the dashboard.
 
 ## Related
 
-- [Safety and Execution](../concepts/safety-and-execution.md)
+- [Safety and Execution](../concepts/safety-and-execution.md) — how Safe vs Allow mode interacts with this layer
+- [Safety Model](../concepts/safety-model.md) — the broader risk-classification picture

package/agent-assets/docs/reference/keyboard-shortcuts.md

@@ -3,36 +3,73 @@ schema_version: 1
 slug: reference/keyboard-shortcuts
 title: Keyboard Shortcuts
 id: keyboard-shortcuts
+aliases:
+  - keyboard shortcuts
+  - hotkeys
+  - key bindings
 category: reference
 summary: |
   Keyboard shortcuts available in the dashboard. The set is small by
   design — the dashboard is a low-cognition surface.
-section: keyboard-shortcuts
+section: reference
 tags:
   - reference
   - dashboard
+  - core
 status: stable
 ask_examples:
   - What keyboard shortcuts work in the dashboard?
+  - How do I open the search palette?
+  - What does pressing "?" do in the dashboard?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - shortcut
+  - hotkey
+  - Cmd+K
+  - Ctrl+K
+  - keyboard
+  - cmdk
+  - command palette
+  - help slide-over
+ui_anchors:
+  - /chat
+  - /docs
 related:
   - features/messaging/dashboard-chat
 ---
 
 # Keyboard Shortcuts
 
+The dashboard ships a deliberately small set of shortcuts — it is a
+low-cognition surface, not a power-user IDE. These work from any
+dashboard screen.
+
 | Keys | Action |
 |---|---|
-| `?` | Open the contextual help slide-over. On `/docs`, focuses the inline QA composer. |
-| `Cmd+K` / `Ctrl+K` | Open the search palette (settings + Actions). |
-| `Esc` | Close the slide-over / palette. |
-| `Cmd+Enter` | Send the current QA composer / chat message. |
-
-Shortcuts are skipped when an input or textarea is focused (so typing
-`?` in chat does not open the slide-over). The exception is `Cmd+K`,
-which still opens regardless.
+| `Cmd+K` / `Ctrl+K` | Toggle the search palette — jump to any setting or run an action (e.g. "Ask docs…"). |
+| `?` | Open the contextual help slide-over. On the `/docs` viewer it focuses the inline question composer instead. |
+| `Esc` | Close the open slide-over or palette. |
+| `Cmd+Enter` / `Ctrl+Enter` | Send the message you are typing — works in the chat composer and the docs question composer. |
+
+## When shortcuts are suppressed
+
+Most shortcuts are ignored while a text field (input, textarea, or
+contenteditable) is focused, so typing `?` into a chat message does not
+pop the help slide-over.
+
+**`Cmd+K` / `Ctrl+K` is the exception** — it opens the search palette
+regardless of where focus sits.
+
+## Examples
+
+- Press `Cmd+K`, type "timezone", and hit Enter to jump straight to the
+  Timezone field on `/settings/schedule`.
+- On any screen, press `?` to ask a question about what you are looking
+  at; the help slide-over opens pre-scoped to that page's doc.
+- While drafting a message in `/chat`, press `Cmd+Enter` to send without
+  reaching for the mouse.
 
 ## Related