stnd.buildSTANDARD MANUAL2026-07-15

4.9 README Standards

The standard structure and metadata for README files across the ecosystem.

4.9 README File Standards

All packages (packages/*) and applications (apps/*) in the ecosystem must possess a README.md file conforming to this standard. This ensures the documentation remains readable by humans, navigable by AI agents, and consistently integrable within the Manual on stnd.build.

1. Frontmatter Metadata

Each README.md file must begin with a YAML frontmatter block containing the following keys:

---
title: "@stnd/package-name" # Name of the package or application
status: active               # active | paused | deprecated
maturity: sprout             # seed | sprout | tree
type: package                # package | project | meta | tool
tags:
  - package                  # system tags
  - stnd
---

Maturity Definitions (maturity)

  • seed: Recent, experimental, and highly volatile code. The API is unstable and poorly documented.
  • sprout: Functional code, used in some projects. The API is stable and documented, but test coverage remains minimal.
  • tree: Mature and proven code. The API is frozen, fully documented, with automated test coverage, and serves as a critical dependency in the ecosystem.

2. Standard Structure of a README

The content of the README.md file must respect the following organization:

  1. Main Title (H1): The name of the package or project with a representative emoji if desired.
  2. Hook (Blockquote): A single sentence describing the purpose and philosophy of the brick.
  3. Overview (## Overview): A clear description of the key features provided.
  4. Rules & Architecture (## Rules & Architecture): Description of allowed dependencies, architectural constraints, and key decisions (e.g., “Must not import any other feature module”).
  5. Usage (## Usage / ## API Reference): Minimal and clear code examples, tables of exposed functions or components.
  6. Next Steps (## What's next — open): A task list (- [ ]) listing technical debt, planned refactoring, or missing features.
  7. Links & Standards (## Links & Standards): Relative links pointing to global documents of the repository (e.g., STANDARD.md, root README.md, or other manual sections).

3. Relative Path Rule (AI-Friendly)

Important

Absolute Rule: All links to internal files in the repository must use standard relative paths (e.g., [Code Standards](../2-system/4.2-code-standards.md) or [Styles](../../packages/styles/README.md)).

This rule ensures that:

  1. AI development agents (like Gemini or Claude) can analyze and traverse the repository tree by following links.
  2. Code editors (Zed, VSCode) and Obsidian can resolve and open target files directly locally.
  3. No production absolute links (e.g., https://stnd.build/...) must be used to target repository files within READMEs.