# 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`