docs(sync): add README/AGENTS.md, fix hardware docs, sync central brain

- Add root README.md and AGENTS.md for hardware repo

- Fix cross-repo and internal broken links

- Document hardware/common/scripts

- Populate v2.9 placeholder READMEs

- Update replica-omnisciente central brain pointer

AGENTS.md

@@ -0,0 +1,52 @@
+# 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 |
+
+### Sync note
+
+The `replica-omnisciente/` subtree has its own `AGENTS.md`; its sync command is `.aurelio/sync.py`, not `sync.sh`.

README.md

@@ -0,0 +1,39 @@
+# Savearth Hardware Repository
+
+## WHY
+
+This repository is the canonical hardware design home for the Savearth smart-shower flow-meter device. It holds every PCB revision from early prototypes through the current production design and the next mitigation spin. Keeping hardware sources, manufacturing outputs, and analysis docs in one place lets firmware, manufacturing, and field-support teams work from the same truth.
+
+## HOW
+
+The repository is organised by hardware version under `hardware/`. Each version contains its native EDA project, extracted BOM, parsed schematic data, and manufacturing outputs. Shared component libraries and Python automation scripts live in `hardware/common/`. Design decisions and post-mortems live in `docs/`.
+
+Supported PCB versions: **v2.3, v2.4, v2.5, v2.6, v2.7, v2.8, v2.9**.
+
+## WHAT
+
+### Key documents
+
+| Document | Purpose |
+|---|---|
+| [PCB v2.8 Hardware Analysis & Fixes](docs/v2.8_hardware_analysis_and_fixes.md) | Brick/recovery root causes and the GPIO0 bodge-wire fix |
+| [PCB v2.9 Mitigation Plan](docs/v2.9_mitigation_plan.md) | Architectural changes for the next spin |
+| [Hardware Meeting Agenda — v2.8/v2.9](docs/hw_meeting_v28_v29_agenda.md) | Discussion points and decision checklist |
+| [EasyEDA Pro → KiCad Guide](docs/EASYEDA_PRO_TO_KICAD_GUIDE.md) | Migration procedure |
+| [Supply-Chain Risk Mitigation](docs/reports/supply_chain_risk_mitigation_v2_8.md) | v2.8 component risks and replacements |
+| [Hardware Automation Scripts](hardware/common/scripts/README.md) | `extract_bom.py`, `generate_jlcpcb_bom.py`, `convert_to_kicad.py`, `extract_easyeda_db.py` |
+
+### Related repositories
+
+| Repository | Role |
+|---|---|
+| [`aws-iot-core-poc`](../aws-iot-core-poc) | ESP32-S3 firmware, BSP, drivers, and test firmware |
+| `savearth-iot-infrastructure` | AWS IoT rules, Lambdas, DynamoDB, InfluxDB |
+| `hardware-devicesFirmwareTest` | Assembly-house test station and pre-built binaries |
+
+### Quick start
+
+1. Open the active design: `hardware/v2.8/easyeda/Savearth GBT.eprj` (EasyEDA Pro).
+2. Read the v2.8 analysis if you are debugging brick/recovery issues.
+3. Read the v2.9 mitigation plan before starting the next schematic spin.
+4. Use the scripts in `hardware/common/scripts/` to regenerate BOMs or convert libraries.

docs/hw_meeting_v28_v29_agenda.md

@@ -167,7 +167,6 @@ After this meeting, we should have clear answers on:
 ## Reference Documents
 
 - [v2.9 Mitigation Plan](./v2.9_mitigation_plan.md)
-- [v2.8 Brick Recovery Analysis](../../aws-iot-core-poc/docs/v2.8_brick_recovery_analysis.md)
+- [v2.8 Hardware Analysis & Fixes](./v2.8_hardware_analysis_and_fixes.md) — covers brick recovery and the GPIO0 bodge-wire fix
-- [v2.8 Flashing Guide](../../aws-iot-core-poc/docs/flashing_guide_v28.md)
 - **Jira HW issues:** HW-52, HW-55, HW-56, HW-57, HW-58
 - **Jira FW issues:** FW-200 → FW-207

docs/reports/supply_chain_risk_mitigation_v2_8.md

@@ -41,5 +41,5 @@ Four components on the Flow Meter PCB v2.8 BOM were flagged as supply chain risk
 ## References
 
 - Full analysis: [Confluence — Hardware Space](https://savearth.atlassian.net/wiki/spaces/HA/pages/46628865)
-- BOM file: `hardware/bom/bom_v2_8_jlcpcb.csv`
+- BOM file: `hardware/v2.8/bom/bom_v2_8_jlcpcb.csv`
 - Previous microphone analysis: `docs/reports/ics_43434_replacement_analysis.md`

hardware/common/easyeda_libs/EXPORT_GUIDE.md

@@ -35,12 +35,12 @@ EasyEDA Pro (.eprj)
 ### Prerequisites
 
 - **EasyEDA Pro Desktop** (latest version) — download from [easyeda.com/page/download](https://easyeda.com/page/download)
-- The project file is at: `hardware/easyeda-pro/Savearth GBT.eprj`
+- The project file is at: `hardware/v2.8/easyeda/Savearth GBT.eprj`
 
 ### Step 1: Open the Project
 
 1. Launch EasyEDA Pro Desktop
-2. `File → Open` → navigate to `hardware/easyeda-pro/Savearth GBT.eprj`
+2. `File → Open` → navigate to `hardware/v2.8/easyeda/Savearth GBT.eprj`
 3. The project tree should show all schematic versions (v1.0–v2.8)
 
 ---
@@ -55,16 +55,16 @@ EasyEDA Pro does **NOT** have an "Export → EasyEDA Source" menu. Instead, use:
 2. Go to **`File → File Source...`**
 3. A dialog opens showing the JSON source code of that document
 4. Click **"Download"** to save the file
-5. Save as: `hardware/easyeda-pro/export/savearth_v2_8_esp32.json`
+5. Save as: `hardware/v2.8/easyeda/export/savearth_v2_8_esp32.json`
-6. Repeat for **`Savearth SCH Power v2_8`** → save as `savearth_v2_8_power.json`
+6. Repeat for **`Savearth SCH Power v2_8`** → save as `hardware/v2.8/easyeda/export/savearth_v2_8_power.json`
-7. Repeat for the **PCB layout `Savearth_v2_8`** → save as `savearth_v2_8_pcb.json`
+7. Repeat for the **PCB layout `Savearth_v2_8`** → save as `hardware/v2.8/easyeda/export/savearth_v2_8_pcb.json`
 
 #### Method B: Project Save as Local (full project backup)
 
 If "File Source" doesn't give you the full data, try exporting the whole project:
 
 1. Go to **`File → Project Save as (local)`**
-2. Save the archive (ZIP or EPRO) to `hardware/easyeda-pro/export/`
+2. Save the archive (ZIP or EPRO) to `hardware/v2.8/easyeda/export/`
 3. Extract the archive — it should contain JSON Lines files for each document
 
 #### Method C: Export Netlist (fallback)
@@ -74,7 +74,7 @@ If neither method above works for the conversion pipeline:
 1. Open the v2.8 schematic
 2. Go to **`File → Export → Export Netlist`**
 3. Choose **"EasyEDA Pro"** format
-4. Save as: `hardware/easyeda-pro/export/savearth_v2_8_netlist.json`
+4. Save as: `hardware/v2.8/easyeda/export/savearth_v2_8_netlist.json`
 
 > **Note:** The netlist doesn't include graphical layout data, but it preserves all component connections which is what we need for the KiCad schematic.
 
@@ -84,7 +84,7 @@ If neither method above works for the conversion pipeline:
 
 Check that you have the files in the export directory:
 ```
-hardware/easyeda-pro/export/
+hardware/v2.8/easyeda/export/
 ├── savearth_v2_8_esp32.json    ← ESP32 schematic sheet
 ├── savearth_v2_8_power.json    ← Power management schematic sheet
 └── savearth_v2_8_pcb.json      ← PCB layout
@@ -92,7 +92,7 @@ hardware/easyeda-pro/export/
 
 Or, if you used Method B:
 ```
-hardware/easyeda-pro/export/
+hardware/v2.8/easyeda/export/
 └── savearth_project.zip        ← Full project archive
 ```
 
@@ -104,15 +104,15 @@ Each JSON file should be text (open in any editor to verify — it should contai
 
 If you want to preserve the custom component library separately:
 1. Go to **`File → Export`** and look for library export options
-2. Save as: `hardware/easyeda-pro/export/savearth_library.elibz`
+2. Save as: `hardware/v2.8/easyeda/export/savearth_library.elibz`
 
-This is the same library already in `hardware/easyeda-pro/Documentation/Library/` but ensures you have the latest version.
+This is the same library already in `hardware/common/easyeda_libs/ProLib_pcs_2026-03-05.elibz` but ensures you have the latest version.
 
 ---
 
 ## After Export — What happens next
 
-Once you place the exported files in `hardware/easyeda-pro/export/`, tell me and I will:
+Once you place the exported files in `hardware/v2.8/easyeda/export/`, tell me and I will:
 
 1. **Inspect the format** — determine if it's standard JSON or JSON Lines
 2. **Install `easyeda2kicad6`** on the system

hardware/common/scripts/README.md

@@ -0,0 +1,71 @@
+# Hardware Automation Scripts
+
+## WHY
+
+The Savearth hardware repo contains many PCB versions and manufacturing exports. Manual BOM extraction and library conversion is error-prone and not reproducible. These scripts turn the EDA source into structured JSON, JLCPCB CSVs, and KiCad libraries in a repeatable way.
+
+## HOW
+
+All scripts are Python 3 and read from/write to the per-version directories under `hardware/`. They share a common version list (`2_3` through `2_8`) and use the file naming convention `bom_v{version}.json`.
+
+Run each script with `--help` for full argument lists.
+
+## WHAT
+
+### `extract_bom.py`
+
+Extract component data from EasyEDA Pro `.epro` archives.
+
+```bash
+python3 hardware/common/scripts/extract_bom.py \
+    --epro-dir hardware/v2.8/easyeda \
+    --output-dir hardware/v2.8/bom
+```
+
+Outputs:
+- `bom_v2_8.json` — structured BOM with LCSC, manufacturer, footprint, value, category
+- Updates `hardware/savearth_hw_knowledge.json` with cross-version data
+
+### `generate_jlcpcb_bom.py`
+
+Generate a JLCPCB-compatible CSV from a JSON BOM produced by `extract_bom.py`.
+
+```bash
+python3 hardware/common/scripts/generate_jlcpcb_bom.py \
+    --bom-dir hardware/v2.8/bom \
+    --version 2_8
+```
+
+Output: `hardware/v2.8/bom/bom_v2_8_jlcpcb.csv`
+
+### `convert_to_kicad.py`
+
+Convert LCSC parts to KiCad symbol/footprint/3D libraries via `easyeda2kicad`.
+
+```bash
+python3 hardware/common/scripts/convert_to_kicad.py \
+    --bom-dir hardware/v2.8/bom \
+    --kicad-lib-dir hardware/common/kicad_libs
+```
+
+Requires `easyeda2kicad` to be installed (`pip install easyeda2kicad`).
+
+### `extract_easyeda_db.py`
+
+Parse the SQLite-backed `.eprj` project directly to raw JSON schematics, netlists, and BOMs.
+
+```bash
+python3 hardware/common/scripts/extract_easyeda_db.py \
+    --db-path hardware/v2.8/easyeda/Savearth\ GBT.eprj \
+    --output-dir hardware/v2.8/parsed_data
+```
+
+Useful when you have the binary `.eprj` but no manual `.epro` export.
+
+## Typical workflow
+
+1. Export or locate the EasyEDA Pro source (`.epro` or `.eprj`).
+2. Run `extract_bom.py` (or `extract_easyeda_db.py` for `.eprj`) to refresh `bom_v2_8.json`.
+3. Run `generate_jlcpcb_bom.py` to refresh the assembly CSV.
+4. Run `convert_to_kicad.py` if the KiCad library needs updating.
+5. Commit the generated files and update any affected docs.

hardware/v2.9/README.md

@@ -55,7 +55,7 @@ hardware/v2.9/
 
 ## Related Documents
 
-- [`docs/v2.9_mitigation_plan.md`](/docs/v2.9_mitigation_plan.md)
+- [`docs/v2.9_mitigation_plan.md`](../../docs/v2.9_mitigation_plan.md)
-- [`docs/hw_meeting_v28_v29_agenda.md`](/docs/hw_meeting_v28_v29_agenda.md)
+- [`docs/hw_meeting_v28_v29_agenda.md`](../../docs/hw_meeting_v28_v29_agenda.md)
-- [`docs/v2.8_hardware_analysis_and_fixes.md`](/docs/v2.8_hardware_analysis_and_fixes.md)
+- [`docs/v2.8_hardware_analysis_and_fixes.md`](../../docs/v2.8_hardware_analysis_and_fixes.md)
 - Jira: HW-52, HW-55, HW-56, HW-57, HW-58

hardware/v2.9/altium/README.md

@@ -8,3 +8,9 @@ Expected files:
 - `Savearth_v2_9.pcbdoc` — PCB layout.
 - `Savearth_v2_9/1_Savearth SCH ESP32 v2_9.schdoc` — ESP32/MCU schematic.
 - `Savearth_v2_9/2_Savearth SCH Power v2_9.schdoc` — Power management schematic.
+
+## Related documents
+
+- [v2.9 Mitigation Plan](../../../docs/v2.9_mitigation_plan.md)
+- [v2.8 Hardware Analysis & Fixes](../../../docs/v2.8_hardware_analysis_and_fixes.md)
+- [Hardware Meeting Agenda — v2.8/v2.9](../../../docs/hw_meeting_v28_v29_agenda.md)

hardware/v2.9/bom/README.md

@@ -17,3 +17,9 @@ The v2.9 BOM is expected to add one or more of the following, depending on the a
 - Optional PIR output RC filter components.
 
 Until the schematic is ready, this directory intentionally contains only this placeholder.
+
+## Related documents
+
+- [v2.9 Mitigation Plan](../../../docs/v2.9_mitigation_plan.md)
+- [v2.8 Hardware Analysis & Fixes](../../../docs/v2.8_hardware_analysis_and_fixes.md)
+- [Hardware Meeting Agenda — v2.8/v2.9](../../../docs/hw_meeting_v28_v29_agenda.md)

hardware/v2.9/easyeda/README.md

@@ -9,4 +9,9 @@ Expected files:
 - `Savearth SCH Power v2_9.epro` — Power management subsystem schematic.
 - `Savearth GBT.eprj` — Optional local library/project archive.
 
-The v2.9 schematic will implement the mitigations documented in `docs/v2.9_mitigation_plan.md`.
+The v2.9 schematic will implement the mitigations documented in [`../../../docs/v2.9_mitigation_plan.md`](../../../docs/v2.9_mitigation_plan.md).
+
+## Related documents
+
+- [v2.8 Hardware Analysis & Fixes](../../../docs/v2.8_hardware_analysis_and_fixes.md)
+- [Hardware Meeting Agenda — v2.8/v2.9](../../../docs/hw_meeting_v28_v29_agenda.md)

hardware/v2.9/manufacturing/README.md

@@ -8,3 +8,9 @@ Expected files:
 - `PickAndPlace_Savearth_v2_9_YYYY-MM-DD.xlsx` — Centroid / pick-and-place file.
 - `BOM_Savearth_v2_9_YYYY-MM-DD.xlsx` — Manufacturing BOM.
 - `3D_Savearth_v2_9_YYYY-MM-DD.step` — 3D mechanical model.
+
+## Related documents
+
+- [v2.9 Mitigation Plan](../../../docs/v2.9_mitigation_plan.md)
+- [v2.8 Hardware Analysis & Fixes](../../../docs/v2.8_hardware_analysis_and_fixes.md)
+- [Hardware Meeting Agenda — v2.8/v2.9](../../../docs/hw_meeting_v28_v29_agenda.md)

hardware/v2.9/parsed_data/README.md

@@ -7,3 +7,9 @@ Expected files:
 - `schematic_raw.json` — Raw component/nets extracted from the schematic.
 - `bom_extended.json` — Enriched BOM with supplier data.
 - `netlist.json` — Connectivity netlist for automated checks.
+
+## Related documents
+
+- [v2.9 Mitigation Plan](../../../docs/v2.9_mitigation_plan.md)
+- [v2.8 Hardware Analysis & Fixes](../../../docs/v2.8_hardware_analysis_and_fixes.md)
+- [Hardware Meeting Agenda — v2.8/v2.9](../../../docs/hw_meeting_v28_v29_agenda.md)

replica-omnisciente

@@ -1 +1 @@
-Subproject commit a2e40dd556549cccea230cfa266a9ce92f33fade
+Subproject commit 4b39d2ea0238644c0a60352a8f7ebf7956c8c88c