# Adding a package

Use this checklist when introducing a new shared package to the monorepo.

## Minimum checklist

- create the package under `packages/`
- add a `package.json` with a stable package name
- declare internal workspace dependencies explicitly
- export only the intended public API surface
- add build scripts if the package produces output
- update consumers to depend on the new package rather than deep-importing implementation details

## How the docs generators detect it

The dependency graph is generated from workspace manifests, so the most important thing is to keep `package.json` accurate.

The generator uses:

- the package name
- the package folder name
- internal workspace dependencies
- basic workspace role classification

## After adding the package

Run:

- from `apps/docs-site/`, run `bun run generate`

Then confirm:

- the package shows up in the dependency graph
- downstream apps/packages point to it correctly
- the build-order diagram places it before its consumers

## Conventions worth keeping

- keep package names aligned with folder purpose
- prefer explicit exports over accidental deep import surfaces
- keep internal dependency lists honest — future-you, CI, and the graph generator will all be happier