Documentation Source Of Truth

apps/docs/docs/** is the canonical Markdown source for public MacTain documentation.

Public docs authority

The standalone VitePress app in apps/docs owns the public documentation IA, navigation order, page content, validation, and preview/build path. Public docs changes should be reviewed through normal pull requests in this repository.

Product evidence

Current native implementation, tests, generated CLI help, release notes, and approved product screenshots can provide evidence for a public docs update. They are not a second documentation source and are never copied or synchronized into this repository. All public prose is authored and reviewed directly under apps/docs/docs/**.

Source captures under docs/source-captures/** are evidence snapshots. They record what was reviewed for a public docs update, but they are not the public documentation users read. Update the public Markdown in apps/docs/docs/** when a source capture proves that a user-facing docs claim should change.

Required docs updates

A native MacTain CLI, GUI, Engine, installer, release, or workflow change that affects user-visible behavior must include a corresponding public docs Markdown update before release readiness.

The update can ship in a coordinated release sequence or linked website docs pull request. The release is not docs-ready until the public docs update is merged, accepted, or explicitly deferred by an approved launch decision.

For CLI changes, review both the generated help output and the implementation or test coverage for the command. Public docs should only describe commands, flags, defaults, examples, and troubleshooting guidance that match current source-backed behavior. If a CLI change intentionally ships before public docs are updated, the release decision must record the docs deferral and the target follow-up issue.

For GUI changes, review the native Swift view, view model, fixture, and UI test coverage for the changed surface. Public docs should only describe navigation labels, buttons, menu items, panels, screenshots, and default behavior that match the current app. If a GUI surface changes visually or changes user-facing workflow behavior, capture or approve a fresh screenshot and update the corresponding public Markdown before release readiness.

Repeatable update contract

Every user-facing MacTain CLI or GUI change should follow the same docs update contract:

1. Capture the source evidence under docs/source-captures/<issue>/. CLI changes should include current generated help or docs output. GUI changes should include native source/test references and current screenshots when the surface is visual.
2. Update the public Markdown under apps/docs/docs/** in the same release sequence or in a linked website docs pull request.
3. Update docs validation when the change creates a new durable public contract: required screenshots, required command examples, required defaults, required source-backed warnings, or required maintainer policy text.
4. Run the docs validation command from the docs app before calling the release docs-ready.
5. If the docs update is intentionally deferred, record the approved deferral, target issue, and release risk. A release is not docs-ready just because the source capture exists.

Use this contract for small changes too. A renamed button, new CLI flag, changed default, removed setting, new screenshot-relevant panel, or new troubleshooting path can make existing public docs wrong even when the feature implementation is otherwise correct.