@aitne-sh/aitne 0.1.8 → 0.1.9

package/agent-assets/docs/guides/import-knowledge-file.md

@@ -11,15 +11,13 @@ aliases:
 category: guides
 summary: |
   Upload a Markdown or text file of personal facts so the agent folds
-  it into your user/*.md Context Files. Includes step-by-step recipes
-  for exporting your existing profile out of ChatGPT and Gemini.
+  it into your identity/*.md Context Files. Includes step-by-step
+  recipes for exporting your existing profile out of ChatGPT and Gemini.
 section: import-knowledge-file
 tags:
-  - guide
+  - guides
   - knowledge
   - import
-  - chatgpt
-  - gemini
   - memory
 status: stable
 ask_examples:
@@ -29,15 +27,23 @@ ask_examples:
   - What format does the Knowledge upload accept?
 locale: en-US
 created: 2026-04-28
-updated: 2026-04-28
+updated: 2026-05-28
 ui_anchors:
   - /knowledge
 keywords:
   - import
   - chatgpt history
   - gemini history
-  - json import
   - knowledge
+  - profile
+process_keys:
+  - knowledge.import
+api_endpoints:
+  - POST /api/knowledge/import
+context_files:
+  - identity/profile.md
+  - identity/people.md
+  - journal/agent.md
 related:
   - concepts/memory-model
   - features/memory-files/user-profile
@@ -51,20 +57,21 @@ related:
 Bring a single Markdown (`.md`, `.markdown`) or plain-text (`.txt`)
 file you wrote elsewhere — a hand-written profile, an Obsidian or
 Notion export, or a summary you produced in ChatGPT / Gemini — into
-Aitne's `user/*.md` Context Files. The agent reads the file once and
-appends each fact verbatim into the right topic file. Existing bullets
-are never overwritten; identity-class facts are deferred for your
-explicit confirmation.
+Aitne's `identity/*.md` Context Files. The agent reads the file once
+and appends each fact verbatim into the right topic file. Existing
+bullets are never overwritten; identity-class facts are deferred for
+your explicit confirmation.
 
 ## Prerequisites
 
-- Initial setup is complete (`rules/management.md` saved). Pre-setup
+- Initial setup is complete (`policies/management.md` saved). Pre-setup
   imports are rejected with `409 setup_incomplete` because the
-  `user/*.md` skeleton has not been seeded yet.
-- At least one backend (Claude, Codex, or Gemini CLI) is authenticated
-  with a CLI binary on `PATH`.
-- The file is at most **64 KB after UTF-8 encoding** (Japanese / non-
-  ASCII characters take 3 bytes each — ≈ 21 K Japanese characters).
+  `identity/*.md` skeleton has not been seeded yet.
+- At least one backend (Claude, Codex, Gemini CLI, or OpenCode) is
+  authenticated and runnable — enabled, with its CLI binary on `PATH`.
+- The file is at most **64 KB after UTF-8 encoding** (non-ASCII
+  characters take up to 3 bytes each, so a Unicode-heavy file holds
+  fewer characters than its byte budget suggests).
 - The file does not contain private keys, API tokens, or credentials.
   The route rejects these at upload time and never persists them.
 
@@ -73,12 +80,12 @@ explicit confirmation.
 | Class of fact | Target Context File |
 |---|---|
 | Identity (legal name, primary timezone, primary language, DOB, primary email/phone) | **Deferred for confirmation** — surfaced in the closing journal entry; never auto-written. |
-| Relationships (family, partners, close friends) | `user/people.md` |
-| Work, employer, role, colleagues | `user/work.md` |
-| Skills, expertise, languages spoken | `user/expertise.md` |
-| Lifestyle, hobbies, preferences, health | `user/personal.md` |
-| Goals, aspirations, current focus | `user/goals.md` |
-| Anything else | `user/profile.md` under `## Misc` |
+| Relationships (family, partners, close friends) | `identity/people.md` |
+| Work, employer, role, colleagues | `identity/work.md` |
+| Skills, expertise, languages spoken | `identity/expertise.md` |
+| Lifestyle, hobbies, preferences, health | `identity/personal.md` |
+| Goals, aspirations, current focus | `identity/goals.md` |
+| Anything else | `identity/profile.md` under `## Misc` |
 
 Conflicts (a source bullet that contradicts an existing bullet) land in
 a `## Pending Conflicts` section on the affected file with the upload
@@ -98,7 +105,8 @@ date inline, so you can resolve them later without losing data.
    have at least one model available. Pick `Use default routing` to
    let the daemon's main backend run it.
 5. Click **Import**. The form returns immediately with a 202 + trace id
-   — the heavy-tier session runs in the background.
+   — the import session (`knowledge.import`, medium tier) runs in the
+   background.
 6. Watch progress under the linked **Activity** view (filtered by the
    trace id) and review the resulting bullets under
    `/knowledge?tab=context-files` once the run finishes.
@@ -111,11 +119,11 @@ date inline, so you can resolve them later without losing data.
   session completes (typically 30 s to 2 min depending on file size
   and backend).
 - The agent appends a single `## YYYY-MM-DD knowledge import` block to
-  `agent/journal.md` summarising the run — counts of facts written /
+  `journal/agent.md` summarising the run — counts of facts written /
   skipped, pending conflicts, and identity-class facts awaiting
   confirmation.
-- Open each affected `user/*.md` file under Context Files. New bullets
-  should be verbatim copies of lines in your source file.
+- Open each affected `identity/*.md` file under Context Files. New
+  bullets should be verbatim copies of lines in your source file.
 
 ## If It Fails
 
@@ -130,16 +138,18 @@ date inline, so you can resolve them later without losing data.
 - **`409 setup_incomplete`** — finish the setup wizard first
   (`/setup`).
 - **`No authenticated backends`** in the Execution agent dropdown —
-  set up a backend under Connections → Backends, then return.
+  authenticate a backend under Settings → Models (`/settings/models`),
+  then return. The dropdown lists only backends that are enabled and
+  whose CLI binary is on `PATH`.
 
 ---
 
-# Recipe: Export your profile from ChatGPT
+## Recipe: Export your profile from ChatGPT
 
 OpenAI does not ship a one-click "export as Markdown" button, but the
 following two paths produce a file that uploads cleanly.
 
-## Recommended: ask ChatGPT to write it for you (≈ 2 min)
+### Recommended: ask ChatGPT to write it for you (≈ 2 min)
 
 Works against ChatGPT's *Memory* feature — the model already holds a
 list of personal facts about you. This procedure asks it to dump them
@@ -181,7 +191,7 @@ in the exact format the upload expects.
    imported — the upload writes facts verbatim.
 5. Upload via Knowledge → Upload, with **Source** = `Other`.
 
-## Comprehensive: official Data Export → convert (≈ 30 min, large)
+### Comprehensive: official Data Export → convert (≈ 30 min, large)
 
 Use this when you want to seed Aitne with the *complete* history.
 Output is bulky and requires manual filtering.
@@ -204,7 +214,7 @@ Output is bulky and requires manual filtering.
    upload one at a time.
 5. Upload via Knowledge → Upload, with **Source** = `Other`.
 
-## Bonus: copy your saved memory list
+### Bonus: copy your saved memory list
 
 ChatGPT's Memory page exposes the structured fact list directly.
 
@@ -216,13 +226,13 @@ ChatGPT's Memory page exposes the structured fact list directly.
 
 ---
 
-# Recipe: Export your profile from Gemini
+## Recipe: Export your profile from Gemini
 
 Google Gemini's options mirror ChatGPT's at a high level — no native
 Markdown export, but the in-conversation prompt method works the same
 way, and Google Takeout produces a comprehensive archive.
 
-## Recommended: ask Gemini to write it for you (≈ 2 min)
+### Recommended: ask Gemini to write it for you (≈ 2 min)
 
 1. Open <https://gemini.google.com> and start a **new conversation**.
    The model uses **Saved info** (the Gemini equivalent of ChatGPT's
@@ -233,7 +243,7 @@ way, and Google Takeout produces a comprehensive archive.
 3. Copy the response into `gemini-profile.md`, skim, and upload via
    Knowledge → Upload with **Source** = `Other`.
 
-## Comprehensive: Google Takeout (≈ 1 hr, archive may take longer)
+### Comprehensive: Google Takeout (≈ 1 hr, archive may take longer)
 
 1. Visit <https://takeout.google.com>.
 2. **Deselect all**, then check **Gemini Apps Activity** (and
@@ -248,7 +258,7 @@ way, and Google Takeout produces a comprehensive archive.
    them under the right H2 headings, save as `gemini-export.md`,
    keep under 64 KB, upload.
 
-## Bonus: copy your Saved info list
+### Bonus: copy your Saved info list
 
 1. Open Gemini → click your avatar / settings → **Saved info**.
 2. Copy each saved row into a new `gemini-saved-info.md` under the
@@ -265,11 +275,11 @@ way, and Google Takeout produces a comprehensive archive.
   for personal facts. This is easier to review than one large mixed
   upload.
 - **Edit before you upload.** The agent writes verbatim. Anything in
-  the file *will* land in `user/*.md` (after dedup and identity-class
-  deferral). Trim aggressively.
+  the file *will* land in `identity/*.md` (after dedup and
+  identity-class deferral). Trim aggressively.
 - **Identity is special.** Even if your file says
   `- Name: <Your Name>`, the agent will *not* write it to
-  `user/profile.md`. It surfaces in the journal entry instead, where
+  `identity/profile.md`. It surfaces in the journal entry instead, where
   you can confirm and accept it via the dashboard.
 - **Conflicts are flagged, not merged.** If your file contradicts an
   existing bullet, the agent appends the new bullet to a
@@ -282,5 +292,5 @@ way, and Google Takeout produces a comprehensive archive.
 ## Related
 
 - [Memory Model](../concepts/memory-model.md)
-- [user/profile.md](../features/memory-files/user-profile.md)
+- [identity/profile.md](../features/memory-files/user-profile.md)
 - [First Day](../getting-started/04-first-day.md)

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

@@ -12,11 +12,11 @@ aliases:
 category: guides
 summary: |
   Install Aitne via the npm package (or clone the repo for development),
-  start the daemon and dashboard, and open the dashboard at :3000.
+  start the daemon and dashboard, and open the dashboard at :8322.
 section: install-and-run
 tags:
   - core
-  - guide
+  - guides
   - getting-started
   - install
   - setup
@@ -29,12 +29,12 @@ ask_examples:
   - How do I install the aitne npm package?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - install
   - first run
   - pnpm
-  - npm install aitne
+  - npm install -g @aitne-sh/aitne
   - aitne start
   - PA_DATA_DIR
   - node 22
@@ -67,31 +67,60 @@ through the setup wizard.
   CLI, or Gemini CLI) installed on `PATH`.
 - ~200 MB of disk for the daemon's local state.
 
-## Steps
+## Install
 
-1. `git clone <repo> personal_agent && cd personal_agent`
-2. `pnpm install`
-3. `pnpm start` — builds (if stale) and launches daemon + dashboard
-   in the background.
-4. Open `http://localhost:3000` and follow the setup wizard.
+Pick one path. Most people want the npm package; clone the repo only if
+you intend to develop Aitne itself.
+
+### Option A — npm package (recommended)
+
+```bash
+npm install -g @aitne-sh/aitne
+aitne start
+```
+
+`aitne start` launches the daemon and dashboard in the background. The
+package ships prebuilt, so there is no build step.
+
+### Option B — clone the repo (development)
+
+```bash
+git clone <repo> personal_agent && cd personal_agent
+pnpm install
+pnpm start
+```
+
+`pnpm start` builds first when the source is stale (mtime check against
+`.buildstamp`), then launches the daemon + dashboard detached. The
+`pnpm <cmd>` scripts are thin aliases that forward to
+`node bin/aitne.mjs <cmd>`.
+
+### Then, for both paths
+
+Open `http://localhost:8322` and follow the setup wizard.
 
 ## Verification
 
-- `pnpm status` shows two PIDs (daemon + dashboard) and a green health
-  pill.
-- `~/.personal-agent/` has been created with `data/personal_agent.db`,
-  `context/`, and the log directory.
+- `aitne status` (or `pnpm status` from a clone) shows two PIDs (daemon
+  + dashboard), uptime, connected backends, and a green health pill.
+- `~/.personal-agent/` has been created, containing
+  `data/personal_agent.db`, `context/`, and `logs/`.
 
 ## If It Fails
 
-- A port conflict — set `PA_API_PORT` (default 8321) or
-  `PA_DASHBOARD_PORT` (default 3000).
-- Build errors during `pnpm start`: run `pnpm clean && pnpm build`
-  for verbose output.
+- **Port conflict** — set `PA_API_PORT` (default `8321`) or
+  `PA_DASHBOARD_PORT` (default `8322`) before starting.
+- **Diagnose the install** — run `aitne doctor` (`pnpm doctor` from a
+  clone). It checks Node, ports, keychain, CLI binaries, and native
+  bindings, and exits non-zero on any hard failure.
+- **Build errors (clone only)** — rebuild verbosely with `pnpm build`.
+  If that still fails, `pnpm clean` removes `node_modules`,
+  `.buildstamp`, and Turbo's cache, after which you must re-run
+  `pnpm install` before building again.
 
 ## Related
 
-- [CLI Commands](../reference/cli-commands.md) — full `pa` command
+- [CLI Commands](../reference/cli-commands.md) — full `aitne` command
   list and environment overrides.
 - [Setup Wizard](setup-wizard.md) — what each wizard step does.
 - [Reinstall Cleanly](reinstall-cleanly.md) — wipe and start over.

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

@@ -16,7 +16,7 @@ summary: |
   approval before promoting them.
 section: maintain-wiki-health
 tags:
-  - guide
+  - guides
   - wiki
   - health
 status: stable
@@ -28,21 +28,33 @@ ask_examples:
   - What is a taxonomy candidate?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
   - wiki health
   - wiki lint
   - wiki maintenance
   - wiki freshness
   - orphan notes
+  - taxonomy candidates
 related:
   - features/wiki/overview
   - features/wiki/commands
+  - features/wiki/cost-and-approval
   - guides/explore-with-trace-and-connect
+process_keys:
+  - wiki.lint
+  - wiki.compile
+  - wiki.ingest_url
+  - wiki.ask
+  - wiki.trace
+api_endpoints:
+  - /api/wiki/:workspace/files/:path{.+}
+  - /api/wiki/:workspace/health
 ui_anchors:
   - /wiki
   - /wiki/timeline
   - /settings/wiki
+  - /settings/wiki/timeline
 ---
 
 # Maintain Wiki Health
@@ -55,9 +67,10 @@ notes itself.
 
 ## When to Run
 
-`!lint` is cheap (Sonnet medium tier, default $0.50 envelope) and
-non-destructive. Run it whenever you want a snapshot of wiki
-health. A practical cadence:
+`!lint` runs on the `wiki.lint` process key (medium tier — Sonnet
+by default, $1.00 budget envelope) and never changes your notes.
+Run it whenever you want a snapshot of wiki health. A practical
+cadence:
 
 - **Weekly**, after a busy ingest week, to catch orphans early.
 - **Before promoting a candidate** to the taxonomy or graduating
@@ -104,9 +117,8 @@ makes the change visible.
 
 Open **My Life → Wiki → Timeline & health** (`/wiki/timeline`). The
 page is also reachable from a button at the top of `/settings/wiki`,
-and the legacy `/settings/wiki/timeline` URL redirects here so old
-bookmarks still work. The most-recent report is parsed and rendered
-with:
+and the same view is mirrored under `/settings/wiki/timeline`. The
+most-recent report is parsed and rendered with:
 
 - A coloured date badge.
 - The `## Summary` bullets.
@@ -136,6 +148,18 @@ item:
   update `90_meta/taxonomy.md` manually so future ingests pick the
   right name.
 
+For example, if the report flags `formal-methods.md` as an orphan,
+you might first ask the agent whether it still matters, then either
+link it or archive it:
+
+```
+!ask Is formal-methods still relevant, or has it been folded into another note?
+```
+
+If the answer says it's superseded, archive the note; otherwise add
+a `[[formal-methods]]` link from a related article and re-run
+`!compile` so the index picks it up.
+
 ## Taxonomy Candidates
 
 When `!lint` finds a concept appearing repeatedly that isn't yet
@@ -167,8 +191,9 @@ chokepoint, so:
 
 - It's visible to `!ask` (you can literally ask "what did the last
   lint find?").
-- The DM read-only surface (`/api/wiki/.../files/90_meta/health/...`)
-  serves it back to a DM-agent for follow-up questions.
+- The DM read-only surface
+  (`GET /api/wiki/:workspace/files/90_meta/health/<date>.md`) serves
+  it back to a DM-agent for follow-up questions.
 - Internal-mode workspaces snapshot the previous version into
   `.snapshots/` before each rewrite; external-mode relies on your
   git or cloud sync.

package/agent-assets/docs/guides/migrate-machines.md

@@ -10,19 +10,22 @@ aliases:
   - move install
 category: guides
 summary: |
-  Move a Aitne install to a new machine — install the daemon,
-  copy the context directory, re-pair messaging apps.
+  Move an Aitne install to a new machine — install the daemon, copy
+  the data directory, re-pair messaging apps. The DB carries cleanly
+  because schema migrations auto-forward at boot.
 section: migrate-machines
 tags:
-  - guide
+  - guides
   - operations
   - migration
+  - backup
 status: stable
 ask_examples:
   - Can I move Aitne to a new laptop?
+  - Will my DB still work after upgrading on the new machine?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - migrate
   - move install
@@ -36,29 +39,82 @@ related:
 
 # Migrate Machines
 
-## Goal
-
 Carry your Aitne identity to a new machine without losing
-context-file history.
+context-file history or activity logs.
+
+## What Moves and What Doesn't
+
+| Carries cleanly | Re-do on the new machine |
+|---|---|
+| `~/.personal-agent/context/` (Markdown memory) | OS-keychain secrets (Anthropic / OpenAI / Google API keys) |
+| `~/.personal-agent/data/personal_agent.db` (sessions, actions, observations, FTS) | Messaging pairing tokens (Slack / Telegram / Discord / WhatsApp) |
+| `~/.personal-agent/logs/` (optional — for reference) | Integration OAuth grants (Gmail / Google Calendar / Notion) |
+
+The DB carries cleanly even across daemon versions: at boot, Aitne
+runs forward-only migrations from `packages/daemon/src/db/migrations.ts`
+that bring older schemas up to the current shape. As long as you're
+upgrading (not downgrading), the same DB works.
 
 ## Steps
 
-1. On the old machine: `aitne stop`.
-2. Copy `~/.personal-agent/context/` to the new machine.
-3. On the new machine: install per [Install and Run](install-and-run.md).
-4. Optionally copy `data/personal_agent.db` (skip if upgrading daemon versions).
-5. Re-pair messaging apps and re-authorize integrations.
+1. **On the old machine:** stop the daemon.
+   ```bash
+   aitne stop
+   ```
+2. **Copy the data directory** to the new machine — context plus DB.
+   ```bash
+   rsync -av ~/.personal-agent/ user@new-host:~/.personal-agent/
+   ```
+   (Or rsync just `context/` and `data/` if you want to skip logs.)
+3. **On the new machine:** install per [Install and Run](install-and-run.md).
+4. **Re-register secrets and re-pair messaging** through the dashboard:
+   - Re-register each backend's API key, or re-run its CLI auth flow for
+     the subscription path: `claude auth login`, `codex login`, or for
+     Gemini run `gemini` and choose **Sign in with Google**.
+   - Walk the setup wizard's messaging pairing steps for each app you
+     had paired.
+   - Re-authorize each integration's OAuth grant (Gmail / Calendar /
+     Notion are the common ones).
+5. Start the daemon.
+   ```bash
+   aitne start
+   ```
+
+On first boot the migration runner brings the carried DB up to the
+new daemon's schema. Check the daemon log if you want to see exactly
+which migrations applied:
+
+```bash
+aitne logs -n 200 | grep -i migration
+```
 
-## Verification
+## Verify
 
-- Context files match.
-- Routines fire on the new machine's schedule.
+- `aitne status` reports today's action count and spend, the connected
+  platforms, and uptime — confirming the daemon booted against the
+  carried DB.
+- The dashboard's activity feed contains your historical rows; `aitne
+  audit --since 30d` lists the same past actions you had on the old
+  machine.
+- Routines fire on the new machine's local schedule (timezone follows
+  the OS).
 
 ## If It Fails
 
-- OS-keychain credentials don't move automatically — re-authorize
-  each backend on the new machine.
+- **OS-keychain credentials don't move automatically** — Step 4 is the
+  fix.
+- **The daemon won't start with a SQLite error.** Read
+  `aitne logs -n 200` for the failing migration. If the DB is genuinely
+  corrupt, the last resort is
+  [Reinstall Cleanly](reinstall-cleanly.md) — but context files survive
+  that, so you only lose action history.
+- **You downgraded the daemon by accident.** Migrations are forward-
+  only; reinstall the newer version (`npm i -g @aitne-sh/aitne`) and
+  retry.
 
 ## Related
 
-- [Backup and Restore](backup-and-restore.md)
+- [Backup and Restore](backup-and-restore.md) — the source for the data
+  you carry.
+- [Install and Run](install-and-run.md) — Step 3 in detail.
+- [Schema Migration](../glossary.md#schema-migration)