# vyre-conform internal documentation
This directory holds development-process and internal-design documents for the `vyre-conform` crate. These documents are not published to docs.rs and not part of the user-facing book (`core/docs/`). They exist for maintainers, contributors doing architectural work, and auditors.
## Contents
| `CI.md` | CI pipeline notes — what each job checks, how to add a new gate. |
| `COMPETITORS.md` | Comparison to other conformance / property-testing frameworks. |
| `INTERNAL_SPEC.md` | Internal design notes not meant for the public spec surface. |
| `LOOM.md` | Loom (concurrency model-checking) usage and limitations. |
| `PLAN.md` | Long-running development plan. Large file; treat as a scratchpad. |
| `REFERENCE_TRUST.md` | Trust model for the reference interpreter — what we do and do not trust. |
| `SPEC.md` | Internal specification notes (not the frozen public spec). |
| `schema.md` | Older schema notes; superseded by `rules/SCHEMA.md` at the workspace root. |
## When to add a new internal doc
- Is it a public API contract? → goes in the user-facing book (`core/docs/`) instead.
- Is it a rule contributors need to follow to submit a PR? → goes in the root `CONTRIBUTING.md`.
- Is it a frozen architectural decision? → update `ARCHITECTURE.md` at the workspace root.
- Is it none of the above but useful to maintainers? → it belongs here.
## Why these files are here and not at the crate root
The `vyre-conform/` crate root is the top of what a user sees when they land on crates.io or GitHub. `README.md`, `CHANGELOG.md`, and license files are enough. Everything else distracts. Internal process docs live one level down.