jitxexamples 1.7.0__tar.gz → 2.0.0__tar.gz

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/.github/workflows/build.yaml

@@ -56,6 +56,9 @@ jobs:
         uses: ./pybuild-action  # from checkout above
         with:
            python-version: "${{ matrix.python-version }}"
+           # internal-test-designs main as of 2026-10-20: the v1 tag predates the
+           # test updates for jitx 4.6 and fails 6 reverse-flow tests on 4.6.0rc2.
+           internal-test-designs-ref: 07853dd2207c4dd17eda842af33c19854ef8919c
            run-publish: true
            hatch-index-user: ${{ vars.HATCH_INDEX_USER }}
            hatch-index-auth: ${{ secrets.HATCH_INDEX_AUTH }}

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/.github/workflows/mirror-main.yml

@@ -67,9 +67,10 @@ jobs:
           git clone --branch main "$REMOTE" "$MIRROR"
 
           # Replace the public tree with the released tree (tracked files only,
-          # via git archive), then drop the trees that stay internal: .github
-          # (our workflows) and internal (maintainer-only kit specs, program
-          # TODOs, and deck-production tooling). Wiping first lets the subsequent
+          # via git archive), then drop .github (our workflows) and internal,
+          # which no longer exists and is removed here as a guard in case a
+          # maintainer-only tree of that name is added again. Wiping first lets
+          # the subsequent
           # "git add -A" record deletions/renames, so main accumulates a normal,
           # diffable commit each release.
           find "$MIRROR" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/.gitignore

@@ -16,5 +16,3 @@ __pycache__/
 # `hatch build` output.
 /dist/
 
-# Deck-build dependencies, restored with `npm install` from the committed lockfile.
-node_modules/

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/CLAUDE.md

@@ -24,11 +24,14 @@ specifically about working *with an agent* in this repo.
   context, so instantiating a `SampleDesign` works offline. Only `jitx design build` / `jitx ui` need
   `jitx runtime start`; `jitx design build --dry <target>` translates a design without one.
 
-- **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 design 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.
+- **The repo targets the jitx 4.6 line.** `pyproject.toml` requires `jitx>=4.6.0rc2,<4.7` and
+  `jitxlib-standard>=4.6.0rc2,<4.7`. The cap matters: the floor is a pre-release, so without it a
+  resolve on the internal index takes the newest pre-release, a 4.7 alpha. Two surfaces have to
+  agree (a 4.6 package against a 4.5 runtime is not a working install), so `jitx design 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. When jitx 4.7.0 is released, raise both caps and rerun the suite: left in place, the cap
+  makes pip downgrade a 4.7 project's jitx or fall back to an older `jitxexamples`.
 
 - **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 —
@@ -40,42 +43,49 @@ specifically about working *with an agent* in this repo.
     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
-  `JITX_MOCK_PARTS_DB=1`. Do not add tests that require live parts-DB access.
+  Confirm what you got (`pip list | grep jitx`) rather than assuming. While the floors in
+  `pyproject.toml` are pre-releases that public PyPI does not carry, an isolated resolve fails
+  outright; once they are public releases, a `.dev`, `a` or `rc` suffix means the isolation did not
+  hold. Without it the `hatch` envs resolve *ahead* of the public line.
+
+- **Parts tests resolve through the project's parts chain.** `[tool.jitx.parts]` in
+  `pyproject.toml` names `src/jitxexamples/parts/example-passives.csv` followed by `ideal`. Tests that resolve
+  passives subclass `tests/parts.py:PartsTestDesign`, which loads that same chain from the project
+  its own file sits in (so pytest can start from any directory) and disables locking.
+  In a build, `ideal` needs the value pinned to one number, snaps it to E24, honors `case` and
+  `tolerance` (0402 where no case is pinned, 1% where no tolerance is), and ignores every other filter
+  (`mounting`, `type`, a rating, a dielectric, a current or a frequency), so a rated query the CSV
+  cannot meet resolves to an `IDEAL-*` part with no rating. `PartsTestDesign` swaps in
+  `PlainValueIdeal`, which declines any query carrying such a filter, so in tests that query fails
+  and a gap in the CSV cannot pass silently. A passing test still does not mean every part is
+  orderable: plain value, case and tolerance queries the CSV cannot answer get `IDEAL-*` parts.
+  A query `ideal` declines (an exact non-E24 value such as 30.9 kohm, a value range, or a tolerance
+  limit under 1%) needs a real part in the CSV. `tests/test_parts_chain.py` checks the chain order,
+  that the CSV answers before `ideal`, that a rated query fails rather than falling to `ideal`,
+  and the CSV's tolerance and unit format. Do not add tests that require live parts-source access.
 
 - **`src/jitxexamples/` is an implicit namespace package** (no `__init__.py`). Some `components/*`
   subdirectories have an empty `__init__.py` and some do not. That inconsistency is known and
   intentionally untouched — do not "fix" it as a drive-by.
 
 - **This repo is publicly mirrored** to `JITx-Inc/jitx-examples` on release
-  (`.github/workflows/mirror-main.yml` archives everything tracked except `.github/` and
-  `internal/`). Keep comments, docs, and placeholder text customer-appropriate.
-
-- **`internal/` is tracked but reaches no deployment surface.** It holds the JumpStart Kit specs,
-  program TODOs, and deck-production tooling that used to live in the now-deprecated
-  `JITx-Inc/jumpstart-kits`. Three surfaces publish out of this repo and all three work from tracked
-  files, so each excludes `internal/` explicitly: the sdist via
-  `[tool.hatch.build.targets.sdist] exclude`, the public mirror via `rm -rf "$MIRROR/internal"`, and
-  docs.jitx.com by only ever extracting `jumpstart-kits/` out of that sdist. Moving a file from
-  `internal/` into `jumpstart-kits/` **publishes it** — there is no per-file opt-out, because the
-  docs build's `exclude_patterns` is empty by contract. After touching the sdist config, verify both
-  directions: `tar tzf dist/jitxexamples-*.tar.gz` must list 28 `jumpstart-kits/` entries and no
-  `internal/` ones.
-
-- **The committed kit decks are generated; don't hand-edit the `.pptx`.**
-  `internal/deck-tooling/` holds the build scripts, and each writes straight into the kit directory
-  that publishes it — `jumpstart-kits/js0-setup/presentation/` for JS0, and the per-part directory
-  `jumpstart-kits/js1-stackup-components/part<N>-<slug>/` for each JS1 part. All four are on the
-  JITX brand (black, Arial, teal
-  `#01BFA5` / amber `#FEC107`, `jitX` mark on every slide) — see
-  `internal/deck-tooling/DESIGN-SYSTEM.md`. Neither generator is byte-deterministic, so verify a
-  rebuild with `internal/deck-tooling/deck_text.py`, which diffs slide text and speaker notes; a
-  restyle should leave that diff empty. Two earlier decks *were* patched at the XML level after
-  generation, which silently made their scripts unable to reproduce them — hence the rule.
+  (`.github/workflows/mirror-main.yml` archives everything tracked except `.github/`). Keep
+  comments, docs, and placeholder text customer-appropriate.
+
+- **Every tracked file reaches a deployment surface; there is no maintainer-only tree.** Three
+  surfaces publish out of this repo and all three work from tracked files: the sdist, the public
+  mirror, and docs.jitx.com, which only ever extracts `jumpstart-kits/` out of that sdist. Keep
+  kit specs and program TODOs out of the repo; git history holds the ones that used to be here.
+  The sdist's `exclude = ["internal"]` and the mirror's `rm -rf "$MIRROR/internal"` stay as guards
+  in case such a tree is added again. A file placed in `jumpstart-kits/` **publishes**: there is
+  no per-file opt-out, because the docs build's `exclude_patterns` is empty by contract. After
+  touching the sdist config, verify: `hatch build -t sdist`, then
+  `tar tzf dist/jitxexamples-*.tar.gz` must list one `jumpstart-kits/` entry per tracked file under
+  `jumpstart-kits/` (26 today) and no `internal` entry.
+
+- **Kits carry no presentation decks.** The JS0 and JS1 decks and their deck tooling were
+  removed on 2026-10-22; a kit is its README pages, runbooks, reference companions and supplied
+  inputs. `git log -- internal/deck-tooling` recovers the old tooling from history.
 
 - **Merge a `develop` → `main` release PR with "Create a merge commit", never "Squash and merge".**
   Feature PRs into `develop` are squashed as usual; the release PR is the exception. Squashing

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.5
 Name: jitxexamples
-Version: 1.7.0
+Version: 2.0.0
 Summary: Library of example JITX components, substrates, and demo designs
 Project-URL: Homepage, https://jitx.com
 Project-URL: Documentation, https://docs.jitx.com
 Author: JITX
 Maintainer: JITX
 Requires-Python: >=3.12
-Requires-Dist: eseries
-Requires-Dist: jitx<5,>=4.4.0
-Requires-Dist: jitxlib-parts<2,>=1.3.0
-Requires-Dist: jitxlib-standard<5,>=4.4.0
-Requires-Dist: jitxlib-voltage-divider<2,>=1.0.0
-Requires-Dist: pytest
+Requires-Dist: eseries<2,>=1.2.1
+Requires-Dist: jitx<4.7,>=4.6.0rc2
+Requires-Dist: jitxlib-parts<3,>=2.0.0rc1
+Requires-Dist: jitxlib-standard<4.7,>=4.6.0rc2
+Requires-Dist: shapely<3,>=2.1

jitxexamples-2.0.0/README.md

@@ -0,0 +1,157 @@
+# jitx-examples
+
+## What this is
+
+`jitxexamples` is a library of example JITX package contents:
+
+- **Components**: Python classes that model real, sourceable electronic parts (op-amps, FETs, MCUs, regulators, connectors, sensors, etc.) for use with the JITX PCB design framework.
+- **Substrates**: reusable PCB stackups, via definitions, and fabrication constraints.
+- **Patterns**: small single-technique modules, each with a design that translates.
+- **Demos**: buildable example boards that compose package components, substrates, routing rules, and geometry into complete JITX designs.
+
+## Commands
+
+```bash
+hatch test --cover        # run the test suite with coverage (canonical, per README)
+hatch fmt --check         # check formatting/lint (ruff 0.14.9, config in pyproject)
+hatch run types:check     # pyright type check
+hatch run types:stats     # pyright stats
+
+pytest tests/test_AO3401A.py            # run a single test file
+pytest tests/test_AO3401A.py -k ao3401a # run a single test
+```
+
+### Run demos
+
+JITX design builds require an installed and running JITX runtime. From the project root:
+
+```bash
+jitx runtime start --background
+jitx design find
+jitx design build jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design
+jitx ui open --board --design jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design
+```
+
+Build the explicit non-test design target above; do not substitute similarly named targets from
+`test`, `tests`, or a test file listed by `jitx design find`.
+
+`jitx design build` writes its output to `<repo-root>/designs/<module.path.design_name>/`
+(`design-info/`, `temp/`, ...). That directory name is chosen by JITX, not by this repo, and is
+git-ignored — which is why the Python sources live in `src/jitxexamples/demos/` rather than
+`src/jitxexamples/designs/`.
+
+The git `pre-commit` hook (`hooks/pre-commit`) runs `ruff check`, `ruff format --diff`, and `python -m unittest discover` on staged Python files. Install it with `git config core.hooksPath hooks` (or symlink into `.git/hooks/`).
+
+Lint is intentionally narrow: ruff `select = ["E","F","W","A","B","C"]` with `E501`, `A005`, `C901`, `A002` ignored. Line length 88, double quotes.
+
+## Architecture
+
+### Component definitions (`src/jitxexamples/components/<category>/`)
+Components are grouped into category packages (`opamps/`, `fets_n_ch/`, `mcus/`, `connectors/`, ...). Each `.py` file defines one component as a subclass of `jitx.Component`. The `__init__.py` files are empty — components are imported by their full module path (e.g. `from jitxexamples.components.fets_p_ch.AO3401A import AO3401A`).
+
+A component class is declarative. The standard shape (see `components/opamps/texas_instruments_OPA189.py`):
+- Metadata class attributes: `mpn`, `manufacturer`, `reference_designator_prefix`, `datasheet`.
+- `Port()` attributes for each pin/signal.
+- A `landpattern` built from a footprint generator (`jitxlib.landpatterns.generators.*`, e.g. `SOT23_5`) configured with `LeadProfile` and `jitx.Toleranced` dimensions.
+- A `symbol` from `jitxlib.symbols.*`.
+- A `mappings` list of `jitx.PadMapping` (port → `landpattern.p[n]`) and `jitx.SymbolMapping` (port → symbol pin).
+
+Some files ship an accompanying `.stp` (3D STEP model) alongside the `.py`. Some components also alias the class as `Device: type[...] = ...`.
+
+### JumpStart kit reference solutions (`src/jitxexamples/jumpstart_kits/`)
+Importable reference solutions for the JumpStart kit runbooks published from `jumpstart-kits/`
+(one package per kit, e.g. `js1_stackup_components/`, with one subpackage per task deliverable:
+`hdi_stackup/`, `versal_fpga/`). These are covered by the same ruff, pyright, and pytest gates as
+the rest of the package. The learner-facing runbooks and supplied inputs live in `jumpstart-kits/`
+at the repo root (published to the docs site), not here.
+
+### Substrate definitions (`src/jitxexamples/substrates/`)
+Substrates define reusable PCB construction details. `generic_20layer.py` provides `Generic_Substrate`, a generic 20-layer stackup with dielectric/conductor materials, fabrication constraints, and via classes that designs can use directly or specialize.
+
+### Pattern definitions (`src/jitxexamples/patterns/`)
+Patterns are small modules that each show one technique, written to be read; each ends in a design that translates with `jitx design build --dry`. `fenced_pour_outline.py` fences an arbitrary closed outline (an antipad, an RF cavity, a BGA breakout) with vias: a `Tag`, a `design_constraint(...).fence_via(...)` rule on the substrate, and a tagged `Pour` inside a `FencedOutline` circuit whose `GND` port connects to the board's ground net. A `KeepOut` over the same outline, which keeps pours and auto-placed vias out of the opening, is optional; the module adds one. Its design target is `jitxexamples.patterns.fenced_pour_outline.fenced_pour_outline_design`. To see the fence, run a full build (`jitx design build <target>`, which needs the runtime) and open the board with `jitx ui open --board --design <target>`.
+
+The `si_*` modules each show one signal-integrity constraint on jitx 4.6, on plain nets with code routes that close the path, and their docstrings paste the design-issues output they produced: `si_point_to_point` (timing and loss with a `TerminatingPinModel`), `si_series_part` (a `BridgingPinModel` through a series part), `si_via_model` (a via with `models`), `si_diff_pair` (intra-pair skew), `si_bundle_skew` (skew across pairs with `ConstrainReferenceDifference`), `si_daisy_chain` (an ordered chain with `>>`), `si_via_structure` (a via structure from `jitxlib.via_structures`) and `si_signal_constraint` (a `SignalConstraint` subclass); `si_parts` holds their fictional parts. The `pin_*` modules show SI constraints on pin-assigned paths: `pin_lane_polarity` (lane choice and P/N inversion on a provider that is one end of the path) and `pin_series_array` (channel choice through a pass-through part, both sides in one mapping). The `jitx-interconnect-constraints` and `jitx-pin-assignment` skills point at them as worked patterns.
+
+### Protocol definitions (`src/jitxexamples/protocols/`)
+High-speed protocols that `jitxlib.protocols` does not ship: port bundles plus a `SignalConstraint` whose skew limits cite their source and its scope in the module docstring. Each protocol module has a worked example beside it named `<protocol>_example.py`, a `SampleDesign` that nets a fictional controller to a real memory part and applies the constraint without `>>`. Today that is `memory/lpddr4.py` (Micron MT53E1G32D2FW-046 WT:B, an LPDDR4X/LPDDR4 part, target `jitxexamples.protocols.memory.lpddr4_example.LPDDR4ExampleDesign`) and `memory/ddr4.py` (Micron MT40A1G16TB-062E:F, target `jitxexamples.protocols.memory.ddr4_example.DDR4ExampleDesign`). The examples are not routed, so the design issues (each example's docstring shows the `issues(satisfied=True)` call) list each constrained path as `Unconnected Topology` until the board is routed.
+
+### Demo definitions (`src/jitxexamples/demos/`)
+Demos are buildable JITX `SampleDesign` classes. The SI BGA optimization example lives under `demos/si_bga_optimization/`; its build target is `jitxexamples.demos.si_bga_optimization.bga_escape.bga_optimization_design`.
+
+Within that demo package, `constraints.py` defines the design-rule `Tag` subclasses and the antipad fence-via `design_constraint` rules; `substrate.py` specializes the generic substrate with the 85 ohm stripline routing structure and per-signal-layer launch profiles (`BGAEscapeSubstrate`), anchoring the fence rules into the design tree; `si_geometry.py` builds the per-lane signal-via antipad, deskew-arc, GND-stitching, and board-level SI-cutout geometry, including the HFSS-instrumented-lane override; and `bga_escape.py` assembles the per-lane `EscapeLane` circuits into the top-level `BGALink` and holds the buildable `bga_optimization_design` entry point. `generic_bga.py` defines the reusable hex-grid BGA component used by the design, and `deskew.py` contains support geometry for the BGA diff-pair deskew copper.
+
+### Tests (`tests/`)
+One `test_*.py` per component. Tests subclass `jitx.test.TestCase` (a `unittest.TestCase` that activates the JITX *instantiation context* in `setUpClass` — required so that JITX class members instantiate correctly; do not use plain `unittest.TestCase` for code that builds design elements). A test typically defines a `SampleDesign` subclass containing an `@inline class circuit(Circuit)` that instantiates the component, then asserts on the built design.
+
+## Dependencies & environment
+
+Requires Python ≥3.12; the test matrix covers 3.12/3.13/3.14. Built with hatchling + hatch-vcs (version derived from git tags). Core deps: `jitx>=4.6.0rc2,<4.7`, `jitxlib-standard>=4.6.0rc2,<4.7`, `jitxlib-parts>=2.0.0rc1,<3`, `eseries>=1.2.1,<2`, and `shapely>=2.1,<3`. The wheel packages `src/jitxexamples`; `docs/` and `tests/` are excluded from `[tool.jitx]` discovery, while `docs/` is also excluded from pyright.
+
+## Parts configuration
+
+Some component circuits here create `jitxlib.parts.Resistor`, `Capacitor`, or `Inductor` from
+electrical constraints with no MPN named, and each query goes to the providers of a parts chain in
+order ([jitxlib-parts docs](https://github.com/JITx-Inc/jitxlib-parts#readme)). Your project owns
+that chain: the `jitxexamples` wheel carries the example CSV but no chain, and without a chain
+resolution stops with `NoChainConfigured`. This repository's `pyproject.toml` sets:
+
+```toml
+[tool.jitx.parts]
+chain = ["csv:src/jitxexamples/parts/example-passives.csv", "ideal"]
+```
+
+The `csv:` path is relative to this repository's root, so it names the source file in a checkout;
+a project that installed `jitxexamples` copies the file out instead (below). That CSV is asked
+first. It holds real resistors, capacitors, and inductors as an example. Every resistor row has a
+`max_power`, except the 0 ohm jumpers, which the datasheet rates by current: their `max_current` is
+that rated current. Every inductor row has a `max_current`: the DC current the part carries within
+both its temperature-rise and saturation ratings, the lower of the two where the datasheet gives
+both. On a resistor row, `rated_voltage_dc` is the datasheet's maximum working (limiting element)
+voltage. The voltage across a resistor at its rated power, sqrt(P x R), is lower than that for low
+values, so state a resistor's dissipation with `max_power`. The example CSV is not a qualified
+approved-vendor list. Columns other than `category`, `mpn`, `manufacturer`, and `datasheet` are
+attributes a query can filter or rank on. A bare number gets a unit only in `resistance`,
+`capacitance`, `inductance`, `rated_voltage_dc`, `max_current`, `max_power`, and `area`; elsewhere
+write the unit (`6.2 GHz`), or a query with units on that column fails with a dimension mismatch.
+
+`ideal` answers only what the CSV could not. Its parts have an MPN starting `IDEAL-`, no
+manufacturer, and cannot be ordered. It needs the value pinned to one number and snaps it to E24. It
+takes the `case` the query names (the first, if it names several), or 0402 if it names none, and an
+exact `tolerance`, or 1% otherwise. It ignores every other filter, including ratings, dielectric,
+`mounting`, and `mpn`. So a query the example CSV cannot meet and that names no `case`, such as a 10
+µF capacitor rated 56 V or a 10 µH inductor rated 1 A, comes back as an 0402 part with no rating. `ideal`
+declines a value range, and a query its snapped value, case, or tolerance does not meet (an exact
+4.99 kohm, or a tolerance limit under 1%); such a query must match a CSV row or resolution fails. A
+`csv:` path that names no file reads as an empty catalogue with no error, so every query `ideal` can
+meet gets an `ideal` part.
+
+`PartsTestDesign` in `tests/parts.py` uses the same chain with locking off, and limits `ideal` to
+queries on value, case, and tolerance, so a test fails where a build would drop a filter.
+
+With no `lock` keys set, a build here records the passives it resolves in `parts.lock.json` at the
+repository root, `ideal` parts included, and later builds reuse those entries. Adding the real part
+to the CSV does not replace an `ideal` part already in the lockfile; delete `parts.lock.json` to
+resolve again, and search it or the BOM for `IDEAL-` to see what is left. For a board you intend to
+order:
+
+```toml
+[tool.jitx.parts]
+chain = ["csv:parts/approved-parts.csv"]
+lock = "parts.lock.json"
+lock-mode = "read-write"
+```
+
+A project that installed `jitxexamples` can copy the example in to try these circuits: pass
+`importlib.resources.files("jitxexamples") / "parts" / "example-passives.csv"` to `shutil.copy`
+with the destination `parts/approved-parts.csv` (the `parts/` directory must exist). The copy is
+not an approved list. Every row needs your approval before you order a board built from it.
+Point `csv:` at your approved-parts list, starting from the example header: these circuits filter or
+rank on `case`, `mounting`, `tolerance`, `type`, `temperature_coefficient_code`, `rated_voltage_dc`,
+`max_current`, `self_resonant_frequency`, `quality_factor`, and `material_core`, plus the value
+columns. Remove `"ideal"` so that a query your list cannot meet, a column your list lacks, or a
+wrong CSV path fails instead of resolving to a part that ignores the filters asked for. Commit the
+`parts.lock.json` a build writes, so a catalogue change cannot silently change an existing board;
+the `lock` lines spell out the defaults, with paths relative to the project root. To share a
+catalogue as package data, use `jitxlib.parts.providers.CsvParts.from_package(...)` or publish a
+chain through the `jitxlib-parts-policy` entry point.

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/docs/Makefile

@@ -6,6 +6,7 @@ SHELL := /bin/bash
 # You can set these variables from the command line, and also
 # from the environment for the first three.
 PIPOPTS       ?= --extra-index-url "https://pypi.jitx.com/jitx/main/+simple"
+PYTHON        ?= python3
 SPHINXOPTS    ?= --jobs 1 --write-all --fresh-env --warning-file build.out
 SPHINXAPIDOC  ?= sphinx-apidoc
 SPHINXBUILD   ?= sphinx-build
@@ -21,7 +22,7 @@ all: html archive
 
 # create python venv
 .venv: requirements.txt
-	python -m venv .venv \
+	$(PYTHON) -m venv .venv \
 	  && source .venv/bin/activate \
 	  && pip install $(PIPOPTS) -r requirements.txt \
 	  && touch .venv
@@ -52,4 +53,4 @@ archive:
 # clean up
 .PHONY: clean
 clean:
-	rm -rf .venv "source/jitxlib" "$(BUILDDIR)" build.out "$(ARCHIVENAME)"
+	rm -rf .venv "source/jitxexamples" "$(BUILDDIR)" build.out "$(ARCHIVENAME)"

jitxexamples-2.0.0/docs/requirements.txt

@@ -0,0 +1,8 @@
+sphinx>=8.1.0,<9.0
+sphinx_autodoc_typehints
+
+jitx>=4.6.0rc2,<4.7
+jitxlib-standard>=4.6.0rc2,<4.7
+jitxlib-parts>=2.0.0rc1,<3
+eseries>=1.2.1,<2
+shapely>=2.1,<3

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/docs/source/conf.py

@@ -40,7 +40,7 @@ exclude_patterns = []
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "alabaster"
-html_static_path = ["_static"]
+html_static_path = []
 
 # -- Don't show "Bases: object" in api docs ----------------------------------
 # https://stackoverflow.com/questions/46279030/how-can-i-prevent-sphinx-from-listing-object-as-a-base-class

jitxexamples-2.0.0/docs/source/index.rst

@@ -0,0 +1,11 @@
+.. jitxexamples documentation master file
+
+jitxexamples documentation
+==========================
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   jitxexamples/components/modules

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/jumpstart-kits/README.md

@@ -9,16 +9,14 @@ landing page itself.
 
 ## What belongs here
 
-Learner-facing narrative and collateral only: runbooks, reference companions, supplied inputs, and
-decks. Importable solution code lives under `src/jitxexamples/jumpstart_kits/` where the repo's
+Learner-facing narrative and collateral only: runbooks, reference companions, and supplied inputs.
+Kits carry no presentation decks. Importable solution code lives under `src/jitxexamples/jumpstart_kits/` where the repo's
 ruff, pyright, and pytest gates cover it.
 
-Internal material stays in `internal/` at the repo root: requirement specs, program TODOs, and
-deck-production tooling. That tree is excluded from the sdist and from the public mirror, so it
-reaches no deployment surface. **Every `.md` placed here, by contrast, will be published to
-docs.jitx.com and into the site-root `llms.txt`** once the docs build picks up this section — so
-write everything here as public from the outset, and never link from here into `internal/` (the
-link would 404 on the docs site).
+**Every `.md` placed here will be published to docs.jitx.com and into the site-root `llms.txt`**
+once the docs build picks up this section, so write everything here as public from the outset,
+and link only to pages and files that are published too (any other link would 404 on the docs
+site).
 
 ## Structure
 
@@ -32,7 +30,7 @@ link to one child.
 
 ## Linking collateral, and the one place Sphinx syntax is needed
 
-A plain relative markdown link is all you need for a deck, a PDF, or a supplied input: the docs build
+A plain relative markdown link is all you need for a PDF or a supplied input: the docs build
 turns a link to a **non-document** file into a real download, served from
 `_downloads/<sha256-of-its-bytes>/<name>`.
 

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/jumpstart-kits/js0-setup/JS0_Environment_Setup.md

@@ -243,43 +243,46 @@ to `@jitx <request to AI>` for general work). For example:
 ## Appendix A — Python dependencies
 
 Creating a project installs the packages below into the project virtual environment. The JS kits
-require **JITX 4.4.0 or newer**. The table is an **illustrative snapshot of the shape of the
-dependency set**, captured from a freshly scaffolded project on **JITX 4.4.0 with Python 3.12** —
-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.
+require **JITX 4.6.x**. The table is an **illustrative snapshot of the shape of the
+dependency set**, captured from a freshly scaffolded project on Python 3.12.1 with pre-release 4.6
+builds: jitx 4.6.0rc9.dev2+ga358849d8, jitxcore 4.6.0rc3 and jitxlib-standard
+4.6.0rc3.dev12+g2fd994d25. The capture machine's pip serves pre-releases, which is why protobuf
+7.37.0rc1 appears, and jitx and jitxlib-standard were pinned to 4.6 after
+`jitx project dependencies upgrade` moved them past it. 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 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
+> line**: the same major.minor, e.g. a 4.6.x runtime with 4.6.x packages. Patch numbers can differ;
+> release lines cannot: a 4.6 package against a 4.4 runtime is not a working install. `jitx runtime
 > introspect` reports the runtime, `pip show jitx` the package.
 
 | Package | Version |
 | --- | --- |
 | annotated-doc | 0.0.5 |
-| anyio | 4.14.2 |
-| certifi | 2026.7.22 |
+| anyio | 4.15.1 |
+| certifi | 2026.10.23 |
 | click | 8.5.0 |
 | flexcache | 0.3 |
 | flexparser | 0.4 |
 | h11 | 0.16.0 |
 | httpcore | 1.0.9 |
 | httpx | 0.28.1 |
-| idna | 3.19 |
-| jitx | 4.4.0 |
-| jitxcore | 4.4.0 |
-| jitxlib-standard | 4.4.0 |
+| idna | 3.20 |
+| jitx | 4.6.0rc9.dev2+ga358849d8 |
+| jitxcore | 4.6.0rc3 |
+| jitxlib-standard | 4.6.0rc3.dev12+g2fd994d25 |
 | markdown-it-py | 4.2.0 |
 | mdurl | 0.1.2 |
-| numpy | 2.5.2 |
+| numpy | 2.5.4 |
 | packaging | 25.0 |
 | Pint | 0.24.4 |
-| pip | 25.0.1 |
-| platformdirs | 4.11.5 |
-| protobuf | 7.36.1 |
+| pip | 23.2.1 |
+| platformdirs | 4.14.0 |
+| protobuf | 7.37.0rc1 |
 | psutil | 7.2.2 |
 | Pygments | 2.21.0 |
 | rich | 14.3.4 |
-| shapely | 2.1.2 |
+| shapely | 2.2.0 |
 | shellingham | 1.5.4 |
 | typer | 0.25.1 |
 | typing_extensions | 4.16.0 |

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/jumpstart-kits/js0-setup/JS0_Reference_Companion.md

@@ -1,4 +1,4 @@
-<!-- JITX Setup — Reference Companion (JS0) · rev 1.6 · 2026-09-14 -->
+<!-- JITX Setup — Reference Companion (JS0) · rev 1.7 · 2026-10-28 -->
 
 # 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 `$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 design 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.
+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 run `pip install jitx`, `jitx project dependencies upgrade`, `jitx runtime start --background`, and `jitx design find`. After the upgrade, `pip show jitx` and `jitx runtime introspect` should report the same release line (4.6 and 4.6, say). **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 design find` — ignore any target whose module path comes from `test`, `tests`, or a test file. **Take the target verbatim from `jitx design 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 design 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 design 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.7.0 → jitxexamples-2.0.0}/jumpstart-kits/js0-setup/JS0_Setup_Runbook.md

@@ -1,5 +1,5 @@
 <!--
-JITX Setup Runbook (JS0) · rev 1.6 · 2026-09-14
+JITX Setup Runbook (JS0) · rev 1.7 · 2026-10-28
 Paste this file into your AI coding agent (Claude Code, Codex / GPT, or Devin), or upload it,
 and tell the agent to follow it.
 -->
@@ -88,8 +88,8 @@ jitx runtime start --background
 jitx design 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 design find` — ignore any target whose module path comes from `test`, `tests`, or a test file. **Take the target verbatim from `jitx design 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 design 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 design 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 design 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.
+- **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 design find`; ignore any target whose module path comes from `test`, `tests`, or a test file. **Take the target verbatim from `jitx design 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 design 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 design 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`. If `jitx design find` also prints a warning, or an `errors:` block naming only test modules (`test_*`, `conftest`), that is not a fault here: take the target from the `designs:` list. If the target is not there, or the `errors:` block names any other module, stop and show me the `errors:` lines. And after `jitx project dependencies upgrade`, `pip show jitx` and `jitx runtime introspect` must report the same release line (4.6 and 4.6, say); 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.
 

{jitxexamples-1.7.0 → jitxexamples-2.0.0}/jumpstart-kits/js0-setup/README.md

@@ -8,17 +8,10 @@ steps that need you. Everything below is the context around it.
 Takes you from scratch to a configured, authenticated, skills-enabled JITX environment — proven by
 two real builds and a closing design-as-code change. Work through JS0 before JS1.
 
-Requires JITX 4.4.0 or newer.
+Requires JITX 4.6.x.
 
 ## Start here — the JS0 walkthrough
 
-You can get oriented by reading this page or alternatively downloading the 5-slide deck.
-Instruction content is also available as a PDF or PPTX for reference or distribution, from the
-[Presentation](presentation/) page:
-
-- [JS0_Presentation.pdf](presentation/JS0_Presentation.pdf) — read-only, opens anywhere
-- [JS0_Presentation.pptx](presentation/JS0_Presentation.pptx) — editable PowerPoint
-
 ### The goal — get JITX set up and AI-enabled correctly
 
 You finish with the JITX CLI and runtime installed, an authenticated session, the JITX skills

jitxexamples-2.0.0/jumpstart-kits/js1-stackup-components/README.md

@@ -0,0 +1,59 @@
+# JS1 — Stackup and Component Handling
+
+**Shortcut:** Download the runbook for the part you want, hand it to your AI coding agent, and tell
+it to follow the file:
+
+- {download}`Part 1 · Stackup <part1-stackup/JS1_Part1_Stackup-from-Fab-CSV_Runbook.md>` — hand it
+  [the supplied fab CSV](part1-stackup/JS1_Part1_Fab-Stackup.csv) as well
+- {download}`Part 2 · Versal FPGA <part2-versal-fpga/JS1_Part2_Versal-FPGA-from-Pin-File_Runbook.md>`
+
+**Start a new agent session before you begin any part.** Every step of a JS1 runbook drives a JITX
+skill, and a skills install only takes effect in a session started after it.
+
+Each part is self-contained and stops at the `[HUMAN]` steps that need you, but all of them assume
+[JS0](../js0-setup/) is done. Everything below is the context around each part.
+
+JS1 has two parts, building a stackup (Part 1) and component creation (Part 2). They are
+**independent**, so either can be tackled first.
+
+In every part the user uses agents to drive a JITX skill rather than hand-writing the code, and
+nothing counts as done until it clears its ground-truth check (the fab spec or the
+vendor pin file) **and** `jitx design build <non-test design target>` completes successfully.
+
+## Start here — the JS1 walkthrough
+
+Each part has its own page carrying everything that part needs: the
+runbook you hand to an agent, any supplied input, and the reference solution.
+
+### Part 1 — Stackup
+
+Turn a fab-house stackup report into a verified 20-layer HDI substrate by driving
+`jitx-substrate-modeler`, with tests that re-read the report and a summed stack thickness that has
+to equal the report's finished thickness. Two `[HUMAN]` gates stop for you.
+
+Runbook, the supplied fab CSV, and the reference solution are on the
+[Part 1 page](part1-stackup/).
+
+### Part 2 — FPGA
+
+Generate a 1,369-ball FPGA (Versal) component from the vendor's machine-readable pin file, then wrap
+it in the circuit so a board design can instantiate the FPGA by driving `jitx-component-modeler` and
+`jitx-circuit-builder`.
+
+The part is an AMD Versal Premium VP1002 in the NFVI1369 package, and AMD publishes its ball map as
+a machine-readable file — so you parse it rather than transcribe it. A committed, stdlib-only
+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), an offline test suite 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.
+
+Runbook, the reference companion, and the reference solution are on the
+[Part 2 page](part2-versal-fpga/).
+
+## Reference solutions
+
+Verified code for both parts ships as importable code in the `jitxexamples` package, under
+[`jitxexamples.jumpstart_kits.js1_stackup_components`](https://github.com/JITx-Inc/jitx-examples/tree/main/src/jitxexamples/jumpstart_kits/js1_stackup_components) —
+one module per part, named on that part's page.