---
name: bosch-molecule-generator
description: Guides schematic design of Bosch component molecules on 8x8, 16x16, or 16x32 grids using medium machine pins and contacts with standardized I2C pinout and corner power/ground layout.
---

# Bosch Molecule Generator

Design Bosch component molecules as KiCad schematics with a fixed pin/contact layout. Focus is schematic-first — PCB placement is pin/contact placement only, no routing.

## Before you start

1. **Ask the user which molecule size they want.** Valid sizes are `8x8`, `16x16`, and `16x32`. If they pick anything else, tell them only those three sizes are available and ask them to choose one.
2. **Identify the Bosch component.** Look up the datasheet to determine which pins exist (I2C, interrupts, reset, address select, etc.).
3. **If the chip has SPI functionality**, tell the user: "This component has SPI functionality — this molecule only supports the I2C interface. SPI lines will not be included in the schematic." Then proceed with I2C only.
## Library setup — always use the user's personal desktop library

**All symbols, footprints, and STEP files must be added to the user's personal KiCad library on their desktop machine, NOT the Adom internal library on the Docker container.**

This requires an active Adom Desktop connection. Before doing any library work:

1. **Verify Adom Desktop is connected.** Run `adom-desktop status` to check. If the desktop is not connected, tell the user: "You need Adom Desktop connected to add parts to your personal KiCad library. Please connect Adom Desktop and try again." Do not proceed until the connection is confirmed.
2. **Send files to the desktop** using `adom-desktop send_file` (or the Conduit file transfer mechanism) to place symbols, footprints, and STEP files into the user's personal KiCad library path on their local machine.

### Adom KiCad library (REQUIRED — machine pins and contacts)

**The Adom KiCad library is mandatory.** It contains the medium machine pin and medium contact symbols and footprints that every molecule uses. You must NEVER create your own versions of these — always use the ones from the Adom library.

Before doing anything else, verify the Adom KiCad library exists on the user's desktop:

1. Check both the sym-lib-table and fp-lib-table for entries containing "adom" or "Adom_BLT".
2. Verify the footprint library directory exists and contains `MachinePinMediumStandard.kicad_mod` and `MachineContactMedium.kicad_mod`.
3. Verify the symbol library file exists and contains MachinePinMedium and MachineContactMedium symbols.

**If ANY of these are missing**, stop and tell the user:
> "Your KiCad installation is missing the Adom KiCad library, which contains the machine pins and contacts required for molecule design. You need to download and install it before we can proceed."

Then guide them to install it:
1. Search the Adom Wiki: `adom-wiki page search "adom kicad library" --deep`
2. Install via: `adom-wiki app install adom-kicad-library` (or download from the wiki page)
3. Send the library files to their desktop and add the library paths to their KiCad project (symbol and footprint lib tables)

**Do not proceed until machine pins and contacts are confirmed present in the user's desktop library. Do not create substitutes.**

### Bosch component and supporting parts — sourcing order

For the Bosch chip and any other components needed (LDO, capacitors, resistors, etc.), follow this strict sourcing order. **Never create symbols or footprints yourself unless all other sources are exhausted.**

**ALWAYS check the user's existing libraries FIRST.** Many standard parts (0402 caps, common resistors, connectors) are already installed in most KiCad setups. Do not download or create duplicates of parts the user already has.

#### Sourcing priority (follow in order — do not skip steps):

1. **Check the user's personal KiCad libraries first (MOST IMPORTANT)** — pull and grep their sym-lib-table and fp-lib-table, then search the actual `.kicad_sym` files on their desktop for the part name, package, or manufacturer. **This applies to ALL components, not just basic passives (R, L, C).** Users often have ICs, sensors, connectors, and specialty parts from previous projects already in libraries like `JLC_Misc_BLT`, `Bosch_Sensors`, etc. **If it exists in any user library, use it. Do not add another copy. Do not download a duplicate from the internet.**
2. **Check the Adom Wiki** — `adom-wiki page search "<part number>" --deep`. The wiki may have the part from a previous molecule or project.
3. **Search JLCPCB/LCSC and convert with easyeda2kicad** — the `easyeda2kicad` tool (pre-installed) can convert any LCSC part to KiCad format: `easyeda2kicad --full --lcsc_id=CXXXXXXX --output=<name>`. This generates symbol, footprint, and 3D model. **Verify pin names/numbers against the datasheet** — EasyEDA symbols sometimes use SPI-mode pin names instead of I2C primary names, or have all pins typed as "unspecified." Fix pin names and electrical types before importing.
4. **Search other online sources** — SnapEDA, Ultra Librarian, Component Search Engine, manufacturer websites, GitHub community libraries.
5. **Last resort only: create the symbol/footprint yourself** — if the part cannot be found anywhere. When creating, follow KiCad Library Convention (KLC) guidelines. Always tell the user you had to create it and that they should verify pin assignments against the datasheet.

**Do NOT default to KiCad's pre-packaged standard libraries** (e.g., `Sensor_Motion`, `Device`) for components beyond basic passives. The user's personal libraries contain parts with correct LCSC part numbers, footprint associations, and verified pin mappings tailored to their workflow. KiCad standard libraries are a fallback for basic footprints like `Capacitor_SMD:C_0402_1005Metric`, not a primary source for ICs or sensors.

#### For each part, you need three files:
1. **KiCad symbol** (`.kicad_sym`) — schematic symbol with correct pin names, numbers, and electrical types.
2. **KiCad footprint** (`.kicad_mod`) — PCB land pattern matching the datasheet package drawing.
3. **STEP file** (`.step`) — 3D model for the footprint.

**Send all three to the user's desktop** and place them in the correct location within their library structure (see "Library file placement" below).

Do this for every part that is not already in the user's library — including decoupling caps, the LDO (if needed), and the jumper contacts (if needed).

### Library file placement — respect the user's organization

Before adding any new symbol, footprint, or STEP file, **inspect the user's existing library structure** to understand how it is organized. Many users organize their libraries categorically (by manufacturer, component type, or function).

#### How to detect the organization:

1. **List the user's writable symbol libraries** from `sym-lib-table` — look at the library names and file paths. Check for patterns like manufacturer names (e.g., `JLC_Misc_BLT`, `Bosch_Sensors`, `TI_Power`), component categories (e.g., `Capacitors`, `Connectors`, `ICs`), or flat naming.
2. **List the user's writable footprint libraries** from `fp-lib-table` — footprint libraries are directories, so list the folder names. Look for the same organizational patterns.
3. **Check for STEP/3D model directories** — look for a 3D models folder near the footprint libraries. It may be organized by manufacturer (e.g., `3DModels/Bosch/`, `3DModels/TI/`) or by component type.

#### Placement rules:

- **If the libraries are categorically organized** and you find a category that fits the new part, **add the part to that existing library**:
  - Symbol: append the new symbol to the matching `.kicad_sym` file (e.g., a Bosch accelerometer symbol goes into `JLC_Misc_BLT.kicad_sym` or `Bosch_Sensors.kicad_sym` if one exists).
  - Footprint: place the `.kicad_mod` file into the matching footprint library directory (e.g., a Bosch footprint goes into the `Bosch/` or `Bosch.pretty/` footprint folder).
  - STEP file: place the `.step` file into the matching manufacturer/category subfolder within the 3D models directory.
- **If no existing category fits**, create a new library with a name that matches the user's naming convention. For example, if the user has `JLC_Resistors_BLT` and `JLC_Capacitors_BLT`, a new Bosch sensor library might be named `JLC_Sensors_BLT` or `Bosch_Sensors`.
- **If the libraries are not categorically organized** (flat structure, single library, etc.), place files wherever the user's existing parts live — ask the user if unclear.
- **Never create a standalone library named after a single part** (e.g., `BMA580.kicad_sym`) if there is already a categorical library it belongs in. Standalone part-named libraries clutter the user's library list.

#### Match existing symbol/footprint conventions

Before adding a new part to a user's library, **read 2–3 existing symbols or footprints in that same library file/directory** and look for consistent conventions. Match whatever patterns you find, including:

- **Property ordering and formatting** — which properties are present (Value, Footprint, Datasheet, Description, LCSC PN, etc.), what order they appear in, how they are formatted (quoted vs. unquoted, visible vs. hidden).
- **Pin naming style** — uppercase vs. mixed case, abbreviation conventions (e.g., `VDD` vs `Vdd`, `~{RESET}` vs `RESET_N`), whether power pins use specific naming.
- **Symbol geometry** — pin length, text size, box dimensions, pin grouping style.
- **Footprint naming** — naming pattern for `.kicad_mod` files (e.g., `BMA580_WLCSP-6` vs `BMA580-WLCSP6`), whether package info is in the name.
- **Custom fields** — if every symbol has a `"LCSC PN"` field, the new symbol must too. If they all have `"Manufacturer"` or `"MPN"` fields, add those as well.

The goal is that the new part looks like it was always part of the user's library — not an obvious addition from an external tool with different formatting.

### JLCPCB / LCSC part numbers

**For every component in the schematic, look up whether it is available on JLCPCB (jlcpcb.com/parts or lcsc.com).** If it is:

1. Add the **LCSC part number** (e.g., `C12345`) as a custom field on the KiCad symbol:
   - **Check the user's existing library symbols for the field name convention.** Common names are `"LCSC PN"` or `"LCSC"`. **Match whatever the user's library already uses** — do not guess. If the user has `"LCSC PN"` on their other symbols, use `"LCSC PN"`.
   - Field value: the LCSC part number (e.g., `C2838043`)
2. Also note in the symbol's description or a `JLCPCB_Note` field whether the part is:
   - **Basic** (no extra fee, stocked at JLCPCB)
   - **Extended** (small setup fee per unique extended part)
3. Prefer **JLCPCB Basic parts** for common passives (0402 caps, resistors) when multiple options exist.

This ensures the BOM is assembly-ready for JLCPCB orders without manual part number lookup later.

## Pin and contact rules

**All pins and contacts are medium machine pins and medium contacts.** No other size or type.

### Corner machine pins (all sizes)

Every molecule has four corner machine pins. The rule is the same regardless of grid size:

| Corner | 8x8 position | 16x16 position | 16x32 position | Net |
|--------|-------------|----------------|----------------|-----|
| Top-left | (0, 0) | (0, 0) | (0, 0) | **3.3V** |
| Top-right | (8, 0) | (16, 0) | (16, 0) | **GND** |
| Bottom-left | (0, 8) | (0, 16) | (0, 32) | **GND** |
| Bottom-right | (8, 8) | (16, 16) | (16, 32) | **GND** |

Top-left is ALWAYS 3.3V. The other three corners are ALWAYS GND.

### Signal contacts — top edge

These contacts sit along the top edge of the board. Positions are the same for all three sizes:

| Position | Signal | Notes |
|----------|--------|-------|
| (2, 0) | SCL | Only place if chip has I2C clock pin |
| (4, 0) | SDA | Only place if chip has I2C data pin |
| (6, 0) | RESET | Only place if chip has a reset pin |

If the chip does not have one of these pins, leave that position empty — do not place a contact there.

### Signal contacts — bottom edge

These contacts sit along the bottom edge. The Y coordinate depends on the grid size:

| Signal | 8x8 position | 16x16 position | 16x32 position |
|--------|-------------|----------------|----------------|
| INT1 | (6, 8) | (6, 16) | (6, 16) |
| INT2 | (4, 8) | (4, 16) | (4, 16) |

If the chip has no interrupt 1 pin, leave the INT1 position empty. Same for interrupt 2. Never place a contact for an interrupt that does not exist on the chip.

### 16x32 layout note

The 16x32 grid is 16 wide and 32 tall. Compared to 16x16:
- Top-edge contacts stay at y=0 (same as 16x16)
- Bottom-edge interrupt contacts stay at y=16 (same as 16x16)
- Bottom corner machine pins move from y=16 to y=32

## I2C rules

- **Never add pull-up resistors on SDA or SCL.** Pull-ups are done externally, not on this molecule.
- Only wire I2C — ignore SPI even if the chip supports both interfaces.

## Alternate address pin (jumper molecule)

If the Bosch chip has an address-select pin (e.g., SDO/ADR):
- Use a **jumper molecule**: two medium contacts placed side by side.
- **Always pull the address pin HIGH** (connect to 3.3V through the jumper).
- Wire the jumper into the schematic so the address select is tied high by default.
- **Jumper placement**: jumpers must be placed along the **left or right edge** of the board only. Never place jumpers on the top edge, bottom edge, or internally. Jumper contacts must align to the **2mm grid**.

## 1.8V logic power

Some Bosch components require an external 1.8V supply for their digital logic interface (VDDIO pin). When the datasheet specifies a separate 1.8V logic supply:

1. **Check the datasheet** for the VDDIO current consumption (typical and max).
2. **Recommend a 3.3V-to-1.8V LDO** that can handle the component's current draw with margin. Choose an LDO with:
   - Input voltage range that covers 3.3V
   - Fixed 1.8V output
   - Output current rating above the chip's max VDDIO consumption
   - Small package (SOT-23 or similar) that fits within the molecule grid
3. **Add the LDO to the schematic** with input/output decoupling capacitors per the LDO's datasheet recommendations.
4. **Wire it**: 3.3V from the top-left corner pin feeds the LDO input; the LDO's 1.8V output connects to the Bosch chip's VDDIO pin.

If the component runs its logic interface directly on 3.3V (no separate VDDIO pin, or VDDIO accepts 3.3V), skip the LDO entirely.

## KiCad 9 schematic format rules

KiCad `.kicad_sch` files are S-expressions with strict format requirements. Getting any of these wrong causes a silent "Failed to load schematic" error with no detail.

### Critical format rules:

1. **Version and generator**: Must match the user's KiCad version. For KiCad 9: `(version 20250114)`, `(generator "eeschema")`, `(generator_version "9.0")`. Check by reading the header of any existing `.kicad_sch` on the user's machine.
2. **No comments**: KiCad's S-expression parser does NOT support `;;` comments or any comment syntax. Never write comments in `.kicad_sch` or `.kicad_mod` files.
3. **Sub-symbol naming**: In the `lib_symbols` cache, the **main symbol** uses the full `library:name` prefix (e.g., `"JLC_Capacitors_BLT:C_100nF_0402"`), but **sub-symbols** use ONLY the symbol name part (e.g., `"C_100nF_0402_0_1"`, NOT `"JLC_Capacitors_BLT:C_100nF_0402_0_1"`). This is the most common cause of load failures.
4. **`(embedded_fonts no)`**: Required inside each cached lib_symbol AND at the schematic root level (before the final closing paren).
5. **Pin instances**: Each symbol instance needs `(pin "N" (uuid ...))` entries for every pin.
6. **Symbol instances**: Each symbol instance needs `(instances (project "ProjectName" (path "/rootUUID" (reference "REF") (unit 1))))`.
7. **Indentation**: Use tabs, matching KiCad's native format.
8. **Symbol `(at X Y angle)` — angle is REQUIRED**: For symbol instances, `(at X Y)` without an angle will fail with "need a number for 'symbol orientation'". Always write `(at X Y 0)` even when unrotated.
9. **Property positions are ABSOLUTE, not relative**: The `(at X Y angle)` on each property (Reference, Value, etc.) in a symbol instance is in **absolute schematic coordinates**, NOT relative to the symbol. To position labels correctly: (1) read the library symbol's property offsets (e.g., Reference at `(0, -10.16)` means 10.16mm above the symbol origin), (2) apply the symbol's rotation to the offset, (3) add the rotated offset to the symbol's absolute position. For example, if U1 is at `(152.4, 101.6)` and the library puts Reference at offset `(0, -10.16)`, the instance Reference goes at `(152.4, 91.44)`. Hidden properties (Footprint, Datasheet, Description, LCSC PN) can stay at the symbol's position since they are not visible.
10. **Avoid floating-point artifacts**: Python float math produces values like `99.05999999999999` from `101.6 - 2.54`. Always round coordinates to 4 decimal places before writing them to the file.

### Schematic symbol caching (`lib_symbols`)

KiCad schematic files contain a `lib_symbols` section that caches a copy of every symbol used. **Do not write simplified or hand-drawn stand-ins.** Instead:

1. **Pull the actual symbol data** from the library file on the user's desktop (e.g., `pull_file` the `.kicad_sym` file, read the symbol definition, and paste it verbatim into `lib_symbols`).
2. **Fix the sub-symbol names** when caching: the main symbol gets the `library:` prefix added, but sub-symbols keep their original names (no prefix). For example, a symbol `"C_100nF_0402"` from `JLC_Capacitors_BLT` becomes `"JLC_Capacitors_BLT:C_100nF_0402"` at the top level, while its sub-symbols stay as `"C_100nF_0402_0_1"` and `"C_100nF_0402_1_1"`.
3. If you cannot pull the actual symbol data, use minimal placeholders BUT tell the user to run **"Update Symbols from Library"** (`Tools > Update Symbols from Library...`) after opening the schematic.

The `lib_id` on each symbol instance must always point to the correct library (e.g., `adom-kicad-footprint-library_BLT:MachinePin`).

### Validation before sending

Before sending the schematic to the user's desktop, always verify:
1. **Parentheses are balanced** — write a quick Python check: count `(` and `)`, confirm depth ends at 0 and never goes negative.
2. **Version matches** the user's KiCad installation.
3. **No comments** exist in the file.
4. **Sub-symbol names** do not contain library prefixes.

## PCB generation — never hand-write PCB files

**Do NOT generate `.kicad_pcb` files directly.** Hand-written PCB files will have incorrect footprint definitions, missing net associations, and broken library links.

Instead, use KiCad's built-in **"Update PCB from Schematic"** feature to generate the PCB. **Do NOT attempt to automate KiCad's GUI** (clicking buttons, sending keyboard shortcuts via xdotool, etc.) — this is unreliable and wastes time. Ask the user to perform the GUI steps.

### PCB workflow:

1. **Generate only the `.kicad_sch` file** — the schematic is the single source of truth.
2. **Send the schematic** to the user's desktop project folder.
3. **Ask the user to perform these steps in KiCad:**
   > Please do the following in KiCad:
   > 1. Open the project file (`.kicad_pro`) in the KiCad project manager — do NOT open the `.kicad_sch` directly, or it will be in standalone mode.
   > 2. Click **Schematic Editor** to open the schematic.
   > 3. In the schematic editor, click **Tools > Update PCB from Schematic** (or press F8).
   > 4. In the dialog, click **Update PCB**, then **Close**.
   > 5. Save the PCB file (Ctrl+S in the PCB editor).
   > 6. Let me know when you're done so I can position the footprints.
4. **Wait for the user to confirm** the PCB has been saved.
5. **Pull the `.kicad_pcb` file** from the user's desktop and edit the footprint positions programmatically:
   - **Bosch component (U1)**: place at the **center of the board** based on the grid size:
     - 8x8 → center at **(4, 4)**
     - 16x16 → center at **(8, 8)**
     - 16x32 → center at **(8, 16)**
   - **Corner machine pins (MP1–MP4)**: use the corner position tables in "Pin and contact rules" above.
   - **Signal contacts (MC1–MCn)**: use the edge position tables in "Pin and contact rules" above.
   - **Passives (C1, etc.)**: place near the Bosch component, inside the board outline.
6. **Set the board outline** on the Edge.Cuts layer. The board outline is **NOT the same as the grid dimensions** — it is larger and centered on the grid center:
     - **8x8 → 10.8mm × 10.8mm** centered at (4, 4)
     - **16x16 → 18.8mm × 18.8mm** centered at (8, 8)
     - **16x32 → 18.8mm × 34.8mm** centered at (8, 16)
7. **Send the updated `.kicad_pcb` back** to the user's desktop.
8. **Ask the user to reload**: "Please close and reopen the PCB editor (or press Ctrl+Shift+R) to see the updated footprint positions."
9. **Do not route anything** — routing is done separately.

### What you CAN edit in the PCB file programmatically:

After the user generates the PCB via "Update PCB from Schematic" and saves it, you can safely edit these in the `.kicad_pcb` file:
- **Footprint `(at X Y)` coordinates** — to position footprints on the grid
- **Board outline** — add/modify `(gr_line ...)` or `(gr_rect ...)` on `Edge.Cuts`
- **Footprint rotation** — modify the angle in `(at X Y angle)`

Do NOT edit: pad definitions, net assignments, footprint internals, or library references. Those are managed by KiCad.

## Workflow

1. Ask the user for the molecule size (8x8, 16x16, or 16x32).
2. Verify Adom Desktop is connected (`adom-desktop status`). If not connected, stop and tell the user they need to connect it first.
3. **Verify the Adom KiCad library exists** on the user's desktop — check for MachinePinMediumStandard and MachineContactMedium in both the symbol and footprint libraries. If missing, stop and guide the user to install it. **Do not proceed without it. Do not create substitute symbols or footprints.**
4. Identify the Bosch component and look up its pinout from the datasheet.
5. Notify the user if SPI exists (and that it will be ignored).
6. Check if the chip needs 1.8V logic power — if so, recommend a suitable LDO.
7. **Source all parts** following the strict sourcing order: user's existing libraries → KiCad standard libraries → Adom Wiki → internet (SnapEDA, Ultra Librarian, manufacturer sites) → create yourself only as a last resort. For each part, get the symbol, footprint, and STEP file. **Place them in the correct location** within the user's library structure — inspect the user's libraries for categorical organization and add parts to matching categories rather than creating standalone single-part libraries (see "Library file placement" section above).
8. **Generate the KiCad schematic only** (`.kicad_sch`):
   - Follow all rules in "KiCad 9 schematic format rules" — correct version, no comments, proper sub-symbol naming, balanced parens.
   - Set `lib_id` references to the correct library names (e.g., `adom-kicad-footprint-library_BLT:MachinePin`).
   - For the `lib_symbols` cache, pull actual symbol data from the user's library files — fix sub-symbol names (no library prefix on sub-symbols).
   - **Set the `Footprint` property explicitly on EVERY symbol instance** — MachinePin (`Adom_BLT:MachinePinMediumStandard`), MachineContact (`Adom_BLT:MachineContactMedium`), the Bosch IC, capacitors, LDOs, everything. The MachineContact symbol does NOT have a default footprint in its library definition, so it MUST be set on each instance or "Update PCB from Schematic" will fail to place it. Do not rely on the cached `lib_symbols` footprint — always set it on the instance.
   - Place the Bosch component symbol.
   - Wire corner machine pins (3.3V top-left, GND on other three).
   - Wire signal contacts (SCL, SDA, RESET on top edge; INT1, INT2 on bottom edge) — only for pins that exist on the chip.
   - Add decoupling capacitors per datasheet recommendations.
   - If an address-select pin exists, add the jumper molecule on the left or right edge (2mm grid) and tie it high.
   - If 1.8V logic power is needed, add the recommended LDO with decoupling caps.
   - Do NOT add pull-ups on SCL/SDA.
   - **Validate** parens are balanced and sub-symbol names are correct before proceeding.
   - **Do NOT write a `.kicad_pcb` file.**
9. **Send the schematic to the user's desktop** project folder. Verify it loads with `kicad-cli sch export svg`.
10. **Ask the user to generate the PCB** — do NOT try to automate KiCad's GUI. Tell the user:
    > Please open the `.kicad_pro` in KiCad's project manager, open the Schematic Editor, then go to Tools > Update PCB from Schematic (F8). Click "Update PCB", then save the PCB (Ctrl+S). Let me know when done.
11. **Wait for the user to confirm**, then pull the `.kicad_pcb` file from the desktop.
12. **Edit footprint positions** programmatically in the pulled PCB file:
    - **Bosch component (U1)** at the board center: (4,4) for 8x8, (8,8) for 16x16, (8,16) for 16x32.
    - **Corner machine pins (MP1–MP4)** and **signal contacts (MC1–MCn)** at grid positions per the "Pin and contact rules" tables.
    - **Passives** near the Bosch component, inside the board outline.
    - **Add board outline** on Edge.Cuts to match the molecule size.
13. **Send the updated PCB back** to the user's desktop and ask them to reload it.
14. Present the schematic and PCB to the user for review.

## Common mistakes to avoid

These are errors that have caused failures in past molecule generation sessions. Read before starting.

### Schematic file errors
- **Wrong version number**: Always check the user's KiCad version first. KiCad 9 uses `(version 20250114)`. Using an older version (e.g., `20231120` from KiCad 8) causes a silent load failure.
- **Library prefix on sub-symbols**: The #1 cause of "Failed to load schematic". Main symbol = `"Library:Name"`, sub-symbols = `"Name_0_1"` (NO prefix). Always verify this after generating the file.
- **Comments in S-expressions**: KiCad does NOT support `;;` or any comment syntax. Even one comment line will cause a load failure.
- **Unbalanced parentheses**: When extracting symbol data from `.kicad_sym` files, be careful with line ranges — off-by-one errors can include the library's closing paren and produce an unbalanced file. Always run a paren-depth check.
- **Wrong grid size**: If the user asks for 8x8, double-check you're not generating 16x16. Verify the grid size in the component placement coordinates.

### Library and part sourcing errors
- **Using Device:C instead of user's library**: Always check the user's existing libraries first. If they have a `JLC_Capacitors_BLT` library with `C_100nF_0402`, use that — not `Device:C` from the KiCad standard library. The user's parts have LCSC part numbers and correct footprint associations already.
- **Creating standalone single-part libraries**: If the user's libraries are categorically organized (e.g., `JLC_Misc_BLT`, `JLC_Capacitors_BLT`), add new symbols to the matching existing library file. Don't create `BMA580.kicad_sym` when `JLC_Misc_BLT.kicad_sym` exists.
- **Wrong LCSC field name**: Check what existing symbols in the user's library use. Some libraries use `LCSC PN`, others use `LCSC`. Match the existing convention.

### PCB and KiCad GUI errors
- **Never automate KiCad's GUI**: xdotool clicks and keyboard shortcuts are unreliable with KiCad on Linux. Ctrl+S doesn't always register. Clicking dialog buttons fails silently. Always ask the user to perform GUI steps (open project, update PCB, save).
- **Opening schematic in standalone mode**: Never use `kicad_open_schematic` to open a `.kicad_sch` file directly. This opens eeschema in standalone mode, which blocks "Update PCB from Schematic". The user must open the `.kicad_pro` through the KiCad project manager first.
- **Force-killing KiCad**: Never use `killall -9 kicad` or `pkill -9`. This can corrupt KiCad's window position config, making all KiCad windows invisible on next launch. If KiCad needs to be closed, ask the user to close it normally.
- **Placing contacts for nonexistent pins**: If the chip has only INT1 (no INT2), do not place a contact at the INT2 position. Same for RESET — only place contacts for pins that actually exist on the chip.

## Board outline dimensions (Edge.Cuts)

The board outline is larger than the grid and centered on the grid center. These are exact dimensions — do not use the grid dimensions as the board size.

| Grid size | Board outline (Edge.Cuts) | Center point | Board extends from | Board extends to |
|-----------|--------------------------|--------------|-------------------|-----------------|
| 8x8 | **10.8mm × 10.8mm** | (4, 4) | (-1.4, -1.4) | (9.4, 9.4) |
| 16x16 | **18.8mm × 18.8mm** | (8, 8) | (-1.4, -1.4) | (17.4, 17.4) |
| 16x32 | **18.8mm × 34.8mm** | (8, 16) | (-1.4, -1.4) | (17.4, 33.4) |

## Grid size reference

| Size | Board dimensions | Use when |
|------|-----------------|----------|
| 8x8 | 10.8 mm × 10.8 mm | Component is small enough to fit with minimal passives |
| 16x16 | 18.8 mm × 18.8 mm | Component needs more room for passives or has a larger footprint |
| 16x32 | 18.8 mm × 34.8 mm | Component has a large footprint or many supporting passives |