@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -9,19 +9,27 @@ aliases:
   - install wizard
 category: guides
 summary: |
-  Walks through the setup wizard step by step: profile, time axis,
-  backend selection and API-key registration, messaging pairing,
-  integrations, execution mode.
+  Walks through the setup wizard step by step: basics (name + language),
+  vault, AI backend + API-key registration + execution mode, mail,
+  calendar, notes, messaging pairing, and the chat-driven Customize
+  Rules step.
+section: guides
 tags:
+  - core
+  - guides
+  - getting-started
   - setup
+  - backends
+  - messaging
 status: stable
 ask_examples:
   - What does each setup step do?
   - Can I rerun the setup wizard?
   - Do I have to connect every integration to start?
+  - Where do I paste my API key?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - setup
   - wizard
@@ -29,14 +37,27 @@ keywords:
   - cloud providers
   - bedrock
   - vertex
+  - foundry
+  - azure-openai
+  - opencode
+  - execution mode
 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
+  - concepts/backends-and-tiers
+config_keys:
+  - agentDisplayName
+  - primaryLanguage
+  - vaultMode
+api_endpoints:
+  - POST /api/setup/mode
 ui_anchors:
   - /setup
+  - /settings/models
+  - /connections
+  - /settings/routines
 ---
 
 # Setup Wizard Walkthrough
@@ -44,35 +65,56 @@ ui_anchors:
 ## Goal
 
 Take a fresh install through the wizard with informed answers at each
-step. The wizard is rerunnable any time (`/setup?mode=update`); skip
-the steps you have already filled in.
+step. The wizard is rerunnable any time at `/setup?mode=update`, which
+jumps straight to the Customize Rules step so you can refine the agent
+without redoing the whole flow.
 
 ## Prerequisites
 
-- The daemon is launched (`pa start` or `pnpm start`).
-- The dashboard is reachable at `http://localhost:3000`.
+- The daemon is launched (`aitne start` or `pnpm start`).
+- The dashboard is reachable at `http://localhost:8322`.
+
+## The steps at a glance
+
+The wizard has eight collection steps plus a terminal "Done" screen.
+Three are required (**Basics**, **Vault**, **AI Backend**, plus
+**Customize Rules**); the four integration/messaging steps are
+skippable and re-runnable later.
+
+| # | Step | Required? | What it sets |
+|---|------|-----------|--------------|
+| 1 | Basics | required | Agent display name + primary language |
+| 2 | Vault | required | Vault mode (plain MD vs. Obsidian) + primary path |
+| 3 | AI Backend | required | Main backend, API key, execution mode |
+| 4 | Mail | skippable | Gmail / Outlook / IMAP accounts |
+| 5 | Calendar | skippable | Google / Outlook calendars |
+| 6 | Notes | skippable | Notion + external Obsidian vault |
+| 7 | Messaging | skippable | Slack / Telegram / Discord / WhatsApp pairing |
+| 8 | Customize Rules | required | Chat-driven persona + house rules |
 
 ## Steps
 
-### Step 1 — Profile
+### Step 1 — Basics
 
-Pick a display name for the agent and (optionally) a character
-prompt. The character is prepended to every session as part of the
-agent profile.
+Pick a display name for the agent and the primary language it should
+write in. The character/persona itself is *not* set here — that is
+generated interactively in the Customize Rules step (Step 8).
 
-### Step 2 — Time Axis
+### Step 2 — Vault
 
-Set your timezone and `dayBoundaryHour` (default 04:00). See
-[Agent Day](../concepts/agent-day.md) for why the boundary is not
-midnight.
+Choose how durable memory is stored: **plain** (Markdown under
+`~/.personal-agent/context/`, the default) or **Obsidian** (point the
+agent at an existing vault and set the primary path inline). See
+[Use an Existing Obsidian Vault](use-an-existing-obsidian-vault.md)
+for the Obsidian path.
 
-### Step 3 — Backends and API Keys
+### Step 3 — AI Backend
 
-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.
+Pick a main backend (**Claude**, **Codex**, **Gemini**, or
+**OpenCode**), verify the CLI is installed, and register a provider
+API key for it. The wizard stores the key in the OS keychain; the
+daemon mirrors it into the backend subprocess environment so the SDK /
+CLI picks it up.
 
 The provider dropdown picks one of:
 
@@ -84,56 +126,84 @@ The provider dropdown picks one of:
 - **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.
+For non-direct providers the form re-renders with the cloud-specific
+fields (region, project ID, AWS auth mode, deployment names, …). Refer
+to your cloud provider's enterprise / Vertex / Bedrock documentation
+for each field's value; the daemon stores them in the OS keychain and
+mirrors the matching env vars into the backend subprocess.
 
-API key (or cloud-provider) registration is the recommended path
+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.
+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: **Claude
+Sonnet 4.6** (`claude-sonnet-4-6`) for owner-facing work and **Claude
+Haiku 4.5** (`claude-haiku-4-5-20251001`) for delegated/simple
+polling. Opus (`claude-opus-4-8`) is registered but not seeded — opt
+in per row. There are no subscription-plan questions. Change the
+bindings or credentials any time on `/settings/models`.
+
+**Execution mode** is set on this same step (one card below the
+backend picker). Choose **Safe** (recommended) or **Allow** per
+backend; the top-level choice applies to every backend you do not
+override. Safe is the strict-permission posture; the absolute-block
+layer holds in both modes. The same setting is exposed later via
+`POST /api/setup/mode` (`{mode, perBackend?}`) and the Execution Mode
+card on `/settings/models`. See
+[Safety and Execution](../concepts/safety-and-execution.md).
+
+### Step 4 — Mail (skippable)
+
+Connect Gmail, Outlook, or a generic IMAP account. Re-runnable later
+from `/connections`.
+
+### Step 5 — Calendar (skippable)
 
-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`.
+Connect Google or Outlook calendars. Re-runnable from `/connections`.
 
-### Step 4 — Execution Mode
+### Step 6 — Notes (skippable)
 
-Choose Safe (recommended) or Allow per backend. The absolute-block
-layer holds in both modes; Safe is the strict-permission posture.
+Connect Notion and/or point at an external Obsidian vault. Re-runnable
+from `/connections`.
 
-### Step 5 — Messaging
+### Step 7 — Messaging (skippable, but do it)
 
-Pair at least one messaging app (Telegram is the easiest). Without
-a paired app, the agent has no way to DM you.
+Pair at least one messaging app (Telegram is the easiest). Without a
+paired app, the agent has no way to DM you, so this is the one
+"skippable" step worth completing on the first run. Re-runnable from
+`/connections`.
 
-### Step 6 — Integrations
+### Step 8 — Customize Rules
 
-Optional — connect mail, calendar, git, Notion, Obsidian as you go.
-Each integration is independently re-runnable from `/connections`.
+A chat-driven step (no form): you talk to the agent to shape its
+persona/character and your house rules. The agent stages a character
+block and rule set you can review before saving. This is where the
+character prompt referenced in Step 1 actually gets written.
 
-### Step 7 — Routines
+## After the wizard
 
-Toggle which routines are enabled (morning, evening, weekly, monthly,
-hourly check) and pick the hours.
+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.
 
 ## Verification
 
-- The dashboard's Overview shows a green health pill and your paired
+- The dashboard Overview shows a green health pill and your paired
   messaging app.
-- Send a DM from the paired app and watch the response.
+- Send a DM from the paired app and watch for the response.
 
-## If It Fails
+## If it fails
 
-- A step that errors: check `pa logs` for the underlying daemon
-  message. Most failures are credential shape issues.
-- A backend that won't authenticate: see [Auth Failed](../troubleshooting/auth-failed.md).
+- A step that errors: check `aitne logs` for the underlying daemon
+  message. Most failures are credential-shape issues.
+- A backend that won't authenticate: see
+  [Auth Failed](../troubleshooting/auth-failed.md).
 
 ## Related
 

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

@@ -3,6 +3,10 @@ schema_version: 1
 slug: guides/switch-default-backend
 title: Switch the Default Backend
 id: switch-default-backend
+aliases:
+  - switch backend
+  - change main backend
+  - switch claude codex gemini opencode
 category: guides
 summary: |
   Change the main backend the agent uses for most ProcessKeys, plus
@@ -10,55 +14,106 @@ summary: |
   different backend.
 section: switch-default-backend
 tags:
-  - guide
+  - guides
   - backends
+  - operations
+  - routing
 status: stable
 ask_examples:
   - How do I switch from Claude to Codex?
-  - How do I make my morning routine use Gemini?
+  - How do I make Gemini the default backend?
+  - How do I change the main backend the agent uses?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
+keywords:
+  - main backend
+  - switch backend
+  - default backend
+  - PUT /api/backends/main
 related:
   - concepts/backends-and-tiers
   - features/operations/backend-routing
   - guides/change-which-model-handles-x
-  - guides/use-cloud-providers
+  - troubleshooting/fallback-keeps-firing
+ui_anchors:
+  - /settings/models
+  - /activity
+process_keys:
+  - message.dm
+  - dashboard.docs_qa
+api_endpoints:
+  - PUT /api/backends/main
+  - POST /api/backends/apply-defaults
 ---
 
 # Switch the Default Backend
 
 ## Goal
 
-Change which backend the agent uses by default, or pin a specific
-ProcessKey to a different one.
+Change which backend the agent uses by default for most work —
+`claude`, `codex`, `gemini`, or `opencode`. This is the broad switch
+that re-seeds every ProcessKey to the new backend's per-tier default
+models. To change just one ProcessKey instead, see
+[Change which model handles X](change-which-model-handles-x.md).
 
 ## Prerequisites
 
-- The new backend has an API key registered on `/settings/models`
+The new backend needs working auth before you switch, or the agent
+will start failing the moment it routes work there.
+
+- Register an API key for the backend 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.
+  options for that backend).
+- API keys are the supported path. If no key is set, the daemon falls
+  back to whatever subscription login the backend's CLI already has —
+  the auth-health card on `/settings/models` flags this so you can
+  tell which credential is actually in use.
 
 ## Steps
 
 1. Open `/settings/models`.
-2. Click "Main backend" and pick the new default.
-3. The cascade-write helper updates inheriting ProcessKeys
-   (e.g. `dashboard.docs_qa` follows `message.dm`'s pin).
-4. Per-ProcessKey overrides happen in the table below — pick a row
-   and choose its main / fallback.
+2. In the "Main backend" control, pick the new default and confirm.
+3. The daemon re-seeds every ProcessKey to the new backend's per-tier
+   default model (lite → medium → high). Rows you previously pinned
+   yourself are **left untouched** — the re-seed skips any binding you
+   set by hand, so your manual overrides survive the switch.
+
+Behind the scenes step 2 calls `PUT /api/backends/main`, which writes
+the new `default_backend`, runs the re-seed
+(`POST /api/backends/apply-defaults` is the same logic you can trigger
+manually to reset), and cascades any integrations that were in `native`
+mode off the old backend.
+
+### What the re-seed picks
+
+Each ProcessKey keeps its tier; only the backend-specific model id
+changes. For example, switching the main backend to Codex maps:
+
+- lite-tier keys → `gpt-5.4-mini`
+- medium-tier keys → `gpt-5.4`
+- high-tier keys → `gpt-5.4` (the seeded high default collapses to the
+  medium model; `gpt-5.5` stays opt-in only)
+
+`dashboard.docs_qa` is hard-locked to the medium tier regardless of the
+backend, so it always lands on that backend's medium model.
 
 ## Verification
 
-- The Activity feed's next routine row shows the new backend.
+- The Activity feed (`/activity`) shows the new backend on the next
+  routine or DM row.
 
 ## If It Fails
 
-- Auth-health card flips amber: see [Auth Failed](../troubleshooting/auth-failed.md).
+- The auth-health card on `/settings/models` flips amber — the new
+  backend's credential isn't valid. See
+  [Auth Failed](../troubleshooting/auth-failed.md).
+- If the agent keeps bouncing back to the old backend, the fallback
+  may be firing: see
+  [Fallback keeps firing](../troubleshooting/fallback-keeps-firing.md).
 
 ## Related
 
 - [Backends and Tiers](../concepts/backends-and-tiers.md)
+- [Backend routing](../features/operations/backend-routing.md)
 - [Change which model handles X](change-which-model-handles-x.md)

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

@@ -14,22 +14,44 @@ summary: |
   through Adopt vs Migrate vs Split.
 section: use-an-existing-obsidian-vault
 tags:
-  - guide
+  - guides
   - wiki
   - obsidian
+  - knowledge
 status: stable
 ask_examples:
   - Can the wiki use my existing Obsidian vault?
   - How does the iCloud-sandbox fallback work?
   - What does Adopt vs Migrate mean?
+  - Why is Split greyed out?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
+keywords:
+  - external vault
+  - existing obsidian vault
+  - point at vault
+  - wiki external
+  - obsidian cli fallback
+  - adopt migrate split
 related:
   - features/wiki/overview
+  - features/wiki/workspaces
   - guides/build-your-wiki
   - guides/budget-and-cost-for-wiki
+  - guides/multiple-wikis-for-multiple-domains
   - troubleshooting/wiki-write-failed
+prerequisites:
+  - features/wiki/overview
+ui_anchors:
+  - /settings/wiki
+  - /wiki
+api_endpoints:
+  - GET /api/fs/probe
+  - POST /api/wiki/workspaces/probe
+  - POST /api/wiki/workspaces
+process_keys:
+  - wiki.compile
 ---
 
 # Use an Existing Obsidian Vault
@@ -44,9 +66,9 @@ vs Split**.
 
 ## Step 1 — Open Settings → Wiki
 
-Click **Setup → Settings → Wiki** in the dashboard sidebar (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:
+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:
 
 - **Enable Internal Workspace** — uses the daemon-owned root.
 - **Probe & Create External** — points at the path you choose with
@@ -62,10 +84,9 @@ to type the path by hand or worry about typos:
 - **Linux** — one of `zenity`, `kdialog`, or `yad` opens (whichever
   is installed on your system).
 
-If you prefer to paste a path you already have on the clipboard, the
-text field accepts that too — typing or pasting and clicking the
-folder button are equivalent. Aitne refuses paths that overlap
-`dataDir`, your primary vault, or the external Obsidian vault path so
+You can also type or paste a path directly — the text field and the
+folder button are equivalent. Aitne refuses any path that overlaps
+`dataDir`, your primary vault, or the external Obsidian vault path, so
 two writers never claim the same files.
 
 ### Inline validation banner
@@ -115,7 +136,7 @@ classifications comes back:
 |---|---|
 | **Adopt** | Keeps your existing schema and subdirectory layout verbatim. Aitne's wiki agent gets a workspace-specific addendum so it follows your conventions. |
 | **Migrate** | Flattens type-based subdirectories (`20_wiki/concepts/x.md → 20_wiki/x.md`) and renames legacy frontmatter keys (`topic → title`, `source_url → url`, …) to Aitne's Bases-era schema. Always writes a backup mirror under `90_meta/health/pre-migrate-<date>/` first. |
-| **Split** | Refuses to touch the existing vault and creates a sibling workspace instead. Available once multi-workspace lands. |
+| **Split** | Would leave the existing vault untouched and create a sibling workspace instead. **Not yet available** — the wizard greys it out and the import API rejects `decision: "split"` with `import_split_unsupported`; for now choose Adopt or Migrate. To run several wikis side by side, see [Multiple wikis for multiple domains](multiple-wikis-for-multiple-domains.md). |
 
 When you pick **Migrate**, the dashboard renders the plan — files
 that will be moved, frontmatter renames per file, slug collisions to