@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,118 @@
+---
+schema_version: 1
+slug: concepts/memory-model
+title: Memory Model
+id: memory-model
+aliases:
+  - context files
+  - memory files
+  - long-term memory
+category: concepts
+summary: |
+  Aitne stores durable memory as plain Markdown files under
+  ~/.personal-agent/context/. SQLite holds sessions, actions, and
+  observations; the MD files are the authoritative store for everything
+  the agent reads and rewrites about you.
+section: memory
+tags:
+  - core
+  - memory
+  - storage
+status: stable
+ask_examples:
+  - Where are my context files stored?
+  - How does the agent edit context files?
+  - What is the difference between context MD and SQLite?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - context
+  - markdown
+  - SQLite
+  - today.md
+  - user/profile.md
+  - roadmap.md
+related:
+  - features/memory-files/today
+  - features/memory-files/user-profile
+  - features/memory-files/roadmap
+  - features/memory-files/agent-journal
+  - features/memory-files/schedule
+  - features/memory-files/projects
+ui_anchors:
+  - /knowledge
+  - /connections/knowledge
+context_files:
+  - today.md
+  - user/profile.md
+  - roadmap.md
+  - agent/journal.md
+  - daily/<date>.md
+  - projects/<slug>.md
+---
+
+# Memory Model
+
+## TL;DR
+
+Aitne treats 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.
+
+## 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".
+
+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.
+
+## 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.
+- **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.
+
+## Concrete Examples
+
+- `today.md` — rewritten by the morning routine.
+- `user/profile.md` — your profile, hand-edited or appended by the
+  agent on request. Topic-shaped slices live alongside it
+  (`user/people.md`, `user/work.md`, `user/expertise.md`,
+  `user/personal.md`, `user/goals.md`). See
+  [User Profile](../features/memory-files/user-profile.md).
+- `roadmap.md` — long-running goals + Preparation Timeline rows that
+  fire daily during the morning routine.
+- `agent/journal.md` — the agent's own running log of decisions,
+  retros, and judgement calls.
+- `daily/2026-04-25.md` — per-date archive of that day's plan,
+  synthesized by the morning routine.
+- `projects/<slug>.md` — one file per active project.
+
+## Where You See It in the Dashboard
+
+- **Knowledge → Context Files** lists every file with its size, last
+  modified time, and a preview.
+- **Connections → Knowledge** is where vault integrations (Obsidian,
+  Notion) attach.
+
+## Related
+
+- [today.md](../features/memory-files/today.md)
+- [user/profile.md](../features/memory-files/user-profile.md)
+- [roadmap.md](../features/memory-files/roadmap.md)
+- [Skills](skills.md) — the per-skill SKILL.md files that tell the
+  agent how to read and write each context file.

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

@@ -0,0 +1,80 @@
+---
+schema_version: 1
+slug: concepts/observations
+title: Observations
+id: observations
+aliases:
+  - observation
+  - polling
+  - hourly check
+category: concepts
+summary: |
+  Observations are change records the polling integrations write into
+  SQLite. The hourly check consumes them — there is no per-change
+  notification. This pivot was the Phase 9 polling change.
+section: observations
+tags:
+  - core
+  - observations
+  - polling
+status: stable
+ask_examples:
+  - What is an observation?
+  - Why doesn't the agent message me on every git commit?
+  - How does the hourly check use observations?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - observation
+  - polling
+  - hourly check
+  - phase 9
+related:
+  - features/routines/hourly-check
+  - concepts/process-keys
+---
+
+# Observations
+
+## 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.hourly_check` consumes the queue and decides
+what is worth surfacing.
+
+## 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.
+
+## Definitions
+
+- **Observation**: one row in the `observations` table.
+- **Actor**: who caused the change. `actor='agent'` rows are filtered
+  out by the consumer (anti-loop).
+- **Hourly check**: the consumer routine. Light tier by default.
+- **`AgentWriteTracker`**: the daemon component that tags
+  agent-originated writes so observers don't observe the agent's own
+  output.
+
+## Concrete Examples
+
+- A new commit in a watched repo → 1 observation.
+- A saved note in Obsidian → 1 observation.
+- A calendar event move → 1 observation.
+
+## Where You See It in the Dashboard
+
+- **Activity** logs hourly-check fires; the detail shows how many
+  observations were consumed.
+
+## Related
+
+- [Hourly Check](../features/routines/hourly-check.md)
+- [Git](../features/integrations/git.md)
+- [Obsidian](../features/integrations/obsidian.md)

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

@@ -0,0 +1,89 @@
+---
+schema_version: 1
+slug: concepts/process-keys
+title: ProcessKeys
+id: process-keys
+aliases:
+  - process key
+  - dispatch key
+  - event key
+category: concepts
+summary: |
+  A ProcessKey is the agent's dispatch identity for one kind of work
+  ("morning routine", "DM", "hourly check"). The router resolves it
+  to a backend + tier binding; the manifest map resolves it to skills.
+section: process-keys
+tags:
+  - core
+  - dispatch
+status: stable
+ask_examples:
+  - What is a ProcessKey?
+  - Where can I see all the ProcessKeys?
+  - How do I change which model handles a ProcessKey?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - process key
+  - dispatch
+  - routing
+related:
+  - concepts/backends-and-tiers
+  - concepts/skills
+  - reference/process-keys
+---
+
+# ProcessKeys
+
+## 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.
+
+## 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.
+
+## Definitions
+
+- **CONFIGURABLE_PROCESS_KEYS**: the set the operator can override per
+  backend on `/settings/models`.
+- **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events (DMs,
+  dashboard chat, docs QA).
+- **DEFAULT_PROCESS_TIERS**: the per-key default (heavy or light).
+- **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to the skill manifest
+  key.
+
+## Concrete Examples
+
+- Routines: `routine.morning_routine`, `routine.morning_routine_initial`,
+  `routine.evening_review`, `routine.weekly_review`,
+  `routine.monthly_review`, `routine.hourly_check`,
+  `routine.roadmap_refresh`, `routine.today_refresh`,
+  `routine.user_profile_sweep`
+- Custom routines: `routine.custom.<slug>` (kebab-case slug)
+- Messaging: `message.dm`, `message.mention`
+- Dashboard: `dashboard.chat`, `dashboard.docs_qa`
+- Scheduled / external: `agent.task` (recurring schedules),
+  `agent.dm_task` (DM-tone scheduled briefings),
+  `schedule.approaching`, `calendar.change`, `gmail_classify`,
+  `setup`
+
+## Where You See It in the Dashboard
+
+- **Settings → Models** lists every configurable ProcessKey with its
+  current binding.
+- **Activity** rows include the ProcessKey for every fire.
+
+## Related
+
+- [Backends and Tiers](backends-and-tiers.md)
+- [Skills](skills.md)
+- [Reference: ProcessKeys](../reference/process-keys.md)

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

@@ -0,0 +1,108 @@
+---
+schema_version: 1
+slug: concepts/routines
+title: Routines
+id: routines
+aliases:
+  - autonomous routines
+  - cron
+  - scheduled work
+category: concepts
+summary: |
+  Routines are the autonomous, scheduled tasks Aitne runs on
+  its own — morning routine, evening review, hourly check, weekly and
+  monthly retros, plus any custom routines you define.
+section: routines
+tags:
+  - core
+  - routine
+  - autonomous
+status: stable
+ask_examples:
+  - What routines does the agent run automatically?
+  - How do I disable a routine?
+  - Can I add my own routine?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - routine
+  - cron
+  - autonomous
+  - scheduler
+related:
+  - features/routines/morning-routine
+  - features/routines/evening-review
+  - features/routines/weekly-review
+  - features/routines/hourly-check
+  - features/routines/custom-routines
+  - concepts/process-keys
+ui_anchors:
+  - /connections/routines
+  - /settings/routines
+---
+
+# Routines
+
+## 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`; evening / weekly / monthly retros fire on fixed
+schedules in code; the hourly check coalesces accumulated observations
+on a configurable cadence.
+
+## 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.
+
+Each routine is a single ProcessKey — `routine.morning_routine`,
+`routine.hourly_check`, `routine.weekly_review`, etc. The dispatcher
+treats them as just another event class; the only difference from a
+DM is who fired the event.
+
+## Definitions
+
+- **Routine**: one autonomous job firing at a schedule. Identified by
+  a ProcessKey starting with `routine.`.
+- **Agent day**: the 24-hour window starting at `dayBoundaryHour`
+  (default 04:00) — see [Agent Day](agent-day.md).
+- **Catch-up**: if the daemon was offline at the trigger time, the
+  scheduler re-fires the routine on next launch when it is still in
+  the same agent day.
+- **Heavy / light tier**: only `routine.morning_routine` (and the
+  one-shot `routine.morning_routine_initial`) run heavy by default
+  (Opus on Claude, GPT-5.5 on Codex, Gemini 3 Pro on Gemini). Evening,
+  weekly, and monthly reviews plus the hourly check default to light —
+  see [Backends and Tiers](backends-and-tiers.md).
+
+## Concrete Examples
+
+| ProcessKey | When | Tier |
+|---|---|---|
+| `routine.morning_routine_initial` | First setup day, one-shot | heavy |
+| `routine.morning_routine` | `dayBoundaryHour` daily | heavy |
+| `routine.evening_review` | 18:00 daily (fixed) | light |
+| `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | light |
+| `routine.weekly_review` | Friday 18:00 (fixed) | light |
+| `routine.monthly_review` | Last day of month, 18:00 (fixed) | light |
+| `routine.custom.<slug>` | Operator-defined recurrence | configurable |
+
+## Where You See It in the Dashboard
+
+- **Settings → Routines** is where the hourly check active window, the
+  hourly check cadence, and any custom routines live. Morning, evening,
+  weekly, and monthly fire times are fixed in code and not surfaced
+  here.
+- **Connections → Routines** is the unified view of next-fire times.
+- **Activity** logs each routine run with its outcome.
+
+## Related
+
+- [Morning Routine](../features/routines/morning-routine.md)
+- [Evening Review](../features/routines/evening-review.md)
+- [Hourly Check](../features/routines/hourly-check.md)
+- [Custom Routines](../features/routines/custom-routines.md)

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

@@ -0,0 +1,109 @@
+---
+schema_version: 1
+slug: concepts/safety-and-execution
+title: Safety and Execution Modes
+id: safety-and-execution
+aliases:
+  - execution mode
+  - safe mode
+  - allow mode
+  - absolute block
+  - disallowed tools
+category: concepts
+summary: |
+  Aitne has two execution-mode postures (Safe / Allow) plus an
+  always-disallowed layer that holds in both. Together they decide
+  what tools the agent can run, when it must ask for approval, and
+  which actions are categorically refused.
+section: safety
+tags:
+  - core
+  - safety
+  - cost
+status: stable
+ask_examples:
+  - What is the difference between Safe and Allow mode?
+  - Can the agent ever delete files on its own?
+  - How do I see what tools the agent is allowed to use?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - safety
+  - safe mode
+  - allow mode
+  - absolute block
+  - disallowed tools
+  - approval
+related:
+  - concepts/skills
+  - features/operations/approvals
+  - reference/disallowed-tools
+ui_anchors:
+  - /settings/advanced
+config_keys:
+  - disallowedTools
+  - allowedToolsOverride
+  - claudeExecutionPermissionMode
+  - codexExecutionPermissionMode
+  - geminiExecutionPermissionMode
+---
+
+# Safety and Execution Modes
+
+## TL;DR
+
+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). Per-backend.
+3. **Always-disallowed** — a hard floor. Recursive deletes, sudo,
+   secret-file reads / writes are denied unconditionally regardless
+   of mode.
+
+## Why This Concept Exists
+
+A long-running agent that can write files, send messages, and call
+external APIs is one bad prompt away from a destructive turn. Layering
+the safety controls means a misconfigured allow-list can't unlock the
+absolute-block layer; a too-broad skill can't widen past the
+disallowed-tools floor.
+
+## Definitions
+
+- **Safe mode**: the default. Strict permission checks, Claude curl/jq
+  hooks, Codex workspace-write sandbox, Gemini whitelist TOML.
+- **Allow mode**: the looser posture. SDK bypass, sandbox off, minimal
+  TOML. The absolute-block layer still holds.
+- **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**: `read`, `notify`, `approve`. Read = autonomous. Notify
+  = the agent proceeds after DMing the operator. Approve = blocked
+  until the operator clicks approve in the dashboard.
+
+## Concrete Examples
+
+| Action | Risk tier |
+|---|---|
+| Read `today.md` | read |
+| Append to `agent/journal.md` | notify |
+| Send a DM | notify |
+| Update `roadmap.md` | approve |
+| Recursive delete | absolute-block (refused) |
+| `chmod` on a daemon-owned file | absolute-block |
+
+## Where You See It in the Dashboard
+
+- **Settings → Advanced** holds `disallowedTools`, `allowedToolsOverride`,
+  and the per-backend execution mode switch.
+- **Activity** logs every blocked tool call as `action_type='blocked_absolute'`.
+- **Approvals** is where Approve-tier actions queue when they fire.
+
+## Related
+
+- [Skills](skills.md) — where each session's per-task `allowed-tools` lives.
+- [Approvals](../features/operations/approvals.md) — the operator-side
+  surface for Approve-tier actions.
+- [Disallowed Tools (reference)](../reference/disallowed-tools.md)