Organize repository documentation

Repository documentation helps the next person—or agent—understand what you are building and why. Megamono gives these documents consistent locations, links, and lifecycle tools.

Choose the right document

#

• Specification: describe intended behavior and acceptance criteria.
• Plan: break work into steps and track progress.
• Decision: explain a choice and its tradeoffs.
• Research: record what you investigated and learned.
• Audit: assess an implementation against a specification.

For a folder-by-folder explanation, see the docs directory.

Set up and create documents

#

Choose the documentation module when initializing your workspace, or use docs-init to add it later. If you already have documentation, review its locations and links before applying changes; you do not need a second copy.

Find your project's Nx name, then preview a specification or plan:

npm exec -- nx show projects
megamono generate docs-spec --project=api --title="Search API" --dry-run
megamono generate docs-plan --project=api --title="Implement search" --dry-run

Replace api with your project's name. Review the proposed files, repeat without --dry-run, and fill in the generated sections.

Keep a visual handoff

#

The docs scaffold includes docs/design/README.md, manifest.md, boards/, and screenshots/. Use these for visual references and their links to accepted specs and acceptance tests; retain docs/DESIGN.md as the concise design brief.

An optional tokens.json can hold design values. Declare whether it is authoritative or generated from an existing theme, and avoid maintaining both independently. Existing handoff files are preserved when you rerun initialization. These assets do not require lifecycle frontmatter and are not automatically published or pruned. See visual design handoffs for the layout and source-of-truth conventions.

Keep documents useful

#

Use validation to check metadata and links, and indexing to keep the document list up to date. Inspect the documentation project's targets with npm exec -- nx show project <project> before running them.

When work is finished, archive eligible documents with a reason and any replacement links. Prune expired reports only after reviewing the deletion preview. Specifications, decisions, and transient reports serve different purposes; keep their history understandable.

Keep public product docs separate

#

Your team's plans and decisions are not automatically public website content. Keep customer-facing guides in the site or a dedicated content library. Content libraries and content types help organize that content independently.