# 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 uses `brainwave` only as a code name. Formal product name,
organization-owned application ID, and final `minSdk` remain product decisions.
Until they are accepted, the `app` project is a Kotlin/JVM domain harness, not a
publishable Android application. Do not invent placeholder release identity.

## Verification

Run from the repository root:

```powershell
.\gradlew.bat verifyLocal --offline
```

After the Android application plugin is configured, also run the Android gates
listed in `docs/quality-gates.md`. Report skipped device or Android checks
explicitly; do not imply they passed.