@huaqiu/dsh-hqsch 0.4.8

package/skills/hqsch-scenario-b/docs/property-conventions.md

@@ -0,0 +1,225 @@
+# Object Property Key Conventions (HQSCH)
+
+## Objective
+
+Map common schematic editing terms (designator, value, footprint) to the
+`propKey` strings required by `CanvasOpsService` property RPCs. The protobuf
+schema only declares `propKey` as a generic `string`; HQSCH uses
+vendor-specific key names that differ between **find** and **read/write**
+operations.
+
+## Property Key Reference
+
+| Business term | Read / write (`GetObjectProperty`, `SetObjectProperty`) | Find (`FindObjectByProperty`) | Notes |
+| --- | --- | --- | --- |
+| Designator (位号) | `Part Reference` | `Reference` | **Always use `Part Reference` when setting the designator.** `Reference` and `Designator` do not work for get/set. |
+| Net label (电源/全局符号) | `Name` | `Name` | Power symbols (VCC, GND, VCC_5V) store the net label in `Name`. **Part Reference is often empty** — do not use `FindObjectByProperty("Reference", "VCC_5V")`. |
+| Value (值) | `Value` | — | Component value (e.g. `10k`, `NCE30P50G`). |
+| Footprint (封装) | `Footprint` or `pcbFootprint` | — | Prefer reading back with `GetObjectProperty` to confirm the active key on a given object. |
+| Description | `Description` | — | Free-text description when present. |
+| MPN | `MPN` | — | Manufacturer part number in symbol properties. |
+
+## Find vs Set Asymmetry
+
+HQSCH maps designator lookup and designator mutation to **different keys**:
+
+1. **Locate** a part by designator → `FindObjectByProperty` with
+   `propKey = "Reference"`, `propValue = "Q31"`.
+2. **Read or change** the designator → `GetObjectProperty` /
+   `SetObjectProperty` with `propKey = "Part Reference"`.
+
+Do not assume the key used for find is valid for set.
+
+## Response Shape Notes
+
+| API | Field | Correct usage |
+| --- | --- | --- |
+| `FindObjectByProperty` | `objectIds` | Repeated field — use `objectIds[0]`, not `objectId`. |
+| `SetObjectProperty` | `op` | Use `OBJ_PROP_SET` (value `1`) for replacement. |
+| `SetObjectProperty` | `commitUndo` | Set `true` to record the edit on the editor undo stack. |
+
+## Rename Designator Workflow
+
+1. `project-get-active-project` → build `ProjectContext`.
+2. `canvas-find-object-by-property` — `propKey: "Reference"`, `propValue: "<old>"`.
+3. Take `objectIds[0]` from the response.
+4. Optional: `canvas-get-object-property` — `propKey: "Part Reference"` to confirm current value.
+5. `canvas-set-object-property` — `propKey: "Part Reference"`, `propValue: "<new>"`, `op: OBJ_PROP_SET`, `commitUndo: true`.
+6. Verify with another `GetObjectProperty` or `FindObjectByProperty`.
+
+## Pin Coordinates and Wiring
+
+After placement, **always save `response.object_id`** from
+`PlacePartFromLibrary` / `PlaceSymbolFromLibrary` / `PlaceKicadSymbol`.
+Use that id for wiring — not designator strings alone.
+
+### Wiring priority
+
+| Priority | Skill | When to use |
+| --- | --- | --- |
+| **1 (preferred)** | `canvas-auto-connect-objects-by-id` | You have both placement `object_id`s (works for C1 ↔ VCC/GND power symbols). |
+| **2** | `obj-place-place-wire` | After `kernel-get-snapshot` pin lookup via `canvas_object_id`. |
+| **3** | `canvas-auto-connect-by-part-reference` | Both endpoints are regular parts with stable `Reference` designators (R/C/U). |
+| **Avoid** | Estimated coords (placement Y ± offset) | Never guess pin positions — wires will miss pins. |
+
+For nets with **three or more nodes**, also read
+[`placement-conventions.md` — Schematic wire routing (avoid overlap)](placement-conventions.md#schematic-wire-routing-avoid-overlap):
+separate branch lanes at placement and chain-connect (do not hub from one anchor).
+
+### Option 1 — AutoConnect by object id (recommended)
+
+Uses the same `object_id` returned by placement RPCs directly — no snapshot
+lookup required:
+
+```typescript
+// After placing C1, VCC_5V, GND — save each object_id
+await getSkill("canvas-auto-connect-objects-by-id")!.execute(ctx, {
+  context: projectCtx,
+  objectId1: c1ObjectId,
+  pinNum1: [1],
+  objectId2: vccObjectId,
+  pinNum2: [0],   // power / GND / port / off-page symbol → always 0
+});
+
+await getSkill("canvas-auto-connect-objects-by-id")!.execute(ctx, {
+  context: projectCtx,
+  objectId1: c1ObjectId,
+  pinNum1: [2],
+  objectId2: gndObjectId,
+  pinNum2: [0],   // power / GND / port / off-page symbol → always 0
+});
+```
+
+Proto fields: `object_id_1`, `pin_num_1` (repeated int32), `object_id_2`,
+`pin_num_2`.
+
+**Symbol pin numbers:** when either endpoint is a **power / GND / hierarchical
+port / off-page** symbol (`PlaceSymbolFromLibrary`), pass **`pinNum: [0]`** for
+that side. Do not use `1` — the engine treats symbol connection points as pin `0`.
+Regular parts use their printed pin numbers.
+
+### Option 2 — PlaceWire after snapshot pin lookup
+
+Pin positions come from **`kernel-get-snapshot`**, not property RPCs.
+
+**Primary lookup:** `canvas_object_id` — same value as placement
+`object_id`. Do not rely on `designator` or `Name` alone (power symbols have
+empty Part Reference; duplicate names may exist on one page).
+
+```typescript
+const PAGE_TOP = 1400; // PAGE_SIZE_START_Y — page top canvas anchor
+
+function canvasPinToExt(x: bigint, y: bigint) {
+  return { x: Number(x), y: PAGE_TOP - Number(y) };
+}
+
+function getPinExtByObjectId(
+  snap: KernelSnapshot,
+  objectId: bigint,
+  pinNum: string,
+): { x: number; y: number } | null {
+  const oid = objectId.toString();
+  const si = snap.symbolInstances?.find(
+    (s) => String(s.canvasObjectId) === oid,
+  );
+  if (!si) return null;
+  const defId = si.definitionId;
+  const symDef = snap.symbolDefinitions?.find((sd) => sd.id === defId);
+  const pinInst = snap.pinInstances?.find((p) => {
+    if (String(p.canvasObjectId) !== oid) return false;
+    const def = symDef?.pins?.find((pd) => pd.id === p.pinDefinitionId);
+    return def?.number === pinNum;
+  });
+  if (!pinInst?.position) return null;
+  return canvasPinToExt(pinInst.position.x!, pinInst.position.y!);
+}
+```
+
+Workflow:
+
+1. `PlacePartFromLibrary` / `PlaceSymbolFromLibrary` → save `response.object_id`.
+2. `kernel-get-snapshot`.
+3. `symbolInstances.find(s => s.canvasObjectId === object_id)`.
+4. `pinInstances` filtered by `canvasObjectId === object_id` and pin number via
+   `symbolDefinitions[].pins[].number`.
+5. Read `pinInstances[].position` (canvas coordinates, Y **up**), convert, then
+   `obj-place-place-wire`.
+
+**Fallback (human-readable only):** match `symbolInstances[].designator` (e.g.
+`Q31`) when `canvas_object_id` is unavailable — not reliable for power symbols.
+
+```text
+extY = PAGE_SIZE_START_Y - canvasY    // PAGE_SIZE_START_Y ≈ 1400 (page top anchor)
+```
+
+`obj-place-place-wire` (`PlaceWire`) uses the **same external display
+coordinates** as placement RPCs — page top-left origin, Y **down**. The server
+converts internally (`canvasY = PAGE_SIZE_START_Y - extY`).
+
+```typescript
+// geometry.start / geometry.end — external display coords
+await client.objPlace.placeWire({
+  context: projectCtx,
+  geometry: {
+    start: { x: BigInt(extA.x), y: BigInt(extA.y) },
+    end:   { x: BigInt(extB.x), y: BigInt(extB.y) },
+  },
+  snapToGrid: true,
+});
+```
+
+Use orthogonal segments (horizontal then vertical) when pins are not aligned.
+
+**Do not use** `canvas-auto-connect-by-part-reference-single-pin` for power
+symbols — their `Part Reference` is empty so `partRef2: "VCC_5V"` will not
+resolve. Use `canvas-auto-connect-objects-by-id` instead.
+
+**Common mistake:** passing raw `pinInstances[].position` (canvas, Y-up) directly
+to `PlaceWire` — wire placement will fail or land off-grid. Always convert first.
+
+**Common mistake:** locating power-symbol pins by `FindObjectByProperty("Reference",
+"VCC_5V")` or by snapshot `designator` — use placement `object_id` →
+`canvas_object_id` instead.
+
+**Common mistake:** using placement center coordinates ± offset as pin endpoints.
+
+## Kernel Snapshot Lag
+
+`GetSnapshot` may lag the canvas immediately after placement — newly placed
+objects may be missing from `symbolInstances` / `pinInstances` / `labels`, or
+`canvas_object_id` may not yet be populated. Mitigations:
+
+1. **Prefer `canvas-auto-connect-objects-by-id`** — does not require snapshot.
+2. If using snapshot pin lookup, **retry** `kernel-get-snapshot` (e.g. 3–5 times,
+   200–500 ms apart) before falling back.
+3. For designator state after `SetObjectProperty`, use `GetObjectProperty` /
+   `FindObjectByProperty` — not snapshot `designator`.
+
+**Enumerating unknown port / NetAlias names:** use `GetSnapshot` —
+`labels[].text` for net aliases, and `symbolInstances[].designator` for
+hierarchical ports / off-page / power. Each also carries owning page via
+`schematic_name` / `page_name` (top-level after SDK regen, or
+`metadata.properties` keys `schematic_name` / `page_name` today).
+**Do not** guess candidate names and poll `FindObjectByProperty(Name=…)`.
+
+## Required Capabilities
+
+| Capability | Purpose |
+| --- | --- |
+| `project-get-active-project` | Resolve active project / `ProjectContext`. |
+| `canvas-find-object-by-property` | Locate objects by designator (`Reference`) or net label (`Name`). |
+| `canvas-get-object-property` | Read property values (`Part Reference`, `Value`, …). |
+| `canvas-set-object-property` | Write property values (`Part Reference`, `Value`, …). |
+| `canvas-auto-connect-objects-by-id` | Wire two placed objects by `object_id` + pin numbers. |
+| `kernel-get-snapshot` | Pin positions via `canvas_object_id`, net graph. |
+| `obj-place-place-wire` | Place wire segments between converted pin coordinates. |
+
+## Critical Guardrails
+
+- Never use `Reference` as `propKey` in `SetObjectProperty` for designator changes.
+- Never use `JSON.stringify()` on protobuf responses — use `toJsonString()` from `@huaqiu/hqeda`.
+- When `FindObjectByProperty` returns multiple `objectIds`, disambiguate with
+  `objTypeFilter` or additional property constraints before mutating.
+- Report designators exactly as shown on the schematic (e.g. `Q31`, `U1`).
+- Never invent candidate port/NetAlias names to poll `FindObjectByProperty` —
+  enumerate via `GetSnapshot` (`labels` / `symbolInstances`) first.

package/skills/hqsch-scenario-b/docs/quickstart.md

@@ -0,0 +1,99 @@
+# HQ EDA Skill Quickstart
+
+End-to-end chain for running a generated skill against a live HQ EDA editor.
+
+## Prerequisites
+
+- HQ EDA desktop runtime running locally
+- Node.js 18+
+- Packages: `@huaqiu/hqeda` and `@huaqiu/huaqiu-client`
+
+```bash
+npm install @huaqiu/hqeda @huaqiu/huaqiu-client
+```
+
+## Step 1 — Discover running editors
+
+```typescript
+import { listEditors } from "@huaqiu/huaqiu-client";
+
+const editors = await listEditors();
+console.log(editors);
+// [{ instanceId: "...", pid: 12345, ... }, ...]
+```
+
+When multiple editors are running, pass `instanceId` explicitly to `connect()`.
+
+## Step 2 — Connect
+
+```typescript
+import { connect } from "@huaqiu/huaqiu-client";
+
+const client = await connect();
+// Or target a specific instance:
+// const client = await connect({ instanceId: editors[0].instanceId });
+```
+
+`connect()` returns an `EditorClient` with service accessors (`client.project`, `client.edaBom`, `client.canvasOps`, …).
+
+## Step 3 — Build context (when required)
+
+Many RPCs require a `context` field. Build it from the connected client:
+
+```typescript
+// Editor-level context (project listing, active project discovery)
+const editorContext = client.createEditorContext();
+
+// Project-scoped context (canvas, selection, BOM for one project)
+const projectContext = client.createProjectContext("my-project");
+```
+
+Obtain `projectId` via [`project-get-active-project`](../project/get-active-project/SKILL.md) or [`project-list-open-projects`](../project/list-open-projects/SKILL.md).
+
+## Step 4 — Execute a skill
+
+```typescript
+import { getSkill, toJsonString } from "@huaqiu/hqeda";
+
+const skill = getSkill("bom-get-bom");
+if (!skill) throw new Error("Skill not found: bom-get-bom");
+
+const result = await skill.execute(
+  { client },
+  { projectId: "my-project" },
+);
+
+console.log(toJsonString(result, { prettySpaces: 2 }));
+```
+
+## Step 5 — Serialize responses
+
+Always use `toJsonString()` or `toJson()` from `@huaqiu/hqeda` — never `JSON.stringify()` directly on protobuf messages. See [serialization.md](serialization.md).
+
+## Minimal complete script
+
+```typescript
+import { connect } from "@huaqiu/huaqiu-client";
+import { getSkill, toJsonString } from "@huaqiu/hqeda";
+
+async function main() {
+  const client = await connect();
+  const active = await client.project.getActiveProject({
+    context: client.createEditorContext(),
+  });
+  const projectId = active.project?.projectId;
+  if (!projectId) throw new Error("No active project");
+
+  const skill = getSkill("bom-get-bom");
+  const bom = await skill!.execute({ client }, { projectId });
+  console.log(toJsonString(bom, { prettySpaces: 2 }));
+}
+
+main().catch(console.error);
+```
+
+## Install a single skill (Agent)
+
+```bash
+npx skills add Huaqiu-Electronics/skills --path eda/bom/get-bom
+```

package/skills/hqsch-scenario-b/docs/reading-a-circuit.md

@@ -0,0 +1,317 @@
+# Reading a circuit (understanding an existing design)
+
+Use this when the task is **read-only understanding**, not drawing: "what does
+VR201 do?", "how is this powered?", "why is this net named X?".
+
+The goal is to reconstruct the **electrical topology plus device semantics**
+without hand-parsing wire geometry or guessing.
+
+## The one call that does most of the work
+
+`kernel.GetSnapshot({ context })` returns a **whole-project** snapshot in a
+single unary RPC (~1.6 s for 160 parts / 602 wires / 181 nets). It is the
+primary data source for circuit understanding.
+
+Measured scope: snapshot nets (181) == `netList.GetProjectNetList` nets (181),
+while the current page held only 132 nets. So **snapshot is project-wide, not
+page-scoped** — you do not need to walk pages.
+
+| Entity | Count here | What it gives you |
+| --- | --- | --- |
+| `symbolInstances` | 160 | designator, definitionId, position, rotation, mirrored, **metadata.properties** — includes parts, power globals, **hierarchical ports**, and **off-page connectors** (`designator` = Name) |
+| `pinInstances` | 612 | `symbolInstanceId`, `pinDefinitionId`, **absolute position** |
+| `nets` | 181 | `name`, `netClass`, `pinInstanceIds[]` |
+| `symbolDefinitions` | 58 | `name`, **`pins[]` with `number` + `name`** (pin-number → pin-name table) |
+| `wireSegments` | 602 | geometry (rarely needed for semantics) |
+| `labels` | (when used) | NetAlias instances: `text` (= name), `position`, `netId`, `metadata.id` (= canvas dbId when present) |
+| `junctions` | (when used) | wire junctions |
+| `noConnects` | (when used) | no-connect markers |
+
+### Enumerating ports / net labels (do not guess names)
+
+**Never** invent candidate names and poll `FindObjectByProperty(Name=…)`. Use one snapshot:
+
+```typescript
+const snap = await client.kernel.getSnapshot({ context: ctx });
+const s = snap.snapshot!;
+
+// Net aliases — text + owning schematic/page
+const labels = (s.labels ?? []).map((l) => ({
+  name: l.text,
+  schematic: l.schematicName
+    ?? l.metadata?.properties?.find((p) => p.key === "schematic_name")?.stringValue
+    ?? "",
+  page: l.pageName
+    ?? l.metadata?.properties?.find((p) => p.key === "page_name")?.stringValue
+    ?? "",
+}));
+
+// Ports / off-page / power — designator + schematic/page (same property keys)
+const ports = (s.symbolInstances ?? []).map((x) => ({
+  name: x.designator,
+  schematic: x.schematicName
+    ?? x.metadata?.properties?.find((p) => p.key === "schematic_name")?.stringValue
+    ?? "",
+  page: x.pageName
+    ?? x.metadata?.properties?.find((p) => p.key === "page_name")?.stringValue
+    ?? "",
+}));
+```
+
+`Label` / `SymbolInstance` proto fields: `schematic_name`, `page_name`.
+Until the published SDK regenerates those top-level fields, they are also present as
+`metadata.properties` with keys `schematic_name` / `page_name`.
+
+`FindObjectByProperty` is only for **known** names after this enumeration.
+
+### Cross-page / cross-hierarchy port pairing (do not guess)
+
+Different page ports can share one design net **even when names differ**
+(e.g. `/TYPE-C` `USB_D+` ↔ `/ESP32-C3FH4` `GPIO18`). That comes from hierarchical
+block-pin ↔ port merge on the parent sheet — **not** from GUID matching.
+
+**Never** invent same-name rules for this case. Call:
+
+```typescript
+const pairing = await client.netList.getPortPairing({});
+for (const p of pairing.pairings ?? []) {
+  console.log(
+    `${p.portA?.occPath} ${p.portA?.pageName}/${p.portA?.name}` +
+    ` ↔ ${p.portB?.occPath} ${p.portB?.pageName}/${p.portB?.name}` +
+    ` on ${p.netName} rule=${p.rule}`
+  );
+}
+```
+
+| `rule` | Meaning |
+| --- | --- |
+| `BY_NAME` | Same-name Off-page / Hierarchical Port within a schematic folder |
+| `BY_HIERARCHY` | Parent hierarchical block pin joins child ports (may be **different names**) |
+| `BY_GLOBAL` | Design-wide Power / Global name merge |
+
+Recommended flow: `GetSnapshot` (enumerate ports) → `GetPortPairing` (cross-page edges)
+→ `GetProjectNetList` only if you need pin membership of the merged net.
+
+### Reconstructing pin → net (verified recipe)
+
+Three joins give the full topology. This was verified end-to-end against VR201:
+
+```typescript
+const snap = await client.kernel.getSnapshot({ context: ctx });
+const s = snap.snapshot!;
+
+// 1. designator → instance
+const sym = s.symbolInstances.find((x) => x.designator === "VR201");
+const symId = sym.metadata!.id;                    // e.g. "/-74618591"
+
+// 2. pin-number → pin-name (from the symbol definition)
+const def = s.symbolDefinitions.find((d) => d.name === sym.definitionId);
+const pinName = new Map(def!.pins.map((p) => [p.number, p.name]));
+// → 1=OUTPUT 2=SENSE 3=GND 4=SHDN# 5=VIN
+
+// 3. pin instance → net
+const netOf = new Map<string, string>();
+for (const net of s.nets)
+  for (const pid of net.pinInstanceIds) netOf.set(pid, net.name);
+
+// 4. join
+for (const p of s.pinInstances.filter((x) => x.symbolInstanceId === symId)) {
+  const pn  = p.metadata!.id;                      // "/-74618591-1"
+  const num = p.pinDefinitionId;                   // "1"
+  console.log(`pin${num} ${pinName.get(num)} → ${netOf.get(pn) ?? "(unconnected)"} @${p.position}`);
+}
+```
+
+Output (matches the netlist exactly, and **additionally** shows the
+unconnected pin and the physical coordinates):
+
+```
+pin1  OUTPUT  → +3.3V        @(1890,670)
+pin2  SENSE   → +3.3V        @(1890,660)
+pin3  GND     → GND          @(1890,650)
+pin4  SHDN#   → (unconnected) @(1770,670)
+pin5  VIN     → N0261718     @(1770,660)
+```
+
+Key advantages over `netList`:
+
+- **Unconnected pins are visible.** `pin4 SHDN#` shows up here; the netlist
+  only lists pins that belong to a net, so floating pins disappear.
+- **Absolute pin coordinates**, in kernel canvas coordinates (Y up).
+- **`rotation` / `mirrored`** for each instance.
+
+> Beware BigInt: `position.x/y` are `bigint`. `JSON.stringify` throws
+> "Do not know how to serialize a BigInt" — pass a replacer:
+> `JSON.stringify(v, (_k, x) => typeof x === "bigint" ? String(x) : x)`.
+
+## Device semantics are already in the snapshot — do not fetch datasheets
+
+`symbolInstance.metadata.properties` carries a rich electrical parameter set
+harvested from the part database. **Read it before going online.**
+
+Real dump for `VR201`:
+
+```
+Datasheet                      = http://file.elecfans.com/.../pYYBAGDuZ16ARrigAALCJORq5X4437.pdf
+Description                    = Micropower Low Dropout Regulator with Shutdown,
+                                 4.15 to 30 V Vin, 5 V Vout, 5-pin FM (T-5), 0 to 125 degC
+MPN                            = LT1129CT-5#06PBF
+Manufacturer                   = Analog Devices
+dropout_voltage                = 450 mV
+input_voltage                  = 30 V, 4.15 V
+output_voltage                 = 5 V
+output_current                 = 700 mA
+supply_current                 = 50 μA
+power_supply_rejection_ratio   = 64 dB
+topology                       = 正，固定式
+features                       = Enable
+operating_temperature          = 0 °C, 125 °C
+package                        = TO-220-5
+huaqiu_pn                      = G7258042
+```
+
+For `U202` (MAX202ESE+T) the same mechanism yields `interface=RS-232`,
+`data_rate=120 kb/s`, `driver_receiver=2/2`, `supply_voltage=5.5 V`, etc.
+
+**Consequence:** an "is this part appropriate for its net?" check is fully
+local. Comparing `output_voltage = 5 V` against the net name `+3.3V` surfaces
+the mismatch with zero network access.
+
+Property keys vary by part family (a regulator exposes `topology` /
+`dropout_voltage`; a transceiver exposes `interface` / `data_rate`). Treat the
+set as open — read the keys, do not assume a fixed schema.
+
+## Which comprehension interfaces actually work
+
+**Canonical map (works / ban / hollow):** [rpc-availability.md](./rpc-availability.md).
+
+Summary: **Snapshot + `netList` is the whole toolbox for comprehension.** Do not
+build on `GetConnectivity`, selection, ERC, export, runtime, or `FindNet`
+(silent `success:false`). Advanced helpers (`GetObjectsJsonByIds`, `FindObject`,
+`GetSelectionNetList`) are optional — not required for Flow B.
+
+Timing baseline: `GetSnapshot` ~1.6–3.2 s for a mid-size project; do not treat
+that as a hang.
+
+## Project identification — do not assume the project
+
+`getActiveProject` returns whichever schematic is focused. The project can
+change between calls (the user may switch tabs, or the editor may restart).
+Always read `projectId` from the response and print it, rather than reusing a
+cached one.
+
+Note the active project is identified by **file path** as the id, e.g.
+`C:/Users/Administrator/Desktop/kit-dev-coldfire.HQSch`.
+
+The editor instance can also restart (new `instanceId`, new pid), which clears
+the live canvas. After a restart the canvas is empty while the saved project
+file still holds data — that is expected, not a bug. Re-check
+`GetPageOccupancy` before assuming a prior placement persists.
+
+## Practical workflow
+
+1. `project.GetActiveProject` → print `projectId`. Do not cache across tasks.
+2. `kernel.GetSnapshot` once — it answers most questions.
+3. Build the three maps (designator→instance, pinDef→name, pinInstance→net).
+4. For semantics, read `metadata.properties` of the instance.
+5. **Neighborhood expansion** — for each pin of the target REF, list other
+   members on the same net (grouped by pin). See below.
+6. **Optional series traversal** — `TRACE=1` on `read-circuit.ts` to follow
+   C/R/L/FB two-terminal bridges to the far-side net. No extra RPC.
+7. **Canvas edit ids** — print `metadata.id`, `canvasObjectId`, and
+   `FindObjectByProperty(Reference)` for Flow C. See [editing-a-circuit.md](./editing-a-circuit.md).
+8. Only if a project is large enough to make the 1.6 s snapshot painful,
+   fall back to `netList.GetProjectNetList` (~27 ms) for pure net queries.
+
+## Standard answer template (agent natural language)
+
+When answering "what does REF do?", structure the reply as:
+
+1. **Identity** — `Description` / `MPN` from `metadata.properties`; if empty,
+   state definition name only — **do not invent datasheet values**.
+2. **Pin → net** — table from snapshot join.
+3. **Neighborhood** — per pin, who else shares each net (see next section).
+4. **Series links (optional)** — if user asks about coupling/series path, enable
+   TRACE or describe C/R/L/FB bridges manually from snapshot.
+5. **Consistency flags** — e.g. `output_voltage` vs rail net name.
+6. **Role summary** — one paragraph: what this part does **in this local context**.
+
+Template script: `template/scripts/read-circuit.ts` (`REF=VR201`).
+
+## Neighborhood expansion (same-net, 1 hop)
+
+After pin→net for target `REF`:
+
+1. Collect connected nets (exclude `(unconnected)`).
+2. For each net, reverse-map `nets[].pinInstanceIds` → designator + pin number/name.
+3. **Group by pin** (not flat per net) so "what's on VIN?" is obvious.
+4. Remove the target REF's own pins from neighbor lists.
+5. **Large net summary** (GND, +5V, …): if >8 pin instances, show netClass,
+   total part/pin counts, prefix stats (`C×4, R×2`), and **first 5** representative neighbors.
+6. **Role hints** (rule-based, not online): `C*` → bypass/filter cap;
+   `R*` → pull/divider; `U*`/`VR*` → active IC; power symbols → rail entry.
+7. Attach `Value=` from neighbor `metadata.properties` when present.
+
+Default depth: **1 hop** (same net only). Do not recursively expand every
+neighbor's other nets unless the user asks for a subsystem view.
+
+## Series traversal (C / R / L / ferrite bead)
+
+**No new engine RPC.** Build a client-side graph from one snapshot:
+
+| Edge | Rule |
+| --- | --- |
+| Same net | All pins on net N are mutually reachable |
+| Series passive | `C/R/L/FB*` with exactly **2 connected pins on 2 different nets** |
+
+**Do not bridge:**
+
+- Multi-pin ICs (`U*`, `VR*`, …) — stop at net boundary.
+- **Shunt decoupling cap** — one leg on GND/VCC/POWER netClass, other on signal:
+  list as same-net neighbor only; **do not** traverse into the rail through the cap.
+- Optional: stop penetration into huge GND/POWER nets after listing summary.
+
+**BFS** from each pin of target REF (default `maxDepth=2`):
+
+```
++3.3V —[C205 100nF]— NET_MCU_AVDD → U301(14 VDD)
+```
+
+Enable in template:
+
+```bash
+REF=VR201 TRACE=1 npx tsx scripts/read-circuit.ts
+REF=VR201 TRACE=1 TRACE_DEPTH=2 npx tsx scripts/read-circuit.ts
+```
+
+Engine-side `GetConnectivity` with `edgeKind=series` would be more authoritative
+(P2); skill uses this BFS until then — see [rpc-availability.md](./rpc-availability.md).
+
+## Designator lookup and canvas id mapping
+
+| Step | API / field |
+| --- | --- |
+| Exact REF | `symbolInstances.find(designator === REF)` |
+| Fuzzy | prefix match / substring; print candidates — never guess silently |
+| Snapshot join id | `symbolInstance.metadata.id` |
+| Canvas mutate id | `canvasObjectId` **or** `FindObjectByProperty("Reference", REF).objectIds[0]` |
+| Set designator | `SetObjectProperty` + **`Part Reference`** (not `Reference`) |
+
+After Flow B, carry ids into Flow C — [editing-a-circuit.md](./editing-a-circuit.md).
+
+## When properties are empty
+
+Hand-drawn or non-CIS parts may have no `metadata.properties`:
+
+- Use `symbolDefinitions` pin names + neighborhood topology.
+- State uncertainty explicitly.
+- **Forbidden:** fabricating voltage/current ratings or MPN from memory.
+
+## Multi-part / subsystem questions
+
+"How is this power block fed?" — expand by **net cluster**, not one REF:
+
+1. Start from regulator VIN/EN nets (Flow B on REF).
+2. Run `NET=<name>` mode on upstream nets.
+3. Use `TRACE=1` for series elements between rails and loads.
+4. Summarize chain: source → filter → regulator → load caps → loads.