Instructs agents to use the ranger CLI for task management on this
project, with conventions for states, comments as decision logs,
and architecture reference.

Assisted-by: Claude Opus 4.6 via pi

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ec697d0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,121 @@
+# Ranger — Agent Instructions
+
+## Project
+
+Personal task tracker. Rust workspace: `ranger-lib` (library) + `ranger-cli` (binary). SQLite via sqlx, async with tokio, CLI with clap.
+
+## Commands
+
+```bash
+cargo build --workspace          # Build everything
+cargo test --workspace           # Run all tests (33 unit + 1 integration)
+cargo test -p ranger-lib         # Library tests only
+cargo test -p ranger-cli         # CLI integration test only
+cargo run --bin ranger -- --help  # CLI usage
+```
+
+## Project Management
+
+Use the `ranger` CLI to manage tasks for this project. The database lives at the default XDG path (`~/.local/share/ranger/ranger.db`).
+
+### Setup (first time only)
+
+```bash
+cargo run --bin ranger -- backlog create "Ranger"
+```
+
+### Workflow
+
+Before starting work, check the backlog:
+
+```bash
+ranger task list --backlog <key> --state queued
+ranger task list --backlog <key> --state in_progress
+```
+
+When picking up a task:
+
+```bash
+ranger task edit <key> --state in_progress
+ranger comment add <key> "Starting work on this"
+```
+
+While working, add comments to track progress and decisions:
+
+```bash
+ranger comment add <key> "Decided to use X because Y"
+```
+
+When done:
+
+```bash
+ranger task edit <key> --state done
+ranger comment add <key> "Completed — summary of what was done"
+```
+
+To add new work:
+
+```bash
+ranger task create "Title" --backlog <key>                    # icebox by default
+ranger task create "Title" --backlog <key> --state queued     # committed work
+ranger task create "Subtask" --backlog <key> --parent <key>   # subtask
+```
+
+Use `--json` on any command when you need structured output.
+
+### Conventions
+
+- **Icebox**: ideas, not committed to
+- **Queued**: committed, ordered by priority (top = most important)
+- **In Progress**: actively being worked on
+- **Done**: finished
+
+Add comments liberally — they serve as a decision log for future sessions.
+
+## Architecture
+
+```
+crates/
+├── ranger-lib/          # Core library
+│   ├── src/
+│   │   ├── db.rs        # SQLite connection, migrations
+│   │   ├── error.rs     # Error types
+│   │   ├── key.rs       # jj-style key generation
+│   │   ├── models.rs    # Data types (Backlog, Task, Comment, Tag, Blocker)
+│   │   ├── position.rs  # Lexicographic fractional indexing
+│   │   └── ops/         # CRUD operations per model
+│   └── migrations/      # SQL schema
+└── ranger-cli/          # CLI binary
+    ├── src/
+    │   ├── main.rs      # Entrypoint, clap setup, DB path resolution
+    │   ├── output.rs    # Human/JSON output helpers
+    │   └── commands/    # One module per subcommand group
+    └── tests/
+        └── cli.rs       # End-to-end integration test
+```
+
+## Key Design Decisions
+
+- **Keys**: jj-style random strings (16 chars, `k-z` alphabet). Reference by shortest unique prefix.
+- **Positioning**: Lexicographic string-based ordering within backlogs. Insert between two positions without renumbering.
+- **Tasks in multiple backlogs**: A task can belong to multiple backlogs via `backlog_tasks` join table, with independent positions.
+- **Subtasks are tasks**: `parent_id` on tasks — subtasks get full task capabilities.
+- **No compile-time checked queries**: Using `sqlx::query_as` with runtime binding, not `query_as!` macros. No need for `DATABASE_URL` at build time.
+- **Dependencies unpinned**: `Cargo.toml` uses `"*"` versions; `Cargo.lock` pins exact versions.
+
+## Testing
+
+Tests use `tempfile` for isolated SQLite databases. Each test creates its own DB — no shared state.
+
+The integration test (`crates/ranger-cli/tests/cli.rs`) exercises the full workflow via the compiled binary using `assert_cmd`.
+
+## Gotchas
+
+- `sqlx::raw_sql` is used for migrations (multiple statements in one file). `sqlx::query` only runs one statement.
+- SQLite foreign keys must be enabled per-connection (`foreign_keys(true)` on connect options).
+- The `xdg` crate resolves `$XDG_DATA_HOME/ranger/ranger.db`. Override with `RANGER_DB` env var or `--db` flag.
+- Migration uses `CREATE TABLE IF NOT EXISTS` so it's idempotent (safe to run on every connect).
+
+## VCS
+
+This project uses **jj** (Jujutsu), not git directly. Use `jj` commands for commits, diffs, and history.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..fbc731a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+See [AGENTS.md](AGENTS.md) for all project context and instructions.