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

3.0 KiB

Raw Blame History

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

A note lands in 010 inbox/ with type: note.
The watcher polls every 10 seconds. It classifies the note.
The watcher writes the proposal into the note frontmatter.
The owner reviews the note in Obsidian and ticks the approved checkbox.
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.

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

3.0 KiB Raw Blame History