# Brainwave agent guide

This file is the short repository entry point. The detailed, authoritative map is
[`docs/README.md`](docs/README.md).

## Start here

1. Read `docs/agent-playbook.md` before changing files.
2. Read `docs/environment.md` before build, SDK, device, or dependency work.
3. Read the relevant product/domain/architecture document from `docs/README.md`.
4. Follow `docs/implementation-plan.md`; never silently turn an item in
   `docs/decisions.md#未决问题` into a product fact.

## Discovery

Prefer the configured codebase knowledge-graph tools in this order:
`search_graph`, `trace_path`, `get_code_snippet`, `query_graph`, then
`get_architecture`. Fall back to `rg` for literals, non-code files, or when those
tools are unavailable or insufficient. State the fallback in the handoff.

## Non-negotiable domain rules

- The three physical coins are entered manually; do not add random casting.
- `字 = 2`, `背 = 3`; record six lines from bottom to top.
- Sums `6` and `9` move; sums `7` and `8` remain static.
- King Wen numbering is a lookup table, never `binary + 1`.
- Casting code remains pure Kotlin with no Android, Compose, database, or network
  dependency.
- AI is opt-in explanation only. Do not place provider secrets in the app or repo.

## Current build boundary

The repository keeps `brainwave` only as its code name. The accepted Android
identity is product name `灵机`, namespace/application ID `net.opcapp.flash`, and
`minSdk` 26. The `app` project is an installable Android application; the app icon
and store assets remain product decisions and must not be silently finalized.

## Verification

Run from the repository root:

```powershell
.\gradlew.bat verifyLocal
```

`verifyLocal` includes Android lint, debug unit tests, APK assembly, repository
checks, and dependency-license coverage. Run `connectedDebugAndroidTest` separately
when an authorized device is present, and report skipped device checks explicitly.