Sam Rolfe
63ed336dfa
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.
78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
# 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`
|