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.
This commit is contained in:
69
docs/outline/03-code-map.md
Normal file
69
docs/outline/03-code-map.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# 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
|
||||
|
||||
1. **Command wrapper**: `~/bin/obsidian-sort`. It changes to `~/obsidian-sorter`,
|
||||
then runs `python3 -m sorter` with the vault and inbox set.
|
||||
2. **Module**: `python3 -m sorter --vault <path> --inbox <name> <command>`.
|
||||
3. **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`.
|
||||
Reference in New Issue
Block a user