Files

Sam Rolfe 63ed336dfa 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.

2026-10-13 12:37:28 +11:00

2.6 KiB

Raw Permalink Blame History

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

Command wrapper: ~/bin/obsidian-sort. It changes to ~/obsidian-sorter, then runs python3 -m sorter with the vault and inbox set.
Module: python3 -m sorter --vault <path> --inbox <name> <command>.
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.

2.6 KiB Raw Permalink Blame History