diff --git a/README.md b/README.md index ff452cd..5e45a52 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Capture and manage ideas from the command line. A worktree-aware backlog tracker ## Why idea? - **Plain Markdown, not a database** — your backlog is a checked-in `fab/backlog.md` file. Hand-edit it, grep it, diff it, review it in PRs. `idea` is one (canonical) writer of the format; the file is the contract. -- **Per-repo, not global** — every repo has its own backlog. No central app to log into, no cross-project noise. -- **Worktree-aware** — by default `idea` reads/writes the *current* worktree's backlog, so parallel changes don't step on each other. `--main` opts into the shared backlog when you need it. +- **Per-repo by default, with a global escape hatch** — every repo has its own backlog, so there's no cross-project noise. When you're not in a repo (or want a personal, cross-cutting list), `idea` falls back to a system-level backlog at `~/.config/idea/backlog.md` — reachable from anywhere with `--system`. +- **Worktree-aware** — by default `idea` reads/writes the *current* worktree's backlog, so parallel changes don't step on each other. `--main` opts into the shared backlog, and `--system` targets the global one. - **Short, addressable IDs** — every idea gets a 4-character ID like `[qu1d]` you can type into any command. Queries also match free-text substrings. - **Hooks into fab-kit** — `fab/backlog.md` is the same file fab-kit's `/fab-new` reads, so capturing an idea today and starting a change from it tomorrow is one command. @@ -101,10 +101,12 @@ This is the one behavior worth knowing in detail. `idea` resolves the backlog fi | Main repo | `idea add "..."` | `
/fab/backlog.md` | | Linked worktree | `idea add "..."` | `/fab/backlog.md` (local to this worktree) | | Linked worktree | `idea --main add "..."` | `
/fab/backlog.md` (shared with the team) | -| Anywhere | `idea --file path/to/file.md ...` | that file (relative to git root) | -| Anywhere | `IDEAS_FILE=... idea ...` | the env-var path | +| Outside any git repo | `idea add "..."` | `~/.config/idea/backlog.md` (the system backlog — automatic fallback) | +| Anywhere | `idea --system add "..."` | `~/.config/idea/backlog.md` (the system backlog, even inside a repo) | +| Anywhere | `idea --file path/to/file.md ...` | that file (relative to the git root, or to `~/.config/idea` outside a repo; absolute paths as-is) | +| Anywhere | `IDEAS_FILE=... idea ...` | the env-var path (same rooting as `--file`) | -Why the default favors the current worktree: when you're heads-down on a change and capture a thought, you usually mean "for *this* branch." `--main` is the explicit opt-in for "add this to the shared roadmap." In the main worktree, both behave identically. +Why the default favors the current worktree: when you're heads-down on a change and capture a thought, you usually mean "for *this* branch." `--main` is the explicit opt-in for "add this to the shared roadmap." In the main worktree, `--main` and the default behave identically. `--system` is the opt-in for a personal, cross-repo list — and it's also what you get automatically when you run `idea` outside any git repo, so capture works everywhere. (The system path honors `$XDG_CONFIG_HOME`, defaulting to `~/.config/idea/backlog.md`. `--system` and `--main` are mutually exclusive.) ## Integration with fab-kit diff --git a/docs/site/workflows.md b/docs/site/workflows.md index bdedac2..b36e420 100644 --- a/docs/site/workflows.md +++ b/docs/site/workflows.md @@ -9,37 +9,49 @@ New here? Start with the [install guide](install.md), then come back. ## Worktree-aware resolution -`idea` resolves the backlog file based on *where you run it* — not on an -environment default or a global config. By default it reads and writes the -**current worktree's** `fab/backlog.md`. +`idea` resolves the backlog file based on *where you run it*. Inside a git repo +it reads and writes the **current worktree's** `fab/backlog.md` by default — +predictable from your directory, never from stray environment state. Outside a +repo (or with `--system` anywhere), it uses a **system-level backlog** at +`~/.config/idea/backlog.md`, so capture works even where there's no repo. | Where you are | What you type | Which file `idea` touches | |---------------|---------------|----------------------------| | Main repo | `idea add "..."` | `
/fab/backlog.md` | | Linked worktree | `idea add "..."` | `/fab/backlog.md` (local to this worktree) | | Linked worktree | `idea --main add "..."` | `
/fab/backlog.md` (shared with the team) | -| Anywhere | `idea --file path/to/file.md ...` | that file (relative to the git root) | -| Anywhere | `IDEAS_FILE=... idea ...` | the env-var path | - -How resolution actually works under the hood: - -- **Current worktree** (the default): `idea` runs `git rev-parse --show-toplevel` - and uses `/fab/backlog.md`. +| Outside any git repo | `idea add "..."` | `~/.config/idea/backlog.md` (system backlog — automatic fallback) | +| Anywhere | `idea --system add "..."` | `~/.config/idea/backlog.md` (system backlog, even inside a repo) | +| Anywhere | `idea --file path/to/file.md ...` | that file (relative to the git root, or to `~/.config/idea` outside a repo) | +| Anywhere | `IDEAS_FILE=... idea ...` | the env-var path (same rooting as `--file`) | + +How resolution actually works under the hood (first match wins): + +- **`--system`**: skips git entirely and uses the system backlog — + `$XDG_CONFIG_HOME/idea/backlog.md`, defaulting to `~/.config/idea/backlog.md`. + Reachable from anywhere, including inside a repo. Mutually exclusive with `--main`. +- **`--file ` / `IDEAS_FILE`**: overrides the path. A relative value is + rooted at the git root inside a repo, or at `~/.config/idea` outside one; an + absolute value is used verbatim. - **`--main`**: `idea` runs `git rev-parse --path-format=absolute --git-common-dir` and takes that directory's parent as the main worktree root, then uses - `
/fab/backlog.md`. In the *main* worktree, `--main` and the default - behave identically. -- **`--file `**: overrides the path entirely (resolved relative to the git - root). -- **`IDEAS_FILE`**: same override via environment variable. + `
/fab/backlog.md`. Git-only — it errors outside a repo. In the *main* + worktree, `--main` and the default behave identically. +- **Current worktree** (the in-repo default): `idea` runs `git rev-parse --show-toplevel` + and uses `/fab/backlog.md`. +- **System fallback** (the out-of-repo default): when `git rev-parse` reports + you're not in a repo, `idea` gracefully falls back to the system backlog + instead of erroring. The config directory is created on first write. **Why the default favors the current worktree.** When you're heads-down on a change in a linked worktree and capture a thought, you almost always mean "for *this* branch." Defaulting to the current worktree keeps parallel changes from stepping on each other's backlogs. `--main` is the explicit opt-in for "add this -to the shared roadmap." Resolution never reads heuristics or stray environment -state — it asks git directly, so behavior is predictable from your current -directory alone. +to the shared roadmap." Inside a repo, resolution never reads heuristics or stray +environment state — it asks git directly, so behavior is predictable from your +current directory alone. The system backlog (`--system`, or the automatic +out-of-repo fallback) is the one deliberate exception: a single personal list for +cross-cutting ideas and for capture wherever there's no repo at all. ## fab-kit integration loop