## Summary
Adds `BEANS_PATH` environment variable as an alternative to the
`--beans-path` CLI flag for specifying the beans data directory.
## Motivation
When using beans with git worktrees, it's often desirable to have agents
directly use the base checkout's beans directory as a single source of
truth across all worktrees.
**Why not use existing approaches?**
- **`--beans-path` flag** - Requires agents to include the flag on every
single command invocation, which is error-prone and easy to forget
- **Modifying `.beans.yml` in worktrees** - Creates unwanted
modifications that might accidentally get committed or cause merge
conflicts
**Why an environment variable?**
An environment variable is easy to set once, transparent across all
beans commands, safe from accidental commits, and follows standard
patterns for environment-specific configuration.
## Changes
### Path Resolution Precedence
The beans path is now resolved in this order:
1. **`--beans-path` flag** (highest priority) - Explicit user override
2. **`BEANS_PATH` env var** (medium priority) - Session/environment
setting
3. **Config file** (lowest priority) - Default behavior
### Implementation
**Extracted `resolveBeansPath()` function** (`cmd/root.go`):
- Centralizes path resolution logic into a testable function
- Checks `os.Getenv("BEANS_PATH")` when flag is empty
- Context-aware error messages (explicit path vs config fallback)
**Updated flag help text**:
- `"Path to data directory (overrides config and BEANS_PATH env var)"`
### Tests
8 test cases in `cmd/root_test.go`:
| Test | Verifies |
|------|----------|
| `flag_takes_highest_precedence` | Flag wins over both env var and
config |
| `flag_overrides_env_var` | Flag used even when `BEANS_PATH` is set to
invalid path |
| `env_var_used_when_flag_is_empty` | `BEANS_PATH` is picked up when no
flag given |
| `config_used_when_flag_and_env_var_are_empty` | Falls through to
config when neither is set |
| `invalid_flag_path_returns_error` | Error: "does not exist or is not a
directory" |
| `invalid_env_var_path_returns_error` | Same error for bad env var path
|
| `invalid_config_path_returns_init_suggestion` | Suggests `beans init`
for config fallback |
| `file_path_rejected_as_not_a_directory` | Regular file (not dir) is
rejected |
## Usage
```bash
# Set once for the session — all beans commands use it
export BEANS_PATH=/path/to/base-checkout/.beans
beans list
beans create "New task" -t task
# Flag still takes precedence when needed
BEANS_PATH=/default/path beans list --beans-path /override/path
```