@aitne-sh/aitne 0.1.3 → 0.1.4

package/agent-assets/docs/features/lifestyle/git.md

@@ -10,12 +10,17 @@ aliases:
   - daily git management
   - git triggers
   - repo polling cadence
+  - refresh architecture
+  - architecture refresh
+  - repository overview
+  - repository readme mirror
 category: features
 summary: |
   The /git page (sidebar: My Life › Git) is the per-repository control
   surface: override polling cadence, define event-driven triggers, and
-  enable daily git management (overview MD + per-day journal entry) for
-  each registered repository.
+  enable daily git management — a deep AI-generated architecture
+  analysis (refreshable on demand), a per-day journal of activity, a
+  mirrored copy of the source README, and a curated overview document.
 section: lifestyle
 tags:
   - lifestyle
@@ -23,6 +28,7 @@ tags:
   - github
   - automation
   - observation
+  - architecture
 status: stable
 ask_examples:
   - What is the My Life › Git page for?
@@ -30,11 +36,17 @@ ask_examples:
   - Does daily git management need a local clone?
   - Can the agent poll a GitHub repo with no local checkout?
   - What's the difference between Polling, Triggers, and Daily git management?
+  - What does the Refresh architecture button do?
+  - When does the agent regenerate the Architecture section?
+  - Does the agent read my README on every scan?
+  - Where does the README mirror get written?
   - Where does the daily journal get written?
   - What happens if a scan fails repeatedly?
+  - Can I run Architecture refresh on a schedule?
+  - How much does one Architecture refresh cost?
 locale: en-US
 created: 2026-05-05
-updated: 2026-05-05
+updated: 2026-05-07
 keywords:
   - my life
   - git
@@ -44,10 +56,14 @@ keywords:
   - daily git management
   - overview
   - journal
+  - architecture
+  - readme mirror
+  - refresh architecture
 related:
   - features/integrations/git
   - features/integrations/github
   - features/routines/hourly-check
+  - guides/refresh-repository-architecture
   - concepts/observations
 ui_anchors:
   - /git
@@ -62,14 +78,17 @@ config_keys:
 
 A per-repository control panel for everything Git/GitHub: tighten the
 polling cadence on a single repo, attach event-driven triggers, and
-opt in to **daily git management** (a curated overview MD plus a
-once-a-day journal entry).
+opt in to **daily git management** — a curated `overview.md` whose
+**Architecture section is generated by an AI agent that reads the
+whole repository**, plus a per-day activity journal and a verbatim
+mirror of the source README.
 
 ## What It Does
 
 The page lists every repository registered on
 **Connections → Repositories** and exposes three collapsible sections
-per repo:
+per repo (now **all open by default** so the controls are visible at
+a glance):
 
 1. **Polling** — overrides the global `gitPollIntervalSeconds` for
    this repository alone. Useful when one repo is high-traffic and
@@ -81,14 +100,87 @@ per repo:
    task-flow defaults, not in place of them. Each trigger has a
    workdir mode (`local-clone` or `ephemeral`); local-clone triggers
    require the repository to have a `localPath`.
-3. **Daily git management** — opt-in per repo. When enabled, the
-   `repository-management-cron` observer fires `git.project.update`
-   roughly once every 24 hours. The session writes/refreshes a
-   curated `git/<slug>/overview.md` and appends a per-day entry under
-   `git/<slug>/journal/YYYY-MM-DD.md` if there was activity.
+3. **Daily git management** — opt-in per repo. Enabling it does three
+   distinct kinds of work, on different cadences:
+   - On the first **Run init now** click, writes the curated
+     `git/<slug>/overview.md` skeleton, mirrors the source `README.*`
+     to `git/<slug>/README.md`, and **automatically queues a
+     one-shot Architecture refresh** so the AI agent fills in the
+     deep Architecture section for you.
+   - Once a day, the `repository-management-cron` observer iterates
+     enabled rows and writes `git/<slug>/journal/YYYY-MM-DD.md` if
+     there was activity, plus a one-line entry under
+     `## Daily Activity Log` in `overview.md`.
+   - **Refresh architecture** (the button) re-runs the Architecture
+     analysis on demand. Use it when the codebase has moved enough
+     that the existing Architecture section is stale (a major refactor,
+     a new package, a switched framework). There is no automatic
+     schedule for this — it runs only when you click.
 
 The agent never pushes, amends, or force-resets. Read-only by design.
 
+## Architecture Section — Deep AI Analysis
+
+The `## Architecture` block of `git/<slug>/overview.md` is wrapped in
+`<!-- architecture:start -->` / `<!-- architecture:end -->` markers
+and contains a **module map, runtime shape, data flow, persistence
+model, integrations, build pipeline, and design choices** produced by
+a Sonnet-class agent that reads the actual code.
+
+**When it's generated**
+
+- **First time** — automatically queued the moment you click
+  **Run init now**. Returns immediately with `architectureScheduleId`;
+  the agent runs in the background (typically 30 s – 2 min) and
+  replaces the placeholder block with real analysis.
+- **On demand** — click **Refresh architecture** any time. The daemon
+  re-copies the source README into the slug directory before queueing
+  the agent run, so the mirror stays in sync with what the agent
+  actually reads.
+- **Never automatically** — there is no weekly/monthly cron that
+  refreshes Architecture. This is by design: each refresh costs one
+  Sonnet session, and the analysis is durable across daily journal
+  appends. If you want a recurring refresh, click the button on
+  whatever cadence makes sense for the repo (after a big refactor,
+  before a release, etc.).
+
+**Idempotency**
+
+If you click **Refresh architecture** while a previous refresh is
+still pending or running, the API returns 409 with the existing
+schedule id rather than spawning a parallel session — you cannot burn
+quota by double-clicking.
+
+**Surgical writes**
+
+The agent never rewrites the whole `overview.md`. It submits only the
+new Architecture body via the chokepoint
+`PUT /api/repositories/:id/architecture-section`; the daemon performs
+the marker-bracketed replacement so other sections (Notable Changes,
+Daily Activity Log, Open Threads) are preserved verbatim. Every write
+also snapshots the previous Architecture body to `md_file_snapshots`
+for recovery.
+
+## README Mirror
+
+`git/<slug>/README.md` is a **mechanical verbatim copy** of the
+repository's `README.*` (whichever extension exists, with `.md`
+preferred). It is refreshed on:
+
+- Every **Run init now** (initial mirror).
+- Every **Refresh architecture** click (so the mirror tracks what the
+  agent just analyzed).
+
+It is **not** refreshed on the daily scan — the file rarely changes
+and a daily mirror would just churn `md_file_snapshots`. If you want
+a fresh mirror without re-running architecture analysis, you can
+re-run init.
+
+The mirror's purpose is to give the dashboard's `/knowledge` viewer
+and any retrospective tooling a stable copy of the README *as it
+existed at the time of the last refresh*, even after the upstream
+README is rewritten.
+
 ## When It Runs / How It Is Triggered
 
 - **Polling** runs continuously on the per-repo cadence (or the global
@@ -99,25 +191,60 @@ The agent never pushes, amends, or force-resets. Read-only by design.
   which iterates the `repository_management` table once an hour and
   emits a `scheduled.task` (`git.project.update`) for any enabled row
   whose `last_scan_at` is more than 24 hours old.
+- **Architecture refresh** (`git.project.refresh_architecture`) is
+  enqueued only on:
+  - Manual **Run init now** (auto-enqueue, first time only).
+  - Manual **Refresh architecture** click.
+  
+  No cron, no observer fires this. The cron-driven implicit init
+  (when daily scan creates a missing skeleton) deliberately does NOT
+  auto-enqueue.
 
 ## What It Outputs
 
-- **Polling** → `observation` rows (one per detected change set) +
-  trigger fires when a trigger's match conditions are satisfied.
-- **Triggers** → an autonomous session whose task-flow is selected
-  by the trigger's process key.
-- **Daily git management** → `git/<slug>/overview.md` (refreshed each
-  scan) and `git/<slug>/journal/YYYY-MM-DD.md` (appended for the day,
-  only when activity warrants it).
+Per repository, under `<contextDir>/git/<slug>/`:
+
+| File | Source | Refresh cadence |
+|---|---|---|
+| `overview.md` | Daemon (skeleton + Notable Changes + journal log) + Agent (Architecture section) | Skeleton on init; Architecture on init/refresh; daily entry appended on each scan |
+| `README.md` | Verbatim copy of `<repo>/README.*` | Every init + every architecture refresh |
+| `journal/YYYY-MM-DD.md` | Daemon (commits + PR/workflow observations + diff stat) | Once per day per repo, when activity exists |
+
+Polling additionally produces `observation` rows in the database;
+triggers spawn autonomous sessions whose task-flow is selected by the
+trigger's process key.
 
 ## Where in the Dashboard
 
-- **My Life → Git** (`/git`) — this page.
+- **My Life → Git** (`/git`) — this page. Polling, Triggers, and Daily
+  git management are now all expanded by default.
 - **Connections → Repositories** (`/connections/repositories`) —
-  register a repo (link a `localPath` and/or `owner/repo`),
-  rename, set `local-only`, delete.
+  register a repo (link a `localPath` and/or `owner/repo`), rename,
+  set `local-only`, delete. The model-binding cards visible on this
+  page now cover only the **`git.project.init`**, **`git.project.update`**,
+  and **`git.project.retemplate`** processes — the per-event
+  GitHub cards (`github.assigned`, `github.security_alert`,
+  `github.pull_request.review_requested`, `github.workflow_run.failed`)
+  were folded back into the default routing. To pin a different model
+  for any of those, use **Settings → Models** instead.
 - **Knowledge** (`/knowledge?path=git/<slug>/overview`) — quick links
-  on each repo card open the generated overview / today's journal.
+  on each Daily-git-management panel open the generated overview, the
+  current day's journal, and (after the architecture refresh
+  completes) the AI-rich Architecture section in context.
+
+## UI polish (2026-05-07)
+
+- The Daily git management toggle is now a styled switch instead of a
+  raw checkbox — same behavior, more legible state.
+- Init / Refresh architecture / Run today's scan now buttons surface
+  inline confirmation messages (green) on success and inline error
+  messages (red) on failure, instead of the previous silent return.
+- The button order on the panel is **Run init now → Refresh
+  architecture → Run today's scan now**, matching the lifecycle order
+  (one-time skeleton → one-time deep analysis → daily increments).
+- The Polling, Triggers, and Daily git management collapsibles all
+  open by default so a freshly-loaded `/git` page exposes every
+  per-repo control without an extra click.
 
 ## Configuration
 
@@ -127,6 +254,7 @@ The agent never pushes, amends, or force-resets. Read-only by design.
 | Per-repo polling override | `/git` → Polling | Stored on the repository row; null means "use global". |
 | Triggers | `/git` → Triggers | Per-repo, multiple. Each has match conditions, workdir mode, process key. |
 | Daily git management toggle | `/git` → Daily git management | Stored in `repository_management` table. Requires `localPath`. |
+| Architecture refresh model | `/settings/models` (process key `git.project.refresh_architecture`) | Defaults to Sonnet. Pin to a different model per backend if you want Opus-grade analysis instead. |
 
 ## Local Clone Requirement
 
@@ -148,6 +276,10 @@ repository has a `localPath`:
   `listManagementDueForScan` query filters on `r.local_path IS NOT
   NULL`, so even a stale `enabled = 1` row will not fire without a
   local path.
+- **Architecture refresh** also requires a `localPath` — the agent
+  reads source files directly from disk. The button is disabled with
+  the same "No local clone" message until you link one on
+  **Connections → Repositories**.
 
 ## When Something Goes Wrong
 
@@ -166,9 +298,24 @@ repository has a `localPath`:
   (check `Last scan`-style timestamps), and remember the agent's own
   writes are filtered out (see `AgentWriteTracker`) — make sure the
   commit was authored by you.
+- **Architecture section still shows the placeholder text** (`_Architecture
+  analysis pending..._`) several minutes after init. Open
+  **Activity**, filter for `git.project.refresh_architecture`, and
+  inspect the latest run. Common causes: the agent crashed before
+  calling the chokepoint, or the backend session is still running on
+  a slow network. Click **Refresh architecture** to retry.
+- **"Refresh architecture" returns 409 `already_in_flight`.** A
+  previous refresh is still pending or running for this repo. Wait
+  for it to complete (Activity → `git.project.refresh_architecture`)
+  before clicking again.
+- **The README mirror went out of date** after the source repo's
+  README was rewritten. Click **Refresh architecture** (which also
+  re-copies the README) or **Run init now** on the repo.
 
 ## Related
 
+- [Refresh repository architecture](../../guides/refresh-repository-architecture.md)
+  — focused walkthrough of the Refresh architecture button.
 - [Git integration](../integrations/git.md) — the underlying observer
   contract and `gitPollIntervalSeconds` semantics.
 - [GitHub integration](../integrations/github.md) — remote-side data

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

@@ -25,7 +25,7 @@ ask_examples:
   - Why didn't I get a notification?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 keywords:
   - messaging
   - dm
@@ -34,6 +34,8 @@ keywords:
   - slack
   - discord
   - whatsapp
+  - voice
+  - audio
 related:
   - features/messaging/pairing-and-magic-phrase
   - features/messaging/telegram
@@ -41,6 +43,7 @@ related:
   - features/messaging/discord
   - features/messaging/whatsapp
   - features/messaging/dashboard-chat
+  - features/messaging/voice-attachments
   - features/operations/notifications
   - features/operations/quiet-hours
 ui_anchors:
@@ -65,6 +68,10 @@ notification fires.
   the same way (group chat is filtered out by design — DMs only).
 - **Outbound notifications**: routines and observations fire alerts
   back through the same channel.
+- **Voice attachments**: when the platform attaches audio (Telegram
+  voice notes, WhatsApp voice messages, etc.), the daemon transcribes
+  it locally with Whisper before handing the turn to the agent. See
+  [Voice Attachments](voice-attachments.md).
 - **Magic-phrase pairing**: the operator types a one-time phrase to
   bind their account to the agent (anti-impersonation).
 
@@ -107,5 +114,7 @@ adapter and the dispatcher both check).
 ## Related
 
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Voice Attachments](voice-attachments.md) — local Whisper
+  transcription for inbound audio.
 - [Dashboard Chat](dashboard-chat.md) — the in-browser equivalent.
 - [Notifications](../operations/notifications.md)

package/agent-assets/docs/features/routines/morning-routine.md

@@ -115,7 +115,7 @@ during the setup wizard's first day. After the first run, only
 
 - The most common failure is **morning routine did not run** because the daemon was offline at the trigger window. The next launch picks the run up via the catch-up scheduler if it is still the same agent day.
 - A failed morning routine emits a fallback-success notification when the secondary backend caught the run, or a fallback-failed notification (high priority) when both failed.
-- Heavy-tier quota exhaustion (Claude Max5/Max20 5-hour Opus window) is the second most common cause. Switch the routine's model to a different heavy-tier option in Settings → Models or wait out the window.
+- Heavy-tier quota exhaustion is the second most common cause: a provider rate limit on your `ANTHROPIC_API_KEY`, or — when running on the subscription fallback — the rolling Opus window of the underlying Claude plan. Switch the routine's model to a different heavy-tier option in Settings → Models or wait for the provider window to refresh.
 
 ## Related
 

package/agent-assets/docs/getting-started/01-what-is-this.md

@@ -6,8 +6,9 @@ id: what-is-this
 category: getting-started
 summary: |
   Aitne is a local-first proactive personal AI agent. It runs
-  as a daemon on your own machine, uses your Claude / Codex / Gemini
-  subscription, and stores all memory as plain Markdown files.
+  as a daemon on your own machine, calls Claude / Codex / Gemini via
+  API keys you register (with the local CLI's subscription auth as a
+  fallback), and stores all memory as plain Markdown files.
 section: getting-started
 tags:
   - core
@@ -32,9 +33,10 @@ related:
 # What is Aitne?
 
 Aitne is a local-first personal AI agent. It runs as a long-running
-daemon on your own machine, uses an LLM subscription you already own
-(Claude, Codex, or Gemini), and keeps all of its memory as plain
-Markdown files under `~/.personal-agent/`.
+daemon on your own machine, drives Claude Code, Codex CLI, or Gemini
+CLI via provider API keys you register (with the CLI's local
+subscription login as a fallback), and keeps all of its memory as
+plain Markdown files under `~/.personal-agent/`.
 
 Unlike a chat assistant that only responds when you type, Aitne also
 runs on its own — on a schedule, in reaction to changes it sees in
@@ -128,16 +130,30 @@ an opaque vector store.
 
 → [Memory Model](../concepts/memory-model.md)
 
-### Use the LLM subscription you already have
+### Drive Claude Code / Codex / Gemini via API keys
+
+Aitne drives Claude Code, Codex CLI, and Gemini CLI on your behalf.
+The recommended setup is to register a provider API key for each
+backend you want to use — this matches what Anthropic, OpenAI, and
+Google document for headless / programmatic agent use, and gives you
+predictable per-call billing that is unambiguously permitted.
+
+- Claude — `ANTHROPIC_API_KEY` (via Claude Code)
+- Codex — `OPENAI_API_KEY` (via Codex CLI)
+- Gemini — `GEMINI_API_KEY` / `GOOGLE_API_KEY` (via Gemini CLI)
+
+If you skip the API key, Aitne falls back to whatever local
+subscription login the CLI already has on your machine (`claude`,
+`codex login`, `gemini auth`). This fallback works mechanically, but
+most providers do not officially support running automated agents on
+a personal subscription — Anthropic currently prohibits using the
+Claude Agent SDK with a Claude Pro / Max subscription. The dashboard
+surfaces a warning whenever a backend is running on subscription
+auth.
 
-You can point Aitne at one or more of your existing subscriptions.
 Each kind of work (heavy reasoning vs. a quick reply) is mapped to a
 backend; you can change the mapping any time.
 
-- Claude (via Claude Code)
-- Codex (via Codex CLI)
-- Gemini (via Gemini CLI)
-
 → [Backends and Tiers](../concepts/backends-and-tiers.md) ·
 [Costs and Quotas](../concepts/costs-and-quotas.md) ·
 [Backend Routing](../features/operations/backend-routing.md)
@@ -166,7 +182,9 @@ backend; you can change the mapping any time.
 - **An IDE plugin**: Claude Code is one of its backends, but the
   agent daemon is the surface, not the editor.
 - **A separate subscription**: Aitne itself does not bill you; you
-  pay your LLM provider directly.
+  pay your LLM provider directly via the API key you register (or via
+  the CLI's local subscription auth, if you opt into the fallback
+  path).
 
 ## Where to Start
 

package/agent-assets/docs/getting-started/02-first-steps.md

@@ -18,12 +18,13 @@ ask_examples:
   - Do I have to connect every integration?
 locale: en-US
 created: 2026-04-27
-updated: 2026-04-27
+updated: 2026-05-04
 related:
   - getting-started/01-what-is-this
   - getting-started/03-what-can-this-do
   - getting-started/04-first-day
   - guides/setup-wizard
+  - guides/use-cloud-providers
 ---
 
 # First Steps in the Dashboard
@@ -49,9 +50,19 @@ in (a backend, a messaging pair). Run through it once, top to bottom.
    the daemon claims you as the owner. See
    [Messaging Overview](../features/messaging/overview.md) for the
    list of supported apps and what each one does well.
-3. **Pick a main backend and plan.** This is the LLM the agent uses
-   for "think hard" turns. Defaults are sensible; you can change it
-   later from `/settings/models`. Background:
+3. **Pick a main backend and register an API key.** Pick the LLM
+   the agent uses for "think hard" turns (Claude / Codex / Gemini)
+   and paste a provider API key — the supported way to run a
+   headless agent. If you skip the key, the daemon falls back to
+   whatever subscription login the matching CLI already has on your
+   machine; the dashboard surfaces a warning when this happens
+   because most providers do not support running agents on a
+   personal subscription. The same picker also lets you point the
+   backend at a cloud provider (Bedrock / Vertex / Foundry / Azure
+   OpenAI / Gemini-Vertex) instead of the direct API key — see
+   [Use a Cloud Provider for Models](../guides/use-cloud-providers.md).
+   Defaults are sensible and can be changed later from
+   `/settings/models`. Background:
    [Backends and Tiers](../concepts/backends-and-tiers.md).
 4. **Skip integrations you do not need yet.** Mail, calendar, git,
    Notion, Obsidian are all optional and re-runnable any time from

package/agent-assets/docs/getting-started/03-what-can-this-do.md

@@ -19,13 +19,15 @@ ask_examples:
   - How does the agent reach out to me?
 locale: en-US
 created: 2026-04-27
-updated: 2026-04-27
+updated: 2026-05-04
 related:
   - getting-started/01-what-is-this
   - getting-started/02-first-steps
   - getting-started/04-first-day
   - concepts/routines
   - concepts/memory-model
+  - features/messaging/voice-attachments
+  - features/operations/skill-self-optimization
 ---
 
 # What This App Can Do
@@ -47,10 +49,13 @@ review writes a journal entry; weekly and monthly summaries roll up.
 
 DM the agent from Telegram, Slack, Discord, WhatsApp, or the
 dashboard's own chat. It answers, remembers, and can DM you back when
-something comes up.
+something comes up. Voice notes are transcribed locally with Whisper
+so you can talk to it the same way you'd type.
 
 - [Messaging Overview](../features/messaging/overview.md) — supported
   apps and how pairing works.
+- [Voice Attachments](../features/messaging/voice-attachments.md) —
+  local transcription of inbound audio.
 - [Dashboard Chat](../features/messaging/dashboard-chat.md) — the
   in-dashboard chat surface.
 
@@ -102,6 +107,16 @@ operations keep the agent from doing anything you don't want.
 - [Quiet Hours](../features/operations/quiet-hours.md) — when it
   stays silent.
 
+## Get sharper over time
+
+A background self-optimization loop watches how your knowledge layout
+drifts (new folders, schema tweaks, vocabulary changes) and refines
+specific skill sections to match. The original SKILL.md files are
+never rewritten — overlays are reversible.
+
+- [Skill Self-Optimization](../features/operations/skill-self-optimization.md)
+  — the loop, the cadence, and the dashboard surface.
+
 ## Related
 
 - [Your First Day](04-first-day.md) — what to expect when the agent

package/agent-assets/docs/guides/install-and-run.md

@@ -39,7 +39,16 @@ through the setup wizard.
 ## Prerequisites
 
 - Node ≥ 22, pnpm 10.x.
-- A Claude Code / Codex / Gemini CLI subscription (at least one).
+- A provider API key for at least one backend you intend to use:
+  Anthropic (`ANTHROPIC_API_KEY`), OpenAI (`OPENAI_API_KEY`), or
+  Google (`GEMINI_API_KEY` / `GOOGLE_API_KEY`). API keys are the
+  recommended and provider-supported way to run Aitne. If you skip
+  the key, Aitne falls back to the corresponding CLI's local
+  subscription login (`claude`, `codex login`, `gemini auth`); see
+  [Costs and Quotas](../concepts/costs-and-quotas.md) for the trade-
+  offs and the provider policies that apply.
+- The CLI binary for whichever backend you pick (Claude Code, Codex
+  CLI, or Gemini CLI) installed on `PATH`.
 - ~200 MB of disk for the daemon's local state.
 
 ## Steps

package/agent-assets/docs/guides/setup-wizard.md

@@ -10,7 +10,8 @@ aliases:
 category: guides
 summary: |
   Walks through the setup wizard step by step: profile, time axis,
-  backends and plans, messaging pairing, integrations, execution mode.
+  backend selection and API-key registration, messaging pairing,
+  integrations, execution mode.
 tags:
   - setup
 status: stable
@@ -20,16 +21,20 @@ ask_examples:
   - Do I have to connect every integration to start?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-27
+updated: 2026-05-04
 keywords:
   - setup
   - wizard
   - first run
+  - cloud providers
+  - bedrock
+  - vertex
 related:
   - getting-started/01-what-is-this
   - getting-started/02-first-steps
   - getting-started/04-first-day
   - concepts/safety-and-execution
+  - guides/use-cloud-providers
 ui_anchors:
   - /setup
 ---
@@ -61,10 +66,42 @@ Set your timezone and `dayBoundaryHour` (default 04:00). See
 [Agent Day](../concepts/agent-day.md) for why the boundary is not
 midnight.
 
-### Step 3 — Backends and Plans
-
-Pick a main backend (Claude / Codex / Gemini) and the plan you
-subscribe to. You can change this any time on `/settings/models`.
+### Step 3 — Backends and API Keys
+
+Pick a main backend (Claude / Codex / Gemini), verify the CLI is
+installed, and register a provider API key for it. The wizard uses
+the per-backend API-key panel to store the key in the OS keychain;
+the daemon mirrors it into `process.env` so the SDK / CLI subprocess
+picks it up.
+
+The provider dropdown picks one of:
+
+- **Claude** — `anthropic` (direct), `bedrock` (Amazon Bedrock),
+  `vertex` (Google Vertex AI), `foundry` (Microsoft Foundry).
+- **Codex** — `openai` (direct), `azure-openai` (Azure OpenAI; the
+  daemon writes a managed `config.toml` under `<dataDir>/codex-home/`
+  so your personal `~/.codex/` is untouched).
+- **Gemini** — `google` (direct AI Studio key), `gemini-vertex`
+  (Vertex AI).
+
+For non-direct providers, the form re-renders with the cloud-specific
+fields (region, project ID, AWS auth mode, deployment names, …). See
+[Use a Cloud Provider for Models](use-cloud-providers.md) for the
+full per-provider field reference.
+
+API key (or cloud-provider) registration is the recommended path
+because it is what Anthropic, OpenAI, and Google document for
+headless / programmatic agent use. Skipping the key is allowed —
+the daemon falls back to the backend's local CLI login
+(subscription auth) — but the dashboard flags the fallback because
+most providers do not officially support running automated agents on
+a personal subscription. Anthropic in particular currently prohibits
+using the Claude Agent SDK with a Claude Pro / Max subscription.
+
+Per-process model bindings are seeded with fixed defaults (Sonnet for
+owner-facing work, Haiku for delegated/simple polling); subscription-
+plan registration has been removed. You can change the bindings or
+the credentials any time on `/settings/models`.
 
 ### Step 4 — Execution Mode
 

package/agent-assets/docs/guides/switch-default-backend.md

@@ -18,11 +18,12 @@ ask_examples:
   - How do I make my morning routine use Gemini?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 related:
   - concepts/backends-and-tiers
   - features/operations/backend-routing
   - guides/change-which-model-handles-x
+  - guides/use-cloud-providers
 ---
 
 # Switch the Default Backend
@@ -34,8 +35,11 @@ ProcessKey to a different one.
 
 ## Prerequisites
 
-- The new backend is authenticated (Claude credentials, Codex token,
-  or Gemini API key).
+- The new backend has an API key registered on `/settings/models`
+  (`anthropic` / `openai` / `google`, or one of the cloud-provider
+  options for that backend). API keys are the supported path; if no
+  key is set, the daemon falls back to whatever subscription login
+  the CLI already has — the dashboard will flag it.
 
 ## Steps
 

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

@@ -17,9 +17,10 @@ ask_examples:
   - What does the docs-search skill do?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 related:
   - concepts/skills
+  - features/operations/skill-self-optimization
 ---
 
 # Built-in Skills
@@ -48,3 +49,11 @@ related:
 The source of truth is each skill's `SKILL.md` under
 `agent-assets/skills/<slug>/`. The `description` field in that file's
 frontmatter is what the dispatcher uses for runtime skill selection.
+
+A subset of these skills' sections (knowledge layout, routing
+tables, search recipes, etc.) is also refined at runtime through
+JSON **overlays** maintained by the skill-curation loop. The seed
+files in `agent-assets/skills/` are never rewritten — overlays are
+applied at session-init by the SkillsCompiler and live under
+`<dataDir>/overlays/<skill>/<section-id>.json`. See
+[Skill Self-Optimization](../features/operations/skill-self-optimization.md).