# Agent Guide: savearth-hw-project

## WHY

This repository stores the Savearth smart-shower flow-meter hardware. Agents editing here need to keep mechanical, electrical, manufacturing, and firmware contexts aligned, because a schematic change in `hardware/v2.9/easyeda/` can force a BSP update in `aws-iot-core-poc`, a BOM update in `hardware/v2.9/bom/`, and a Confluence page update.

## HOW

- Work by hardware version: active production design is `hardware/v2.8/`, next spin is `hardware/v2.9/`.
- Use the Python scripts in `hardware/common/scripts/` for repeatable BOM extraction and library conversion; do not hand-edit generated JSON/CSV files unless the source EDA project has changed.
- Maintain parity between markdown docs in `docs/` and Confluence pages in the Hardware space.
- When you touch files referenced by `AGENTS.md`, update this file too.

## WHAT

### Directory layout

| Path | Contents |
|---|---|
| `hardware/v2.3/…v2.7/` | Legacy Altium and EasyEDA designs |
| `hardware/v2.8/` | Active EasyEDA Pro production design, BOM, manufacturing outputs, parsed data |
| `hardware/v2.9/` | Placeholder for next mitigation spin |
| `hardware/common/` | Shared KiCad/EasyEDA libraries and automation scripts |
| `docs/` | Analysis, guides, meeting notes, and reports |
| `.aurelio/memory/` | Agent memory index and log |

### Key scripts

See `hardware/common/scripts/README.md` for details.

| Script | Purpose |
|---|---|
| `extract_bom.py` | Extract BOM from EasyEDA Pro `.epro` exports |
| `generate_jlcpcb_bom.py` | Build JLCPCB-compatible CSV from extracted JSON |
| `convert_to_kicad.py` | Convert LCSC parts to KiCad symbols/footprints/3D |
| `extract_easyeda_db.py` | Parse the SQLite `.eprj` directly |

### Confluence mirror expectations

Every document in `docs/` must have a corresponding Confluence page in the Hardware space. When you add, move, or rename a doc, mirror the change on Confluence or flag it in the commit message.

### Related repositories

| Repository | Local path | Role |
|---|---|---|
| `aws-iot-core-poc` | `../aws-iot-core-poc` | Firmware and BSP |
| `savearth-iot-infrastructure` | `../savearth-iot-infrastructure` | Cloud backend |
| `hardware-devicesFirmwareTest` | `../hardware-devicesFirmwareTest` | Assembly-house test station |

### Local Aurelio Workspace

This repository contains a local `.aurelio/` workspace configured for the `flow-meter-pcb` realm. It replaces the previous external Git submodule and connects directly to `savearth-mcp`, `savearth-workspace`, and the electrical MCP servers (`electrical-eda-mcp`, `electrical-sourcing-mcp`).

Tracked bootstrap files:

| File | Purpose |
|---|---|
| `.aurelio/config.toml` | Realm identity (`savearth Flow Meter PCB`, `flow-meter-pcb`, v2.8.0), sync endpoint, model defaults |
| `.aurelio/mcp_config.json` | MCP server declarations scoped to hardware work |
| `.aurelio/sync.py` | Push/pull the local `brain/` to the central Aurelio host |
| `.aurelio/README.md` | Workspace documentation |
| `.aurelio/realm/AGENTS.md` | Realm-specific agent guide |
| `.aurelio/realm/memory/index.md` | Starter memory index |

Use `python3 .aurelio/sync.py --pull` to fetch the latest central brain and `python3 .aurelio/sync.py --push` to publish local memory changes. Runtime brain artifacts under `.aurelio/brain/` and `.aurelio/memory/` are ignored by Git.