# Development

- Prefer simple, idiomatic Rust; reuse existing code and dependencies before adding abstractions or crates.
- Keep changes focused, handle errors explicitly, and add the smallest useful test for non-trivial behavior.
- Preserve `rustfmt` output and keep Clippy warning-free.
- Each model family has one behavioral oracle. Model execution, token processing, sampling/RNG, context accounting, and KV-cache/session behavior must remain identical to it. Differences are bugs unless they are unavoidable Rust/platform requirements and the user explicitly approves them before implementation; when uncertain, preserve the oracle's behavior.
  - DeepSeek and GLM models: DS4.
  - Qwen 3.8 Flash Next: the pinned MTPLX revision. Follow its current execution route, not only its numerical results.
- Keep family-specific behavior in that family's code. Before changing a helper shared across families, trace every caller and keep the other families' oracle behavior exact, with regression controls.
- Keep all application, model-loading, inference-graph, session, and orchestration code in Rust. Never copy, vendor, compile, or call DS4's C implementation or MTPLX/MLX Python; use them only as behavioral and performance references. Native code is limited to the Objective-C Metal bridge and `.metal` kernels required to execute GPU work.
- This is not a GitHub project. Use direct `git` commands for version control and the `tea` CLI for forge operations; do not use GitHub tools or workflows.
- Issues are managed with the command "tea" run from the project directory.

## Visual language

- Follow the Codex macOS dark UI: near-black backgrounds, subtly raised surfaces, quiet borders, rounded corners, and restrained contrast.
- Present overviews as one bordered panel with divided rows, a clear primary label, muted supporting text, and compact trailing actions.
- Reuse the shared surface and action-button styles in `src/app/view.rs`; keep button shape, padding, typography, hover, and disabled states consistent across windows. Destructive actions may differ by color only, while navigation controls may remain flat.
- Render boolean controls as macOS-style slider toggles through the shared `toggle` helper, not checkboxes.
- Prefer generous spacing and clear hierarchy over decoration; avoid one-off colors, card stacks, oversized controls, and screen-specific button styling.

## Commit gates

Run before every commit:

```sh
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
make bundle
cargo test --all-features
```

## Commit messages

Use a short, imperative subject describing one change. Skip prefixes and bodies unless they add necessary context.