# obsidian-sorter — Code Structure Map

> **Target**: AI Agents — ASD-STE100 Simplified Technical English.

## Dependencies

The sorter uses the Python standard library only. It requires Python 3.10 or
later. It uses no PyYAML, no HTTP library, and no JEV SDK. Deploy with `rsync`.
Hosts need no pip.

## Layout

| Path | Purpose |
| :--- | :--- |
| `sorter/__main__.py` | Module entry point. Calls `cli.main`. |
| `sorter/cli.py` | Argument parser and all commands. |
| `sorter/models.py` | Data types. Folder-to-type map. `Note`, `Proposal`. |
| `sorter/vault.py` | Vault scanning and index introspection. |
| `sorter/frontmatter.py` | Minimal YAML frontmatter reader and writer. |
| `sorter/classify.py` | Tier 1 deterministic classifier. |
| `sorter/jev.py` | TypeSafe JEV client. Cost tracking. |
| `sorter/tier2.py` | Tier 2 semantic classifier. Hybrid logic. |
| `sorter/writer.py` | Plans, frontmatter merge, TOC insert, apply. |
| `sorter/watch.py` | Inbox watcher. Maintains proposals. |
| `tests/run_tests.py` | Test suite. Runs against an isolated vault copy. |
| `tools/normalize_tags.py` | One-off tag cleanup tool. |
| `docs/` | Diagrams, handoff notes, and this Outline set. |

## Entry Points

1. **Command wrapper**: `~/bin/obsidian-sort`. It changes to `~/obsidian-sorter`,
   then runs `python3 -m sorter` with the vault and inbox set.
2. **Module**: `python3 -m sorter --vault <path> --inbox <name> <command>`.
3. **Systemd unit**: `ExecStart=~/bin/obsidian-sort watch --interval 10`.

## Commands

Read-only commands:

| Command | Purpose |
| :--- | :--- |
| `scan` | Report vault shape. |
| `propose <file>` | Classify one note. |
| `inbox` | Classify every inbox note. |
| `validate` | Replay the classifier against known-good notes. |
| `benchmark` | Measure accuracy and cost of the hybrid classifier. |

Write commands:

| Command | Purpose |
| :--- | :--- |
| `sort <file>` | Plan, then optionally apply, sorting for one note. |
| `sort-inbox` | Plan, then optionally apply, sorting for the whole inbox. |
| `watch` | Watch the inbox and maintain proposals. |

## Core Data Flow

`vault.py` scans notes into `Note` objects. `classify.py` picks a folder with
rules. `tier2.py` escalates to `jev.py` when needed. `writer.py` builds a
`Proposal` and a `Plan`, then applies it. `watch.py` connects the classifier to
the file system on a 10-second poll.

## Where to Fix Things

- **Misfiled notes**: edit `FOLDER_NOTES` in `sorter/tier2.py`. This teaches the
  model the meaning of each folder.
- **Rule behaviour**: edit `sorter/classify.py`.
- **Type or folder rules**: edit `sorter/models.py`.
- **Filing safety**: edit `sorter/writer.py`.