# Publishing `@whynot/design`

`@whynot/design` is published to the **coulomb Gitea npm registry** so consuming
repos can pin a version (`npm i @whynot/design@x.y.z`) and track it at their own pace
(WHYNOT-WP-0003). The git tag cut by `make release` (see `DesignSystemIntroduction.md`
§6) is the version; publishing makes that version installable.

- Registry: `https://gitea.coulomb.social/api/packages/coulomb/npm/`
- `package.json` `publishConfig.registry` already points `npm publish` here.
- `lit` is a **peerDependency** — consumers install it themselves so their bundler
  dedupes to a single `lit` instance.

## The token (never commit it)

Publishing and installing `@whynot/*` need a Gitea package token. It is **not stored in
this repo** — per `.claude/rules/credential-routing.md`, tokens are routed, not vended:
a Gitea package token is operator/OpenBao-owned (`railiance-platform`). Obtain one from
the operator and export it:

```sh
export NPM_AUTH_TOKEN=…        # Gitea package token; never paste into git/chat/logs
```

`.npmrc` (committed) references it via `${NPM_AUTH_TOKEN}` — no secret lives in the file.

## Publish (maintainer)

```sh
git checkout main && git pull --ff-only
make release VERSION=x.y.z      # bumps, cuts CHANGELOG, commits, tags  (§6)
git push --follow-tags origin main
npm publish                     # uses publishConfig.registry + NPM_AUTH_TOKEN
```

`npm publish` is **outward and immutable** — a published version cannot be silently
replaced. Confirm the tag and `npm pack --dry-run` contents first.

## Install (consumer)

Add an `.npmrc` to the consuming repo so the `@whynot` scope resolves to the registry,
then install the package plus the `lit` peer:

```ini
# .npmrc
@whynot:registry=https://gitea.coulomb.social/api/packages/coulomb/npm/
//gitea.coulomb.social/api/packages/coulomb/npm/:_authToken=${NPM_AUTH_TOKEN}
```

```sh
npm i @whynot/design@x.y.z lit
```

The installed package carries the consumer-facing contract under `ir/` (component
contracts, `tokens.json`, exemplars) reachable via the `./ir/*` export — that is what
the `drift` check (WHYNOT-WP-0003 T05) reads to report changes between versions.