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:
61
docs/outline/02-config-and-env.md
Normal file
61
docs/outline/02-config-and-env.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# obsidian-sorter — Configuration & Environment
|
||||
|
||||
> **Target**: AI Agents — ASD-STE100 Simplified Technical English.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Purpose |
|
||||
| :--- | :--- | :--- |
|
||||
| `TYPESAFE_API_KEY` | Only for JEV | Authenticates calls to TypeSafe JEV. The rules tier needs no key. |
|
||||
|
||||
The sorter reads `TYPESAFE_API_KEY` in this order:
|
||||
|
||||
1. The process environment.
|
||||
2. `~/.config/environment.d/*.conf`.
|
||||
3. `~/.config/obsidian-sorter/secrets.conf`.
|
||||
|
||||
The sorter accepts `KEY=value` and `export KEY=value` lines. It strips quotes.
|
||||
|
||||
**Warning**: Non-login SSH shells do not load `environment.d`. Set the key or
|
||||
use a login shell for manual JEV runs.
|
||||
|
||||
## Config Paths
|
||||
|
||||
| Path | Purpose |
|
||||
| :--- | :--- |
|
||||
| `~/obsidian/` | Vault root (default `--vault`). |
|
||||
| `~/obsidian/010 inbox/` | Inbox folder (default `--inbox`). |
|
||||
| `~/obsidian/010 inbox/_sort log.md` | Sorter activity log. |
|
||||
| `~/.local/state/obsidian-sorter.log` | Watcher service log. |
|
||||
| `~/.config/systemd/user/obsidian-sorter.service` | Watcher unit file. |
|
||||
| `~/bin/obsidian-sort` | Command wrapper. Sets vault and inbox. |
|
||||
|
||||
The command-line default for `--inbox` is `inbox`. The `~/bin/obsidian-sort`
|
||||
wrapper always passes `010 inbox`.
|
||||
|
||||
## Network
|
||||
|
||||
The sorter opens no listening port. It makes one outbound HTTPS call:
|
||||
|
||||
- `POST https://api.typesafe.ai/v1/systemone` (TypeSafe JEV).
|
||||
|
||||
Default request timeout is 90 seconds. Default call cap is 500 per run.
|
||||
|
||||
## Tunable Defaults
|
||||
|
||||
| Flag | Default | Meaning |
|
||||
| :--- | :--- | :--- |
|
||||
| `--threshold` | `0.45` | Rule confidence below this value escalates to JEV. |
|
||||
| `--interval` | `5.0` (CLI), `10` (service) | Seconds between watcher passes. |
|
||||
| `--max-calls` | `500` | Maximum JEV calls per run. |
|
||||
| `--timeout` | `90.0` | JEV request timeout in seconds. |
|
||||
|
||||
## Secrets
|
||||
|
||||
Do not commit secrets. The API key lives only in the config files above. The
|
||||
repository ignores `*.log`, `test-vault/`, `__pycache__/`, and `.venv/`.
|
||||
|
||||
## Cost
|
||||
|
||||
JEV costs about `$0.0001` per note. The rules tier is free. Use `--no-jev` to
|
||||
run without API cost.
|
||||
Reference in New Issue
Block a user