@aitne-sh/aitne 0.1.9 → 0.1.11

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

@@ -1,46 +1,54 @@
 ---
 schema_version: 1
 slug: guides/add-a-custom-routine
-title: Add a Custom Routine
+title: Create a Recurring Agent
 id: add-a-custom-routine
 aliases:
+  - recurring agent
+  - new agent
+  - user agent
   - custom routine
-  - user-defined routine
   - add a routine
   - scheduled task
 category: guides
 summary: |
-  Define a new autonomous routine — slug, cron expression, model tier, and
-  budget cap — via /settings/routines. The form writes a vault file at
-  policies/routines/custom/<slug>.md; saving it registers the cron job.
+  Make the agent run a prompt you write on a schedule you pick by
+  creating a user Agent — via the "New Agent" form on /agents or
+  POST /api/agents. The Markdown body (the prompt) becomes the task
+  prompt for every run; runs appear on the Agent's detail page.
 section: add-a-custom-routine
 tags:
   - guides
+  - agents
   - routines
   - scheduler
   - autonomous
   - core
 status: stable
 ask_examples:
-  - How do I add a custom routine?
-  - What can a custom routine do?
+  - How do I create a recurring agent?
   - How do I schedule the agent to run on a cron?
+  - How do I add a custom routine?
+  - Where do I see my agent's runs?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
-  - custom routine
-  - schedule
+  - recurring agent
+  - new agent
   - cron
+  - schedule
   - recurrence
-  - backend_tier
-  - process_key
+  - task prompt
+  - agent.task
 ui_anchors:
-  - /settings/routines
+  - /agents
 api_endpoints:
-  - PUT /api/context/*
+  - POST /api/agents
+  - GET /api/agents/{slug}/executions
+  - POST /api/agents/{slug}/run-now
 context_files:
-  - policies/routines/custom/<slug>.md
+  - policies/agents/<slug>/agent.md
 related:
   - features/routines/custom-routines
   - concepts/routines
@@ -48,76 +56,122 @@ related:
   - concepts/backends-and-tiers
 ---
 
-# Add a Custom Routine
+# Create a Recurring Agent
 
 ## Goal
 
-Make the agent fire a particular kind of work on a schedule you pick.
+Make the agent fire a particular kind of work on a schedule you pick —
+as a user **Agent** you can watch, tune, and toggle from `/agents`.
 
 ## Prerequisites
 
 - Daemon running.
 
-## Steps
-
-1. Open `/settings/routines` (the older `/connections/routines` URL
-   redirects here).
-2. Click **Add**. The "New custom routine" dialog opens.
-3. Fill the form:
-   - **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
----
+## Steps (dashboard)
+
+1. Open **Agents** (`/agents`) and click **New Agent**.
+2. Fill the form:
+   - **Name** — the human label in the agents list (e.g. "Daily
+     Digest").
+   - **ID** — lowercase kebab-case slug. It becomes the URL
+     (`/agents/<id>`) and the definition file
+     `policies/agents/<id>/agent.md`. Must not collide with an
+     existing Agent (built-in slugs are reserved too).
+   - **Schedule** — pick a frequency (hourly / daily / weekly /
+     monthly) and its fields, e.g. weekly on Tuesday at 11:00. An
+     optional toggle defers runs that land inside your quiet hours.
+   - **Backend engine / Model tier** — `lite` (Haiku-class), `medium`
+     (Sonnet-class), or `high` (Opus-class). See
+     [Backends and tiers](../concepts/backends-and-tiers.md).
+   - **Limits** — max turns, max budget (USD) per run, and timeout
+     (minutes).
+   - **Task prompt** — what the agent should do on each run. This text
+     becomes the Markdown body of `agent.md` and is the prompt the
+     agent receives every time it fires.
+   - An **Advanced (YAML)** toggle reveals the raw `agent.md` editor
+     for long-tail fields the form doesn't expose (tags, tools,
+     success criteria, error handling).
+3. Save. The dashboard writes `policies/agents/<slug>/agent.md`
+   through the context vault and opens the new Agent's detail page;
+   the daemon imports the file without a restart.
+
+## Steps (API)
+
+`POST /api/agents` is the programmatic counterpart:
+
+```bash
+curl -X POST http://localhost:8321/api/agents \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slug": "tuesday-notion-sweep",
+    "name": "Tuesday Notion Sweep",
+    "description": "Weekly Notion inbox cleanup",
+    "schedule": { "kind": "cron", "expression": "0 11 * * 2" },
+    "backend": { "tier": "medium" },
+    "limits": { "max_budget_usd": 0.10 },
+    "prompt": "- Review my Notion inbox for items older than a week.\n- File or archive each one.\n- DM me a one-paragraph summary."
+  }'
 ```
 
-To stop a routine without deleting it, set `enabled: false` in the
-file and save — that unregisters the cron job.
+- **`prompt` becomes the Agent's task prompt** — it is stored as the
+  Markdown body of `agent.md` and sent to the agent on every run.
+- **`schedule`** takes one of two forms: a raw 5-field cron
+  (`{ "kind": "cron", "expression": "0 11 * * 2" }`, interpreted in
+  the daemon's timezone unless `schedule.timezone` is set) or a
+  structured rule (`{ "kind": "recurring", "recurrence": { "frequency":
+  "weekly", "daysOfWeek": ["tuesday"], "time": "11:00" } }`).
+  `/agents` is recurring-only — a one-time task belongs on
+  `POST /api/schedule` instead.
+- **`backend.tier`** is optional; omitted, the Agent inherits the
+  `agent.task` process default (medium). `backend.process_key`
+  defaults to `agent.task` — you don't need to set it.
+- **`limits`** defaults: 20 turns, $0.25 per run, 10-minute timeout.
+- Success returns `201 { "status": "created", "slug": ... }`. A taken
+  slug returns `409 slug_collision`; validation failures return `400`
+  with a field-level `issues` list.
+
+## Where to See Runs
+
+- **`/agents`** lists every Agent with its schedule, enable toggle,
+  7-day metrics, and last run.
+- **`/agents/<slug>`** is the detail page: the full definition, recent
+  execution history with results and cost, and a **Run now** button
+  (`POST /api/agents/<slug>/run-now`).
+- **Activity** logs each run alongside everything else the agent does.
+- Programmatically: `GET /api/agents/<slug>/executions`.
 
 ## Verification
 
-- Wait for the cron to fire; check Activity for the row tagged
-  `routine.custom.<slug>`.
+- Click **Run now** on the detail page (or wait for the schedule); an
+  execution row should appear with its result and cost.
 
 ## If It Fails
 
-- 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
+- `409 slug_collision` — pick a different ID; built-in Agent slugs are
+  reserved.
+- `400 invalid_definition` — fix the fields listed in `issues`.
+- `400 one_shot_not_supported` — `/agents` is recurring-only; use
+  `POST /api/schedule` for one-time work.
+- A prompt that hits the absolute-block guardrails: the run fires but
+  the offending tool call is logged as `blocked_absolute` in the
   action log.
 
+## Migrating From Custom Routines
+
+The legacy custom-routine format —
+`policies/routines/custom/<slug>.md` files with `cron:` frontmatter
+and a `## Checks` body — is retired and those files no longer fire.
+At the first daemon start after the upgrade, each valid file was
+converted **once** into a user Agent with the same cron, tier, budget,
+and enabled state; the `## Checks` body became the Agent's task
+prompt, and the source file was kept but marked inert
+(`enabled: false` plus a `migrated_to_agent: <slug>` marker). See
+[Custom Routines (Retired)](../features/routines/custom-routines.md)
+for collision and invalid-file handling.
+
 ## Related
 
-- [Custom Routines](../features/routines/custom-routines.md)
+- [Custom Routines (Retired)](../features/routines/custom-routines.md)
+- [Routines](../concepts/routines.md)
+- [ProcessKeys](../concepts/process-keys.md)
+- [Backends and tiers](../concepts/backends-and-tiers.md)

package/agent-assets/docs/guides/budget-and-cost-for-wiki.md

@@ -27,7 +27,7 @@ ask_examples:
   - What does the pre-compile snapshot do?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - wiki budget
   - wiki cost
@@ -126,7 +126,7 @@ before `!compile full`** enabled, Aitne runs:
 git -C <vault> status --porcelain
 # must be empty — dirty trees refuse the operation entirely
 git -C <vault> add -A
-git -C <vault> commit -m "aitne wiki: pre-compile snapshot <ISO-8601-ts>"
+git -C <vault> commit --allow-empty -m "aitne wiki: pre-compile snapshot <ISO-8601-ts>"
 ```
 
 before the compile session starts. The commit message is

package/agent-assets/docs/guides/connect-a-new-mail-account.md

@@ -27,7 +27,7 @@ ask_examples:
   - How do I connect an Outlook mailbox?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - mail
   - imap
@@ -48,6 +48,7 @@ api_endpoints:
   - /api/config/mail/app-password
 config_keys:
   - enabledMailProviders
+  - mailPollIntervalSeconds
 context_files:
   - state/today.md
 ---
@@ -96,7 +97,8 @@ kind authenticates differently:
 4. Save. Registration succeeds regardless of the enabled-providers
    setting (`enabledMailProviders`); the account goes live only when
    you flip its **Enable** toggle on the mail card.
-5. The first poll runs within a minute of being enabled.
+5. The account is picked up on the next mail poll tick (default every
+   180 seconds, configurable via `mailPollIntervalSeconds`).
 
 ## Verification
 

package/agent-assets/docs/guides/explore-with-trace-and-connect.md

@@ -30,7 +30,7 @@ ask_examples:
   - How do I run !trace against a non-default wiki workspace?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - "!trace"
   - "!connect"
@@ -187,6 +187,7 @@ Every report is a regular wiki file under `30_outputs/`. You can:
 ## Cost Envelope
 
 Both commands run at Sonnet medium tier with a default $1.00
-spend cap per run, identical to `!ask`. The 7-day cost rollup on
-**Settings → Wiki** breaks the spend out per command so you can
-see where the budget went.
+spend cap per run, identical to `!ask`. The **Settings → Wiki**
+overview shows a single 7-day cost stat across all wiki commands;
+to see per-command spend, filter the timeline on `/wiki/timeline`
+by `wiki.trace` or `wiki.connect`.

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

@@ -29,7 +29,7 @@ ask_examples:
   - How do I install the aitne npm package?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - install
   - first run
@@ -60,7 +60,7 @@ through the setup wizard.
   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
+  subscription login (`claude auth login`, `codex login`, `gemini`); 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

package/agent-assets/docs/guides/maintain-wiki-health.md

@@ -28,7 +28,7 @@ ask_examples:
   - What is a taxonomy candidate?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - wiki health
   - wiki lint
@@ -68,7 +68,7 @@ notes itself.
 ## When to Run
 
 `!lint` runs on the `wiki.lint` process key (medium tier — Sonnet
-by default, $1.00 budget envelope) and never changes your notes.
+by default, $0.50 budget envelope) and never changes your notes.
 Run it whenever you want a snapshot of wiki health. A practical
 cadence:
 

package/agent-assets/docs/guides/pause-the-agent.md

@@ -23,7 +23,7 @@ ask_examples:
   - Can I disable everything for a week?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - pause agent
   - stop agent
@@ -36,10 +36,10 @@ related:
   - features/messaging/bang-commands
   - concepts/routines
 ui_anchors:
-  - /settings/schedule
-  - /settings/routines
+  - /settings/hours
+  - /agents
 config_keys:
-  - hourlyCheckEnabled
+  - activityScanEnabled
   - monthlyReviewEnabled
   - quietHoursStart
   - quietHoursEnd
@@ -62,7 +62,7 @@ DM `!stop` to the agent on any paired messaging app. This is the
 recommended way to go silent and the only one you need for most cases:
 
 - It pauses **every** cron-driven routine — morning, evening, weekly,
-  monthly, and the hourly check — not just one of them.
+  monthly, and the activity scan — not just one of them.
 - Non-command DMs are declined with a paused notice (no LLM cost)
   until you resume.
 - The paused state is persisted, so a daemon restart does **not**
@@ -75,23 +75,29 @@ Resume with `!start` whenever you want the agent active again. See
 
 ## Finer-grained control from the dashboard
 
-If you want to mute specific behaviour rather than pause everything, use
-`/settings/schedule`:
-
-1. **Disable the hourly check** — toggle `hourlyCheckEnabled` off. This
-   leaves the morning, evening, weekly, and monthly routines running.
-2. **Disable the monthly review** — toggle `monthlyReviewEnabled` off
-   (it ships off by default).
-3. **Silence notifications without pausing work** — set an extended
-   quiet hours window: e.g. `quietHoursStart: "00:00"`,
-   `quietHoursEnd: "23:59"`. Both fields take an `HH:MM` string.
-   Routines still run; they just don't notify you.
+If you want to mute specific behaviour rather than pause everything:
+
+1. **Disable the activity scan** — open `/agents/activity-scan` and click
+   **Disable**. This leaves the morning, evening, weekly, and monthly
+   routines running. (The agent's enable switch replaced the legacy
+   `activityScanEnabled` config key, now a deprecated fallback.)
+2. **Disable the monthly review** — open `/agents/monthly-review` and
+   click **Disable** (it ships disabled by default; the agent's enable
+   switch replaced the legacy `monthlyReviewEnabled` config key).
+3. **Silence notifications without pausing work** — on `/settings/hours`
+   ("Hours & Notifications"), set an extended quiet hours window: e.g.
+   `quietHoursStart: "00:00"`, `quietHoursEnd: "23:59"`. Both fields
+   take an `HH:MM` string. Routines still run; they just don't notify
+   you.
 
 Morning (fires at the day boundary, default 04:00), evening (18:00),
-and weekly (Fri 18:00) reviews have no per-routine enable toggle in the
-dashboard — to stop them, use `!stop` above. You can still edit each
-routine's instructions on `/settings/routines`, but that page does not
-turn them on or off.
+and weekly (Fri 19:00) reviews each have a per-routine Enable/Disable
+toggle on the `/agents` page — open `/agents/<slug>` (e.g.
+`/agents/weekly-review`) and click Disable (a stop-warning confirmation
+appears for these system agents). To halt all of them at once, use
+`!stop` above instead. Each routine's instructions (its rulebook) are
+edited on the same page's **Rulebook** tab
+(`/agents/<slug>?tab=rulebook`).
 
 ## Last resort: stop the daemon
 
@@ -111,7 +117,7 @@ temporary pause that survives across days, prefer `!stop`. Restart with
 
 - A routine still fires after `!stop`: confirm the pause registered by
   checking `!help` or the dashboard banner; re-send `!stop`.
-- A toggle on `/settings/schedule` did not take effect: confirm it
+- A setting on `/settings/hours` did not take effect: confirm it
   saved — the dashboard's "Save" button must be clicked.
 
 ## Related

package/agent-assets/docs/guides/reinstall-cleanly.md

@@ -46,6 +46,8 @@ related:
   - guides/migrate-machines
   - guides/pause-the-agent
   - glossary
+ui_anchors:
+  - /settings/danger-zone
 ---
 
 # Reinstall Cleanly

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

@@ -29,7 +29,7 @@ ask_examples:
   - Where do I paste my API key?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-10
 keywords:
   - setup
   - wizard
@@ -57,7 +57,8 @@ ui_anchors:
   - /setup
   - /settings/models
   - /connections
-  - /settings/routines
+  - /agents
+  - /settings/hours
 ---
 
 # Setup Wizard Walkthrough
@@ -187,10 +188,15 @@ character prompt referenced in Step 1 actually gets written.
 
 ## After the wizard
 
-Routines are **not** configured in the wizard. Enable and schedule the
-morning / evening / weekly reviews and the hourly check post-setup on
-`/settings/routines`. Repositories are also added after setup, from
-Settings → Connections → Repositories.
+Routines are **not** configured in the wizard. Post-setup, each routine
+is an agent under `/agents`: edit the per-cadence rulebooks (morning /
+evening / weekly / activity scan) on the agent's Rulebook tab, create custom
+recurring agents from the New Agent dialog, set the activity-scan switch
+and cadence on `/agents/activity-scan`, and opt into the monthly review
+by enabling `/agents/monthly-review`. Quiet hours, timezone, and
+notification caps live on `/settings/hours` ("Hours & Notifications").
+Repositories are also added after setup, from Connections →
+Repositories.
 
 ## Verification
 

package/agent-assets/docs/guides/use-an-existing-obsidian-vault.md

@@ -26,7 +26,7 @@ ask_examples:
   - Why is Split greyed out?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - external vault
   - existing obsidian vault
@@ -68,11 +68,11 @@ vs Split**.
 
 Open **`/settings/wiki`** in the dashboard (or open `/wiki` and follow
 the **Enable Wiki** button — both land on the same page). If you have
-no workspace yet, the page shows two CTAs:
+no workspace yet, the page shows two options:
 
-- **Enable Internal Workspace** — uses the daemon-owned root.
-- **Probe & Create External** — points at the path you choose with
-  the folder picker.
+- **Internal** → **Enable internal wiki** — uses the daemon-owned root.
+- **Existing Obsidian vault** → **Use this folder** — points at the
+  path you choose with the folder picker.
 
 ### Picking the path
 
@@ -110,7 +110,7 @@ levels:
   an existing wiki layout is detected, the wizard will surface the
   Adopt / Migrate decision in Step 3.
 
-The **Probe & Create External** button is greyed out while the banner
+The **Use this folder** button is greyed out while the banner
 is an error so you cannot fire a workspace-create that the daemon
 already knows will fail.
 

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

@@ -28,7 +28,7 @@ ask_examples:
   - How do I list registered backends?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-06-08
 keywords:
   - API
   - REST
@@ -54,7 +54,7 @@ The daemon serves a single Hono app on `127.0.0.1:PA_API_PORT` (default
 `8321`). Almost all endpoints are mounted under `/api/*`; the lone
 exception is the GitHub webhook receiver, mounted at root `/webhook/github`.
 **Source of truth:** `packages/daemon/src/api/server.ts` (`createApp`)
-registers most route groups, with two post-compose mounts in
+registers most route groups, with one post-compose mount in
 `packages/daemon/src/bootstrap/api.ts` (the docs corpus + docs-QA, wired
 only after the indexer handle exists). Each group lives in its own file
 or directory under `packages/daemon/src/api/routes/`.
@@ -93,13 +93,13 @@ callers pass it as `Authorization: Bearer <token>`.
 | Activity sources | `/api/activity-sources/*` | `activity-sources.ts` | Activity feed sources. |
 | Entities | `/api/entities/*` | `entities.ts` | Entity registry CRUD. |
 | SoT bindings | `/api/sot-bindings/*` | `sot-bindings.ts` | Source-of-truth bindings (vault ↔ daemon). |
-| Voice | `/api/voice/*` | `voice.ts` | Voice transcript cache + transcribe-on-demand. |
+| Voice | `/api/voice/*` | `voice.ts` | Whisper model install / status / weight-removal opt-in surface for the dashboard. |
 
 ### Integrations
 
 | Group | Path | Source | Purpose |
 |---|---|---|---|
-| Mail | `/api/mail/*` | `mail.ts`, `mail-search.ts` | Multi-provider mail proxy (Gmail / Outlook / Yahoo / iCloud / IMAP) + FTS5 local search. |
+| Mail | `/api/mail/*` | `mail/` | Multi-provider mail proxy (Gmail / Outlook / Yahoo / iCloud / IMAP) + FTS5 local search. |
 | Calendar | `/api/calendar/*` | `calendar.ts` | Google Calendar proxy. |
 | Apple Calendar | `/api/apple-calendar/*` | `apple-calendar.ts` | macOS Calendar.app bridge. |
 | Notion | `/api/notion/*` | `notion.ts` | Notion proxy. |
@@ -107,7 +107,7 @@ callers pass it as `Authorization: Bearer <token>`.
 | Git | `/api/git/*`, `/api/git-accounts/*` | `git.ts`, `git-accounts.ts`, `git-templates.ts` | Read-only git proxy (`/api/git/{log,diff,show}`), repo templates (`/api/git/templates/*`), and git-account CRUD (`/api/git-accounts/*`). |
 | Repositories | `/api/repositories/*` | `repositories.ts` | Unified repository CRUD (replaces split Git/GitHub settings). |
 | GitHub | `/api/github/*`, `POST /webhook/github` | `github.ts` | GitHub proxy and webhook receiver (mounted under `/`, not `/api`). |
-| Integrations | `/api/integrations/*` | `integrations.ts`, `integrations-reconcile.ts` | Integration mode CRUD (`direct \| delegated \| native \| disabled`), live probe endpoint, mode reconciliation. |
+| Integrations | `/api/integrations/*` | `integrations/`, `integrations-reconcile.ts` | Integration mode CRUD (`direct \| delegated \| native \| disabled`), live probe endpoint, mode reconciliation. |
 | Delegated sync | `/api/delegated/*`, `/api/delegated-sync/*` | `delegated.ts`, `delegated-sync.ts` | Delegated worker control + opt-in cadence config. |
 | MCP | `/api/mcp/*` | `mcp.ts` | Per-session MCP materializer. |
 
@@ -129,6 +129,27 @@ callers pass it as `Authorization: Bearer <token>`.
 | Books | `/api/books/*` | `books.ts` | Reading-list CRUD. |
 | Travel bookings | `/api/travel-bookings/*` | `travel-bookings.ts` | Travel-booking CRUD. |
 
+### Feedback learning
+
+All three routes are `RiskTier.Autonomous`. `POST /api/feedback` server-restricts `source` to `explicit` / `self_critique` — `behavioral` signals are daemon-only (written by `SignalDetector`) and a `behavioral` body returns 400.
+
+| Group | Path | Source | Purpose |
+|---|---|---|---|
+| Feedback | `POST /api/feedback` | `feedback.ts` | Record an explicit or self-critique feedback signal. Dedups on `(scope_type, scope_ref, summary)` within 10 min. When `feedbackLearningEnabled=false` returns `200 {disabled:true}` without recording. |
+| Feedback consume | `POST /api/feedback/consume` | `feedback.ts` | `{ids: number[], lessonRef?}` → `{consumed, notFound}`. Marks signals consumed after a consolidation pass. |
+| Feedback lessons | `GET /api/feedback/lessons` | `feedback.ts` | Read-only lesson-store overview for the dashboard — global `agent` store plus every per-agent store on disk, with cap-utilisation metrics. |
+
+### Self-tuning
+
+Both routes are `RiskTier.Autonomous`. The weekly review's Recommend pre-step generates at most 3 bounded recommendations per cycle; verdicts may only reference the single-use ids the daemon generated for the **current** cycle (the pending blob is overwritten — and prior ids expired — every weekly run). Verdicts are always recorded and audited as `agent_actions.action_type='self_tuning.verdict'`, and rejections become `self_critique` feedback signals server-side.
+
+While `selfTuningEnabled=false` (the shipped default) the loop runs in **shadow mode**: nothing is ever actuated and responses carry `shadow: true` with an empty `applied` array. With the flag on (**live mode**), newly-recorded `apply` verdicts actuate per key namespace: config knobs go through the `applyConfigUpdates` chokepoint (bounds enforced there), write a `runtime_state.self_tuning:<key>` ledger entry, audit `self_tuning.applied`, and DM the owner one line with the `!revert tuning` undo hint; `notification:<type>` (R2) applies are recorded as lesson guidance only; `recurring_schedules:<id>` (R4) applies become an owner DM suggestion — never an automatic flip. Retried POSTs are `duplicate` per id and never re-actuate. A daily auto-revert monitor re-measures each applied change after its 7-day verify window and reverts on regression (audit `self_tuning.reverted`, 28-day re-proposal cool-down); clean windows are stamped `self_tuning.verified`.
+
+| Group | Path | Source | Purpose |
+|---|---|---|---|
+| Tuning verdicts | `POST /api/tuning/verdicts` | `tuning.ts` | `{cycleId, verdicts: [{id, verdict: apply\|reject\|defer, reason}]}` → per-id `recorded`/`duplicate`/`conflict` results plus `shadow`, `applied[]`, and `actuationFailures[]`. Idempotent per id (first verdict wins); 400 atomically on any unknown id; 409 on a missing or expired cycle. |
+| Tuning pending | `GET /api/tuning/pending` | `tuning.ts` | The current cycle's recommendations + recorded verdicts, for the owner's validation and the dashboard. `shadow` reflects the live flag. |
+
 ### Docs and wiki
 
 | Group | Path | Source | Purpose |

package/agent-assets/docs/reference/cli-commands.md

@@ -28,7 +28,7 @@ ask_examples:
   - How do I check my install with aitne doctor?
 locale: en-US
 created: 2026-04-27
-updated: 2026-05-28
+updated: 2026-06-07
 keywords:
   - aitne start
   - aitne stop
@@ -95,7 +95,7 @@ needed.
 | `aitne open` | Open the dashboard root in the default browser. |
 | `aitne doctor` | Install-health checks (Node, ports, OS keychain, backend CLIs, native bindings, …). |
 | `aitne audit [--since 24h] [--type X] [--result failed]` | Show the agent action log; flags filter by time, action type, result, or backend. `--json` for machine-readable. |
-| `aitne run-now <job>` | Fire a daemon-internal maintenance job on demand. The only supported job today is `roadmap_maintenance`. Reads the API token from the macOS Keychain, so this command is macOS-only. |
+| `aitne run-now <job>` | Fire a daemon-internal maintenance job on demand. The only supported job today is `roadmap_maintenance`. Reads the API token from the OS secret store (macOS Keychain, Windows DPAPI, Linux libsecret, or the encrypted file fallback), so it works on every supported platform. |
 | `aitne verify [target]` | Run post-launch verification for a shipped design surface (e.g. `evening-review-slimdown`). |
 | `aitne version [--json]` | Print version, Node version, install path, last build time. |
 | `aitne update [--check]` | Print the npm command to upgrade. `--check` makes one network call to compare against the latest published version. |
@@ -150,7 +150,7 @@ and the cost-gate / approval semantics.
 |---|---|---|
 | `PA_DATA_DIR` | `~/.personal-agent` | Where logs, the SQLite DB, context Markdown, and prompts live. |
 | `PA_API_PORT` | `8321` | Daemon HTTP port. |
-| `PA_DASHBOARD_PORT` | `3000` | Dashboard port. |
+| `PA_DASHBOARD_PORT` | `8322` | Dashboard port. |
 
 All runtime state — PIDs, logs, SQLite DB, context Markdown, prompts —
 lives under `PA_DATA_DIR`, **not** inside the repo.