# Contributing to Atelier

Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.

## What We Accept

- **New domain first-principles** — if a domain is missing (e.g., `domains/ai-ml/`), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in `matrix/principles-matrix.md`.
- **New domain derived docs** — topic docs under an existing domain (e.g., `domains/api/webhooks.md`), deriving from the domain's first-principles.
- **New language application docs** — `languages/<lang>.md` showing how domain principles apply in a specific language.
- **New examples** — `examples/good/*` (with principle citations) or `examples/bad/*` (with violation citations).
- **Corrections** — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
- **Improvements to the matrix** — if a derivation is missing or wrong, propose the fix with the rationale.

## What We Do Not Accept

- **Style rules** — Atelier is principles, not style. Use a linter for style.
- **Tooling** — linters, analyzers, or enforcement code. Atelier is markdown.
- **Unlisted docs** — every document must be in `MANIFEST.md`. An unlisted doc is not part of the framework.
- **Principles without derivation** — a domain principle that does not trace to a core principle is orphaned and will be rejected.

## How to Contribute

### 1. Read the relevant docs first
- `core/first-principles.md` — the eight axioms.
- `core/conflict-resolution.md` — how conflicts are resolved.
- The domain(s) you are contributing to.
- `matrix/principles-matrix.md` — to see existing derivations.

### 2. Follow the document structure
See `domains/documentation/doc-templates.md` for the canonical structure. Every first-principles doc has:
- Manifesto
- The Principles (P1–P10, named, defined, with "what violates it")
- Conflict Resolution
- What Violates These Principles (table)
- Relationship to Core

### 3. Update the matrix
If you add or change a principle, update `matrix/principles-matrix.md` with the derivation. A PR with a new principle but no matrix row is incomplete.

### 4. Update the manifest
If you add a new document, add it to `MANIFEST.md` in the correct section. An unlisted document is not part of the framework.

### 5. Add examples
If you add a principle, add at least one good example and one bad example in `examples/`. Examples are mandatory (Documentation P3).

### 6. Write a clear PR description
- What principle or document you are adding/changing.
- Why (the rationale, not just the what — Documentation P8 Why Over What).
- Which core principle(s) it derives from.
- What conflicts it might introduce (if any).

## Review Criteria

Reviewers will check (see `review/peer-review-checklist.md`):
- Does the new principle trace to a core principle?
- Is the matrix updated?
- Is the manifest updated?
- Are there examples?
- Does the structure follow the template?
- Does it conflict with existing principles? If so, is the conflict resolvable per `core/conflict-resolution.md`?

## Versioning

- A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
- A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
- A change to `core/first-principles.md` (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
- See `CHANGELOG.md` for the version history.

## License

By contributing, you agree that your contributions are licensed under the MIT license (see `LICENSE`).