Packages

Package versions identify immutable source snapshots. A dependency on component-lib@0.3.2 selects the same source for every build until the manifest changes.

Repository structure

A board repository has a root pcb.toml with [workspace] and [board] metadata, a board .zen entrypoint, and generated KiCad files under layout/. Create one with pcb new board <NAME> <REPO_URL>. A registry repository has a root [workspace] but no [board]. Both repository types can own reusable packages under components/ and modules/. Each package has its own pcb.toml and .zen entrypoints; component packages also carry their symbols and footprints. vendor/ holds vendored dependencies.

Version policy

PCB packages use semantic versions with hardware-specific compatibility rules:

Change	Allowed contents
Patch, such as `0.3.1` to `0.3.2`	Documentation and metadata changes that do not alter connectivity, layout, or electrical behavior.
Minor, such as `0.3` to `0.4`	New compatible behavior after `1.0`; a breaking compatibility lane before `1.0`.
Major, such as `1.x` to `2.0`	Breaking changes such as changed pins, interfaces, or removed behavior.

Compatibility families are minor-version lanes before 1.0 (0.3.x, 0.4.x) and major-version lanes afterward (1.x, 2.x). Do not publish breaking changes within a family. pcb sync records the selected dependency graph in pcb.toml, resolving branches and commits to immutable pseudo-versions. Builds reuse this hydrated state rather than selecting newly published versions.

Workspace package discovery

Starting at the workspace root, pcb searches at most eight directory levels and treats each descendant directory containing pcb.toml as a package. [workspace].exclude controls discovery:

[workspace]
pcb-version = "0.4"
exclude = ["scratch/**", "experiments/old-board"]

pcb does not search inside an excluded directory. It also skips generated and cache directories such as .git, .pcb, vendor, target, node_modules, and fork.

Coexisting versions

A build can contain incompatible families of one package, such as component-lib@0.3.x and component-lib@1.x. The resolver keeps separate copies for their dependents. Their values have distinct types and cannot cross the compatibility boundary.

Minimal Version Selection

Minimal Version Selection (MVS), based on Go modules, selects the highest explicit minimum required within each package family:

Board
├── component-lib >= 0.3
└── regulator >= 1.0
    └── component-lib >= 0.3.2

The board requires component-lib >= 0.3.0, while regulator requires component-lib >= 0.3.2. MVS therefore selects 0.3.2, even if 0.3.9 exists. Require a newer version explicitly when the project is ready to test it:

[dependencies]
"github.com/acme/component-lib" = "0.3.9"

Resolution starts with all workspace packages’ direct dependencies, fetches selected manifests, and raises versions to satisfy transitive requirements until the graph stops changing. It then traces the final graph from workspace roots, discarding superseded versions. MVS is deterministic and does not backtrack.

Import paths as identity

Import paths serve as globally unique package identifiers:

load("@stdlib/units.zen", "Voltage")
load("github.com/myorg/components/capacitor.zen", "Capacitor")

Paths identify the owner and repository, without versions. Declare versions in pcb.toml so imports remain stable across upgrades:

[dependencies]
"code.diode.computer/diode/registry/components/ti/tps54331" = "1.0"

Hydrated manifests

Workspaces store resolved dependency state in pcb.toml. pcb sync updates:

[dependencies]: direct dependencies the package imports or explicitly owns.
[dependencies.indirect]: the tool-managed MVS closure needed to build it.

[dependencies]
"code.diode.computer/diode/registry/modules/Regulator" = "1.0"

[dependencies.indirect]
"code.diode.computer/diode/registry/components/TPS54331@1" = "1.0.2"
"code.diode.computer/diode/registry/modules/Feedback@1" = "1.1.0"

The @1 suffix is a compatibility lane. It allows multiple incompatible versions of the same package path to coexist while keeping the selected version exact. Do not edit [dependencies.indirect] by hand. Commit hydrated pcb.toml files.

Vendoring (`[workspace].vendor`)

Vendoring policy is controlled by the root workspace manifest:

[workspace]
vendor = ["github.com/myorg/**"]

pcb publish uses [workspace].vendor patterns when staging release sources.
pcb sync vendors packages matched by [workspace].vendor.
pcb vendor without --all uses [workspace].vendor.
pcb vendor --all vendors everything.
Read commands such as pcb build, pcb layout, pcb test, pcb open, and pcb bom do not change vendor/ or rewrite dependency manifests.

Workspace name (`[workspace].name`)

Workspace manifests can override the Diode workspace name used for board release uploads:

[workspace]
name = "my-workspace"

If name is omitted, pcb publish derives the workspace name from the first path segment of [workspace].repository. For example, anything.com/XYZ/boards/MyBoard uses XYZ.

Endpoint (`[workspace].endpoint`)

Workspace manifests can override the Diode host suffix used by CLI commands that access Diode services:

[workspace]
endpoint = "diode.computer"

endpoint = "diode.computer" resolves application and API URLs under app.diode.computer and api.diode.computer.
The setting applies to workspace-aware commands such as pcb auth, pcb bom, pcb publish, and routing commands.
Authentication is scoped to the resolved endpoint. Authentication for one endpoint does not overwrite tokens for another.

BOM matching (`[workspace.bom]`)

pcb bom availability queries use strict BOM matching by default, requiring exact MPN matches. Workspace manifests can opt out to use fuzzy matching:

[workspace.bom]
strict = false

Registry search scope

Registry-backed pcb search searches the public Diode registry and the registries configured by [workspace].repository.

pcb search --registry code.diode.computer/diode/registry ... overrides the default scope for that invocation.
Repeat --registry to search more than one registry.

Pseudo-versions

Pseudo-versions identify unreleased commits while preserving version ordering. The format is v<base>-0.<timestamp>-<commit>.

[dependencies]
# Branch reference - resolved to pseudo-version
"github.com/acme/component-lib" = { branch = "main" }

# Specific commit
"github.com/acme/component-lib" = { rev = "a1b2c3d4" }

Resolution produces a version such as:

v0.3.15-0.20251120004415-137e2dcabc28…   # commit hash shortened here for readability

pcb sync writes the resolved pseudo-version back to the package manifest with the full 40-character commit hash. The base version (0.3.15) is the next patch version after the most recent tag reachable from that commit. This places the pseudo-version after its base tag and before the next release. If the package has never been tagged, pseudo-versions start in the 0.1.1 family (for example 0.1.1-0.<timestamp>-<commit>), one patch above the initial unpublished release version 0.1.0. Pseudo-versions participate fully in MVS. If one package requires component-lib@0.3.14 and another requires the pseudo-version above, MVS selects the pseudo-version (it is higher). This permits testing an unreleased change without retaining a mutable branch reference in the hydrated graph. Use a tagged release for production dependencies when one is available.

Commands

`pcb migrate`

Runs project migrations using the latest stable pcbc toolchain, regardless of the workspace’s current pcb-version lane. After all migrations succeed, the command updates [workspace].pcb-version in pcb.toml to the target toolchain lane.

pcb migrate
pcb migrate ./path/to/workspace

`pcb sync`

Reconciles imports and hydrates package manifests. Run this after adding or removing imports or changing dependency versions.

pcb sync                    # Sync packages under the current workspace/package
pcb sync --check            # CI guard: fail if pcb.toml or vendor/ is out of sync
pcb sync -v                 # Print changed manifests

The command also downloads selected packages into the cache and vendors packages matched by [workspace].vendor. pcb sync --check always verifies the whole workspace, regardless of the current directory, and writes neither pcb.toml nor vendor/. It detects missing or stale vendored package versions; it does not verify the contents of vendored versions that are already present.

`pcb add`

Adds or upgrades a direct dependency for the package in the current directory.

pcb add github.com/acme/regulators/Buck@1.2.3
pcb add github.com/acme/regulators/Buck@latest
pcb add -u                              # Upgrade all direct remote dependencies
pcb add -u github.com/acme/regulators/Buck

pcb add rewrites the direct dependency entry and rehydrates the package’s dependency closure.

`pcb build`

Builds a board or workspace package.

pcb build                    # Build default board
pcb build WV0002.zen         # Build a specific board file
pcb build --offline          # Build using only cached/vendored packages

pcb build checks that the hydrated state is sufficient and does not rewrite pcb.toml or vendor/. Use pcb sync or pcb vendor to update dependency state.

`pcb list`

Lists read-only package dependency information.

pcb list -m -u                              # Show compatible updates for direct dependencies
pcb list -m -versions github.com/acme/foo   # Show published versions for a dependency

pcb list -m -u must be run from a package directory. It reports direct remote dependencies only, showing the latest stable version in the same compatibility lane and the latest newer breaking lane when available. It does not update manifests.

`pcb update`

pcb update is disabled. Use pcb add -u instead.

`pcb publish`

Publishes changed packages with annotated Git tags.

pcb publish                  # Publish all changed packages
pcb publish --bump=infer     # Infer bumps from commit history and dependency waves
pcb publish --bump=infer -y  # Skip the final publish confirmation
pcb publish --force          # Skip preflight checks

A package requires publication when:

No version tag exists.
Its content hash differs from the published tag.
Its pcb.toml hash differs from the published tag.

Versions are computed automatically:

Unpublished: Start at 0.1.0.
Published packages: Apply the requested semantic-version bump: patch, minor, or major.
--bump=infer: Infer each bump from conventional commits since the last tag, then raise dependent bumps to at least the highest bump among published internal dependencies.
-y / --yes: Skip the final confirmation prompt.

Packages are published in dependency order. Packages with no changed dependencies are published first; their dependents follow after manifest updates.

`pcb info`

Displays workspace and package information.

pcb info                     # Show workspace summary
pcb info --format json       # Machine-readable output

Toolchain

Registry

Examples

Repository structure

Version policy

Workspace package discovery

Coexisting versions

Minimal Version Selection

Import paths as identity

Hydrated manifests

Vendoring (`[workspace].vendor`)

Workspace name (`[workspace].name`)

Endpoint (`[workspace].endpoint`)

BOM matching (`[workspace.bom]`)

Registry search scope

Pseudo-versions

Commands

`pcb migrate`

`pcb sync`

`pcb add`

`pcb build`

`pcb list`

`pcb update`

`pcb publish`

`pcb info`

​Repository structure

​Version policy

​Workspace package discovery

​Coexisting versions

​Minimal Version Selection

​Import paths as identity

​Hydrated manifests

​Vendoring ([workspace].vendor)

​Workspace name ([workspace].name)

​Endpoint ([workspace].endpoint)

​BOM matching ([workspace.bom])

​Registry search scope

​Pseudo-versions

​Commands

​pcb migrate

​pcb sync

​pcb add

​pcb build

​pcb list

​pcb update

​pcb publish

​pcb info

Repository structure

Version policy

Workspace package discovery

Coexisting versions

Minimal Version Selection

Import paths as identity

Hydrated manifests

Vendoring (`[workspace].vendor`)

Workspace name (`[workspace].name`)

Endpoint (`[workspace].endpoint`)

BOM matching (`[workspace.bom]`)

Registry search scope

Pseudo-versions

Commands

`pcb migrate`

`pcb sync`

`pcb add`

`pcb build`

`pcb list`

`pcb update`

`pcb publish`

`pcb info`