jitxexamples 1.6.0__tar.gz → 1.6.2__tar.gz

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/CLAUDE.md

@@ -24,21 +24,24 @@ specifically about working *with an agent* in this repo.
   context, so instantiating a `SampleDesign` works offline. Only `jitx build` / `jitx ui` need
   `jitx runtime start`; `jitx build --dry <target>` translates a design without one.
 
-- **JITX 4.4.0 is public, and the parked-changes list is `internal/JITX-4.4-RELEASE-ACTIONS.md`.**
-  Read it before planning work here: it says what is already done so you don't redo it, and what is
-  still open. Two items were still open as of 2026-08-31 — deleting
-  `vishay_crcw._STANDARD_TABLE_OVERRIDES` (its trigger fired long ago) and regenerating
-  `JS0_Environment_Setup.md` Appendix A, whose dependency table is still a 4.2-line snapshot. The
-  file's runtime-surface check (`jitx runtime introspect` reporting a 4.4.x `release` build) had not
-  been run at that point either.
-
-- **The repo targets the jitx 4.4 line, and public PyPI now serves it.** `pyproject.toml` requires
-  `jitx>=4.4.0,<5`, which resolves from public PyPI — the pre-release specifier and the
-  CI-can't-install caveat are both gone. The `hatch` envs still add the internal index
-  (`PIP_EXTRA_INDEX_URL`), so they resolve *ahead* of the public line: expect a `4.4.x.devN` build
-  there rather than 4.4.0 exactly. Before concluding that demo code is broken, check which `jitx`
-  you resolved, and note that `jitx build` also needs the runtime (`~/.jitx/current`) on the same
-  line as the library.
+- **The repo targets the jitx 4.4 line, and public PyPI serves it.** `pyproject.toml` requires
+  `jitx>=4.4.0,<5`. Two surfaces have to agree — a 4.4 package against a 4.2 runtime is not a
+  working install — so `jitx build` also needs the runtime (`~/.jitx/current`, check with
+  `jitx runtime introspect`) on the same line as the library. Before concluding demo code is broken,
+  check which `jitx` you actually resolved on both.
+
+- **A maintainer machine does not resolve what a customer resolves.** Developer setups here carry an
+  internal index and a pre-release opt-in, and they are not all environment variables —
+  `~/.pip/pip.conf` can set `extra-index-url` and `pre = true`, which `env -u PIP_EXTRA_INDEX_URL`
+  does not strip. To reproduce a customer's resolution, neutralise the config file as well:
+
+  ```bash
+  env -u PIP_PRE -u PIP_EXTRA_INDEX_URL -u UV_PRERELEASE -u UV_EXTRA_INDEX_URL \
+    PIP_CONFIG_FILE=/dev/null hatch test --cover
+  ```
+
+  Confirm what you got (`pip list | grep jitx`) rather than assuming: a `.dev`, `a` or `rc` suffix
+  means the isolation did not hold. Without it the `hatch` envs resolve *ahead* of the public line.
 
 - **The parts database is mocked in tests.** `tests/conftest.py` installs an autouse fixture
   patching `jitxlib.parts.query_api.dbquery` with fixtures from `captured_json/` and sets

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jitxexamples
-Version: 1.6.0
+Version: 1.6.2
 Summary: Library of example JITX components, substrates, and demo designs
 Project-URL: Homepage, https://jitx.com
 Project-URL: Documentation, https://docs.jitx.com

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js0-setup/JS0_Environment_Setup.md

@@ -212,6 +212,7 @@ to `@jitx <request to AI>` for general work). For example:
 
 - [ ] VSCode (or Cursor / Windsurf / Devin) installed **[Engineer]**
 - [ ] Python 3.12+ available to the editor **[Engineer]**
+- [ ] Windows: `PYTHONUTF8` = `1` set as a user environment variable (same steps as [Appendix B](#appendix-b--memory-configuration-for-large-designs)) — the default `cp1252` console rejects the `Ω` and `→` in JITX output **[Engineer]**
 - [ ] JITX extension installed (pulls in JITX packages + runtime) **[IT/Admin + Engineer]**
 - [ ] First project created successfully **[Engineer]**
 
@@ -247,9 +248,10 @@ dependency set**, captured from a freshly scaffolded project on **JITX 4.4.0 wit
 the versions are **not** the floor and they move with each release, so regenerate it for the version
 you are deploying with `pip list` in the project venv.
 
-> Note: the JITX runtime version and the Python package versions do not track one-to-one — the
-> `jitx` and `jitxcore` packages report their own version numbers. Expect them to differ from the
-> runtime version; the two are versioned independently.
+> Note: the JITX runtime and the `jitx` / `jitxcore` Python packages must sit on the **same release
+> line** — the same major.minor, e.g. a 4.4.x runtime with 4.4.x packages. Patch numbers can differ;
+> release lines cannot — a 4.4 package against a 4.2 runtime is not a working install. `jitx runtime
+> introspect` reports the runtime, `pip show jitx` the package.
 
 | Package | Version |
 | --- | --- |

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js0-setup/JS0_Reference_Companion.md

@@ -1,4 +1,4 @@
-<!-- JITX Setup — Reference Companion (JS0) · rev 1.4 · 2026-08-31 -->
+<!-- JITX Setup — Reference Companion (JS0) · rev 1.5 · 2026-09-08 -->
 
 # JITX Setup — Reference Companion (JS0)
 
@@ -16,7 +16,7 @@ Run these in a terminal — you'll get a working, authenticated install, proven
 2. **Install the JITX CLI.** `pip install jitx`. If you hit the PEP 668 "externally-managed-environment" error — the Python packaging rule that stops `pip` writing into a system-managed interpreter — install `uv` (https://astral.sh/uv) and run `uv tool install jitx` instead. Verify: `jitx --version`.
 3. **Install the runtime.** `jitx runtime install` — do this **before** signing in. **On Windows**, this launches an MSI installer in a separate popup window (possibly behind others) — complete it to finish. If it fails with `not tested on Linux distribution '<x>'`, retry as `jitx runtime install --target ubuntu`; the Ubuntu build runs on most glibc Linux. Check it with `jitx runtime introspect`, which works anywhere — `jitx runtime status` is project-scoped and fails with `No pyproject.toml found` until you create the project in step 5.
 4. **Sign in.** `jitx auth login` prints an activation link and a code; open it in any browser, approve, and the command completes on its own. It does not launch the browser for you, which matters on a headless or remote machine. **The link expires in 10 minutes** — re-run the command if it lapses. In the browser, **Sign in with Google** is simplest; if you're **not** using a Google-enabled account, enter your registered email and JITX password. Confirm with `jitx auth show`: **`Authorized: yes`** is the field that matters, and an `Expires` in the past is normal — the value shown is always the pre-refresh one, because the authorization check that renews the token runs after the claims are read.
-5. **Validate with two builds.** The global CLI (step 2) has no `pip`, so run this inside each project once it exists. Create and activate a virtual environment — `python3 -m venv .venv && source .venv/bin/activate` on macOS or Linux, or `py -3.12 -m venv .venv` then `.\.venv\Scripts\Activate.ps1` in Windows PowerShell — then `pip install jitx`, `jitx project dependencies upgrade`, `jitx runtime start --background`, and `jitx find`.
+5. **Validate with two builds.** The global CLI (step 2) has no `pip`, so run this inside each project once it exists. Create and activate a virtual environment — `python3 -m venv .venv && source .venv/bin/activate` on macOS or Linux, or `$env:PYTHONUTF8 = "1"; py -3 -m venv .venv` then `.\.venv\Scripts\Activate.ps1` in Windows PowerShell — then `pip install jitx`, `jitx project dependencies upgrade`, `jitx runtime start --background`, and `jitx find`. After the upgrade, `pip show jitx` and `jitx runtime introspect` should report the same release line (4.4.x with 4.4.x). **On Windows**, `PYTHONUTF8=1` keeps the `cp1252` console from choking on `Ω`; and a `WinError 32` from the upgrade means pip is replacing the running `jitx.exe` — run `.\.venv\Scripts\python.exe -m pip install --upgrade jitx` and re-run the upgrade.
    - **Simplest.** Create a new project with `jitx project layout init` (this seeds a two-resistor sample design). Build the seeded non-test target from `jitx find` — ignore any target whose module path comes from `test`, `tests`, or a test file. **Take the target verbatim from `jitx find`** — the two halves are derived differently, so don't assemble it yourself: the package is the directory lowercased with hyphens and spaces turned into underscores, while the design class is that same name in CapWords. A directory called `my-first-board` builds as `jitx build my_first_board.main.MyFirstBoard`. Then open the views with `jitx ui open --schematic` and `jitx ui open --board`.
    - **Full.** Clone `https://github.com/JITx-Inc/jitx-examples` and build the [`si_bga_optimization`](https://github.com/JITx-Inc/jitx-examples/tree/main/src/jitxexamples/demos/si_bga_optimization) design, taking the target verbatim from `jitx find` as above — expect `jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design`. Open the board view to confirm.
    - **`jitx ui open` holds the terminal** while its window is open — use a second terminal, or background it, for the next command. Later calls return straight away and add their windows to the JITX app already running; there's no limit on how many views can be open at once, so leave the Simplest build's windows up.

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js0-setup/JS0_Setup_Runbook.md

@@ -1,5 +1,5 @@
 <!--
-JITX Setup Runbook (JS0) · rev 1.4 · 2026-08-31
+JITX Setup Runbook (JS0) · rev 1.5 · 2026-09-08
 Paste this file into your AI coding agent (Claude Code, Codex / GPT, or Devin), or upload it,
 and tell the agent to follow it.
 -->
@@ -19,7 +19,7 @@ and tell the agent to follow it.
 **Assumptions / prerequisites**
 
 - Python 3.12+ and `git` are available.
-- You are running inside an AI coding agent that can execute shell commands (not sandboxed).
+- You are running inside an AI coding agent that can execute shell commands (not sandboxed). If your harness gates commands or network access behind approval prompts, expect them at the installers (steps 1–2), the background runtime start, the `git clone`, and each `jitx ui open` — approve them; none of those steps works from a read-only sandbox.
 - (Optional) A code editor is installed (VSCode, Cursor, or Windsurf/Devin).
 
 ---
@@ -78,7 +78,7 @@ Drive these with the base JITX skill (step 4). The step-1 CLI has no `pip`, so r
 python3 -m venv .venv && source .venv/bin/activate
 
 # Windows (PowerShell)
-py -3.12 -m venv .venv; .\.venv\Scripts\Activate.ps1
+$env:PYTHONUTF8 = "1"; py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
 ```
 
 ```bash
@@ -89,10 +89,15 @@ jitx find
 ```
 
 - **5a — Simplest build.** Run `jitx project layout init` to create a new JITX project seeded with a two-resistor sample design (Devin users: you made this project in step 4). Then run the setup commands above and build the seeded non-test target from `jitx find` — ignore any target whose module path comes from `test`, `tests`, or a test file. **Take the target verbatim from `jitx find`** — the two halves are derived differently, so don't assemble it yourself: the package is the directory lowercased with hyphens and spaces turned into underscores, while the design class is that same name in CapWords. A directory called `my-first-board` builds as `jitx build my_first_board.main.MyFirstBoard`. Then show me the schematic and board views.
-- **5b — Full build.** Clone `https://github.com/JITx-Inc/jitx-examples`, run the setup commands above, and **take the `si_bga_optimization` target verbatim from `jitx find`** — the same rule as 5a, so a repo reorganisation can't strand you on a stale module path. Expect `jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design`. Build it, confirm it builds, and display the board UI windows for me.
+- **5b — Full build.** Clone `https://github.com/JITx-Inc/jitx-examples`, run the setup commands above, and **take the `si_bga_optimization` target verbatim from `jitx find`** — the same rule as 5a, so a repo reorganisation can't strand you on a stale module path. Expect `jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design`. Two things about this repo's output: `jitx find` also prints an `errors: import failed` block for the repo's `tests/` modules — expected here (its tests aren't a package) and not a fault; the `designs:` list is what you take the target from. And after `jitx project dependencies upgrade`, `pip show jitx` and `jitx runtime introspect` must report the same release line (4.4.x with 4.4.x) — if the upgrade moved `jitx` to a different line than the runtime, stop and tell me rather than building. Build it, confirm it builds, and display the board UI windows for me.
 
 > **If a build fails with "You are not authenticated. Please sign in through the JITX Sidebar in VSCode"**, that means step 3 didn't complete — re-run `jitx auth login`, don't go looking for VSCode. `jitx runtime start --background` succeeds while unauthenticated, so a green step 2 is not proof of sign-in, and the real one-line cause arrives underneath two Python tracebacks.
 
+> **[Windows] Two things the PowerShell block is protecting you from.**
+>
+> - **`$env:PYTHONUTF8 = "1"` is not optional.** JITX output and these runbooks carry `Ω`, `→` and `·`, and the default `cp1252` console raises `UnicodeEncodeError` on them — a build that is otherwise fine stops on a resistor value. The line sets it for this shell only; to make it permanent, add `PYTHONUTF8` = `1` as a user environment variable the way Environment Setup's Appendix B does for the heap variables.
+> - **`WinError 32` from `jitx project dependencies upgrade`** means pip is trying to replace the `jitx.exe` that is running it — it only happens when the upgrade has to move `jitx` itself. Do that one step from Python instead, then re-run the upgrade: `.\.venv\Scripts\python.exe -m pip install --upgrade jitx`, then `jitx project dependencies upgrade` again (nothing left to move).
+
 > **Opening the views — what to expect.**
 >
 > - **`jitx ui open` blocks while its window is open**, so launch it in the background rather than letting it hang your shell for the whole session. Later calls return immediately and add their windows to the JITX app already running — there's no limit on how many views can be open at once, so leave 5a's windows up while you open 5b's.
@@ -108,7 +113,7 @@ Report the results of both builds.
 Search the editor's (or VSCode's) marketplace for the JITX extension and install it via that editor's CLI. Ask me to confirm it's installed and its sidebar shows me authenticated.
 
 **7 · [HUMAN] Close the loop — make a live design change.**
-Now show me the design-as-code loop on the step-5 design. **Invite me to make a change**, then **wait for me to ask.** Report the before → after values. If the view doesn't redraw after the rebuild, reopen it — see step 5's note on how `jitx ui open` behaves.
+Now show me the design-as-code loop on the step-5 design. **Invite me to make a change**, then **wait for me to ask.** Report the before → after values. The board view that is already open normally redraws on its own after the rebuild — check it (ask me what I see) before you reopen anything, and reopen only if it didn't; see step 5's note on how `jitx ui open` behaves.
 
 - **If 5b ran** — tell me I can adjust the differential-pair geometry; suggest I say: *"change the differential-pair trace width to 0.0762 mm and the pair spacing to 0.1568 mm."* Edit the constants — `DIFFPAIR_TRACE_WIDTH` → `0.0762` and `DIFFPAIR_PAIR_SPACING` → `0.1568` (in the design's `substrate.py`) — rebuild, and show me **both** the changed source lines and the updated board view. Say plainly what the edit costs: those constants are the 85 Ω stripline geometry, so the new values detune every 85 Ω signal layer. We're changing them to watch a source edit reach the board, and in real work you'd re-solve the geometry for the impedance target. **Then point me at the right layer** — select `L2-Signal1` and zoom into the BGA escape region, where the diff-pair geometry lives. The change is subtle but visible there; it won't show on the default `L1-Ground1` whole-board view.
 - **If 5b didn't build** — fall back to the 5a design: tell me I can change a resistor value, and suggest I say *"change r2 to 10 kΩ."* Edit that resistor's `resistance` in the project's `main.py`, rebuild, and show me the changed line and the updated schematic. Say which design you used.
@@ -121,3 +126,4 @@ Now show me the design-as-code loop on the step-5 design. **Invite me to make a
 - The JITX skills are visible **and invocable** in a new agent session, confirmed by actually invoking one.
 - **5a** (two-resistor template) builds, and so does **5b** (`si_bga_optimization`).
 - A prompted design change — the diff-pair edit on 5b, or a resistor value on 5a if 5b didn't build — is applied, rebuilt, and visible in both the code and the UI.
+- You have listed the `jitx ui open` jobs you backgrounded, so I can close the windows myself — don't kill them; the windows are what I came to see.

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/README.md

@@ -71,7 +71,7 @@ a machine-readable file — so you parse it rather than transcribe it. A committ
 generator reconciles the file to exactly 1,369 balls before any component code exists, and the
 circuit wrapper lifts the flat pin map into what a board designer actually consumes: 31 `Power`
 rails, three ground domains, and six GTM transceiver quads as bundles. Verification is layered —
-reconciliation (parsed rows = file footer = full 37×37 grid), 17 tests and 74 subtests including
+reconciliation (parsed rows = file footer = full 37×37 grid), 19 tests and 198 subtests including
 hand-read ball spot-checks, and both designs building `status: ok`. Expect roughly 2–3 hours across
 four `[HUMAN]` gates, most of it agent-autonomous.
 

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/part1-stackup/JS1_Part1_Stackup-from-Fab-CSV_Runbook.md

@@ -1,5 +1,5 @@
 <!--
-JITX Stackup-from-Fab-CSV Runbook (JS1 · Part 1) · rev 1.3 · 2026-08-31
+JITX Stackup-from-Fab-CSV Runbook (JS1 · Part 1) · rev 1.4 · 2026-09-08
 Paste this file into your AI coding agent (Claude Code, Codex / GPT, or Devin), or upload it,
 together with your stackup CSV, and tell the agent to follow it. Complete the JS0 Setup Runbook
 first. START A NEW AGENT SESSION before you begin — a skills install only takes effect in a
@@ -10,11 +10,12 @@ session started after it, so the session that finished JS0 cannot run this runbo
 
 **Goal (for the agent):** Turn a fabrication house's stackup report into a verified JITX substrate in a file called `board.py` — a 20-layer HDI stack, five microvia levels per side, impedance-controlled routing structures. The user-provided documentation (e.g. CSV) is the **only** ground truth: every material, thickness, via and trace width must trace to one of its rows. Estimate nothing: if the CSV doesn't state it and the substrate-modeler skill doesn't supply a labeled default for it, ask me. Follow the steps **in order**. Where a step is marked **[HUMAN]**, stop and wait for me — do not proceed until I confirm.
 
-> **For humans:** you need a completed **JS0** (authenticated `jitx` CLI, `jitx-skills` enabled) and a stackup CSV — `part1-stackup/JS1_Part1_Fab-Stackup.csv` from this kit, or your own fab's export. Reference solution: `pip install jitxexamples`, then [`jitxexamples.jumpstart_kits.js1_stackup_components.hdi_stackup`](https://github.com/JITx-Inc/jitx-examples/tree/main/src/jitxexamples/jumpstart_kits/js1_stackup_components/hdi_stackup).
+> **For humans:** you need a completed **JS0** (authenticated `jitx` CLI, `jitx-skills` enabled) and a stackup CSV — `part1-stackup/JS1_Part1_Fab-Stackup.csv` from this kit, or your own fab's export. Reference solution: `pip install jitxexamples`, then [`jitxexamples.jumpstart_kits.js1_stackup_components.hdi_stackup`](https://github.com/JITx-Inc/jitx-examples/tree/main/src/jitxexamples/jumpstart_kits/js1_stackup_components/hdi_stackup). (The scaffold seeds `jitxexamples-components`, which shares the namespace, so `import jitxexamples` succeeding is not proof it is installed — the test is `import jitxexamples.jumpstart_kits`.)
 
 **Assumptions / prerequisites**
 
 - Python 3.12+ and `git` are available; the agent can run shell commands.
+- The `jitx` library your project resolves should sit on the same release line as the CLI — if pip lands a different line, say so rather than silently proceeding.
 - The stackup CSV is in the project directory, or pasted into this session.
 
 ---
@@ -25,14 +26,14 @@ session started after it, so the session that finished JS0 cannot run this runbo
 Read this runbook's revision out of the HTML comment at the top of the file and tell me what it is, so the run is pinned to a known version of the kit. This task drives the **substrate modeler** skill — confirm it is invocable before you start.
 
 **1 · Scaffold a project.**
-Run `jitx project layout init`, then set up the project environment inside it:
+Create a new project directory (copy the CSV into it, or paste the CSV into this session), run `jitx project layout init` **in it**, then set up the project environment inside it:
 
 ```bash
 # macOS / Linux
 python3 -m venv .venv && source .venv/bin/activate
 
 # Windows (PowerShell)
-py -3.12 -m venv .venv; .\.venv\Scripts\Activate.ps1
+$env:PYTHONUTF8 = "1"; py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
 ```
 
 ```bash
@@ -69,10 +70,12 @@ A good result is: `pyright` reports zero errors, `pytest` is green with every as
 **8 · [HUMAN] Close the loop — re-issue the report.**
 Now show me the substrate regenerates from the report. **Invite me to change the CSV** — suggest I say: *"the fab came back on the through-hole again — 0.400 mm finished hole this time; re-issue the report and tell me what moved."* **Wait for me to ask.**
 
-Edit the CSV only with values I give you — both unit columns for the hole, the derived columns on the same row, a Rev C history line, and the `DOCUMENT` fields the skill's re-issue rule names. Per that rule, re-derive the arithmetic over the changed row and re-run the step-5 hand checks. `Depth_mm` does **not** move — it is set by the layer span, not the hole — so the new ratio is the same depth over the new hole. Then update `board.py`, rebuild, and report before → after — including what did **not** move: no dielectric changed, so no impedance row is touched and every trace width still points at its CSV row.
+Edit the CSV only with values I give you — both unit columns for the hole, the derived columns on the same row, a Rev C history line, and the `DOCUMENT` fields the skill's re-issue rule names. Per that rule, re-derive the arithmetic over the changed row and re-run the step-5 hand checks. `Depth_mm` does **not** move — it is set by the layer span, not the hole — so the new ratio is the same depth over the new hole. Keep the CSV's filename — the revision lives in its `DOCUMENT` rows, not the name — and keep every edited column at the precision it already prints (`0.350` → `0.400`, `13.78` → `15.75`). Then update `board.py`, rebuild, and report before → after — including what did **not** move: no dielectric changed, so no impedance row is touched and every trace width still points at its CSV row.
 
 **If I ask for a dielectric change instead, stop.** A dielectric change re-solves the controlled-impedance line widths, and that solve belongs to the fab — the CSV carries its result, not the model that produced it. Report the affected trace widths as blocked pending re-solved impedance rows; do not estimate them, and do not carry the old widths forward as if they still held. If I supply re-solved rows, carry them through and report before → after for every changed width.
 
+If the rebuild ends in `status: error` with `EOF when reading a line`, the runtime asked *"Significant changes detected… Do you want to continue? [Y/n]"* on a stdin it does not have under `--background` — there is no flag to pre-answer it, and piping `y` into `jitx build` does not reach it. Tell me: I stop the background runtime and run `jitx runtime start` in my own terminal, answer the prompt there, and you rebuild.
+
 Then close this step the way step 7 closes: `pyright`, `pytest`, a `jitx build` of the design that binds the substrate, and **`jitx-code-review`**. The code and tests you wrote here have not been through that gate — step 7's review went stale the moment you edited anything.
 
 ---

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/part2-parametric-passives/JS1_Part2_Parametric-Passives_Runbook.md

@@ -1,5 +1,5 @@
 <!--
-JITX Parametric Component Families Runbook (JS1 · Part 2) · rev 1.3 · 2026-08-31
+JITX Parametric Component Families Runbook (JS1 · Part 2) · rev 1.4 · 2026-09-08
 Paste this file into your AI coding agent (Claude Code, Codex / GPT, or Devin), or upload it,
 and tell the agent to follow it. Complete the JS0 Setup Runbook first.
 START A NEW AGENT SESSION before you begin — a skills install only takes effect in a session
@@ -16,6 +16,7 @@ drives a skill.
 **Assumptions / prerequisites**
 
 - Python 3.12+ and `git` are available; the agent can run shell commands and fetch PDFs.
+- The `jitx` library your project resolves should sit on the same release line as the CLI — if pip lands a different line, say so rather than silently proceeding.
 - `pip install pymupdf` is available for datasheet page extraction (the component-modeler skill uses it).
 
 ---
@@ -96,7 +97,7 @@ Create a new project directory and run `jitx project layout init` (seeds a two-r
 python3 -m venv .venv && source .venv/bin/activate
 
 # Windows (PowerShell)
-py -3.12 -m venv .venv; .\.venv\Scripts\Activate.ps1
+$env:PYTHONUTF8 = "1"; py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
 ```
 
 ```bash
@@ -114,15 +115,15 @@ Download all four manufacturer datasheets into `.context/` (gitignored — **lin
 - **Yageo RC_L** — https://yageogroup.com/content/datasheet/asset/file/PYU-RC_GROUP_51_ROHS_L (the RC_L series datasheet, all sizes 0075–2512).
 - **Panasonic ERJ** — https://industrial.panasonic.com/cdbs/www-data/pdf/RDA0000/AOA0000C301.pdf
 - **Vishay CRCW** — https://www.vishay.com/docs/20035/dcrcwe3.pdf
-- **Samsung CL (MLCC)** — the Samsung Electro-Mechanics MLCC catalog PDF: https://product.samsungsem.com/resources/file/product-catalog/MLCC_2512.pdf (the filename is dated per revision — if it has moved, get the newest MLCC catalog from https://product.samsungsem.com/product-catalog.do). It contains the part-numbering scheme, case-size dimension tables, and the dielectric/voltage lineup.
+- **Samsung CL (MLCC)** — the Samsung Electro-Mechanics MLCC catalog PDF: https://product.samsungsem.com/resources/file/product-catalog/MLCC_2512.pdf (the filename is dated per revision — if it has moved, get the newest MLCC catalog from https://product.samsungsem.com/product-catalog.do). It contains the part-numbering scheme and the dielectric/voltage lineup; step 7 names what it does **not** contain.
 
 Per the skill's **"Verify the download is a datasheet"**: these four URLs are canonical, so if one doesn't answer, say whether you hit an egress problem or a moved document, and tell me which URL you ended up using.
 
 **3 · Family 1 — Yageo RC_L.**
-Drive the component-modeler skill with the Yageo datasheet to build `yageo_rc.py`, following its **Parameterized Component Families** and **Two-Terminal Chip Components** sections. Values encode in Yageo's RKM style (`100K`). Keep this family **self-contained in one file — no shared helpers yet**. Write `tests/test_yageo_rc.py` per the skill's **"Verifying a component with tests"**, cross-checking the datasheet's own ordering example **`RC0402JR-07100KL`**. Verify: `pyright` → `pytest` → `jitx build <non-test design target>`. Commit when green.
+Drive the component-modeler skill with the Yageo datasheet to build `yageo_rc.py`, following its **Parameterized Component Families** and **Two-Terminal Chip Components** sections. Values encode in Yageo's RKM style (`100K`). Keep this family **self-contained in one file — no shared helpers yet**. Write `tests/test_yageo_rc.py` per the skill's **"Verifying a component with tests"**, cross-checking the datasheet's own ordering example **`RC0402JR-07100KL`**. Table-driven checks go in `self.subTest(...)` — pytest's `parametrize` does not apply to `unittest`-style `TestCase` methods, and `jitx.test.TestCase` is one. Verify: `pyright` → `pytest` → `jitx build <non-test design target>`. Commit when green.
 
 **4 · [HUMAN] Verify Family 1 together.**
-Stop and walk me through the family against the datasheet before replicating the pattern. Show me: (a) two or three transcribed dimensions side-by-side with the datasheet table, **including which of the two printed termination bands you used and why**; (b) the encoder reproducing the ordering-example MPN and a decade-carry case (`9999 → "10K"`); (c) a fail-fast rejection listing the valid options — run this demo **inside the instantiation context**, since a plain script raises nothing; (d) how each vendor size label maps to the generator's size key by body L×W — including the label mismatch (Yageo `0075` → `009005`); (e) the skill's filled **Component completeness check** block. **Wait for my approval** before continuing.
+Stop and walk me through the family against the datasheet before replicating the pattern. Show me: (a) two or three transcribed dimensions side-by-side with the datasheet table, **including which of the two printed termination bands you used and why**; (b) the encoder reproducing the ordering-example MPN and a decade-carry case (`9999 → "10K"`); (c) a fail-fast rejection listing the valid options — run this demo **inside the instantiation context**, since a plain script raises nothing; (d) how each vendor size label maps to the generator's size key by body L×W — three naming systems meet here: the vendor's own label, the metric code, and the EIA imperial code the generator keys on. Yageo's `0075` is a 0.30 × 0.15 mm body, metric `03015`, imperial (and JITX key) `009005`; its `0100` is 0.40 × 0.20 mm, metric `0402`, imperial `01005`; (e) the skill's filled **Component completeness check** block. **Wait for my approval** before continuing.
 
 **5 · Family 2 — Panasonic ERJ.**
 Build `panasonic_erj.py` from the Panasonic datasheet: 3-digit EIA value code (`103`), its own tables and MPN f-string. This is the second consumer, so per the skill's **"Shared helpers — extract at the second family"**, extract them now into `chip_resistor.py` and refactor Family 1 onto them — Family 1's unchanged tests passing proves the refactor safe. Write `tests/test_panasonic_erj.py`, cross-checking **`ERJ3GEYJ102V`**. Verify: `pyright` → `pytest` (all families) → `jitx build <non-test design target>`. Commit when green.
@@ -139,7 +140,7 @@ Create a small combined `SampleDesign` that instantiates one part from **each of
 A good result is: `pyright` reports zero errors and no suppressions, the full `pytest` suite is green including every family's datasheet cross-check, `jitx build <non-test design target>` completes on the combined design, `jitx-code-review` returns no unresolved findings, and each family has its **Component completeness check** block filled in, written next to the code.
 
 **9 · [HUMAN] Close the loop — request a part.**
-The library is done; now show me what it's for. **Invite me to ask for an arbitrary part** — suggest I say: *"give me a 49.9 kΩ 0402 1% Yageo and a 100 nF X7R 0603 50 V Samsung CL."* **Wait for me to ask.** When I do, instantiate the requested parts from the family classes in the combined design, rebuild, and show me the schematic/board plus the **generated MPNs**, so I can spot-check them against the datasheets' part-numbering schemes.
+The library is done; now show me what it's for. **Invite me to ask for an arbitrary part** — suggest I say: *"give me a 49.9 kΩ 0402 1% Yageo and a 100 nF X7R 0603 50 V Samsung CL."* **Wait for me to ask.** When I do, instantiate the requested parts from the family classes in the combined design, rebuild, and show me the schematic/board — launch `jitx ui open` in the background, it blocks while its window is open (JS0 step 5 explains) — plus the **generated MPNs**, so I can spot-check them against the datasheets' part-numbering schemes.
 
 This step writes code, so it goes through step 8's gate like every other step — finish with the full verification block (`pyright` → `pytest` → `jitx build <non-test design target>` → `jitx-code-review`). Don't let the last code written be the only code that skipped the review. Print the BOM as well as the MPNs: value labels are the one thing none of those four commands checks.
 

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/part3-versal-fpga/JS1_Part3_Reference_Companion.md

@@ -1,4 +1,4 @@
-<!-- Versal FPGA from the Vendor Pin File — Reference Companion (JS1 · Part 3) · rev 1.1 · 2026-08-27 -->
+<!-- Versal FPGA from the Vendor Pin File — Reference Companion (JS1 · Part 3) · rev 1.2 · 2026-09-08 -->
 
 # Versal FPGA from the Vendor Pin File — Reference Companion (JS1 · Part 3)
 
@@ -53,8 +53,9 @@ Reference solution: the `jitxexamples` package, module
 | **Total** | **1369** |
 
 Six GTM quads, each 4 × (RXP/RXN/TXP/TXN) lanes + 2 × REFCLK pairs; the quad-column bias pins
-(`GTM_RREF_*`, `GTM_AVTTRCAL_*`, and the GTY equivalents) are single balls that take one external
-precision resistor each — the circuit wrapper exposes them as pass-through ports.
+(`GTM_AVTTRCAL_L`, `GTM_RREF_L`, `GTM_AVTTRCAL_RN`, `GTM_RREF_RN`, `GTY_AVTTRCAL_RS`,
+`GTY_RREF_RS`) are single balls that take one external precision resistor each — the circuit
+wrapper exposes them as pass-through ports.
 
 ## Two traps the runbook makes you catch
 
@@ -74,7 +75,7 @@ precision resistor each — the circuit wrapper exposes them as pass-through por
 
 - Generator reconciliation: parsed rows = file footer = **1369**, unique balls, full grid; the
   committed module regenerates **byte-identically** (`--check`).
-- 17 tests + 74 subtests pass offline on the jitx 4.4 line, including ~10 hand-read
+- 19 tests + 198 subtests pass offline on the jitx 4.4 line, including ~10 hand-read
   ball spot-checks spanning the grid corners and every bank type, symbol coverage (every port in
   exactly one box), and mapping bijectivity. Both non-test designs `jitx build` with `status: ok`.
 - Every one of the 1369 balls was **independently re-checked against the AMD file** by a

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/part3-versal-fpga/JS1_Part3_Versal-FPGA-from-Pin-File_Runbook.md

@@ -1,5 +1,5 @@
 <!--
-JITX Versal FPGA from the Vendor Pin File Runbook (JS1 · Part 3) · rev 1.3 · 2026-08-31
+JITX Versal FPGA from the Vendor Pin File Runbook (JS1 · Part 3) · rev 1.4 · 2026-09-08
 Paste this file into your AI coding agent (Claude Code, Codex / GPT, or Devin), or upload it,
 and tell the agent to follow it. Complete the JS0 Setup Runbook first.
 START A NEW AGENT SESSION before you begin — a skills install only takes effect in a session
@@ -24,6 +24,8 @@ is marked **[HUMAN]**, stop and wait for me — do not proceed until I confirm.
 > `pip install jitxexamples`, then the module
 > `jitxexamples.jumpstart_kits.js1_stackup_components.versal_fpga` — also readable on
 > [GitHub](https://github.com/JITx-Inc/jitx-examples/tree/main/src/jitxexamples/jumpstart_kits/js1_stackup_components/versal_fpga).
+> (The scaffold seeds `jitxexamples-components`, which shares the namespace, so `import jitxexamples`
+> succeeding is not proof it is installed — the test is `import jitxexamples.jumpstart_kits`.)
 > Expect roughly 2–3 hours end to end, most of it agent-autonomous.
 
 **Assumptions / prerequisites**
@@ -115,7 +117,7 @@ environment inside it:
 python3 -m venv .venv && source .venv/bin/activate
 
 # Windows (PowerShell)
-py -3.12 -m venv .venv; .\.venv\Scripts\Activate.ps1
+$env:PYTHONUTF8 = "1"; py -3 -m venv .venv; .\.venv\Scripts\Activate.ps1
 ```
 
 ```bash
@@ -209,7 +211,9 @@ comment, coordinate tables under `# fmt: off`, the structural `gtm_quad_pins()`
 **Mark the 60 NC balls `no_connect()`** — they are open per AMD, and an ordinary `Port()` makes that
 indistinguishable from a board designer forgetting to wire them. Output must be deterministic and
 `ruff format`-stable per the skill's rule for emitted collections, with a `--check` mode that
-regenerates and diffs. Run the generator; commit the generated module.
+regenerates and diffs. Read the pin file and write the module with explicit `encoding="utf-8"` and
+`newline="\n"` — the platform defaults (`cp1252`, CRLF on Windows) are what make `--check` drift
+between machines. Run the generator; commit the generated module.
 
 **7 · Build the land pattern — read the drawing, then the fine print.**
 From the figure captioned **"Package Dimensions for NFVI1369"** take body 35×35 mm, height
@@ -217,8 +221,11 @@ From the figure captioned **"Package Dimensions for NFVI1369"** take body 35×35
 Øb = 0.50/0.64/0.70 mm, but the JITX BGA generator's `ball_diameter` argument sets the **copper land
 diameter** of the PCB pad. Open the jitxlib BGA generator source and confirm what the parameter
 drives, then take the land from the table captioned **"BGA Package Design Rules"** (0.92 mm pitch →
-**0.51 mm** max PCB solder land, NSMD). State in a comment where each number came from, caption
-first. Build `landpattern.py` with a `VersalBGA(BGA)` subclass adding the public `get_pad(row,
+**0.51 mm** max PCB solder land, NSMD). The same row gives a **0.61 mm** solder-mask opening: decide
+whether you set it per pad or let the substrate's registration rules size the mask at build time,
+and record which in the same comment — either is defensible, an unrecorded default is not. State
+in a comment where each number came from, caption first. Build `landpattern.py` with a
+`VersalBGA(BGA)` subclass adding the public `get_pad(row,
 column)` adapter per the skill's BGA notes — both arguments zero-indexed, matching the coordinates
 the generated module carries, so ball A1 is `get_pad(0, 0)` and the framework's 1-based column
 offset lives inside the adapter rather than at every call site.
@@ -245,11 +252,14 @@ Show me, side by side with the pinout file: the corners **A1** and **AU37** (bot
 per bank type (a GTM lane, a GTY refclk, a PMC_MIO, an LPD_MIO, an XPIO pin); both sysmon pairs
 (VP/VN_500, VREFP/VREFN_500); and two GNDs from opposite corners — each as
 ball → `(row, col)` → port → pad. Also show the geometry cross-check: the A1↔AU37 pad centers
-must be 36 × 0.92 = **33.12 mm** apart on both axes (the drawing's D1/E1). **Wait for my approval.**
+must be 36 × 0.92 = **33.12 mm** apart on both axes (the drawing's D1/E1) — and **signed**: read each
+pad's `transform` and show A1 and AU37 at opposite corners, because the unsigned distance alone
+passes a mirrored grid. Put that signed check in the tests too. **Wait for my approval.**
 
 **11 · Wrap the circuit.**
-Drive the circuit-builder skill. Create `bundles.py` (`GTMQuad`: 4 × `LanePair` + 2 × REFCLK
-`DiffPair`) and `circuit.py` (`XCVP1002Circuit`): one `Power()` port per supply rail from your
+Drive the circuit-builder skill. Create `bundles.py` (`GTMQuad`: 4 × `jitx.common.LanePair` —
+upper-case `TX`/`RX` sub-ports with lower-case `p`/`n` inside — + 2 × REFCLK `DiffPair`) and
+`circuit.py` (`XCVP1002Circuit`): one `Power()` port per supply rail from your
 step-4 inventory — **no rail invented, none dropped**; a `rail_ties()` roster method; three ground
 domains (main GND takes all 689 GND + 2 RSVDGND + every main rail's `Vn`; `GND_SMON` and
 `GND_SENSE` take only their dedicated ball + their rail's `Vn`); sysmon inputs and the six GT
@@ -263,9 +273,10 @@ rules. Where this part instantiates them:
   so they land as scalar ports rather than rail lists. Two of the four carry the returns that
   *define* `GND_SMON` and `GND_SENSE`, so a roster built by walking the rail lists both undercounts
   and silently collapses the three-ground requirement.
-- **The six GT bias pins live in banks 109, 203 and 105** — 109 carries its pair and **no lanes at
-  all**. They serve whole supply groups, so keep them out of `GTMQuad`: model them per-quad and four
-  of the six quads have none.
+- **The six GT bias pins live in banks 109, 203 and 105** — `GTM_AVTTRCAL_L`, `GTM_RREF_L`,
+  `GTM_AVTTRCAL_RN`, `GTM_RREF_RN`, `GTY_AVTTRCAL_RS`, `GTY_RREF_RS`; 109 carries its pair and **no
+  lanes at all**. They serve whole supply groups, so keep them out of `GTMQuad`: model them per-quad
+  and four of the six quads have none.
 - **The `_L` / `_RS` group tags come from the bank diagram**, not the pin file — including which
   groups have no bonded quad in this package.
 
@@ -277,16 +288,19 @@ named net colliding with a public port name fails only in the full runtime build
 already in use"); `jitx build --dry` cannot see it.
 
 **12 · Verify the circuit.**
-Extend the tests (rail roster + sizes, ground-domain separation, 6 quads × 20 topology links,
-circuit design translates), then `pyright` → `pytest` → `jitx build <non-test circuit design target>` →
+Extend the tests (rail roster + sizes, ground-domain separation, 6 quads × 20 topology links **and**,
+for at least one quad, that each link's two endpoints are the expected bundle sub-port and component
+ball — a count alone passes a lane- or polarity-swapped wiring; circuit design translates), then
+`pyright` → `pytest` → `jitx build <non-test circuit design target>` →
 `jitx-code-review`. Commit when green.
 
 **13 · [HUMAN] Close the loop.**
 The wrapper is what a board design consumes; show me. **Invite me to ask for something** —
 suggest I say: *"give me GTM quad 205 as a 4-lane bundle and tell me which power rails and bias
 pins it needs."* **Wait for me to ask.** Answer from the built circuit (bundle port, rail ties,
-bias pass-throughs), then open the schematic viewer (`jitx ui open --schematic`) on the bank-205
-page so I can see the quad.
+bias pass-throughs), then open the schematic viewer (`jitx ui open --schematic`, in the background
+— it blocks while its window is open, see JS0 step 5) and tell me the bank-205 page to look at: the
+CLI opens the design, not a page, so I navigate there in the viewer.
 
 **This answer goes through a gate like every other step.** State which document each claim comes
 from; anything not derivable from the built design or the step-2 documents, say so rather than

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/jumpstart-kits/js1-stackup-components/part3-versal-fpga/README.md

@@ -37,7 +37,7 @@ add `GTMQuad` (4 lanes + 2 refclks) and `XCVP1002Circuit`: 31 `Power` rails, thr
 (GND / GND_SMON / GND_SENSE), and six GTM quad bundles wired through the generated pin groupings.
 
 **How we know it's right.** Reconciliation runs before any code: parsed rows = file footer = 1,369,
-unique balls, full 37×37 grid. Then 17 tests and 74 subtests on jitx 4.4 — hand-read ball
+unique balls, full 37×37 grid. Then 19 tests and 198 subtests on jitx 4.4 — hand-read ball
 spot-checks across grid corners and every bank type, symbol coverage, mapping bijectivity, circuit
 rail roster. Both designs, the component viewer and the wrapped circuit, build `status: ok` against
 the runtime. An independent 13-agent review re-checked all 1,369 balls against the AMD file with

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/src/jitxexamples/jumpstart_kits/js1_stackup_components/hdi_stackup/board.py

@@ -123,7 +123,7 @@ that don't bear on this file's own choices.
    mapping``. The mapping form accepts ``None`` values at construction time,
    but they are **translation-fatal**: ``jitx._translate.routing`` assigns
    ``desired_width`` into a protobuf float with no ``None`` guard (verified on
-   4.2.2 and 4.4.0rc2). The failure is latent in this kit because routing
+   4.2.2 and 4.4.0). The failure is latent in this kit because routing
    structures only translate when a net, topology or rule applies them, and
    ``main.py``'s smoke design has an empty circuit — it would surface in the
    first consumer design that uses one. So this file carries the planes with

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/src/jitxexamples/jumpstart_kits/js1_stackup_components/parametric_passives/components/yageo_rc.py

@@ -64,8 +64,10 @@ def _dims(
 
 
 # Yageo size label -> JITX SMT_CHIP_DEFS case key, where the two differ. Most
-# sizes use their imperial label directly; the ultra-tiny 0075/0100 are keyed in
-# the generator by their metric body size (0.30x0.15 mm, 0.40x0.20 mm).
+# Yageo labels are the EIA imperial code the generator keys on; the ultra-tiny
+# 0075/0100 are Yageo's own labels, so they map by body size to that code:
+# 0075 = 0.30x0.15 mm = metric 03015 = imperial 009005, and
+# 0100 = 0.40x0.20 mm = metric 0402 = imperial 01005.
 _SMT_KEY: dict[str, str] = {"0075": "009005", "0100": "01005"}
 
 # Dimensions (mm) from datasheet Table 1: _dims(L, +/-, W, +/-, H, +/-, l2, +/-)

{jitxexamples-1.6.0 → jitxexamples-1.6.2}/src/jitxexamples/jumpstart_kits/js1_stackup_components/versal_fpga/tools/generate_pinout.py

@@ -637,14 +637,14 @@ def main(argv: list[str] | None = None) -> int:
         help="regenerate and diff against --out; exit 1 on drift",
     )
     args = parser.parse_args(argv)
-    text = args.pinout_file.read_text()
+    text = args.pinout_file.read_text(encoding="utf-8")
     model = classify(parse_pinout(text, args.pinout_file.name))
     if args.report:
         print(inventory_report(model))
         return 0
     emitted = emit_module(model)
     if args.check:
-        committed = args.out.read_text()
+        committed = args.out.read_text(encoding="utf-8")
         if committed == emitted:
             print(f"OK: {args.out} matches regeneration")
             return 0
@@ -653,7 +653,7 @@ def main(argv: list[str] | None = None) -> int:
         )
         sys.stdout.writelines(line + "\n" for line in list(diff)[:60])
         return 1
-    args.out.write_text(emitted)
+    args.out.write_text(emitted, encoding="utf-8", newline="\n")
     counts = f"{len(model.uniques)} unique ports, {len(model.rails)} rails"
     print(f"wrote {args.out} ({counts}, {model.pinout.total_from_footer} balls)")
     return 0