Unnecessary manual setup for projects configuration

[juhoinkinen]

Currently the project configuration file project.toml must exist somewhere on the system when bibra is run (see the config PR #75). A user must get the projects.toml from the repository or write it from scratch. Notably when installing bibra from PyPI the projects.toml.example file is not obtained together with bibra itself.

Claude Sonnet 4.6 gave these options how this could be remediated:

Remediation Options

Option 1 — XDG / Platform-standard user config directory ⭐ Recommended

Follow the XDG Base Directory Specification (Linux/macOS) and its Windows equivalent. The search order becomes:

1. --config flag / BIBRA_CONFIG env var   (explicit override, unchanged)
2. ./projects.toml                         (local, project-specific)
3. $XDG_CONFIG_HOME/bibra/projects.toml   (~/.config/bibra/projects.toml on Linux)
4. /etc/bibra/projects.toml               (system-wide, Linux/macOS)

Python's platformdirs library (already widely used in the ecosystem) gives cross-platform paths for free:

from platformdirs import user_config_dir
Path(user_config_dir("bibra")) / "projects.toml"

Pros: Standard, predictable, works on all platforms, no magic.
Cons: Adds one small dependency (platformdirs).

---

Option 2 — bibra init scaffold command

Add a CLI command that writes a starter projects.toml (from the bundled example) into the appropriate location:

bibra init                  # writes ~/.config/bibra/projects.toml
bibra init --local          # writes ./projects.toml
bibra init --system         # writes /etc/bibra/projects.toml

This is the pattern used by tools like git, poetry, ruff, etc.

Pros: Excellent UX — zero manual file hunting; the file is self-documenting.
Cons: Slightly more code; users still need to edit the file after init.

---

Option 3 — Bundle a default config inside the package

Ship a minimal projects.toml as a package data file (e.g. bibra/data/projects.toml) and fall back to it when no user config is found, using importlib.resources:

import importlib.resources
default_cfg = importlib.resources.files("bibra") / "data" / "projects.toml"

Pros: Zero user action required; app always starts.
Cons: The bundled default is necessarily generic (only dummy backend works out of the box); real backends still need user configuration.

---

Option 4 — Graceful degradation (no config = dummy-only mode)

Instead of raising ConfigFileNotFoundError when no file is found, fall back to a built-in minimal registry containing only the dummy backend. The app starts and is usable; a warning is printed.

Pros: Best "it just works" experience for first-time users.
Cons: Could be confusing if a user accidentally deletes their config and doesn't notice.

---

Recommended Combination

The most robust and user-friendly approach combines Options 1 + 2 + 4:

flowchart TD
    A[bibra starts] --> B{--config or BIBRA_CONFIG?}
    B -- yes --> C[Load that file]
    B -- no --> D{./projects.toml exists?}
    D -- yes --> C
    D -- no --> E{"~/.config/bibra/projects.toml exists?"}
    E -- yes --> C
    E -- no --> F["Warn: no config found\nFall back to dummy-only mode"]
    F --> G["Suggest: run 'bibra init'"]

Loading

The bibra init command scaffolds the config at ~/.config/bibra/projects.toml from the bundled projects.toml.example, so a new user's workflow becomes:

pip install bibra
bibra init          # creates ~/.config/bibra/projects.toml with instructions
$EDITOR ~/.config/bibra/projects.toml
bibra list-projects

Implementation scope

Change	File(s)
Add platformdirs dependency	pyproject.toml
Extend path resolution in ProjectRegistry.__init__()	bibra/config.py
Bundle example config as package data	pyproject.toml, new bibra/data/projects.toml
Add bibra init command	bibra/cli.py
Graceful fallback in ProjectRegistry.load()	bibra/config.py
Update tests	tests/test_config.py, tests/test_cli.py