| 1 | ---
|
| 2 | description: Keep project documentation aligned with the codebase
|
| 3 | globs: docs/**/*
|
| 4 | alwaysApply: true
|
| 5 | ---
|
| 6 |
|
| 7 | # Documentation rules
|
| 8 |
|
| 9 | ## Single source of truth
|
| 10 |
|
| 11 | | Topic | Canonical doc | Also surfaced in |
|
| 12 | |-------|---------------|------------------|
|
| 13 | | User-facing features / DSL / UI | `docs/HELP.md` | In-app Help tab (`include_str!` in `src/lib.rs`) |
|
| 14 | | System design | `docs/ARCHITECTURE.md` | — |
|
| 15 | | DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
|
| 16 | | `.pos` file schema | `docs/FILE-FORMAT.md` | — |
|
| 17 | | Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
|
| 18 | | Build / packages | `docs/BUILD.md` | `README.md` summary |
|
| 19 |
|
| 20 | ## When to update docs
|
| 21 |
|
| 22 | Update documentation **in the same commit** (or immediately before merge) when you change:
|
| 23 |
|
| 24 | - Supported DSL syntax or directives
|
| 25 | - UI tabs, toolbar actions, or dialogs
|
| 26 | - `.pos` file schema or metadata fields
|
| 27 | - Print transport, baud rate, or discovery behaviour
|
| 28 | - Dependencies or CI/release artifacts
|
| 29 | - Anything described in the in-app Help tab
|
| 30 |
|
| 31 | ## Implementation status markers
|
| 32 |
|
| 33 | Design docs written before implementation may describe planned features. When editing:
|
| 34 |
|
| 35 | - Mark **implemented** vs **planned** clearly (as in `PRINTING.md` and `ARCHITECTURE.md`).
|
| 36 | - Remove references to rejected choices (e.g. Tauri, `escpos` crate) unless in a historical "considered" section.
|
| 37 | - Do not document features that are not in code unless under a "Planned" or "Future" heading.
|
| 38 |
|
| 39 | ## HELP.md sync
|
| 40 |
|
| 41 | If you add or change user-visible behaviour:
|
| 42 |
|
| 43 | 1. Edit `docs/HELP.md`.
|
| 44 | 2. Confirm `pub const HELP_MARKDOWN` in `src/lib.rs` still uses `include_str!("../docs/HELP.md")`.
|
| 45 | 3. No duplicate help text elsewhere.
|
| 46 |
|
| 47 | ## README
|
| 48 |
|
| 49 | Keep `README.md` as the entry point: status, build/run, release artifacts, link to `docs/`.
|