Contributing Documentation

Canonical documentation is authored directly under apps/docs/src/content/docs; generated files under apps/docs/public and build output are not editing surfaces.

Before proposing a change, identify the page’s role, preserve its explicit metadata, and link claims to authoritative runtime or repository evidence. Run the documentation checks and production build defined by the docs application, then review the rendered route and generated public artifacts for unintended exposure or stale navigation.

Start at the documentation home to verify that readers can reach the changed material through a useful entry point.

Keep GUI and terminal guidance usable

Use Choose the GUI or CLI as the interface coverage map. GUI help and Academy own immediate control explanations; docs retain complete terminal workflows, shared artifact/evidence semantics, configuration, recovery, automation, and compatibility boundaries. A feature being visible in the GUI is not a reason to remove its CLI procedure.

Link interface-specific steps to the shared workflow instead of copying an entire lifecycle into every guide. Verify visible labels against the current GUI and command availability against the selected executable. Planned descriptors must not appear as runnable examples. State when evidence belongs to a historical release rather than the current repository build.

Remove obsolete examples and starter content, preserve useful route entry points, and update indexes and generated exports together. The first-project journey is curated public guidance; unlike the exact workflow mirrors, it does not copy the historical installed tutorial body.