@marktiderman/genesis

One-install umbrella for the Genesis DS (design system). Holds no code of its own — every subpath re-exports a granular @marktiderman/genesis-* package.

import { Button } from "@marktiderman/genesis/ui";
import { useSwitchboard } from "@marktiderman/genesis/switchboard";
import { tokens } from "@marktiderman/genesis/design-system/tokens";

| Subpath | Re-exports | | ---------------------------- | -------------------------------------- | | @marktiderman/genesis/core | @marktiderman/genesis-core | | @marktiderman/genesis/ui | @marktiderman/genesis-ui | | .../ui/data | @marktiderman/genesis-ui/data | | .../ui/utils | @marktiderman/genesis-ui/utils | | .../ui/status-colors | @marktiderman/genesis-ui/status-colors | | .../ui/hooks | @marktiderman/genesis-ui/hooks | | .../design-system | @marktiderman/genesis-design-system | | .../design-system/tokens | @marktiderman/genesis-design-system/tokens | | .../design-system/theme | @marktiderman/genesis-design-system/theme | | .../switchboard | @marktiderman/genesis-switchboard | | .../native | @marktiderman/genesis-ui-native |

Web bundlers never pull in React Native code unless a consumer explicitly imports @marktiderman/genesis/native — react-native is an optional peer dependency. Each granular package remains independently installable as an escape hatch for rare subpaths not mirrored here.

The Genesis version coordinate

@marktiderman/genesis's own version is the single canonical coordinate for the whole Genesis system — the one number that answers "which Genesis am I on?" for a consuming repo. Pin one umbrella version and the entire set is determined:

• Sub-packages. The umbrella depends on @marktiderman/genesis-{core,ui, design-system,switchboard,ui-native} via workspace:*, which pnpm replaces with the exact published version at pack time. So @marktiderman/genesis@X resolves one reproducible, pinned set — not a caret range that drifts. Each granular package keeps its own independent semver train; the umbrella version is the coordinate that names a specific combination of them.
• Vendored harness. scripts/harness/genesis-sync.sh stamps GENESIS_SOURCE_VERSION in a child's .genesis/source from this same umbrella version (GENESIS_SOURCE_SHA stays the precise git-HEAD pointer). So a child's harness stamp and its @marktiderman/genesis npm pin read the same number.
• Plugin / marketplace. .claude-plugin/plugin.json's version tracks the umbrella coordinate, kept in lockstep by scripts/harness/sync-plugin-version.mjs (run automatically in the release "version packages" step).

The coordinate advances whenever any pinned sub-package is released. The deciding option is changesets' updateInternalDependents (default "out-of-range") — not updateInternalDependencies: because the umbrella pins each sub-package via workspace:*, which changesets resolves to the dependency's exact current version, any sub-package release moves that dependency out of the umbrella's pinned range, so out-of-range pulls the umbrella into the same release plan and bumps it. (updateInternalDependencies, default "patch", only sets the resulting bump type once the umbrella is already in the plan — it does not decide whether the umbrella is bumped.) The workspace:* exact pin is what makes this automatic — a caret range would let a patch stay in range and skip the umbrella — so PKG-04 enforces the exact pin. The release step then re-syncs the plugin stamp. One pinned umbrella version therefore means every sub-component and the harness is already "in the system," versioned and pinned together.

Because this auto-advance rests on a changesets default rather than an explicit config key — a top-level updateInternalDependents is silently ignored in changesets 2.30.0 (the option is read only from the ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH namespace) — the invariant is made upgrade-safe two ways instead: @changesets/cli is pinned to ~2.30.0 so a minor bump can't silently flip the default, and PKG-05 empirically re-asserts the umbrella auto-bump on every run (it drives changesets' own release-plan assembly with a synthetic sub-package-only changeset). A future changesets change that broke the coordinate would fail CI loudly instead of shipping silently.

Caveat — the release-PR window. The umbrella version bumps via a changesets "version packages" PR, not on the feature-PR merge itself. So there is a brief, transient window — feature PR merged, "version packages" PR not yet merged — where main's packages/genesis/package.json still carries the previous umbrella version. A child that runs genesis-sync.sh during that window stamps the new harness contents with that previous version number. Nothing is silently lost: GENESIS_SOURCE_SHA (git HEAD) is always exact and is the precise pointer; only the human-readable coordinate can lag by one release until the "version packages" PR merges.

Installing the harness alongside the umbrella

Installing @marktiderman/genesis gives you the DS packages over npm. The agent harness (hooks, skills, the belt CLI, the plugin) is a git-native surface that rides your repo's own history rather than node_modules — so it is vendored, not imported. Because the umbrella's version is the single coordinate, you bootstrap the matching harness in one command, keyed to the umbrella you just pinned:

npm i @marktiderman/genesis        # (or pnpm/bun/yarn add) — the version you pin is the coordinate

# `@marktiderman/genesis`'s published tarball ships only `dist/` + this README (see `files` in
# package.json) — the bootstrapper script itself is NOT vendored by npm yet, so
# `node_modules/@marktiderman/genesis/scripts/harness/genesis-sync.sh` does not exist. Today, fetch
# that one script straight from the source repo and run it against your repo (it only needs your
# repo root + the installed umbrella manifest — where the script itself lives doesn't matter):
git clone --depth 1 https://github.com/marktiderman/genesis.git /tmp/genesis-src
bash /tmp/genesis-src/scripts/harness/genesis-sync.sh   # BOOTSTRAPS: reads the installed umbrella,
                                                         # vendors the matching harness + scaffolds
                                                         # the Git Data System trellis
rm -rf /tmp/genesis-src

bash tools/genesis-harness/scripts/harness/genesis roller validate --ci   # validate the trellis

The bootstrap reads the source repo + version straight out of the installed umbrella manifest, prefers the release tag matching that version (falling back to the branch tip), and writes a .genesis/source stamp recording the vendored version and the exact SHA. Re-running the same script later re-vendors (upgrades) the stamped tree — and once vendored, tools/genesis-harness/ scripts/harness/genesis sync is the one-liner for that (see the sync skill). One pinned umbrella version therefore really does mean every sub-component and the harness land together, versioned by one coordinate.

Known gap. The git clone step above is a stand-in for a real npx-invokable bootstrapper (e.g. a bin entry shipping genesis-sync.sh in the umbrella's own tarball, mirroring the npx genesis-data init pattern @marktiderman/genesis-data already ships). That packaging work is tracked as follow-up, not done in this change — don't let this doc drift back to claiming the script ships with the npm install until it actually does.