Add AGENTS.md to document repository structure and development guidelines

- Introduced `AGENTS.md` to provide an overview of the repository layout and working conventions.
- Included guidance for firmware, hardware, and website contributions.
- Added validation, file hygiene, and handoff expectations for consistent development practices.

AGENTS.md

@@ -0,0 +1,62 @@
+# 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.