> ## Documentation Index
> Fetch the complete documentation index at: https://86d.store/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Setup, the six health gates, what a good pull request looks like, and how to publish a Module of your own.

<Warning>
  **In development.** 86d is being built in the open. Every capability is Experimental until it earns evidence, so check [maturity levels](/docs/resources/versioning) before you rely on anything here.
</Warning>

The codebase is built for small focused changes, and those get reviewed first. A pull request that does one thing well will move faster than one that does four things adequately.

Two repositories take contributions: [86d-store/86d](https://github.com/86d-store/86d) holds the framework, meaning the Store app, all 101 [Modules](/docs/concepts/modules), the CLI, and the shared packages. [86d-store/docs](https://github.com/86d-store/docs) holds this site.

## Setting up the framework

```bash theme={null}
git clone https://github.com/86d-store/86d
cd 86d
bun install
86d init
```

Run `86d doctor` and clear anything it flags before you start changing things. Debugging your change and your setup at the same time is miserable.

## The six health gates

All six pass before a pull request merges:

```bash theme={null}
bun run generate:modules -- --frozen  # Generated Module registry
bun run typecheck                     # TypeScript
bun run check                         # Biome lint + format
bun run test                          # Unit and integration tests
bun run docker:build                  # Production Store Runtime image
bun run docker:verify                 # Container boot and health smoke
```

Run them locally first and in that order. CI runs the same six, and finding out from CI is slower for everyone. The focused Playwright browser smoke is a separate path-filtered workflow.

## Commit messages

Every repository in the 86d project uses [Conventional Commits](https://www.conventionalcommits.org/) with a **required scope**. Git hooks enforce the format locally; CI enforces it on pull requests.

```
type(scope): subject
```

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`

**Framework scopes:** `store`, `cli`, `core`, `runtime`, `sdk`, `registry`, `db`, `emails`, `env`, `lib`, `storage`, `utils`, `modules`, `ci`, `deps`, `config`, `docs`, `repo`

**Docs scopes:** `site`, `concepts`, `guides`, `cli`, `modules`, `resources`, `config`, `repo`

**Examples:**

```
feat(store): add checkout finalization step
fix(modules): handle empty cart in stripe webhook
docs(guides): add module installation steps
chore(deps): bump turbo to 2.10.9
```

Use imperative, lowercase subject with no trailing period. Keep it under 72 characters when possible. See `CONTRIBUTING.md` in each repository for the full scope list.

## What a good pull request looks like

* **One change.** A bug fix, or an endpoint, or a Module, or a docs improvement. Not all four.
* **Tests that match the change.** New endpoint means Vitest tests. UI changes need rendered-state coverage and direct Chrome review. Add Playwright only for a real-browser seam. Bug fixes need a regression test that fails without the fix.
* **A description worth reading.** What problem this solves, why this approach, what you considered instead, and what it does not cover.
* **A Changesets entry** for anything affecting a published package. Run `bunx changeset` and commit the file. CI rejects the pull request without one when one is needed.

## Coding standards

* **No `any`, `@ts-expect-error`, `@ts-ignore`, or `biome-ignore`.** Fix the type or the code underneath.
* **No config edits to silence an error.** If a rule genuinely does not fit, raise it. Do not route around it in `tsconfig.json` or `biome.json`.
* **Do not edit UI primitives.** Wrap or compose shadcn/ui, Base UI, Radix UI, and React Aria rather than changing their internals.
* **Never weaken or delete a passing test** to get a change through.
* **Biome does the formatting.** `bun biome check --write src/`.

## Writing a Module

```bash theme={null}
86d module create my-feature
86d module enable my-feature
86d generate
bun test --filter @86d-store/my-feature
```

Before you ask for review:

* a real schema, with types and relations that mean something
* [Storefront](/docs/concepts/storefront) and admin endpoints actually implemented, with no `TODO` bodies
* loading, error, and empty states in every UI component
* Vitest tests on the paths that matter, with fixtures shaped like the real provider response
* for anything talking to an outside API: real HTTP, retries, error mapping, and webhook signature verification
* rendered-state tests for every new screen state
* direct Chrome review at 1280 x 720 and 375 x 667, in light and dark, including focus, overflow, errors, and recovery
* focused Playwright coverage only when the behavior depends on navigation, storage, focus, responsive layout, browser request construction, or another browser boundary

See [Build a custom Module](/docs/guides/building-a-module).

Clearing this list is not the same as earning Stable. See [Versioning and maturity](/docs/resources/versioning).

## Publishing your own Module

You do not have to upstream anything to publish it:

1. Build with `bun run build` so `dist/` contains JavaScript and `.d.ts` (plus copied `.mdx` assets when needed).
2. Set `"private": false` and a release version in `package.json`.
3. Restrict `"files"` to `dist` (+ README); map `publishConfig.exports` to `./dist`. Do not publish `src` or test/tooling files.
4. Replace `workspace:*` / `catalog:` with real semver versions.
5. Add accurate package metadata and provenance.
6. Publish: `npm publish --access public`.

Then anyone installs it:

```bash theme={null}
86d module add npm:@your-scope/your-module
```

The registry is first-party only. Publishing to npm does not add you to it, and it establishes nothing about compatibility.

## Documentation

Docs live at [`86d-store/docs`](https://github.com/86d-store/docs). Every page is `.mdx` with YAML frontmatter. Clone it and preview locally:

```bash theme={null}
git clone https://github.com/86d-store/docs
cd docs
npm i -g mint
mint dev
```

The bar for a docs change:

* **Active voice.** "Run the command", not "the command should be run".
* **Sentence case headings.** Defined terms keep their capitals inside one.
* **No em dashes.** Comma, colon, semicolon, parentheses, or a new sentence.
* **Working examples.** If you cite a command or an endpoint, paste the exact form and run it first.

The full style contract, including which nouns are capitalized and how maturity is stated, is in `AGENTS.md` in that repository.

## Releases

Maintainers cut a release by merging the aggregated Changesets pull request CI generates. See `release` in `package.json`. Module publishes use `--provenance`, so anyone installing can verify what they got.

## License

86d.store is licensed under the [MIT License](https://github.com/86d-store/86d/blob/main/LICENSE). By contributing, you agree that your contributions are licensed under the same terms. 86d.app remains proprietary.

## Code of conduct

Be kind, assume good faith, and disagree about ideas rather than people. 86d follows the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

## Security issues

[GitHub Security Advisories](https://github.com/86d-store/86d/security/advisories), privately, not a public issue.

## Getting help

* [Discussions](https://github.com/86d-store/86d/discussions) for design proposals and open questions.
* [Issues](https://github.com/86d-store/86d/issues) for bugs and feature requests.

Both get triaged as they arrive. If something is urgent, say so in the first sentence rather than the fourth paragraph.

## Related pages

* [Build a custom Module](/docs/guides/building-a-module)
* [Test the Store Runtime](/docs/operations/testing)
* [Versioning and maturity](/docs/resources/versioning)
* [Changelog](/docs/resources/changelog)