docs(outline): add AI agent context set (Outline layer)
Add docs/outline/00-index.md plus system overview, config/env, code map, and agent runbook in Simplified Technical English. Link the set from the README. Completes the project-docs Outline layer.
This commit is contained in:
77
docs/outline/01-system-overview.md
Normal file
77
docs/outline/01-system-overview.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# obsidian-sorter — System Overview
|
||||
|
||||
> **Target**: AI Agents — ASD-STE100 Simplified Technical English.
|
||||
|
||||
## Purpose
|
||||
|
||||
The sorter files notes into a personal Obsidian vault. The owner drops a note
|
||||
into `010 inbox/`. The sorter decides the destination. The owner approves. The
|
||||
sorter then moves the note and updates the index. The owner stays in control of
|
||||
every move.
|
||||
|
||||
## Architecture
|
||||
|
||||
The sorter uses two classification tiers. Tier 1 uses deterministic rules. Tier
|
||||
2 uses a probabilistic model (TypeSafe JEV). Tier 2 runs only when Tier 1 is
|
||||
unsure.
|
||||
|
||||
The system has one rule for types: **the type mirrors the folder**. Nothing is
|
||||
inferred from content. The destination folder decides the type.
|
||||
|
||||
| Folder | Type |
|
||||
| :--- | :--- |
|
||||
| `200 projects/` | `project` |
|
||||
| `300 areas/` | `area` |
|
||||
| `400 Personal Family/` | `family` |
|
||||
| `100 Table of Contents/` | `index` |
|
||||
| `000 daily/` | `daily` |
|
||||
| `500 archive/` | `archive` |
|
||||
| `Clippings/` | `clipping` |
|
||||
| `010 inbox/` | `note` (unsorted placeholder only) |
|
||||
|
||||
Retired types (never reintroduce): `subject`, `domain`, `tool`, `service`,
|
||||
`container`, `machine`, `storage`, `backup-system`, `network-component`,
|
||||
`website`, `person`.
|
||||
|
||||
## Flow
|
||||
|
||||
1. A note lands in `010 inbox/` with `type: note`.
|
||||
2. The watcher polls every 10 seconds. It classifies the note.
|
||||
3. The watcher writes the proposal into the note frontmatter.
|
||||
4. The owner reviews the note in Obsidian and ticks the `approved` checkbox.
|
||||
5. The watcher files the note. It moves the file, strips admin fields, and
|
||||
inserts the Table of Contents entry.
|
||||
|
||||
Admin fields written during review: `proposed_folder`, `proposed_toc`,
|
||||
`proposed_tags`, `confidence`, `approved`, `proposed_for`. The writer removes
|
||||
all admin fields after filing.
|
||||
|
||||
## Active Services
|
||||
|
||||
| Service | Host | Details |
|
||||
| :--- | :--- | :--- |
|
||||
| `obsidian-sorter` (systemd user unit) | `.27` | Polls the inbox every 10 seconds. Enabled and lingering. |
|
||||
| Command wrapper | `.27` | `~/bin/obsidian-sort` |
|
||||
|
||||
The unit runs `~/bin/obsidian-sort watch --interval 10`. It writes to
|
||||
`~/.local/state/obsidian-sorter.log`. It restarts on failure after 30 seconds.
|
||||
|
||||
## Key Behaviour Rules
|
||||
|
||||
- Dry run is the default. The `--apply` flag is required to write anything.
|
||||
- Notes named `Untitled*` never move. The plan is blocked.
|
||||
- The writer never overwrites an existing destination.
|
||||
- The owner's folder choice always wins. The sorter never re-decides a folder
|
||||
that already has a value.
|
||||
- The owner's own tags win. A note tagged `project` or `family` stays in that
|
||||
bucket.
|
||||
- The writer preserves `tags`, `aliases`, `id`, and `created`.
|
||||
- The writer never rewrites the note body.
|
||||
- JEV is probabilistic. Folder accuracy is about 74%. Tests assert the bucket
|
||||
strictly. Tests assert the sub-folder only with `--strict-folders`.
|
||||
|
||||
## Related Artifacts
|
||||
|
||||
- Gitea repository: `https://gitea.lab.audasmedia.com.au/sam/obsidian-sorter`
|
||||
- Architecture map: `https://maps.lab.audasmedia.com.au/obsidian-sorter/docs/obsidian-sorter-map.html`
|
||||
- Handoff notes: `docs/HANDOFF.md`
|
||||
Reference in New Issue
Block a user