Sam Rolfe
63ed336dfa
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.
119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# 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.
|