# Package Documentation (docs/architecture/packages/{package}.md)

Truth document. Use for: **one workspace package — what it is and how it behaves**. One file per package, named for the package's folder (`packages/cli/` → `docs/architecture/packages/cli.md`). It states the package's own machinery: its manifest and published identity, its build and entry point, its source layout, and every behavior of its tree that no system or feature document claims.

**A package document is the residual owner of its own tree.** Its `owns:` is the whole package glob — `["packages/{name}/**"]` — and that glob is the *broadest* claim anything makes on those paths, so it loses to every narrower one. A system document naming `packages/{name}/src/server/runs/**` wins those files by specificity; a feature document naming `packages/{name}/src/surfaces/apps/**` wins those. What is left after every narrower claim is what this document describes, and it describes that exhaustively. **The residual claim is a promise of completeness, not of scope**: a package document with nothing left after the systems and features have claimed their subtrees is still owed — the manifest, the build, the entry, the layout, the test wiring and the deploy shape are always residual.

**Two rules bind the glob.** Neither genre may claim a path another document claims at **equal specificity** — equal-specificity overlap is an ownership conflict to resolve before either document ships, not a duplication to live with. And every glob **matches at least one file on disk** at `status: active`; a projected glob is permitted only at `draft`, and is confirmed when the document flips.

**How this differs from its neighbours.** A **feature** document covers one capability or one page a person names, and owns that surface's globs. A **system** document covers one machine that spans packages, and owns the subtrees that machine is made of. A **package** document covers one unit of distribution — a manifest, a build, a binary or a bundle — and owns what is left of it. The unit is the package boundary, so if the subject you are writing about does not stop at a `package.json`, it is not this genre. Route it: one screen → feature; one machine crossing two packages → [system](system.md).

**Required vs optional.** Required in every package document: the **frontmatter**, the **opening** (title, identity line, what the package is), the **ownership boundary** (what this document does not describe and which document does), at least one **behavior section**, **Files**, and **Related**. Everything else is optional — include a section only when the package has something real to put in it. A package with no test wiring of its own gets no verification section; a package that nothing else in the repo consumes says so in one line rather than growing a Consumers section. A short accurate document beats a full skeleton with empty headings.

Package documents run long because they are exhaustive over their residue — roughly 150 to 600 lines is the working range, and the top of that range is a package holding an application, not a document that has lost discipline.

```yaml
---
owns: ["packages/{name}/**"]                      # required — the whole package tree, one glob; the residual claim
keywords: [package-name, binary, build, entry]    # required — discovery terms: the npm name, the binary, the surfaces
status: active                                    # required — active | draft | deprecated
applies: [docs/architecture/common/api.md]         # optional — cross-cutting doctrine this package is BOUND by (obligation, not a bibliography); omit when none
type: package                                     # required tooling key — genre stamp; preserve on edits, never narrate
---
```

> A package document carries no `module:` — a package is already a bounded unit, and a second label
> for the same boundary is a thing to keep in sync for nothing. `last-reviewed:` is optional and,
> like `type:`, is tooling metadata: preserve it, never narrate it.

```
# {package-path} — {the one-line role}

**Package:** `@scope/name` · **Ships as:** {a public npm package with one binary `x` / a private
source-first workspace package / a Worker on {domain}} · **Source:** `packages/{name}`

{One paragraph: what this package is and the job it does in the product. Name what it holds that
nothing else does, and what it deliberately does not hold. Written for someone who has not opened
the folder.}

{One paragraph: the ownership boundary. This document is the residual owner of `packages/{name}/**`;
these subtrees are claimed at higher specificity by these documents and are pointed at, not
restated. Where the routing is more than a sentence, make it the table below instead.}

{Optional, and worth its line whenever the body names paths: "Paths below are relative to
`packages/{name}/` unless they name another package."}

## What is built and what is not

{Optional — required in substance whenever some of the tree does not run. State plainly which
halves exist and which do not, with the source evidence for each claim, and say what a reader who
runs the unbuilt half will actually observe. A package whose subject as a whole does not run is
`status: draft` and says so here; a scoped gap in a working package stays `active` and takes an
UNBUILT marker at the section that describes the gap.}

## Ownership — packages/{name}

{Optional — use the table form when more than two documents claim subtrees of this package.}

**The package glob is the residual claim.** A system or feature document's `owns:` is more specific
and wins by specificity, so this document describes only what none of them claims, and points to
each for the rest.

| Path | What it is |
| --- | --- |
| `src/index.ts` | {the residue: the entry, the dispatch, the layout} |

| Subtree | Stated and owned by |
| --- | --- |
| `src/{machine}/**` | [{system}](../systems/{system}.md) |
| `src/surfaces/{x}/**` | [{feature}](../../features/{feature}.md) |

## {Behavior sections — named for this package's own machinery}

{The body. There is no fixed section list, and inventing one would be a lie: what a CLI owes
(commands, the store, the on-ramp) and what a UI package owes (the host port, the frame, the route
zones, the component pool) share no headings. Name each section for the thing it describes and
order them the way a reader meets them — identity and build first, then the surface, then what it
writes, then how it is verified. Prefer a table wherever the content is a roster (commands, routes,
exports, bindings, environment variables); prefer prose wherever the content is a rule and its
reason. State mechanisms and contracts, never pasted implementations.}

## Tests

{Optional. What proves this package, and what each suite pins — a `Suite | Pins` table, or the
commands a reader runs. A package whose verification is a build check names the check instead
(`## Checks`, `## Build and test`); a package with no suite of its own says so in one line in the
build section and carries no heading here.}

## Files

| Path | Role |
| --- | --- |
| `packages/{name}/package.json` | {the manifest: the bin, the exports, the scripts} |
| `packages/{name}/src/index.ts` | {the entry} |

{One row or bullet per file this document owns, with what it holds — the roster a reader uses to go
from the document to the code. Close with the inverse where it helps: "Read here, owned elsewhere:"
naming the paths the body describes but another document claims.}

## Related

- [`{system}.md`](../systems/{system}.md) — {why a reader of this document would open that one}
- [`{other-package}.md`]({other-package}.md) — {the seam between the two}
- [`{doctrine}.md`](../common/{doctrine}.md) — {the cross-cutting contract this package answers to}
```

### The identity line

The bolded `·`-separated run under the title is what a reader checks first, and it answers three
questions no body section should have to: **what is this called** on the registry or in the
workspace, **how does it ship** (a public tarball, a private source-first package, a deployed
Worker, a signed installer), and **where is its source**. A package that ships two artifacts names
both. Add a `**Crate:**` or `**Deploys as:**` term where the package has one; drop any term that
would restate the title.

### Marking what is decided and unbuilt

Where the package holds code for a design that is decided and not built — or a surface whose other
half does not exist — wrap the prose in a marker so the gap is machine-findable and its evidence
travels with it:

```
<!-- UNBUILT:START — {what is decided, where it is decided (an AD or an owner ruling), and the
source evidence that it is not built: the file that does not exist, the route that is not mounted,
the binding that is not declared} -->
{the prose describing the unbuilt half}
<!-- UNBUILT:END -->
```

**A design that was decided *against* carries no marker.** A marker means the work is owed and
absent; using one for a rejected design turns the register of debt into a register of opinions.
Say in prose that it is not built and not owed, and name the decision that settled it.