{
  "name": "Pauta",
  "edition": "2.0.1",
  "date": "2026-11-06",
  "url": "https://pauta-project.dev/2.0.1/",
  "levels": {
    "MUST": "A release blocker for a new app.",
    "SHOULD": "Expected unless the app has a stated reason.",
    "MAY": "A pattern worth copying when the app grows into it."
  },
  "checks": {
    "code": "Verify by reading or searching the app's source, as the check says.",
    "test": "A named test holds the rule; confirm the app has it, or its equivalent, and that it runs in the build.",
    "by hand": "Needs the running app; source alone can't settle it."
  },
  "rules": [
    {
      "id": "PLAT-01",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-01",
      "text": "The app builds on **JDK 25 or newer**. `maven.compiler.release` 25 is the floor, not the ceiling: build and bundle a current JDK.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`pom.xml` sets `maven.compiler.release` to 25 and the enforcer's `requireJavaVersion` to the open-ended range `[25,)`."
      },
      "reference": "Editora `pom.xml`."
    },
    {
      "id": "PLAT-02",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-02",
      "text": "The installers carry a jlinked runtime; users never install Java.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the `dist` profile's jpackage step builds a jlinked app image (`jLinkOptions`) and wraps the installer around it."
      },
      "reference": "Editora `pom.xml` (`dist` profile)."
    },
    {
      "id": "PLAT-03",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-03",
      "text": "The app builds on **JavaFX 27 or newer**.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`pom.xml` sets `javafx.version` to 27 or later."
      },
      "reference": "Editora `pom.xml`."
    },
    {
      "id": "PLAT-04",
      "level": "SHOULD",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-04",
      "text": "The app is one named JPMS module, `com.<app>`, whose `module-info.java` opens only what reflection, FXML and Jackson need.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`src/main/java/module-info.java` declares `module com.<app>`; each `opens` line serves FXML, Jackson or another reflective reader."
      },
      "reference": "Editora `src/main/java/module-info.java`."
    },
    {
      "id": "PLAT-05",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-05",
      "text": "Controls use **AtlantaFX 3.x** (`atlantafx-base`), with light and dark themes.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`pom.xml` depends on `atlantafx-base` 3.x; the theme list offers at least one light and one dark theme."
      },
      "reference": "Editora `pom.xml`, `ui/Themes.java`."
    },
    {
      "id": "PLAT-06",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-06",
      "text": "App stylesheets take their colors from AtlantaFX `-color-*` tokens, or from state tokens built on them; no component rule carries a fixed hex. See [Icons and color](https://pauta-project.dev/2.0.1/icons-and-color/).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`grep -nE '#[0-9a-fA-F]{3,8}\\b' app.css` finds hexes only where a token is defined (a `ladder()` of the ground, a scoped `-color-*` block), not in a component's `-fx-*-color` or `-fx-fill`."
      },
      "reference": "Editora `app.css`; `StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens` holds the severity and debug colors. Editora's `app.css` still has fixed hexes in a few component rules (the breakpoint markers, the execution arrow, the editor area's defaults)."
    },
    {
      "id": "PLAT-07",
      "level": "SHOULD",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-07",
      "text": "The app bundles **Inter** (Regular, Bold, Italic, BoldItalic and `OFL.txt`), registers it with `Font.loadFont` before any stylesheet, and attaches `ui-font.css` to every scene and dialog pane.",
      "why": "the family has one look on every OS.",
      "check": {
        "kind": "code",
        "text": "the four Inter `.ttf` files and `OFL.txt` are in the resources; one place loads them before the first stylesheet, and one listener adds `ui-font.css` to every window's scene."
      },
      "reference": "Editora `ui/Fonts.java`; `App.installUiFont`."
    },
    {
      "id": "PLAT-08",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-08",
      "text": "The build is **Maven** with the **Maven Wrapper** committed (`mvnw`, `mvnw.cmd`, `.mvn/wrapper/`), so `./mvnw` works on a clean machine.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`mvnw`, `mvnw.cmd` and `.mvn/wrapper/maven-wrapper.properties` are in the repository."
      },
      "reference": "Editora `mvnw`, `.mvn/wrapper/`."
    },
    {
      "id": "PLAT-09",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-09",
      "text": "Nullness is declared with **JSpecify** and checked by **NullAway** on **Error Prone** at compile time. Every package is `@NullMarked` in its own `package-info.java`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the compiler arguments include `-Xep:NullAway:ERROR`; every source package has a `package-info.java` with `@NullMarked`."
      },
      "reference": "Editora `pom.xml`, `docs/conventions.md#null-annotations-jspecify-checked-by-nullaway`."
    },
    {
      "id": "PLAT-10",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-10",
      "text": "Code is formatted by **Spotless** with Palantir Java Format, and CI fails an unformatted change.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the spotless plugin configures `palantirJavaFormat`, and a CI job runs `spotless:check`."
      },
      "reference": "Editora `pom.xml` (spotless plugin), `.github/workflows/ci.yml` (*Format*)."
    },
    {
      "id": "PLAT-11",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-11",
      "text": "Tests run on **JUnit** (Jupiter, 5 or newer) and **TestFX** over JavaFX's built-in **Headless** glass platform (`-Dglass.platform=Headless`), so FX tests need no display, no xvfb and no Monocle.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "surefire's `systemPropertyVariables` set `glass.platform` to `Headless`; no Monocle dependency and no xvfb step in CI."
      },
      "reference": "Editora `pom.xml` (surefire), `docs/testing.md`, `FxTestSupport`."
    },
    {
      "id": "PLAT-12",
      "level": "MUST",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-12",
      "text": "A **JaCoCo** `check` runs at `mvn verify`: **≥ 0.90 lines, ≥ 0.90 methods**, ≥ 0.79 branches, plus per-package floors.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the `jacoco-check` execution is bound to `verify` with `BUNDLE` limits of 0.90 `LINE` and 0.90 `METHOD`."
      },
      "reference": "Editora `pom.xml` `jacoco-check`."
    },
    {
      "id": "PLAT-13",
      "level": "SHOULD",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-13",
      "text": "The app logs through `java.util.logging`, captured in-app by the Debug Log.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the Debug Log adds a handler to the root `java.util.logging` logger; the app's own code imports no other logging API."
      },
      "reference": "Editora `ui/DebugLog.java`."
    },
    {
      "id": "PLAT-14",
      "level": "SHOULD",
      "page": "platform",
      "pageTitle": "Platform baseline",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/platform/#plat-14",
      "text": "JSON config files are Jackson POJOs, each with a `SCHEMA_VERSION`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every class written to the config folder declares `SCHEMA_VERSION` and a `schemaVersion` field."
      },
      "reference": "Editora `config/Settings`, `config/migration/ConfigSchema.java`."
    },
    {
      "id": "REPO-01",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-01",
      "text": "`README.md` is a landing page of about 200 lines: logo, badges, a one-paragraph pitch, the hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`README.md` is near 200 lines and has those parts, with links to the website for the rest."
      },
      "reference": "Editora `README.md`."
    },
    {
      "id": "REPO-02",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-02",
      "text": "`CHANGELOG.md` follows [Keep a Changelog 1.1](https://keepachangelog.com/en/1.1.0/) and SemVer: an `## [Unreleased]` section with Added / Changed / Fixed / Removed, and each entry opens with a bold one-line summary written for users.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the file names Keep a Changelog and Semantic Versioning, starts with `## [Unreleased]`, and every entry starts with `- **`."
      },
      "reference": "Editora `CHANGELOG.md`."
    },
    {
      "id": "REPO-03",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-03",
      "text": "`LICENSE` is MIT, \"Copyright (c) 2026 Adrián Arturo De León Saldivar\".",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`LICENSE` opens with `MIT License` and that copyright line."
      },
      "reference": "Editora `LICENSE`."
    },
    {
      "id": "REPO-04",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-04",
      "text": "`NOTICE` gives the app name, the copyright, \"licensed under the MIT License\", then every bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). It ships inside the installers too.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test fails when a runtime dependency in `pom.xml` has no `NOTICE` entry, and another when `LICENSE` and `NOTICE` are not packaged."
      },
      "reference": "Editora `NOTICE`, `NoticeCoverageTest`, `BuildHygieneTest`."
    },
    {
      "id": "REPO-05",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-05",
      "text": "`AGENTS.md` holds the operational rules for coding agents: essential commands, worktree-per-task, the change checklist. It is not a changelog. A short `CLAUDE.md` points to it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`AGENTS.md` has sections for commands, worktrees and the change checklist; `CLAUDE.md` is a few lines that send the reader to `AGENTS.md`."
      },
      "reference": "Editora `AGENTS.md`, `CLAUDE.md`."
    },
    {
      "id": "REPO-06",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-06",
      "text": "`CONTRIBUTING.md` says how to build, test, format, and open a PR.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`CONTRIBUTING.md` names the build, test and format commands and the PR step."
      },
      "reference": "Editora `CONTRIBUTING.md`."
    },
    {
      "id": "REPO-07",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-07",
      "text": "`docs/` holds `architecture.md`, `conventions.md`, `testing.md`, `gotchas.md`, `release.md`, `building-and-packaging.md` and `decisions/` (ADRs).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each of those paths exists under `docs/`."
      },
      "reference": "Editora `docs/`."
    },
    {
      "id": "REPO-08",
      "level": "MAY",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-08",
      "text": "`TODO.md` holds the open list, kept in the same PR as the change.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`TODO.md` exists at the root."
      },
      "reference": "Editora `TODO.md`."
    },
    {
      "id": "REPO-09",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-09",
      "text": "`.github/ISSUE_TEMPLATE/bug_report.yml` is an issue form whose field ids (`environment`, `report`) the in-app Report a Problem fills.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the form has fields with `id: environment` and `id: report`."
      },
      "reference": "Editora `.github/ISSUE_TEMPLATE/bug_report.yml`."
    },
    {
      "id": "REPO-10",
      "level": "MUST",
      "page": "repository",
      "pageTitle": "Repository documents",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/repository/#repo-10",
      "text": "`branding/` holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit beside it or in `packaging/`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`branding/` has an `.svg`; the `jpackage` icon paths in `pom.xml` point at the generated files."
      },
      "reference": "Editora `branding/editora-icon.svg`, with `editora.png`, `.icns` and `.ico` beside it; the template keeps them in `packaging/icons/`."
    },
    {
      "id": "DOCS-01",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "User documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-01",
      "text": "Every app has user documentation: a *Getting started* page (install, first launch, the first thing to do), one page per feature area, the keyboard reference, the Settings, and an FAQ. It is written for the person using the app, in their words, with screenshots from the real window. The README's 200 lines are not it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the website repository's `src/content/docs/` has a getting-started page, a keymaps page, a settings or configuration page, an FAQ and a page per feature area."
      },
      "reference": "editora-website `src/content/docs/` (43 pages in nine categories, from *Getting started* to *Help*); torrenta-website (19), termina-website (16), mirada-website (11)."
    },
    {
      "id": "DOCS-02",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "User documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-02",
      "text": "The user docs live on the app's website, under `/docs/`, in the app's `<app>-website` repository, beside the feature pages, the screenshots, the news posts and the blog. Each docs page is a Markdown file whose frontmatter gives its `category` and `order`; the sidebar, the sitemap and the RSS feed follow. The app's repository never carries a second copy.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every file in the website's `src/content/docs/` has `category` and `order` in its frontmatter; the app's `docs/` holds no user guide."
      },
      "reference": "editora-website `README.md` (*Content*); Editora's `AGENTS.md`: \"User-facing feature documentation goes to the separate website repository\"."
    },
    {
      "id": "DOCS-03",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "User documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-03",
      "text": "Deep links from the app open the running version's docs. Pages live under `/docs/v-<version>/…`; bare `/docs` and every unversioned slug redirect to the current version, so a link in a page never carries a version and a bump just regenerates `src/lib/version.ts`. The app builds the base from its own version with `-SNAPSHOT` dropped, so a development build points at the release it is working toward instead of a path that would always 404.",
      "why": "a release that pointed at another release's docs would claim what is not true ([*Never claim what is not true*](https://pauta-project.dev/2.0.1/principles/#for-the-people-using-the-apps)), so this becomes a must the day the app links to a specific page.",
      "check": {
        "kind": "code",
        "text": "the app's docs URL is `<homepage>/docs/v-` plus its version without `-SNAPSHOT`; the site's `astro.config.mjs` serves `/docs/v-<version>/` and redirects the unversioned paths."
      },
      "reference": "Editora `AppInfo.docsUrl()`, `releaseVersion()`; editora-website `astro.config.mjs`, `README.md` (*Versioned docs*). The other three sites carry a comment to port these routes when their app first deep-links."
    },
    {
      "id": "DOCS-04",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "User documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-04",
      "text": "Docs are generated where the app is the source. The Commands and Keybindings pages are generated from the app's command registrations, `messages.properties` and keymaps; the Roadmap and What's new from `TODO.md` and `CHANGELOG.md`; the version from `pom.xml`. The output is committed, so the site builds without the app checked out. A check fails the site when a docs page quotes a command id that does not exist or a chord that is bound to a different command.",
      "why": "one fact, one source ([*One source of truth for each fact*](https://pauta-project.dev/2.0.1/principles/#for-the-people-building-them)).",
      "check": {
        "kind": "code",
        "text": "the website's `scripts/` holds the generators, their output under `src/lib/` is committed, and `npm run check:docs` runs the id and chord check."
      },
      "reference": "editora-website `scripts/GenCommands.java` (every `Command.of` in Editora's `com.editora.ui`, `MainController` holding most), `GenRoadmap.java`, `GenFeatures.java`; `scripts/check-doc-commands.mjs` (`npm run check:docs`)."
    },
    {
      "id": "DOCS-05",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "User documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-05",
      "text": "Release notes are written for users. Each `CHANGELOG.md` entry opens with a bold one-line summary ([Repository documents](https://pauta-project.dev/2.0.1/repository/)); the GitHub release carries the section, the Welcome page's *What's New* opens this build's release, and the website's What's new is generated from the same file.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the Welcome page's *What's New* opens `AppInfo.releaseNotesUrl()`; the website's What's new is generated from `CHANGELOG.md`."
      },
      "reference": "Editora `AppInfo.releaseNotesUrl()`, `WelcomePane` (`welcome.whatsNew`); editora-website `GenRoadmap.java`."
    },
    {
      "id": "DOCS-06",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-06",
      "text": "**Help → Documentation** opens the user docs in the browser. It is a command (`help.documentation`), so it is in the palette, bindable and in the menu through the registry like every other row; it is the first row of the Help menu after the Command Palette, and the Welcome page's Help row repeats it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`help.documentation` is registered, follows `palette.show` in the Help `MenuSpec`, and the Welcome page's Help row runs it through the registry."
      },
      "reference": "Editora `WindowCommandRegistrar` (`help.documentation` → `MainController.openDocumentation()`), `MenuBarModel` (`menubar.help`), `WelcomePane` (`welcome.documentation`)."
    },
    {
      "id": "DOCS-07",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-07",
      "text": "The Help menu runs in this order: Command Palette · Documentation · Check for Updates · Message Log · Debug Log · Report a Problem · About. Simple mode keeps Command Palette, Documentation and About. An app without a feature drops its row; nothing moves.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "both `menubar.help` menu specs list those command ids in that order."
      },
      "reference": "Editora `MenuBarModel`, both `MenuSpec(\"menubar.help\", …)`."
    },
    {
      "id": "DOCS-08",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-08",
      "text": "Help has a keyboard reference: a searchable window of every key, grouped as the menus are, or the keybinding editor.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open it from Help, search for a command, and find its key."
      },
      "reference": "Termina's and Mirada's `ShortcutsWindow`; Editora's keybinding editor ([Keyboard first](https://pauta-project.dev/2.0.1/keyboard/))."
    },
    {
      "id": "DOCS-09",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-09",
      "text": "Every command has a one-line description (`command.<id>.desc`), shown under the title in the palette. It is the in-app documentation of the command.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "the parity test fails when a `command.<id>` title has no `.desc`."
      },
      "reference": "Editora `messages.properties`, `MessagesTest.everyCommandTitleHasAMatchingDescription` ([Code quality gates](https://pauta-project.dev/2.0.1/quality/))."
    },
    {
      "id": "DOCS-10",
      "level": "MAY",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-10",
      "text": "The palette opens per-command help. With a command highlighted, `C-h` opens its page, `/docs/v-<version>/commands/<id>`; where the keymap binds `C-h`, the first free of `F1` and `Shift+F1` does. Search Everywhere shares the URL builder so the two pickers can never disagree.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the palette and Search Everywhere both build the URL with `CommandPalette.docsUrl`."
      },
      "reference": "Editora `CommandPalette.docsUrl`, `setDocsOpener`; `PickerKeys.freeChord`."
    },
    {
      "id": "DOCS-11",
      "level": "MAY",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Reachable from the app",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-11",
      "text": "Each page of the Settings window has a *Help for &lt;page&gt;* link to its docs page, from one map of page to slug.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "one map from Settings page to docs slug feeds every page's help link."
      },
      "reference": "Editora `SettingsWindow`, `SettingsFrameBits.helpUrl`, `settings.help`."
    },
    {
      "id": "DOCS-12",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Developer documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-12",
      "text": "`docs/` has an index. `docs/README.md` says who the folder is for (contributors; user docs live on the website), states that the code wins when the two disagree, and lists every guide with one line. The set is the one [Repository documents](https://pauta-project.dev/2.0.1/repository/) names: `architecture.md`, `conventions.md`, `testing.md`, `gotchas.md`, `release.md`, `building-and-packaging.md` and `decisions/`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`docs/README.md` exists, says those two things, and links each guide in `docs/`."
      },
      "reference": "Editora's `docs/README.md`; the template's `docs/`."
    },
    {
      "id": "DOCS-13",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Developer documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-13",
      "text": "Every choice a newcomer would question has a decision record: a fork, a rejected dependency, a storage format, an escape hatch. It is one numbered Markdown file, `docs/decisions/NNNN-slug.md`, with the context, the decision and what it costs.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`docs/decisions/` holds `NNNN-slug.md` files, each with context, decision and consequences."
      },
      "reference": "Editora's `docs/decisions/` (18 records, from `0001-richtextfx-fork.md`)."
    },
    {
      "id": "DOCS-14",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Developer documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-14",
      "text": "Three files have three jobs. `AGENTS.md` is the operational guide, kept short (commands, worktree-per-task, the change checklist). `CONTRIBUTING.md` is the short version for a person, pointing into `docs/`. `docs/` holds the durable explanations. Exhaustive history goes to `docs/reference/`, not into any of the three.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`AGENTS.md` and `CONTRIBUTING.md` link into `docs/`; long catalogs sit under `docs/reference/`."
      },
      "reference": "Editora's `AGENTS.md` (*Documentation map*), `CONTRIBUTING.md`, `docs/reference/README.md`."
    },
    {
      "id": "DOCS-15",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Developer documentation",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-15",
      "text": "Javadoc sits on its member: a doc comment above another doc comment documents nothing. Comments say why, not what.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test fails the build on a Javadoc comment followed by another."
      },
      "reference": "Editora `StackedJavadocTest`."
    },
    {
      "id": "DOCS-16",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Kept in step",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-16",
      "text": "Docs change in the same PR. A change that affects behavior updates `CHANGELOG.md`, `TODO.md`, the contributor guides it touches and the website's user docs in the same change, never as a follow-up. A reviewer treats a feature PR with no docs change as incomplete.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`docs/conventions.md`, `CONTRIBUTING.md` and `AGENTS.md` state the rule; in review, a feature PR's diff touches `CHANGELOG.md`."
      },
      "reference": "Editora `docs/conventions.md#docs-in-the-same-pr`, `CONTRIBUTING.md` (step 4), `AGENTS.md`."
    },
    {
      "id": "DOCS-17",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Kept in step",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-17",
      "text": "When documentation and code disagree, the code wins, and the documentation is fixed in the same change. The same rule this guide applies to itself.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`AGENTS.md` and `docs/README.md` say so."
      },
      "reference": "Editora's `AGENTS.md`, `docs/README.md`."
    },
    {
      "id": "DOCS-18",
      "level": "SHOULD",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Kept in step",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-18",
      "text": "Screenshots are retaken, not described. The capture hook renders the real window at 2× after any UI change, for the README (its hero in light and dark), the website and bug reports.",
      "why": "a stale screenshot claims what is not true.",
      "check": {
        "kind": "code",
        "text": "the app has a capture hook or a headless harness that writes the real window to a PNG."
      },
      "reference": "`DevCapture` ([Shared features](https://pauta-project.dev/2.0.1/family/shared-features/)); Editora's headless harness."
    },
    {
      "id": "DOCS-19",
      "level": "MUST",
      "page": "documentation",
      "pageTitle": "Documentation",
      "section": "Kept in step",
      "url": "https://pauta-project.dev/2.0.1/documentation/#docs-19",
      "text": "The README defers. It is about 200 lines: pitch, hero, highlights, install, build, command line, config folder, license, and links into the website's docs. It carries no feature catalog, so it changes only when those facts do.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`README.md` is near 200 lines and links to the website's docs instead of listing every feature."
      },
      "reference": "[Repository documents](https://pauta-project.dev/2.0.1/repository/); Editora `docs/conventions.md#docs-in-the-same-pr`."
    },
    {
      "id": "QUAL-01",
      "level": "MUST",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-01",
      "text": "NullAway is an error, not a warning. A new package starts with its own `package-info.java` carrying `@NullMarked`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the compiler arguments say `-Xep:NullAway:ERROR`; every source package has a `package-info.java` with `@NullMarked`."
      },
      "reference": "Editora `pom.xml`, `docs/conventions.md` (*Null annotations*)."
    },
    {
      "id": "QUAL-02",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-02",
      "text": "A NullAway report is fixed, not suppressed: put `@Nullable` on what may be null.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`grep -rn '@SuppressWarnings(\"NullAway\")' src/main` finds nothing."
      },
      "reference": "Editora; one suppression is left, in `recovery/RecoveryCodec.java`."
    },
    {
      "id": "QUAL-03",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-03",
      "text": "Coverage floors are a regression net, not a target. Beyond the build-wide floor of 0.90 lines and methods, each package of 300+ lines gets its own floor about three points below its measured level; when a package's coverage rises, its floor is ratcheted up.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the `jacoco-check` rules in `pom.xml` carry a `PACKAGE` line floor for each large package."
      },
      "reference": "Editora `pom.xml` `jacoco-check`."
    },
    {
      "id": "QUAL-04",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-04",
      "text": "When a guide quotes the coverage floors, a test fails when the quoted table and the pom disagree.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a build test reads the `jacoco-check` rules from `pom.xml` and compares them with the guide's table."
      },
      "reference": "Editora `BuildHygieneTest.theCoverageFloorsQuotedInTheTestingGuideAreTheOnesTheBuildEnforces`, `docs/testing.md`."
    },
    {
      "id": "QUAL-05",
      "level": "MUST",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-05",
      "text": "Extract the decision, then test it ([principle 12](https://pauta-project.dev/2.0.1/principles/#for-the-people-building-them)). Prefer a pure decision helper plus unit tests; use the headless FX harness only when controller or toolkit behavior is the point.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "enablement, visibility and navigation rules sit in classes that import no `javafx` type, each with a unit test not tagged `fx`."
      },
      "reference": "Editora `docs/testing.md` (*Prefer pure logic*): `ui/Chrome`, `editops/TextNav`, `config/PathKeys`, each with a plain unit test."
    },
    {
      "id": "QUAL-06",
      "level": "MUST",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-06",
      "text": "FX tests are tagged `@Tag(\"fx\")`, so the pure suite runs alone with `-DexcludedGroups=fx`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every test class that boots the toolkit (`FxTestSupport`, `FxToolkit`) carries `@Tag(\"fx\")`."
      },
      "reference": "Editora `docs/testing.md`. Editora does not hold it fully yet: about twenty `*FxTest` classes, most of them `ProjectMap*FxTest`, carry no tag."
    },
    {
      "id": "QUAL-07",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-07",
      "text": "Tests do not sleep. Workers and FX callbacks are owned by a scope (`AsyncTestScope`), and tests wait on latches.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`grep -rn 'Thread.sleep' src/test` finds nothing."
      },
      "reference": "Editora `AsyncTestScope`, `docs/testing.md`. Many older Editora tests still poll with `Thread.sleep`."
    },
    {
      "id": "QUAL-08",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-08",
      "text": "A test window writes only inside its temp folders, never in the real home directory.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "the command sweep checks the home directory after running every command."
      },
      "reference": "Editora `CommandSweepFxTest.leftInTheHomeDirectory`."
    },
    {
      "id": "QUAL-09",
      "level": "MUST",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-09",
      "text": "UI work is verified in the running app ([principle 13](https://pauta-project.dev/2.0.1/principles/#for-the-people-building-them)): a capture hook or headless screenshot of the real window, with real key and mouse events, before a UI change is called done.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the app has a capture hook (`DevCapture`) or a headless fixture that builds the real window."
      },
      "reference": "Editora `FxWindowFixture` (the real `MainController` window, headless); Torrenta and Termina `DevCapture.java`."
    },
    {
      "id": "QUAL-10",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-10",
      "text": "A guard that cannot fail is decoration. When you add a drift or parity test, break the thing it guards once and watch it fail.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "break what the new test guards, run it, and see it fail."
      },
      "reference": "Modula's `DependenciesTest`."
    },
    {
      "id": "QUAL-11",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-11",
      "text": "A command sweep runs every registered command in a real headless window.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "one FX test iterates the registry and runs each command."
      },
      "reference": "Editora `CommandSweepFxTest`."
    },
    {
      "id": "QUAL-12",
      "level": "MUST",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-12",
      "text": "A message parity test holds that every locale has every key and every `command.<id>` has a `.desc`.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "the test fails on a key missing from a locale or a command title without `.desc`."
      },
      "reference": "Editora `MessagesTest`."
    },
    {
      "id": "QUAL-13",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-13",
      "text": "A settings round trip shows that every switch, number and choice survives a restart.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "one FX test sets every control, reloads the settings and reads each back."
      },
      "reference": "Editora `SettingsRoundTripFxTest`."
    },
    {
      "id": "QUAL-14",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-14",
      "text": "A contrast test holds that text tokens keep their ratios in every theme.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a pure test reads the stylesheets and does the WCAG arithmetic."
      },
      "reference": "Editora `StyleContrastTest`."
    },
    {
      "id": "QUAL-15",
      "level": "SHOULD",
      "page": "quality",
      "pageTitle": "Code quality gates",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/quality/#qual-15",
      "text": "A release supply-chain test keeps the signing and attestation steps where they are.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test reads the workflows and fails when a signing, notarization or attestation step moves or goes."
      },
      "reference": "Editora `ReleaseSupplyChainTest`."
    },
    {
      "id": "PERF-01",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "The UI thread",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-01",
      "text": "Never block the JavaFX application thread. No file or network I/O, no process start or wait, no parsing, searching, hashing or JSON of any size on it, and no `Thread.sleep`, `Future.get()`, `join()` or `Process.waitFor()` there.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "event handlers, listeners and `Platform.runLater` bodies call no `Files.*`, `HttpClient.send`, `ProcessBuilder.start`, `waitFor`, `Future.get`, `join` or `Thread.sleep`; that work runs on an executor or a virtual thread."
      },
      "reference": "Editora `docs/performance.md` §1."
    },
    {
      "id": "PERF-02",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "The UI thread",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-02",
      "text": "Touch the scene graph only on the FX thread. Background work hands its result back with `Platform.runLater`; nothing else creates, changes or reads live nodes.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every executor task or thread body that ends in UI work wraps that work in `Platform.runLater`."
      },
      "reference": "every Editora service, for example `git/GitService.java`."
    },
    {
      "id": "PERF-03",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "The UI thread",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-03",
      "text": "A background result is applied under a generation guard, so an answer to an old request never overwrites a newer one.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each request takes a generation (`AtomicLong.incrementAndGet`) or goes through `LatestOnly`, and its result is applied only while that generation is still current, checked again inside the `runLater`."
      },
      "reference": "Editora `git/GitService.java`, `search/SearchService.java`, `ui/LatestOnly.java` (`LatestOnlyTest`)."
    },
    {
      "id": "PERF-04",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "The UI thread",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-04",
      "text": "Every thread is named and is a daemon.",
      "why": "a thread dump then says what is running, and a stray worker never keeps the app alive after its last window closes.",
      "check": {
        "kind": "code",
        "text": "every `Executors.new…` and `new Thread` gets a name and `setDaemon(true)`, through a thread factory such as `daemon(\"my-feature\")`; virtual threads are daemons already."
      },
      "reference": "Editora `daemon(\"my-feature\")` in the shape below, `terminal/TerminalExecutors.java`."
    },
    {
      "id": "PERF-05",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "The UI thread",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-05",
      "text": "Blocking work stays off the common `ForkJoinPool`, and a `Process` subclass overrides `onExit()`.",
      "why": "the common pool has one worker fewer than the machine has cores, so a few blocked waits (`CompletableFuture.supplyAsync` of a `waitFor`) starve every other user of it.",
      "check": {
        "kind": "code",
        "text": "no `supplyAsync` or `runAsync` without an executor wraps a blocking call, and every class that extends `Process` overrides `onExit()`."
      },
      "reference": "Editora `process/ExitWatch.java`, `docs/gotchas.md`. Editora's `DapManager.reportJavaExit` still waits up to 3 s for an exit code in a `supplyAsync` on the common pool."
    },
    {
      "id": "PERF-06",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Hot paths",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-06",
      "text": "Redraws are coalesced to at most one per pulse with a `pending` flag, and text-driven work waits for typing to pause.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a redraw request sets a `pending` flag and schedules one pass; listeners on text go through a debounce."
      },
      "reference": "Editora `ui/FxThrottle.java`."
    },
    {
      "id": "PERF-07",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Hot paths",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-07",
      "text": "Streams (process output, logs, progress) reach the FX thread in batches at least 16 ms apart, never one `runLater` per line.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a reader thread appends to a buffer that the FX thread drains, with a minimum interval between drains."
      },
      "reference": "Editora `process/OutputPump.java` (`MIN_DRAIN_INTERVAL_MILLIS`), `ui/ConsoleAppender.java`."
    },
    {
      "id": "PERF-08",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Hot paths",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-08",
      "text": "Work only on what is visible and only on what changed: no O(document) or O(list) work per keystroke, scroll or tick. Anything that can grow is shown in a virtualized control (`ListView`, `TableView`, a fixed cell size).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a listener on text, scroll or a timer re-processes the edited range or the visible rows, never the whole document or list; growing lists are `ListView` or `TableView`, not a `VBox` of nodes."
      },
      "reference": "Editora `editor/highlight/HighlightPass.java`, `editor/minimap/MinimapRows.java`."
    },
    {
      "id": "PERF-09",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Hot paths",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-09",
      "text": "A hot path allocates little: it reuses buffers and arrays, and caches data a repaint only reads.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the per-frame and per-keystroke code allocates no new arrays or images when the size has not changed."
      },
      "reference": "Editora `editor/minimap/Minimap.java` (the snapshot image reused at the same size), `MinimapRows.java`."
    },
    {
      "id": "PERF-10",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Hot paths",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-10",
      "text": "CSS stays cheap: no `applyCss()` on a large subtree, stable style classes, and spans of the same style merged before they are applied.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`applyCss()` is called only on small nodes; style classes are not toggled per keystroke."
      },
      "reference": "Editora `SpanMerger` in `editor/highlight/TextMateHighlighter.java`, `docs/gotchas.md`."
    },
    {
      "id": "PERF-11",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Memory and size",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-11",
      "text": "Everything that grows is bounded: logs, histories, consoles, caches, undo. The newest is kept, with a note of what was cut.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "each such store has a test that fills it past its cap and finds the oldest dropped."
      },
      "reference": "Editora `ui/MessageLog.java` (200, `MessageLogTest`), `ui/DebugLog.java` (`DebugLogTest`), `test/OutputCap.java`."
    },
    {
      "id": "PERF-12",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Memory and size",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-12",
      "text": "Large inputs are guarded by size and shape before they load: expensive features turn off past one threshold, the input opens read-only or capped past another, and what will not fit the free heap is refused.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the loader compares the size against named thresholds before reading the content."
      },
      "reference": "Editora `EditorBuffer.LARGE_FILE_BYTES` (5 MB) and `HUGE_FILE_BYTES` (50 MB), `ui/LoadHeapGuard.java` (`LoadHeapGuardTest`)."
    },
    {
      "id": "PERF-13",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Memory and size",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-13",
      "text": "A closed window releases what it held: listeners, timers, executors, file watchers, native resources.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test opens and closes windows and checks nothing is left running."
      },
      "reference": "Editora `FxWindowFixture.dispose` (`FxWindowFixtureLifecycleFxTest`), `ClosedLspManagers`."
    },
    {
      "id": "PERF-14",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Start-up",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-14",
      "text": "The first frame comes first: only what the first window shows is built before it; tool windows, panels and pages build on first open.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test opens a window and finds no closed tool window's panel built before the first paint."
      },
      "reference": "Editora's lazy `ToolWindow` suppliers, `LazyToolWindowsFxTest`."
    },
    {
      "id": "PERF-15",
      "level": "MUST",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Start-up",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-15",
      "text": "What nobody waits for starts after the first frame has painted: the update check, extra fonts, indexes and caches.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test finds the deferred work not started before the first paint."
      },
      "reference": "Editora `ui/UpdateCheckScheduler.java`, `Fonts.loadRemainingAfterNextPaint` (`UpdateCheckSchedulerTest`, `FontsDeferredLoadFxTest`, `StartupDeferralFxTest`)."
    },
    {
      "id": "PERF-16",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Start-up",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-16",
      "text": "Config is read off the FX thread, before the toolkit needs it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`main` starts the config read on its own thread before `launch`."
      },
      "reference": "Editora's `config-prefetch` thread in `App.java`."
    },
    {
      "id": "PERF-17",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Start-up",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-17",
      "text": "The app ships precompiled stylesheets (`.bss`) and an AOT cache trained on a real session.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the build converts the `.css` files to `.bss` and runs a training launch for the AOT cache."
      },
      "reference": "Editora `scripts/css2bss.java`, `scripts/aot_build.java`; Termina's and Mirada's `scripts/aot-train.sh`."
    },
    {
      "id": "PERF-18",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Measure, don't guess",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-18",
      "text": "Every change on a hot path says what it costs in its pull request: added FX-thread work, allocation per keystroke or scroll, extra layout passes, memory. \"Negligible\" is an answer; no answer is not.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "read the app's recent pull requests that touch a hot path."
      },
      "reference": "Editora `docs/performance.md` (its opening paragraph)."
    },
    {
      "id": "PERF-19",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Measure, don't guess",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-19",
      "text": "Start-up is measured by a script that takes the median of several cold launches, and by phase marks in the app.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the repository has the script, and `main` and the first paint record phase marks."
      },
      "reference": "`scripts/measure-startup.sh` in Editora and Mirada; Editora `perf/Startup.java`."
    },
    {
      "id": "PERF-20",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Measure, don't guess",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-20",
      "text": "The app can sample its FX thread when something stalls.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "an environment variable or property turns on a sampler of the FX thread's stack."
      },
      "reference": "Editora `perf/Startup.java` (`EDITORA_PERF_SAMPLE=1`)."
    },
    {
      "id": "PERF-21",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Measure, don't guess",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-21",
      "text": "Each hot path that once regressed keeps a headless test.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "the fix for a hot-path regression adds a headless test that fails on the old code."
      },
      "reference": "Editora `MinimapDeferredRenderFxTest`."
    },
    {
      "id": "PERF-22",
      "level": "SHOULD",
      "page": "performance",
      "pageTitle": "Performance",
      "section": "Measure, don't guess",
      "url": "https://pauta-project.dev/2.0.1/performance/#perf-22",
      "text": "A suspected regression gets a number before and after, from temporary `System.nanoTime` instrumentation if nothing better exists.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "the pull request that fixes it states both numbers."
      },
      "reference": "Editora `docs/performance.md`."
    },
    {
      "id": "KBD-01",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Commands",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-01",
      "text": "Every user-facing action is a `Command` (id, title, runnable) registered in one `CommandRegistry`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "menu items, toolbar buttons, palette rows and key bindings run a command id through the registry; no control's handler does work no command can reach."
      },
      "reference": "Editora `command/Command.java`, `command/CommandRegistry.java`."
    },
    {
      "id": "KBD-02",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Commands",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-02",
      "text": "Command ids are dotted and grouped by area: `file.open`, `view.toggleStatusBar`, `help.reportProblem`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every registered id matches `<area>.<camelCaseName>`."
      },
      "reference": "Editora `ui/MenuBarModel.java`."
    },
    {
      "id": "KBD-03",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Commands",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-03",
      "text": "A command's title comes from `command.<id>` and its palette description from `command.<id>.desc` in the message catalogs.",
      "why": "a registered command is then localized and discoverable without extra work.",
      "check": {
        "kind": "test",
        "text": "a catalog parity test fails when a registered command has no `command.<id>` or `command.<id>.desc` key."
      },
      "reference": "Editora `i18n/messages.properties`, `MessagesTest`."
    },
    {
      "id": "KBD-04",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Commands",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-04",
      "text": "A command that cannot run in the current context is shown grayed, with a tooltip that says why, not hidden.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the palette and menus list a disabled command with a reason, rather than filtering it out."
      },
      "reference": "Editora `ui/Chrome.java` (`paletteEnabled`, `disabledReason`)."
    },
    {
      "id": "KBD-05",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Command Palette",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-05",
      "text": "The Command Palette opens with `M-x` in the Emacs keymap and `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) in the others.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each bundled keymap binds that chord to the palette command."
      },
      "reference": "Editora `keymaps/emacs.json` (`M-x`), `cua.json` and `vscode.json` (`C-S-p`), `cua.mac.json` (`Cmd-S-p`), all to `palette.show`."
    },
    {
      "id": "KBD-06",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Command Palette",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-06",
      "text": "The palette matches fuzzily over title, id and description; a query that names a command's title outranks a fuzzy hit. Each row shows the command's binding in the active keymap. See the [Command Palette template](https://pauta-project.dev/2.0.1/templates/command-palette/).",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a ranking test puts the title match first."
      },
      "reference": "Editora `ui/CommandPalette.java`, `search/FuzzyMatch.java`."
    },
    {
      "id": "KBD-07",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Command Palette",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-07",
      "text": "The palette is an in-scene overlay in the window's root `StackPane`, not a `javafx.stage.Popup`.",
      "why": "on Windows a Popup does not reliably take OS keyboard focus, and the whole app can stop receiving keystrokes.",
      "check": {
        "kind": "code",
        "text": "the palette and every picker add their node to the root `StackPane`; none creates a `Popup`."
      },
      "reference": "Editora `ui/CommandPalette.java`."
    },
    {
      "id": "KBD-08",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Command Palette",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-08",
      "text": "The same picker serves every other list choice: recent files, themes, keymaps, a setting's values.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no second list-picker class or `ChoiceDialog` for those choices."
      },
      "reference": "Editora `ui/QuickOpen.java`."
    },
    {
      "id": "KBD-09",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-09",
      "text": "Emacs and CUA keymaps ship as JSON resources, CUA with a `.mac.json` variant where Cmd replaces Ctrl.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`emacs.json`, `cua.json` and `cua.mac.json` are in the app's resources."
      },
      "reference": "Editora `src/main/resources/com/editora/keymaps/`."
    },
    {
      "id": "KBD-10",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-10",
      "text": "IntelliJ, VS Code and Sublime keymaps ship the same way, each with its `.mac.json` variant.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`intellij`, `vscode` and `sublime` `.json` and `.mac.json` files are in the resources."
      },
      "reference": "Editora `src/main/resources/com/editora/keymaps/`."
    },
    {
      "id": "KBD-11",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-11",
      "text": "Keymaps are applied in layers: base keymap → user overrides → plugin keymaps → the user's own bindings again. An app without plugins has the first two.",
      "why": "the user always has the last word, and a plugin can still use a chord the user freed.",
      "check": {
        "kind": "code",
        "text": "one place applies the layers in that order."
      },
      "reference": "Editora `ui/KeymapLayers.java`."
    },
    {
      "id": "KBD-12",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-12",
      "text": "A keymap editor in Settings lists every command with its chord, is searchable, and warns of conflicts.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open Settings → Keymap, search, and bind a chord that is taken."
      },
      "reference": "Editora `ui/SettingsKeymapsPage.java`; conflicts from `KeybindingEdits.takenDefaults`."
    },
    {
      "id": "KBD-13",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-13",
      "text": "No command's chord is written into translated text. Every label shows the binding from the active keymap. Fixed keys of a control (Enter, Tab, Esc, arrows) and keys meant for another program may be written.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no message catalog value names a command's chord (`Ctrl+`, `Cmd+`, `C-x`, `M-x`); chords are rendered by one formatter."
      },
      "reference": "Editora `command/ChordFormat.java`, the one place a binding is rendered. Editora's `command.edit.universalArgument` title still carries `C-u`."
    },
    {
      "id": "KBD-14",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Keymaps",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-14",
      "text": "A multi-key prefix (`C-x …`) shows a which-key style hint listing the possible next keys.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "press `C-x` in the Emacs keymap and wait."
      },
      "reference": "no app lists the next keys yet. Editora echoes only the pending prefix (`C-x -`) in the status bar (`command/KeyDispatcher.java`)."
    },
    {
      "id": "KBD-15",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-15",
      "text": "Every interactive control is reachable with Tab and operable with Space or Enter. Toolbar buttons are the exception: they stay out of the Tab order (see [Toolbars and tooltips](https://pauta-project.dev/2.0.1/toolbars-and-tooltips/)).",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "Tab through every window and dialog without the mouse."
      },
      "reference": "Editora; `FocusRingFxTest` holds that every control family draws the focus ring when Tab reaches it."
    },
    {
      "id": "KBD-16",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-16",
      "text": "The keyboard focus ring is one layer of `:focus-visible` rules at the end of `app.css`.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test tabs to each control family and asserts the ring."
      },
      "reference": "Editora `app.css` (*Keyboard focus*, one layer for every control), `FocusRingFxTest`."
    },
    {
      "id": "KBD-17",
      "level": "MUST",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-17",
      "text": "Icon-only buttons are built by one helper that sets both the tooltip and the accessible text.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no icon-only `Button` is built outside the helper."
      },
      "reference": "Editora `ui/Icons.java` (`Icons.button`). Editora's main toolbar doesn't yet: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set the tooltip but no accessible text."
    },
    {
      "id": "KBD-18",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-18",
      "text": "On/off rows use a keyboard-operable switch with the `TOGGLE_BUTTON` role.",
      "why": "a bare AtlantaFX `ToggleSwitch` is mouse-only.",
      "check": {
        "kind": "code",
        "text": "no `new ToggleSwitch` outside the switch class."
      },
      "reference": "Editora `ui/SettingSwitch.java`."
    },
    {
      "id": "KBD-19",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-19",
      "text": "Readable text uses `-color-fg-muted` or stronger; `-color-fg-subtle` (about 3:1) is for disabled or decorative text only.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a pure contrast test over the stylesheets."
      },
      "reference": "Editora `StyleContrastTest`."
    },
    {
      "id": "KBD-20",
      "level": "SHOULD",
      "page": "keyboard",
      "pageTitle": "Keyboard first",
      "section": "Focus and accessibility",
      "url": "https://pauta-project.dev/2.0.1/keyboard/#kbd-20",
      "text": "Rows wrap instead of truncating to \"…\".",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "run the app in German at 1024 px wide; no test catches a cut row."
      },
      "reference": "Editora `messages_de.properties`."
    },
    {
      "id": "WIN-01",
      "level": "MUST",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-01",
      "text": "A status bar is always present (it can be toggled). Its left side is the *echo area*: one line of feedback for the last action, errors in red and warnings in amber. Clicking it opens the Message Log.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the echo label switches between an error and a warning style class, and its click handler runs the Message Log command."
      },
      "reference": "Editora `ui/StatusBar.java` (`status-echo-error`, `status-echo-warn`; a click runs `view.messageLog`) and the [Message Log template](https://pauta-project.dev/2.0.1/templates/message-log/)."
    },
    {
      "id": "WIN-02",
      "level": "MUST",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-02",
      "text": "Light and dark AtlantaFX themes and a \"follow the system\" choice, switchable at run time without a restart. Semantic colors: amber is not durable yet (unsaved, read-only), red is broken, green is verified or added. See [Icons and color](https://pauta-project.dev/2.0.1/icons-and-color/).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "one place applies the app theme to every open window, and the theme list has a system choice that follows the OS color scheme as it changes."
      },
      "reference": "Editora `ui/Themes.java` (`applyAppTheme`) switches at run time and `ui/WindowColorScheme.java` tells every window's frame which scheme it is in; Mirada `ui/Theme.java` (`ThemeChoice.SYSTEM`) follows the system. Editora has no system choice yet."
    },
    {
      "id": "WIN-03",
      "level": "SHOULD",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-03",
      "text": "The title bar uses JavaFX 27's `HeaderBar` with `StageStyle.EXTENDED` to carry the menu or tabs, with a decorated-window fallback, and `useSystemMenuBar` on macOS.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the main stage is created `StageStyle.EXTENDED` with a `HeaderBar`, a setting falls back to a decorated window, and the menu bar sets `useSystemMenuBar` on macOS."
      },
      "reference": "Editora `ui/ExtendedWindow.java`, `ui/MainMenuBar.java`."
    },
    {
      "id": "WIN-04",
      "level": "SHOULD",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-04",
      "text": "Native dialogs go through one helper that attaches the app stylesheet and the UI font.",
      "why": "a dialog is its own scene and inherits neither.",
      "check": {
        "kind": "code",
        "text": "every `Alert` and `Dialog` the app builds passes through the helper."
      },
      "reference": "Editora `ui/Dialogs.java` (`Dialogs.styled`)."
    },
    {
      "id": "WIN-05",
      "level": "MUST",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-05",
      "text": "A destructive action asks first, and says what it does. Removing, deleting, discarding or overwriting something the user made goes through one confirm helper: the question names the thing (\"Remove 3 torrents?\"), the confirm button names the action (Remove, Discard, Overwrite), never OK or Yes, and Escape cancels. Where the action can be undone instead, the undo is better than the question. See the [Confirm dialog template](https://pauta-project.dev/2.0.1/templates/confirm-dialog/).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each destructive action calls the one confirm helper before it changes anything, or records an undo."
      },
      "reference": "Torrenta `RemoveConfirm` and `UndoStack`; Editora's save decisions (`ui/CloseCoordinator.java`); Termina's and Editora's reopen-closed-tab."
    },
    {
      "id": "WIN-06",
      "level": "SHOULD",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-06",
      "text": "A Welcome page when there is nothing to restore: Start actions (which run commands), Recent items, a Customize block (keymap and theme) and Help links. See the [Welcome template](https://pauta-project.dev/2.0.1/templates/welcome/).",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "start the app with no session to restore."
      },
      "reference": "Editora `ui/WelcomePane.java`."
    },
    {
      "id": "WIN-07",
      "level": "MUST",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-07",
      "text": "About shows the version, the build, the Pauta edition the app implements, the runtime (Java and JavaFX versions), the license, links, and the result of the last update check. See the [About template](https://pauta-project.dev/2.0.1/templates/about/).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the About window reads the version, build and edition from `AppInfo` and shows the update checker's last answer."
      },
      "reference": "Editora `ui/AboutDialog.java`. No app names its Pauta edition yet."
    },
    {
      "id": "WIN-08",
      "level": "SHOULD",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-08",
      "text": "Window size, position, maximized state and open items are restored on the next launch; `--no-session` skips the restore.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a round-trip test of the saved workspace state, and a test that `--no-session` is honored."
      },
      "reference": "Editora `config/WorkspaceState.java` (`windowX` … `windowMaximized`), `ui/WindowSessionCoordinator.java`, `App.noSessionFlag`; tests `WorkspaceStateV29Test`, `AppArgsTest`, `NoSessionStartupFxTest`."
    },
    {
      "id": "WIN-09",
      "level": "SHOULD",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-09",
      "text": "UI and content zoom from the keyboard (`Ctrl/Cmd +`, `-`, `0`), kept across launches.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "zoom in, out and reset are commands bound in every keymap, and the zoom level is a saved setting."
      },
      "reference": "Editora zooms content only: `view.textZoomIn`, `view.textZoomOut` and `view.textZoomReset`, kept in `Settings.fontZoom`."
    },
    {
      "id": "WIN-10",
      "level": "MAY",
      "page": "window-shell",
      "pageTitle": "Window shell",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/window-shell/#win-10",
      "text": "Modes: Zen (no chrome), Simple (fewer menus for new users), Expert.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each mode is a command, and one truth table decides which chrome each mode shows."
      },
      "reference": "Editora `ui/WindowChromeCoordinator.java` (`toggleZen`, `applySimpleMode`) over the truth table in `ui/Chrome.java`."
    },
    {
      "id": "ICON-01",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Type",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-01",
      "text": "Inter is attached by a *scene* stylesheet on every window's scene, dialogs, popups and tooltips included, not by a rule in the app stylesheet.",
      "why": "dialogs, the Settings window, the palette, context menus and tooltips each live in a scene of their own that does not share `app.css`, and a scene sheet is re-applied cleanly when the theme switches at run time (`setUserAgentStylesheet`). AtlantaFX neither bundles nor names Inter, and JavaFX does not fall through a font-family list, so without the sheet the whole interface renders in the platform's \"System\" face.",
      "check": {
        "kind": "code",
        "text": "a listener on `Window.getWindows()` adds `ui-font.css` to each window's scene, and to a new scene when the window's scene changes; no `.root` rule in `app.css` sets `-fx-font-family`."
      },
      "reference": "Editora `App.installUiFont`, `styles/ui-font.css`. Termina and Torrenta carry the same sheet."
    },
    {
      "id": "ICON-02",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Type",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-02",
      "text": "The app bundles Inter's four faces and registers them before any CSS is applied; it never maps the platform's own UI font.",
      "why": "an earlier macOS-only sheet used San Francisco, which JavaFX faux-bolds; Inter has a real bold on every platform.",
      "check": {
        "kind": "code",
        "text": "`Inter-Regular`, `Inter-Bold`, `Inter-Italic` and `Inter-BoldItalic` `.ttf` are under the app's `fonts/inter/` with their `OFL.txt`, and `Font.loadFont` runs on them before the first window is shown."
      },
      "reference": "Editora `src/main/resources/com/editora/fonts/inter/`, `ui/Fonts.java` (`loadForFirstPaint`, called from `App`). Termina and Torrenta bundle the same four faces."
    },
    {
      "id": "ICON-03",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Type",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-03",
      "text": "A line of UI text is `-color-fg-default` and secondary text `-color-fg-muted`; `-color-fg-subtle` (about 3:1) is for disabled or decorative text only.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test lists the selectors of text that must be read and fails when one uses `-color-fg-subtle`."
      },
      "reference": "Editora `StyleContrastTest.textThatMustBeReadUsesTheMutedRoleNotSubtle`."
    },
    {
      "id": "ICON-04",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "The palette: Caret & Ink",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-04",
      "text": "A theme file follows the vendored AtlantaFX community themes: a `.root` block of `-color-*` tokens, then component rules that reference only those tokens.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the file's first rule is `.root`, and no rule after it holds a `#` hex."
      },
      "reference": "Editora `styles/atlantafx-themes/editora-light.css`, `editora-dark.css`."
    },
    {
      "id": "ICON-05",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "The palette: Caret & Ink",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-05",
      "text": "A new app ships the Caret & Ink pair as its default theme, with `editora-light.css` and `editora-dark.css` copied unchanged into its own `styles/`.",
      "why": "the palette is the family's, not the editor's.",
      "check": {
        "kind": "code",
        "text": "the app's two files are identical to Editora's."
      },
      "reference": "Torrenta and Termina `styles/`. Both copies of `editora-dark.css` match Editora's; both copies of `editora-light.css` still have the earlier `-color-accent-fg`, `-color-warning-fg` and `-color-success-fg`, which Editora has since darkened."
    },
    {
      "id": "ICON-06",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "The palette: Caret & Ink",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-06",
      "text": "Brace (`-state-key`) is a `ladder()` over `-color-bg-default` that picks a deep ink on a light ground and a lighter periwinkle the darker the ground gets, and reads at 4.5:1 or more on every bundled theme's default and subtle surfaces.",
      "why": "Brace has no AtlantaFX role, so it has to be a literal.",
      "check": {
        "kind": "test",
        "text": "a contrast test resolves the ladder against every bundled theme's grounds."
      },
      "reference": "Editora `app.css` (`.root`), `StyleContrastTest.theKeyboardPeriwinkleReadsOnEveryBundledAppTheme`."
    },
    {
      "id": "ICON-07",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-07",
      "text": "Each state color is named once, as a `-state-*` token on `.root` that chains to one of the theme's roles (or a `ladder()` of its ground), and component rules use the token.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the `-state-*` tokens are declared only in the `.root` block at the top of `app.css`, each chaining to a `-color-*` role or a `ladder()`."
      },
      "reference": "Editora `styles/app.css` (`.root`)."
    },
    {
      "id": "ICON-08",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-08",
      "text": "No fixed hex in a component rule.",
      "why": "a hex suits one theme; the roles track every theme for free.",
      "check": {
        "kind": "code",
        "text": "outside the `.root` token block, `app.css` holds no `#` hex. A test fails a severity or debug color that is not a state token."
      },
      "reference": "Editora `StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens`. Editora doesn't yet pass the whole check: `.breakpoint-marker`, `.exec-arrow`, `.view-mode-bar`, `.recent-remove`, `.personal-note-tooltip-content`, the fold-gutter markers and the default editor and Markdown preview palettes in `app.css` still carry fixed hexes."
    },
    {
      "id": "ICON-09",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-09",
      "text": "Readable text uses `-color-fg-muted` or stronger, which is 4.5:1 on the default, subtle and overlay grounds in both flagship themes.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a contrast test computes muted ink on each ground, and fails a readable selector set in `-color-fg-subtle`."
      },
      "reference": "Editora `StyleContrastTest.textThatMustBeReadUsesTheMutedRoleNotSubtle`."
    },
    {
      "id": "ICON-10",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-10",
      "text": "Tinted text (`-color-<role>-fg`) reaches 4.5:1 on its own subtle fill and on both grounds.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a contrast test computes each role's `-fg` on its `-subtle`, on `-color-bg-subtle` and on `-color-bg-default`, in both flagship themes."
      },
      "reference": "Editora `StyleContrastTest.lightTintedTextReachesAaOnItsOwnGroundAndOnTheSubtleSurface`, `darkTintedTextStaysAa`."
    },
    {
      "id": "ICON-11",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-11",
      "text": "Ink on an emphasis fill is `-color-fg-emphasis`, never white.",
      "why": "white on the dark accent is 1.68:1.",
      "check": {
        "kind": "test",
        "text": "a contrast test computes `-color-fg-emphasis` on each role's `-emphasis`, and the rules that paint on an emphasis fill use it."
      },
      "reference": "Editora `StyleContrastTest.inkOnAnEmphasisFillIsTheThemesOnEmphasisColour`."
    },
    {
      "id": "ICON-12",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-12",
      "text": "One focus ring, `-focus-ring: -color-accent-emphasis`, drawn by the `:focus-visible` block at the end of `app.css`, at 3:1 or better on every surface (see [Keyboard first](https://pauta-project.dev/2.0.1/keyboard/)).",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test reads `-focus-ring` from `.root` and computes it on the default, subtle, inset and overlay grounds."
      },
      "reference": "Editora `app.css` (*Keyboard focus*), `StyleContrastTest.theFocusRingIsAtLeastThreeToOneOnEverySurface`."
    },
    {
      "id": "ICON-13",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-13",
      "text": "A brand hue the theme has no role for (periwinkle, olive, violet) is a `ladder()` of `-color-bg-default`, never a fixed pair.",
      "why": "the old fixed light hexes read at 3.2:1 on Editora Dark.",
      "check": {
        "kind": "test",
        "text": "a contrast test resolves each ladder on every bundled theme's ground."
      },
      "reference": "Editora `app.css` (`-state-olive`, `-state-violet`, `-state-key`), `StyleContrastTest.theGitOliveAndVioletFollowTheAppThemesGround`."
    },
    {
      "id": "ICON-14",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "State colors",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-14",
      "text": "A pure test reads the stylesheets and does the WCAG arithmetic.",
      "why": "a contrast regression is invisible in a code diff.",
      "check": {
        "kind": "code",
        "text": "a test class reads the app's `.css` resources and computes contrast ratios without starting the toolkit."
      },
      "reference": "Editora `StyleContrastTest`. Mirada's `AccentTest` checks that the accent reads as text on both grounds; Termina's `ThemeTest` keeps every chromatic color of its terminal schemes legible."
    },
    {
      "id": "ICON-15",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Themes",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-15",
      "text": "The app has light and dark themes and switches between them at run time, without a restart (see [Window shell](https://pauta-project.dev/2.0.1/window-shell/)).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "picking a theme calls `Application.setUserAgentStylesheet` in the running app."
      },
      "reference": "Editora `ui/Themes.java` (`applyAppTheme`)."
    },
    {
      "id": "ICON-16",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Themes",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-16",
      "text": "A \"follow the system\" choice applies the light or dark theme to match the system's color scheme, and changes with it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the theme setting has a system value, and a listener on `Platform.getPreferences().colorSchemeProperty()` re-applies the theme."
      },
      "reference": "Mirada `settings/Settings.java` (`ThemeChoice.SYSTEM`), `ui/Theme.java`. Editora doesn't yet: its theme picker lists named themes only."
    },
    {
      "id": "ICON-17",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Themes",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-17",
      "text": "A theme name the app does not know falls back to the first-run default theme.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the lookup from a saved name to a theme ends in the default, not an exception."
      },
      "reference": "Editora `Themes.themeFor`, falling back to `Themes.DEFAULT` (Editora Light)."
    },
    {
      "id": "ICON-18",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Themes",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-18",
      "text": "Semantic colors never decorate: a theme may change the teal, the ground and the ink, but amber still means \"not durable yet\", red \"broken\" and green \"verified\".",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every rule that uses `-state-amber`, `-state-red` or `-state-green` marks one of the meanings in the State colors table."
      },
      "reference": "Editora `app.css`."
    },
    {
      "id": "ICON-19",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-19",
      "text": "A glyph node carries one family's style class, `icon-line` or `toolbar-icon`, never both.",
      "why": "a line glyph is colored by its stroke, and any `X .toolbar-icon` fill rule (there are dozens) would paint its outline solid. A glyph that moves family moves its CSS with it.",
      "check": {
        "kind": "test",
        "text": "a test builds every line glyph and fails when one also carries `toolbar-icon`."
      },
      "reference": "Editora `ui/Icons.java` (`line`, `of`), `MenuIconFamilyFxTest.aLineGlyphIsNeverAlsoTaggedAsAFilledOne`."
    },
    {
      "id": "ICON-20",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-20",
      "text": "The same action wears the same glyph wherever it is reached: Save is one floppy on the toolbar, in the File menu and in a tab's menu.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test compares the path data and style class of each action's glyph across the icon classes."
      },
      "reference": "Editora `ui/MenuBarIcons.java` reuses `Icons`; `editor/MenuIcons.java` (the editor package may not depend on `ui`) copies each twin's family and path data verbatim, held by `MenuIconFamilyFxTest.everySharedActionUsesTheSameGlyphInBothIconSets`."
    },
    {
      "id": "ICON-21",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-21",
      "text": "An icon-only control has a name: it is built through `Icons.button` or `Icons.toolbarButton`, which set the tooltip and the accessible text together (see [Keyboard first](https://pauta-project.dev/2.0.1/keyboard/)).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no icon-only `Button` is given a graphic outside those helpers without `Icons.name`."
      },
      "reference": "Editora `ui/Icons.java`. Editora doesn't yet pass the check on its main toolbar: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set only the tooltip (see [Toolbars and tooltips](https://pauta-project.dev/2.0.1/toolbars-and-tooltips/))."
    },
    {
      "id": "ICON-22",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-22",
      "text": "No invented glyph. A row gets an icon only where an existing glyph genuinely depicts it, and the icon column stays reserved so a menu with a mix stays aligned (see [Menus](https://pauta-project.dev/2.0.1/menus/)).",
      "why": "a picture that does not mean the thing beside it has to be read and then discounted.",
      "check": {
        "kind": "test",
        "text": "a test holds that a command with no fitting glyph maps to none."
      },
      "reference": "Editora `ui/MenuBarIcons.java`, `MenuBarIconsTest.aCommandWithNoFittingGlyphGetsNoneRatherThanAnInventedOne`."
    },
    {
      "id": "ICON-23",
      "level": "SHOULD",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-23",
      "text": "A file's icon comes from a pure function from file name to icon key, unit-tested without the toolkit, and any type it does not know gets the generic document glyph, so a new type never regresses the look.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a unit test resolves names to keys, an unknown one to the generic key."
      },
      "reference": "Editora `ui/FileIcons.java`: `iconKeyFor(name)` resolves the key, `forFileName` turns it into a node; brand logos from Simple Icons, category glyphs (image, archive, PDF, table, lock, JSON, settings) from Material. `FileIconsTest.unknownAndNullFallBackToGeneric`."
    },
    {
      "id": "ICON-24",
      "level": "MUST",
      "page": "icons-and-color",
      "pageTitle": "Icons and color",
      "section": "Icons",
      "url": "https://pauta-project.dev/2.0.1/icons-and-color/#icon-24",
      "text": "Every glyph set and font the app ships is credited in `NOTICE` with its license.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each icon source named in the icon classes and each family under `fonts/` has an entry in `NOTICE`."
      },
      "reference": "Editora `NOTICE`: Material Design Icons (Apache-2.0), Simple Icons (CC0; the logos stay their owners' trademarks), Inter and the monospace faces (OFL), and the glyph sets inside the bundled Symbols Nerd Font, Octicons and Seti UI (MIT) among them."
    },
    {
      "id": "TBAR-01",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-01",
      "text": "Every icon-only button has a name: one helper sets its tooltip and its accessible text from the same string.",
      "why": "a hand-rolled button gets the tooltip and forgets the name, which is how Editora once had seven copies of the helper drifting apart, and how a screen reader comes to announce \"button\".",
      "check": {
        "kind": "code",
        "text": "every icon-only `Button` is built by `Icons.button` or `Icons.toolbarButton`, or passed to `Icons.name`; none calls `setTooltip` without `setAccessibleText`."
      },
      "reference": "Editora `ui/Icons.java` (`button`, `toolbarButton`, `name`); Torrenta's copy of all three. nux sets both by hand on its \"?\" button for the same reason. Editora doesn't yet on its main toolbar: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set the tooltip only."
    },
    {
      "id": "TBAR-02",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-02",
      "text": "Toolbar buttons stay out of the Tab order: the command, the palette and the menus reach the action, and Tab is for the content. The [keyboard page](https://pauta-project.dev/2.0.1/keyboard/#focus-and-accessibility) has the general focus rules.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every button on a toolbar is built by `Icons.toolbarButton` or calls `setFocusTraversable(false)`."
      },
      "reference": "Editora `Icons.toolbarButton`, used by the tool window toolbars (Git, Diff, Markdown lint); Termina's search bar buttons; Mirada's header buttons. Editora doesn't yet on its main toolbar: the buttons built by `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton`, and the stripe buttons, take focus."
    },
    {
      "id": "TBAR-03",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-03",
      "text": "The tooltip names the command and its chord, read from the active keymap and never typed into a string: \"Save (C-x C-s)\". An unbound command shows its title alone.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the tooltip is built from the command's title and the keymap's display chord for its id, and is rebuilt when the keymap changes."
      },
      "reference": "Editora `WindowToolbar.setupButton` (`refreshToolbarTooltips`), `ToolbarCoordinator.buildExtraButton` and `ToolWindowManager.tooltipFor`; Torrenta's `toolbar.withChord`. Mirada's header buttons use the same \"label (key)\" form with the key written into the string."
    },
    {
      "id": "TBAR-04",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-04",
      "text": "Groups are separated by spacing, not rules: keep the `Separator` nodes (their padding is the gap) and make the line transparent.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the stylesheet sets `.tool-bar .separator:vertical > .line` to a transparent border."
      },
      "reference": "Editora `app.css`. Torrenta's separators still draw a line."
    },
    {
      "id": "TBAR-05",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-05",
      "text": "Hiding a button group (Simple mode, a build tool that is not detected) hides the leading, trailing and doubled separators it leaves, so no gap stands on its own, and shows them all again when nothing is hidden.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every change to a toolbar item's visibility ends in one pass over the bar's separators."
      },
      "reference": "Editora `WindowChromeCoordinator.collapseToolbarSeparators`."
    },
    {
      "id": "TBAR-06",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-06",
      "text": "One chrome band: the menu bar, the toolbar and the tab strip share `-color-bg-subtle` and draw no hairline between them; the breadcrumb, the bottom stripe and the status bar do the same at the bottom.",
      "why": "three rules within forty pixels read as clutter, not structure.",
      "check": {
        "kind": "by hand",
        "text": "look at the top and the bottom of a window in a light and a dark theme for a line between the bands."
      },
      "reference": "Editora `app.css` (`.menu-bar, .tool-bar`)."
    },
    {
      "id": "TBAR-07",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-07",
      "text": "A toggle looks on while it is on: a button that opens an overlay (Find, the palette, a split) and the Simple mode button carry the `:open` pseudo-class while their state holds, so the way back out does not look like the way in.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each such button sets a pseudo-class from its state, and the stylesheet gives that state a fill."
      },
      "reference": "Editora `MainController.OPEN`, `WindowChromeCoordinator` (Simple mode), `.button:open` in `app.css`. Torrenta uses `:on` for Simple mode and `:active` for the alternative speed limit."
    },
    {
      "id": "TBAR-08",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-08",
      "text": "The toolbar never holds the only way to an action: every icon in the customizable cluster is also in the menus and the palette.",
      "why": "that is what makes it safe to hide icons in a narrow window and to let the user remove them.",
      "check": {
        "kind": "code",
        "text": "every toolbar catalog item runs a registered command that a menu also lists."
      },
      "reference": "Editora `toolbar/ToolbarCatalog.java`: each item carries the `commandId` it runs; the only items without one are declared special widgets, such as the Recent menu button (`ToolbarCatalogTest`)."
    },
    {
      "id": "TBAR-09",
      "level": "MAY",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-09",
      "text": "The toolbar is customizable: the user reorders, removes and restores its buttons, and the layout is saved in Settings and shared by every window.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "FX tests drive customize mode, reorder and removal."
      },
      "reference": "Editora `ui/ToolbarCoordinator.java`, `ToolbarCustomizeModeFxTest`, `ToolbarCustomizationFxTest`. The cluster is a list of catalog ids in Settings (`toolbarLayout`), sanitized on read. The bar's right-click menu offers *Customize Toolbar…* (or *Done*), *Configure…* (the Settings page) and *Restore Default*. In customize mode the bar tints, buttons drag to reorder with an accent insertion line and drag off the bar to remove; Escape leaves the mode."
    },
    {
      "id": "TBAR-10",
      "level": "MUST",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-10",
      "text": "The bar's right-click menu is one menu, reused across right-clicks, so showing it again moves it, and it closes on a press anywhere, the toolbar included.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test right-clicks the bar twice and finds one menu, then presses on the bar and elsewhere in the window and finds it closed."
      },
      "reference": "Editora `ToolbarCoordinator`, `ContextMenuDismissal`, `ToolbarContextMenuDismissFxTest`. See [Menus](https://pauta-project.dev/2.0.1/menus/)."
    },
    {
      "id": "TBAR-11",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-11",
      "text": "The bar's right-click menu is the size of every other menu (14 px), not the bar's 18 px.",
      "why": "a popup inherits the font of the node it was shown from; the `.context-menu` rule that pins menus to 14 px is what keeps this one in line.",
      "check": {
        "kind": "test",
        "text": "an FX test opens the menu from the bar and reads its font size."
      },
      "reference": "Editora `app.css` (`.context-menu`), `ToolbarMenuFontFxTest`."
    },
    {
      "id": "TBAR-12",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-12",
      "text": "Tool window stripes are toolbars: a stripe button is built like a toolbar button, with the chord in its tooltip, accessible text bound to the window's title, and a right-click menu with *Open in Split* and *Hide*.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the stripe button's tooltip comes from the same title-and-chord format, and its `accessibleTextProperty` is bound to the tool window's title."
      },
      "reference": "Editora `ToolWindowManager.register`, `tooltipFor`."
    },
    {
      "id": "TBAR-13",
      "level": "SHOULD",
      "page": "toolbars-and-tooltips",
      "pageTitle": "Toolbars and tooltips",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/toolbars-and-tooltips/#tbar-13",
      "text": "The right stripe's first icon lines up with the editor's first line of text, not with the tab strip.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test compares the first stripe button's top with the editor's first line."
      },
      "reference": "Editora `ToolWindowStripeAlignmentFxTest`."
    },
    {
      "id": "TABS-01",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-01",
      "text": "Every tab operation is a command, so it can be bound to a chord, is in the palette and has a menu row: close, close others, close all, close unmodified, close to the left and right, pin, reopen closed, next and previous. The tab's [right-click menu](https://pauta-project.dev/2.0.1/menus/) lists the ones that act on a tab.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each operation has a registered command id, and `TabContextMenu` lists the per-tab ones."
      },
      "reference": "Editora `ui/WindowCommandRegistrar.java` (`buffer.close`, `buffer.closeOthers`, `buffer.closeAll`, `buffer.closeUnmodified`, `buffer.closeLeft`, `buffer.closeRight`, `buffer.togglePin`, `buffer.reopenClosed`, `buffer.next`), `ui/TabContextMenu.java`. Editora has no previous-tab command yet."
    },
    {
      "id": "TABS-02",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-02",
      "text": "The header is the title: the Tab's own text stays empty, and a graphic header carries the file-type glyph, the markers and the title in a `.tab-title` label. The tooltip is the full path.",
      "why": "the graphic is what makes the header a drag handle and lets each state set its own color.",
      "check": {
        "kind": "code",
        "text": "every editor tab gets `setText(\"\")` and a graphic with a `.tab-title` label; its tooltip is the file's path."
      },
      "reference": "Editora `ui/TabHeaders.java`."
    },
    {
      "id": "TABS-03",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-03",
      "text": "The one header carries the states: a `• ` prefix in amber italic for unsaved, a pin and bold for pinned, muted italic for read-only.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`app.css` styles `.tab-header.dirty`, `.tab-header.pinned` and `.tab-header.read-only` `.tab-title`, and the header sets those classes."
      },
      "reference": "Editora `ui/TabHeaders.java`, `app.css`; the Unsaved, Pinned and Read-only rows of the Spec table below."
    },
    {
      "id": "TABS-04",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-04",
      "text": "Bulk close skips pinned tabs: close others, close all, close unmodified and close to the left or right never close a pinned tab.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`closeOtherTabs`, `closeAllTabs`, `closeUnmodifiedTabs` and `eligibleToLeft` / `eligibleToRight` all filter on the pinned set."
      },
      "reference": "Editora `ui/MainController.java`."
    },
    {
      "id": "TABS-05",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-05",
      "text": "Pinning moves the tab to the end of the pinned group, unpinning to just after it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`togglePin` calls `moveToPinBoundary`."
      },
      "reference": "Editora `ui/MainController.java` (`togglePin`), `ui/EditorArea.java` (`moveToPinBoundary`)."
    },
    {
      "id": "TABS-06",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-06",
      "text": "Reopen Closed Tab brings back the files whose tabs this window closed, newest first, bounded to twenty, a file listed once, with the caret where it was. In a terminal app the *tab* comes back (its shells, their directories, the pane arrangement, the names the user gave them, its place in the strip) and not the scrollback.",
      "why": "the process is gone, and pretending otherwise would be worse than saying so.",
      "check": {
        "kind": "test",
        "text": "a unit test over the closed-tab list holds the order, the bound, the single entry per file and the caret."
      },
      "reference": "Editora `ui/ClosedTabs.java`, `ClosedTabsTest`; `C-S-t` in the CUA keymap. Termina `ui/ClosedTabs.java`, on `Ctrl+Shift+Z` (`Cmd+Z` on macOS)."
    },
    {
      "id": "TABS-07",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-07",
      "text": "Tabs reorder by dragging, with the feedback shown above: the dragged header dimmed and an accent line on the edge where it will land.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "drag a tab along the strip and watch the landing edge."
      },
      "reference": "Editora `TabHeaders.enableTabDrag`; Termina `installTabDrag` and the pure `TabReorder.insertIndex`. In Termina a double-click on a tab renames it, and a pane dragged onto a tab joins it (the whole header outlined, `tab-drop-into`)."
    },
    {
      "id": "TABS-08",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-08",
      "text": "A tab shows its file's Git status in the Project tree's colors: modified accent, added green, untracked olive, renamed violet, deleted muted, conflict red. A read-only tab still shows it; an unsaved one shows amber.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test gives a changed file the same style class the Project tree uses."
      },
      "reference": "Editora `ui/TabGitStatus.java`, `TabGitStatusTest`."
    },
    {
      "id": "TABS-09",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-09",
      "text": "A switcher lists the open files in tab order: `C-x C-b` (Emacs) opens it, `C-n` / `C-p` or the arrows move, Enter or releasing Ctrl activates, `C-g` or Esc cancels, `C-d` or Backspace closes the highlighted file. Its width is fixed to the longest path on each open, so it never resizes while you move.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open it with several tabs and move through it; the list keeps its width."
      },
      "reference": "Editora `ui/Switcher.java`, `SwitcherFxTest`."
    },
    {
      "id": "TABS-10",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-10",
      "text": "The window title names the file, the project and the app, with a `●` prefix for an unsaved file.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the code that sets the stage title adds all three and the marker."
      },
      "reference": "Editora `MainController.updateWindowTitle`."
    },
    {
      "id": "TABS-11",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-11",
      "text": "Tabs sit in the title bar through JavaFX 27's `HeaderBar`; see [Window shell](https://pauta-project.dev/2.0.1/window-shell/).",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "the tab strip shares the title bar's row."
      },
      "reference": "Termina `ui/TerminalWindow.java`."
    },
    {
      "id": "TABS-12",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tabs",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-12",
      "text": "A command hides the tab bar.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a registered command toggles the tab header."
      },
      "reference": "Editora `view.toggleTabBar`, `.tab-pane.no-tab-header` in `app.css`."
    },
    {
      "id": "TABS-13",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-13",
      "text": "A command toggles each panel (`tool.<id>`: `M-1` … `M-0` in the Emacs keymap for ten of them), and the stripe button is the same command with a glyph.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every tool window registers a `tool.<id>` command, and its stripe button runs it."
      },
      "reference": "Editora `ui/ToolWindowManager.java`, `keymaps/emacs.json`."
    },
    {
      "id": "TABS-14",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-14",
      "text": "A panel's content is built on first use.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test holds that no closed tool window builds its panel before the first paint."
      },
      "reference": "Editora `LazyToolWindowsFxTest`."
    },
    {
      "id": "TABS-15",
      "level": "MUST",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-15",
      "text": "Panel state is restored: which windows are open, on which side, in what order, hidden or shown, floating, and every divider position go to `workspace-state.json` and come back on the next launch.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the workspace state holds each of those, and the manager reads them back at startup."
      },
      "reference": "Editora `ui/ToolWindowManager.java`, `config/WorkspaceState.java`."
    },
    {
      "id": "TABS-16",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-16",
      "text": "Panels dock on three sides, left, right and bottom, and a side holds at most two windows stacked (Project over Structure, two consoles along the bottom).",
      "why": "past that a side stops being a dock and becomes a list of slivers.",
      "check": {
        "kind": "code",
        "text": "the sides are an enum of three and the per-side limit is two."
      },
      "reference": "Editora `ToolWindow.Side`, `ToolWindowManager.MAX_PER_SIDE`."
    },
    {
      "id": "TABS-17",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-17",
      "text": "A panel re-docks by dragging its stripe button to another stripe, with the same dim-and-accent-line feedback as a tab; an empty stripe appears as a dashed accent drop zone for the duration of the drag.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "drag a stripe button to the opposite side."
      },
      "reference": "Editora `ui/ToolWindowDock.java`, `ToolWindowVisibilityTest` (an empty stripe shows while dragging)."
    },
    {
      "id": "TABS-18",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-18",
      "text": "Panels float, maximize, resize and close from the keyboard, and at most one window is maximized at a time.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the commands are registered and bound in the Emacs keymap."
      },
      "reference": "Editora `view.floatToolWindow`, `view.maximizeToolWindow` (`C-x f`), `view.closeFocusedToolWindow` (`C-x 0`), the resize commands (`C-x S-.`, `C-x S-,`, `C-x S-6`)."
    },
    {
      "id": "TABS-19",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-19",
      "text": "Closing the panel that holds keyboard focus returns focus to where it was in the editor.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the manager keeps the last editor focus owner and refocuses it on close."
      },
      "reference": "Editora `ToolWindowManager.focusEditor`, a weak reference to the last editor focus owner."
    },
    {
      "id": "TABS-20",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-20",
      "text": "Hidden is not unavailable: the user's show/hide choice for a stripe button is kept apart from a context-driven hide (the Commit window outside a Git repository), so the second never clobbers the first.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a unit test holds that a button shows only when visible and available."
      },
      "reference": "Editora `ui/ToolWindowVisibility.java`, `ToolWindowVisibilityTest`."
    },
    {
      "id": "TABS-21",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-21",
      "text": "A bottom window that is unusable at the default height asks for more on its first open; the user's own size wins afterwards.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test opens an output window taller while the others keep the side's size."
      },
      "reference": "Editora `ToolWindow.setFirstOpenShare`, `ToolWindowFirstOpenShareTest`."
    },
    {
      "id": "TABS-22",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-22",
      "text": "A stripe button badges a spinner while its window has something under way.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test badges a busy window's stripe button without changing its size."
      },
      "reference": "Editora `ToolWindow.busy`, `ToolWindowManagerFxTest`."
    },
    {
      "id": "TABS-23",
      "level": "SHOULD",
      "page": "tabs-and-panels",
      "pageTitle": "Tabs and tool panels",
      "section": "Tool panels",
      "url": "https://pauta-project.dev/2.0.1/tabs-and-panels/#tabs-23",
      "text": "Panels follow the active document where they should: the Git UI follows the active tab's repository, the status bar's environment segment the active `.http` file, Local History the file whose tab menu opened it.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "switch between tabs from two repositories with the Git window open."
      },
      "reference": "Editora `ui/GitPathScope.java`."
    },
    {
      "id": "MENU-01",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "The menu bar",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-01",
      "text": "Every menu-bar item is a command from the registry, with its title from `command.<id>`, its chord from the active keymap and its enabled state from the command's gate. The bar assembles and refreshes; it holds no behavior of its own.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the bar's model lists command ids only, and every row runs its id through the registry."
      },
      "reference": "Editora `ui/MenuBarModel.java` over `command/CommandRegistry.java`, `ui/MainMenuBar.java`."
    },
    {
      "id": "MENU-02",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "The menu bar",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-02",
      "text": "Menu-bar rows use no `KeyCombination` accelerators. In the in-window bar each row is a `CustomMenuItem` laying out icon, title, spacer and chord. On the macOS system menu bar (`useSystemMenuBar`) the chord is appended to the title and rows carry no icon.",
      "why": "Emacs chords are multi-key, which a `KeyCombination` cannot express, and on macOS an accelerator would bypass the key dispatcher. The native macOS menu draws text only and no graphics, which is also the platform's convention.",
      "check": {
        "kind": "code",
        "text": "no `setAccelerator` in the menu-bar classes."
      },
      "reference": "Editora `ui/MainMenuBar.java` (`rowContent`, `refresh`)."
    },
    {
      "id": "MENU-03",
      "level": "SHOULD",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "The menu bar",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-03",
      "text": "Enablement is re-read every time a menu opens, and titles and chords on a keymap or locale change.",
      "why": "a menu built before Git finished detecting a repository must not stay grayed out.",
      "check": {
        "kind": "test",
        "text": "an FX test detects a repository after the window is built and finds the menu enabled."
      },
      "reference": "Editora `MainMenuBar.refreshEnablement`, `MenuBarEnablementFxTest`."
    },
    {
      "id": "MENU-04",
      "level": "SHOULD",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "The menu bar",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-04",
      "text": "Simple mode shows a shorter menu, rebuilt only when the mode actually changes.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the bar rebuilds only when the simple flag differs from the current one."
      },
      "reference": "Editora `MainMenuBar.setSimple`, `MenuBarModel.menus(simple)`."
    },
    {
      "id": "MENU-05",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-05",
      "text": "Every list row, tree row, tab, editor and read-only console has a right-click menu with the actions for *that* thing, each one a command.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "right-click each kind of thing; every row's action is also in the palette."
      },
      "reference": "Editora `ui/TabContextMenu.java`, `ui/RowContextMenu.java`, `ui/ConsoleContextMenu.java`."
    },
    {
      "id": "MENU-06",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-06",
      "text": "One right-click menu at a time: a right-click while a menu is open replaces it, and the first one closes before the second shows.",
      "why": "JavaFX stacks a second menu beside the first when each row owns its own `ContextMenu`, and the stale one is then no longer dismissible.",
      "check": {
        "kind": "test",
        "text": "an FX test right-clicks another row with a menu open and finds one menu showing."
      },
      "reference": "Editora `ui/ContextMenuDismissal.java` closes every open right-click menu on the press that opens the next (`ContextMenuDismissalFxTest`); Modula's `RadioPane` hides the previous menu before showing a new one; Termina keeps one menu per view and shows it again."
    },
    {
      "id": "MENU-07",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-07",
      "text": "A press anywhere outside a right-click menu closes it, including inside the control the menu was opened on. The press is not consumed: a click in a list still selects the row, and a right-click on another row opens that row's menu straight away. Drop-downs opened by a plain click (menu buttons, choice boxes, the menu bar) keep the stock behavior, and a menu that turned auto-hide off is left alone.",
      "why": "JavaFX's auto-hide deliberately ignores a press on the menu's *owner node*, so a stock menu on a tree or a text area stays open when the user clicks another row or the text.",
      "check": {
        "kind": "test",
        "text": "an FX test clicks inside the owner control and in another window, and the menu closes."
      },
      "reference": "Editora `ContextMenuDismissal.install()`, called once in `App` at startup for every current and future window; `ContextMenuDismissalFxTest`."
    },
    {
      "id": "MENU-08",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-08",
      "text": "Escape closes a right-click menu and focus goes back where it was. In a terminal the Escape does not reach the shell.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open a menu, press Escape, and type: the keys reach the control that had focus."
      },
      "reference": "the stock `ContextMenu` hide-on-Escape (Spec below); Termina's `onKeyPressed` filter hides the menu and consumes the key (`TerminalView`)."
    },
    {
      "id": "MENU-09",
      "level": "MUST",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-09",
      "text": "The Menu key and <kbd>Shift+F10</kbd> open the selected row's menu, scrolled into view first, so every row action a mouse can reach the keyboard can too.",
      "why": "those keys arrive at the focused control, not at a row's cell, so a menu installed on cells never saw them.",
      "check": {
        "kind": "test",
        "text": "an FX test sends a keyboard request to a tree and a list and finds the selected row's menu, anchored to that row."
      },
      "reference": "Editora `RowContextMenu.install(tree)`, `RowContextMenuFxTest`."
    },
    {
      "id": "MENU-10",
      "level": "SHOULD",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-10",
      "text": "A right-click selects first. In an editor, a right-click outside every selection moves the caret to the click (so Paste lands there); inside a selection it keeps carets and selections (so Cut and Copy act on what was clicked). From the keyboard the target is the caret. In a list, the menu is the clicked row's.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "select a word, right-click elsewhere and paste; then right-click inside a selection and copy."
      },
      "reference": "Editora `editor/ContextMenuTarget.java`."
    },
    {
      "id": "MENU-11",
      "level": "SHOULD",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-11",
      "text": "A menu attached to something that exists once per open file is built when first shown, and set up for each showing: an `onShowing` handler sets the labels, enablement and visibility for *this* showing, then collapses the separators.",
      "why": "such a menu is built for every file and opened for almost none.",
      "check": {
        "kind": "code",
        "text": "per-file menus are created through `LazyContextMenu.of(build)`."
      },
      "reference": "Editora `ui/LazyContextMenu.java`, `LazyContextMenuFxTest`. A read-only console's menu is just Select All and Copy, both disabled while it is empty (`ConsoleContextMenu`)."
    },
    {
      "id": "MENU-12",
      "level": "SHOULD",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-12",
      "text": "A destructive row carries the `danger` class. The action follows the [window shell](https://pauta-project.dev/2.0.1/window-shell/) rule: it asks first with a button that names it, or is undoable.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "rows that delete, discard or reset add `danger` to their style classes."
      },
      "reference": "Editora `.menu-item.danger` in `app.css`, `ui/BranchPopup.java`."
    },
    {
      "id": "MENU-13",
      "level": "MAY",
      "page": "menus",
      "pageTitle": "Menus",
      "section": "Right-click menus",
      "url": "https://pauta-project.dev/2.0.1/menus/#menu-13",
      "text": "In a terminal view, a program that grabbed the mouse owns the right-click; <kbd>Shift</kbd>+right-click always opens the menu, and the keyboard request is never contested.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a pure test of when the menu shows, per mouse mode, Shift and trigger."
      },
      "reference": "Termina's `TerminalView.shouldShowMenu`, `ContextMenuContentionTest`."
    },
    {
      "id": "TRAY-01",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "The icon and its menu",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-01",
      "text": "The tray comes from the shared `tray/` package: a StatusNotifierItem on Linux, AWT's `SystemTray` on Windows and macOS, created off the FX thread after the first frame.",
      "why": "D-Bus and AWT can block, and neither is worth a stalled first frame.",
      "check": {
        "kind": "code",
        "text": "`Trays.create` picks `SniTray` on Linux and `AwtTray` elsewhere, and the window calls it from a background thread."
      },
      "reference": "Torrenta `tray/Trays.java`, `MainWindow.installTray`; the Spec table below."
    },
    {
      "id": "TRAY-02",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-02",
      "text": "The app is fully usable without a tray. No icon is a normal outcome (stock GNOME has no StatusNotifier host), not an error, and the reason is said where the person will look.",
      "why": "the bug they actually hit is silence: the box says close to tray, and closing quits.",
      "check": {
        "kind": "code",
        "text": "when the tray attempt returns no tray, the status bar says why and that closing quits."
      },
      "reference": "Torrenta `MainWindow.installTray` (\"No tray icon (…); closing the window quits Torrenta\", `status.noTray`); Modula's status says closing the window will quit it (`RadioPane.reportNoTray`)."
    },
    {
      "id": "TRAY-03",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-03",
      "text": "Closing the window hides it only while an icon is actually up and the setting says so, both read at close time; otherwise a close quits. `Platform.setImplicitExit(false)` is set only once a tray exists, and turning the tray off brings a hidden window back.",
      "why": "the checkbox can change while the window is open, and hiding a window that leaves no icon behind is how a program becomes unreachable.",
      "check": {
        "kind": "code",
        "text": "the close handler tests that a tray exists and reads the live setting; `setImplicitExit(false)` sits after the tray is created."
      },
      "reference": "Torrenta `MainWindow.setOnCloseRequest`, Modula's `installCloseBehaviour`, nux's `TrayController.closeHidesWindow` and `updateImplicitExit`."
    },
    {
      "id": "TRAY-04",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-04",
      "text": "Quit is explicit and one path: the tray's Quit, File → Quit and the system's Quit all run the same method, which closes open dialogs first and saves the window geometry.",
      "why": "quitting from inside a nested event loop aborted the JVM.",
      "check": {
        "kind": "code",
        "text": "every quit entry point calls the one quit method."
      },
      "reference": "Torrenta `MainWindow.quit`."
    },
    {
      "id": "TRAY-05",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-05",
      "text": "`--minimized` comes up behind the icon. The window is never shown until the tray attempt has answered; if no icon comes, the window is shown after all. With the tray setting off, Torrenta starts minimized instead and nux ignores the flag.",
      "why": "a start at login can then never leave a program with no way back.",
      "check": {
        "kind": "code",
        "text": "a `--minimized` start shows the window when the tray attempt returns none."
      },
      "reference": "Torrenta `MainWindow.show`, nux's `App`."
    },
    {
      "id": "TRAY-06",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-06",
      "text": "Start at login writes the OS's own entry, and nothing else: an XDG autostart entry in `~/.config/autostart` (quoted `Exec`, `StartupWMClass` matching the installed launcher, `X-KDE-autostart-after=panel` so a tray host is up first), a LaunchAgent in `~/Library/LaunchAgents`, the `HKCU\\…\\Run` value on Windows (read together with `StartupApproved`, where Task Manager keeps the person's \"off\"). The entry is the one truth: turned off in GNOME Tweaks, KDE's Autostart page or Task Manager, the box shows unticked. The one setting beside it is *start behind the tray icon*, written into the entry as `--minimized`.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a pure test of the exact bytes of each platform's entry."
      },
      "reference": "Torrenta `os/Autostart.java`, `os/AutostartSpec.java`, `AutostartSpecTest`; nux's design."
    },
    {
      "id": "TRAY-07",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-07",
      "text": "Only the app writes the login entry, and only from an installed package: the installers never do it, and a run from source says it has nothing to start.",
      "why": "an installer runs for every account.",
      "check": {
        "kind": "code",
        "text": "the entry's target comes from `jpackage.app-path`, and is absent when it is unset."
      },
      "reference": "Torrenta `os/Autostart.java`."
    },
    {
      "id": "TRAY-08",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-08",
      "text": "Every start-at-login call runs off the FX thread.",
      "why": "it may block on the file system or `reg.exe`.",
      "check": {
        "kind": "code",
        "text": "every `Autostart` read and write starts on a worker thread."
      },
      "reference": "Torrenta `SettingsWindow` (`autostart-read`, `autostart-write`) and `MainWindow` (`autostart-refresh`); nux's `App` (`nux-autostart`)."
    },
    {
      "id": "TRAY-09",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-09",
      "text": "Desktop notifications go through one `Notifier`: `notify-send` on Linux (nux and Termina fall back to `gdbus` against the freedesktop service), `osascript` with `display notification` on macOS, a PowerShell toast on Windows. Each is a short program run with the title and message as arguments, never as part of a script, off the FX thread and bounded to a few seconds; a failure is logged and never breaks the app.",
      "why": "text from a torrent name or a remote shell then cannot run anything.",
      "check": {
        "kind": "test",
        "text": "a test holds that each platform's command line passes the text as arguments and that a missing program is a problem, not an exception."
      },
      "reference": "Torrenta `automation/Notifiers.java`, `ProcessNotifier`, `NotifierTest` (it ships `toast.ps1`); nux's `service/Notifier` raises it through the tray icon, which it keeps as the last resort on every platform; Termina's `DesktopNotifier`."
    },
    {
      "id": "TRAY-10",
      "level": "MUST",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-10",
      "text": "Notifications are for what happened while the window was away, with one switch per event and few on by default.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each notified event has its own setting, and most default to off."
      },
      "reference": "Torrenta notifies on added, finished, seeding done, error and updated, with only *finished* on at first, and a Test button in Settings shows one now (`automation/AutomationSettings.java`); nux notifies on power events with a rule per UPS; Termina and Editora relay a program's own OSC 9 and OSC 777 notifications."
    },
    {
      "id": "TRAY-11",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-11",
      "text": "A notification is never the only place a state is said: the in-app status already shows it.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "trigger each notified event with notifications off; the window still shows it."
      },
      "reference": "Torrenta's status bar and transfer list."
    },
    {
      "id": "TRAY-12",
      "level": "MAY",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-12",
      "text": "A dock badge: Torrenta puts the download rate on the macOS dock icon through AWT's `Taskbar` and a count on a Linux launcher that honors Unity's `LauncherEntry` signal (KDE, Dash to Dock); nothing on Windows, whose taskbar badges only AWT's own windows. It is cleared when nothing downloads and has its own switch.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a pure test of the badge state."
      },
      "reference": "Torrenta `os/Badges.java`, `BadgeState`, `BadgeStateTest`."
    },
    {
      "id": "TRAY-13",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-13",
      "text": "A second launch brings the hidden window forward: the [single-instance hand-off](https://pauta-project.dev/2.0.1/command-line/) shows a window hidden to the tray before it opens what it was given.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "close to the tray, then launch the app again with a file."
      },
      "reference": "Torrenta `MainWindow.showFromTray`."
    },
    {
      "id": "TRAY-14",
      "level": "SHOULD",
      "page": "tray-and-background",
      "pageTitle": "Tray and background",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/tray-and-background/#tray-14",
      "text": "AWT stays headless unless the tray needs it. Linux never needs it; Windows and macOS lift the guard only when the tray setting is on, decided in `main`. A tray turned on later says \"restart to show the tray icon\" rather than \"unsupported\".",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test holds that AWT is headful only where the tray is AWT's and wanted."
      },
      "reference": "Torrenta `Trays.usesAwt`, `os.AwtUse`, `TraysTest`."
    },
    {
      "id": "SET-01",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "The Settings window",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-01",
      "text": "The Settings window opens from a palette command, bound to `Ctrl+,` (`Cmd+,` on macOS) in the CUA keymap.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a registered command opens Settings, and `cua.json` and `cua.mac.json` bind it."
      },
      "reference": "Editora `view.settings`, bound in `keymaps/cua.json` and `cua.mac.json` (and in the VS Code and Sublime keymaps; IntelliJ's uses `C-M-s`)."
    },
    {
      "id": "SET-02",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "The Settings window",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-02",
      "text": "The window has a sidebar of pages with icons on the left, the page on the right, and a search field on top.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open Settings; the search field sits above the sidebar and the page."
      },
      "reference": "Editora `ui/SettingsWindow.java`, `ui/SettingsSidebarNav.java`, `ui/SettingsIcons.java`."
    },
    {
      "id": "SET-03",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "The Settings window",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-03",
      "text": "Search finds a row by its title, description, visible text, its card or section heading, its page name and English keywords. Title hits rank above description hits; whole words above word starts. The page with the best match opens, and every non-matching row, heading and card is hidden.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a unit test ranks a title hit above a keyword hit and a whole word above part of one."
      },
      "reference": "Editora `ui/SettingsSearch.java`, `SettingsSearchTest`."
    },
    {
      "id": "SET-04",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "The Settings window",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-04",
      "text": "Settings apply live, with no Save button. Text fields commit on Enter or focus loss; invalid values are marked and never committed.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no Save or Apply button in the window; text fields commit through `commitOnEnterOrBlur`."
      },
      "reference": "Editora `SettingsWindow.commitOnEnterOrBlur`; `SettingsSyncPage`'s branch field marks an invalid branch."
    },
    {
      "id": "SET-05",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "The Settings window",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-05",
      "text": "A change made in one window reaches every other open window.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an FX test changes a setting in one window and finds it applied in the other."
      },
      "reference": "Editora: every window holds the same `config/SharedConfig.java`, which announces each change (`onSettingsChanged`); `CrossWindowSettingsFxTest`."
    },
    {
      "id": "SET-06",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Adding a setting touches five places",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-06",
      "text": "Every setting has a palette command that flips the field or prompts for its value.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "for each row in Settings, find a palette command that changes it."
      },
      "reference": "Editora's `view.toggle…` and picker commands (`ui/WindowCommandRegistrar.java`). Editora does not have one for every setting yet: `terminalNotifications`, for one, is only a Settings row."
    },
    {
      "id": "SET-07",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-07",
      "text": "Config lives in `~/.<app>`: `~/.<app>-dev` for `--dev`, any folder via `--config-dir` or `<APP>_CONFIG_DIR`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "one resolver picks the folder, in the order `--config-dir`, the environment variable, the default."
      },
      "reference": "Editora `App` and `ConfigManager.configDirFor`, `ConfigDirTest`."
    },
    {
      "id": "SET-08",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-08",
      "text": "`settings.json` holds preferences, `workspace-state.json` session state, and other stores their own JSON files.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the config folder's file names are constants in the config package."
      },
      "reference": "Editora `config/ConfigManager.java`, `config/WorkspaceState.java`."
    },
    {
      "id": "SET-09",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-09",
      "text": "Every versioned file has a `SCHEMA_VERSION` and a `v → v+1` migration step. A purely additive field uses an identity step.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each store declares `SCHEMA_VERSION`, and the migrations have one step per version."
      },
      "reference": "Editora `config/migration/ConfigMigrations.java`, `ConfigSchema.java`, `ConfigMigrationsTest`."
    },
    {
      "id": "SET-10",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-10",
      "text": "A file newer than the running build is backed up to `<name>.v<n>.bak` and defaults load.",
      "why": "an older build never clobbers a newer config.",
      "check": {
        "kind": "test",
        "text": "a test loads a too-new `settings.json` and finds the backup and the defaults."
      },
      "reference": "Editora `ConfigVersioningTest` (`tooNewSettingsAreBackedUpAndDefaultsLoaded`)."
    },
    {
      "id": "SET-11",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-11",
      "text": "Never trust a config file. Clamp every value to its valid range when it is **read**, not only when it is written; an unknown value falls back to its default; a file that cannot be decoded is kept as `<name>.corrupt.bak` and defaults load. A bad file never stops the app from starting.",
      "why": "config is plain JSON (or properties) and people edit it by hand. A hand-edited two-million-line scrollback must not exhaust memory at the next launch (Termina).",
      "check": {
        "kind": "test",
        "text": "a test loads out-of-range numbers and an unparseable file."
      },
      "reference": "Editora `ConfigLoadProblemsTest` (`outOfRangeNumbersAreClampedOnLoad`, `anUnparseableFileIsReportedWithItsBackup`)."
    },
    {
      "id": "SET-12",
      "level": "MUST",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Config folder and schema",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-12",
      "text": "Export configuration writes a timestamped `.zip` of the config folder; Import restores from one.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "tests over the zip's name and contents, and an import that replaces only the ticked parts."
      },
      "reference": "Editora `config/ConfigExporter.java`, `config/ConfigImport.java`, `ConfigExporterTest`, `ConfigImportTest`."
    },
    {
      "id": "SET-13",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Secrets stay out of files",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-13",
      "text": "No secret goes in a config file. API keys and tokens go to the operating system's keychain: macOS Keychain, Windows Credential Manager, the Secret Service on Linux. Calls may block on a prompt, so they run off the FX thread.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no key or token field in the settings model; reads and writes go through the secret store."
      },
      "reference": "Editora `secrets/SecretStore.java`."
    },
    {
      "id": "SET-14",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Secrets stay out of files",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-14",
      "text": "A credential the app can ask for again lives in memory for the session only and is never written. Work that needs it waits until the user has signed in this session; do not \"fix\" that by storing the password.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the credential is a field of a runtime object, absent from every config class."
      },
      "reference": "nux's UPS login (`app/CommandRunner.java`)."
    },
    {
      "id": "SET-15",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Secrets stay out of files",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-15",
      "text": "A secret in the wrong place is refused. A repository URL with a password or token in it is refused, with the fix ([Settings Sync](https://pauta-project.dev/2.0.1/templates/settings-sync/)); a problem report redacts tokens, hosts and home paths before anyone sees it ([Diagnostics](https://pauta-project.dev/2.0.1/diagnostics/)).",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "paste `https://user:token@host/repo.git` as the sync repository."
      },
      "reference": "Editora `ui/SettingsSyncPage.java` (`settings.sync.repo.credentials`)."
    },
    {
      "id": "SET-16",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Secrets stay out of files",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-16",
      "text": "An option that weakens security has no UI: it exists only as a key in the config file, so nobody turns it on by clicking.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "no Settings row or command writes such a key."
      },
      "reference": "nux's trust-all TLS (`tlsTrustAll` in `config/Config.java`)."
    },
    {
      "id": "SET-17",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Settings Sync (Git / GitHub)",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-17",
      "text": "Settings, keybindings and user data can sync, optionally, through a Git repository the user owns.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "set up Sync on two machines and change a setting on one."
      },
      "reference": "Editora `sync/SyncEngine.java`, `docs/subsystems/settings-sync.md`. Editora syncs key bindings and user data (snippets, abbreviations, templates, the dictionary), not the rest of `settings.json`; Torrenta syncs its settings file (`sync/SyncEngine.java`)."
    },
    {
      "id": "SET-18",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Settings Sync (Git / GitHub)",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-18",
      "text": "Setup is by pasting a repo URL, or **Create on GitHub** through the `gh` CLI. The account that can read the repo is pinned per clone, so machines with two GitHub accounts work.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test remembers the first account that can read the repository and uses it without asking again."
      },
      "reference": "Editora `sync/SyncAccount.java`, `SyncAccountTest`, `ui/SettingsSyncPage.java`."
    },
    {
      "id": "SET-19",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Settings Sync (Git / GitHub)",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-19",
      "text": "Sync runs automatically (on change and at start) and on demand. Machine-local keys (window size, paths) never sync.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "one pure class decides which keys or files travel, and machine-local ones are not among them."
      },
      "reference": "Editora `ui/SettingsSync.java` (after startup, after a local change, on an interval, and `sync.now`), `sync/SyncCategory.java`; Torrenta `sync/SyncKeys.java`."
    },
    {
      "id": "SET-20",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Settings Sync (Git / GitHub)",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-20",
      "text": "On a same-entry conflict *this machine wins*, and a backup is taken before any sync that replaces local files.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a merge test where both sides changed one entry keeps this machine's."
      },
      "reference": "Editora `sync/SyncMerge.java`, `SyncMergeTest`."
    },
    {
      "id": "SET-21",
      "level": "SHOULD",
      "page": "settings",
      "pageTitle": "Settings",
      "section": "Settings Sync (Git / GitHub)",
      "url": "https://pauta-project.dev/2.0.1/settings/#set-21",
      "text": "Sync status shows as a pill in Settings and as echo messages; failures go to the Message Log.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "point Sync at a repository that does not exist and read the pill and the log."
      },
      "reference": "Editora `ui/SettingsSyncPage.java`, `SyncStatus`."
    },
    {
      "id": "DIAG-01",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-01",
      "text": "The **Message Log** is a session-only, bounded history of every echo-area message with `HH:mm:ss` times, newest first. Clicking the status message opens it; Esc closes it; Clear empties it.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test records messages newest first, evicts the oldest past the cap, and clears."
      },
      "reference": "Editora `ui/MessageLog.java` (`MessageLogTest`), `ui/MessageLogPopup.java`."
    },
    {
      "id": "DIAG-02",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-02",
      "text": "The **Debug Log** captures all `java.util.logging` records and uncaught exceptions in memory (bounded) **and** mirrors them to `<app>-session.log` in the config folder, keeping the previous one as `<app>-session.prev.log` so a crash is still visible next launch.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "tests bound the buffer and find the session file written and the previous one kept."
      },
      "reference": "Editora `ui/DebugLog.java` (`DebugLogTest`, `DebugLogSessionFileTest`)."
    },
    {
      "id": "DIAG-03",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-03",
      "text": "The Debug Log opens in a modeless window with Refresh, Copy, Clear, Export and Report a Problem.",
      "why": "it is the only way to see logs in a packaged build.",
      "check": {
        "kind": "by hand",
        "text": "open the Debug Log and keep working in the main window while it is open."
      },
      "reference": "Editora `ui/DebugLogWindow.java`."
    },
    {
      "id": "DIAG-04",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-04",
      "text": "An **uncaught exception handler** is installed at the start of `main`, before the toolkit starts, and routes to the Debug Log and an echo message. Never a stack trace dialog.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`main` calls the install method before any argument handling or `launch`, and the handler shows no dialog."
      },
      "reference": "Editora `DebugLog.install()`. Editora, Torrenta and Termina log the exception but do not yet post an echo message."
    },
    {
      "id": "DIAG-05",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-05",
      "text": "The **update notification** reads GitHub `/releases/latest` once per app session (not per window), at most once a day, a few seconds after the first frame. A newer version shows a status-bar notice and a line in About; \"Check for Updates\" runs it by hand; Settings has an off switch. It never downloads or installs by itself.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test waits for the first paint and the delay, then checks once a session and not when off or not due."
      },
      "reference": "Editora `update/UpdateCheck.java`, `ui/UpdateCheckScheduler.java` (`UpdateCheckSchedulerTest`), `ui/UpdateCoordinator.java`."
    },
    {
      "id": "DIAG-06",
      "level": "MUST",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-06",
      "text": "Help → **Report a Problem** builds a report (version, OS, runtime, settings summary, recent Debug Log), **redacts** it (home paths, user names, e-mail addresses, credentials, tokens), shows it editable, copies it to the clipboard and opens a prefilled GitHub issue from `bug_report.yml`. Over about 7,500 characters the link falls back to \"paste from the clipboard\". `<app> --report` does the same from the command line for when the app cannot start. Nothing is uploaded.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "redaction tests cover home paths, user names, e-mail addresses, credentials in URLs and tokens; a report test puts a short report in the link and leaves the paste hint for a long one."
      },
      "reference": "Editora `report/ProblemReport.java`, `report/Redactor.java`, `report/ReportCommand.java`, `ui/ReportProblemWindow.java` (`RedactorTest`, `ProblemReportTest`)."
    },
    {
      "id": "DIAG-07",
      "level": "SHOULD",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-07",
      "text": "A **Doctor** page checks the environment (external tools, versions, permissions, paths), with a status per row and a fix or link for each failure.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open the Doctor with a tool missing and find its row failed, with what to install."
      },
      "reference": "Editora `doctor/*`, `ui/DoctorPane.java`."
    },
    {
      "id": "DIAG-08",
      "level": "SHOULD",
      "page": "diagnostics",
      "pageTitle": "Diagnostics and support",
      "section": null,
      "url": "https://pauta-project.dev/2.0.1/diagnostics/#diag-08",
      "text": "An app with user documents snapshots unsaved work off the FX thread and offers it back after a crash.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test finds an abandoned session's snapshots and offers them to the first window only."
      },
      "reference": "Editora `recovery/RecoveryService.java` (`RecoveryServiceTest`, `CrashRecoveryFxTest`)."
    },
    {
      "id": "CLI-01",
      "level": "MUST",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-01",
      "text": "`--help` and `--version` print before the GUI starts, in plain English, not translated.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`main` handles both and exits before `launch`, printing fixed English text rather than catalog messages."
      },
      "reference": "Editora `App.main`, `App.helpText`; `AppArgsTest`."
    },
    {
      "id": "CLI-02",
      "level": "MUST",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-02",
      "text": "`--config-dir <dir>` uses another config folder, and `--dev` uses `~/.<app>-dev`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the config folder is resolved from both flags before anything reads `~/.<app>`."
      },
      "reference": "Editora `App.main` (`ConfigManager.configDirFor`, `App.devFlag`)."
    },
    {
      "id": "CLI-03",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-03",
      "text": "`--new-instance` starts a second process instead of handing off to the running one.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the flag skips the single-instance hand-off."
      },
      "reference": "Editora `App.newInstanceFlag`."
    },
    {
      "id": "CLI-04",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-04",
      "text": "`--no-session` does not restore the last session.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "launch with `--no-session` and find only the items given on the command line."
      },
      "reference": "Editora `App.helpText`."
    },
    {
      "id": "CLI-05",
      "level": "MUST",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-05",
      "text": "`--report` writes a redacted problem report and opens the GitHub issue, without starting the GUI.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test runs the report command and finds the redacted report written."
      },
      "reference": "Editora `report/ReportCommand.java` (`ReportCommandTest`)."
    },
    {
      "id": "CLI-06",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Flags",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-06",
      "text": "`[files…]` opens these items.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "launch with two files and find both open."
      },
      "reference": "Editora `App.fileTargets`."
    },
    {
      "id": "CLI-07",
      "level": "MUST",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Launch",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-07",
      "text": "One instance runs per config folder. A second launch hands its arguments to the running app over a local endpoint and exits; on macOS, `openFiles` Apple Events reach the running app.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test makes the first launch primary and delivers a second launch's arguments to it."
      },
      "reference": "Editora `ipc/SingleInstance.java` (`SingleInstanceTest`), `MacOpenFiles.java`."
    },
    {
      "id": "CLI-08",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Launch",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-08",
      "text": "An advisory lock tells two processes on one config folder about each other.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test takes the lock from two processes."
      },
      "reference": "Editora `config/InstanceLock.java` (`InstanceLockTest`)."
    },
    {
      "id": "CLI-09",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Launch",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-09",
      "text": "`main` sets `java.awt.headless=true` before any AWT class loads.",
      "why": "on macOS, AWT's native toolkit and JavaFX contend for the one AppKit run loop and can hang; headless Java2D still draws to images.",
      "check": {
        "kind": "code",
        "text": "`System.setProperty(\"java.awt.headless\", \"true\")` is among the first statements of `main`."
      },
      "reference": "Editora `App.main`."
    },
    {
      "id": "CLI-10",
      "level": "SHOULD",
      "page": "command-line",
      "pageTitle": "Command line and launch",
      "section": "Launch",
      "url": "https://pauta-project.dev/2.0.1/command-line/#cli-10",
      "text": "External tools are resolved through the login shell's `PATH`.",
      "why": "a `.app` launched from Finder inherits a stripped `PATH`.",
      "check": {
        "kind": "code",
        "text": "every process the app starts gets a `PATH` that includes the login shell's."
      },
      "reference": "Editora `process/ProcessRunner.java` (`augmentedPath`)."
    },
    {
      "id": "INTL-01",
      "level": "MUST",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-01",
      "text": "The app ships a message catalog for each of the six languages above, English as the base.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the six `messages*.properties` files are in the app's `i18n` resources."
      },
      "reference": "Editora `src/main/resources/com/editora/i18n/`."
    },
    {
      "id": "INTL-02",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-02",
      "text": "A new language is a `messages_<code>.properties` with every key, listed in the Settings language picker and in the parity test.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the language's code is in `Messages`' language list (which the picker shows) and in the catalog list the parity test walks."
      },
      "reference": "Editora `i18n/Messages.java` (`LANGUAGES`, `available()`); `MessagesTest`'s `LOCALES` and `ALL_CATALOGS`, after which `translationCatalogsHaveExactlyTheBaseKeySet` holds it to the same keys as the others."
    },
    {
      "id": "INTL-03",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-03",
      "text": "Every value is translated for real: no English value is shipped in another language's catalog.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "compare each catalog's values with the base; a value identical to the English one is a name, a term or a bare pattern that stays the same in that language (\"Git: Pull (Rebase)\", \"{0} · {1}\"), never an untranslated sentence. No test catches it, so it is also checked in review."
      },
      "reference": "Editora `messages_*.properties`."
    },
    {
      "id": "INTL-04",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-04",
      "text": "The layout holds in every language at 1024 px wide: rows wrap, never cut. German is today's longest.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "run the app in each language at 1024 px wide (see [Quality](https://pauta-project.dev/2.0.1/quality/))."
      },
      "reference": "Editora `messages_de.properties`."
    },
    {
      "id": "INTL-05",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-05",
      "text": "A Chinese, Japanese or Korean catalog comes with a font fallback for its script.",
      "why": "Inter has no CJK glyphs.",
      "check": {
        "kind": "by hand",
        "text": "run the app in that language and look for missing-glyph boxes."
      },
      "reference": "no app yet."
    },
    {
      "id": "INTL-06",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Languages",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-06",
      "text": "An Arabic or Hebrew catalog sets `NodeOrientation.RIGHT_TO_LEFT` on every scene.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the scene setup sets the node orientation from the current language."
      },
      "reference": "no app yet."
    },
    {
      "id": "INTL-07",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-07",
      "text": "No raw English literal is passed to a control: every string comes from `tr(\"some.key\")` in one `Messages` class.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test scans the sources for `tr(\"…\")` calls and fails when a key is missing from the base catalog."
      },
      "reference": "Editora `i18n/Messages.java`, `MessagesTest.everyLiteralKeyUsedInTheSourcesExists`."
    },
    {
      "id": "INTL-08",
      "level": "MUST",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-08",
      "text": "Every catalog has every key of the base catalog, and no more, each with a non-empty value.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a parity test fails the build when a key is missing, extra or empty in any catalog."
      },
      "reference": "Editora `MessagesTest.translationCatalogsHaveExactlyTheBaseKeySet`, `translationsAreNonEmptyAndDistinctFromKeys`."
    },
    {
      "id": "INTL-09",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-09",
      "text": "In a value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once.",
      "why": "a value with a placeholder is a `MessageFormat` pattern, where a lone apostrophe starts a quoted section and can swallow the placeholder after it; a value without one is shown exactly as written.",
      "check": {
        "kind": "test",
        "text": "catalog tests fail a lone apostrophe beside a placeholder and a doubled one without."
      },
      "reference": "Editora `MessagesTest.aValueWithAPlaceholderNeverHasALoneApostrophe`, `aValueWithoutAPlaceholderNeverDoublesAnApostrophe`."
    },
    {
      "id": "INTL-10",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-10",
      "text": "Identifiers such as line numbers and ports use `{0,number,#}`, so they are not digit-grouped.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test formats each identifier argument in every locale and fails on a grouped number."
      },
      "reference": "Editora `MessagesTest.identifierArgumentsAreNeverDigitGrouped`."
    },
    {
      "id": "INTL-11",
      "level": "SHOULD",
      "page": "i18n",
      "pageTitle": "Internationalization",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/i18n/#intl-11",
      "text": "Technical identifiers and the `--help` and `--version` text stay untranslated, outside the catalogs.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the usage text is a literal in the launcher, not a `tr` call."
      },
      "reference": "Editora `App.java` (the usage text)."
    },
    {
      "id": "PAL-01",
      "level": "MUST",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-01",
      "text": "Every app has one Command Palette per window, opened by `palette.show`: `M-x` in the Emacs keymap and `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) in the others.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the window builds one `CommandPalette`, and each bundled keymap binds that chord to `palette.show`."
      },
      "reference": "Editora `ui/CommandPalette.java`, built once in `MainController`; `keymaps/emacs.json` (`M-x`), `cua.json` and `vscode.json` (`C-S-p`), `cua.mac.json` (`Cmd-S-p`)."
    },
    {
      "id": "PAL-02",
      "level": "MUST",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-02",
      "text": "The palette lists every registered command, with its title from `command.<id>` and its description from `command.<id>.desc`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the palette's rows come from the whole registry, filtered only by the query; a command that cannot run stays listed, grayed. A catalog parity test fails on a command title with no `.desc`."
      },
      "reference": "Editora `CommandPalette.filter` (`registry.all()`), `MessagesTest`; the Spec table below."
    },
    {
      "id": "PAL-03",
      "level": "MUST",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-03",
      "text": "The palette is an in-scene overlay in the window's root `StackPane`, over a faint scrim, not a `javafx.stage.Popup`.",
      "why": "on Windows a popup does not reliably take keyboard focus.",
      "check": {
        "kind": "code",
        "text": "the palette shows its card through the overlay host installed in the root `StackPane`; no `Popup` is created for it."
      },
      "reference": "Editora `ui/OverlayHost.java` (`install`), `CommandPalette.show`."
    },
    {
      "id": "PAL-04",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-04",
      "text": "The palette opens from the `palette.show` command, by its chord or a menu item, with an empty query that lists every command.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`show` clears the field and filters on the empty query before the card appears."
      },
      "reference": "Editora `CommandPalette.show`."
    },
    {
      "id": "PAL-05",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-05",
      "text": "Typing filters the list, and the first *enabled* match is selected.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test with a disabled command at the top finds the cursor on the first enabled row."
      },
      "reference": "Editora `CommandPalette.selectFirstEnabled`, `CommandPaletteDisabledFxTest`."
    },
    {
      "id": "PAL-06",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-06",
      "text": "↑ ↓, `C-n` `C-p` and Page Up/Down move the selection; Enter, or a click on an enabled row, runs the command. The palette closes first, then the command runs.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the run path hides the card before it calls the registry, and does nothing on a disabled row."
      },
      "reference": "Editora `CommandPalette.runSelected`, `PickerKeys`."
    },
    {
      "id": "PAL-07",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-07",
      "text": "Esc, `C-g` or a click on the scrim cancels, and focus returns to where it was.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the cancel key and a press on the backdrop both hide the overlay, and hiding focuses the node that had focus before it opened."
      },
      "reference": "Editora `PickerKeys` (`CANCEL`), `OverlayHost` (`previousFocus`)."
    },
    {
      "id": "PAL-08",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-08",
      "text": "`C-h`, or the first of `C-h`, `F1`, `Shift+F1` the active keymap leaves free, opens the selected command's page on the website, for the running version.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the docs chord is the first free one of the three, and the URL is built from the app's versioned docs address."
      },
      "reference": "Editora `CommandPalette` (`PickerKeys.freeChord`, `docsUrl`), `AppInfo.docsUrl`."
    },
    {
      "id": "PAL-09",
      "level": "SHOULD",
      "page": "templates/command-palette",
      "pageTitle": "Command Palette",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/command-palette/#pal-09",
      "text": "A live keymap switch re-renders the key chips, the opener chip and the key legend.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "applying a new keymap calls the palette's rebind method, which rebuilds the opener, the legend and the rows."
      },
      "reference": "Editora `CommandPalette.refreshBindings`, called from `SettingsReapply`."
    },
    {
      "id": "QOPEN-01",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-01",
      "text": "One picker serves every list choice: recent files, themes, keymaps, a setting's values, a branch to compare with.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "those choices are instances of one generic picker class; there is no second list-picker class or `ChoiceDialog` for them."
      },
      "reference": "Editora `ui/QuickOpen.java` (one generic class, instantiated more than seventy times), driven by `PickerKeys`."
    },
    {
      "id": "QOPEN-02",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-02",
      "text": "The picker is the palette's card in the shared in-scene overlay host, with a title naming the command over the field and a prompt in the field; never a `javafx.stage.Popup`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the picker shows its card through the overlay host and sets a title and a prompt text."
      },
      "reference": "Editora `QuickOpen.setOverlayHost`, `ui/OverlayHost.java`; the Spec table below."
    },
    {
      "id": "QOPEN-03",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-03",
      "text": "The items are read fresh on every showing and snapshotted, so typing filters a stable list. A source that answers late (an outline the language server has not returned yet) calls `reload()`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`show` calls the items supplier; `reload` re-reads it and keeps the query."
      },
      "reference": "Editora `QuickOpen.show`, `QuickOpen.reload`."
    },
    {
      "id": "QOPEN-04",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-04",
      "text": "With nothing typed the list keeps the supplier's own order (recency for recent files, document order for symbols), with the current value pre-selected when there is one.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the empty query passes the items through unsorted and selects the `setCurrentItem` value."
      },
      "reference": "Editora `QuickOpen.filter`, `setCurrentItem`."
    },
    {
      "id": "QOPEN-05",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-05",
      "text": "Typing ranks by fuzzy score, and ties keep the supplier's order, so rows do not shuffle under the cursor between keystrokes.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the sort's last tiebreak is the supplier's index."
      },
      "reference": "Editora `QuickOpen.filter`."
    },
    {
      "id": "QOPEN-06",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-06",
      "text": "The active keymap's line and page chords (`nav.lineDown`, `nav.pageUp`, …) move the selection, as do ↑ ↓, Page Up/Down and `Ctrl+Home`/`Ctrl+End` (`Cmd` on macOS), which always work; plain Home and End stay with the field's caret. Enter or a click on a row chooses; the card hides first, then the choice runs, so focus is already back where it belongs.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the accept path hides the card before it calls the choice handler."
      },
      "reference": "Editora `QuickOpen` (`hide()` then `onChoose`), `PickerKeys.resolve`."
    },
    {
      "id": "QOPEN-07",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-07",
      "text": "Esc, `C-g` or a click on the scrim cancels, and the host restores focus. A picker that previewed something undoes it.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test previews a row, dismisses the picker and finds the preview undone."
      },
      "reference": "Editora `OverlayHost` (`previousFocus`), `QuickOpenPreviewFxTest` (`dismissingRestoresWhatWasPreviewed`)."
    },
    {
      "id": "QOPEN-08",
      "level": "MAY",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-08",
      "text": "A picker previews the highlighted row as the selection moves and undoes the preview on cancel (Recent Locations shows each place and returns to the origin on Esc). A preview without an undo is worse than none, and nothing is previewed for the row the picker opens on, only for one the user moved to. The theme and keymap pickers do not preview; they apply on Enter.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "opening previews nothing, moving previews, choosing does not restore."
      },
      "reference": "Editora `QuickOpen.setPreview(onPreview, onCancelled)`, `QuickOpenPreviewFxTest`."
    },
    {
      "id": "QOPEN-09",
      "level": "MAY",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-09",
      "text": "A row action acts on the highlighted row and keeps the picker open (the breakpoints picker enables or removes one), re-reading the list afterwards and keeping the cursor in place.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a row action runs on the highlighted row and the picker stays up."
      },
      "reference": "Editora `QuickOpen.addRowAction(key, legend, action)`, `QuickOpenPreviewFxTest` (`aRowActionActsOnTheHighlightedRowAndKeepsThePickerOpen`)."
    },
    {
      "id": "QOPEN-10",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-10",
      "text": "A picker that can open on an empty list shows a placeholder sentence in it, never a blank card. A picker with nothing to offer may instead say so in the status line and not open.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each picker whose source can be empty either calls `setPlaceholder` or returns before `show` with a status message."
      },
      "reference": "Editora `QuickOpen.setPlaceholder` (`BreakpointsPicker`); `NavigationCoordinator` (`status.nav.noRecentLocations`)."
    },
    {
      "id": "QOPEN-11",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-11",
      "text": "The host shows one card at a time; opening a picker replaces whatever card was up.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the host's `show` removes the previous card before it adds the new one, and keeps the original focus owner."
      },
      "reference": "Editora `OverlayHost.show`."
    },
    {
      "id": "QOPEN-12",
      "level": "SHOULD",
      "page": "templates/quick-open",
      "pageTitle": "QuickOpen picker",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/quick-open/#qopen-12",
      "text": "The picker's relatives move, accept and cancel with the same keys as the picker.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each relative maps its keys through `PickerKeys`."
      },
      "reference": "Editora `Switcher`, `FileFinder`, `MultiSelectPicker`, `BranchPopup`, `GitStashPopup`."
    },
    {
      "id": "WELC-01",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-01",
      "text": "An app that opens files or projects shows a Welcome page when there is no session to restore.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "startup with nothing restored opens the Welcome page."
      },
      "reference": "Editora `ui/WelcomePane.java`, `MainController.addWelcomeTab`."
    },
    {
      "id": "WELC-02",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-02",
      "text": "An app whose window *is* its content shows its own empty state instead, with the same ingredients: the ways in, each with its chord.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "start the app with nothing in it and read the empty state's keys."
      },
      "reference": "Torrenta `ui/Welcome.java` (see In the apps below)."
    },
    {
      "id": "WELC-03",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-03",
      "text": "The page is shown at startup when there is no session to restore (so always with `--no-session`), by the `view.welcome` command (Help → Welcome Page), and when the tab strip is empty after a project swap. Standalone diff startup suppresses it while its worker reads the files.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "those three paths open the one Welcome tab; the diff startup holds a flag that skips it."
      },
      "reference": "Editora `MainController.addWelcomeTab`, `showWelcomeIfNoTabs`; `WindowSessionCoordinator` (`suppressWelcome`)."
    },
    {
      "id": "WELC-04",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-04",
      "text": "Closing the last file tab does not bring the page back. The editor area shows its own quiet hint instead: Open File, Open Folder, Command Palette and Welcome Page, each with its chord, and takes focus so chords still reach the window.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "closing the last tab shows the hint and opening a tab hides it."
      },
      "reference": "Editora `ui/EditorEmptyState.java`, `EditorEmptyStateFxTest`."
    },
    {
      "id": "WELC-05",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-05",
      "text": "The page is rebuilt on every show, so the recents, the Projects and Git toggles, the keymap and the theme are current. A refresh keeps the focus where it was.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "showing the page calls `refresh`, which re-requests focus when the page had it."
      },
      "reference": "Editora `WelcomePane.refresh`."
    },
    {
      "id": "WELC-06",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-06",
      "text": "The recent lists offer no file that no longer exists and no project whose root is gone. Remote files are kept unchecked.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the recent files pass through the same filter as the toolbar's dropdown; projects are kept only when their root is a directory."
      },
      "reference": "Editora `RecentFiles.showable`, `WelcomePane`."
    },
    {
      "id": "WELC-07",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-07",
      "text": "Remove from recent files asks first, through the caller, then refreshes the page.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the remover the page is given shows a confirmation before it removes the entry."
      },
      "reference": "Editora `WelcomePane.setRecentRemover`; `MainController` (`dialog.removeRecent.*`)."
    },
    {
      "id": "WELC-08",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-08",
      "text": "The digits 1 to 9 open the numbered entries: typed characters only, with no modifier, so chords and Enter are untouched.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the digit handler is on `KEY_TYPED` and ignores Ctrl, Alt and Meta."
      },
      "reference": "Editora `WelcomePane.onKeyTyped`."
    },
    {
      "id": "WELC-09",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-09",
      "text": "Saved SFTP sites appear as their own section; a click opens the connection form prefilled. The section is hidden when there are none.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the page adds a Remote Sites section only when the saved-sites list is not empty."
      },
      "reference": "Editora `WelcomePane` (`remoteSites`, `welcome.remote`)."
    },
    {
      "id": "WELC-10",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-10",
      "text": "Customize runs `keymap.select` and `theme.setAppTheme`; a change made there re-renders the page, chords included.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the Customize links run those two commands."
      },
      "reference": "Editora `WelcomePane` (`customizeRow`)."
    },
    {
      "id": "WELC-11",
      "level": "SHOULD",
      "page": "templates/welcome",
      "pageTitle": "Welcome page",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/welcome/#welc-11",
      "text": "The Welcome tab is not a document: its menu is Close only, with no Save, Rename or Pin, and the title bar shows the app or project name, not a file.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the Welcome tab's context menu holds one Close item."
      },
      "reference": "Editora `MainController.addWelcomeTab`."
    },
    {
      "id": "ABOUT-01",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-01",
      "text": "Every app has an About window, reached by Help → About, the `help.about` command, and on macOS the application menu's About item.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`help.about` is registered and listed in the Help menu, and the macOS application menu's About item runs it."
      },
      "reference": "Editora `ui/AboutDialog.java`, `ui/MenuBarModel.java` (`help.about` in the Help menu)."
    },
    {
      "id": "ABOUT-02",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-02",
      "text": "About shows the version and build, the Pauta edition (see below), the runtime, the license, links, and the result of the last update check.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the window reads the version, build and edition from `AppInfo`, the same text as `--version`, and shows the update checker's last answer."
      },
      "reference": "Editora `ui/AboutDialog.java`, `AppInfo`; the Spec table below."
    },
    {
      "id": "ABOUT-03",
      "level": "SHOULD",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-03",
      "text": "*Copy details* copies the environment block and leaves the window open; its label becomes \"Copied\".",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the button sits in the content, not the dialog's button bar, so pressing it can't close the window."
      },
      "reference": "Editora `AboutDialog` (`about.copyDetails`, `about.copied`)."
    },
    {
      "id": "ABOUT-04",
      "level": "SHOULD",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-04",
      "text": "The update status claims nothing before a check has answered: with no answer, or with the check switched off, it says it has not checked, never \"up to date\".",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the status falls back to the not-checked text when the checker has no result."
      },
      "reference": "Editora `AboutDialog` (`about.notChecked`); the states below."
    },
    {
      "id": "ABOUT-05",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Pauta edition",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-05",
      "text": "The edition appears in two places: a link, *Built to Pauta 2.0.0*, among the others, and a line `Pauta: 2.0.0` in the environment block, right after the commit, so *Copy details* carries it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the links use the `about.pauta` key, and the environment block writes a `Pauta:` line after the commit."
      },
      "reference": "no app yet."
    },
    {
      "id": "ABOUT-06",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Pauta edition",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-06",
      "text": "The link opens the edition's own address, `https://pauta-project.dev/<edition>/` (for example `https://pauta-project.dev/2.0.0/`), which never changes, not `latest/`, which moves on to newer editions.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the URL is built from the edition number and never contains `latest`."
      },
      "reference": "no app yet."
    },
    {
      "id": "ABOUT-07",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Pauta edition",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-07",
      "text": "The number is the edition the app meets, not the newest. Moving to a newer edition means reading its changelog for new or stronger MUSTs, meeting them, then changing the number.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "audit the app against the MUSTs of the edition it names."
      },
      "reference": "no app yet."
    },
    {
      "id": "ABOUT-08",
      "level": "MUST",
      "page": "templates/about",
      "pageTitle": "About window",
      "section": "Pauta edition",
      "url": "https://pauta-project.dev/2.0.1/templates/about/#about-08",
      "text": "The edition has one source: a `pauta.version` property in `pom.xml`, filtered into `build-info.properties` and read by `AppInfo`, like the app's own version. The README's Pauta badge and its \"Built to\" line name the same edition and change with it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`pom.xml` defines `pauta.version`, `build-info.properties` carries it, `AppInfo` reads it, and the README names the same number."
      },
      "reference": "no app yet."
    },
    {
      "id": "CONF-01",
      "level": "MUST",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-01",
      "text": "Before anything the user made is removed, deleted, discarded or overwritten, the app asks first, unless the action can be taken back instead.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each destructive action calls a confirmation before it changes anything, or records an undo."
      },
      "reference": "Editora `ui/CloseCoordinator.java` (unsaved changes, Quit) and `GitCoordinator.confirmDestructive`; Torrenta `ui/RemoveConfirm.java`, which asks it for the torrent list, the RSS tab and every list in Settings."
    },
    {
      "id": "CONF-02",
      "level": "MUST",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-02",
      "text": "The question names the thing and what happens to it.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every confirmation string names the thing, by an argument for its name or count or in its own words (\"Quit Editora?\"), and says what happens to it."
      },
      "reference": "Editora `dialog.unsaved.header`, `dialog.discard.tracked`; Torrenta `RemoveConfirm.question`, `Actions.removeQuestion`."
    },
    {
      "id": "CONF-03",
      "level": "MUST",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-03",
      "text": "The confirming button carries the action's own verb (Delete files, Remove, Discard, Quit), never OK or Yes, in the `danger` style.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the action's `ButtonType` is named from the catalog and its button gets the `danger` style class."
      },
      "reference": "Editora `GitCoordinator.confirmDestructive`, `MainController.styleUnsavedChangesButtons`, `styleQuitButtonAsDanger`; Torrenta `RemoveConfirm.ask`."
    },
    {
      "id": "CONF-04",
      "level": "MUST",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-04",
      "text": "Cancel is the way out: Escape and the window's close button both answer Cancel, and nothing is lost on a dismissal.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "Cancel has the `CANCEL_CLOSE` role, and the result defaults to Cancel when the dialog closes any other way (`showAndWait().orElse(cancel)`)."
      },
      "reference": "Editora `GitCoordinator.confirmDestructive`, `CloseCoordinator.unsavedAlert`; Torrenta `RemoveConfirm.ask`."
    },
    {
      "id": "CONF-05",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "States",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-05",
      "text": "When saving is an option the question has three answers, in this order: Save (the `success` style, green), Discard (`danger`) and Cancel. A Save that fails leaves the tab open.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the unsaved-changes alert sets Save, Discard and Cancel in that order and styles the first two."
      },
      "reference": "Editora `CloseCoordinator.unsavedAlert`, `MainController.styleUnsavedChangesButtons`."
    },
    {
      "id": "CONF-06",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "States",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-06",
      "text": "A question about ending a running program, which is not the user's data, words the button Close and makes Cancel the default button, so dismissing the dialog by any route keeps the program alive.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the close-running-program alert calls `setDefaultButton(true)` on Cancel."
      },
      "reference": "Termina `ui/TerminalWindow.java` (`dialog.closeAnyway`)."
    },
    {
      "id": "CONF-07",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "States",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-07",
      "text": "Where the action can be taken back, the app asks nothing and offers Undo instead.",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "close a clean tab and reopen it with Reopen Closed Tab; in Mirada, trash an image and undo."
      },
      "reference": "Mirada moves an image to the trash at once and offers Undo; Torrenta asks before removing a torrent but also keeps the removal on its undo stack for ten minutes (`UndoStack.KEEP_MS`); Editora `ClosedTabs`."
    },
    {
      "id": "CONF-08",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-08",
      "text": "The question comes before anything changes, and the action runs only on the action button.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the helper returns true on the action button alone, and the caller acts only on true."
      },
      "reference": "Torrenta `RemoveConfirm.ask`; Editora `GitCoordinator.confirmDestructive`."
    },
    {
      "id": "CONF-09",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-09",
      "text": "One gesture asks one question. An action on many things asks once with the count (\"Remove these 3 torrents?\", Torrenta's \"Apply to many torrents\" for a bulk command). Closing every tab asks per unsaved buffer, selecting each tab first so the user sees what the question is about, and remembers a Discard answer for exactly the state that was shown.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "a bulk command builds one question with a plural count; the close-all sweep selects each tab before it asks."
      },
      "reference": "Torrenta `Actions.removeQuestion`; Editora `CloseCoordinator.confirmSweep`."
    },
    {
      "id": "CONF-10",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-10",
      "text": "A delete that cannot be undone says so; one that leaves the files says that instead.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "\"This cannot be undone.\" appears only in the strings of actions that cannot be undone."
      },
      "reference": "Editora `dialog.discard.tracked`; Torrenta `actions.removeQuestion.delete`."
    },
    {
      "id": "CONF-11",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-11",
      "text": "A dangerous alternative (Force with Lease, Delete Anyway) is offered beside the safe one (Pull, then Push), in red, and only once the safe one has failed.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the force path is reached only from the safe command's failure result."
      },
      "reference": "Editora `GitBranchCoordinator.offerAfterRejection` (Force with Lease after a rejected push), `confirmForceDelete` (Delete Anyway after `NOT_FULLY_MERGED`)."
    },
    {
      "id": "CONF-12",
      "level": "SHOULD",
      "page": "templates/confirm-dialog",
      "pageTitle": "Confirm dialog",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/confirm-dialog/#conf-12",
      "text": "The question can be tested without a screen: its words come from pure code, and a capture hook answers the dialog, so a UI test never presses a native button.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a unit test covers the header and question for every kind, and UI tests set the capture answer."
      },
      "reference": "Torrenta `RemoveConfirm.header`, `question`, `answerForCapture`; `RemoveConfirmTest`."
    },
    {
      "id": "FIND-01",
      "level": "MUST",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-01",
      "text": "Wherever there is text to search, the app has a find bar that is part of the window, never a popup.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the bar is a node in the window's scene graph (docked or floating); no `Popup` or `Stage` is created for it."
      },
      "reference": "Editora `ui/FindReplaceBar.java` (the editor's find and replace), with `ui/ConsoleFindBar.java` and `ui/TerminalFindBar.java` as the same shape over a console and a terminal; Termina `ui/SearchBar.java`."
    },
    {
      "id": "FIND-02",
      "level": "MUST",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-02",
      "text": "The bar searches as you type and shows a match count.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the query field's text listener runs the search (debounced) and updates the count label."
      },
      "reference": "Editora `FindReplaceBar` (`debounce`, `find.count`); Termina `SearchBar` (`search.count`)."
    },
    {
      "id": "FIND-03",
      "level": "MUST",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-03",
      "text": "A list app filters instead of finding, with the same field and the same Escape.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the list's filter field filters as it is typed, and Escape in it empties it or gives focus back to the list."
      },
      "reference": "Torrenta `Omnibox`, `FilterQuery`, `MainWindow.onOmniboxKey`."
    },
    {
      "id": "FIND-04",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-04",
      "text": "The find command (`find.show`) opens the bar: `C-s` in the Emacs keymap and `Ctrl/Cmd+F` in CUA, Sublime, VS Code and IntelliJ, with `F3` as well in CUA and Sublime. A terminal uses `Ctrl+Shift+F`, `Cmd+F` on macOS, since a plain `Ctrl+letter` belongs to the shell. The command while the bar is already open finds the next match (Editora) or puts the caret back in the field (Termina).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each bundled keymap binds that chord to the find command; the command steps when the bar is shown."
      },
      "reference": "Editora `keymaps/*.json`, `MainController.findShowOrNext`; Termina `TerminalWindow` (`menu.find`, `MenuAction.appChord`)."
    },
    {
      "id": "FIND-05",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-05",
      "text": "Typing highlights every match and selects and scrolls to the first one at or after the caret. The anchor is the caret at open time, so refining the query does not run away down the document.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the search starts from an anchor saved when the bar opens, not from the current selection."
      },
      "reference": "Editora `FindReplaceBar` (`searchAnchor`, `recompute`)."
    },
    {
      "id": "FIND-06",
      "level": "MUST",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-06",
      "text": "Enter steps to the next match and Shift+Enter to the previous one, wrapping around at the ends. In a terminal the directions are up and down the scrollback.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the query field's key handler steps forward on Enter and backward on Shift+Enter."
      },
      "reference": "Editora `ConsoleFindBar`, `TerminalFindBar`; Termina `SearchBar`. Editora's editor bar (`FindReplaceBar`) does not yet: its field steps forward on Enter, and back only with the previous button, `find.showBackward` (`C-r`, `Shift+F3`) or `find.previous`. Alt+Enter there turns every match into a caret."
    },
    {
      "id": "FIND-07",
      "level": "MUST",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-07",
      "text": "Escape or the close button closes the bar: the highlights go, a search still pending is canceled so nothing moves after the bar is gone, and focus returns to the editor, the console or the shell.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the close path stops the debounces, cancels the running search, clears the highlights and focuses the text it searched."
      },
      "reference": "Editora `FindReplaceBar.hideBar`."
    },
    {
      "id": "FIND-08",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-08",
      "text": "In a terminal, Escape is consumed in the field and never reaches the shell, and the terminal's own key and mouse filters leave every event aimed at the bar alone.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the field consumes Escape, and the terminal's filters return early for events from the bar."
      },
      "reference": "Termina `SearchBar`, `TerminalView.fromSearchBar`."
    },
    {
      "id": "FIND-09",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-09",
      "text": "The keymap's caret and editing chords (`C-a`, `C-e`, `C-k`, `C-y`, `Ctrl+V/X/C/Z`) act on the field, not on the document. Find's own chords stay global, so next, previous, replace and close work while the field has focus.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the find fields install the shared text-input keymap."
      },
      "reference": "Editora `TextInputKeymap.installShared`; Termina's and Mirada's `TextInputKeys`."
    },
    {
      "id": "FIND-10",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-10",
      "text": "Nothing found is one status-line message (\"Not found: x\") or the count \"No matches\". No beep, no dialog.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the no-match path sets `find.notFound` or `search.none` and opens nothing."
      },
      "reference": "Editora `FindReplaceBar` (`find.notFound`); Termina `SearchBar` (`search.none`)."
    },
    {
      "id": "FIND-11",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-11",
      "text": "Replace keeps each match's case when *AB* (preserve case) is on.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test replaces with preserve case on and finds each match's casing kept."
      },
      "reference": "Editora `FindReplaceBarFxTest` (`preserveCaseFollowsEachMatchesCasing`)."
    },
    {
      "id": "FIND-12",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-12",
      "text": "A replacement that is too slow stops with \"Replace stopped: the pattern is too slow\" instead of hanging the window.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a catastrophic regex in Replace All aborts."
      },
      "reference": "Editora `find.replaceTimeout`, `FindReplaceBarFxTest` (`catastrophicRegexInReplaceAllAbortsInsteadOfHanging`)."
    },
    {
      "id": "FIND-13",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-13",
      "text": "A list app's filter box filters the names as plain words are typed, turns `key:value` terms into chips and runs a command after `>`. `Ctrl+K` focuses it and is drawn in the box as a key badge.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the box's text listener filters, and its badge is read from the filter command's chord."
      },
      "reference": "Torrenta `Omnibox`, `MainWindow.buildFilterBar`."
    },
    {
      "id": "FIND-14",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-14",
      "text": "Escape in a filter box peels one layer: a box with something in it empties, an empty one gives the list back.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the box's Escape handler clears a non-empty box and otherwise focuses the list."
      },
      "reference": "Torrenta `MainWindow.onOmniboxKey`."
    },
    {
      "id": "FIND-15",
      "level": "SHOULD",
      "page": "templates/find-bar",
      "pageTitle": "Find bar",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/find-bar/#find-15",
      "text": "The filter box is out of the Tab order, so a fresh launch does not land every keystroke in it, and the window's own chords (undo, `Ctrl+Alt+1…9`) do not fire while a text field has focus: `Ctrl+Z` there is the field's own undo.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the box is not focus-traversable, and the window's chord handlers return early when the focus owner is a `TextInputControl`."
      },
      "reference": "Torrenta `MainWindow.buildFilterBar`, `MainWindow` window chords."
    },
    {
      "id": "MLOG-01",
      "level": "MUST",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-01",
      "text": "Every app with a status bar keeps a Message Log: the session's status-bar messages, newest first, opened from the status bar.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every status-bar message is also added to one log model, and a view lists that model."
      },
      "reference": "Editora `ui/MessageLog.java` (the model, no JavaFX) and `ui/MessageLogPopup.java` (the view); Torrenta carries the same pair."
    },
    {
      "id": "MLOG-02",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-02",
      "text": "A click on the echo line or on the unread-error count opens the log, as does the `view.messageLog` command.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "both status-bar nodes run `view.messageLog` on a click."
      },
      "reference": "Editora `StatusBar` (`echo`, `unreadErrors`), `StatusBar.showMessageLog`."
    },
    {
      "id": "MLOG-03",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-03",
      "text": "Esc, `C-g` or a click outside closes the log.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the card's key handler hides it on Escape and `C-g`; the overlay's backdrop hides it on a press."
      },
      "reference": "Editora `MessageLogPopup`, `OverlayHost`."
    },
    {
      "id": "MLOG-04",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-04",
      "text": "`Ctrl+C` (`Cmd+C` on macOS) copies the selected entries.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the card's key handler copies the selection on the shortcut-down C."
      },
      "reference": "Editora `MessageLogPopup.copySelection`."
    },
    {
      "id": "MLOG-05",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-05",
      "text": "A message's severity comes from its key: a `status.*` key whose last segment contains `fail` or `error` is an error, one containing `cannot` or `invalid` a warning. Name new keys accordingly, or report through the error channel directly.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a severity test classifies keys by those rules."
      },
      "reference": "Editora `ui/StatusSeverity.java` (`ofKey`), `StatusSeverityTest`."
    },
    {
      "id": "MLOG-06",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-06",
      "text": "Opening the log, or clearing it, resets the unread-error count.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "opening the log marks it read, and `clear` zeroes the count."
      },
      "reference": "Editora `MessageLog.markRead`, `MessageLog.clear`, `StatusBar.showMessageLog`."
    },
    {
      "id": "MLOG-07",
      "level": "SHOULD",
      "page": "templates/message-log",
      "pageTitle": "Message Log",
      "section": "Behavior",
      "url": "https://pauta-project.dev/2.0.1/templates/message-log/#mlog-07",
      "text": "An unread error is never evicted silently: the count keeps it even when the entry drops off the end.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "an error pushed past the capacity still counts as unread."
      },
      "reference": "Editora `MessageLogSeverityTest` (`anEvictedErrorStillCounts`)."
    },
    {
      "id": "SYNC-01",
      "level": "SHOULD",
      "page": "templates/settings-sync",
      "pageTitle": "Settings Sync",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/settings-sync/#sync-01",
      "text": "An app with user data worth carrying between computers offers Settings Sync, on a page of its own in the Settings window that the Settings search finds by \"sync\".",
      "why": null,
      "check": {
        "kind": "by hand",
        "text": "open Settings, search \"sync\", and land on the Sync page."
      },
      "reference": "Editora `ui/SettingsSync.java` (the service) and `ui/SettingsSyncPage.java`, built by `SettingsWindow` (`Category.SYNC`)."
    },
    {
      "id": "SYNC-02",
      "level": "SHOULD",
      "page": "templates/settings-sync",
      "pageTitle": "Settings Sync",
      "section": "Rules",
      "url": "https://pauta-project.dev/2.0.1/templates/settings-sync/#sync-02",
      "text": "The store is a Git repository the user owns, reached through their own Git credentials (a credential helper or an SSH key), with no server or account of ours. A URL with a password or token in it is refused.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the sync package runs `git` against the user's URL, and the page refuses a URL with credentials in it."
      },
      "reference": "Editora `sync/` package (`SyncEngine`, `SyncMerge`, `SyncAccount`), `SyncEngine.hasCredentials`; Termina carries the same package, Torrenta its own `sync/` with `SyncEngine` and `SyncAccount`; the Spec table below."
    },
    {
      "id": "REL-01",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-01",
      "text": "jpackage builds the installers for the five targets in the table above, each on its own runner, through the Maven `dist` profile.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the release workflow's build matrix lists `linux-x64`, `linux-arm64`, `macos-arm64`, `macos-x64` and `windows-x64` on those runners, and `pom.xml` has a `dist` profile."
      },
      "reference": "Editora `release.yml` (the `build` job), `pom.xml` (`dist`)."
    },
    {
      "id": "REL-02",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-02",
      "text": "Downloads are named `<App>-<version>-<target>.<ext>`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the release-asset check builds the expected names this way."
      },
      "reference": "Editora `scripts/release/CheckRelease.java` (`expectedAssets`)."
    },
    {
      "id": "REL-03",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-03",
      "text": "**JReleaser** (`jreleaser.yml`) only creates the GitHub release: it builds nothing, and attaches every file and `checksums_sha256.txt`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`jreleaser.yml` attaches the build matrix's files and runs after the build jobs."
      },
      "reference": "Editora `jreleaser.yml`, the `release` job in `release.yml`."
    },
    {
      "id": "REL-04",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-04",
      "text": "The release notes are the version's section of `CHANGELOG.md`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the release job hands JReleaser that section as the changelog."
      },
      "reference": "Torrenta `scripts/release/ReleaseNotes.java`. Editora's release notes are still its commit list."
    },
    {
      "id": "REL-05",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-05",
      "text": "The Maven version is the single source of truth: a tag `vX.Y.Z` releases the version in `pom.xml`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the release workflow fails when the tag and the pom version differ."
      },
      "reference": "Editora's \"Check the tag against the pom version\" step in `release.yml`."
    },
    {
      "id": "REL-06",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-06",
      "text": "`master` carries a `-SNAPSHOT` version, and a post-release job opens the pull request that bumps it to the next snapshot.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the pom's version on `master` ends in `-SNAPSHOT`, and `release.yml` has the bump job."
      },
      "reference": "Editora's `bump` job in `release.yml`."
    },
    {
      "id": "REL-07",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-07",
      "text": "A **release-asset check** fails the run before publishing when an expected file is missing.",
      "why": "GitHub releases are immutable.",
      "check": {
        "kind": "code",
        "text": "a step before JReleaser compares the gathered files with the expected list."
      },
      "reference": "Editora's \"Verify the expected release assets\" step in `release.yml`."
    },
    {
      "id": "REL-08",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-08",
      "text": "On Linux, a `.desktop` file's `StartupWMClass` is the JavaFX app class.",
      "why": "the running window then belongs to the menu entry and shows its icon.",
      "check": {
        "kind": "code",
        "text": "`packaging/linux/<App>.desktop` sets `StartupWMClass=com.<app>.App`."
      },
      "reference": "Editora `packaging/linux/Editora.desktop`, Torrenta `packaging/linux/Torrenta.desktop`."
    },
    {
      "id": "REL-09",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-09",
      "text": "On Linux, AppStream metainfo has the id `io.github.adriandeleon.<App>`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`packaging/linux/io.github.adriandeleon.<App>.metainfo.xml` carries that `<id>`."
      },
      "reference": "Torrenta `packaging/linux/`. Editora's metainfo id (`com.editora.Editora`) predates the rule."
    },
    {
      "id": "REL-10",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Targets",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-10",
      "text": "Packaging trains an **AOT cache** (JDK 25 Leyden) to cut start-up time; Linux legs run the training under `xvfb`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the `dist` build runs a training launch with `-XX:AOTCacheOutput`, and the Linux release legs install `xvfb`."
      },
      "reference": "Editora `scripts/aot_build.java`."
    },
    {
      "id": "REL-11",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Install methods",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-11",
      "text": "The GitHub release offers every download on every platform: the `.dmg`, `.msi`, `.deb`, `.rpm`, `.AppImage` and `.tar.gz`, with checksums.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`jreleaser.yml` attaches each of these types."
      },
      "reference": "Editora `jreleaser.yml`."
    },
    {
      "id": "REL-12",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Install methods",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-12",
      "text": "On macOS (Apple Silicon) the app installs with `brew install --cask adriandeleon/tap/<app>`: JReleaser's `brew` packager writes the cask to [`adriandeleon/homebrew-tap`](https://github.com/adriandeleon/homebrew-tap). A cask takes exactly one artifact, so it serves Apple Silicon, and Intel Macs use the `macos-x64` DMG.",
      "why": "the official homebrew-cask repository has notability rules a new project does not meet, so the family shares one personal tap.",
      "check": {
        "kind": "code",
        "text": "`jreleaser.yml` has a `brew` packager for that tap; `jreleaser package --basedir .` writes the cask locally, to check it without releasing."
      },
      "reference": "Torrenta and Termina `jreleaser.yml`; Editora has no packager yet."
    },
    {
      "id": "REL-13",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Install methods",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-13",
      "text": "On Windows x64 the app installs with `winget install AdrianDeLeon.<App>`: JReleaser's `winget` packager opens a pull request on [`microsoft/winget-pkgs`](https://github.com/microsoft/winget-pkgs) from the `adriandeleon` fork. The package identifier is `AdrianDeLeon.<App>`, the moniker the app's lower-case name.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`jreleaser.yml` has a `winget` packager with that identifier; `jreleaser package --basedir .` writes the manifests locally."
      },
      "reference": "Torrenta and Termina `jreleaser.yml`; Editora has no packager yet."
    },
    {
      "id": "REL-14",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Install methods",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-14",
      "text": "Both packagers read a `PACKAGES_TOKEN` secret, a classic personal access token with `repo` scope. Without it JReleaser skips both, and the GitHub release still publishes.",
      "why": "the workflow's own token cannot write to the tap or open a pull request on the fork.",
      "check": {
        "kind": "code",
        "text": "`release.yml` passes `PACKAGES_TOKEN` to JReleaser and leaves the packagers out when it is empty."
      },
      "reference": "Torrenta and Termina `release.yml`."
    },
    {
      "id": "REL-15",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Signing",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-15",
      "text": "The macOS `.dmg` is signed with the Developer ID Application certificate (team 8JKSF797L8), with the hardened runtime and per-app entitlements, notarized with `notarytool`, stapled and checked with `spctl`; then the notarized app is launched once.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`release.yml` imports `MACOS_CERT_P12` and `MACOS_CERT_PASSWORD`, notarizes with `APPLE_API_KEY_P8`, `APPLE_API_KEY_ID` and `APPLE_API_ISSUER`, staples, runs `spctl` and launches the app."
      },
      "reference": "Editora's \"Import signing certificate (macOS)\" and \"Notarize DMG (macOS)\" steps in `release.yml`, `packaging/macos/Editora.entitlements`. Done in all six apps."
    },
    {
      "id": "REL-16",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Signing",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-16",
      "text": "Linux downloads are signed with the one shared OpenPGP release key (\"Adrian De Leon (release signing)\") in a separate `sign-linux` job: `rpmsign` for the `.rpm`, a debsigs origin signature for the `.deb`, and an armored `.asc` beside every file. The public key is committed as `packaging/linux/signing-key.asc` and attached to each release.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`release.yml` has a `sign-linux` job that reads `LINUX_GPG_KEY` and `LINUX_GPG_PASSPHRASE` and runs the shared scripts, and `packaging/linux/signing-key.asc` exists."
      },
      "reference": "Editora `scripts/release/sign-linux-packages.sh`, `scripts/release/check-linux-signatures.sh`. Done in Editora, Torrenta, Termina and Modula; Mirada partly; nux not yet."
    },
    {
      "id": "REL-17",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Signing",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-17",
      "text": "The Windows `.msi` is signed with Authenticode, once the certificate is chosen.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the Windows leg signs the `.msi` before it is uploaded."
      },
      "reference": "no app yet. **Open decision**: SignPath Foundation (free for OSS), a Certum Open Source certificate, or Azure Trusted Signing. Until then MSIs are unsigned and SmartScreen warns."
    },
    {
      "id": "REL-18",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "Signing",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-18",
      "text": "Every download has a GitHub **build provenance attestation** (`actions/attest-build-provenance`), which `gh attestation verify` checks.",
      "why": null,
      "check": {
        "kind": "test",
        "text": "a test keeps the attested files and the files JReleaser attaches the same list."
      },
      "reference": "Editora's \"Attest build provenance\" step in `release.yml`, `ReleaseSupplyChainTest`. Done in Editora, Termina and Mirada."
    },
    {
      "id": "REL-19",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-19",
      "text": "`ci.yml` runs on every push to `master` and every pull request: **Format** (`spotless:check`) and **Build & Test** (`./mvnw verify`, coverage gate included) on JDK 25. Both are required status checks for `master`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`ci.yml` triggers on `push` to `master` and on `pull_request`, with the two jobs; the repository's rules for `master` require both."
      },
      "reference": "Editora `ci.yml`."
    },
    {
      "id": "REL-20",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-20",
      "text": "`full-tests.yml` runs the full suite on Linux, macOS and Windows daily, on a pull request labeled `full-ci`, and before every release, and lists flaky tests in the job summary.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`full-tests.yml` has a `schedule` and a `pull_request` trigger gated on the label, and the release preflight waits for its run on the tagged commit."
      },
      "reference": "Editora `full-tests.yml`, `scripts/ci/ReportFlakes.java`, and the \"Check that the Full tests passed on this commit\" step in `release.yml`."
    },
    {
      "id": "REL-21",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-21",
      "text": "`release.yml` runs on a `v*` tag that matches the pom version, with `workflow_dispatch` as a dry run. It runs the five-target matrix, the signing jobs, attestations, the release-asset check, JReleaser, then the bump to the next snapshot. A dry run builds and signs and publishes nothing.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`release.yml` triggers on the tag pattern and `workflow_dispatch`, and a dispatch runs JReleaser with `--dry-run`."
      },
      "reference": "Editora `release.yml`."
    },
    {
      "id": "REL-22",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-22",
      "text": "Every workflow pins each third-party action to a commit SHA, with its version in a comment (`actions/setup-java@b843ebf… # v6.1.0`).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every `uses:` in `.github/workflows/` ends in a 40-character SHA and a `# vX.Y.Z` comment."
      },
      "reference": "Editora `.github/workflows/`."
    },
    {
      "id": "REL-23",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-23",
      "text": "Dependabot updates `github-actions` and `maven` weekly.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`.github/dependabot.yml` lists both ecosystems with `interval: weekly`."
      },
      "reference": "Editora `.github/dependabot.yml`."
    },
    {
      "id": "REL-24",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-24",
      "text": "Every workflow starts from `permissions: contents: read`; only a job that needs write access asks for it, in its own block.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each workflow's top-level `permissions` is `contents: read`, and every `write` sits in a job's own `permissions`."
      },
      "reference": "Editora `release.yml`: `release` (publish), `bump` (the pull request) and `preflight` (start a Full tests run)."
    },
    {
      "id": "REL-25",
      "level": "SHOULD",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-25",
      "text": "Every workflow sets up JDK 25 with `actions/setup-java` and `cache: maven`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each `setup-java` step has `java-version: '25'` and `cache: maven`."
      },
      "reference": "Editora uses Temurin in `ci.yml` and `full-tests.yml`, and Liberica for the release build, for linux-aarch64 coverage."
    },
    {
      "id": "REL-26",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-26",
      "text": "Every job has `timeout-minutes`, and `concurrency` cancels a superseded pull-request run, never a run on `master`.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "every job sets `timeout-minutes`; `cancel-in-progress` is true only for `pull_request` events."
      },
      "reference": "Editora `ci.yml` (`cancel-in-progress: ${{ github.event_name == 'pull_request' }}`)."
    },
    {
      "id": "REL-27",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-27",
      "text": "CI uploads the surefire reports even when tests fail, and the JaCoCo report; it writes the coverage totals to the job summary.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "the test reports upload under `if: always()`, and a step appends the totals to `$GITHUB_STEP_SUMMARY`."
      },
      "reference": "Editora's \"Upload test reports and coverage data\" and \"Summarise coverage\" steps in `ci.yml`."
    },
    {
      "id": "REL-28",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-28",
      "text": "Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag without them fails.",
      "why": null,
      "check": {
        "kind": "code",
        "text": "each signing step checks its secrets first, skips without them, and fails on a tag push."
      },
      "reference": "Editora's \"Import signing certificate (macOS)\" step checks `MACOS_CERT_P12` first."
    },
    {
      "id": "REL-29",
      "level": "MUST",
      "page": "release",
      "pageTitle": "Packaging, signing and release",
      "section": "CI/CD (GitHub Actions)",
      "url": "https://pauta-project.dev/2.0.1/release/#rel-29",
      "text": "The packaged app is launched once on each OS before a release (a smoke test).",
      "why": null,
      "check": {
        "kind": "code",
        "text": "`release.yml` runs the packaged launcher on every target before JReleaser."
      },
      "reference": "Torrenta's \"Smoke-test the packaged app\" step runs the launcher in every target's image. Editora runs only the notarized macOS app (`--version`, `--check-terminal`)."
    }
  ]
}
