# Engineering design documents

This directory holds **engineering design documents**: proposals, architecture
decisions, and interface sketches that are argued and agreed *before* code is
written.

It is not the user-facing documentation site. That lives in `sites/docs`
(Astro Starlight, published). Nothing here is built, deployed, compiled, or
type-checked.

## Layout

| Path | Contents |
|---|---|
| `docs/design/NNNN-<slug>.md` | One design document per proposal, numbered in the order they were opened. |
| `docs/design/sketches/` | Non-compiling interface sketches referenced by a design document. |

## Sketch files

Files under `docs/design/sketches/` carry a trailing `.sketch` extension
(`foo.rs.sketch`, `foo.ts.sketch`, `foo.proto.sketch`) so that no build tool
picks them up:

* there is no root `Cargo.toml` workspace, and no crate's `src/` includes this
  path, so `.rs.sketch` is invisible to cargo;
* `pnpm-workspace.yaml` globs only `server/`, `libraries/base/`, `sites/*` and
  `desktop/`, so `.ts.sketch` is invisible to pnpm, nuxt and tsc;
* `torrential/build.rs` compiles only `torrential/proto/*.proto`, so
  `.proto.sketch` is invisible to protoc.

Sketches are illustrative. They name the types, traits and field layouts a
design implies. They are deliberately incomplete and will not compile.

## Status values

Each design document declares a status in its frontmatter:

* **Draft**: written, not yet reviewed.
* **Accepted**: agreed. Implementation may begin.
* **Implemented**: shipped. The document is now history; the code is the truth.
* **Superseded by NNNN**: replaced.

A document at `Draft` or `Accepted` describes something that **does not exist
yet**. Do not read it as a description of current behaviour.

## Index

| # | Title | Status |
|---|---|---|
| [0001](design/0001-import-time-chunk-compression.md) | Import-time chunk compression for game delivery | Draft |