All interactive decisions in long-running setup scripts go in one batch at the top, before any work runs. Use this when adding a new prompt to `cmd_init`, `setup::init`, or any multi-minute recipe — it explains the "Step 0/N Configuration" pattern and why we don't sprinkle Y/n prompts through the steps.
There should be exactly one way to do everything in this repo. Use this when reviewing or refactoring setup/sync code — it's the rule that drove removing `cmd_once`, `_have_watchman`, watchman-host-fallback, the distrobox-optional path, and the existence-check-before-recreate ceremony.
Every cmd_init step except system-deps lives in scripts/setup/NN-<name>.sh as a self-registering "module" with a uniform read/prompt/write/apply contract. Use this when adding a new setup-time decision, refactoring a `read -rp` that re-asks on re-runs, or wiring a setting into `just doctor`.
Code comments are terse or absent — never multi-line rationale blocks, never narration of what the next line does, never explaining what's missing or why-not. Use when writing or editing any code file (.sh, .just, Containerfile, .py, compose). The repo owner and BAR contributors treat verbose comment blocks as AI clutter.
Don't probe inside the bar-dev distrobox container for things `dev.Containerfile` is supposed to install. Use this when touching `setup.sh`, `dev.Containerfile`, or distrobox-related plumbing — it explains why we removed several layers of "diligent" if-statements and what to do instead.
Hard-won facts about the WSL2 ↔ Windows sync daemon (sync.py, sync.sh, launch.sh). Read this before changing how files cross the WSL/Windows boundary, before adjusting watchman/rsync invocations, before "improving" the cold-copy path, or before proposing a different sync architecture.