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.6 KiB

Raw Permalink Blame History

obsidian-sorter — AI Agent Runbook

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

Prerequisites

Python 3.10 or later. No pip packages.
TYPESAFE_API_KEY for the JEV tier. The rules tier needs no key.
On .27, the code lives in ~/obsidian-sorter/.

Step 1 — Inspect Before You Act

Always run read-only commands first. Never write on the first pass.

cd ~/obsidian-sorter

# Vault shape: counts and types
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" scan

# Classify one note with the rules tier (free)
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
    propose "010 inbox/My Note.md"

# Classify one note with JEV
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
    propose "010 inbox/My Note.md" --jev

Step 2 — Plan, Then Apply

sort and sort-inbox are dry runs by default. Add --apply to write. The plan lists every change. Read the plan before you apply it.

# Show the plan
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
    sort "010 inbox/My Note.md" --jev

# Apply one note
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
    sort "010 inbox/My Note.md" --jev --apply

# Apply the whole inbox without a prompt (for agents)
python3 -m sorter --vault ~/obsidian --inbox "010 inbox" \
    sort-inbox --jev --apply --yes

Step 3 — Run the Tests

The tests run against an isolated vault copy. They never touch the live vault.

cd ~/obsidian-sorter

python3 tests/run_tests.py            # full suite (uses JEV, small cost)
python3 tests/run_tests.py --no-jev   # mechanics only, no API cost
python3 tests/run_tests.py --keep     # keep the temp vault for inspection
python3 tests/run_tests.py --strict-folders   # assert sub-folders (may flake)

Validation command for agents: python3 tests/run_tests.py --no-jev.

Step 4 — Refresh the Test Mirror (from `.13`)

rsync -a --delete \
  --exclude='.git' --exclude='.trash' --exclude='.venv' \
  --exclude='graphify-out*' --exclude='.obsidian' \
  sam@192.168.20.27:~/obsidian/ ./test-vault/

Step 5 — Manage the Watcher (on `.27`)

systemctl --user status  obsidian-sorter    # is it running?
systemctl --user restart obsidian-sorter    # restart after a code change
systemctl --user stop    obsidian-sorter    # pause it
systemctl --user start   obsidian-sorter    # resume it
journalctl --user -u obsidian-sorter -f     # live output

Log files:

Service log: ~/.local/state/obsidian-sorter.log
Sort log: ~/obsidian/010 inbox/_sort log.md

Step 6 — Deploy Code to `.27`

rsync -a --delete --exclude='test-vault' --exclude='__pycache__' \
  --exclude='.git' --exclude='*.pyc' ./ sam@192.168.20.27:~/obsidian-sorter/
systemctl --user restart obsidian-sorter    # on .27

Restart Checklist

Read this runbook and the Document Catalog in 00-index.md.
Check git status: git status.
Check recent commits: git log -n 5 --oneline.
Run validation: python3 tests/run_tests.py --no-jev.
Restart the service: systemctl --user restart obsidian-sorter.
Confirm it runs: systemctl --user status obsidian-sorter.

Safety Rules for Agents

Never write to the live vault without --apply.
Never edit a note body. Edit only frontmatter when the owner asks.
Never move a note named Untitled*.
Never overwrite an existing destination.
Never reintroduce retired types.
Never commit secrets.

Current Gaps

Phase D (MCP tool wrapper) is pending.
Phase E (Pi skill + distribution) is pending.
The test suite has no automated watcher test. Test it manually.

3.6 KiB Raw Permalink Blame History