Skip to content

docs(schematic): note label scope vs power symbols in instanced sheets - #483

Merged
mixelpixx merged 1 commit into
mixelpixx:mainfrom
7487:docs/label-scope-instanced-sheets
Sep 9, 2026
Merged

docs(schematic): note label scope vs power symbols in instanced sheets#483
mixelpixx merged 1 commit into
mixelpixx:mainfrom
7487:docs/label-scope-instanced-sheets

Conversation

@7487

@7487 7487 commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #469

batch_connect_to_net and connect_to_net emit plain (label …) items (via format_net_label), which KiCad scopes to the sheet. In a sheet instanced N times that yields N independent nets — right for per-node signals, wrong for a rail every instance must share. Power symbols go the other way: power:+5V is one net across every sheet and instance, so using it for a per-node rail shorts all the instances together. Neither the tool descriptions nor the schematic skill said so; the skill's "use add_power_symbol for rails, not net labels" rule actively pointed at the wrong choice for the instanced case.

Approach

Documentation only, no behaviour change:

  • batch_connect_to_net and connect_to_net descriptions: state that the label is sheet-local, that an instanced sheet gets one net per instance, and that a shared rail needs add_power_symbol or a global_label (connect_to_net has the same trap, so it carries the same note rather than pointing at a tool in another toolset).
  • kicad-schematic/SKILL.md: a bullet under connect_to_net on label scope, a bullet under add_power_symbol on power symbols being global (with the shorted-rails failure spelled out), and an exception clause on rule 6.
  • references/wiring-patterns.md: a paragraph under the Net Label Types table tying scope to instanced sheets.

The net_label/global_label/hierarchical_label names in the docs are the label_type values add_schematic_net_label accepts, so they are left as they are.

Branch and dependencies

Base: current upstream/main (326aa73). No dependencies; independent of the open navigation series (#391, #396#401), whose hunks in sch_batch.rs/sch_wiring.rs do not touch these descriptions.

Compatibility and safety

No public compatibility impact: tool names, schemas, and behaviour are unchanged; only description strings and installed skill text change. No tools added or removed, so the doc-count guard is unaffected.

Validation

  • cargo fmt --all -- --check — clean (rustfmt parses both edited files, so the string-literal edits are syntactically sound)
  • cargo test -p konnect-core -p konnect --locked --lib — not runnable on my machine: the nng-sys build script needs cmake, which is not installed here. The Rust diff is two description string literals; leaving the test/clippy/doc gates to CI.
  • Real-KiCad check not run; the behaviour being documented is KiCad's own label/power-port scoping, as observed in the issue's QuadNode run.

Review checklist

  • The diff is focused and contains no generated output, personal data, or unrelated cleanup.
  • The branch was based on latest upstream/main, not a release tag.
  • The PR shows only its unique commits and diff; no dependencies.
  • No new names; no public renames.
  • No behaviour change, so no new regression coverage.
  • No file or IPC mutations.
  • No tools added or removed.

🤖 Generated with Claude Code

batch_connect_to_net and connect_to_net place plain labels, which KiCad
scopes to the sheet: a sheet instanced N times gets N independent nets.
Power symbols and global labels are one net across every instance. Say
so in both tool descriptions and in the kicad-schematic skill, whose
"power symbols for rails" rule otherwise sends a per-instance rail
through power:+5V and shorts every instance's rail together.

Fixes mixelpixx#469

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@neusse neusse added the status:waiting-on-review Next actor: maintainer label Sep 7, 2026
@mixelpixx mixelpixx added status:ready-to-merge Next actor: automation or maintainer — exact head reviewed and removed status:waiting-on-review Next actor: maintainer labels Sep 9, 2026
@mixelpixx
mixelpixx merged commit eddf131 into mixelpixx:main Sep 9, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status:ready-to-merge Next actor: automation or maintainer — exact head reviewed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document that power symbols are global while labels are sheet-scoped in instanced sheets

3 participants