@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,287 @@
+---
+schema_version: 1
+slug: getting-started/04-first-day
+title: Your First Day
+id: first-day
+category: getting-started
+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.
+section: getting-started
+tags:
+  - core
+  - getting-started
+status: stable
+ask_examples:
+  - What should I do on my first day?
+  - How do I make the agent useful?
+  - How do I tell the agent about myself?
+  - Can I import my history from ChatGPT?
+  - 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
+created: 2026-04-25
+updated: 2026-04-27
+related:
+  - getting-started/02-first-steps
+  - getting-started/03-what-can-this-do
+  - guides/setup-wizard
+  - guides/import-knowledge-file
+  - features/routines/morning-routine
+  - features/routines/custom-routines
+  - features/memory-files/user-profile
+  - concepts/delegated-mode
+  - concepts/skills
+---
+
+# Your First Day
+
+## Goal
+
+Get the agent past cold start. Right after setup it knows almost
+nothing about you, sees none of the tools you actually use, and has
+no idea what work you want it to do for you. Day one is when you
+fix all three.
+
+## Prerequisites
+
+- Setup wizard complete (`/setup`).
+- At least one messaging app paired and a DM exchanged.
+
+## The shape of day one
+
+Three things make the difference between an agent that produces a
+sparse skeleton and one that actively helps you:
+
+1. **Teach it about you** — who you are, what matters, how to talk
+   to you.
+2. **Connect the tools you live in** — mail, calendar, notes, the
+   apps you check every day.
+3. **Show it the work you want done** — described in plain English,
+   then promoted to a routine once it works.
+
+Walk down the page in that order. Each step compounds — the agent's
+output on step 3 is only as good as how much you put in on steps 1
+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
+session. The faster those files have real content, the faster every
+reply gets useful.
+
+### Quickest path: just DM it
+
+Send 3–5 DMs that read like introductions to a new assistant:
+
+- *"My name is X. I lead Y at Z. I'm currently focused on A and B."*
+- *"I work in Asia/Tokyo and I sleep between 1am and 9am — never
+  ping me there."*
+- *"My partner is K, my closest collaborators are M and N — when you
+  see them on my calendar, treat the meeting as 1:1."*
+- *"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,
+primary timezone) are deferred for your explicit confirmation
+rather than auto-written.
+
+### Bootstrap from ChatGPT, Gemini, or anywhere else
+
+If you've been using ChatGPT or Gemini for a while, those services
+already hold a profile of you. Ask them to dump it as Markdown and
+upload the file under **Knowledge → Upload**.
+
+The full recipes — the exact prompt to paste into ChatGPT, the
+Google Takeout path for a comprehensive history, the format the
+upload accepts — live in
+[Import a Knowledge File](../guides/import-knowledge-file.md).
+
+You can run the recipe more than once: a small "work facts only"
+file first, verify the result under **Knowledge → Context Files**,
+then a separate file for personal facts. Duplicate facts on the
+second upload are skipped automatically.
+
+### Verify what landed
+
+Open **Knowledge → Context Files** and skim each `user/*.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
+as a conflict.
+
+→ [user/profile.md](../features/memory-files/user-profile.md) ·
+[Memory Model](../concepts/memory-model.md)
+
+---
+
+## 2. Connect the tools you actually use
+
+The agent only knows about apps you've connected. There are three
+ways in.
+
+### Built-in integrations
+
+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. |
+| [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. |
+
+Connect only what you use. Empty integrations are noise — skipping
+ones you don't need is the right default.
+
+### Anything else: connectors and MCP
+
+If your important app isn't in the list above — Linear, Asana, a
+private CRM, Google Drive, your bank's CSV exporter, anything —
+you have two ways to wire it in without waiting for first-party
+support.
+
+- **Backend connectors.** Sign into a connector that ships with your
+  backend (claude.ai for Claude, ChatGPT for Codex, Google for
+  Gemini) and let the agent reach the service through the backend's
+  native MCP tools. Same-backend calls go directly to the connector;
+  cross-backend calls proxy through the daemon. Flip a built-in
+  integration to **delegated** mode under **Connections → Mail /
+  Calendar** to use a connector instead of the daemon's own
+  credentials. Background:
+  [Delegated Mode](../concepts/delegated-mode.md).
+- **Custom MCP servers.** Anything that ships an MCP server (and the
+  catalog is exploding — Drive, Slack, Linear, Figma, Notion, Jira,
+  even your own scripts) can be attached under **Connections →
+  MCP**. Once attached, every backend that supports MCP can call its
+  tools as if they were built in.
+
+Picking between them: prefer a built-in if it exists, then a
+connector if your backend already ships one, then a custom MCP
+server.
+
+→ [Skills and MCP](../concepts/skills.md) ·
+[Delegated Mode](../concepts/delegated-mode.md)
+
+---
+
+## 3. Describe the work you want done
+
+You don't have to write any code. The fastest way to teach the
+agent a new task is to DM it the task in plain English. If the
+result is good, ask it to keep doing this on a schedule and you
+have a routine.
+
+### Start with one-off requests
+
+DM the agent things you'd send to a competent assistant:
+
+- *"Pull the last week of my Gmail and tell me which threads I owe a
+  reply on."*
+- *"For tomorrow's meeting with Acme, summarize what we last
+  discussed (search my Notion + my Obsidian vault) and any news from
+  Acme in the last month."*
+- *"Read today's Drive files in
+  drive.google.com/drive/folders/<id> and give me a 90-second
+  speaker outline for the afternoon presentation."*
+
+The agent will either do it or tell you what's missing — a
+connection it needs, a credential, a file it can't reach. Either
+way you've just learned what to fix next.
+
+### Promote a working request to a routine
+
+Once a request gives you a result you like, two paths make it
+recurring:
+
+- **Scheduled DMs** — *"Every weekday at 9:30 PT, do exactly that
+  and message me on WhatsApp."* The agent stores a recurring
+  schedule and runs the same prompt at the same cron. Best for
+  per-channel reminders and small recurring asks.
+- **Custom routines** — heavier, multi-step jobs that should write
+  to Markdown memory and DM you with a summary. Add one under
+  **Settings → Routines → Add custom routine**, or DM the agent the
+  cron + steps and ask it to save the routine. See
+  [Custom Routines](../features/routines/custom-routines.md) and
+  [Add a Custom Routine](../guides/add-a-custom-routine.md).
+
+### A worked example: a richer morning routine
+
+Suppose you want a morning routine that, every weekday at 7am:
+
+1. Creates a Notion daily-note for today's date and seeds it with a
+   TODO list pulled from your open tasks.
+2. For every meeting on today's calendar, researches the attendee's
+   company online and writes a one-paragraph brief into the same
+   Notion note.
+3. DMs the brief list to you on WhatsApp.
+4. Looks at the Drive folder you keep today's deck in, reads the
+   slides, and drafts speaker notes — saved under a `## Speaker
+   notes` heading in the same Notion daily note.
+
+Shortest path from zero to that:
+
+1. **Run each step as a one-off DM first.** "Create a Notion page
+   for today named …" / "List today's calendar events and research
+   each company …" / "Read the slides at … and draft speaker
+   notes." This makes the gaps obvious — Notion not connected?
+   Calendar not connected? WhatsApp not paired? Drive not reachable
+   through a connector or MCP server? Fix them as they show up.
+2. **Once each piece works standalone**, open **Settings → Routines
+   → Add custom routine**:
+   - Slug: `morning-deep-prep`
+   - Cron: `0 7 * * 1-5`
+   - Backend tier: `heavy`
+   - Max budget USD: `0.20`
+   - 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.
+
+→ [Custom Routines](../features/routines/custom-routines.md) ·
+[Add a Custom Routine](../guides/add-a-custom-routine.md)
+
+---
+
+## Verification
+
+By end of day one you should have:
+
+- At least 5–10 facts in `user/*.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
+  apps could have told the agent.
+- (Stretch) one custom routine or recurring schedule in **Settings
+  → Routines** that you'd be sad to lose.
+
+## If it fails
+
+- Replies never reference anything specific to you → `user/*.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 →
+  [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.
+
+## Related
+
+- [Import a Knowledge File](../guides/import-knowledge-file.md)
+- [Morning Routine](../features/routines/morning-routine.md)
+- [Custom Routines](../features/routines/custom-routines.md)
+- [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)

package/agent-assets/docs/glossary.md

@@ -0,0 +1,116 @@
+---
+schema_version: 1
+slug: glossary
+title: Glossary
+id: glossary
+category: glossary
+summary: |
+  Single flat term list for Aitne vocabulary. Cross-references
+  link to a single canonical anchor here so concept docs do not drift.
+status: stable
+ask_examples:
+  - What is a ProcessKey?
+  - What does heavy tier mean?
+  - What is the difference between light and heavy tiers?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - terminology
+  - vocabulary
+  - glossary
+related:
+  - concepts/agent-day
+  - features/routines/morning-routine
+---
+
+# Glossary
+
+A single flat list of Aitne vocabulary. Concept docs link to
+anchors here rather than redefining terms inline.
+
+## Agent Day
+
+The 24-hour window starting at the configured day-boundary hour (default
+04:00 local). See [Agent Day](concepts/agent-day.md) for the full rule
+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.
+
+## Backend Router
+
+The component that resolves a `ProcessKey` to a concrete `(backend,
+model, maxTurns, maxBudgetUsd)` binding at dispatch time. Lives in
+`packages/daemon/src/core/backends/backend-router.ts`. Routing reads
+`process_backend_config` (per-process pins) layered over
+`backend_global_defaults` (installation-wide defaults).
+
+## Citation Pill
+
+The clickable inline UI element rendered from a `[doc:slug#anchor]`
+token in a QA reply. Clicking scrolls the docs content pane to the
+matching anchor.
+
+## Day Boundary
+
+The hour-of-day at which the agent day rolls over. Configured via
+`dayBoundaryHour` (default `4`).
+
+## 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`.
+
+## 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.
+
+## ProcessKey
+
+The branded string identifier for a class of agent invocation, e.g.
+`routine.morning_routine`, `message.dm`, `dashboard.docs_qa`. Drives
+backend selection, skill manifest, agent profile, and task-flow
+template lookup. Defined in `packages/shared/src/process-key.ts`.
+
+## 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.
+
+## Skill
+
+A read-only or scoped tool surface defined as `agent-assets/skills/<slug>/SKILL.md`.
+Skills are the only way the agent reaches the daemon API or external
+services. The skill manifest per ProcessKey controls which skills load.
+
+## Slug
+
+The path-style canonical identity of a doc, e.g.
+`features/routines/morning-routine`. Used as the URL under `/docs/<slug>`,
+the row key in `fts_docs`, and the first half of every
+`[doc:slug#anchor]` citation.
+
+## 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.
+
+## Today.md
+
+The current agent day's main memory file under
+`~/.personal-agent/context/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.

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

@@ -0,0 +1,71 @@
+---
+schema_version: 1
+slug: guides/add-a-custom-routine
+title: Add a Custom Routine
+id: add-a-custom-routine
+category: guides
+summary: |
+  Define a new autonomous routine — slug, cron expression, tier, and
+  budget cap — via /settings/routines. The form writes a vault file at
+  routines/custom/<slug>.md.
+section: add-a-custom-routine
+tags:
+  - guide
+  - routines
+status: stable
+ask_examples:
+  - How do I add a custom routine?
+  - What can a custom routine do?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/routines/custom-routines
+  - concepts/routines
+---
+
+# Add a Custom Routine
+
+## Goal
+
+Make the agent fire a particular kind of work on a schedule you pick.
+
+## Prerequisites
+
+- Daemon running.
+
+## Steps
+
+1. Open `/settings/routines` (the older `/connections/routines` URL
+   redirects here).
+2. Click "Add custom routine".
+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.
+
+## Verification
+
+- Wait for the cron to fire; check Activity for the row tagged
+  `routine.custom.<slug>`.
+
+## 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`.
+
+## Related
+
+- [Custom Routines](../features/routines/custom-routines.md)

package/agent-assets/docs/guides/backup-and-restore.md

@@ -0,0 +1,54 @@
+---
+schema_version: 1
+slug: guides/backup-and-restore
+title: Backup and Restore
+id: backup-and-restore
+category: guides
+summary: |
+  Aitne's data lives in two places — the SQLite database and
+  the context Markdown files. Back both up and restoration is a tar
+  extract.
+section: backup-and-restore
+tags:
+  - guide
+  - operations
+status: stable
+ask_examples:
+  - How do I back up Aitne?
+  - Can I restore on a new machine?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - guides/reinstall-cleanly
+  - guides/migrate-machines
+---
+
+# Backup and Restore
+
+## Goal
+
+Capture all Aitne state in a tar that you can restore later.
+
+## Steps
+
+1. `pa stop`.
+2. `tar -czf personal-agent-backup-$(date +%F).tgz ~/.personal-agent/`.
+3. To restore: extract the tar to your home directory, then `pa start`.
+
+## Verification
+
+- Activity feed shows historical rows after restore.
+- Context files match the originals.
+
+## If It Fails
+
+- A schema-version mismatch: Aitne's policy is "clean
+  reinstall, no data migration" — if the restored DB is from an
+  older daemon version, drop the DB and re-seed from the context
+  files.
+
+## Related
+
+- [Reinstall Cleanly](reinstall-cleanly.md)
+- [Migrate Machines](migrate-machines.md)

package/agent-assets/docs/guides/change-which-model-handles-x.md

@@ -0,0 +1,47 @@
+---
+schema_version: 1
+slug: guides/change-which-model-handles-x
+title: Change Which Model Handles X
+id: change-which-model-handles-x
+aliases:
+  - per-process tier
+  - per-process model
+category: guides
+summary: |
+  Pin a specific ProcessKey to a non-default backend / tier — for
+  example, run morning routine on Sonnet to save Opus tokens.
+section: change-which-model-handles-x
+tags:
+  - guide
+  - backends
+status: stable
+ask_examples:
+  - How do I make my morning routine use Sonnet instead of Opus?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - guides/switch-default-backend
+  - concepts/backends-and-tiers
+---
+
+# Change Which Model Handles X
+
+## Goal
+
+Override the default tier or backend on a single ProcessKey.
+
+## Steps
+
+1. Open `/settings/models`.
+2. Find the ProcessKey row in the table.
+3. Pick its main backend and tier explicitly.
+4. Save.
+
+## Verification
+
+- The next fire of that ProcessKey shows the new model in Activity.
+
+## Related
+
+- [Switch the Default Backend](switch-default-backend.md)

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

@@ -0,0 +1,59 @@
+---
+schema_version: 1
+slug: guides/connect-a-new-mail-account
+title: Connect a New Mail Account
+id: connect-a-new-mail-account
+category: guides
+summary: |
+  Add a Gmail / Outlook / Yahoo / iCloud account to the mail
+  integration. Each provider has its own credential shape.
+section: connect-a-new-mail-account
+tags:
+  - guide
+  - mail
+status: stable
+ask_examples:
+  - How do I add another Gmail account?
+  - What mail providers does Aitne support?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/integrations/mail
+---
+
+# Connect a New Mail Account
+
+## Goal
+
+Wire a new mailbox into Aitne so the agent can read, label,
+and search it.
+
+## Prerequisites
+
+- The provider's OAuth or app password is available.
+
+## Steps
+
+1. Open `/connections/mail`.
+2. Click "Add account".
+3. Pick the provider kind. The supported set is `gmail`, `outlook`,
+   `yahoo`, `icloud` — the registry deliberately stops at hosted
+   providers, so a generic IMAP server is not a separate kind.
+4. Step through the OAuth flow (Gmail / Outlook) or paste the
+   provider-specific app password (Yahoo / iCloud).
+5. Save. The first poll runs within a minute.
+
+## Verification
+
+- The account row turns green on the auth-health card.
+- The mail count updates on `/connections/mail`.
+
+## If It Fails
+
+- OAuth that does not return: confirm the redirect URL matches the
+  daemon's API port (default 8321).
+
+## Related
+
+- [Mail](../features/integrations/mail.md)