@aitne-sh/aitne 0.1.8 → 0.1.9

package/agent-assets/docs/features/memory-files/projects.md

@@ -1,16 +1,18 @@
 ---
 schema_version: 1
 slug: features/memory-files/projects
-title: projects/ files
+title: plans/projects/ files
 id: projects
 aliases:
   - project files
   - projects directory
+  - plans/projects
 category: features
 summary: |
-  One Markdown file per active project under projects/. Each captures
+  One Markdown file per project under plans/projects/. Each captures
   the project's why, status, key links, and the per-project log of
-  agent activity. Cross-linked from the roadmap.
+  agent activity. Cross-linked from the roadmap and surfaced by the
+  morning routine while the project is active.
 section: memory-files
 tags:
   - memory
@@ -20,43 +22,95 @@ status: stable
 ask_examples:
   - Where do I find the per-project files?
   - How does the agent decide a project is active?
+  - How does the agent write to a project file?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
-  - projects.md
+  - projects
   - project file
-  - projects/<slug>.md
+  - plans/projects/<slug>.md
   - active project
 related:
   - features/memory-files/roadmap
+  - features/memory-files/today
+ui_anchors:
+  - /knowledge?tab=context-files
+api_endpoints:
+  - GET /api/context/list/:dir
+  - PUT /api/context/*
+  - PATCH /api/context/*
 context_files:
-  - projects/<slug>.md
+  - plans/projects/<slug>.md
 ---
 
-# projects/ Files
+# plans/projects/ Files
 
 ## In One Sentence
 
-One Markdown file per active project; the agent appends notes,
-decisions, and external references over the project's lifetime.
+One Markdown file per project, stored at `plans/projects/<slug>.md`;
+the agent appends notes, decisions, and external references over the
+project's lifetime.
 
 ## What It Does
 
-- Captures the project's purpose, status, links, recent decisions.
-- Surfaces in the morning routine when the project is active and
-  has Preparation Timeline rows.
+- Captures the project's purpose, status, links, and recent decisions
+  in a single durable note.
+- Surfaces in the morning routine while the project is active and the
+  roadmap has Preparation Timeline rows pointing at it.
 - Becomes the canonical reference the agent quotes from in DMs.
 
+## File Shape
+
+Each file lives at `plans/projects/<slug>.md`. The daemon validates
+only the minimum — `type: project`, `owner: shared`, an `updated`
+date, and an H1 title. By convention the agent also writes `slug`,
+`state`, `start`, `due`, `stakeholders`, `next_milestone`, and `tags`.
+
+`state` is what marks a project **active**: the dashboard's project
+view filters on it, and the morning routine only surfaces projects
+whose `state` is active.
+
+```markdown
+---
+type: project
+owner: shared
+slug: spring-launch
+state: active
+due: 2026-06-15
+next_milestone: ship beta
+updated: 2026-05-28
+---
+
+# Spring Launch
+
+## Why
+Ship the public beta before the conference.
+
+## Log
+- 2026-05-28: agreed to cut feature X for v1.
+```
+
 ## When It Runs / How It Is Triggered
 
-Read on demand. Written when the operator asks the agent to
-remember something project-specific.
+Read on demand. Written when the operator asks the agent to remember
+something project-specific, or when a DM expresses project intent
+(create, update status, mark done).
+
+The agent never edits files on disk — it has no `Edit`/`Write` tools.
+All project writes go through the context API:
+
+- `GET /api/context/list/projects` — discover existing project files.
+- `PUT /api/context/plans/projects/<slug>` — create or fully replace.
+- `PATCH /api/context/plans/projects/<slug>` — append a log line or
+  update a section.
 
 ## Where in the Dashboard
 
-- **Knowledge → Context Files → projects/**.
+- **Knowledge → Context Files** (`/knowledge?tab=context-files`), under
+  the `plans/projects/` folder.
 
 ## Related
 
-- [roadmap.md](roadmap.md)
+- [roadmap.md](roadmap.md) — cross-links to project files for deeper context.
+- [today.md](today.md) — where active-project prep surfaces each day.

package/agent-assets/docs/features/memory-files/roadmap.md

@@ -15,26 +15,33 @@ summary: |
 section: memory-files
 tags:
   - memory
-  - planning
   - core
 status: stable
 ask_examples:
   - What is the roadmap file?
   - What is a Preparation Timeline?
   - How does the morning routine use the roadmap?
+  - How do I add a roadmap entry?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - roadmap.md
   - roadmap
   - long-term goals
   - preparation timeline
+  - milestones
 related:
   - features/routines/morning-routine
   - features/memory-files/projects
+  - features/memory-files/today
+ui_anchors:
+  - /knowledge?tab=context-files
+api_endpoints:
+  - PUT /api/context/*
+  - PATCH /api/context/*
 context_files:
-  - roadmap.md
+  - plans/roadmap.md
 ---
 
 # roadmap.md
@@ -42,19 +49,51 @@ context_files:
 ## In One Sentence
 
 A multi-week plan: each goal carries dates and Preparation Timeline
-rows the morning routine fires on the day of.
+rows that the morning routine fires on the day they come due.
 
 ## What It Does
 
-- Captures long-running goals beyond a single day.
+- Captures long-running goals that span more than a single day, so
+  they don't fall out of `state/today.md` (which is replaced fresh
+  each morning).
 - Preparation Timeline rows like "T-7 days: book hotel" surface in
-  the morning routine on the right day.
+  the morning routine on the day each offset lands — turning a far-off
+  milestone into concrete actions at the right moment.
 - Cross-links to project files for deeper context.
 
+## What It Looks Like
+
+A goal with a Preparation Timeline is just Markdown the agent reads
+each morning. For example:
+
+```markdown
+## Conference talk — 2026-06-20
+
+Goal: deliver the keynote in Tokyo.
+
+Preparation Timeline:
+- T-14 days: finalize slide deck
+- T-7 days: book hotel
+- T-2 days: dry run with the team
+- T-0: travel day
+```
+
+On 2026-06-06 the morning routine sees the `T-14` offset come due and
+pulls "finalize slide deck" into that day's plan; on 2026-06-13 it
+surfaces "book hotel", and so on.
+
 ## When It Runs / How It Is Triggered
 
-Read by the morning routine; updated by the operator (or the agent
-on request).
+Read by the morning routine each day, which walks the roadmap and
+surfaces any Preparation Timeline rows whose offset fires that day.
+The file is updated by the operator, or by the agent on request (for
+example via the roadmap skill or `aitne run-now roadmap_maintenance`).
+
+The agent never edits the file directly. All writes go through the
+daemon's context endpoint — `PUT /api/context/plans/roadmap` (full
+replace) or `PATCH /api/context/plans/roadmap` (section op) — which is
+guarded by an exclusive roadmap write lock so two flows can't clobber
+each other.
 
 ## Where in the Dashboard
 
@@ -62,5 +101,6 @@ on request).
 
 ## Related
 
-- [Morning Routine](../routines/morning-routine.md)
-- [Projects](projects.md)
+- [Morning Routine](../../routines/morning-routine.md) — reads the roadmap each day.
+- [Projects](projects.md) — deeper, per-project context the roadmap links to.
+- [today.md](today.md) — the single-day plan the roadmap feeds into.

package/agent-assets/docs/features/memory-files/schedule.md

@@ -1,112 +1,155 @@
 ---
 schema_version: 1
 slug: features/memory-files/schedule
-title: daily/ files
+title: journal/daily/ files
 id: schedule-files
 aliases:
-  - schedule directory
+  - daily journal
   - daily directory
-  - per-date schedule
-  - daily/YYYY-MM-DD.md
+  - per-date journal
+  - journal/daily/YYYY-MM-DD.md
+  - schedule directory
 category: features
 summary: |
-  Per-date synthesis files (daily/YYYY-MM-DD.md) the morning routine
-  writes from yesterday.md plus the SQLite event log. They are the
-  read-only archive each day rolls into; the dashboard's Schedule view
-  also reads them.
+  Per-date diary files (journal/daily/YYYY-MM-DD.md) the morning
+  routine writes as a first-person retrospective of the previous
+  agent-day. They are a read-only archive composed by the daemon from
+  the Stage B journal session's output; weekly and monthly reviews
+  read them back.
 section: memory-files
 tags:
   - memory
-  - schedule
+  - journal
+  - routines
   - core
 status: stable
 ask_examples:
-  - Where does the agent store the day's archived plan?
-  - Why is yesterday still showing up in /schedule?
-  - How do I hand-edit a day's plan?
+  - Where does the agent store the day's diary?
+  - What is in journal/daily and how is it different from today.md?
+  - How do I change which sections the daily journal includes?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-26
+updated: 2026-05-28
 keywords:
-  - schedule
-  - daily
+  - daily journal
+  - diary
   - per-date
-  - calendar snapshot
+  - retrospective
+  - synthesis
 related:
   - features/routines/morning-routine
   - features/memory-files/today
+  - features/memory-files/agent-journal
   - concepts/agent-day
 ui_anchors:
   - /schedule
+process_keys:
+  - routine.morning_routine_journal
 context_files:
-  - daily/<date>.md
+  - journal/daily/<date>.md
 ---
 
-# daily/ Files
+# journal/daily/ Files
 
 ## In One Sentence
 
-`daily/YYYY-MM-DD.md` is the morning routine's synthesized archive of
-the agent-day; the dashboard's Schedule view and downstream routines
-read from this directory.
-
-> **Heads up — directory renamed.** The mechanical
-> `schedule/YYYY-MM-DD.md` copy was retired in B-007. The morning
-> routine now synthesizes `daily/YYYY-MM-DD.md` from `yesterday.md`
-> plus the SQLite event log instead. Hand-pruning the old `schedule/`
-> directory is safe.
-
-## What It Does
-
-Each file under `~/.personal-agent/context/daily/` corresponds to one
-**agent day** (the file name uses the agent-day date, not the calendar
-date — see [Agent Day](../../concepts/agent-day.md)). The morning
-routine writes the file shortly after rolling `today.md` →
-`yesterday.md`. It contains:
-
-- Calendar events from connected calendars.
-- Mail-driven items the agent flagged for that day.
-- Preparation Timeline rows from `roadmap.md` whose offset fired that day.
-- Carryover items the agent did not finish.
-
-The synthesis is template-driven and reads from the in-process DB
-snapshot of the closing `today.md` plus the day's event records, so
-late edits made directly to `today.md` after rotation cannot retroactively
-rewrite a previous `daily/` file.
-
-## When It Runs / How It Is Triggered
-
-The morning routine writes today's file once at start-of-day. Other
-routines read it but do not rewrite.
-
-## What It Outputs
-
-- A Markdown file with sections for events, preparations, and
-  carryover items.
-- A `last_updated` line so the dashboard knows freshness.
+`journal/daily/YYYY-MM-DD.md` is the morning routine's first-person
+diary of the **previous** agent-day — what the user did, who they met,
+what they talked about — composed by the daemon and kept as a
+read-only archive that the weekly and monthly reviews read back.
+
+> **Renamed from `schedule/`.** The old mechanical `schedule/YYYY-MM-DD.md`
+> copy was retired. Today the morning routine synthesizes a diary at
+> `journal/daily/YYYY-MM-DD.md` instead — a retrospective, not a plan.
+> Pruning any leftover `schedule/` directory is safe.
+
+## What It Is (and What It Is Not)
+
+This is a **diary of what already happened**, written for the user in
+their own voice. It is the opposite end of the day from
+[today.md](today.md):
+
+- **`state/today.md`** is the live, forward-looking plan for the
+  *current* agent-day — calendar events ahead, items to prepare,
+  carryover.
+- **`journal/daily/<date>.md`** is the finished, retrospective record
+  of a *past* agent-day. Once written it is not rewritten.
+
+It is also distinct from [journal/agent.md](agent-journal.md): the
+daily journal is the *user's* diary, while `journal/agent.md` is the
+agent's own decision log. Agent-side telemetry (action counts, retry
+stats) never appears here.
+
+## What It Contains
+
+Each file under `~/.personal-agent/context/journal/daily/` corresponds
+to one **agent day** (the file name uses the agent-day date, not the
+calendar date — see [Agent Day](../../concepts/agent-day.md)). The body
+typically includes:
+
+- `## Summary` — a first-person recap of the day.
+- `## Schedule` — the events and meetings that actually took place.
+- `## Tasks` — what the user worked on.
+- `## Conversations` — who they talked to and about what.
+
+When the `browser_history` integration is active, a reading/research
+surface is woven in from the day's browser digest. Daemon-owned
+frontmatter (`date`, `weekday`, `calendar_events`, `messages_handled`,
+`projects`, `people`, `tags`, `content_hash`, `updated`) is filled in
+automatically. The exact sections and tone are governed by the
+journal-format and journal-export policy files (see
+[Configuration](#configuration)).
+
+## When It Runs / How It Is Written
+
+The daily journal is **Stage B of the 04:00 morning routine**
+(process key `routine.morning_routine_journal`, lite tier), which runs
+in parallel with Stage A's `state/today.md` rollover. Stage B authors
+the body of *yesterday's* file; because the agent has no write tools,
+its output is two XML-tagged blocks that the daemon's
+`DailyJournalComposer` extracts, frames with frontmatter, and writes
+atomically to disk.
+
+Because the synthesis reads pre-aggregated facts captured at rotation
+time, late edits made directly to `state/today.md` after rollover
+cannot retroactively rewrite an already-written `journal/daily/` file.
+
+Other routines (weekly and monthly reviews) read these files back but
+do not rewrite them.
 
 ## Where in the Dashboard
 
-- **Schedule (`/schedule`)** reads adjacent `daily/<date>.md` files
-  to render the past/today/upcoming columns. Hand-edits are picked up
-  on the next view refresh.
+The daily journal does **not** appear on the Schedule page — that page
+shows the scheduler's wake-ups and recurring routines, not these files.
+
+- **Journal settings (`/settings/journal`)** is where you shape the
+  output: the Format and Export rule files control which sections
+  appear, the voice, the required frontmatter, and the redaction /
+  inclusion rules applied on every synthesis run. Edits take effect on
+  the next morning routine.
 
 ## Configuration
 
-There is nothing to configure on these files directly; they are a
-side effect of the morning routine. Retention is unlimited — old
-files accumulate. A manual prune (`rm daily/2025-*.md`) is safe.
+There is nothing to configure on the files themselves; they are a
+side effect of the morning routine. To change *what* gets written, edit
+the journal Format and Export rules at `/settings/journal`.
+
+Retention is unlimited — old files accumulate. A manual prune
+(`rm ~/.personal-agent/context/journal/daily/2025-*.md`) is safe.
 
 ## When Something Goes Wrong
 
-- An **empty** daily file usually means the morning routine did not
-  run. See [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
-- A view that **shows yesterday** is the day-boundary subtlety:
-  before `dayBoundaryHour`, the agent day is still yesterday. See
-  [Agent Day](../../concepts/agent-day.md).
+- A **missing or empty** daily file usually means the morning routine
+  did not run. See
+  [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
+- An entry **dated to the wrong day** is the day-boundary subtlety:
+  before `dayBoundaryHour` (default 04:00 local), the agent day is
+  still yesterday. See [Agent Day](../../concepts/agent-day.md).
 
 ## Related
 
-- [Morning Routine](../routines/morning-routine.md) — the writer.
-- [today.md](today.md) — the live, hand-editable surface for the
-  current agent day.
+- [Morning Routine](../routines/morning-routine.md) — the writer (Stage B).
+- [today.md](today.md) — the live, forward-looking plan for the
+  current agent-day.
+- [journal/agent.md](agent-journal.md) — the agent's own decision log,
+  distinct from this user diary.

package/agent-assets/docs/features/memory-files/today.md

@@ -8,9 +8,9 @@ aliases:
   - day plan
 category: features
 summary: |
-  today.md is the live, hand-editable plan for the current agent day.
-  The morning routine writes it; the operator and the agent both
-  append to it during the day.
+  today.md is the live plan for the current agent day. The morning
+  routine rebuilds it each day; the hourly check, evening review,
+  and the operator all read and append to it during the day.
 section: memory-files
 tags:
   - core
@@ -23,52 +23,77 @@ ask_examples:
   - Why does today.md keep getting rewritten?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - today
   - day plan
+  - agent log
+  - handoff
 related:
   - features/routines/morning-routine
+  - features/routines/hourly-check
+  - features/routines/evening-review
   - features/memory-files/schedule
   - concepts/agent-day
+ui_anchors:
+  - /knowledge?tab=context-files
+api_endpoints:
+  - PUT /api/context/*
+  - PATCH /api/context/*
 context_files:
-  - today.md
+  - state/today.md
 ---
 
 # today.md
 
 ## In One Sentence
 
-The single live file that captures the day's plan, log, tasks, and
-hand-off — rebuilt by the morning routine, appended-to by everything
-else during the day.
+The single live file for the current agent day — plan, log, tasks, and
+hand-off. The morning routine rebuilds it; everything else during the
+day appends to it.
 
 ## What It Does
 
-Sections:
+today.md holds six sections, written in this order:
 
-- **User Schedule** — calendar events.
-- **Tasks** — today's external + agent-tracked tasks.
-- **Agent Plan** — what the agent intends to work on today.
-- **Agent Log** — what actually happened.
-- **Handoff** — what carries to tomorrow.
+- **User Schedule** — the day's calendar events.
+- **User Tasks** — today's external tasks plus agent-tracked to-dos.
+- **Agent Plan** — what the agent intends to work on today (each row is
+  registered as a schedule entry by the morning routine).
+- **Agent Notes** — look-ahead items and date-bound memos folded in from
+  inbox triage.
+- **Agent Log** — what actually happened, appended throughout the day.
+- **Handoff** — what carries over to tomorrow.
 
 ## When It Runs / How It Is Triggered
 
-- The morning routine fully rewrites it.
-- The hourly check appends short observations under Agent Log.
-- The evening review reads it before writing the journal.
+- The **morning routine** fully rebuilds today.md (the daemon first
+  rotates the previous day's file to `state/yesterday.md`).
+- The **hourly check** routes new observations into the right section
+  and appends short status lines under Agent Log.
+- The **evening review** finalizes the file — it updates Agent Log and
+  the Handoff section before writing the daily journal.
+
+## How It Is Written
+
+The agent never edits today.md with a file tool. All writes go through
+the daemon's context API — `PUT`/`PATCH /api/context/state/today` (the
+canonical, class-prefixed path). A `today-write-lock` serializes writes
+during the morning routine: while the lock is held, a write to
+`state/today` must carry the `X-Lock-Id` header or it is rejected.
 
 ## Where in the Dashboard
 
-- **Knowledge → Context Files → today.md** to view and edit.
+- **Knowledge → Context Files → today.md** to view and edit by hand.
 
 ## When Something Goes Wrong
 
-- An empty today.md after the morning hour: see [Morning Routine
-  Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
+- An empty today.md after the morning hour: see
+  [Morning routine didn't run](../../troubleshooting/morning-routine-didnt-run.md).
 
 ## Related
 
-- [Morning Routine](../routines/morning-routine.md)
+- [Morning routine](../routines/morning-routine.md)
+- [Hourly check](../routines/hourly-check.md)
+- [Evening review](../routines/evening-review.md)
 - [schedule/ files](schedule.md)