# Project instructions

## Beads

This project uses `bd` (Beads) as the source of truth for work tracking.

At the beginning of a work session run:

```sh
bd prime
bd status
bd ready --exclude-type epic
```

Claim the selected bead before changing code and close it only after its acceptance criteria and relevant checks pass. Create follow-up beads for newly discovered work and connect real blockers with `bd dep add`.

The current Beads database is local-only embedded Dolt. No Git or Dolt remote is configured, so do not claim that changes were pushed. At the end of a session:

1. run the relevant quality gates;
2. update or close the active bead;
3. run `bd dep cycles` after dependency changes;
4. export a readable snapshot with `bd export --output .beads/issues.jsonl`;
5. commit local source and tracking changes when appropriate;
6. report explicitly that synchronization remains local until a remote is configured.

Do not edit `.beads/issues.jsonl` manually. The source of truth is `.beads/embeddeddolt`.

## Build and tests

```sh
./gradlew clean testDebugUnitTest lintDebug assembleDebug
./gradlew connectedDebugAndroidTest
```

The connected test command requires a running Android device or emulator.

## Product documents

- `docs/DEVELOPMENT_PLAN.md` — approved GDD + TDD + production roadmap.
- `docs/CURRENT_ROADMAP.md` — current execution sequence.
- `docs/BEADS_WORKFLOW.md` — backlog structure and operator commands.