yoi/work-items/open/20260601-110026-crate-readme-boundaries/item.md

id	slug	title	status	kind	priority	labels	created_at	updated_at	assignee	legacy_ticket
20260601-110026-crate-readme-boundaries	crate-readme-boundaries	Standardize crate README responsibility boundaries	open	task	P2	docs	2026-06-01T11:00:26Z	2026-06-01T11:09:35Z	null	null

Background

The crate README files are uneven and several important crates have no README at all. They should be standardized as thin responsibility-boundary documents rather than API references.

This work item follows docs-information-architecture and should link crate README files to the maintained design/development docs where appropriate.

Requirements

• Each crate README should explain the crate's role, boundaries, key entry points, and relevant design docs.
• README files should avoid public type inventories, method lists, and implementation details that are likely to drift.
• Important crates without README files should get concise responsibility-boundary README files.
• Existing stale names or stale architectural claims should be removed.

Acceptance criteria

• Existing crate README files follow a consistent role/boundary-oriented shape.
• Important crates without README files have a short README.
• Crate README files link to docs/design/ or docs/development/ instead of duplicating long design content.
• Validation includes ./tickets.sh doctor and git diff --check.