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

```bash
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.

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

```bash
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`)

```bash
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`)

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

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

1. Read this runbook and the Document Catalog in `00-index.md`.
2. Check git status: `git status`.
3. Check recent commits: `git log -n 5 --oneline`.
4. Run validation: `python3 tests/run_tests.py --no-jev`.
5. Restart the service: `systemctl --user restart obsidian-sorter`.
6. 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.