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

# Contributing

> Adapted from CONTRIBUTING.md at the monorepo root

Parmana is an Execution Trust Infrastructure platform. The project prioritizes correctness, determinism, immutability, and verifiable execution over implementation convenience.

## Architecture first

Every significant architectural change should begin with documentation. Use this decision process:

1. **Is this a bug fix?** Implement the fix with tests.
2. **Is this a new feature?** Create an RFC describing the proposal.
3. **Does the feature change architectural behavior?** Create or update an Architecture Decision Record (ADR).
4. **Does the change modify a normative platform contract?** Update the relevant specification in `docs/`.

## Core principles

<CardGroup cols={2}>
  <Card title="Deterministic execution">Identical inputs must always produce identical decisions.</Card>
  <Card title="Immutable domain model">No trust-chain artifact supports an update operation.</Card>
  <Card title="Independent verification">Verifying a record shouldn't require trusting the runtime that produced it.</Card>
  <Card title="Append-only evidence">Corrections are new artifacts, never edits to history.</Card>
  <Card title="Cryptographic agility">Algorithms are swappable implementation details, not fixed domain concepts.</Card>
  <Card title="Separation of concerns">Each package under `packages/` has one responsibility.</Card>
</CardGroup>

Changes that violate these principles require an approved ADR.

<Note>
  This documentation surfaces several places where the current implementation doesn't yet fully live up to these principles — see [REST API → Authentication](/docs/api/authentication), [REST API → Error Model](/docs/api/error-model), [Packages → replay](/docs/packages/replay), and [Packages → verification](/docs/packages/verification) for concrete examples. Contributions that close those gaps are exactly the kind this project wants; contributions that quietly paper over them without an ADR are not.
</Note>

## Testing requirements

All changes should include appropriate automated tests:

* Unit tests for new domain behavior.
* Regression tests for bug fixes.
* Conformance tests when platform contracts are affected.

The build should pass:

```bash theme={null}
npm run build
npm run typecheck
npm test
```

## Coding standards

* Use TypeScript strict mode.
* Prefer immutable objects.
* Avoid hidden side effects.
* Keep classes focused on a single responsibility.
* Document public APIs.

## Pull requests

Pull requests should include:

* A clear description.
* A linked issue or RFC, if applicable.
* Updated documentation when required.
* Passing build and test results.

## Where documentation lives

| Content                  | Location       |
| ------------------------ | -------------- |
| Normative specifications | `docs/`        |
| Architecture decisions   | `docs/adr/`    |
| Future proposals         | `docs/rfcs/`   |
| Implementation guides    | `docs/guides/` |

## Philosophy

Parmana is designed to establish trust between authority and execution. Every contribution should strengthen that goal.

## Related

<CardGroup cols={2}>
  <Card title="Architecture Overview" href="/docs/architecture/overview">The principles above, in context.</Card>
  <Card title="Security Model" href="/docs/architecture/security-model">The guarantees these principles support.</Card>
</CardGroup>