---
description: Keep project documentation aligned with the codebase
globs: docs/**/*
alwaysApply: true
---

# Documentation rules

## Single source of truth

| Topic | Canonical doc | Also surfaced in |
|-------|---------------|------------------|
| User-facing features / DSL / UI | `docs/HELP.md` | In-app Help tab (`include_str!` in `src/lib.rs`) |
| System design | `docs/ARCHITECTURE.md` | — |
| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
| Build / packages | `docs/BUILD.md` | `README.md` summary |

## When to update docs

Update documentation **in the same commit** (or immediately before merge) when you change:

- Supported DSL syntax or directives
- UI tabs, toolbar actions, or dialogs
- `.pos` file schema or metadata fields
- Print transport, baud rate, or discovery behaviour
- Dependencies or CI/release artifacts
- Anything described in the in-app Help tab

## Implementation status markers

Design docs written before implementation may describe planned features. When editing:

- Mark **implemented** vs **planned** clearly (as in `PRINTING.md` and `ARCHITECTURE.md`).
- Remove references to rejected choices (e.g. Tauri, `escpos` crate) unless in a historical "considered" section.
- Do not document features that are not in code unless under a "Planned" or "Future" heading.

## HELP.md sync

If you add or change user-visible behaviour:

1. Edit `docs/HELP.md`.
2. Confirm `pub const HELP_MARKDOWN` in `src/lib.rs` still uses `include_str!("../docs/HELP.md")`.
3. No duplicate help text elsewhere.

## README

Keep `README.md` as the entry point: status, build/run, release artifacts, link to `docs/`.
