# docs/README.md (documentation root)

Truth document. Use for: the entry point for all documentation in a repo, created by the `maintenance` agent's baseline.

**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, so the index's history records roster churn instead of what the index said. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. The only files an index may name are the mandated scaffolds and the root instruction files (`SKILL.md` § Indexes and descriptions). Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`). The repo-root `README.md` routes the team and agents in by intent and this file describes the folders of the docs tree; each links the other once and neither restates the other.

**Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.

```
---
type: docs-readme
description: "{at most 300 characters: what the documentation tree holds and how it is organised}"
---

# {Project Name} Documentation

Technical documentation for {project description}. {Two or three sentences: what the product is, its planes or packages, who the docs are for.}

> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.

---

## Architecture

The design layer — [architecture/](architecture/): {what the folder holds — the system overview, steering docs, cross-cutting doctrine, the per-package and per-system documents, and `decisions/` (one Architecture Decision per subject, `AD-NNN-{slug}.md`, status in each file's frontmatter)}.

## Features

[features/](features/) — one living reference per feature (how it works today), flat, named `{feature}.md`; each names the objects it designs in `objects:`, and the source files it speaks for name it in their headers. Find a feature by its name or by the ownership index, never by a row here.

## Tests

[tests/](tests/) — one behavioral checklist per documented surface, `{feature}.md`, `verifies:` naming the document whose promises it proves.

## Operations

[operations/](operations/) — how to set up, run, develop, deploy and recover. Start at [`setup.md`](operations/setup.md) on a new machine; every other procedure is named for its task.

## History

[history/](history/) — the records, and two queues: `plans/` (one dated plan per unit of work, frozen at completion), `changelog/` (one entry per unit of work; [CHANGELOG.md](history/CHANGELOG.md) explains how to read it), `migrations/` (one-shot runbooks), `brainstorms/`, `research/`, [backlog.md](history/backlog.md) (open work; a finished item is deleted) and `journal.md` (mid-execution facts awaiting their owning doc).

## Research and memory

[research/](research/) — in-progress brainstorm sessions and standing research. [memory/](memory/) — project memory, one file per agent.

## Notes for this repository

{The one place project-specific placement facts live, because `structure.md` is the harness's and is overwritten on every refresh: legacy folders kept as frozen provenance, a retired genre whose residue is still on disk, a local exception to a folder rule. One bullet each; delete the section when there are none.}

---

## Contributing

See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
```