Repository structure

Use the selected repository profile as the structural contract. A repository can add product-owned folders when the architecture requires them.

Required root files

README.md
AGENTS.md
CLAUDE.md
MAINTAINING.md
CONTRIBUTING.md
SECURITY.md
LICENSE
CHANGELOG.md
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
.github/
docs/

A deployed app can omit CHANGELOG.md when it does not make versioned releases. A library must include it.

File ownership

• README.md serves package users and repository visitors.
• AGENTS.md records architecture, invariants, verification, and prohibited actions.
• MAINTAINING.md records quick fixes, large changes, dependency updates, documentation changes, releases, rollbacks, and incidents.
• CONTRIBUTING.md defines contributor scope and pull request requirements.
• SECURITY.md gives the private vulnerability-reporting path.
• CLAUDE.md points to AGENTS.md. It does not copy policy.
• docs/WRITING.md defines the repository's public writing terms.

Library layout

A single-package library keeps its package at the root. A package monorepo keeps published packages in packages/. Both keep the deployable documentation app in docs/.

Do not put the documentation app in apps/docs in one repository and docs in another. The Vercel Root Directory is always docs/ for the standard profiles.

Local independence

The handbook is the fleet-wide source of truth. A repository still includes the exact commands and constraints needed to operate it. A maintainer must not need this site to identify the package list or run the release checks.