@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/getting-started/04-first-day.md

@@ -8,11 +8,28 @@ summary: |
   Turn the freshly-installed agent into one that actually helps you —
   teach it about you, connect the tools you use, and describe the work
   you want it to do.
+aliases:
+  - first day
+  - onboarding day 1
+  - day one
+  - day zero
 section: getting-started
 tags:
   - core
   - getting-started
+  - setup
+  - integrations
+  - routines
+  - memory
 status: stable
+keywords:
+  - first day
+  - onboarding
+  - import history
+  - chatgpt import
+  - integrations
+  - profile
+  - teach the agent
 ask_examples:
   - What should I do on my first day?
   - How do I make the agent useful?
@@ -21,8 +38,21 @@ ask_examples:
   - How do I connect an app that isn't on the integrations list?
   - Can I teach the agent a multi-step morning task?
 locale: en-US
+ui_anchors:
+  - /knowledge?tab=upload
+  - /knowledge?tab=context-files
+  - /connections
+  - /connections/mcp
+  - /settings/routines
+  - /activity
+context_files:
+  - identity/profile.md
+  - state/today.md
+  - journal/agent.md
+api_endpoints:
+  - POST /api/knowledge/import
 created: 2026-04-25
-updated: 2026-04-27
+updated: 2026-05-28
 related:
   - getting-started/02-first-steps
   - getting-started/03-what-can-this-do
@@ -70,8 +100,8 @@ and 2.
 ## 1. Teach the agent about you
 
 The agent reads
-[`user/profile.md`](../features/memory-files/user-profile.md) and
-the rest of the `user/*.md` Context Files at the start of every
+[`identity/profile.md`](../features/memory-files/user-profile.md) and
+the rest of the `identity/*.md` Context Files at the start of every
 session. The faster those files have real content, the faster every
 reply gets useful.
 
@@ -87,9 +117,9 @@ Send 3–5 DMs that read like introductions to a new assistant:
 - *"I prefer terse replies in English. Don't summarize what I just
   said back to me."*
 
-The agent appends each fact to the right `user/*.md` file (work
-facts → `user/work.md`, people → `user/people.md`, preferences →
-`user/personal.md`, and so on). Identity-class facts (legal name,
+The agent appends each fact to the right `identity/*.md` file (work
+facts → `identity/work.md`, people → `identity/people.md`, preferences →
+`identity/personal.md`, and so on). Identity-class facts (legal name,
 primary timezone) are deferred for your explicit confirmation
 rather than auto-written.
 
@@ -111,13 +141,13 @@ second upload are skipped automatically.
 
 ### Verify what landed
 
-Open **Knowledge → Context Files** and skim each `user/*.md` file.
+Open **Knowledge → Context Files** and skim each `identity/*.md` file.
 If a bullet is wrong, edit it directly — the agent reads your edit
 on its next turn. The journal entry the import session writes
-(`agent/journal.md`) lists everything that was deferred or flagged
+(`journal/agent.md`) lists everything that was deferred or flagged
 as a conflict.
 
-→ [user/profile.md](../features/memory-files/user-profile.md) ·
+→ [identity/profile.md](../features/memory-files/user-profile.md) ·
 [Memory Model](../concepts/memory-model.md)
 
 ---
@@ -134,7 +164,7 @@ Open **Connections** and connect the ones you live in:
 | Integration | What it gives the agent |
 |---|---|
 | [Mail](../features/integrations/mail.md) | Reads and locally searches your inbox (Gmail, Outlook, Yahoo, iCloud, IMAP). Auto-files reading lists, receipts, travel bookings. |
-| [Calendar](../features/integrations/calendar.md) | Sees today's and upcoming events. Pre-meeting nudges, plus travel-time lookups. |
+| [Calendar](../features/integrations/calendar.md) | Sees today's and upcoming events. Pre-meeting nudges. |
 | [Obsidian](../features/integrations/obsidian.md) | Watches a vault for new notes — references them in the morning plan. |
 | [Notion](../features/integrations/notion.md) | Watches selected pages and databases for changes. |
 | [Git](../features/integrations/git.md) / [GitHub](../features/integrations/github.md) | Watches local repos and tracked GitHub repos. |
@@ -239,14 +269,16 @@ Shortest path from zero to that:
    → Add custom routine**:
    - Slug: `morning-deep-prep`
    - Cron: `0 7 * * 1-5`
-   - Backend tier: `heavy`
-   - Max budget USD: `0.20`
+   - Backend tier: `high (opus)` — this is a heavy, multi-tool job
+   - Max budget (USD): `0.20` (a generous per-execute override; the
+     form default is `0.05`)
    - Description: paste the four numbered steps above verbatim.
 3. **Watch the next firing in Activity** and iterate. The vault file
-   at `~/.personal-agent/context/routines/custom/morning-deep-prep.md`
-   is a plain Markdown file — edit the `## Checks` section directly
-   to refine the wording or change the schedule. The watcher picks
-   up changes without a restart.
+   at `~/.personal-agent/context/policies/routines/custom/morning-deep-prep.md`
+   is a plain Markdown file: edit the `## Checks` body to refine the
+   step wording, or the `cron:` field in the YAML frontmatter to
+   change the schedule. The watcher picks up changes without a
+   restart.
 
 → [Custom Routines](../features/routines/custom-routines.md) ·
 [Add a Custom Routine](../guides/add-a-custom-routine.md)
@@ -257,7 +289,7 @@ Shortest path from zero to that:
 
 By end of day one you should have:
 
-- At least 5–10 facts in `user/*.md` (DM and/or upload).
+- At least 5–10 facts in `identity/*.md` (DM and/or upload).
 - Two or more **Connections** connected and showing recent polls in
   **Activity**.
 - One DM whose answer references something only your connected
@@ -267,11 +299,11 @@ By end of day one you should have:
 
 ## If it fails
 
-- Replies never reference anything specific to you → `user/*.md` is
+- Replies never reference anything specific to you → `identity/*.md` is
   still mostly empty. DM more, or run a Knowledge upload.
 - A connected integration shows no observations after an hour →
   [Observation Not Detected](../troubleshooting/observation-not-detected.md).
-- A blank `today.md` after the morning routine →
+- A blank `state/today.md` after the morning routine →
   [Morning Routine Didn't Run](../troubleshooting/morning-routine-didnt-run.md).
 - A Knowledge upload returns `409 setup_incomplete` → finish the
   setup wizard at `/setup` first.
@@ -284,4 +316,4 @@ By end of day one you should have:
 - [Add a Custom Routine](../guides/add-a-custom-routine.md)
 - [Delegated Mode](../concepts/delegated-mode.md)
 - [Skills and MCP](../concepts/skills.md)
-- [user/profile.md](../features/memory-files/user-profile.md)
+- [identity/profile.md](../features/memory-files/user-profile.md)

package/agent-assets/docs/glossary.md

@@ -3,25 +3,90 @@ schema_version: 1
 slug: glossary
 title: Glossary
 id: glossary
+aliases:
+  - terms
+  - vocabulary
+  - lexicon
 category: glossary
+section: glossary
 summary: |
   Single flat term list for Aitne vocabulary. Cross-references
   link to a single canonical anchor here so concept docs do not drift.
+tags:
+  - core
+  - reference
+  - glossary
 status: stable
 ask_examples:
   - What is a ProcessKey?
   - What does heavy tier mean?
   - What is the difference between light and heavy tiers?
+  - What is OpenCode?
+  - What is a routine pre-pass?
+  - What is the wiki workspace?
+  - What is an integration mode?
+  - What is native mode?
+  - What is B-3 / browser history?
+  - What is B-4 / managed Chromium?
+  - What is a schema migration?
+  - What is execution permission mode?
+  - What is a bang command?
+  - What is deniedTools?
+  - What is an observation?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - terminology
   - vocabulary
   - glossary
+  - backend
+  - processkey
+  - tier
+  - opencode
+  - observation
+  - skill
+  - wiki workspace
+  - integration mode
+  - native mode
+  - delegated mode
+  - browser history
+  - managed chromium
+  - schema migration
+  - execution permission mode
+  - research cluster
+  - bang command
+  - deniedTools
+  - safety model
 related:
   - concepts/agent-day
+  - concepts/backends-and-tiers
+  - concepts/process-keys
+  - concepts/observations
+  - concepts/delegated-mode
+  - concepts/safety-and-execution
+  - concepts/safety-model
   - features/routines/morning-routine
+  - features/wiki/overview
+  - features/integrations/browser-history
+  - features/messaging/bang-commands
+ui_anchors:
+  - /settings/models
+  - /docs
+  - /settings/integrations/browser-history-managed/b4
+process_keys:
+  - dashboard.docs_qa
+  - delegated_task_heavy
+  - routine.fetch_window
+  - routine.hourly_check
+  - routine.research_cluster_update
+config_keys:
+  - dayBoundaryHour
+  - browserTaskHostnameDenylist
+  - delegatedTaskHeavyEnabled
+  - claudeExecutionPermissionMode
+api_endpoints:
+  - POST /api/observations
 ---
 
 # Glossary
@@ -38,9 +103,46 @@ and rationale.
 ## Backend
 
 One of the model providers Aitne can dispatch to: `claude`
-(Claude Code SDK), `codex` (Codex CLI), or `gemini` (Gemini CLI). Each
-backend is configured per-installation; one is the **main backend**, and
-the others can be enabled as fallbacks.
+(Claude Code SDK), `codex` (Codex CLI), `gemini` (Gemini CLI), or
+`opencode` (`@opencode-ai/sdk` HTTP server). Each backend is configured
+per-installation; one is the **main backend**, and the others can be
+enabled as fallbacks.
+
+## Browser History (B-3)
+
+Local-only history poller that reads the browser's own SQLite database
+(Chrome / Safari / Firefox / Arc) and records page visits as
+observations. Drives the **research cluster** derivation, the weekly
+reload-memory block, and the [`!checks`](features/messaging/bang-commands.md)
+on-demand reload tally. No content is uploaded; only URLs, titles, and
+visit timings the browser itself recorded. See
+[Browser History](features/integrations/browser-history.md).
+
+## Managed Chromium (B-4)
+
+Experimental purchase-confirmation flow that drives a daemon-spawned
+Chromium profile to complete a vendor checkout the agent has already
+prepared. **Default-off.** Requires per-site opt-in, the experimental-
+danger acknowledgement modal, at least one DM channel, a single-use
+`!~xxxxxxxx` token, screenshot-first consent, and a 5-min timeout. There
+is no longer a hardcoded domain category denylist (banks, government,
+payment processors, etc. were removed at the framework level on
+2026-05-27); domain-level deny is operator-managed via **Settings →
+Integrations → Browser History (Managed) → B-4** (`browserTaskHostnameDenylist`,
+default empty). The structural defences that remain: the IP CIDR layer
+in `shouldDenyEgress` (RFC1918 / loopback / cloud-metadata), the
+form-submit `payment-path-blocker`, and the single-use token primitive.
+Operator self-testing only until B-3 has been stable for six weeks. See
+[Managed Chromium](features/operations/managed-chromium.md).
+
+## Bang Command
+
+Short, owner-only command typed in a paired DM that starts with `!`
+(e.g. `!help`, `!stop`, `!cost`, `!report`, `!checks`, `!research`,
+`!ingest`, `!compile`, `!ask`). Handled by the daemon directly — no
+LLM call, no cost, no session opened. Built-in commands plus operator-
+enabled custom commands appear in `!help`. See
+[Bang Commands](features/messaging/bang-commands.md).
 
 ## Backend Router
 
@@ -61,19 +163,111 @@ matching anchor.
 The hour-of-day at which the agent day rolls over. Configured via
 `dayBoundaryHour` (default `4`).
 
+## deniedTools
+
+Per-integration deny list of tool names (or prefix globs like
+`send_*`) the agent must not call. The primary defense against
+unwanted destructive actions in the [Safety Model](concepts/safety-model.md).
+Editable in **Connections → \<integration\> → Tool Permissions**;
+seeded with a recommended starter list on first delegated setup.
+Patterns are validated against the connector's `capabilityTools` set
+at PATCH time so typos fail fast.
+
+## Execution Permission Mode
+
+Per-backend `Safe` / `Allow` posture, set independently for each
+registered backend via
+`{claude,codex,gemini,opencode}ExecutionPermissionMode`. **Safe** =
+strict per-call permission checks plus the Claude curl/jq hooks,
+Codex `workspace-write` sandbox, and Gemini whitelist TOML. **Allow** =
+SDK bypass / sandbox off / minimal TOML. The absolute-block layer
+(recursive delete, sudo, secret-file reads/writes) is enforced in
+*both* modes — `allowedToolsOverride` cannot widen past it. Codex
+allow mode cannot enforce the absolute-block layer for shell commands
+(no hook surface); the gap is documented in
+`docs/design/09-safety-cost.md`. See
+[Safety and Execution](concepts/safety-and-execution.md).
+
+## Integration Mode
+
+The per-integration posture for how Aitne ingests events from a
+connected service: `direct | delegated | native | disabled`.
+
+- **direct** — the daemon runs its own poller against the integration's
+  API.
+- **delegated** — a lite-tier `delegated-sync-worker` polls on opt-in
+  cadences (see `docs/design/appendices/delegated-sync-opt-in.md`).
+- **native** — no poller; the main backend reaches the integration
+  through its own MCP connector and POSTs observations in-turn via
+  `/api/observations`. Two variants: **descriptor-driven** (the
+  integration ships a `backendConnectors` entry — `gmail`,
+  `google_calendar`, `notion`) and **user-managed** (the descriptor
+  declares `userManagedConnector: true` and the user installs their own
+  MCP / skill harness — `outlook_mail`, `outlook_calendar`).
+- **disabled** — silence; no poller, no native handoff.
+
+Mode lookup goes through `getIntegrationState(db, key)`; never
+hardcode an integration reference outside
+`packages/shared/src/integrations.ts`. See
+[Delegated Mode](concepts/delegated-mode.md).
+
 ## Heavy Tier
 
-The expensive, high-quality model lane on each backend (Claude Opus
-4.7, GPT-5.5, Gemini 3 Pro). Reserved by default for processes whose
-output quality directly drives the agent's daily decision-making —
-primarily `routine.morning_routine` and the one-shot
-`routine.morning_routine_initial` plus `setup`.
+Synonym for the **high** tier — the expensive, high-quality model lane
+on each backend (Claude Opus 4.8 / `claude-opus-4-8`, `gpt-5.5` on
+Codex, `gemini-3.1-pro-preview` on Gemini, Opus 4.8 via OpenCode).
+Registered but not auto-selected on any install-seeded surface: after
+the "no Opus by default" pass (2026-05-16) the **only** process key that
+defaults to high tier is `delegated_task_heavy` (opt-in, gated by the
+`delegatedTaskHeavyEnabled` flag). Every other process key — including
+`setup` and `knowledge.import` — defaults to medium. Operators can pin
+any other process key to high per row from the `/settings/models`
+dashboard page.
 
 ## Light Tier
 
-The cheaper, fast model lane on each backend (Claude Sonnet 4.6,
-GPT-5.4-mini, Gemini 3 Flash). Default for owner DMs, dashboard chat,
-the hourly check, and the evening / weekly / monthly review routines.
+Operator-facing umbrella for the two non-heavy lanes on each backend:
+
+- **Medium / Main** (Claude Sonnet 4.6, `gpt-5.4` on Codex,
+  `gemini-3.1-pro-preview` on Gemini, Sonnet 4.6 via OpenCode) —
+  default for owner DMs, dashboard chat, the hourly check, and the
+  morning / evening / weekly review routines.
+- **Lite / Delegated** (Claude Haiku 4.5, `gpt-5.4-mini` on Codex,
+  `gemini-3.1-flash-lite-preview` on Gemini, Haiku 4.5 via OpenCode) —
+  reserved for mechanical / delegated surfaces: Gmail classification,
+  GitHub triage, calendar-change handlers, the routine pre-pass
+  fetcher, the `delegated_task` invoker.
+
+## OpenCode
+
+The 4th backend (joined 2026-05). Implemented on top of
+`@opencode-ai/sdk`'s HTTP server. Operates in **Managed** mode (the
+daemon spawns a local loopback server) or **Remote** mode (operator
+points at an existing baseUrl). OpenCode dispatches the same
+ProcessKey set as Claude / Codex / Gemini but does not host
+native-mode integration connectors. Cost telemetry reads
+`session.info.cost` + `info.tokens` with a `MODEL_REGISTRY` pricing
+fallback when upstream reports zero.
+
+## Routine Pre-pass
+
+A lite-tier `routine.fetch_window` session spawned before each main
+routine (morning / today_refresh / hourly_check / evening / weekly).
+It fetches each routine's mail / calendar / Notion window
+(`ROUTINE_WINDOWS`) and POSTs the results to `/api/observations`. The
+main routine then consumes the resulting `<fetch_report>` block and
+pending observations instead of calling upstream APIs itself. Introduced
+in 2026-05 to trim morning-routine input tokens by ~24%.
+
+## Observation
+
+One row in the `observations` table. A change record a polling
+integration (Obsidian, Git, Notion, calendar, mail, browser history)
+or a `routine.fetch_window` pre-pass wrote into SQLite. The
+`routine.hourly_check` is the consumer — there is no per-change
+notification. `actor='agent'` rows are filtered out by the consumer
+to break the agent-observing-its-own-writes loop. See
+[Observations](concepts/observations.md).
 
 ## ProcessKey
 
@@ -82,12 +276,40 @@ The branded string identifier for a class of agent invocation, e.g.
 backend selection, skill manifest, agent profile, and task-flow
 template lookup. Defined in `packages/shared/src/process-key.ts`.
 
+## Research Cluster
+
+A topic the browser-history poller derives from a user's reading
+pattern when meaningful visits, foreground time, and distinct domains
+cross a threshold. Each cluster has a slug, a display name, a journal
+file at `context/research/<slug>.md`, and a status
+(`active | dormant | muted | concluded`). Surfaced via the
+**Two-Option Offer DM** (research dive vs. wiki summary) and the
+[`!research`](features/messaging/bang-commands.md) bang prefix.
+
+## Schema Migration
+
+Forward-only, append-only, idempotent migration entry in
+`packages/daemon/src/db/migrations.ts:MIGRATIONS`. Runs right after
+`applySchema(db)` at boot; applied ids are recorded in
+`schema_migrations` so each runs at most once per DB. Used for any
+non-additive change to a pre-existing structure — `ALTER TABLE ADD
+COLUMN`, `CREATE INDEX` on a column added by a prior migration, data
+backfill, or a `settings_json` shape change whose old value won't parse
+under the new schema. Gating ALTERs behind `columnExists` /
+`tableExists` / `indexExists` keeps a fresh DB (where `applySchema`
+already produced the target state) a no-op. The legacy reinstall
+escape hatch still exists as a last resort, but **migrations are the
+upgrade path** — see [Reinstall Cleanly](guides/reinstall-cleanly.md).
+
 ## QA Panel
 
 The right-side pane on `/docs` and the bottom of the `?`-button
 slide-over that runs grounded question answering over the docs corpus.
-Runs on the operator's DM-bound backend at the **light tier** —
-inherited from `message.dm`'s binding via the cascade-write helper.
+Dispatched under the `dashboard.docs_qa` ProcessKey, which is **hard
+tier-locked to medium** (`TIER_LOCKED_PROCESS_KEYS` in
+`packages/shared/src/process-key.ts`) — an operator pin to a different
+tier is ignored. The backend itself is inherited from the operator's
+DM-bound backend via the cascade-write helper.
 
 ## Skill
 
@@ -104,26 +326,68 @@ the row key in `fts_docs`, and the first half of every
 
 ## Tier
 
-Short for **model tier**: `light` or `heavy`. Each ProcessKey has a
-default tier; per-process pins and per-call requested-tier overrides can
-deviate from that default.
+Short for **model tier**. The code-level enum (`ProcessModelTier` in
+`packages/shared/src/process-key.ts`) has three values — `lite`,
+`medium`, `high`. This doc also uses the operator-facing two-way split
+**light** (lite + medium) vs **heavy** (high); see [Light Tier](#light-tier)
+and [Heavy Tier](#heavy-tier). Each ProcessKey has a default tier;
+per-process pins and per-call requested-tier overrides can deviate from
+that default, except for keys in `TIER_LOCKED_PROCESS_KEYS` (today only
+`dashboard.docs_qa`, locked to medium).
+
+## Two-Option Offer DM
+
+DM pattern used for research-cluster offers and any other follow-up
+where the user has two natural choices. Sends one DM with two distinct
+actions (e.g. "research dive" vs. "wiki summary") instead of a single
+yes/no prompt; the user replies with the matching `!research` subcommand
+to accept either path. Replaces the older single-option offer for
+ambiguous-intent surfaces.
 
 ## Today.md
 
 The current agent day's main memory file under
-`~/.personal-agent/context/today.md`. Rebuilt once per day by the
+`~/.personal-agent/context/state/today.md`. Rebuilt once per day by the
 morning routine and edited by every DM, observation, and routine that
 needs to record state for the day.
 
 ## Wiki Workspace
 
 A single named root the wiki feature writes into. Either **internal**
-(`~/.personal-agent/wiki/`) or **external** (a path you point at, often
-an existing Obsidian vault). Every wiki bang command targets a
-workspace; omitting the `@<workspace>` token addresses the default.
+(`~/.personal-agent/context/knowledge/wiki/` after the context-vault v2 restructure;
+pre-v2 installs lived at `~/.personal-agent/wiki/`) or **external**
+(a path you point at, often an existing Obsidian vault). Every wiki bang
+command targets a workspace; omitting the `@<workspace>` token addresses the default.
 See [Wiki Overview](features/wiki/overview.md) and
 [Multiple Wikis](guides/multiple-wikis-for-multiple-domains.md).
 
+## Authority Class
+
+One of the six top-level partitions of the vault — `identity/`, `state/`,
+`plans/`, `journal/`, `knowledge/`, `policies/`. Each class carries a
+distinct authority + lifecycle contract; the daemon enforces by reading
+file frontmatter (Phase 1 advisory; Phase 2 strict). Established by the
+context-vault v2 restructure (CONTEXT_VAULT_REDESIGN_PLAN.md). See
+[Knowledge Layout](reference/knowledge-layout.md) for what lives in each.
+
+## Context Vault v2
+
+The vault layout introduced by the context-vault v2 restructure
+(migration id `0004-context-vault-restructure`) — six authority classes,
+in-process legacy path alias, `wiki/` and `integrations.md` and user
+`skills/` consolidated under the vault root. Migrates forward-only on
+first boot of the cutover release; never destroys user data. See
+[Knowledge Layout](reference/knowledge-layout.md).
+
+## Frontmatter Contract
+
+YAML preamble in each vault MD file declaring `kind` (one of the six
+class names), `authority` (`user` / `agent` / `mixed`), `mutability`
+(`replace` / `patch` / `append` / `readonly`), `slug`, and `title`.
+Parsed by `core/context-validation/frontmatter.ts`. Phase 1 logs
+warnings on missing/invalid frontmatter; Phase 2 rejects the write.
+Toggle: `runtimeSettings.contextVault.enforceFrontmatter` (default `false`).
+
 ## Wiki Layers
 
 The four directories every workspace contains:

package/agent-assets/docs/guides/add-a-custom-routine.md

@@ -3,25 +3,49 @@ schema_version: 1
 slug: guides/add-a-custom-routine
 title: Add a Custom Routine
 id: add-a-custom-routine
+aliases:
+  - custom routine
+  - user-defined routine
+  - add a routine
+  - scheduled task
 category: guides
 summary: |
-  Define a new autonomous routine — slug, cron expression, tier, and
+  Define a new autonomous routine — slug, cron expression, model tier, and
   budget cap — via /settings/routines. The form writes a vault file at
-  routines/custom/<slug>.md.
+  policies/routines/custom/<slug>.md; saving it registers the cron job.
 section: add-a-custom-routine
 tags:
-  - guide
+  - guides
   - routines
+  - scheduler
+  - autonomous
+  - core
 status: stable
 ask_examples:
   - How do I add a custom routine?
   - What can a custom routine do?
+  - How do I schedule the agent to run on a cron?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - custom routine
+  - schedule
+  - cron
+  - recurrence
+  - backend_tier
+  - process_key
+ui_anchors:
+  - /settings/routines
+api_endpoints:
+  - PUT /api/context/*
+context_files:
+  - policies/routines/custom/<slug>.md
 related:
   - features/routines/custom-routines
   - concepts/routines
+  - concepts/process-keys
+  - concepts/backends-and-tiers
 ---
 
 # Add a Custom Routine
@@ -38,22 +62,48 @@ Make the agent fire a particular kind of work on a schedule you pick.
 
 1. Open `/settings/routines` (the older `/connections/routines` URL
    redirects here).
-2. Click "Add custom routine".
+2. Click **Add**. The "New custom routine" dialog opens.
 3. Fill the form:
-   - **Slug** — kebab-case (e.g. `tuesday-notion-sweep`); becomes the
-     ProcessKey `routine.custom.<slug>` and the file name
-     `routines/custom/<slug>.md`.
-   - **Cron expression** — standard 5-field cron (e.g. `0 11 * * 2`).
-     The form previews the next three fires.
-   - **Backend tier** — `light` or `heavy`. Custom routines have no
-     concrete model picker; tier determines which model the
-     BackendRouter resolves at fire time.
-   - **Max budget USD** — per-execute cap (default `0.05`).
-   - **Description** — free-text. Becomes the body of the generated
-     vault file under `## Checks`. Edit the file later to refine the
-     check list.
-4. Save. The dashboard writes the vault file; the next-fire timestamp
-   appears in the routine table.
+   - **Slug** — lowercase kebab-case, 1–64 chars, no leading/trailing
+     hyphen (e.g. `tuesday-notion-sweep`). It becomes the ProcessKey
+     `routine.custom.<slug>` and the file name
+     `policies/routines/custom/<slug>.md`.
+   - **Cron expression** — standard 5-field cron in the daemon's
+     timezone (e.g. `0 11 * * 2` for 11:00 every Tuesday). The dialog
+     previews the next three fire times.
+   - **Backend tier** — `lite` (Haiku), `medium` (Sonnet), or `high`
+     (Opus). Default is `medium`. Custom routines have no concrete
+     model picker; the tier is written to the file's `backend_tier`
+     frontmatter, and the BackendRouter resolves the actual model at
+     fire time. (See [Backends and tiers](../concepts/backends-and-tiers.md).)
+   - **Max budget (USD)** — per-execute cap (default `0.05`; must be a
+     positive number).
+   - **Description** — optional free text. It becomes the body of the
+     generated vault file, above an empty `## Checks` section seeded
+     with a `### First check` placeholder. Edit the file later on the
+     same page to flesh out the check list.
+4. Click **Create**. The dashboard writes the vault file via the
+   context API (`PUT /api/context/policies/routines/custom/<slug>`).
+   Because the file ships with `enabled: true` and a `cron:` field,
+   saving it registers (or refreshes) the cron job, and the next-fire
+   timestamp appears in the routine list.
+
+The generated file looks roughly like this:
+
+```yaml
+---
+type: rule
+slug: tuesday-notion-sweep
+cron: "0 11 * * 2"
+process_key: routine.custom.tuesday-notion-sweep
+enabled: true
+backend_tier: medium
+max_budget_usd: 0.05
+---
+```
+
+To stop a routine without deleting it, set `enabled: false` in the
+file and save — that unregisters the cron job.
 
 ## Verification
 
@@ -62,9 +112,11 @@ Make the agent fire a particular kind of work on a schedule you pick.
 
 ## If It Fails
 
-- A cron that resolves to "never": the dashboard refuses to save it.
-- A prompt that hits absolute-block guardrails: the routine fires
-  but the offending tool call is logged as `blocked_absolute`.
+- A cron that resolves to "never" (or is otherwise invalid): the
+  dialog shows the preview error and refuses to save it.
+- A prompt that hits the absolute-block guardrails: the routine fires
+  but the offending tool call is logged as `blocked_absolute` in the
+  action log.
 
 ## Related