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

Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.

**A document is read by people, and its footer is for the agent** (`references/style-guide.md` § Owning documents — the body and the footer). A package document tells a person what the package is for, why it is its own unit, how it ships and to whom, how it is meant to be used, and what its consumers can rely on. Its manifest, build, entry, internal layout and test wiring are the code graph's (`docs/architecture/systems/knowledge-layer.md`), not a roster here.

**A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.

**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. Which subtrees narrower documents speak for is computed from their headers, never tabled here.

**Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.

**Sections:** the frontmatter, the identity line and the goal line are required. Then:

| Section | When |
| --- | --- |
| `Scope` | required. Why the package is its own unit, who consumes it, and what it deliberately does not hold |
| `Ownership` | required, as one line |
| `Usage` | required |
| `Decisions` | once any choice was made that the code cannot explain |
| `Promises` | required |
| `Gaps` | only when there is one |
| `For the agent` | required |

Nothing else. The feature template's lint rules apply. Forty to a hundred and twenty lines.

```yaml
---
type: package
description: "{at most 300 characters: what this document settles and where its boundary sits}"
status: active
objects: [nustack cli, device credential]        # required — the objects this package designs or ships
owns: ["packages/{name}/**"]                     # transitional — the residual region glob, read only by the ownership scan until it switches to header pointers
---
```

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

**Package:** `@scope/name` · **Ships as:** {…} · **Source:** `packages/{name}`

{One sentence: the job this package does in the product, for whom.}

## Scope

- **Role:** {what it holds that nothing else does}
- **Consumers:** {who consumes it, and how and when it ships}
- **Out of scope:** {what it deliberately does not hold, and where that lives}

## Ownership

This document is the residual owner of `packages/{name}/**`; a subtree whose files' headers name a system or feature document is that document's.

## Usage

- **{Noun-phrase label — e.g. "Install", "`nustack login`", "Import"}:** {what a person or another package does with it, and what they see. The public contract (commands, flags, exports) belongs here.}

## Decisions

- **{The decision as a noun phrase}:** {why.}

## Promises

- **{Noun-phrase label}:** {what a consumer can rely on, or what the package refuses; checkable.}

## Gaps

- **{Noun-phrase label}:** {what is missing and what it would take.}

## For the agent

- **Objects:** {…}
- **Commands and exports:** {…} — the public contract
- **Code root:** `packages/{name}/`
- **Seams:** {…} by name
- **Checklist:** `docs/tests/{package}.md`
- **See also:** {neighbour}: {why}

No file lists or symbol rosters — those are the graph's.
```

### Marking what is decided and unbuilt

`<!-- UNBUILT:START — {…} -->` … `<!-- UNBUILT:END -->` around the bullets for a decided, unbuilt half; a design decided *against* carries no marker.