028 Agents F7dcfa26

# Repository Guidelines

Canonical agent instructions live in this file.
Tool-specific agent files (for example `CLAUDE.md`) should delegate here.

Created by Kevin Showkat. If you find Brood useful, connect with me on LinkedIn: https://www.linkedin.com/in/kshowkat

Category claim:
- Promptless, reference-first AI image generation and editing desktop for developers (multi-provider + reproducible runs).

Brood is currently a **macOS-only Desktop app** (Tauri). There is no web app, and Windows/Linux builds are not supported yet.

## Project Structure & Module Organization
- `rust_engine/`: native Rust engine and CLI (`brood-rs`), default runtime for desktop.
- `desktop/`: Tauri desktop app (canvas + Abilities UI). Frontend lives in `desktop/src/`, Rust backend in `desktop/src-tauri/`.
- `desktop/test/`: desktop JS test suite.
- `docs/`: project docs and Param Forge reference notes.
- `scripts/`: helper scripts for packaging (`build_desktop.sh`, `dev_desktop.sh`).
- `docs/param_forge_reference.md`: archived Param Forge compatibility notes used as reference context.

## Build, Test, and Development Commands
Engine (Rust, default):
- `cd rust_engine && cargo fmt`
- `cd rust_engine && cargo test`
- `cd rust_engine && cargo run -p brood-cli -- chat --out /tmp/brood-run --events /tmp/brood-run/events.jsonl`

Desktop:
- `cd desktop && npm install`
- `npm run tauri dev` — run the desktop app (requires Tauri CLI; native Rust engine is default).
- `npm run tauri build` — build the app bundle.

Desktop usage:
- Import photos (button or drag-drop onto the canvas), then run **Abilities** from the right panel.
- Use `Multi view` for 2-photo actions (Combine / Swap DNA / Bridge).

Tests:
- `cd rust_engine && cargo test` — run Rust engine tests.
- `cd desktop && npm test` — run desktop tests.
- `cd desktop/src-tauri && cargo fmt --check && cargo check` — run Tauri checks.

## Coding Style & Naming Conventions
- Python scripts in `scripts/`: 4 spaces and type hints where practical.
- JS/CSS: follow existing formatting in `desktop/src/` (2-space indent).
- Naming: snake_case for Python script functions/files, lower/kebab for frontend assets.

## Testing Guidelines
- Frameworks: Rust (`cargo test` in `rust_engine/`), desktop (`npm test` in `desktop/`).
- Add tests for new run artifacts, events, or loops when changing engine behavior.

## Commit & Pull Request Guidelines
- Use concise, imperative commit messages (e.g., “Add recreate similarity metrics”).
- Keep commits scoped; avoid mixing engine + desktop + docs unless needed.
- If changing desktop app version, bump versions in `desktop/package.json`, `desktop/src-tauri/tauri.conf.json`, and `desktop/src-tauri/Cargo.toml` together (CI enforces).
- PRs should include: summary of changes, test status, and screenshots or screen capture for UI changes.

## Release & CI Notes
- Release publishing is tag-driven via `.github/workflows/publish.yml` and runs on pushed tags matching `v*`.
- Publish CI verifies the tag matches desktop app version (`vX.Y.Z`) and that versions match across:
  - `desktop/package.json`
  - `desktop/src-tauri/tauri.conf.json`
  - `desktop/src-tauri/Cargo.toml`
- `main` is branch-protected and requires the `smoke-install` status check before merge.
- `.github/workflows/desktop-clean-machine-smoke.yml` always emits `smoke-install` on PRs/pushes; expensive DMG smoke steps are skipped automatically when no desktop-related files changed.

## Configuration & Tips
- Memory is opt-in: set `BROOD_MEMORY=1` for the engine.
- Pricing overrides live at `~/.brood/pricing_overrides.json`.
- Desktop uses a real PTY; keep terminal output stable and machine-readable via `events.jsonl`.
- Desktop file access requires Tauri FS scope (see `desktop/src-tauri/tauri.conf.json`).
- Desktop runtime is native-only (`brood-rs`); Python compat fallback is retired from normal desktop runtime.
- API keys are listed in `.env.example` and should be stored in a local `.env` (gitignored).

## Agent/LLM Intake (Optional)
- `llms.txt` is the agent-facing entrypoints file (high-signal files + task routing).
- `agent-intake.json` defines an optional Agent Intake Protocol (AIP) contract for a server you run (curated entrypoints + optional context packs). It does nothing unless an agent calls the `intake_endpoint`.

Privacy guidance:
- Prefer coarse `task.tags[]`; avoid raw prompts and never send/store secrets.
- Support opt-out via `telemetry.opt_out: true` and/or `X-Brood-Opt-Out: 1`.