Consuming `@conform-ed/*` and `@pgxsinkit/*`

emergent depends on two in-house library families published from their own repos:

• @conform-ed/* — conformance/QTI/Common-Cartridge libraries (repo: conform-ed/conform-ed)
• @pgxsinkit/* — the sync/data-layer foundation (repo: pgxsinkit/pgxsinkit)

Each is published to two registries, and emergent consumes them differently depending on whether you want released versions (the default) or unreleased work-in-progress.

Default: public npm (what CI, k3s and prod use)

The committed package.json specs are release pins (e.g. @conform-ed/contracts: ^0.1.2, @pgxsinkit/contracts: 0.1.32), resolved from public npm. No token, fully reproducible.

Bump them with your normal workflow:

bun update --latest --recursive --interactive

--latest follows each package’s latest dist-tag — i.e. the released version on npm — and ignores the -dev.* prereleases. So this only ever moves you between proper releases. Nothing about GitHub Packages is involved in this path; the token is never needed here.

A new library release only shows up here once it has been published to npm (the publisher’s manual step — see each repo’s RELEASING.md). A version that exists only on GitHub Packages will not appear in bun update --latest.

Opt-in: GitHub Packages dev channel (local only)

Every push to a library’s develop publishes a -dev.<sha> build to the GitHub Packages npm registry (npm.pkg.github.com); develop is freely rewritable, main stays stable and publishes nothing on push (ADR-0031 amendment). To preview that unreleased work in emergent locally:

bun run dev:link      # write the gitignored bunfig.toml (token via `gh auth token`), repoint every
                      # @conform-ed/@pgxsinkit spec at the `dev` dist-tag, then install
bun run dev:status    # show whether you're linked + what each scoped dep resolves to
bun run dev:unlink    # remove bunfig.toml, restore the committed release pins, then install

dev:link needs a read:packages token — npm.pkg.github.com requires auth even for public packages (unlike npmjs/GHCR). Run gh auth refresh -s read:packages once; the script reads it via gh auth token (or $GH_PACKAGES_TOKEN). dev:unlink restores ONLY the scoped specs from git show HEAD, so it never clobbers unrelated edits.

Under the hood it is exactly the manual flow: copy bunfig.toml.example → bunfig.toml, flip the routed scopes’ specs to dev (routing is all-or-nothing per scope — a leftover ^0.1.2 would 404 on GitHub Packages), then bun install; unlink reverses it.

Why bunfig.toml and not ~/.npmrc

emergent’s local build runs bun install inside a k3s pod that hostPath-mounts this project directory. A gitignored file in the project dir is visible in the pod (.gitignore governs git tracking, not file presence); ~/.npmrc and host environment variables are not (the pod has its own $HOME/env). So the routing + token must live in bunfig.toml, which is gitignored so the token never gets committed.

Don’t commit the dev pins

-dev.* versions only exist on GitHub Packages, so committing them would break any build that uses public npm (CI, k3s, prod). The dev channel is a local preview lane; the way unreleased work reaches CI/prod is by the library cutting a real release to npm, then bun update --latest.

Agent Skills (AI-assistant guidance shipped in the packages)

@pgxsinkit/* ships TanStack Intent Agent Skills — skills/**/SKILL.md files bundled inside each npm package (client, contracts, server, react) that teach an AI agent how to use the toolkit correctly, version-pinned to whatever pgxsinkit release emergent has installed. They complement (do not replace) pgxsinkit’s published llms.txt: llms.txt is the broad mental model pulled by URL; the skills are task-scoped and travel with the installed package. Current set: core, operating (@pgxsinkit/client), registry-authoring (@pgxsinkit/contracts), deploying (@pgxsinkit/server), react (@pgxsinkit/react).

Once emergent is on a pgxsinkit release that includes them, discover and load them from this repo:

bunx @tanstack/intent@latest list                        # what @pgxsinkit/* ships
bunx @tanstack/intent@latest load @pgxsinkit/client#core  # print one skill
bunx @tanstack/intent@latest install                      # add loading guidance to AGENTS.md / CLAUDE.md

(Use the @latest form; @electric-sql/client also ships an intent binary, so a bare intent in node_modules/.bin can resolve to the wrong CLI.)

REMINDER — validate the skills as we push pgxsinkit through emergent. Treat the skills (and pgxsinkit’s docs/llms.txt) as living artifacts. As real integration work hits each area, check that the relevant skill is actually accurate and useful at the moment you’d reach for it, and capture every gap, wrong assumption, or missing failure mode the integration surfaces. Feed those back upstream in pgxsinkit/pgxsinkit (fix the SKILL.md and the source doc it derives from) rather than working around them in emergent — same rule as any other @pgxsinkit/* bug. This is a deliberate pre-launch loop: harden the skills on a real consumer before publicising them widely.