@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/docs/concepts/memory-model.md

@@ -15,10 +15,8 @@ summary: |
   the agent reads and rewrites about you.
 section: memory
 tags:
-  - core
   - memory
   - knowledge
-  - context
   - safety
 status: stable
 ask_examples:
@@ -29,7 +27,7 @@ ask_examples:
   - How does the daemon prevent the agent from writing to disk directly?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-11
+updated: 2026-07-01
 keywords:
   - context
   - markdown
@@ -78,36 +76,39 @@ api_endpoints:
 
 ## TL;DR
 
-Aitne treats Markdown files in `~/.personal-agent/context/`
+Aitne uses Markdown files in `~/.personal-agent/context/`
 as its long-term memory and SQLite
-(`~/.personal-agent/data/personal_agent.db`) as session-scoped state.
-Anything you want the agent to remember between runs lives in an MD
-file you can read, diff, and edit by hand. The vault is partitioned
-into six authority classes — `identity/`, `state/`, `plans/`, `journal/`,
-`knowledge/`, and `policies/` — each carrying its own authority and
-lifecycle contract. See [Knowledge Layout](../reference/knowledge-layout.md)
-for the canonical map.
+(`~/.personal-agent/data/personal_agent.db`) for short-lived state that
+only matters within a single run. Anything you want the agent to
+remember between runs lives in an MD file you can open, diff, and edit
+by hand. The vault (the folder that holds these files) is split into six
+top-level folders — `identity/`, `state/`, `plans/`, `journal/`,
+`knowledge/`, and `policies/` — and each one has its own rules about who
+may change it and how long its contents last. See
+[Knowledge Layout](../reference/knowledge-layout.md) for the full map.
 
 ## Why This Concept Exists
 
-A long-running agent that stores meaning inside an opaque database
-gives you no recourse when something goes wrong. Aitne's design
-is the opposite: every fact the agent recalls about you, your projects,
-your day, or its own past behavior sits in a `.md` file you can open in
-any editor. Auditing, backups, and recovery are all "use git or rsync".
+If a long-running agent hides everything it knows inside an opaque
+database, you have no way to check or fix it when something goes wrong.
+Aitne does the opposite: every fact the agent recalls about you, your
+projects, your day, or its own past behavior sits in a `.md` file you
+can open in any editor. Auditing, backing up, and restoring all come
+down to ordinary tools — git or rsync.
 
 SQLite is reserved for the things you do not want the agent rewriting
-on every turn — session logs, action audit trails, observations, FTS
-indexes, and configuration.
+on every turn — session logs, action audit trails, observations,
+full-text search (FTS) indexes, and configuration.
 
 ## Definitions
 
 - **Context file**: any `.md` file under `~/.personal-agent/context/`.
 - **Authoritative memory**: the union of context files; SQLite never
   stores facts the agent treats as canonical truth about the operator.
-- **`AgentWriteTracker`**: the daemon component that distinguishes an
-  agent-originated context-file write from a human edit so the
-  Obsidian/Git observers do not loop on the agent's own output.
+- **`AgentWriteTracker`**: the daemon component that tells an
+  agent-made context-file write apart from a human edit, so the
+  Obsidian/Git observers (the watchers that notice file changes) do not
+  loop on the agent's own output.
 - **Context API**: the daemon's `/api/context/*` endpoint, the **only**
   legal write path. The agent does not have direct `Edit` / `Write`
   permissions on the filesystem; it must go through the daemon.
@@ -115,9 +116,9 @@ indexes, and configuration.
 ## How the Agent Writes
 
 The agent has no `Edit` or `Write` tool. To change a context file it
-calls the daemon over HTTP, and every write funnels through one
-endpoint family so the daemon can validate, hold locks, and snapshot a
-backup before touching disk. Paths are class-prefixed
+calls the daemon over HTTP, and every write goes through one small set
+of endpoints so the daemon can validate the request, hold locks, and
+save a backup snapshot before it touches disk. Paths are class-prefixed
 (`/api/context/<class>/<path>`):
 
 ```bash

package/agent-assets/docs/concepts/observations.md

@@ -16,7 +16,6 @@ summary: |
   notification. This pivot was the Phase 9 polling change.
 section: observations
 tags:
-  - core
   - observations
   - polling
   - integrations
@@ -29,7 +28,7 @@ ask_examples:
   - Where does the routine pre-pass write observations?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - observation
   - observations
@@ -50,6 +49,10 @@ related:
   - concepts/routines
   - features/integrations/git
   - features/integrations/obsidian
+  - features/integrations/calendar
+  - features/integrations/github
+  - features/integrations/notion
+  - features/integrations/browser-history
 ui_anchors:
   - /activity
 process_keys:
@@ -72,29 +75,30 @@ context_files:
 
 ## TL;DR
 
-Polling integrations (Obsidian, Git, Notion, Calendar) **do not emit
-events** when they detect changes. They write observation rows to
-SQLite. A single `routine.activity_scan` consumes the queue and decides
-what is worth surfacing.
+Polling integrations (Obsidian, Git, Notion, Calendar) watch for
+changes on a schedule. When they find one, they **do not emit an
+event** or message you — they write an *observation* row into SQLite.
+A single `routine.activity_scan` reads that queue and decides what is
+worth surfacing.
 
-Since 2026-05, observations have a **second writer**: every main
-routine (`routine.morning_routine`, `routine.today_refresh`,
+Since 2026-05, observations have a **second writer**. Before each main
+routine runs (`routine.morning_routine`, `routine.today_refresh`,
 `routine.activity_scan`, `routine.evening_review`,
-`routine.weekly_review`) is preceded by a lite-tier
-`routine.fetch_window` pre-pass that fetches mail / calendar / Notion
-windows and POSTs them to `/api/observations/batch`.
-(`routine.monthly_review` has no pre-pass window.) The main routine
-then reads them via the same `pending=true` queue that the polling
-path feeds. Observation rows look identical regardless of which writer
-produced them — the distinction is invisible to downstream consumers.
+`routine.weekly_review`), a lite-tier `routine.fetch_window` pre-pass
+fetches mail / calendar / Notion windows and POSTs them to
+`/api/observations/batch`. (`routine.monthly_review` has no pre-pass
+window.) The main routine then reads them through the same
+`pending=true` queue that the polling path feeds. The rows look
+identical no matter which writer produced them, so downstream consumers
+cannot tell them apart.
 
 ## Why This Concept Exists
 
 Per-change notifications turned every routine commit, every saved
-note, every tiny calendar tweak into a paging event. The Phase 9
-pivot moved the agent away from that: changes accumulate, and once an
-hour the agent looks at the bag and decides whether the pattern adds
-up to something the operator should hear about.
+note, every tiny calendar tweak into an interruption. The Phase 9
+pivot moved the agent away from that: changes pile up quietly, and
+once an hour the agent reviews the whole batch and decides whether the
+pattern adds up to something you should hear about.
 
 ## Definitions
 
@@ -149,4 +153,8 @@ Both write rows of the same shape; the consumer reads the merged queue.
 - [Process Keys](./process-keys.md)
 - [Routines](./routines.md)
 - [Git](../features/integrations/git.md)
+- [GitHub](../features/integrations/github.md)
 - [Obsidian](../features/integrations/obsidian.md)
+- [Notion](../features/integrations/notion.md)
+- [Calendar](../features/integrations/calendar.md)
+- [Browser History](../features/integrations/browser-history.md)

package/agent-assets/docs/concepts/process-keys.md

@@ -14,10 +14,8 @@ summary: |
   to a backend + tier binding; the manifest map resolves it to skills.
 section: process-keys
 tags:
-  - core
-  - dispatch
-  - backends
   - routing
+  - backends
 status: stable
 ask_examples:
   - What is a ProcessKey?
@@ -26,7 +24,7 @@ ask_examples:
   - What is the difference between configurable and fixed ProcessKeys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - process key
   - ProcessKey
@@ -70,36 +68,37 @@ ui_anchors:
 
 ## TL;DR
 
-A ProcessKey is a string like `routine.morning_routine` or `message.dm`
-that identifies one class of agent work. Every routine, every reactive
-event, every dashboard action is tagged with one. The router uses it
-to pick the backend; the skills compiler uses it to pick the tools.
+A ProcessKey is a short string like `routine.morning_routine` or
+`message.dm` that names one class of agent work. Every routine, every
+event the agent reacts to, and every dashboard action carries one. The
+router uses it to pick the backend; the skills compiler uses it to pick
+the tools.
 
 ## Why This Concept Exists
 
-Without a stable identifier per task class, "the morning routine" and
-"a DM" would have to be hand-distinguished everywhere they were
-treated differently — pricing, retention, tool scope, auditability.
-The ProcessKey is the single coupling that ties dispatch to all of
-those subsystems.
+Without a stable name for each class of task, "the morning routine" and
+"a DM" would have to be told apart by hand everywhere they behave
+differently — pricing, retention, tool scope, and auditing. The
+ProcessKey is the one label that connects dispatch to all of those
+subsystems.
 
 ## Definitions
 
-- **CONFIGURABLE_PROCESS_KEYS**: the set the operator can override per
+- **CONFIGURABLE_PROCESS_KEYS**: the keys an operator can override per
   backend on `/settings/models`. The rest (`delegated_task`, `setup`,
-  `schedule.approaching`, …) use fixed defaults and are not surfaced
+  `schedule.approaching`, …) use fixed defaults and do not appear
   there.
-- **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events
-  (`message.dm`, `message.mention`, `dashboard.chat`,
-  `dashboard.docs_qa`, `setup`, `knowledge.import`). Everything else is
-  autonomous.
-- **DEFAULT_PROCESS_TIERS**: the per-key default model size — `lite`
-  (Haiku-class), `medium` (Sonnet-class), or `high` (Opus-class).
-  Unknown keys default to `medium`.
-- **TIER_LOCKED_PROCESS_KEYS**: keys whose tier is hard-locked and
-  cannot be overridden by an operator pin. Today this is just
-  `dashboard.docs_qa`, locked to `medium`.
-- **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to the skill manifest
+- **REACTIVE_PROCESS_KEYS**: keys tied to events that happen while you
+  interact with the agent (`message.dm`, `message.mention`,
+  `dashboard.chat`, `dashboard.docs_qa`, `setup`, `knowledge.import`).
+  Everything else runs on its own (autonomous).
+- **DEFAULT_PROCESS_TIERS**: the default model size for each key —
+  `lite` (Haiku-class), `medium` (Sonnet-class), or `high`
+  (Opus-class). Unknown keys default to `medium`.
+- **TIER_LOCKED_PROCESS_KEYS**: keys whose tier is hard-locked, so an
+  operator pin cannot change it. Today this is just `dashboard.docs_qa`,
+  locked to `medium`.
+- **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to its skill manifest
   key, so the skills compiler can pick the right tool set.
 
 ## Concrete Examples

package/agent-assets/docs/concepts/routines.md

@@ -17,7 +17,6 @@ summary: |
   retro, plus any recurring user Agents you define.
 section: routines
 tags:
-  - core
   - routines
   - autonomous
   - scheduler
@@ -30,7 +29,7 @@ ask_examples:
   - Which routine uses the high tier by default?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - routine
   - routines
@@ -78,24 +77,26 @@ config_keys:
 
 ## TL;DR
 
-A routine is a unit of agent work that runs on a schedule, not in
-response to a message. The morning routine fires once per agent day at
-`dayBoundaryHour`; the evening review (18:00 daily), weekly review
-(Friday 19:00), and optional monthly review fire on fixed schedules in
-code; the activity scan coalesces accumulated observations on a
-configurable cadence.
+A routine is a piece of agent work that runs on a schedule instead of
+in reply to a message. The morning routine fires once per agent day —
+the 24-hour window that starts at `dayBoundaryHour` (04:00 by default).
+The evening review (18:00 daily), weekly review (Friday 19:00), and
+optional monthly review run on fixed schedules set in code. The
+activity scan gathers up the observations that have piled up, on a
+cadence you can configure.
 
 ## Why This Concept Exists
 
-The premise of Aitne is that the operator does not want to
-"prompt" their assistant every time. Routines are how the agent shows
-up without being asked: it builds today, it logs to the journal, it
-files a retro for the week. They are the proactive surface.
+The whole idea of Aitne is that you should not have to "prompt" your
+assistant every time. Routines are how the agent shows up without being
+asked: it builds the day's plan, it writes to the journal, and it files
+a weekly retrospective. This is the proactive side of the agent.
 
 Each routine is a single ProcessKey — `routine.morning_routine`,
-`routine.activity_scan`, `routine.weekly_review`, etc. The dispatcher
-treats them as just another event class; the only difference from a
-DM is who fired the event.
+`routine.activity_scan`, `routine.weekly_review`, and so on. The
+dispatcher treats a routine as just another kind of event; the only
+thing that sets it apart from a direct message (DM) is what triggered
+it — a schedule rather than you.
 
 ## Definitions
 
@@ -128,8 +129,8 @@ DM is who fired the event.
 - **Pre-pass fetcher**: each main routine that needs fresh mail /
   calendar / Notion data is preceded by a lite-tier
   `routine.fetch_window` session that fetches the relevant window and
-  POSTs observations. The main routine then consumes the resulting
-  `<fetch_report>` block plus pending observations instead of hitting
+  POSTs observations. The main routine then reads the resulting
+  `<fetch_report>` block plus pending observations instead of calling
   upstream APIs itself — a cost-savings split introduced in 2026-05.
 
 ## Concrete Examples

package/agent-assets/docs/concepts/safety-and-execution.md

@@ -17,7 +17,6 @@ summary: |
   which actions are categorically refused.
 section: safety
 tags:
-  - core
   - safety
   - operations
   - backends
@@ -28,7 +27,7 @@ ask_examples:
   - How do I see what tools the agent is allowed to use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - safety
   - safe mode
@@ -63,7 +62,9 @@ Three layers gate what the agent can do:
 
 1. **Skill `allowed-tools`** — the visible toolset for that session.
 2. **Execution mode** — Safe (strict permission checks, sandboxes)
-   or Allow (SDK bypass, sandbox off). Set per-backend.
+   or Allow (the SDK's permission prompts are bypassed, sandbox off).
+   Set per backend (the underlying agent engine — Claude, Codex,
+   Gemini, or OpenCode).
 3. **Always-disallowed** — a hard floor. Recursive deletes, `sudo`,
    secret-file reads / writes are denied unconditionally regardless
    of mode, and neither a skill nor Allow mode can widen past it.
@@ -87,29 +88,31 @@ disallowed-tools floor.
   permission block.
 - **Allow mode**: the looser posture. SDK bypass, sandbox off, minimal
   TOML. The absolute-block layer still holds in Allow mode on Claude,
-  Gemini, and OpenCode — Codex is the documented exception: its Allow
-  mode is a binary sandbox-off switch with no hook layer the daemon can
+  Gemini, and OpenCode. Codex is the documented exception. Its Allow
+  mode is a binary sandbox-off switch, with no hook layer the daemon can
   attach the block list to, so the dashboard warns you before you flip
-  it. Set independently per backend, so one backend can run Allow while
-  the others stay Safe.
+  it. You set the mode separately for each backend, so one backend can
+  run Allow while the others stay Safe.
 - **Absolute block**: the unconditional layer. `ALWAYS_DISALLOWED_TOOLS`
   in `src/safety/always-disallowed.ts`. Cannot be widened by skills,
   by config, or by allow-mode.
 - **Risk tier**: every daemon-API operation carries one of three tiers —
   `autonomous`, `read_sensitive`, or `approve`. *Autonomous* runs without a
-  prompt. *Read-sensitive* reads (email, calendar, notes, context files) are
-  the same blast radius as autonomous but are gated by a read token when
-  `enforceReadToken` is on. *Approve* is blocked until you confirm with a
-  bearer token (the dashboard does this when you click Approve). There is no
-  separate "notify" tier — that behaviour now lives in the skill prompts: for
-  potentially destructive actions the agent DMs you first, then proceeds. See
-  [Safety model](safety-model.md) for the full taxonomy.
+  prompt. *Read-sensitive* reads (email, calendar, notes, context files) can
+  do no more harm than autonomous ones, but they are gated by a read token
+  when `enforceReadToken` is on. *Approve* actions are blocked until you
+  confirm with a bearer token (the dashboard does this when you click
+  Approve). There is no separate "notify" tier — that behaviour now lives in
+  the skill prompts: before a potentially destructive action the agent DMs
+  you first, then proceeds. See [Safety model](safety-model.md) for the full
+  taxonomy.
 
 ## Concrete Examples
 
-The daemon API is the agent's only write path, so most of its own writes are
-`autonomous` (the memory chokepoint validates and snapshots them). The
-absolute-block layer and Approve tier are where the agent is actually stopped.
+The daemon API is the agent's only write path, so most of the writes it makes
+are `autonomous` — a single choke point validates and snapshots each one. The
+places the agent is actually stopped are the absolute-block layer and the
+Approve tier.
 
 | Action | What gates it |
 |---|---|

package/agent-assets/docs/concepts/safety-model.md

@@ -22,7 +22,6 @@ summary: |
   unchanged.)
 section: safety
 tags:
-  - core
   - safety
   - integrations
   - audit
@@ -34,7 +33,7 @@ ask_examples:
   - Where do I see what the agent has been doing?
 locale: en-US
 created: 2026-04-26
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - deniedTools
   - safety floor
@@ -73,9 +72,10 @@ The risk classifier has two write tiers, not three:
   every connector tool call (send mail, archive, label, create event,
   delete event, …) and for normal context writes.
 - **Approve** — agent must present a Bearer token issued through the
-  dashboard. Reserved for posture-changing daemon configuration:
-  flipping integration modes, swapping the main backend, enabling/
-  disabling backends, wiping config.
+  dashboard. Reserved for posture-changing daemon configuration
+  (settings that change the safety setup itself): flipping integration
+  modes, swapping the main backend, enabling/disabling backends,
+  wiping config.
 - (`ReadSensitive` is the third tier, but it gates *reads* of personal
   data — orthogonal to write notifications. It is unchanged.)
 
@@ -95,22 +95,23 @@ actions are:
 ## Why This Concept Exists
 
 The previous Notify tier (3-tier model: Autonomous / Notify / Approve)
-gave a *false sense* of safety: the action completed regardless, the
-operator could miss the DM, and the middleware was structurally unable
-to intercept native MCP calls (the agent could reach Gmail through the
-backend's connector without ever touching the daemon). Curating a
-per-tool Notify policy across direct + cross-backend + same-backend +
-operator-installed MCPs was an ever-growing maintenance trap.
+gave a *false sense* of safety. The action completed either way, the
+operator could easily miss the DM, and the middleware simply could not
+intercept native MCP calls — the agent could reach Gmail through the
+backend's own connector without ever passing through the daemon. On top
+of that, hand-curating a per-tool Notify policy across every path
+(direct, cross-backend, same-backend, and operator-installed MCPs) was
+an ever-growing maintenance trap.
 
 The new model is honest: dangerous actions either (a) are denied at the
 chokepoint by the operator's `deniedTools`, (b) require explicit
 Approve (sparse, intentional, daemon-config only), or (c) happen
 autonomously and are auditable on demand.
 
-The *value proposition* — the agent manages the operator's life — is
-preserved. The operator should not have to manage the agent's calendar
-of "report to me" events. Information about what the agent did is
-**available on demand**, not pushed.
+The core promise — the agent manages the operator's life — stays
+intact. The operator should not have to manage the agent's own calendar
+of "report back to me" events. Details of what the agent did are
+**available on demand**, not pushed at you.
 
 ## Definitions
 

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

@@ -14,7 +14,6 @@ summary: |
   to load it, and pins the exact tools the session may use.
 section: skills
 tags:
-  - core
   - skills
   - safety
   - knowledge
@@ -28,7 +27,7 @@ ask_examples:
   - Where do skill overlays live?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - SKILL.md
   - allowed-tools
@@ -42,6 +41,7 @@ keywords:
 related:
   - concepts/safety-and-execution
   - concepts/process-keys
+  - concepts/delegated-mode
   - reference/skills
 ui_anchors:
   - /knowledge
@@ -66,14 +66,15 @@ A skill is a Markdown file the daemon copies into the agent's working
 directory before each session. Its frontmatter declares the skill's
 `name`, `description`, and the `allowed-tools` the session may use.
 The agent reads `SKILL.md` at the start of every session that loads
-that skill and follows it as a contract.
+that skill and treats it as a contract — the rules it must follow
+for that task.
 
 ## Why This Concept Exists
 
 The agent runs against a real machine. Without scoped permissions, a
 "please summarize my mail" turn could in principle invoke `Bash(rm)`,
 post to your social accounts, or rewrite arbitrary files. Skills fix
-that by making the available toolset task-shaped: the morning routine
+that by fitting the available tools to the task: the morning routine
 loads the context/today/observations/schedule skills; a docs question
 loads only `docs-search`. Tools outside the allow-list aren't even
 visible to the model.
@@ -154,5 +155,7 @@ surfaced at **Settings → Self-learning** (`/settings/self-learning`).
   `allowed-tools` is too permissive.
 - [Process Keys](process-keys.md) — the dispatch identity that picks
   which skill manifest to load.
+- [Delegated Mode](delegated-mode.md) — the run mode whose sessions
+  load these skills.
 - [Skills (Reference)](../reference/skills.md) — index of every
   built-in skill.