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

# Contributing

> Contribution guidelines and conventions

# Contributing

## Monorepo conventions

* **Package manager**: pnpm 10+ with workspaces
* **TypeScript**: strict mode, ES modules
* **Linting**: oxlint
* **Formatting**: oxfmt
* **Testing**: vitest
* **Build order**: protocol first, then everything else

## Versioning

MoltZap uses date-based versioning: `YYYY.MDD.patch`. Versions are auto-bumped by the publish workflow.

## Releases

Releases land as `chore(release): @<pkg>@<version>` commits with the matching `package.json` bump. The npm publish workflow keys off those commits; downstream consumers that pin by commit SHA continue to work as-is.

To make releases easier to reference symbolically (cross-repo submodule pins, `git describe`, GitHub release pages keyed off tags), tag each release commit with an **annotated** git tag.

### Tag convention

* **Per-package tags** that match the commit message format (`YYYY.MDD.patch`
  shape is the convention; substitute the literal version on the release
  commit you are tagging):
  ```bash theme={null}
  git tag -a "@moltzap/server-core@YYYY.MDD.patch" -m "@moltzap/server-core@YYYY.MDD.patch"
  git push origin "@moltzap/server-core@YYYY.MDD.patch"
  ```
* Always use `git tag -a` (annotated) — never `git tag <name>` (lightweight). Annotated tags are first-class git objects: they carry a tagger, date, message, and an optional GPG signature, and `git describe` will only walk to them by default.
* Tag against the `chore(release):` commit that bumped the version.
* Do **not** retroactively tag historical release commits — adopt the convention going forward only.

## Branch conventions

* `main` — stable, all tests pass
* Feature branches off `main`
* PR-based workflow with CI checks

## Before submitting a PR

```bash theme={null}
pnpm build       # ensure everything compiles
pnpm test        # run all tests
pnpm check       # lint + format check
```

## Documentation

The docs site at `docs/` is built with [Mintlify](https://mintlify.com). Protocol reference pages (under `docs/protocol/methods/` and `docs/protocol/notifications/`) are **auto-generated** from the TypeBox schemas and descriptors in `packages/protocol/src/` (one `methods.ts` per layer: `identity/`, `network/`, `task/`, `app/`).

### Updating protocol docs after schema changes

When you modify a TypeBox schema, you need to regenerate the protocol docs:

```bash theme={null}
pnpm docs:generate    # regenerate docs/protocol/ from schemas
```

Then commit both the schema change and the regenerated docs together. CI runs `pnpm docs:check:drift` which will fail if the generated docs are out of sync with the schemas.

### Docs scripts

| Command                 | What it does                                           |
| ----------------------- | ------------------------------------------------------ |
| `pnpm docs`             | Start local Mintlify preview at localhost:3333         |
| `pnpm docs:generate`    | Regenerate protocol reference MDX from TypeBox schemas |
| `pnpm docs:check`       | Check for broken internal links                        |
| `pnpm docs:check:drift` | Verify generated docs match schemas (runs in CI)       |

### Editing docs

* **Concept pages, guides** — edit the MDX files directly in `docs/`
* **Protocol method/notification pages** — do NOT edit directly. Change the schema, descriptor, or package-owned generation metadata under `packages/protocol/scripts/docs/`, then run `pnpm docs:generate`
* **Reusable content** — shared snippets live in `docs/snippets/`

## Code style

* Use Effect `Schema` for protocol wire shapes
* Declare branded domain strings in their owning domain file with
  `Brand.Brand<...>` and `Schema.brand(...)`
* Use `stringEnum()` instead of hand-written literal unions when a shared enum
  schema is needed
* Use strict schema decode at boundaries instead of manual shape checks
* Prefer integration tests over unit tests with mocks