# AGENTS.md

## Scope
These instructions apply to the entire repository unless a deeper `AGENTS.md` overrides them.

## Repository Overview
`PlantCtrl` is a mixed-discipline repository with embedded firmware, shared Rust crates, hardware design files, and a Hugo-based website.

Top-level layout:
- `Software/MainBoard/rust`: main embedded Rust firmware for the controller board (`plant-ctrl2`).
- `Software/CAN_Sensor`: embedded Rust firmware for the CAN sensor / BMS board.
- `Software/Shared/canapi`: shared Rust crate used by firmware projects.
- `Hardware`: PCB, case, and related hardware design assets.
- `DataSheets`: reference material; treat as source data, not generated output.
- `website`: Hugo site based on the Blowfish theme.
- `bin`: helper scripts and local tooling, if present.

## Working Rules
- Keep changes tightly scoped to the user request; this repo spans hardware, firmware, and website code.
- Prefer fixing the underlying cause instead of applying cosmetic workarounds.
- Preserve existing file structure and naming unless the user explicitly asks for restructuring.
- Avoid mass formatting or opportunistic cleanup in KiCad files, lockfiles, generated assets, or vendored dependencies.
- Do not edit dependency directories such as `website/themes` or `Software/MainBoard/rust/src_webpack/node_modules` unless the user explicitly asks for vendor changes.
- When touching firmware code, keep resource usage and target constraints in mind; avoid unnecessary allocations or feature creep.

## Firmware Guidance
- Shared protocol or serialization changes must be checked for impact across both `Software/MainBoard/rust` and `Software/CAN_Sensor`.
- Prefer small, explicit changes in embedded code paths; do not introduce heavyweight abstractions without a clear payoff.
- Keep `no_std`/embedded assumptions intact unless the code clearly opts into something else.
- Be careful with feature flags, target-specific dependencies, and boot/runtime configuration in Cargo manifests.

## Hardware Guidance
- Treat hardware directories as design artifacts, not generic text files.
- Do not reorder, normalize, or bulk-edit PCB / CAD files unless the user specifically requests those changes.
- If a software change depends on hardware assumptions, call that out clearly in the final handoff.

## Website Guidance
- The site in `website` uses Hugo with the Blowfish theme.
- Prefer editing site content, config, or custom assets over modifying vendored theme internals.
- Keep frontend changes consistent with the existing site structure unless the user asks for a redesign.

## Validation
Use the narrowest relevant check first.

Useful commands:
- `cargo check --manifest-path Software/Shared/canapi/Cargo.toml`
- `cargo check --manifest-path Software/CAN_Sensor/Cargo.toml`
- `cargo check --manifest-path Software/MainBoard/rust/Cargo.toml`
- `npm run dev` from `website` for local Hugo development if the environment has the required tools installed.

Validation notes:
- Embedded firmware may require target-specific toolchains or hardware-adjacent tooling that is not always available.
- If you cannot run a meaningful validation step, say so explicitly and describe the likely prerequisite.

## File Hygiene
- Read large files in chunks.
- Prefer targeted searches (`rg`, or `find` if unavailable) over broad scans.
- Do not commit build outputs, generated binaries, or local IDE metadata unless the user explicitly requests it.

## Handoff Expectations
- Summarize what changed, where it changed, and any validation performed.
- Call out follow-up work when a change likely affects both firmware targets, hardware assumptions, or the website.