> ## Documentation Index
> Fetch the complete documentation index at: https://invariant-cad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Set up the repository, choose a change boundary, test it, and contribute safely.

InvariantCAD welcomes focused issues, documentation improvements, tests,
protocol reviews, and implementation changes. Read the canonical
[`CONTRIBUTING.md`](https://github.com/shlokjain42/invariantCAD/blob/main/CONTRIBUTING.md)
before opening a pull request.

## Local setup

```bash theme={"system"}
git clone https://github.com/shlokjain42/invariantCAD.git
cd invariantCAD
corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm lint
pnpm test
```

Node.js 22.13 or newer is required. The lockfile records the tested toolchain.

## Validation levels

```bash theme={"system"}
pnpm check          # build + TypeScript
pnpm lint           # source correctness + format hygiene
pnpm test           # unit/integration suite
pnpm test:browser   # production Vite bundle in Chromium
pnpm lint:package   # package export/type lint
pnpm test:package   # packed clean-consumer smoke
pnpm api:entrypoints:check # export/source/report/target manifest
pnpm release:check  # full gate, including coverage + six benchmarks
```

Run the smallest relevant loop while developing, then the proportional full
gate before handing off a change. `release:check` is the canonical release
acceptance command; coverage and the complete reference benchmark corpus are
part of it rather than optional follow-up steps.

The canonical [support policy](https://github.com/shlokjain42/invariantCAD/blob/main/SUPPORT.md),
[governance model](https://github.com/shlokjain42/invariantCAD/blob/main/GOVERNANCE.md),
and [Code of Conduct](https://github.com/shlokjain42/invariantCAD/blob/main/CODE_OF_CONDUCT.md)
describe the project's current single-maintainer boundaries and community
process.

## Protocol changes

Document, topology, kernel, cache, artifact, and native-facade protocols are
versioned separately. A protocol change should include a precise invariant and
failure semantics, hostile-input bounds, frozen compatibility tests,
cancellation and cleanup tests, serialization impact, documentation, and a
migration decision. Never silently widen a frozen document version.

## Backend changes

Construction tests are not enough for topology-aware features. Add tests for
capability metadata, geometry, topology roles/source, complete versus partial
history, failure rollback, resource ceilings, and disposal.

## Documentation changes

The Mintlify source lives in `/docs`. Every navigated page needs `title` and
`description` frontmatter. Keep examples compilable, distinguish tested from
planned behavior, and link to one canonical support matrix.

Selected complete fences are synchronized from strict TypeScript regions under
`examples/docs/`. The
[`manifest.json`](https://github.com/shlokjain42/invariantCAD/blob/main/examples/docs/manifest.json)
lists every canonical TypeScript module, the public workflows it covers, and
each synchronized placement. Edit the canonical source rather than content
between `docs-example` markers, then run `pnpm docs:generate`.

`pnpm docs:check` verifies exact synchronization, manifest-complete TypeScript
coverage, and source-mapped public imports without starting native runtimes.
`pnpm test:docs-examples` independently checks that no canonical module is
missing from the manifest, imports every listed module, runs its Manifold or
OCCT workflow, and requires all named behavioral checks to pass.

The current executable matrix covers portable parametric modeling and STL,
sketch/extrude plus exact STEP, fixed assemblies with configurations and BOMs,
canonical document migration and hashing, persistent topology
capture/resolution/explanation, and bounded parsing with structured
diagnostics. Unmarked fences are intentionally illustrative fragments: keep
them accurate and type-aligned, but do not imply that they are independently
compiled or executed.

## Security reports

Do not open a normal issue for a vulnerability. Follow the
[security policy](/project/security).