Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(chore) Agent skills sync
Egor Khindikaynen11eafdac9179
diff --git a/.agents/skills/nota-design/SKILL.md b/.agents/skills/nota-design/SKILL.mdindex 75dd1800..0b931c2f 100644--- a/.agents/skills/nota-design/SKILL.md+++ b/.agents/skills/nota-design/SKILL.md@@ -1,26 +1,26 @@---name: nota-design-description: Nota's UI design language — "Studio", the design system of the sibling app Saine applied to Nota — neutral greys on dark 1px seams, one orange accent reserved for what is live or chosen, sentence-case labels, in colour themes (Studio Dark — the default — Studio Light, Ember Graphite, Ember Paper). Use whenever building or restyling any Nota UI (windows, panels, controls, device cards, custom-drawn views like the piano roll / waveform / arrangement) so everything stays visually consistent. Points at the authoritative token files and the full guideline rather than restating values.+description: Nota's UI design language — "Studio": the work carries the colour, the interface steps back — neutral greys on dark 1px seams, one orange accent reserved for what is live or chosen, sentence-case labels, in colour themes (Studio Dark — the default — Studio Light, Ember Graphite, Ember Paper). Use whenever building or restyling any Nota UI (windows, panels, controls, device cards, custom-drawn views like the piano roll / waveform / arrangement) so everything stays visually consistent. Points at the authoritative token files and the full guideline rather than restating values.user-invocable: true---# Nota design language — Studio-Saine's design system (`../saine/DESIGN.md`) applied to Nota: neutral greys stepped in a+The work carries the colour; the interface steps back. Neutral greys stepped in afew exact tones (well · ground · panel · raised), flat panels butted against dark 1pxseams, small crisp type, and **one orange accent that appears only where something islive or chosen**. Colour is a **theme**: one fixed look, dark or light, that gives everytoken a value — Studio Dark (the default), Studio Light, Ember Graphite, Ember Paper. Thestructure (layout, type, geometry, where the accent goes) is the same in every theme.Preferences → Appearance picks a theme or Follow system (a dark-mode and a light-mode-theme); the switch is live. `DESIGN.md` is Saine's system as Nota implements it, plus the departures+theme); the switch is live. `DESIGN.md` is the guideline, plus the exceptionsthe project accepted.## Read these first — do not work from memory| File | What it gives you ||---|---|-| `DESIGN.md` | **The guideline.** Rules, colour themes and the readability bar, every Studio token value, elevation, type scales, number setting, controls and states, device cards, shell, the tests, accepted departures, known drift. Start here. |+| `DESIGN.md` | **The guideline.** Rules, colour themes and the readability bar, every Studio token value, elevation, type scales, number setting, controls and states, device cards, shell, the tests, accepted exceptions, known drift. Start here. || `DESIGN.html` | The same thing rendered — swatches, control specimens, a device card at true size, a theme toggle. Generated by `scripts/design-html.py`. || `src/managed/Nota.App/Theme/Themes/*.json` | **Definitive colour**: one file per theme, one value per token (incl. shadow colours and Fluent's accent ramp). || `src/managed/Nota.App/Theme/NotaTheme.axaml` | **Definitive** geometry, type classes, control styles. Holds no colour. |@@ -28,7 +28,6 @@ the project accepted.| `Theme/NotaGeometry.cs` · `NotaFonts.cs` · `NotaText.cs` · `NotaNum.cs` | Radii/sizes/spacing · Geist typefaces and type scale · sentence-case labels · number formatting. || `DeviceCardKit.cs`, `Controls/` | The shared controls and card builders; `Controls/NotaGraph.cs` for graph windows. || `tests/Nota.SmokeTest/DesignTokenCheck*.cs` | The guard tests (incl. `RunStudio`, `RunThemes`, `RunLabels`, `RunIcons`) and their ratchet lists (`*AllowList.txt`, which only shrink) — run the smoke test after any UI change. |-| `../saine/DESIGN.md` | The reference system, when a question is not settled by the files above. |If `DESIGN.md` / `DESIGN.html` disagree with the theme files, **the theme files win** andthe docs need fixing. Say so rather than propagating the drift.diff --git a/.agents/skills/nota-docs/SKILL.md b/.agents/skills/nota-docs/SKILL.mdnew file mode 100644index 00000000..b648ce49--- /dev/null+++ b/.agents/skills/nota-docs/SKILL.md@@ -0,0 +1,134 @@+---+name: nota-docs+description: Keep the user documentation (sibling repo ../nota-docs, Astro Starlight, EN + RU) in sync with the app. Run this WHENEVER you add, change or remove a user-visible feature — a new device or parameter, a new view/panel/window, a changed workflow, a moved menu item, a new or re-mapped shortcut, a new Preferences option — i.e. whenever you write a CHANGELOG [Unreleased] entry. Also run it from /release to catch anything that slipped. Handles: finding the affected pages, editing the EN page and its RU twin, re-shooting screenshots (nota-design mockups or the headless app), regenerating the shortcuts page, and building/checking the site.+user-invocable: true+---++# Keeping Nota Docs honest++The user manual lives in **`../nota-docs`** (relative to this repo; GitHub `nota-daw/nota-docs`),+built with Astro Starlight in **English (root) and Russian (`/ru/`)**. It is written by hand,+so every user-visible change in this repo must be mirrored there or the manual lies. The+overall structure and conventions are in `../nota-docs/PLAN.md` — read it once if you have+not.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+`Added` / `Changed` / `Removed` almost always need a docs edit; `Fixed` only when the fix+changes what the docs describe. Pure refactors, perf and internal changes need nothing.++**Argument** (`/nota-docs <arg>`, optional): a feature name, a changelog line, or `audit`+(reconcile *all* `[Unreleased]` entries — used by `/release`). No argument → the change you+just made in this session.++If the page that should cover the change is still a stub (`status: todo`) and you are not+writing it now, append `{page, change, version}` to the `pending:` list at the bottom+of `../nota-docs/coverage.yml` so the stage that writes that page picks it up, tell the user,+and stop.++## 1. Work out what changed for the user++From the diff and the CHANGELOG entry, list concretely: new/renamed UI labels, new+parameters with ranges and defaults, new menu items and where they sit, new shortcuts,+changed behaviour, removed things. Take names and numbers **from the code** (the device's+DSP class and card under `src/managed/Nota.App/DeviceCards/…`, menus in `MainWindow.axaml`,+`PreferencesWindow.cs`), never from memory or the mockup — the changelog itself can be+contradicted by a later entry.++## 2. Find the pages++1. `../nota-docs/coverage.yml` maps features and source paths → page slugs. Look up every+ file you touched and every feature you named.+2. Grep page frontmatter `sources:` in `../nota-docs/src/content/docs/**/*.mdx` for the+ touched paths, and grep page bodies for the old UI label / old shortcut.+3. Nothing found → it is a new feature. Decide its place in the sidebar (see `PLAN.md`),+ copy `templates/page.mdx` (or `templates/device.mdx`) into both+ `src/content/docs/<slug>.mdx` and `src/content/docs/ru/<slug>.mdx`, and add it to+ `coverage.yml`. The sidebar autogenerates per directory (order via `sidebar.order`); only a+ brand-new top-level section needs an entry in `astro.config.mjs`.++Typical fan-out — check all that apply:+- the feature's own page (device, view, panel, preference pane);+- the overview that lists it (Devices index, Views index, "Main window tour");+- `reference/shortcuts` — regenerated, see step 4;+- the glossary, if you introduced a term;+- tutorials that walk through the changed flow (the old steps may no longer work);+- a new built-in device or a renamed device page → the slug maps in+ `src/managed/Nota.App/NotaDocs.cs` (`Instruments` / `AudioEffects` / `MidiEffects`, indexed by+ engine kind) so the device header's Documentation item opens the right page.++## 3. Edit EN, then RU++- English page under `src/content/docs/<slug>.mdx`, Russian twin at+ `src/content/docs/ru/<slug>.mdx` — **same path, same structure, same screenshots**. Never+ leave one language behind; `scripts/check.mjs` fails on a missing or stale twin.+- A stub page (`status: todo`) you fill in becomes `status: draft` (or `done` once its+ screenshots are in); drop the "Being written" aside.+- Bump `updated:` in both frontmatters to the version in `VERSION` (plus `since:` on new+ pages); add any new source paths to `sources:`.+- Style: short, second person, like the CHANGELOG. UI names exactly as on screen in+ **bold**, keys via `<Kbd>`. In Russian, UI names stay in English (the app is English); the+ explanation is native Russian, not a word-for-word translation.+- Removed feature → delete the text and its screenshots; removed page → delete both+ languages, the sidebar entry and the `coverage.yml` entry, and fix links into it.++## 4. Screenshots and generated pages++`../nota-docs/shots/manifest.yml` lists every image (its header documents the scenes and+args). `npm run shots -- <id-prefix> …` retakes them into `src/assets/shots/{dark,light}/`.++- **app** shots render the real UI headlessly (`shots/app`, both themes, 2×, user/device names+ scrubbed). They build against this repo's `src/managed/Nota.App`, so build the app first if+ you changed it. **design** shots come from `../nota-design` (dark only).+- UI that changed visibly → retake its ids (e.g. `npm run shots -- devices/audio-effects/shutter`).+- New device → add `devices/<group>/<slug>/card` (`scene: device` with its kind id) plus one+ shot per tab you document (`args: {tab: "<tab text>"}`, a chain like `"L>Env"` when a size+ switch comes first, `preset` for an interesting state). Write the page from+ `templates/device.mdx`; facts come from the engine header's top comment and `paramName`,+ the card file's header comment and labels, and `FactoryPresetCatalog` — give a range only+ when the code states it.+- New window / view / Settings page → a new scene in `shots/app/Scenes.cs` if none fits; keep+ it deterministic (demo song, no real user data).+- Mockup no longer matches the code → switch that id to `source: app`; never document the mockup.+- A scene breaks after an app refactor (renamed private method, control name) → fix the+ harness; it reflects into `MainWindow` / `PreferencesWindow` privates on purpose.+- Shortcut changed → `npm run shortcuts` regenerates `reference/shortcuts` (EN + RU) from+ `PreferencesWindow.ShortcutGroups`; run the `nota-shortcuts` skill first so that list is+ right.++## 5. Verify and commit++```bash+cd ../nota-docs+npm run build+npm run check+```++Node may not be on PATH (Homebrew's node isn't linked on this Mac) — use+`/opt/homebrew/Cellar/node/*/bin`. The dev server is the `nota-docs` entry in this repo's+`.claude/launch.json` (preview_start).++Both must pass (broken links, missing RU twin, image id not in manifest, `updated:` older+than a touched source). Look at the changed pages in `npm run preview` via the built-in+browser when screenshots or layout changed.++Commit in **`../nota-docs`**, separately from the app repo: `(docs) <what changed>`, no+Claude attribution trailer. Don't push unless the user asked.++## 6. Report++List the pages changed (EN + RU), screenshots re-shot, anything you could not document+(e.g. a scene the harness can't render) and the gaps you left in `coverage.yml`.++## /release audit mode++Go through every `Added` / `Changed` / `Removed` entry of `[Unreleased]`, check each against+the docs as above, fix what's missing, then `npm run build && npm run check`. Report+the coverage to the user before the tag is created; missing docs do not block a release, but+say so plainly.++## Don't+- Don't document plans, mockup-only features or anything not in the code.+- Don't update only one language.+- Don't hand-edit the generated shortcuts page.+- Don't copy CHANGELOG prose verbatim — the changelog says what changed, the docs say how+ to use it now.diff --git a/.agents/skills/nota-features/SKILL.md b/.agents/skills/nota-features/SKILL.mdnew file mode 100644index 00000000..7fe279a8--- /dev/null+++ b/.agents/skills/nota-features/SKILL.md@@ -0,0 +1,104 @@+---+name: nota-features+description: Keep FEATURES.md (the consolidated "what Nota can do" list in the repo root) in sync with the app. Run this WHENEVER you add, change or remove a user-visible capability — a new device or parameter, a new view/panel/window, a new workflow or editing command, a new MCP tool, a new export option, a new platform/build/CI capability — i.e. whenever you write a CHANGELOG [Unreleased] Added/Changed/Removed entry. Also run it from /release in `audit` mode to catch anything that slipped and bump the "as of version" line.+user-invocable: true+---++# Keeping FEATURES.md honest++`FEATURES.md` is the single page that answers "what can Nota do *right now*". It is written+by hand and is not generated from the changelog, so it drifts unless every feature change is+folded into it. It describes **what is implemented in the code**, not plans, and it is a+**current-state** document: no history, no "now", no "previously", no version numbers per+item — that is the CHANGELOG's job.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+- `Added` → almost always a new bullet or an extension of an existing one.+- `Changed` → rewrite the bullet that describes the old behaviour so it describes the new.+- `Removed` → delete the mention (search the whole file — features get cross-referenced).+- `Fixed` → only if the fix changes what the list claims (a limit lifted, a platform now+ supported). Pure bug fixes, refactors, perf and internals need nothing.++**Argument** (`/nota-features <arg>`, optional): a feature name, a changelog line, or+`audit` (reconcile everything since the version in the file's header — used by `/release`).+No argument → the change you just made in this session.++## 1. Find where it belongs++Read the Contents list at the top of `FEATURES.md` and pick the section by what the user+sees, not by which code you touched:++| Change | Section |+|---|---|+| OS support, installers, auto-update, audio/MIDI backends | Platforms and distribution |+| Projects, saving, version history, transport, tempo, loop, metronome | Project and transport |+| Arrangement / Session / Modular / clip editors / piano roll behaviour | Views |+| Track types, routing, sends, groups, mixer window | Tracks and mixer |+| Note editing, MIDI input, MIDI Learn, controllers | MIDI and virtual instruments |+| Recording, audio clips, warp, stretch, stems | Audio: recording, clips, warp |+| Automation lanes, envelopes, modulation | Automation |+| A built-in instrument / audio effect / MIDI effect / rack | Built-in devices → the matching `###` subsection |+| VST3/AU hosting, plugin scanning, plugin windows | Plugin hosting |+| Browser tabs, sample library, presets, smart samples | Browser and assets |+| Render / bounce / stems export | Export |+| Windows, themes, menus, dialogs, Nota Remote UI | Windows and interface |+| A new Preferences option | Preferences |+| A new or changed MCP tool | MCP / AI control (also mention it on the feature's own bullet if it has one, as existing device bullets do: "MCP `read_sampler` / `set_sampler`") |+| Build scripts, CI, tests, licensing | Other |++Before writing, `grep -n` the file for the feature's name and its key words — the feature+may already be partly described (often it is an extension of an existing bullet, e.g. a new+parameter on a device). **Extend the existing bullet rather than adding a duplicate.** If a+genuinely new top-level area appears, add a `##` section *and* its Contents link (anchor =+GitHub slug of the heading).++## 2. Write it in the file's voice++Match the surrounding bullets — read the neighbours first.+- One bullet per feature; **bold** the feature's name at the start, then a dash or colon and+ what it does. Nested bullets only for sub-features of one thing (see Transport).+- English, present tense, plain language a musician understands. State capabilities and+ user-facing names (menu items, tab names, button labels exactly as in the UI), shortcuts+ in the app's glyphs (⌘ ⇧ ⌥, "Cmd/Ctrl" where the file already does).+- Concrete over vague: parameter names, modes, counts ("25 factory presets", "Poly 16 /+ Mono / Legato") — but verify each number in the code/presets, don't copy it blindly from+ the changelog.+- Condense. The changelog entry explains the change; FEATURES states the result in roughly+ half the words. No rationale, no "fixes", no internal class names (file paths only in+ Other / Platforms, as already done there).+- Built-in devices: follow the existing device bullet shape — what it is · its main controls+ and modes · tabs/sizes of the card · preset count · MCP tools if any.+- Hard-wrap at ~90 columns like the rest of the file.++## 3. Verify against the code++The changelog can be ahead of, or behind, reality. For each claim you add, confirm it in the+source (device kind registration, the view/menu code, the MCP tool list in the MCP server,+the preset folder). If something in the changelog was later reverted or is behind a flag+that is off by default, leave it out (or say "experimental, off by default" if the user can+turn it on).++## 4. `audit` mode (from /release)++1. Read the version in the header line ("as of version **X.Y.Z**").+2. Collect every `CHANGELOG.md` entry newer than that version: all `## [A.B.C]` sections+ above `## [X.Y.Z]`, plus `[Unreleased]` / the section being released right now.+3. For each `Added` / `Changed` / `Removed` entry (and relevant `Fixed`), check whether+ `FEATURES.md` reflects it; fix what is missing or stale per sections 1–3.+4. Update the header: set the version to the one being released (or the latest released+ version when run outside a release), keep "(plus changes in development on `main`)".+5. Report the list of entries you added/changed in FEATURES.md and anything you+ deliberately skipped (and why).++## 5. Finish++- Re-read the edited section as a whole: no duplicates, no contradictions with other+ sections, Contents still matches the `##` headings.+- The SPDX header on line 1 stays.+- Commit FEATURES.md together with the feature (or the release commit in audit mode);+ don't make a separate commit unless the user asks.++## Don't+- Don't paste changelog entries verbatim, and don't add dates or version tags to items.+- Don't describe planned, unmerged or disabled-by-default work as available.+- Don't reorganize or restyle sections you weren't asked to touch.diff --git a/.agents/skills/nota-shortcuts/SKILL.md b/.agents/skills/nota-shortcuts/SKILL.mdnew file mode 100644index 00000000..416d537b--- /dev/null+++ b/.agents/skills/nota-shortcuts/SKILL.md@@ -0,0 +1,66 @@+---+name: nota-shortcuts+description: Keep the Preferences → Shortcuts screen in sync with the app's real keyboard/mouse bindings. Run this WHENEVER you add, remove, or change a keyboard shortcut or mouse gesture (transport keys, editing commands, piano-roll keys, the computer-keyboard note map, device drag, etc.) — the Shortcuts pane is a hand-maintained list and silently drifts from the handlers otherwise. Handles: finding every place bindings are defined, updating the on-screen list, and visually verifying it.+user-invocable: true+---++# Keeping the Shortcuts screen honest++Nota shows its keyboard/mouse shortcuts in **Preferences → Shortcuts**. That list is+**hand-written**, not generated from the handlers — so every time the input handling+changes, the screen must be updated by hand or it lies to the user. This skill is the+checklist for doing that.++**Trigger:** you touched anything that changes what a key or mouse gesture does — a new+hotkey, a re-mapped key, a removed command, a changed computer-keyboard note layout, a new+drag gesture. If your change added/removed/moved a binding, you are not done until the+Shortcuts pane matches.++## 1. The on-screen list (what to edit)++`src/managed/Nota.App/PreferencesWindow.cs` → the static **`ShortcutGroups`** array (feeds+`ShortcutsPane`). It's grouped: `TRANSPORT`, `ARRANGEMENT & EDITING`, `PIANO ROLL`,+`PLAY NOTES (COMPUTER KEYBOARD)`, `MOUSE`. Each row is `(Key, Action)`; the `Key` string is+split on spaces and each token becomes its own mono key-cap (`/` and `·` stay plain+separators) — as long as every token is a key: no lower-case letters, or one of `Space`+`Return` `Delete` `Tab` `Esc` (`IsKeyToken`). Anything else (`Drag note edge`, `Face+buttons`) is a gesture and shows as plain text. The `Action` is a short sentence. Use `⌘` for Meta/Ctrl, `⇧`+for Shift, `⌥` for Alt, and the arrow glyphs `← → ↑ ↓`. Keep actions imperative and terse+(design language: sentence case, `·`/` / ` as separators).++## 2. The source of truth (where bindings actually live)++Read these and reconcile the list against them — do **not** trust the existing pane text:++| Bindings | File |+|---|---|+| Transport (Space/Return), global editing (A, R, M, ⌘M, ⌘G/⌘⇧G, ⌘C/X/V, Delete, Tab, Esc) and the **computer-keyboard note map** (`KeyToPitch`) | `src/managed/Nota.App/MainWindow.Input.cs` |+| Piano-roll note editing (arrows, ⇧ octave, ⌘A/⌘D, ⌘C/X/V, Delete, Esc) | `src/managed/Nota.App/PianoRollView.cs` (its `OnKeyDown`) |+| Arrangement lane / clip gestures (double-click, drag) | `src/managed/Nota.App/ArrangementView*.cs` |+| Device reorder drag | `src/managed/Nota.App/DeviceChainView.cs`, `DeviceCards/…` |++`KeyToPitch` is the note layout: bare letters play notes, and `A` is **deliberately not** a+note (it toggles automation mode) — so the "Play notes" rows must never list `A`. When that+map changes, update the `PLAY NOTES` group (white vs. black keys, and the starting octave).++## 3. Procedure++1. List, from your own diff, every binding you added/changed/removed.+2. Open the source-of-truth file(s) above and confirm the *current* behaviour of each key in+ the affected group — including ones you didn't touch, since the list may already be stale.+3. Edit `ShortcutGroups` so every row matches. Add a row for a new binding, delete a row for a+ removed one, fix the key-cap or wording for a changed one. Put it in the right group.+4. Build: `dotnet build src/managed/Nota.App -c Debug`.+5. Visually verify (see [nota-ui-verify] memory): the pane can't be reached by a click in a+ headless run, so temporarily open it via an env-guarded hook in+ `MainWindow.OnDataContextChanged` (`new PreferencesWindow(new SettingsViewModel(settings),+ _vm).Show(this)`), and select the Shortcuts section (index 8 — count the sidebar entries, it moves as pages are added) — e.g. a temporary env read+ in front of the constructor's `Select(0)`. Screenshot with `screencapture -x -o -l<winid>`+ (get the id from the `winlist` swift helper), check the rows read correctly, then **revert+ the temp hooks** and rebuild.++## 4. Don't forget++- If the change is user-visible, it also wants a `CHANGELOG.md` entry under `## [Unreleased]`.+- Keep the pane concise — it's a reference, not a manual. Group related keys onto one cap+ (`⌘C ⌘X ⌘V`) rather than three rows when the action is one idea.diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.mdnew file mode 100644index 00000000..8c85be7e--- /dev/null+++ b/.agents/skills/release/SKILL.md@@ -0,0 +1,289 @@+---+name: release+description: Cut a Nota release in three phases. `prepare` (on a release/X.Y.Z branch from develop) promotes CHANGELOG.md [Unreleased] to a dated version, writes the curated EN + RU release notes in release-notes/ (the one source for the GitHub release and the news channels), bumps the app and engine versions, makes the release image and the PR texts. `tag` (on main, after the user merged the release PR into develop and the develop → main PR) creates the vX.Y.Z tag. `verify` (after the user pushed the tag) waits for the build and checks the GitHub draft against the curated notes. Run this when the user asks to release, ship, cut a version, tag a release or check a release build.+user-invocable: true+---++# Cutting a Nota release++Two files describe a release, for two readers:++- **`CHANGELOG.md`** is the raw working log. Entries land under `## [Unreleased]` as work+ merges ("what we did, we write"), so it can repeat itself or hold changes that a later+ entry undid. At release time it is only promoted to `## [X.Y.Z] — date` and is never+ rewritten. The CI guard requires the section, and What's New falls back to it for a+ version without curated notes.+- **`release-notes/X.Y.Z.en.md`** and **`release-notes/X.Y.Z.ru.md`** are the curated+ text: summarised, deduplicated, checked against the code. **Everything published comes+ from them**, and the app bundles the EN file for its What's New window, so the notes must+ be committed on the release branch before the tag is built. They hold a summary, the+ full Added / Changed / Fixed list with a commit link on each item, and the contributors+ (format in P4). `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:++ | target | where it goes | full list |+ |-----------|-------------------------------------------------|-----------|+ | `github` | GitHub release body (the workflow uses this) | yes |+ | `post-en` | English news channels | no |+ | `post-ru` | Russian news channels | no |++The release runs through the branches like this. **The user does every commit, push and PR+by hand.** This skill never commits, pushes or opens a PR (see the user-commits rule).++```+release/X.Y.Z ── /release prepare ── user commits, pushes, opens PR → develop (squash)+develop ── CI green, user merges ── user opens PR develop → main (merge commit)+main ── CI green, user merges ── /release tag ── user pushes the tag+CI ── release.yml builds 6 files + draft release ── /release verify ── user publishes+```++`develop` and `main` are protected (rulesets): changes land only through a pull request+with the `macOS`, `Windows` and `Linux` CI checks green; `develop` takes squash merges,+`main` takes merge commits only, so `develop` → `main` never rewrites history. Release+tags `v*` can be created only by maintainers.++**Argument** (`/release <phase> [bump]`): the phase is `prepare` (default), `tag` or+`verify`. For `prepare` the bump is `minor` or `patch` (see step P2).++---++## Phase 1 — `prepare` (on a `release/X.Y.Z` branch from `develop`)++### P1. Preflight. Stop if any check fails++1. On `develop`: `git rev-parse --abbrev-ref HEAD`.+2. The tree is clean (`git status --porcelain` is empty). Otherwise ask the user to commit+ or stash first, so the release changes stay separate.+3. Up to date: `git fetch origin`, then `git rev-list --left-right --count origin/develop...HEAD`+ must show `0` behind and `0` ahead (unpushed commits on `develop` can't reach it any+ more except through a pull request).+4. `## [Unreleased]` has real entries.+5. Once the version is chosen (P2), create the branch: `git switch -c release/X.Y.Z`. This is+ the only branch operation the skill does itself; every later step edits files on it.++### P2. Choose the bump++The app and the engine always move together, by the same kind of bump:++| bump | when | app | engine |+|---------|----------------------------------------------|-----------------|-----------------|+| `minor` | a major feature (new device, view, workflow) | 0.51.2 → 0.52.1 | 0.30.3 → 0.31.1 |+| `patch` | fixes, polish, small additions | 0.51.2 → 0.51.3 | 0.30.3 → 0.30.4 |++A component that resets starts at **1, never 0**. If the user gave no bump, propose one+from the `[Unreleased]` content and confirm it with them. Preview it with+`scripts/release-bump.sh <bump> --dry-run`. It refuses a version whose tag already exists.++### P3. Promote CHANGELOG.md++Rename `## [Unreleased]` to `## [X.Y.Z] — YYYY-MM-DD` (date from `date +%F`). Add a fresh+empty `## [Unreleased]` above it. **Don't touch the entries**: no Highlights and no+rewording. The changelog stays the honest log. Keep the preamble and older sections as they+are.++### P4. Write the curated notes, EN and RU++This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and+`release-notes/X.Y.Z.ru.md`. Each has four parts, in this order:++1. **Summary**: the lede and the numbered headline features, for someone who reads only+ this part.+2. **Full list**: every user-facing change of the release, grouped as Added / Changed /+ Fixed / Removed.+3. **Commit links**: each full-list item ends with a link to its commit.+4. **Contributors**: everyone who has a commit in the release, linked to their GitHub+ profile.++Steps:++1. **Gather.**+ - The previous tag is the highest version tag:+ `git tag --list 'v*' --sort=-v:refname | head -1`. Don't use `git describe` on+ `develop`: release tags sit on `main`'s merge commits, which `develop` doesn't+ contain, so `describe` returns a tag several releases old.+ - Read the whole `[X.Y.Z]` section you just promoted.+ - `scripts/release-credits.sh <prev-tag> origin/develop commits` lists every commit of+ the release (short sha, sha, subject). It's the checklist for the full list.+ - `scripts/release-credits.sh <prev-tag> origin/develop contributors` prints the+ ready Contributors line. It asks GitHub for every commit's authors and co-authors+ (needs `gh` signed in) and leaves out bots and AI co-authors.+2. **Reconcile.** Merge entries that describe the same thing. Where entries conflict (a+ shortcut reassigned twice, a feature added and then reworked), **the code decides**:+ read the handler, the default or the UI and describe what ships. Drop anything that+ was added and then removed within the same release. Then build the full list from the+ commits:+ - Each user-facing change is one item, linked to the commit(s) that brought it. A fix+ and its follow-up make one item with both links.+ - Leave out internal or mechanical commits (refactors, CI, tests, release chores)+ unless a user can feel them. Their authors are still contributors.+ - Walk the `commits` output once more at the end: every user-facing commit must be in+ an item.+3. **Write.** Each language natively, not as a translation. Format: bold titles and `•`+ bullets, no `#` headings, so the text pastes into Telegram as is. The two comment+ markers say where the full list and the contributors start, whatever the language.+ They are invisible on GitHub, and `release-notes.sh` strips them.++ ```+ <!-- SPDX-License-Identifier: AGPL-3.0-only -->+ One or two sentences on what defines this release.++ **1. Biggest user-facing win**+ A short paragraph: what it is and why a musician cares. Not every changelog detail.++ **2. Next feature**+ …++ <!-- changes -->+ **Added**+ • A new capability, one line ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))++ **Changed**+ • A behaviour users must know: a moved shortcut, a changed default ([e4f5a6b](…), [c7d8e9f](…))++ **Fixed**+ • What no longer goes wrong, said from the user's side ([0a1b2c3](…))++ **Removed**+ • …++ <!-- contributors -->+ **Contributors**+ [@login](https://github.com/login), [@other](https://github.com/other)+ ```++ Rules for the format:+ - Rank the summary's sections by importance. A patch release can have just the lede+ before the full list.+ - Groups go in the order Added, Changed, Fixed, Removed; leave out empty groups.+ Inside a group, put the most noticeable changes first.+ - A commit link's text is the 7-character short sha and its URL takes the full sha+ from the `commits` output. These are `develop`'s squash commits. They become part of+ `main` through the develop → main merge, so the links keep working after the release.+ - New notes have no **Also** block: the full list replaces it, so nothing is listed+ twice.+ - RU titles: **Добавлено**, **Изменено**, **Исправлено**, **Удалено**, **Участники**.+ The EN and RU files have the same groups, the items in the same order with the same+ links, and the same contributors.+ - Contributors: paste the `contributors` line. Resolve every `warn:` line it printed+ on stderr:+ - An author with no GitHub login can be a second address of someone already listed+ (the user's work email, for example). Drop that name.+ - Otherwise, find the login and link it, or keep the plain name.+ - Don't add or remove people by hand otherwise.+ - Leave out the title and the download link, because `release-notes.sh` adds them per+ target. Use the user's product language: "track", "device card", "piano roll", not+ class names.+4. Show the user the three renders and iterate until they approve. The rest of the+ release depends on this text.+ - `scripts/release-notes.sh X.Y.Z github` has all four parts.+ - `post-en` and `post-ru` have the summary and the contributors but no full list. A+ Telegram message holds 4096 characters, and the posts end with the link to the+ GitHub release, which has the full list.++ The app bundles the EN file. What's New shows the summary, then "All changes" with the+ groups, then the contributors, and the links in it are clickable. The smoke test checks+ that every full-list item of a shipped notes file ends in a commit link.++### P5. Bump the versions++`scripts/release-bump.sh <bump>` writes `VERSION` and `src/native/nota.engine/VERSION`+(both without a trailing newline, read with `.Trim()` / CMake). The CI checks the tag against+`VERSION`, so the two must agree.++### P6. Feature list and docs++- Run `nota-features` in `audit` mode: fold this version's entries into `FEATURES.md` and+ set its header to `X.Y.Z`. That change goes into the release commit.+- Run `nota-docs` in `audit` mode over the same entries. Its changes are committed in+ `../nota-docs`. Missing docs don't block the release; list them in the report.++### P7. Release image++Build a 16:9 poster in `../media/news/X.Y.Z-src/` (outside the repo). Start from the last+release's `poster.html` (`ls -d ../media/news/*-src | sort -V | tail -1`) and copy its+fonts.++- Header: the logo, `Nota X.Y.Z` (version in brass), a one-line subtitle taken from the+ notes' lede, and a mono tag row with the 2–4 headline features.+- Two or three cards with real screenshots of the headline features. Shoot them from the+ app (see the UI-verify recipe, with an isolated `NOTA_DATA_DIR`) or reuse fresh shots+ from `../nota-docs`. Use Ember Graphite colours (`nota-design`).+- Render it at 2×:++ ```bash+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \+ --hide-scrollbars --window-size=1280,720 --force-device-scale-factor=2 \+ --screenshot="$PWD/../media/news/X.Y.Z.png" "file://$PWD/../media/news/X.Y.Z-src/poster.html"+ ```++- Look at the PNG (Read it) and check for overlaps, clipped text or empty space before+ showing it to the user. Also save the rendered posts next to it as+ `../media/news/X.Y.Z.en.md` and `X.Y.Z.ru.md` (the output of `post-en` / `post-ru`).++### P8. Hand over to the user++Don't commit. Give the user:++- the version change (`app a → b`, `engine c → d`) and the list of changed files:+ `CHANGELOG.md`, `VERSION`, `src/native/nota.engine/VERSION`, `FEATURES.md`,+ `release-notes/X.Y.Z.{en,ru}.md`,+- the commit message `(chore) Release X.Y.Z` and the push command+ `git push -u origin release/X.Y.Z`,+- the **PR into develop**: title `(chore) Release X.Y.Z` (it becomes the squash commit+ message), body = a short list of the changed files,+- the **PR text** for develop → main, opened after the first one is merged. Title+ `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github` (summary,+ full list and contributors), so the reviewer reads exactly what will be published. Merge it with **Create a merge commit**+ (the only method `main` allows),+- the image path and any docs gaps,+- the next step: merge both PRs once CI is green, then run `/release tag`.++---++## Phase 2 — `tag` (on `main`, after the merge)++1. If the user is still on develop, tell them to run `git switch main && git pull --ff-only`.+ Don't switch branches on their tree yourself if it has changes.+2. Run `scripts/release-tag.sh`. It repeats the CI guard locally (on main, clean, equal to+ `origin/main`, the tag is free locally and on origin, the `## [X.Y.Z]` section and both+ notes files exist) and then creates the annotated tag `vX.Y.Z`. **It doesn't push.**+3. Give the user the push command and the Actions link+ (`https://github.com/nota-daw/nota/actions/workflows/release.yml`):++ ```bash+ git push origin vX.Y.Z+ ```++If the script fails, report its message as is. Common causes: the PR isn't merged yet, or+local main is behind. After the tag, `develop` needs no sync: the merge commit on `main`+already has `develop` as a parent.++---++## Phase 3 — `verify` (after the tag push)++1. Find the run: `gh run list --repo nota-daw/nota --workflow release.yml --limit 3`. Wait+ for it with `gh run watch <id> --repo nota-daw/nota --exit-status` (run it in the+ background, because a build takes about 20–30 min). Don't poll in a loop.+2. If a job failed, show its log tail: `gh run view <id> --log-failed`.+3. When it's green, run `scripts/release-verify.sh X.Y.Z`. It checks that the draft body+ equals `release-notes.sh X.Y.Z github` word for word and that all six files are+ attached (dmg arm64/x86_64, exe x64/arm64, AppImage x86_64/aarch64).+4. Report the result. If the body differs (someone edited the draft, or the notes changed+ after the tag), show the diff and fix it at the source. Don't edit the draft by hand to+ make it match. The user reviews the draft and publishes it themselves, then posts+ `../media/news/X.Y.Z.{en,ru}.md` with `X.Y.Z.png` to the channels.++---++## Don't++- Don't commit, push, open PRs, push tags or publish the release. All of these are the+ user's steps.+- Don't reword or summarise inside `CHANGELOG.md`. Curated text goes only to+ `release-notes/`.+- Don't write published text anywhere except `release-notes/`. GitHub and the channels+ must come from the same files.+- Don't type the contributors or commit shas from memory. Take them from+ `scripts/release-credits.sh`, and resolve its warnings instead of ignoring them.+- Don't bump only one of app or engine, and don't reset a component to 0.+- Don't hard-code the date or reuse an existing version or tag.diff --git a/.cursor/skills/nota-design/SKILL.md b/.cursor/skills/nota-design/SKILL.mdnew file mode 100644index 00000000..0b931c2f--- /dev/null+++ b/.cursor/skills/nota-design/SKILL.md@@ -0,0 +1,176 @@+---+name: nota-design+description: Nota's UI design language — "Studio": the work carries the colour, the interface steps back — neutral greys on dark 1px seams, one orange accent reserved for what is live or chosen, sentence-case labels, in colour themes (Studio Dark — the default — Studio Light, Ember Graphite, Ember Paper). Use whenever building or restyling any Nota UI (windows, panels, controls, device cards, custom-drawn views like the piano roll / waveform / arrangement) so everything stays visually consistent. Points at the authoritative token files and the full guideline rather than restating values.+user-invocable: true+---++# Nota design language — Studio++The work carries the colour; the interface steps back. Neutral greys stepped in a+few exact tones (well · ground · panel · raised), flat panels butted against dark 1px+seams, small crisp type, and **one orange accent that appears only where something is+live or chosen**. Colour is a **theme**: one fixed look, dark or light, that gives every+token a value — Studio Dark (the default), Studio Light, Ember Graphite, Ember Paper. The+structure (layout, type, geometry, where the accent goes) is the same in every theme.+Preferences → Appearance picks a theme or Follow system (a dark-mode and a light-mode+theme); the switch is live. `DESIGN.md` is the guideline, plus the exceptions+the project accepted.++## Read these first — do not work from memory++| File | What it gives you |+|---|---|+| `DESIGN.md` | **The guideline.** Rules, colour themes and the readability bar, every Studio token value, elevation, type scales, number setting, controls and states, device cards, shell, the tests, accepted exceptions, known drift. Start here. |+| `DESIGN.html` | The same thing rendered — swatches, control specimens, a device card at true size, a theme toggle. Generated by `scripts/design-html.py`. |+| `src/managed/Nota.App/Theme/Themes/*.json` | **Definitive colour**: one file per theme, one value per token (incl. shadow colours and Fluent's accent ramp). |+| `src/managed/Nota.App/Theme/NotaTheme.axaml` | **Definitive** geometry, type classes, control styles. Holds no colour. |+| `Theme/NotaPalette.cs` · `NotaColourTheme.cs` · `NotaThemeService.cs` | The token slots (the catalogue) and helpers (`Wash`, `InkOn`, `Ink`, `Derived`) · loading and validating themes · applying a theme: slots re-tinted, the same brushes published as `Brush.*`, `Shadow.*` built. |+| `Theme/NotaGeometry.cs` · `NotaFonts.cs` · `NotaText.cs` · `NotaNum.cs` | Radii/sizes/spacing · Geist typefaces and type scale · sentence-case labels · number formatting. |+| `DeviceCardKit.cs`, `Controls/` | The shared controls and card builders; `Controls/NotaGraph.cs` for graph windows. |+| `tests/Nota.SmokeTest/DesignTokenCheck*.cs` | The guard tests (incl. `RunStudio`, `RunThemes`, `RunLabels`, `RunIcons`) and their ratchet lists (`*AllowList.txt`, which only shrink) — run the smoke test after any UI change. |++If `DESIGN.md` / `DESIGN.html` disagree with the theme files, **the theme files win** and+the docs need fixing. Say so rather than propagating the drift.++> This skill deliberately does **not** restate token values. An earlier version did, and+> it drifted a whole palette out of date. Read the files.++## Non-negotiables++Most of these are enforced by `DesignTokenCheck`; the smoke test fails when one breaks.++- **No literals in views.** XAML: `{DynamicResource Brush.*}` / `{DynamicResource Shadow.*}`+ (a `StaticResource` cannot follow a theme change) and+ `{StaticResource Radius.*|Control.*|Space.*}`. C#: `NotaPalette` (a slot,+ `Wash(slot, alpha)`, `InkOn(fill)`, `Ink("#hex")` for a one-off device hue),+ `NotaRadius`, `NotaSize`, `NotaSpace`, `NotaFonts`, `NotaType`. No hex outside `Ink()`,+ no RGB typed as numbers, no `Colors.X` / `Brushes.X` except `Transparent`, no font+ family names, no `new BoxShadows` in a view.+- **Nothing may snapshot a colour.** `new SolidColorBrush(slot.Color)`, a+ `static readonly Color` or brush built from the palette, or a static array of palette+ colours freezes the view in one theme. Use the slot, `Wash`, `InkOn`, `Derived`, a+ property, or read `.Color` inside `Render`. Track colours:+ `ArrangementView.TrackBrush(index)`.+- **Accent = live or chosen, only.** Playing, selected, the playhead, the loop, a toggle+ that is on, a chosen segment, menu hover, the device power switch, and a value control+ *while hovered or dragged*. If it is orange and none of those, it is wrong. **Resting+ values are neutral `VizInk`** — knob arcs, fader and slider fills, value bars, graph+ curves, waveforms. A modulation arc keeps its source chroma. There is no second accent.+- **Semantic fills with derived ink.** Mute on = `Mute` (amber), solo on = `Solo` (blue),+ arm / record on = `Record` (red), solid, with `NotaPalette.InkOn(fill)` for the text or+ glyph — never a fixed label colour on a themed fill. Green is positive status and the+ meter's safe range. Graph chromas (viz ink · teal · rose · blue) live only inside graphs.+- **Seam between, rule within.** Panels meet on `Seam` and so do keys in a segmented+ group; items inside a panel are divided by `Rule` (separators, field edges, graph+ frames).+- **Flat docked, blur only floating.** No gradients, glow or textures. Depth is a tone+ step + a 1px seam + the `Shadow.Raised` top bevel on raised controls. Only a floating+ layer drawn in the main window (`Shadow.Popover`, `Shadow.Modal`) carries a blur; menus+ and popups get a seam ring only (Avalonia clips a popup's shadow at its window edge).+- **Radii 2 / 3 / 4.** `Radius.Clip`/`Badge` 2 for inner keys, rows, clips, menu items;+ `Control`/`Tile`/`Panel`/`Body`/`Pill` 3 for controls, cards, graph windows, popovers;+ `Modal` 4 for modals only; `Docked` 0; `Bar` 1 for bars inside a plot.+- **Geist for words, Geist Mono for every number a user reads.** Names are never mono.+ Nothing under 7 px.+- **Sentence case, no tracking — every label.** Menu items, command titles, palette+ headings, window titles, tooltips, buttons: "Save as…", "Export audio", "Recent". Capitals+ stay only on acronyms and units (`NotaText.Fixed`), "Nota …" product and device names,+ the view names (Arrangement, Session, Modular, Mixer), proper nouns, and a page after+ "Settings: ". Route labels through `NotaText.Label` (it sentence-cases caps literals and+ keeps acronyms and units: `LFO rate`, `Gain dB`). Never `ToUpperInvariant()` a label,+ never set `LetterSpacing`. `RunLabels` fails on an all-caps or Title Case literal;+ `LabelAllowList.txt` is for data only (preset, mode, proper names).+- **Opacity is not a state.** Disabled and muted take the next ink step; use+ `Inactive.Set` for a subtree. The only allowed `Opacity` is a drag ghost.+- **State changes colour only** — never size, border width or position. Hover and colour+ transitions 120 ms ease-out; meters, playhead and spectra are never animated.+- **Numbers are set, not printed.** The app installs a display culture (point decimal,+ U+2212 minus — typed literals too, `"−12"`, never `"-12"`). Put a thin space (` ` in+ source) before units, keep precision fixed (dB one decimal, tempo two, percent whole, Hz+ up to 999 then `3.2 k`) — use `NotaNum` helpers. Ranges take an en dash, closed between+ plain numbers (`1–127`), spaced when an endpoint has a space (`20 Hz – 20 kHz`).+- **Every icon is a `Glyph`.** `Controls/Glyph.cs` is the one icon set: path kinds on a+ 16-unit grid, scaled as a whole (never `Stretch.Uniform`); stroked parts take the shared+ pen (round caps and joins, `max(1.2, size × 1.5/16)`), filled parts the ink (transport+ shapes, the Arrangement / Session view keys, OS marks, `StarFilled`, carets, Snap). A+ missing icon is a new `GlyphKind` with a one-line comment, never a path in a view —+ `RunIcons` fails on `Geometry.Parse`, `Data="M…"` or a path string outside `Glyph.cs`.+ No unicode symbols (`■ ▶ ● ✓ ★ ▾`…) and no emoji as text. `·` separates meta; `→` in+ prose is fine.+- **Copy:** English. Labels one word where it fits, no vowel-dropped contractions+ (`Feedback`, not `Fdbk`; `Freq`/`Reso`/`Thresh` are allowed). Tooltips short and+ verb-first. Empty states are one Ink 5 line.++## Device cards++- **700 × 260** (`DeviceCardKit.CardH`; width exceptions are listed in `DESIGN.md`): panel+ body, radius 3, seam frame.+- **Header 22** (`BuildCardShell` in `DeviceChainView.Shell.cs` — every card uses it,+ racks, the generic instrument card, plug-ins and Sends included; never build a header of+ your own): a raised strip with the `Shadow.Raised` bevel, in fixed slots **name · preset ·+ badges · power**. The preset picker `‹ Name ⌄ ›` is centred in the header between two+ equal halves (name left, badges and power right), only when the device has presets; the badges — the+ type badge (mono, muted, sentence case) and the card's accessories (`HeaderExtra`: Learn,+ S / L) — right-aligned; the power switch (accent while on) last, its slot reserved even+ on a card that cannot be bypassed. A/B, move and delete go in the right-click menu.+- **Body:** inset 6; columns choice → work → output. **Sections are+ `DeviceCardKit.Section(body)`** — no fill, no frame, a 1 px `Rule` on a top or left edge+ facing a neighbouring section (found from the layout, or pass `SectionEdge`); never a+ framed `Border` box. Graph windows and wells keep their frames; chips, tiles, pads and+ readouts are not sections. Titled in `DeviceSection` (muted 600). Device text keeps the+ device scale (7.5–10.5 px) because the frame is kept.+- Values at rest neutral, the accent only for what is live or chosen; modulation shows its+ source chroma; graphs go through `NotaGraph` (well, rule frame, radius 3, `VizGrid`,+ `VizInk` primary curve, accent only on the active node, corner axis labels, no fills+ under curves).++## Adding a control++Reuse before writing: `Knob` (sizes snap to 34/36/44), `DeviceCardKit.KnobCell` (53 tall),+`SwitchTrack` / `DeviceCardKit.Switch` (18 × 10), `DeviceCardKit.Segments`, `SliderTrack` /+`DeviceCardKit.SliderRow`, `MiniFader`, `PanBar`, `VFader`, `DragNumber`, `MeterBar` /+`StereoMeter` / `GrMeter`, `Glyph`, `NaBadge`. Sizes and specs: `DESIGN.md` § Controls.++A new value control **must** match the interaction contract:++- Vertical drag, up increases, full range over ~140 px; Shift/Ctrl/⌘ for fine steps;+ `ns-resize`; a click never jumps the value; no horizontal drag (except a horizontal+ slider along its own axis, `SliderTrack`)+- Double-click restores the default+- Left button only — right-click must bubble to the CV-modulate / MIDI Learn menu+- `GestureBegin` / `GestureEnd` bracket `BeginAutomationWrite` / `EndAutomationWrite`+- Register with `MidiLearn.Bind`+- Live-follow refresher that **skips while dragging**+- Mono readout so width does not jump; the value is always visible, not only in a tooltip+- Its value drawn in `VizInk` at rest and the accent only while hovered or dragged++## Applying it (Avalonia)++- `NotaTheme.axaml` is merged in `App.axaml`; `NotaThemeService` applies the colour theme+ (resolved from settings by `Nota.Application.Appearance`) to both layers. `NotaNum.Install()` runs in `App.Initialize`.+- Buttons: default (raised, seam border, bevel), `primary` (weight and one tone step —+ not colour), `ghost`, `cell` (a readout well), `chip`, `tp-icon`, `tp-play`; a+ `ToggleButton` that is checked is a solid accent key with derived ink.+ `ToggleButton.seg` inside `Border.segmented` (keys butted on 1px seams).+ Containers: `Border.Panel`, `Border.Card`, `Border.well`, `Border.transport`,+ `Border.console`. Fields: `TextBox.field`, `TextBox.search`.+- Text: shell `Title`, `Heading`, `Name`, `Caption`, `SectionLabel`, `CellLabel`,+ `Readout`, `Value`, `Eyebrow`; device `DeviceName`, `DeviceSection`, `RowLabel`,+ `KnobLabel`, `KnobValue`, `Axis`.+- Elevation: `BindResource(Border.BoxShadowProperty, "Shadow.Raised" | "Shadow.Sunken" |+ "Shadow.Popover" | "Shadow.Modal")` — never a literal.++## When you change a token++1. Change the value in each theme file in `Theme/Themes/` it should change in (both Studio+ themes at least). A **new** token is a `T(nameof(X))` slot in `NotaPalette`, a value in+ **every** theme file (the smoke test names a file that lacks it), and a `KeyMap` entry+ if XAML uses it.+2. Every theme must still pass the readability bar (`DESIGN.md` § Readability bar).+3. Run `python3 scripts/design-html.py` and update the table in `DESIGN.md`.+4. Check every theme — in the app and in `DESIGN.html` (`?variant=light`, `?variant=ember-paper`…).++## When you add a theme++Add `Theme/Themes/<id>.json` (every token; `kind` dark or light) and append the id to+`NotaThemes.BuiltInOrder`. Nothing else names a theme. Run the smoke test (`RunThemes`).diff --git a/.cursor/skills/nota-docs/SKILL.md b/.cursor/skills/nota-docs/SKILL.mdnew file mode 100644index 00000000..b648ce49--- /dev/null+++ b/.cursor/skills/nota-docs/SKILL.md@@ -0,0 +1,134 @@+---+name: nota-docs+description: Keep the user documentation (sibling repo ../nota-docs, Astro Starlight, EN + RU) in sync with the app. Run this WHENEVER you add, change or remove a user-visible feature — a new device or parameter, a new view/panel/window, a changed workflow, a moved menu item, a new or re-mapped shortcut, a new Preferences option — i.e. whenever you write a CHANGELOG [Unreleased] entry. Also run it from /release to catch anything that slipped. Handles: finding the affected pages, editing the EN page and its RU twin, re-shooting screenshots (nota-design mockups or the headless app), regenerating the shortcuts page, and building/checking the site.+user-invocable: true+---++# Keeping Nota Docs honest++The user manual lives in **`../nota-docs`** (relative to this repo; GitHub `nota-daw/nota-docs`),+built with Astro Starlight in **English (root) and Russian (`/ru/`)**. It is written by hand,+so every user-visible change in this repo must be mirrored there or the manual lies. The+overall structure and conventions are in `../nota-docs/PLAN.md` — read it once if you have+not.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+`Added` / `Changed` / `Removed` almost always need a docs edit; `Fixed` only when the fix+changes what the docs describe. Pure refactors, perf and internal changes need nothing.++**Argument** (`/nota-docs <arg>`, optional): a feature name, a changelog line, or `audit`+(reconcile *all* `[Unreleased]` entries — used by `/release`). No argument → the change you+just made in this session.++If the page that should cover the change is still a stub (`status: todo`) and you are not+writing it now, append `{page, change, version}` to the `pending:` list at the bottom+of `../nota-docs/coverage.yml` so the stage that writes that page picks it up, tell the user,+and stop.++## 1. Work out what changed for the user++From the diff and the CHANGELOG entry, list concretely: new/renamed UI labels, new+parameters with ranges and defaults, new menu items and where they sit, new shortcuts,+changed behaviour, removed things. Take names and numbers **from the code** (the device's+DSP class and card under `src/managed/Nota.App/DeviceCards/…`, menus in `MainWindow.axaml`,+`PreferencesWindow.cs`), never from memory or the mockup — the changelog itself can be+contradicted by a later entry.++## 2. Find the pages++1. `../nota-docs/coverage.yml` maps features and source paths → page slugs. Look up every+ file you touched and every feature you named.+2. Grep page frontmatter `sources:` in `../nota-docs/src/content/docs/**/*.mdx` for the+ touched paths, and grep page bodies for the old UI label / old shortcut.+3. Nothing found → it is a new feature. Decide its place in the sidebar (see `PLAN.md`),+ copy `templates/page.mdx` (or `templates/device.mdx`) into both+ `src/content/docs/<slug>.mdx` and `src/content/docs/ru/<slug>.mdx`, and add it to+ `coverage.yml`. The sidebar autogenerates per directory (order via `sidebar.order`); only a+ brand-new top-level section needs an entry in `astro.config.mjs`.++Typical fan-out — check all that apply:+- the feature's own page (device, view, panel, preference pane);+- the overview that lists it (Devices index, Views index, "Main window tour");+- `reference/shortcuts` — regenerated, see step 4;+- the glossary, if you introduced a term;+- tutorials that walk through the changed flow (the old steps may no longer work);+- a new built-in device or a renamed device page → the slug maps in+ `src/managed/Nota.App/NotaDocs.cs` (`Instruments` / `AudioEffects` / `MidiEffects`, indexed by+ engine kind) so the device header's Documentation item opens the right page.++## 3. Edit EN, then RU++- English page under `src/content/docs/<slug>.mdx`, Russian twin at+ `src/content/docs/ru/<slug>.mdx` — **same path, same structure, same screenshots**. Never+ leave one language behind; `scripts/check.mjs` fails on a missing or stale twin.+- A stub page (`status: todo`) you fill in becomes `status: draft` (or `done` once its+ screenshots are in); drop the "Being written" aside.+- Bump `updated:` in both frontmatters to the version in `VERSION` (plus `since:` on new+ pages); add any new source paths to `sources:`.+- Style: short, second person, like the CHANGELOG. UI names exactly as on screen in+ **bold**, keys via `<Kbd>`. In Russian, UI names stay in English (the app is English); the+ explanation is native Russian, not a word-for-word translation.+- Removed feature → delete the text and its screenshots; removed page → delete both+ languages, the sidebar entry and the `coverage.yml` entry, and fix links into it.++## 4. Screenshots and generated pages++`../nota-docs/shots/manifest.yml` lists every image (its header documents the scenes and+args). `npm run shots -- <id-prefix> …` retakes them into `src/assets/shots/{dark,light}/`.++- **app** shots render the real UI headlessly (`shots/app`, both themes, 2×, user/device names+ scrubbed). They build against this repo's `src/managed/Nota.App`, so build the app first if+ you changed it. **design** shots come from `../nota-design` (dark only).+- UI that changed visibly → retake its ids (e.g. `npm run shots -- devices/audio-effects/shutter`).+- New device → add `devices/<group>/<slug>/card` (`scene: device` with its kind id) plus one+ shot per tab you document (`args: {tab: "<tab text>"}`, a chain like `"L>Env"` when a size+ switch comes first, `preset` for an interesting state). Write the page from+ `templates/device.mdx`; facts come from the engine header's top comment and `paramName`,+ the card file's header comment and labels, and `FactoryPresetCatalog` — give a range only+ when the code states it.+- New window / view / Settings page → a new scene in `shots/app/Scenes.cs` if none fits; keep+ it deterministic (demo song, no real user data).+- Mockup no longer matches the code → switch that id to `source: app`; never document the mockup.+- A scene breaks after an app refactor (renamed private method, control name) → fix the+ harness; it reflects into `MainWindow` / `PreferencesWindow` privates on purpose.+- Shortcut changed → `npm run shortcuts` regenerates `reference/shortcuts` (EN + RU) from+ `PreferencesWindow.ShortcutGroups`; run the `nota-shortcuts` skill first so that list is+ right.++## 5. Verify and commit++```bash+cd ../nota-docs+npm run build+npm run check+```++Node may not be on PATH (Homebrew's node isn't linked on this Mac) — use+`/opt/homebrew/Cellar/node/*/bin`. The dev server is the `nota-docs` entry in this repo's+`.claude/launch.json` (preview_start).++Both must pass (broken links, missing RU twin, image id not in manifest, `updated:` older+than a touched source). Look at the changed pages in `npm run preview` via the built-in+browser when screenshots or layout changed.++Commit in **`../nota-docs`**, separately from the app repo: `(docs) <what changed>`, no+Claude attribution trailer. Don't push unless the user asked.++## 6. Report++List the pages changed (EN + RU), screenshots re-shot, anything you could not document+(e.g. a scene the harness can't render) and the gaps you left in `coverage.yml`.++## /release audit mode++Go through every `Added` / `Changed` / `Removed` entry of `[Unreleased]`, check each against+the docs as above, fix what's missing, then `npm run build && npm run check`. Report+the coverage to the user before the tag is created; missing docs do not block a release, but+say so plainly.++## Don't+- Don't document plans, mockup-only features or anything not in the code.+- Don't update only one language.+- Don't hand-edit the generated shortcuts page.+- Don't copy CHANGELOG prose verbatim — the changelog says what changed, the docs say how+ to use it now.diff --git a/.cursor/skills/nota-features/SKILL.md b/.cursor/skills/nota-features/SKILL.mdnew file mode 100644index 00000000..7fe279a8--- /dev/null+++ b/.cursor/skills/nota-features/SKILL.md@@ -0,0 +1,104 @@+---+name: nota-features+description: Keep FEATURES.md (the consolidated "what Nota can do" list in the repo root) in sync with the app. Run this WHENEVER you add, change or remove a user-visible capability — a new device or parameter, a new view/panel/window, a new workflow or editing command, a new MCP tool, a new export option, a new platform/build/CI capability — i.e. whenever you write a CHANGELOG [Unreleased] Added/Changed/Removed entry. Also run it from /release in `audit` mode to catch anything that slipped and bump the "as of version" line.+user-invocable: true+---++# Keeping FEATURES.md honest++`FEATURES.md` is the single page that answers "what can Nota do *right now*". It is written+by hand and is not generated from the changelog, so it drifts unless every feature change is+folded into it. It describes **what is implemented in the code**, not plans, and it is a+**current-state** document: no history, no "now", no "previously", no version numbers per+item — that is the CHANGELOG's job.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+- `Added` → almost always a new bullet or an extension of an existing one.+- `Changed` → rewrite the bullet that describes the old behaviour so it describes the new.+- `Removed` → delete the mention (search the whole file — features get cross-referenced).+- `Fixed` → only if the fix changes what the list claims (a limit lifted, a platform now+ supported). Pure bug fixes, refactors, perf and internals need nothing.++**Argument** (`/nota-features <arg>`, optional): a feature name, a changelog line, or+`audit` (reconcile everything since the version in the file's header — used by `/release`).+No argument → the change you just made in this session.++## 1. Find where it belongs++Read the Contents list at the top of `FEATURES.md` and pick the section by what the user+sees, not by which code you touched:++| Change | Section |+|---|---|+| OS support, installers, auto-update, audio/MIDI backends | Platforms and distribution |+| Projects, saving, version history, transport, tempo, loop, metronome | Project and transport |+| Arrangement / Session / Modular / clip editors / piano roll behaviour | Views |+| Track types, routing, sends, groups, mixer window | Tracks and mixer |+| Note editing, MIDI input, MIDI Learn, controllers | MIDI and virtual instruments |+| Recording, audio clips, warp, stretch, stems | Audio: recording, clips, warp |+| Automation lanes, envelopes, modulation | Automation |+| A built-in instrument / audio effect / MIDI effect / rack | Built-in devices → the matching `###` subsection |+| VST3/AU hosting, plugin scanning, plugin windows | Plugin hosting |+| Browser tabs, sample library, presets, smart samples | Browser and assets |+| Render / bounce / stems export | Export |+| Windows, themes, menus, dialogs, Nota Remote UI | Windows and interface |+| A new Preferences option | Preferences |+| A new or changed MCP tool | MCP / AI control (also mention it on the feature's own bullet if it has one, as existing device bullets do: "MCP `read_sampler` / `set_sampler`") |+| Build scripts, CI, tests, licensing | Other |++Before writing, `grep -n` the file for the feature's name and its key words — the feature+may already be partly described (often it is an extension of an existing bullet, e.g. a new+parameter on a device). **Extend the existing bullet rather than adding a duplicate.** If a+genuinely new top-level area appears, add a `##` section *and* its Contents link (anchor =+GitHub slug of the heading).++## 2. Write it in the file's voice++Match the surrounding bullets — read the neighbours first.+- One bullet per feature; **bold** the feature's name at the start, then a dash or colon and+ what it does. Nested bullets only for sub-features of one thing (see Transport).+- English, present tense, plain language a musician understands. State capabilities and+ user-facing names (menu items, tab names, button labels exactly as in the UI), shortcuts+ in the app's glyphs (⌘ ⇧ ⌥, "Cmd/Ctrl" where the file already does).+- Concrete over vague: parameter names, modes, counts ("25 factory presets", "Poly 16 /+ Mono / Legato") — but verify each number in the code/presets, don't copy it blindly from+ the changelog.+- Condense. The changelog entry explains the change; FEATURES states the result in roughly+ half the words. No rationale, no "fixes", no internal class names (file paths only in+ Other / Platforms, as already done there).+- Built-in devices: follow the existing device bullet shape — what it is · its main controls+ and modes · tabs/sizes of the card · preset count · MCP tools if any.+- Hard-wrap at ~90 columns like the rest of the file.++## 3. Verify against the code++The changelog can be ahead of, or behind, reality. For each claim you add, confirm it in the+source (device kind registration, the view/menu code, the MCP tool list in the MCP server,+the preset folder). If something in the changelog was later reverted or is behind a flag+that is off by default, leave it out (or say "experimental, off by default" if the user can+turn it on).++## 4. `audit` mode (from /release)++1. Read the version in the header line ("as of version **X.Y.Z**").+2. Collect every `CHANGELOG.md` entry newer than that version: all `## [A.B.C]` sections+ above `## [X.Y.Z]`, plus `[Unreleased]` / the section being released right now.+3. For each `Added` / `Changed` / `Removed` entry (and relevant `Fixed`), check whether+ `FEATURES.md` reflects it; fix what is missing or stale per sections 1–3.+4. Update the header: set the version to the one being released (or the latest released+ version when run outside a release), keep "(plus changes in development on `main`)".+5. Report the list of entries you added/changed in FEATURES.md and anything you+ deliberately skipped (and why).++## 5. Finish++- Re-read the edited section as a whole: no duplicates, no contradictions with other+ sections, Contents still matches the `##` headings.+- The SPDX header on line 1 stays.+- Commit FEATURES.md together with the feature (or the release commit in audit mode);+ don't make a separate commit unless the user asks.++## Don't+- Don't paste changelog entries verbatim, and don't add dates or version tags to items.+- Don't describe planned, unmerged or disabled-by-default work as available.+- Don't reorganize or restyle sections you weren't asked to touch.diff --git a/.cursor/skills/nota-instrument/SKILL.md b/.cursor/skills/nota-instrument/SKILL.mdnew file mode 100644index 00000000..81ffc46e--- /dev/null+++ b/.cursor/skills/nota-instrument/SKILL.md@@ -0,0 +1,238 @@+---+name: nota-instrument+description: How to build a Nota built-in instrument, audio effect or MIDI effect end-to-end — the DSP class, the kind-registration checklist across the C++ engine and C# managed layers, and the device-card UI design approach (signal-chain panels, tabs, the shared gauge knob, interactive graphs, using the card space well). Use whenever adding or reworking a built-in synth / audio effect / MIDI effect or its editor. Reference implementations: Nota Volt (instrument), Nota Vintage / Auto Filter (audio effect), Nota Arp (MIDI effect).+user-invocable: true+---++# Building a Nota built-in instrument, effect or MIDI effect++This skill covers **all three built-in device families** — an **instrument**+(the track's sound source), an **audio effect** (an insert `Device`), and a+**MIDI effect** (a `MidiDevice` that transforms notes before the instrument).+The DSP conventions (§1) and card design (§3) are shared; only the base class,+the **registration path (§2)** and the **card interface (§3)** differ — effects+and MIDI effects register through a much lighter path than instruments.++The canonical example is **Nota Volt** (virtual-analog synth, kind 6):+`src/native/nota.engine/src/devices/instruments/VoltSynth.h` + `.cpp` (DSP) + `DeviceCards/Instruments/VoltInstrumentCard.cs` (UI).+Its editor is the reference build of the card layout — **read it first when designing+a synth UI, together with `DESIGN.md` § Device cards and the rendered specimens in+`DESIGN.html`.** Good+effect exemplars: **Auto Filter** and **Nota Vintage** (audio, `: public Device`),+**Nota Arp** (MIDI, `: public MidiDevice`). Also load the `nota-design` skill.++Built-in **instruments** (`kind()` ≥ 0): 0 Synth, 1 Sampler, 2 Physical (modal),+3 Instrument Rack, 4 Drum Rack, 5 Aurora (wavetable), 6 Volt, 7 Bass. **Audio+effects** (`builtinKind()`): 0 EQ, 1 Compressor, 2 Reverb, 3 Delay, 4 Utility,+5 Effect Rack, 6 Amp, 7 Auto Filter, 8 Vintage. **MIDI effects** (`midiKind()`):+0 Arp, + Chord / Scale / Note Length / Velocity / Random. **Grep the current+registration for the next free kind before picking one** — this list drifts.++## 1. DSP class (`.h` + `.cpp` pair)++Put the device in its family folder — `src/native/nota.engine/src/devices/+instruments/<Name>.h` + `.cpp` (`final : public Instrument`), `devices/effects/`+(audio effect, `: public Device`, in-place stereo `process(buf, frames)`), or+`devices/midi_fx/` (`: public MidiDevice`, MIDI effect) — and add both files to+`src/native/nota.engine/CMakeLists.txt`. The header declares, the TU implements;+**every new file carries the AGPL SPDX two-line header. Allocation-free after+construction** (pre-size buffers). Rules:++- **Parameters via the plugin-param interface** (`pluginParamCount/Id/Name/Get/Set/+ IndexOfId`). Values are **normalized 0..1** in `std::atomic<float> pn_[N]`+ (audio-thread read). Denormalise inside `render()` to musical units+ (`expMap(v, lo, hi)` for time/cutoff/rate; bipolar = `(v-0.5)*2`; discrete =+ `round(v*(n-1))`). This gives **automation, persist and clone for free** — the+ engine already routes `PluginParam` + `deviceIndex<0` to `instrument->pluginParamSet`.+- **Param order = the persisted state layout — APPEND ONLY.** `getState`/`setState`+ serialize `N` little-endian floats; `setState` tolerates a shorter/longer blob.+ `clone()` copies `pn_` + sample rate. Ids are stable strings; names are display.+- **DSP conventions:** 16 voices, per-sample outer loop when modulation must stay+ smooth; recompute expensive filter coefficients at control rate (every ~16+ samples), not per sample — control-rate math stays `std`-exact, `FastMath`+ applies only to downstream/published sample values. Steal the quietest voice. polyBLEP saw/square if you+ care about aliasing (Volt/Aurora do); a TPT/Cytomic SVF gives LP/HP/BP/Notch+ from one filter (`dsp/primitives/` has the shared SVF, ladder, biquad, delay,+ oscillator, envelope, oversampler and convolution blocks — reuse them, don't+ re-implement). `kind()` returns the new integer; `displayName()` the label.+ Support auto-sleep (`hasTail()`/`isIdle()`/`wake()`): sleep only fully decayed+ blocks, never a frozen loop; the engine never skips `process()` — your own+ skip must advance phases so the device resumes seamlessly.++## 2. Registration checklist (mirror an existing kind)++Grep the exemplar and copy every site. **Instruments** carry the most sites+(they need their own track + C ABI); **audio/MIDI effects register through a much+lighter path — see the end of this section.**++### Instruments (`grep -rn Volt` / `grep -rn Aurora`)++**Native:** `Engine.h` decl `add<Name>Track`; `Engine_Devices.cpp` (the method ++`#include` + `cloneInstrument` switch + `makeBuiltinInstrument` switch);+`devices/racks/RackCore.h` `makeInstrument` switch + include; C ABI+`nota_engine_add_<name>_track` in `src/abi/nota_engine_track.cpp` **and** the decl in+`include/nota/nota_engine.h` (the `_nota_*` export list is a wildcard — no change).++**Managed:** `NativeMethods.Tracks.cs` (`[LibraryImport]`), `NotaEngine.Tracks.cs`+(wrapper), `IAudioEngine.cs` (interface); `Nota.Application/Palette/BuiltinDeviceCatalog.cs`+(the one device list the browser and the command palette read: name, `Kind = N`, sub text **and+a semantic descriptor** — role, aliases, character, sound/source, genre, a one-line+description; the palette smoke test `--palette` fails without a role and aliases), and its+browser category in `Nota.Application/Palette/DeviceCategories.cs` (the category chip it is listed+under — Synths, Dynamics…; the `-- design: browser --` check fails until it has one);+`DeviceInsertService.CreateInstrumentTrack` in Nota.Presentation (`N => Engine.Add…` — the+one place drag & drop, the browser and the palette create the track);+`ProjectService.cs` (`{ Kind: N }`) + `PresetService.cs` (`N =>`); rack/drum+"add chain / add pad" menus in `DeviceCards/Rack/RackCardView.cs`+(`AddChainButton`, `ShowAddPadMenu`).++**Automation menu:** built-in instruments (`TrackInstrumentKind >= 0`) must list+their params *directly, grouped* via `BuildBuiltinInstrumentAutoMenu`+(`ArrangementView.Automation.cs`) — NOT the hosted-plugin "Choose parameter…/Learn"+picker (that path made empty-id lanes → "drew a curve, no effect").++### Audio effects (`grep -rn AutoFilter` / `grep -rn Vintage`) — much lighter++No track, no C ABI, no `Engine.h` method: effects are added generically by+`addTrackBuiltinDevice(trackId, kind)`. Only:+- **Native:** the `.h`/`.cpp` pair in `devices/effects/` with `: public Device` and `builtinKind()` returning the kind,+ then register that kind in the **three switches** in `Engine_Devices.cpp` —+ `addTrackBuiltinDevice` **+** `cloneDevice` **+** `makeBuiltinDevice` — plus the+ `#include`. Params use the plain `Device` interface (`paramCount/paramName/+ paramMin/paramMax/getParam/setParam`); **prefer normalized 0..1** (mirror+ AutoFilter/Vintage, not the older raw-unit Amp/EQ). Persist / clone / automation+ are **generic** through the base `Device` (by `builtinKind()` + params) — no+ `getState`/`setState`, no per-kind managed persist code.+- **Managed:** `DeviceCardFactory` `[kind] = new NameDeviceBody()`; a+ `BuiltinDeviceCatalog.cs` entry (`AudioEffect`, kind N, with its semantic descriptor —+ role, aliases, character, source, task) and its category in `DeviceCategories.cs`. The add/drop path (`DeviceInsertService`) is+ already generic. Factory presets get their descriptor from their folder and name+ (`PresetDescriptors`); a new folder whose name isn't vocabulary goes into its folder map.++### MIDI effects (`grep -rn Arpeggiator` / `grep -rn MidiScale`)++Mirror an existing `MidiDevice` (e.g. `devices/midi_fx/Arpeggiator.h`) with `midiKind()`; register+in the engine's MIDI-device factory + `MidiDeviceCardFactory` `[kind]` + a `MidiEffect`+entry with its descriptor in `BuiltinDeviceCatalog.cs` (and its category in `DeviceCategories.cs`). Params/persist/clone are generic like audio effects. Cards sit+**before** the instrument in the chain.++## 3. Editor card architecture++Cards are **strategy classes under `src/managed/Nota.App/DeviceCards/`**, resolved by+a factory and handed a `DeviceCardContext` — `DeviceChainView` is a thin orchestrator+(row + registries + the 60 Hz `RefreshSynthLive` tick) and builds nothing itself.+To add an editor, write a class and register it — no `switch` to edit (open/closed):++- **Instrument** (kind ≥ 0, the track's instrument): `class NameInstrumentCard :+ IInstrumentCard` in `DeviceCards/Instruments/`, `Control Build(DeviceCardContext ctx)`;+ register `[kind] = new NameInstrumentCard()` in `InstrumentCardFactory`.+- **Audio effect** (device): `class NameDeviceBody : IDeviceBody` (`double Width`,+ optional `bool AutoWidth => true` to size the card to its content,+ `Control Build(ctx, deviceIndex)`) in `DeviceCards/Bodies/`; register in+ `DeviceCardFactory`. The shared device shell (bypass/reorder/remove) wraps it —+ the body has NO instrument live-follow; use `ctx.AddDeviceRefresher(a)` for the+ 60 Hz visual and read/write params with `engine.DeviceGetParam/DeviceSetParam` ++ `BeginAutomationWrite/EndAutomationWrite` (see `AutoFilterDeviceBody`/`VintageDeviceBody`).+- **MIDI effect**: `class NameMidiBody : IMidiDeviceBody` in `DeviceCards/Midi/`;+ register in `MidiDeviceCardFactory`. The racks live in `DeviceCards/Rack/RackCardView.cs`.++Everything a card needs comes through **`ctx`** (never reach into the view): `ctx.Engine`,+`ctx.TrackId`; `ctx.AddDeviceRefresher(a)` for a 60 Hz visual; `ctx.AddInstFader(i,knob,val)`++ `ctx.SetInstLiveViz(refresh)` for instrument live-follow; `ctx.NotifyChanged()` /+`ctx.RequestRebuild()` / `ctx.RequestPresetSave(i)`. Stateless strategies are singletons —+all per-rebuild state stays behind `ctx`. Shared builders: `DeviceParamControls` (param+faders + sidechain), `InstrumentControls.InstKnob`, `SamplerEditor`.++Follow the mockup language:++- **A device card is a fixed rectangle**, height `CardH` (260, shared by all cards)+ — content taller than that is clipped (`ClipToBounds`). **Gotcha:+ `SimpleCard(title, width, body)` — the 2nd arg is WIDTH; height is always CardH.**+- **Use the working space deliberately — no dead space, nothing overflowing.**+ Fill the card's width with content and don't leave a half-empty card or let+ panels spill past the edge. Size each panel to its own controls, then make the+ card track that: either set `Width` to the sum of the panels, or (audio effects)+ set `AutoWidth => true` so the card sizes to content exactly — the safest way to+ guarantee "it all fits". Lay bordered **islands** side by side and give a large+ interactive graph its **own** framed island next to the knob panels (Nota Vintage:+ CHARACTER / WEAR / SHAPE). If the content genuinely can't fit 260px tall at a sane+ width, **split into tabs** (below) rather than shrinking every control. Always+ do the visual check and trim leftover margins.+- **If there's more than one logical section, use tabs** inside the card (e.g.+ Signal Path / Modulation) with a segmented toggle styled like the Devices/Clip+ segment, swapping a `ContentControl`. One section = one horizontal row that fits+ 260px tall.+- **Card sizes (S / L) are views of ONE device, never two devices.** When a mockup gives a+ device a mini (S, 260) and a full (L) size (Nota Arp is the reference):+ - **Presets belong to the device, not to the size.** Both sizes show the same preset+ picker with the **full** preset list and the **same current preset** — pick a preset in+ L, flip to S, it is still selected there (and vice versa). S may edit fewer params, but+ a preset still sets all of them. Never swap the picker for another control in S; the+ shell's `ShellSpec.Compact` only narrows it (and hides the type badge).+ - Every value is shared; S just exposes a subset (e.g. 4 knobs). No per-size params.+ - The size itself is **editor state**: store it in an appended param (`View`, 0 = L,+ 1 = S) so it persists with the project and clones, but keep it out of presets (in-place+ preset apply skips `View`), and out of the automation menu.+ - Plumbing (MIDI effects): `IMidiDeviceBody.WidthFor(engine, track, index)` returns 260/700+ from `View`; `HeaderAccessory(ctx, index)` puts the S/L toggle (and L-only extras) in the+ shell header; the toggle writes `View` and calls `ctx.RequestRebuild()`. Per-card UI+ state that should survive the rebuild (active tab, selected lane) lives in a static map+ keyed by (track, index), not in the singleton body.+ - Plumbing (instruments, Nota Synth is the reference): append a `"view"` plugin param to the+ DSP (its default in the constructor is the instrument's default size — Synth opens as S);+ `InstrumentView` (Nota.Application) finds/reads/writes it, and presets, A/B, the automation+ menu (by id) and the rack chain card (by the name "View") already skip it. The card implements+ `IInstrumentCard.WidthFor(engine, track)` + `HeaderAccessory(ctx)` with+ `MidiCardHeader.SizeToggle(ctx, isMini, setMini)`; the shell goes compact under 300px.+- **Lay panels as a signal chain**: bordered titled sections left→right with `▸`+ arrows (Osc → Noise → Filter → Amp). Each panel = `Border` (SurfaceCard fill,+ 1px border, radius 7) with a bold section title.+- **Controls, in order of preference for space:**+ - The shared **gauge `Knob`** via `InstrumentControls.InstKnob(ctx, idx, id, name, refresh, size, cellW, arc)`+ — 270° groove + value arc + pointer. Pass a teal `arc` for **modulation-depth**+ knobs (env/lfo/key amounts, velocity, vibrato); amber (default) for everything+ else. Double-click resets to the param default.+ - **`KnobGrid(cols, …)`** packs knobs into centered rows (2×2, or vertical for+ 1 col) to shrink a panel; a partial last row stays centred.+ - **Interactive graphs are controls, not decoration**: a drag ADSR editor+ (`VoltEnv`) and a drag filter response (`VoltFilter`, X=cutoff / Y=reso, curve+ follows the type, with grid + fill + freq/dB axes + cutoff handle). They replace+ ~a dozen knobs and should FILL their panel via a `DockPanel` (header docked+ top, graph stretches).+ - **Selectors:** waveform = icon chips (`WaveIcon`), filter type = text chips,+ small A/B or Fil1/Fil2 = segmented `Seg` toggles. Not combo-boxes unless a list+ is long.+ - Live values in `Font.Mono`; tiny UPPERCASE section/knob labels.+- **Live follow:** call `ctx.SetInstLiveViz(Refresh)` and register knobs via+ `ctx.AddInstFader(...)` (InstKnob does this for you); `RefreshSynthLive()` (driven by+ the playhead tick) re-reads params so automation playback moves the UI. Keep a+ `readouts` list of `Action` for numeric captions / graphs and call them in `Refresh`.++Colours/tokens: never hardcode — reuse the `DeviceCardKit` brushes (`Card2`, `BorderDef`,+`Brass`, `Teal`, `Sunken`, `TextPrimary/Secondary/Tertiary`, `AccentBright`), in scope via+`using static Nota.App.DeviceCardKit;` — along with `SimpleCard`, `KnobCell`, `ChipRow`,+`Labeled`, `Glyph`, `Pct`, `NoteName`. See `nota-design`.++## 4. Presets & verification++- **Factory presets:** instruments use `Inst("<group>", N, "Name", ("paramid", v), …)`;+ audio/MIDI effects use `Fx(…)` / `Midi(…)` with **param NAMES** (not ids) in+ `FactoryPresetCatalog.cs` (values normalized 0..1 for the newer devices; bipolar+ knobs neutral at 0.5). ~6 covering the useful range.+- **Smoke test** (`tests/Nota.SmokeTest/Program.cs`): assert kind/`builtinKind`,+ name, param count, param round-trip, clone (duplicate the track), and that each+ mode renders audible + finite (RMS>0). Instruments add a track + note; effects+ do `AddBuiltinDevice(track, kind)` over an audio clip and check `DeviceName`/+ `DeviceGetParam`. Run `dotnet run --project tests/Nota.SmokeTest`.+- **Visual check** (no click automation on macOS — see `nota-ui-verify`): add a+ temporary `NOTA_DEBUG_SESSION`-guarded block at the end of+ `MainWindow.OnDataContextChanged` (a `DispatcherTimer` firing ~2.5 s). For an+ instrument add its track; for an effect add an **audio** track ++ `Engine.AddBuiltinDevice(t, kind)` (an audio track has no instrument card, so the+ effect card is first and not pushed off-screen); then `ShowDevices(t)`. Launch+ with the env var, `screencapture`, crop with `sips`, then **revert the hook and+ rebuild.** To shoot a non-default tab, briefly flip the tab's default `Content`.++Build native (`cmake --build build --target nota_engine`) and managed+(`dotnet build src/managed/Nota.App`) after each layer; the C ABI is wildcard-+exported so a new `_nota_*` function needs no export-list edit.diff --git a/.cursor/skills/nota-pr/SKILL.md b/.cursor/skills/nota-pr/SKILL.mdnew file mode 100644index 00000000..fbb43dc1--- /dev/null+++ b/.cursor/skills/nota-pr/SKILL.md@@ -0,0 +1,124 @@+---+name: nota-pr+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the contributor's own git identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".+user-invocable: true+---++# Opening a pull request++A Nota PR is reviewed by reading its description, so the description carries the proof: what+changed, why, and what it looks like or costs before and after. Images and benchmark charts+never go into `develop` — they live on the orphan **`pr-assets`** branch (see+`CONTRIBUTING.md` § Images for pull requests) and are embedded by raw URL.++## 1. Branch and commit++- Branch from `develop` (never `main`): `git checkout -b <type>/<slug>` — `fix/…`, `feat/…`,+ `docs/…`, `chore/…`. If the work is already on `develop` uncommitted, create the branch+ first; the working tree comes along.+- `scripts/build.sh` (or `build-linux.sh` / `build-win.ps1`) must pass — it runs the smoke test.+- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a body+ that says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no+ "Generated with" line) in commits or the PR body.+- Author and committer: whoever makes the change, from their own git config. Never set+ `user.name` / `user.email` / `--author` to someone else's identity.+- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change they+ describe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.++## 2. Decide what evidence the PR needs++| The change… | Attach |+|---|---|+| alters anything the user sees (a window, panel, device card, menu, theme, layout, custom-drawn view) | **before / after screenshots**, same size, theme and content |+| aims at or may affect performance (engine render path, DSP, threads, allocation, CPU, memory, startup) | **benchmark**: before vs after (and vs the last good build when fixing a regression), with charts + a table |+| both | both |+| neither (docs, refactor with no runtime effect, CI) | nothing — say so in the Summary |++When unsure whether a change is user-visible, run the app and look.++## 3. Screenshots (UI changes)++1. Capture **before** on the base commit and **after** on the branch, with the same window size,+ theme (default Studio Dark unless the change is theme-specific — then one pair per theme),+ interface scale and project content. Reuse the capture tooling the `nota-design` /+ `nota-docs` skills describe (headless Avalonia render or the app's own capture hook) rather+ than hand screenshots, so both shots are pixel-comparable.+2. Name them `<what>-before.png` / `<what>-after.png`; a side-by-side `<what>-both.png` is+ welcome for small changes.++## 4. Benchmarks (performance changes)++Two layers, and a performance change needs both:++- **Regression guards** — `tests/Nota.SmokeTest/RenderPoolTests.cs`, part of every smoke run+ (`scripts/build.sh`, CI on all three platforms; alone: `dotnet run --project+ tests/Nota.SmokeTest -c Release -- --perf`). Hardware-independent checks: render threads+ idle at ~0 CPU (their own thread clocks), parallel vs single-thread CPU ratios while playing+ and bouncing, bounce not slower than one thread, bit-identical output, tracks edited while+ rendering. When you touch the render path, threading or allocation, keep these green; when+ you fix a performance bug, add a guard here that fails on the old code (prove it: put the+ old behaviour back briefly and watch the check fail).+- **Benchmark numbers** for the PR description, below.++The engine benchmark is in the repo:++- `scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...` — links+ `scripts/bench/engine-bench.cpp` against each Release `libnota_engine` and runs idle, offline+ render (bounce) and real-time-paced scenarios for audio and synth tracks, interleaving the+ builds run by run. Writes `results.csv` + `machine.txt`.+- `scripts/bench-chart.py <out-dir> <label>="Display name" ...` — medians, three charts+ (`cpu-playing`, `bounce-time`, `bounce-cpu`; SVG + 2x PNG) and `summary.md` (tables + machine).++Recipe:++1. Build each revision you compare **in Release**, each in its own checkout so nothing is shared:+ `git worktree add --detach /tmp/nota-<label> <commit>`, then configure + `ninja nota_engine` in+ its `src/native/nota.engine/build`. Revisions before the CPM switch (#212) need+ `git submodule update --init --recursive --depth 1` first. The branch itself can use the main+ `build/` dir (it must stay Release).+2. Copy each `libnota_engine.*` into its own folder (`/tmp/bench/libs/<label>/`) so later rebuilds+ don't change what you measured.+3. Run on a quiet machine, on power, ≥3 runs: `scripts/bench-engine.sh -r 3 /tmp/bench/out+ before=… after=…`. Look at the spread in `results.csv`; rerun if runs disagree a lot.+4. Chart it: `scripts/bench-chart.py /tmp/bench/out before="Before" after="This PR"`. Open the+ PNGs and check them (labels, overlap) before attaching.+5. Report honestly: put regressions in the table too and say why they're acceptable or what+ follows up. A benchmark also needs the commits measured and the machine (from `machine.txt`).++If the change needs a scenario the harness lacks, extend `engine-bench.cpp` (stick to C ABI+functions every compared build exports) and the scenario list in `bench-engine.sh`, in the same PR.++## 5. Put the assets on pr-assets++One folder per PR, named after the change or issue (`fix-pr212-review/`, `issue-223/`). Commit on+top of `pr-assets` — never force-push or rewrite it; old PRs link to its files.++```sh+git fetch origin pr-assets+git worktree add /tmp/nota-assets origin/pr-assets -B pr-assets+mkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/+git -C /tmp/nota-assets add <folder>+git -C /tmp/nota-assets commit -m "Images for <change>"+git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \+ push https://github.com/nota-daw/nota.git HEAD:pr-assets+git worktree remove /tmp/nota-assets+```++For benchmarks commit the CSV and `summary.md` next to the charts, so the numbers stay checkable.+Embed with `https://raw.githubusercontent.com/nota-daw/nota/pr-assets/<folder>/<file>.png`.++## 6. Push and open the PR++- Push over HTTPS (SSH push to nota-daw/nota is denied):+ `git -c credential.helper= -c credential.helper='!gh auth git-credential' push -u https://github.com/nota-daw/nota.git <branch>`,+ then `git fetch origin <branch> && git branch -u origin/<branch>`.+- `gh pr create --repo nota-daw/nota --base develop --head <branch> --title "<commit-style title>" --body-file <file>`.+- Body: follow `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Spec, Checklist — tick only what was+ actually done; leave platforms you didn't build unticked). Add sections as needed:+ - **Screenshots** — a table, before | after:+ `| Before | After |` / `|---|---|` / `|  |  |`+ - **Benchmark** — the charts, the `summary.md` tables, the commits measured, the machine, and+ a sentence on how to reproduce (`scripts/bench-engine.sh …`).+ - **Testing** — what was run and what was not.+ - Link the issue (`Fixes #N` / `Refs #N`) and, for review follow-ups, the PR being followed up.+- Base is `develop`. Don't enable auto-merge; don't merge.diff --git a/.cursor/skills/nota-shortcuts/SKILL.md b/.cursor/skills/nota-shortcuts/SKILL.mdnew file mode 100644index 00000000..416d537b--- /dev/null+++ b/.cursor/skills/nota-shortcuts/SKILL.md@@ -0,0 +1,66 @@+---+name: nota-shortcuts+description: Keep the Preferences → Shortcuts screen in sync with the app's real keyboard/mouse bindings. Run this WHENEVER you add, remove, or change a keyboard shortcut or mouse gesture (transport keys, editing commands, piano-roll keys, the computer-keyboard note map, device drag, etc.) — the Shortcuts pane is a hand-maintained list and silently drifts from the handlers otherwise. Handles: finding every place bindings are defined, updating the on-screen list, and visually verifying it.+user-invocable: true+---++# Keeping the Shortcuts screen honest++Nota shows its keyboard/mouse shortcuts in **Preferences → Shortcuts**. That list is+**hand-written**, not generated from the handlers — so every time the input handling+changes, the screen must be updated by hand or it lies to the user. This skill is the+checklist for doing that.++**Trigger:** you touched anything that changes what a key or mouse gesture does — a new+hotkey, a re-mapped key, a removed command, a changed computer-keyboard note layout, a new+drag gesture. If your change added/removed/moved a binding, you are not done until the+Shortcuts pane matches.++## 1. The on-screen list (what to edit)++`src/managed/Nota.App/PreferencesWindow.cs` → the static **`ShortcutGroups`** array (feeds+`ShortcutsPane`). It's grouped: `TRANSPORT`, `ARRANGEMENT & EDITING`, `PIANO ROLL`,+`PLAY NOTES (COMPUTER KEYBOARD)`, `MOUSE`. Each row is `(Key, Action)`; the `Key` string is+split on spaces and each token becomes its own mono key-cap (`/` and `·` stay plain+separators) — as long as every token is a key: no lower-case letters, or one of `Space`+`Return` `Delete` `Tab` `Esc` (`IsKeyToken`). Anything else (`Drag note edge`, `Face+buttons`) is a gesture and shows as plain text. The `Action` is a short sentence. Use `⌘` for Meta/Ctrl, `⇧`+for Shift, `⌥` for Alt, and the arrow glyphs `← → ↑ ↓`. Keep actions imperative and terse+(design language: sentence case, `·`/` / ` as separators).++## 2. The source of truth (where bindings actually live)++Read these and reconcile the list against them — do **not** trust the existing pane text:++| Bindings | File |+|---|---|+| Transport (Space/Return), global editing (A, R, M, ⌘M, ⌘G/⌘⇧G, ⌘C/X/V, Delete, Tab, Esc) and the **computer-keyboard note map** (`KeyToPitch`) | `src/managed/Nota.App/MainWindow.Input.cs` |+| Piano-roll note editing (arrows, ⇧ octave, ⌘A/⌘D, ⌘C/X/V, Delete, Esc) | `src/managed/Nota.App/PianoRollView.cs` (its `OnKeyDown`) |+| Arrangement lane / clip gestures (double-click, drag) | `src/managed/Nota.App/ArrangementView*.cs` |+| Device reorder drag | `src/managed/Nota.App/DeviceChainView.cs`, `DeviceCards/…` |++`KeyToPitch` is the note layout: bare letters play notes, and `A` is **deliberately not** a+note (it toggles automation mode) — so the "Play notes" rows must never list `A`. When that+map changes, update the `PLAY NOTES` group (white vs. black keys, and the starting octave).++## 3. Procedure++1. List, from your own diff, every binding you added/changed/removed.+2. Open the source-of-truth file(s) above and confirm the *current* behaviour of each key in+ the affected group — including ones you didn't touch, since the list may already be stale.+3. Edit `ShortcutGroups` so every row matches. Add a row for a new binding, delete a row for a+ removed one, fix the key-cap or wording for a changed one. Put it in the right group.+4. Build: `dotnet build src/managed/Nota.App -c Debug`.+5. Visually verify (see [nota-ui-verify] memory): the pane can't be reached by a click in a+ headless run, so temporarily open it via an env-guarded hook in+ `MainWindow.OnDataContextChanged` (`new PreferencesWindow(new SettingsViewModel(settings),+ _vm).Show(this)`), and select the Shortcuts section (index 8 — count the sidebar entries, it moves as pages are added) — e.g. a temporary env read+ in front of the constructor's `Select(0)`. Screenshot with `screencapture -x -o -l<winid>`+ (get the id from the `winlist` swift helper), check the rows read correctly, then **revert+ the temp hooks** and rebuild.++## 4. Don't forget++- If the change is user-visible, it also wants a `CHANGELOG.md` entry under `## [Unreleased]`.+- Keep the pane concise — it's a reference, not a manual. Group related keys onto one cap+ (`⌘C ⌘X ⌘V`) rather than three rows when the action is one idea.diff --git a/.cursor/skills/release/SKILL.md b/.cursor/skills/release/SKILL.mdnew file mode 100644index 00000000..8c85be7e--- /dev/null+++ b/.cursor/skills/release/SKILL.md@@ -0,0 +1,289 @@+---+name: release+description: Cut a Nota release in three phases. `prepare` (on a release/X.Y.Z branch from develop) promotes CHANGELOG.md [Unreleased] to a dated version, writes the curated EN + RU release notes in release-notes/ (the one source for the GitHub release and the news channels), bumps the app and engine versions, makes the release image and the PR texts. `tag` (on main, after the user merged the release PR into develop and the develop → main PR) creates the vX.Y.Z tag. `verify` (after the user pushed the tag) waits for the build and checks the GitHub draft against the curated notes. Run this when the user asks to release, ship, cut a version, tag a release or check a release build.+user-invocable: true+---++# Cutting a Nota release++Two files describe a release, for two readers:++- **`CHANGELOG.md`** is the raw working log. Entries land under `## [Unreleased]` as work+ merges ("what we did, we write"), so it can repeat itself or hold changes that a later+ entry undid. At release time it is only promoted to `## [X.Y.Z] — date` and is never+ rewritten. The CI guard requires the section, and What's New falls back to it for a+ version without curated notes.+- **`release-notes/X.Y.Z.en.md`** and **`release-notes/X.Y.Z.ru.md`** are the curated+ text: summarised, deduplicated, checked against the code. **Everything published comes+ from them**, and the app bundles the EN file for its What's New window, so the notes must+ be committed on the release branch before the tag is built. They hold a summary, the+ full Added / Changed / Fixed list with a commit link on each item, and the contributors+ (format in P4). `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:++ | target | where it goes | full list |+ |-----------|-------------------------------------------------|-----------|+ | `github` | GitHub release body (the workflow uses this) | yes |+ | `post-en` | English news channels | no |+ | `post-ru` | Russian news channels | no |++The release runs through the branches like this. **The user does every commit, push and PR+by hand.** This skill never commits, pushes or opens a PR (see the user-commits rule).++```+release/X.Y.Z ── /release prepare ── user commits, pushes, opens PR → develop (squash)+develop ── CI green, user merges ── user opens PR develop → main (merge commit)+main ── CI green, user merges ── /release tag ── user pushes the tag+CI ── release.yml builds 6 files + draft release ── /release verify ── user publishes+```++`develop` and `main` are protected (rulesets): changes land only through a pull request+with the `macOS`, `Windows` and `Linux` CI checks green; `develop` takes squash merges,+`main` takes merge commits only, so `develop` → `main` never rewrites history. Release+tags `v*` can be created only by maintainers.++**Argument** (`/release <phase> [bump]`): the phase is `prepare` (default), `tag` or+`verify`. For `prepare` the bump is `minor` or `patch` (see step P2).++---++## Phase 1 — `prepare` (on a `release/X.Y.Z` branch from `develop`)++### P1. Preflight. Stop if any check fails++1. On `develop`: `git rev-parse --abbrev-ref HEAD`.+2. The tree is clean (`git status --porcelain` is empty). Otherwise ask the user to commit+ or stash first, so the release changes stay separate.+3. Up to date: `git fetch origin`, then `git rev-list --left-right --count origin/develop...HEAD`+ must show `0` behind and `0` ahead (unpushed commits on `develop` can't reach it any+ more except through a pull request).+4. `## [Unreleased]` has real entries.+5. Once the version is chosen (P2), create the branch: `git switch -c release/X.Y.Z`. This is+ the only branch operation the skill does itself; every later step edits files on it.++### P2. Choose the bump++The app and the engine always move together, by the same kind of bump:++| bump | when | app | engine |+|---------|----------------------------------------------|-----------------|-----------------|+| `minor` | a major feature (new device, view, workflow) | 0.51.2 → 0.52.1 | 0.30.3 → 0.31.1 |+| `patch` | fixes, polish, small additions | 0.51.2 → 0.51.3 | 0.30.3 → 0.30.4 |++A component that resets starts at **1, never 0**. If the user gave no bump, propose one+from the `[Unreleased]` content and confirm it with them. Preview it with+`scripts/release-bump.sh <bump> --dry-run`. It refuses a version whose tag already exists.++### P3. Promote CHANGELOG.md++Rename `## [Unreleased]` to `## [X.Y.Z] — YYYY-MM-DD` (date from `date +%F`). Add a fresh+empty `## [Unreleased]` above it. **Don't touch the entries**: no Highlights and no+rewording. The changelog stays the honest log. Keep the preamble and older sections as they+are.++### P4. Write the curated notes, EN and RU++This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and+`release-notes/X.Y.Z.ru.md`. Each has four parts, in this order:++1. **Summary**: the lede and the numbered headline features, for someone who reads only+ this part.+2. **Full list**: every user-facing change of the release, grouped as Added / Changed /+ Fixed / Removed.+3. **Commit links**: each full-list item ends with a link to its commit.+4. **Contributors**: everyone who has a commit in the release, linked to their GitHub+ profile.++Steps:++1. **Gather.**+ - The previous tag is the highest version tag:+ `git tag --list 'v*' --sort=-v:refname | head -1`. Don't use `git describe` on+ `develop`: release tags sit on `main`'s merge commits, which `develop` doesn't+ contain, so `describe` returns a tag several releases old.+ - Read the whole `[X.Y.Z]` section you just promoted.+ - `scripts/release-credits.sh <prev-tag> origin/develop commits` lists every commit of+ the release (short sha, sha, subject). It's the checklist for the full list.+ - `scripts/release-credits.sh <prev-tag> origin/develop contributors` prints the+ ready Contributors line. It asks GitHub for every commit's authors and co-authors+ (needs `gh` signed in) and leaves out bots and AI co-authors.+2. **Reconcile.** Merge entries that describe the same thing. Where entries conflict (a+ shortcut reassigned twice, a feature added and then reworked), **the code decides**:+ read the handler, the default or the UI and describe what ships. Drop anything that+ was added and then removed within the same release. Then build the full list from the+ commits:+ - Each user-facing change is one item, linked to the commit(s) that brought it. A fix+ and its follow-up make one item with both links.+ - Leave out internal or mechanical commits (refactors, CI, tests, release chores)+ unless a user can feel them. Their authors are still contributors.+ - Walk the `commits` output once more at the end: every user-facing commit must be in+ an item.+3. **Write.** Each language natively, not as a translation. Format: bold titles and `•`+ bullets, no `#` headings, so the text pastes into Telegram as is. The two comment+ markers say where the full list and the contributors start, whatever the language.+ They are invisible on GitHub, and `release-notes.sh` strips them.++ ```+ <!-- SPDX-License-Identifier: AGPL-3.0-only -->+ One or two sentences on what defines this release.++ **1. Biggest user-facing win**+ A short paragraph: what it is and why a musician cares. Not every changelog detail.++ **2. Next feature**+ …++ <!-- changes -->+ **Added**+ • A new capability, one line ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))++ **Changed**+ • A behaviour users must know: a moved shortcut, a changed default ([e4f5a6b](…), [c7d8e9f](…))++ **Fixed**+ • What no longer goes wrong, said from the user's side ([0a1b2c3](…))++ **Removed**+ • …++ <!-- contributors -->+ **Contributors**+ [@login](https://github.com/login), [@other](https://github.com/other)+ ```++ Rules for the format:+ - Rank the summary's sections by importance. A patch release can have just the lede+ before the full list.+ - Groups go in the order Added, Changed, Fixed, Removed; leave out empty groups.+ Inside a group, put the most noticeable changes first.+ - A commit link's text is the 7-character short sha and its URL takes the full sha+ from the `commits` output. These are `develop`'s squash commits. They become part of+ `main` through the develop → main merge, so the links keep working after the release.+ - New notes have no **Also** block: the full list replaces it, so nothing is listed+ twice.+ - RU titles: **Добавлено**, **Изменено**, **Исправлено**, **Удалено**, **Участники**.+ The EN and RU files have the same groups, the items in the same order with the same+ links, and the same contributors.+ - Contributors: paste the `contributors` line. Resolve every `warn:` line it printed+ on stderr:+ - An author with no GitHub login can be a second address of someone already listed+ (the user's work email, for example). Drop that name.+ - Otherwise, find the login and link it, or keep the plain name.+ - Don't add or remove people by hand otherwise.+ - Leave out the title and the download link, because `release-notes.sh` adds them per+ target. Use the user's product language: "track", "device card", "piano roll", not+ class names.+4. Show the user the three renders and iterate until they approve. The rest of the+ release depends on this text.+ - `scripts/release-notes.sh X.Y.Z github` has all four parts.+ - `post-en` and `post-ru` have the summary and the contributors but no full list. A+ Telegram message holds 4096 characters, and the posts end with the link to the+ GitHub release, which has the full list.++ The app bundles the EN file. What's New shows the summary, then "All changes" with the+ groups, then the contributors, and the links in it are clickable. The smoke test checks+ that every full-list item of a shipped notes file ends in a commit link.++### P5. Bump the versions++`scripts/release-bump.sh <bump>` writes `VERSION` and `src/native/nota.engine/VERSION`+(both without a trailing newline, read with `.Trim()` / CMake). The CI checks the tag against+`VERSION`, so the two must agree.++### P6. Feature list and docs++- Run `nota-features` in `audit` mode: fold this version's entries into `FEATURES.md` and+ set its header to `X.Y.Z`. That change goes into the release commit.+- Run `nota-docs` in `audit` mode over the same entries. Its changes are committed in+ `../nota-docs`. Missing docs don't block the release; list them in the report.++### P7. Release image++Build a 16:9 poster in `../media/news/X.Y.Z-src/` (outside the repo). Start from the last+release's `poster.html` (`ls -d ../media/news/*-src | sort -V | tail -1`) and copy its+fonts.++- Header: the logo, `Nota X.Y.Z` (version in brass), a one-line subtitle taken from the+ notes' lede, and a mono tag row with the 2–4 headline features.+- Two or three cards with real screenshots of the headline features. Shoot them from the+ app (see the UI-verify recipe, with an isolated `NOTA_DATA_DIR`) or reuse fresh shots+ from `../nota-docs`. Use Ember Graphite colours (`nota-design`).+- Render it at 2×:++ ```bash+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \+ --hide-scrollbars --window-size=1280,720 --force-device-scale-factor=2 \+ --screenshot="$PWD/../media/news/X.Y.Z.png" "file://$PWD/../media/news/X.Y.Z-src/poster.html"+ ```++- Look at the PNG (Read it) and check for overlaps, clipped text or empty space before+ showing it to the user. Also save the rendered posts next to it as+ `../media/news/X.Y.Z.en.md` and `X.Y.Z.ru.md` (the output of `post-en` / `post-ru`).++### P8. Hand over to the user++Don't commit. Give the user:++- the version change (`app a → b`, `engine c → d`) and the list of changed files:+ `CHANGELOG.md`, `VERSION`, `src/native/nota.engine/VERSION`, `FEATURES.md`,+ `release-notes/X.Y.Z.{en,ru}.md`,+- the commit message `(chore) Release X.Y.Z` and the push command+ `git push -u origin release/X.Y.Z`,+- the **PR into develop**: title `(chore) Release X.Y.Z` (it becomes the squash commit+ message), body = a short list of the changed files,+- the **PR text** for develop → main, opened after the first one is merged. Title+ `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github` (summary,+ full list and contributors), so the reviewer reads exactly what will be published. Merge it with **Create a merge commit**+ (the only method `main` allows),+- the image path and any docs gaps,+- the next step: merge both PRs once CI is green, then run `/release tag`.++---++## Phase 2 — `tag` (on `main`, after the merge)++1. If the user is still on develop, tell them to run `git switch main && git pull --ff-only`.+ Don't switch branches on their tree yourself if it has changes.+2. Run `scripts/release-tag.sh`. It repeats the CI guard locally (on main, clean, equal to+ `origin/main`, the tag is free locally and on origin, the `## [X.Y.Z]` section and both+ notes files exist) and then creates the annotated tag `vX.Y.Z`. **It doesn't push.**+3. Give the user the push command and the Actions link+ (`https://github.com/nota-daw/nota/actions/workflows/release.yml`):++ ```bash+ git push origin vX.Y.Z+ ```++If the script fails, report its message as is. Common causes: the PR isn't merged yet, or+local main is behind. After the tag, `develop` needs no sync: the merge commit on `main`+already has `develop` as a parent.++---++## Phase 3 — `verify` (after the tag push)++1. Find the run: `gh run list --repo nota-daw/nota --workflow release.yml --limit 3`. Wait+ for it with `gh run watch <id> --repo nota-daw/nota --exit-status` (run it in the+ background, because a build takes about 20–30 min). Don't poll in a loop.+2. If a job failed, show its log tail: `gh run view <id> --log-failed`.+3. When it's green, run `scripts/release-verify.sh X.Y.Z`. It checks that the draft body+ equals `release-notes.sh X.Y.Z github` word for word and that all six files are+ attached (dmg arm64/x86_64, exe x64/arm64, AppImage x86_64/aarch64).+4. Report the result. If the body differs (someone edited the draft, or the notes changed+ after the tag), show the diff and fix it at the source. Don't edit the draft by hand to+ make it match. The user reviews the draft and publishes it themselves, then posts+ `../media/news/X.Y.Z.{en,ru}.md` with `X.Y.Z.png` to the channels.++---++## Don't++- Don't commit, push, open PRs, push tags or publish the release. All of these are the+ user's steps.+- Don't reword or summarise inside `CHANGELOG.md`. Curated text goes only to+ `release-notes/`.+- Don't write published text anywhere except `release-notes/`. GitHub and the channels+ must come from the same files.+- Don't type the contributors or commit shas from memory. Take them from+ `scripts/release-credits.sh`, and resolve its warnings instead of ignoring them.+- Don't bump only one of app or engine, and don't reset a component to 0.+- Don't hard-code the date or reuse an existing version or tag.diff --git a/.gemini/skills/nota-design/SKILL.md b/.gemini/skills/nota-design/SKILL.mdnew file mode 100644index 00000000..0b931c2f--- /dev/null+++ b/.gemini/skills/nota-design/SKILL.md@@ -0,0 +1,176 @@+---+name: nota-design+description: Nota's UI design language — "Studio": the work carries the colour, the interface steps back — neutral greys on dark 1px seams, one orange accent reserved for what is live or chosen, sentence-case labels, in colour themes (Studio Dark — the default — Studio Light, Ember Graphite, Ember Paper). Use whenever building or restyling any Nota UI (windows, panels, controls, device cards, custom-drawn views like the piano roll / waveform / arrangement) so everything stays visually consistent. Points at the authoritative token files and the full guideline rather than restating values.+user-invocable: true+---++# Nota design language — Studio++The work carries the colour; the interface steps back. Neutral greys stepped in a+few exact tones (well · ground · panel · raised), flat panels butted against dark 1px+seams, small crisp type, and **one orange accent that appears only where something is+live or chosen**. Colour is a **theme**: one fixed look, dark or light, that gives every+token a value — Studio Dark (the default), Studio Light, Ember Graphite, Ember Paper. The+structure (layout, type, geometry, where the accent goes) is the same in every theme.+Preferences → Appearance picks a theme or Follow system (a dark-mode and a light-mode+theme); the switch is live. `DESIGN.md` is the guideline, plus the exceptions+the project accepted.++## Read these first — do not work from memory++| File | What it gives you |+|---|---|+| `DESIGN.md` | **The guideline.** Rules, colour themes and the readability bar, every Studio token value, elevation, type scales, number setting, controls and states, device cards, shell, the tests, accepted exceptions, known drift. Start here. |+| `DESIGN.html` | The same thing rendered — swatches, control specimens, a device card at true size, a theme toggle. Generated by `scripts/design-html.py`. |+| `src/managed/Nota.App/Theme/Themes/*.json` | **Definitive colour**: one file per theme, one value per token (incl. shadow colours and Fluent's accent ramp). |+| `src/managed/Nota.App/Theme/NotaTheme.axaml` | **Definitive** geometry, type classes, control styles. Holds no colour. |+| `Theme/NotaPalette.cs` · `NotaColourTheme.cs` · `NotaThemeService.cs` | The token slots (the catalogue) and helpers (`Wash`, `InkOn`, `Ink`, `Derived`) · loading and validating themes · applying a theme: slots re-tinted, the same brushes published as `Brush.*`, `Shadow.*` built. |+| `Theme/NotaGeometry.cs` · `NotaFonts.cs` · `NotaText.cs` · `NotaNum.cs` | Radii/sizes/spacing · Geist typefaces and type scale · sentence-case labels · number formatting. |+| `DeviceCardKit.cs`, `Controls/` | The shared controls and card builders; `Controls/NotaGraph.cs` for graph windows. |+| `tests/Nota.SmokeTest/DesignTokenCheck*.cs` | The guard tests (incl. `RunStudio`, `RunThemes`, `RunLabels`, `RunIcons`) and their ratchet lists (`*AllowList.txt`, which only shrink) — run the smoke test after any UI change. |++If `DESIGN.md` / `DESIGN.html` disagree with the theme files, **the theme files win** and+the docs need fixing. Say so rather than propagating the drift.++> This skill deliberately does **not** restate token values. An earlier version did, and+> it drifted a whole palette out of date. Read the files.++## Non-negotiables++Most of these are enforced by `DesignTokenCheck`; the smoke test fails when one breaks.++- **No literals in views.** XAML: `{DynamicResource Brush.*}` / `{DynamicResource Shadow.*}`+ (a `StaticResource` cannot follow a theme change) and+ `{StaticResource Radius.*|Control.*|Space.*}`. C#: `NotaPalette` (a slot,+ `Wash(slot, alpha)`, `InkOn(fill)`, `Ink("#hex")` for a one-off device hue),+ `NotaRadius`, `NotaSize`, `NotaSpace`, `NotaFonts`, `NotaType`. No hex outside `Ink()`,+ no RGB typed as numbers, no `Colors.X` / `Brushes.X` except `Transparent`, no font+ family names, no `new BoxShadows` in a view.+- **Nothing may snapshot a colour.** `new SolidColorBrush(slot.Color)`, a+ `static readonly Color` or brush built from the palette, or a static array of palette+ colours freezes the view in one theme. Use the slot, `Wash`, `InkOn`, `Derived`, a+ property, or read `.Color` inside `Render`. Track colours:+ `ArrangementView.TrackBrush(index)`.+- **Accent = live or chosen, only.** Playing, selected, the playhead, the loop, a toggle+ that is on, a chosen segment, menu hover, the device power switch, and a value control+ *while hovered or dragged*. If it is orange and none of those, it is wrong. **Resting+ values are neutral `VizInk`** — knob arcs, fader and slider fills, value bars, graph+ curves, waveforms. A modulation arc keeps its source chroma. There is no second accent.+- **Semantic fills with derived ink.** Mute on = `Mute` (amber), solo on = `Solo` (blue),+ arm / record on = `Record` (red), solid, with `NotaPalette.InkOn(fill)` for the text or+ glyph — never a fixed label colour on a themed fill. Green is positive status and the+ meter's safe range. Graph chromas (viz ink · teal · rose · blue) live only inside graphs.+- **Seam between, rule within.** Panels meet on `Seam` and so do keys in a segmented+ group; items inside a panel are divided by `Rule` (separators, field edges, graph+ frames).+- **Flat docked, blur only floating.** No gradients, glow or textures. Depth is a tone+ step + a 1px seam + the `Shadow.Raised` top bevel on raised controls. Only a floating+ layer drawn in the main window (`Shadow.Popover`, `Shadow.Modal`) carries a blur; menus+ and popups get a seam ring only (Avalonia clips a popup's shadow at its window edge).+- **Radii 2 / 3 / 4.** `Radius.Clip`/`Badge` 2 for inner keys, rows, clips, menu items;+ `Control`/`Tile`/`Panel`/`Body`/`Pill` 3 for controls, cards, graph windows, popovers;+ `Modal` 4 for modals only; `Docked` 0; `Bar` 1 for bars inside a plot.+- **Geist for words, Geist Mono for every number a user reads.** Names are never mono.+ Nothing under 7 px.+- **Sentence case, no tracking — every label.** Menu items, command titles, palette+ headings, window titles, tooltips, buttons: "Save as…", "Export audio", "Recent". Capitals+ stay only on acronyms and units (`NotaText.Fixed`), "Nota …" product and device names,+ the view names (Arrangement, Session, Modular, Mixer), proper nouns, and a page after+ "Settings: ". Route labels through `NotaText.Label` (it sentence-cases caps literals and+ keeps acronyms and units: `LFO rate`, `Gain dB`). Never `ToUpperInvariant()` a label,+ never set `LetterSpacing`. `RunLabels` fails on an all-caps or Title Case literal;+ `LabelAllowList.txt` is for data only (preset, mode, proper names).+- **Opacity is not a state.** Disabled and muted take the next ink step; use+ `Inactive.Set` for a subtree. The only allowed `Opacity` is a drag ghost.+- **State changes colour only** — never size, border width or position. Hover and colour+ transitions 120 ms ease-out; meters, playhead and spectra are never animated.+- **Numbers are set, not printed.** The app installs a display culture (point decimal,+ U+2212 minus — typed literals too, `"−12"`, never `"-12"`). Put a thin space (` ` in+ source) before units, keep precision fixed (dB one decimal, tempo two, percent whole, Hz+ up to 999 then `3.2 k`) — use `NotaNum` helpers. Ranges take an en dash, closed between+ plain numbers (`1–127`), spaced when an endpoint has a space (`20 Hz – 20 kHz`).+- **Every icon is a `Glyph`.** `Controls/Glyph.cs` is the one icon set: path kinds on a+ 16-unit grid, scaled as a whole (never `Stretch.Uniform`); stroked parts take the shared+ pen (round caps and joins, `max(1.2, size × 1.5/16)`), filled parts the ink (transport+ shapes, the Arrangement / Session view keys, OS marks, `StarFilled`, carets, Snap). A+ missing icon is a new `GlyphKind` with a one-line comment, never a path in a view —+ `RunIcons` fails on `Geometry.Parse`, `Data="M…"` or a path string outside `Glyph.cs`.+ No unicode symbols (`■ ▶ ● ✓ ★ ▾`…) and no emoji as text. `·` separates meta; `→` in+ prose is fine.+- **Copy:** English. Labels one word where it fits, no vowel-dropped contractions+ (`Feedback`, not `Fdbk`; `Freq`/`Reso`/`Thresh` are allowed). Tooltips short and+ verb-first. Empty states are one Ink 5 line.++## Device cards++- **700 × 260** (`DeviceCardKit.CardH`; width exceptions are listed in `DESIGN.md`): panel+ body, radius 3, seam frame.+- **Header 22** (`BuildCardShell` in `DeviceChainView.Shell.cs` — every card uses it,+ racks, the generic instrument card, plug-ins and Sends included; never build a header of+ your own): a raised strip with the `Shadow.Raised` bevel, in fixed slots **name · preset ·+ badges · power**. The preset picker `‹ Name ⌄ ›` is centred in the header between two+ equal halves (name left, badges and power right), only when the device has presets; the badges — the+ type badge (mono, muted, sentence case) and the card's accessories (`HeaderExtra`: Learn,+ S / L) — right-aligned; the power switch (accent while on) last, its slot reserved even+ on a card that cannot be bypassed. A/B, move and delete go in the right-click menu.+- **Body:** inset 6; columns choice → work → output. **Sections are+ `DeviceCardKit.Section(body)`** — no fill, no frame, a 1 px `Rule` on a top or left edge+ facing a neighbouring section (found from the layout, or pass `SectionEdge`); never a+ framed `Border` box. Graph windows and wells keep their frames; chips, tiles, pads and+ readouts are not sections. Titled in `DeviceSection` (muted 600). Device text keeps the+ device scale (7.5–10.5 px) because the frame is kept.+- Values at rest neutral, the accent only for what is live or chosen; modulation shows its+ source chroma; graphs go through `NotaGraph` (well, rule frame, radius 3, `VizGrid`,+ `VizInk` primary curve, accent only on the active node, corner axis labels, no fills+ under curves).++## Adding a control++Reuse before writing: `Knob` (sizes snap to 34/36/44), `DeviceCardKit.KnobCell` (53 tall),+`SwitchTrack` / `DeviceCardKit.Switch` (18 × 10), `DeviceCardKit.Segments`, `SliderTrack` /+`DeviceCardKit.SliderRow`, `MiniFader`, `PanBar`, `VFader`, `DragNumber`, `MeterBar` /+`StereoMeter` / `GrMeter`, `Glyph`, `NaBadge`. Sizes and specs: `DESIGN.md` § Controls.++A new value control **must** match the interaction contract:++- Vertical drag, up increases, full range over ~140 px; Shift/Ctrl/⌘ for fine steps;+ `ns-resize`; a click never jumps the value; no horizontal drag (except a horizontal+ slider along its own axis, `SliderTrack`)+- Double-click restores the default+- Left button only — right-click must bubble to the CV-modulate / MIDI Learn menu+- `GestureBegin` / `GestureEnd` bracket `BeginAutomationWrite` / `EndAutomationWrite`+- Register with `MidiLearn.Bind`+- Live-follow refresher that **skips while dragging**+- Mono readout so width does not jump; the value is always visible, not only in a tooltip+- Its value drawn in `VizInk` at rest and the accent only while hovered or dragged++## Applying it (Avalonia)++- `NotaTheme.axaml` is merged in `App.axaml`; `NotaThemeService` applies the colour theme+ (resolved from settings by `Nota.Application.Appearance`) to both layers. `NotaNum.Install()` runs in `App.Initialize`.+- Buttons: default (raised, seam border, bevel), `primary` (weight and one tone step —+ not colour), `ghost`, `cell` (a readout well), `chip`, `tp-icon`, `tp-play`; a+ `ToggleButton` that is checked is a solid accent key with derived ink.+ `ToggleButton.seg` inside `Border.segmented` (keys butted on 1px seams).+ Containers: `Border.Panel`, `Border.Card`, `Border.well`, `Border.transport`,+ `Border.console`. Fields: `TextBox.field`, `TextBox.search`.+- Text: shell `Title`, `Heading`, `Name`, `Caption`, `SectionLabel`, `CellLabel`,+ `Readout`, `Value`, `Eyebrow`; device `DeviceName`, `DeviceSection`, `RowLabel`,+ `KnobLabel`, `KnobValue`, `Axis`.+- Elevation: `BindResource(Border.BoxShadowProperty, "Shadow.Raised" | "Shadow.Sunken" |+ "Shadow.Popover" | "Shadow.Modal")` — never a literal.++## When you change a token++1. Change the value in each theme file in `Theme/Themes/` it should change in (both Studio+ themes at least). A **new** token is a `T(nameof(X))` slot in `NotaPalette`, a value in+ **every** theme file (the smoke test names a file that lacks it), and a `KeyMap` entry+ if XAML uses it.+2. Every theme must still pass the readability bar (`DESIGN.md` § Readability bar).+3. Run `python3 scripts/design-html.py` and update the table in `DESIGN.md`.+4. Check every theme — in the app and in `DESIGN.html` (`?variant=light`, `?variant=ember-paper`…).++## When you add a theme++Add `Theme/Themes/<id>.json` (every token; `kind` dark or light) and append the id to+`NotaThemes.BuiltInOrder`. Nothing else names a theme. Run the smoke test (`RunThemes`).diff --git a/.gemini/skills/nota-docs/SKILL.md b/.gemini/skills/nota-docs/SKILL.mdnew file mode 100644index 00000000..b648ce49--- /dev/null+++ b/.gemini/skills/nota-docs/SKILL.md@@ -0,0 +1,134 @@+---+name: nota-docs+description: Keep the user documentation (sibling repo ../nota-docs, Astro Starlight, EN + RU) in sync with the app. Run this WHENEVER you add, change or remove a user-visible feature — a new device or parameter, a new view/panel/window, a changed workflow, a moved menu item, a new or re-mapped shortcut, a new Preferences option — i.e. whenever you write a CHANGELOG [Unreleased] entry. Also run it from /release to catch anything that slipped. Handles: finding the affected pages, editing the EN page and its RU twin, re-shooting screenshots (nota-design mockups or the headless app), regenerating the shortcuts page, and building/checking the site.+user-invocable: true+---++# Keeping Nota Docs honest++The user manual lives in **`../nota-docs`** (relative to this repo; GitHub `nota-daw/nota-docs`),+built with Astro Starlight in **English (root) and Russian (`/ru/`)**. It is written by hand,+so every user-visible change in this repo must be mirrored there or the manual lies. The+overall structure and conventions are in `../nota-docs/PLAN.md` — read it once if you have+not.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+`Added` / `Changed` / `Removed` almost always need a docs edit; `Fixed` only when the fix+changes what the docs describe. Pure refactors, perf and internal changes need nothing.++**Argument** (`/nota-docs <arg>`, optional): a feature name, a changelog line, or `audit`+(reconcile *all* `[Unreleased]` entries — used by `/release`). No argument → the change you+just made in this session.++If the page that should cover the change is still a stub (`status: todo`) and you are not+writing it now, append `{page, change, version}` to the `pending:` list at the bottom+of `../nota-docs/coverage.yml` so the stage that writes that page picks it up, tell the user,+and stop.++## 1. Work out what changed for the user++From the diff and the CHANGELOG entry, list concretely: new/renamed UI labels, new+parameters with ranges and defaults, new menu items and where they sit, new shortcuts,+changed behaviour, removed things. Take names and numbers **from the code** (the device's+DSP class and card under `src/managed/Nota.App/DeviceCards/…`, menus in `MainWindow.axaml`,+`PreferencesWindow.cs`), never from memory or the mockup — the changelog itself can be+contradicted by a later entry.++## 2. Find the pages++1. `../nota-docs/coverage.yml` maps features and source paths → page slugs. Look up every+ file you touched and every feature you named.+2. Grep page frontmatter `sources:` in `../nota-docs/src/content/docs/**/*.mdx` for the+ touched paths, and grep page bodies for the old UI label / old shortcut.+3. Nothing found → it is a new feature. Decide its place in the sidebar (see `PLAN.md`),+ copy `templates/page.mdx` (or `templates/device.mdx`) into both+ `src/content/docs/<slug>.mdx` and `src/content/docs/ru/<slug>.mdx`, and add it to+ `coverage.yml`. The sidebar autogenerates per directory (order via `sidebar.order`); only a+ brand-new top-level section needs an entry in `astro.config.mjs`.++Typical fan-out — check all that apply:+- the feature's own page (device, view, panel, preference pane);+- the overview that lists it (Devices index, Views index, "Main window tour");+- `reference/shortcuts` — regenerated, see step 4;+- the glossary, if you introduced a term;+- tutorials that walk through the changed flow (the old steps may no longer work);+- a new built-in device or a renamed device page → the slug maps in+ `src/managed/Nota.App/NotaDocs.cs` (`Instruments` / `AudioEffects` / `MidiEffects`, indexed by+ engine kind) so the device header's Documentation item opens the right page.++## 3. Edit EN, then RU++- English page under `src/content/docs/<slug>.mdx`, Russian twin at+ `src/content/docs/ru/<slug>.mdx` — **same path, same structure, same screenshots**. Never+ leave one language behind; `scripts/check.mjs` fails on a missing or stale twin.+- A stub page (`status: todo`) you fill in becomes `status: draft` (or `done` once its+ screenshots are in); drop the "Being written" aside.+- Bump `updated:` in both frontmatters to the version in `VERSION` (plus `since:` on new+ pages); add any new source paths to `sources:`.+- Style: short, second person, like the CHANGELOG. UI names exactly as on screen in+ **bold**, keys via `<Kbd>`. In Russian, UI names stay in English (the app is English); the+ explanation is native Russian, not a word-for-word translation.+- Removed feature → delete the text and its screenshots; removed page → delete both+ languages, the sidebar entry and the `coverage.yml` entry, and fix links into it.++## 4. Screenshots and generated pages++`../nota-docs/shots/manifest.yml` lists every image (its header documents the scenes and+args). `npm run shots -- <id-prefix> …` retakes them into `src/assets/shots/{dark,light}/`.++- **app** shots render the real UI headlessly (`shots/app`, both themes, 2×, user/device names+ scrubbed). They build against this repo's `src/managed/Nota.App`, so build the app first if+ you changed it. **design** shots come from `../nota-design` (dark only).+- UI that changed visibly → retake its ids (e.g. `npm run shots -- devices/audio-effects/shutter`).+- New device → add `devices/<group>/<slug>/card` (`scene: device` with its kind id) plus one+ shot per tab you document (`args: {tab: "<tab text>"}`, a chain like `"L>Env"` when a size+ switch comes first, `preset` for an interesting state). Write the page from+ `templates/device.mdx`; facts come from the engine header's top comment and `paramName`,+ the card file's header comment and labels, and `FactoryPresetCatalog` — give a range only+ when the code states it.+- New window / view / Settings page → a new scene in `shots/app/Scenes.cs` if none fits; keep+ it deterministic (demo song, no real user data).+- Mockup no longer matches the code → switch that id to `source: app`; never document the mockup.+- A scene breaks after an app refactor (renamed private method, control name) → fix the+ harness; it reflects into `MainWindow` / `PreferencesWindow` privates on purpose.+- Shortcut changed → `npm run shortcuts` regenerates `reference/shortcuts` (EN + RU) from+ `PreferencesWindow.ShortcutGroups`; run the `nota-shortcuts` skill first so that list is+ right.++## 5. Verify and commit++```bash+cd ../nota-docs+npm run build+npm run check+```++Node may not be on PATH (Homebrew's node isn't linked on this Mac) — use+`/opt/homebrew/Cellar/node/*/bin`. The dev server is the `nota-docs` entry in this repo's+`.claude/launch.json` (preview_start).++Both must pass (broken links, missing RU twin, image id not in manifest, `updated:` older+than a touched source). Look at the changed pages in `npm run preview` via the built-in+browser when screenshots or layout changed.++Commit in **`../nota-docs`**, separately from the app repo: `(docs) <what changed>`, no+Claude attribution trailer. Don't push unless the user asked.++## 6. Report++List the pages changed (EN + RU), screenshots re-shot, anything you could not document+(e.g. a scene the harness can't render) and the gaps you left in `coverage.yml`.++## /release audit mode++Go through every `Added` / `Changed` / `Removed` entry of `[Unreleased]`, check each against+the docs as above, fix what's missing, then `npm run build && npm run check`. Report+the coverage to the user before the tag is created; missing docs do not block a release, but+say so plainly.++## Don't+- Don't document plans, mockup-only features or anything not in the code.+- Don't update only one language.+- Don't hand-edit the generated shortcuts page.+- Don't copy CHANGELOG prose verbatim — the changelog says what changed, the docs say how+ to use it now.diff --git a/.gemini/skills/nota-features/SKILL.md b/.gemini/skills/nota-features/SKILL.mdnew file mode 100644index 00000000..7fe279a8--- /dev/null+++ b/.gemini/skills/nota-features/SKILL.md@@ -0,0 +1,104 @@+---+name: nota-features+description: Keep FEATURES.md (the consolidated "what Nota can do" list in the repo root) in sync with the app. Run this WHENEVER you add, change or remove a user-visible capability — a new device or parameter, a new view/panel/window, a new workflow or editing command, a new MCP tool, a new export option, a new platform/build/CI capability — i.e. whenever you write a CHANGELOG [Unreleased] Added/Changed/Removed entry. Also run it from /release in `audit` mode to catch anything that slipped and bump the "as of version" line.+user-invocable: true+---++# Keeping FEATURES.md honest++`FEATURES.md` is the single page that answers "what can Nota do *right now*". It is written+by hand and is not generated from the changelog, so it drifts unless every feature change is+folded into it. It describes **what is implemented in the code**, not plans, and it is a+**current-state** document: no history, no "now", no "previously", no version numbers per+item — that is the CHANGELOG's job.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+- `Added` → almost always a new bullet or an extension of an existing one.+- `Changed` → rewrite the bullet that describes the old behaviour so it describes the new.+- `Removed` → delete the mention (search the whole file — features get cross-referenced).+- `Fixed` → only if the fix changes what the list claims (a limit lifted, a platform now+ supported). Pure bug fixes, refactors, perf and internals need nothing.++**Argument** (`/nota-features <arg>`, optional): a feature name, a changelog line, or+`audit` (reconcile everything since the version in the file's header — used by `/release`).+No argument → the change you just made in this session.++## 1. Find where it belongs++Read the Contents list at the top of `FEATURES.md` and pick the section by what the user+sees, not by which code you touched:++| Change | Section |+|---|---|+| OS support, installers, auto-update, audio/MIDI backends | Platforms and distribution |+| Projects, saving, version history, transport, tempo, loop, metronome | Project and transport |+| Arrangement / Session / Modular / clip editors / piano roll behaviour | Views |+| Track types, routing, sends, groups, mixer window | Tracks and mixer |+| Note editing, MIDI input, MIDI Learn, controllers | MIDI and virtual instruments |+| Recording, audio clips, warp, stretch, stems | Audio: recording, clips, warp |+| Automation lanes, envelopes, modulation | Automation |+| A built-in instrument / audio effect / MIDI effect / rack | Built-in devices → the matching `###` subsection |+| VST3/AU hosting, plugin scanning, plugin windows | Plugin hosting |+| Browser tabs, sample library, presets, smart samples | Browser and assets |+| Render / bounce / stems export | Export |+| Windows, themes, menus, dialogs, Nota Remote UI | Windows and interface |+| A new Preferences option | Preferences |+| A new or changed MCP tool | MCP / AI control (also mention it on the feature's own bullet if it has one, as existing device bullets do: "MCP `read_sampler` / `set_sampler`") |+| Build scripts, CI, tests, licensing | Other |++Before writing, `grep -n` the file for the feature's name and its key words — the feature+may already be partly described (often it is an extension of an existing bullet, e.g. a new+parameter on a device). **Extend the existing bullet rather than adding a duplicate.** If a+genuinely new top-level area appears, add a `##` section *and* its Contents link (anchor =+GitHub slug of the heading).++## 2. Write it in the file's voice++Match the surrounding bullets — read the neighbours first.+- One bullet per feature; **bold** the feature's name at the start, then a dash or colon and+ what it does. Nested bullets only for sub-features of one thing (see Transport).+- English, present tense, plain language a musician understands. State capabilities and+ user-facing names (menu items, tab names, button labels exactly as in the UI), shortcuts+ in the app's glyphs (⌘ ⇧ ⌥, "Cmd/Ctrl" where the file already does).+- Concrete over vague: parameter names, modes, counts ("25 factory presets", "Poly 16 /+ Mono / Legato") — but verify each number in the code/presets, don't copy it blindly from+ the changelog.+- Condense. The changelog entry explains the change; FEATURES states the result in roughly+ half the words. No rationale, no "fixes", no internal class names (file paths only in+ Other / Platforms, as already done there).+- Built-in devices: follow the existing device bullet shape — what it is · its main controls+ and modes · tabs/sizes of the card · preset count · MCP tools if any.+- Hard-wrap at ~90 columns like the rest of the file.++## 3. Verify against the code++The changelog can be ahead of, or behind, reality. For each claim you add, confirm it in the+source (device kind registration, the view/menu code, the MCP tool list in the MCP server,+the preset folder). If something in the changelog was later reverted or is behind a flag+that is off by default, leave it out (or say "experimental, off by default" if the user can+turn it on).++## 4. `audit` mode (from /release)++1. Read the version in the header line ("as of version **X.Y.Z**").+2. Collect every `CHANGELOG.md` entry newer than that version: all `## [A.B.C]` sections+ above `## [X.Y.Z]`, plus `[Unreleased]` / the section being released right now.+3. For each `Added` / `Changed` / `Removed` entry (and relevant `Fixed`), check whether+ `FEATURES.md` reflects it; fix what is missing or stale per sections 1–3.+4. Update the header: set the version to the one being released (or the latest released+ version when run outside a release), keep "(plus changes in development on `main`)".+5. Report the list of entries you added/changed in FEATURES.md and anything you+ deliberately skipped (and why).++## 5. Finish++- Re-read the edited section as a whole: no duplicates, no contradictions with other+ sections, Contents still matches the `##` headings.+- The SPDX header on line 1 stays.+- Commit FEATURES.md together with the feature (or the release commit in audit mode);+ don't make a separate commit unless the user asks.++## Don't+- Don't paste changelog entries verbatim, and don't add dates or version tags to items.+- Don't describe planned, unmerged or disabled-by-default work as available.+- Don't reorganize or restyle sections you weren't asked to touch.diff --git a/.gemini/skills/nota-instrument/SKILL.md b/.gemini/skills/nota-instrument/SKILL.mdnew file mode 100644index 00000000..81ffc46e--- /dev/null+++ b/.gemini/skills/nota-instrument/SKILL.md@@ -0,0 +1,238 @@+---+name: nota-instrument+description: How to build a Nota built-in instrument, audio effect or MIDI effect end-to-end — the DSP class, the kind-registration checklist across the C++ engine and C# managed layers, and the device-card UI design approach (signal-chain panels, tabs, the shared gauge knob, interactive graphs, using the card space well). Use whenever adding or reworking a built-in synth / audio effect / MIDI effect or its editor. Reference implementations: Nota Volt (instrument), Nota Vintage / Auto Filter (audio effect), Nota Arp (MIDI effect).+user-invocable: true+---++# Building a Nota built-in instrument, effect or MIDI effect++This skill covers **all three built-in device families** — an **instrument**+(the track's sound source), an **audio effect** (an insert `Device`), and a+**MIDI effect** (a `MidiDevice` that transforms notes before the instrument).+The DSP conventions (§1) and card design (§3) are shared; only the base class,+the **registration path (§2)** and the **card interface (§3)** differ — effects+and MIDI effects register through a much lighter path than instruments.++The canonical example is **Nota Volt** (virtual-analog synth, kind 6):+`src/native/nota.engine/src/devices/instruments/VoltSynth.h` + `.cpp` (DSP) + `DeviceCards/Instruments/VoltInstrumentCard.cs` (UI).+Its editor is the reference build of the card layout — **read it first when designing+a synth UI, together with `DESIGN.md` § Device cards and the rendered specimens in+`DESIGN.html`.** Good+effect exemplars: **Auto Filter** and **Nota Vintage** (audio, `: public Device`),+**Nota Arp** (MIDI, `: public MidiDevice`). Also load the `nota-design` skill.++Built-in **instruments** (`kind()` ≥ 0): 0 Synth, 1 Sampler, 2 Physical (modal),+3 Instrument Rack, 4 Drum Rack, 5 Aurora (wavetable), 6 Volt, 7 Bass. **Audio+effects** (`builtinKind()`): 0 EQ, 1 Compressor, 2 Reverb, 3 Delay, 4 Utility,+5 Effect Rack, 6 Amp, 7 Auto Filter, 8 Vintage. **MIDI effects** (`midiKind()`):+0 Arp, + Chord / Scale / Note Length / Velocity / Random. **Grep the current+registration for the next free kind before picking one** — this list drifts.++## 1. DSP class (`.h` + `.cpp` pair)++Put the device in its family folder — `src/native/nota.engine/src/devices/+instruments/<Name>.h` + `.cpp` (`final : public Instrument`), `devices/effects/`+(audio effect, `: public Device`, in-place stereo `process(buf, frames)`), or+`devices/midi_fx/` (`: public MidiDevice`, MIDI effect) — and add both files to+`src/native/nota.engine/CMakeLists.txt`. The header declares, the TU implements;+**every new file carries the AGPL SPDX two-line header. Allocation-free after+construction** (pre-size buffers). Rules:++- **Parameters via the plugin-param interface** (`pluginParamCount/Id/Name/Get/Set/+ IndexOfId`). Values are **normalized 0..1** in `std::atomic<float> pn_[N]`+ (audio-thread read). Denormalise inside `render()` to musical units+ (`expMap(v, lo, hi)` for time/cutoff/rate; bipolar = `(v-0.5)*2`; discrete =+ `round(v*(n-1))`). This gives **automation, persist and clone for free** — the+ engine already routes `PluginParam` + `deviceIndex<0` to `instrument->pluginParamSet`.+- **Param order = the persisted state layout — APPEND ONLY.** `getState`/`setState`+ serialize `N` little-endian floats; `setState` tolerates a shorter/longer blob.+ `clone()` copies `pn_` + sample rate. Ids are stable strings; names are display.+- **DSP conventions:** 16 voices, per-sample outer loop when modulation must stay+ smooth; recompute expensive filter coefficients at control rate (every ~16+ samples), not per sample — control-rate math stays `std`-exact, `FastMath`+ applies only to downstream/published sample values. Steal the quietest voice. polyBLEP saw/square if you+ care about aliasing (Volt/Aurora do); a TPT/Cytomic SVF gives LP/HP/BP/Notch+ from one filter (`dsp/primitives/` has the shared SVF, ladder, biquad, delay,+ oscillator, envelope, oversampler and convolution blocks — reuse them, don't+ re-implement). `kind()` returns the new integer; `displayName()` the label.+ Support auto-sleep (`hasTail()`/`isIdle()`/`wake()`): sleep only fully decayed+ blocks, never a frozen loop; the engine never skips `process()` — your own+ skip must advance phases so the device resumes seamlessly.++## 2. Registration checklist (mirror an existing kind)++Grep the exemplar and copy every site. **Instruments** carry the most sites+(they need their own track + C ABI); **audio/MIDI effects register through a much+lighter path — see the end of this section.**++### Instruments (`grep -rn Volt` / `grep -rn Aurora`)++**Native:** `Engine.h` decl `add<Name>Track`; `Engine_Devices.cpp` (the method ++`#include` + `cloneInstrument` switch + `makeBuiltinInstrument` switch);+`devices/racks/RackCore.h` `makeInstrument` switch + include; C ABI+`nota_engine_add_<name>_track` in `src/abi/nota_engine_track.cpp` **and** the decl in+`include/nota/nota_engine.h` (the `_nota_*` export list is a wildcard — no change).++**Managed:** `NativeMethods.Tracks.cs` (`[LibraryImport]`), `NotaEngine.Tracks.cs`+(wrapper), `IAudioEngine.cs` (interface); `Nota.Application/Palette/BuiltinDeviceCatalog.cs`+(the one device list the browser and the command palette read: name, `Kind = N`, sub text **and+a semantic descriptor** — role, aliases, character, sound/source, genre, a one-line+description; the palette smoke test `--palette` fails without a role and aliases), and its+browser category in `Nota.Application/Palette/DeviceCategories.cs` (the category chip it is listed+under — Synths, Dynamics…; the `-- design: browser --` check fails until it has one);+`DeviceInsertService.CreateInstrumentTrack` in Nota.Presentation (`N => Engine.Add…` — the+one place drag & drop, the browser and the palette create the track);+`ProjectService.cs` (`{ Kind: N }`) + `PresetService.cs` (`N =>`); rack/drum+"add chain / add pad" menus in `DeviceCards/Rack/RackCardView.cs`+(`AddChainButton`, `ShowAddPadMenu`).++**Automation menu:** built-in instruments (`TrackInstrumentKind >= 0`) must list+their params *directly, grouped* via `BuildBuiltinInstrumentAutoMenu`+(`ArrangementView.Automation.cs`) — NOT the hosted-plugin "Choose parameter…/Learn"+picker (that path made empty-id lanes → "drew a curve, no effect").++### Audio effects (`grep -rn AutoFilter` / `grep -rn Vintage`) — much lighter++No track, no C ABI, no `Engine.h` method: effects are added generically by+`addTrackBuiltinDevice(trackId, kind)`. Only:+- **Native:** the `.h`/`.cpp` pair in `devices/effects/` with `: public Device` and `builtinKind()` returning the kind,+ then register that kind in the **three switches** in `Engine_Devices.cpp` —+ `addTrackBuiltinDevice` **+** `cloneDevice` **+** `makeBuiltinDevice` — plus the+ `#include`. Params use the plain `Device` interface (`paramCount/paramName/+ paramMin/paramMax/getParam/setParam`); **prefer normalized 0..1** (mirror+ AutoFilter/Vintage, not the older raw-unit Amp/EQ). Persist / clone / automation+ are **generic** through the base `Device` (by `builtinKind()` + params) — no+ `getState`/`setState`, no per-kind managed persist code.+- **Managed:** `DeviceCardFactory` `[kind] = new NameDeviceBody()`; a+ `BuiltinDeviceCatalog.cs` entry (`AudioEffect`, kind N, with its semantic descriptor —+ role, aliases, character, source, task) and its category in `DeviceCategories.cs`. The add/drop path (`DeviceInsertService`) is+ already generic. Factory presets get their descriptor from their folder and name+ (`PresetDescriptors`); a new folder whose name isn't vocabulary goes into its folder map.++### MIDI effects (`grep -rn Arpeggiator` / `grep -rn MidiScale`)++Mirror an existing `MidiDevice` (e.g. `devices/midi_fx/Arpeggiator.h`) with `midiKind()`; register+in the engine's MIDI-device factory + `MidiDeviceCardFactory` `[kind]` + a `MidiEffect`+entry with its descriptor in `BuiltinDeviceCatalog.cs` (and its category in `DeviceCategories.cs`). Params/persist/clone are generic like audio effects. Cards sit+**before** the instrument in the chain.++## 3. Editor card architecture++Cards are **strategy classes under `src/managed/Nota.App/DeviceCards/`**, resolved by+a factory and handed a `DeviceCardContext` — `DeviceChainView` is a thin orchestrator+(row + registries + the 60 Hz `RefreshSynthLive` tick) and builds nothing itself.+To add an editor, write a class and register it — no `switch` to edit (open/closed):++- **Instrument** (kind ≥ 0, the track's instrument): `class NameInstrumentCard :+ IInstrumentCard` in `DeviceCards/Instruments/`, `Control Build(DeviceCardContext ctx)`;+ register `[kind] = new NameInstrumentCard()` in `InstrumentCardFactory`.+- **Audio effect** (device): `class NameDeviceBody : IDeviceBody` (`double Width`,+ optional `bool AutoWidth => true` to size the card to its content,+ `Control Build(ctx, deviceIndex)`) in `DeviceCards/Bodies/`; register in+ `DeviceCardFactory`. The shared device shell (bypass/reorder/remove) wraps it —+ the body has NO instrument live-follow; use `ctx.AddDeviceRefresher(a)` for the+ 60 Hz visual and read/write params with `engine.DeviceGetParam/DeviceSetParam` ++ `BeginAutomationWrite/EndAutomationWrite` (see `AutoFilterDeviceBody`/`VintageDeviceBody`).+- **MIDI effect**: `class NameMidiBody : IMidiDeviceBody` in `DeviceCards/Midi/`;+ register in `MidiDeviceCardFactory`. The racks live in `DeviceCards/Rack/RackCardView.cs`.++Everything a card needs comes through **`ctx`** (never reach into the view): `ctx.Engine`,+`ctx.TrackId`; `ctx.AddDeviceRefresher(a)` for a 60 Hz visual; `ctx.AddInstFader(i,knob,val)`++ `ctx.SetInstLiveViz(refresh)` for instrument live-follow; `ctx.NotifyChanged()` /+`ctx.RequestRebuild()` / `ctx.RequestPresetSave(i)`. Stateless strategies are singletons —+all per-rebuild state stays behind `ctx`. Shared builders: `DeviceParamControls` (param+faders + sidechain), `InstrumentControls.InstKnob`, `SamplerEditor`.++Follow the mockup language:++- **A device card is a fixed rectangle**, height `CardH` (260, shared by all cards)+ — content taller than that is clipped (`ClipToBounds`). **Gotcha:+ `SimpleCard(title, width, body)` — the 2nd arg is WIDTH; height is always CardH.**+- **Use the working space deliberately — no dead space, nothing overflowing.**+ Fill the card's width with content and don't leave a half-empty card or let+ panels spill past the edge. Size each panel to its own controls, then make the+ card track that: either set `Width` to the sum of the panels, or (audio effects)+ set `AutoWidth => true` so the card sizes to content exactly — the safest way to+ guarantee "it all fits". Lay bordered **islands** side by side and give a large+ interactive graph its **own** framed island next to the knob panels (Nota Vintage:+ CHARACTER / WEAR / SHAPE). If the content genuinely can't fit 260px tall at a sane+ width, **split into tabs** (below) rather than shrinking every control. Always+ do the visual check and trim leftover margins.+- **If there's more than one logical section, use tabs** inside the card (e.g.+ Signal Path / Modulation) with a segmented toggle styled like the Devices/Clip+ segment, swapping a `ContentControl`. One section = one horizontal row that fits+ 260px tall.+- **Card sizes (S / L) are views of ONE device, never two devices.** When a mockup gives a+ device a mini (S, 260) and a full (L) size (Nota Arp is the reference):+ - **Presets belong to the device, not to the size.** Both sizes show the same preset+ picker with the **full** preset list and the **same current preset** — pick a preset in+ L, flip to S, it is still selected there (and vice versa). S may edit fewer params, but+ a preset still sets all of them. Never swap the picker for another control in S; the+ shell's `ShellSpec.Compact` only narrows it (and hides the type badge).+ - Every value is shared; S just exposes a subset (e.g. 4 knobs). No per-size params.+ - The size itself is **editor state**: store it in an appended param (`View`, 0 = L,+ 1 = S) so it persists with the project and clones, but keep it out of presets (in-place+ preset apply skips `View`), and out of the automation menu.+ - Plumbing (MIDI effects): `IMidiDeviceBody.WidthFor(engine, track, index)` returns 260/700+ from `View`; `HeaderAccessory(ctx, index)` puts the S/L toggle (and L-only extras) in the+ shell header; the toggle writes `View` and calls `ctx.RequestRebuild()`. Per-card UI+ state that should survive the rebuild (active tab, selected lane) lives in a static map+ keyed by (track, index), not in the singleton body.+ - Plumbing (instruments, Nota Synth is the reference): append a `"view"` plugin param to the+ DSP (its default in the constructor is the instrument's default size — Synth opens as S);+ `InstrumentView` (Nota.Application) finds/reads/writes it, and presets, A/B, the automation+ menu (by id) and the rack chain card (by the name "View") already skip it. The card implements+ `IInstrumentCard.WidthFor(engine, track)` + `HeaderAccessory(ctx)` with+ `MidiCardHeader.SizeToggle(ctx, isMini, setMini)`; the shell goes compact under 300px.+- **Lay panels as a signal chain**: bordered titled sections left→right with `▸`+ arrows (Osc → Noise → Filter → Amp). Each panel = `Border` (SurfaceCard fill,+ 1px border, radius 7) with a bold section title.+- **Controls, in order of preference for space:**+ - The shared **gauge `Knob`** via `InstrumentControls.InstKnob(ctx, idx, id, name, refresh, size, cellW, arc)`+ — 270° groove + value arc + pointer. Pass a teal `arc` for **modulation-depth**+ knobs (env/lfo/key amounts, velocity, vibrato); amber (default) for everything+ else. Double-click resets to the param default.+ - **`KnobGrid(cols, …)`** packs knobs into centered rows (2×2, or vertical for+ 1 col) to shrink a panel; a partial last row stays centred.+ - **Interactive graphs are controls, not decoration**: a drag ADSR editor+ (`VoltEnv`) and a drag filter response (`VoltFilter`, X=cutoff / Y=reso, curve+ follows the type, with grid + fill + freq/dB axes + cutoff handle). They replace+ ~a dozen knobs and should FILL their panel via a `DockPanel` (header docked+ top, graph stretches).+ - **Selectors:** waveform = icon chips (`WaveIcon`), filter type = text chips,+ small A/B or Fil1/Fil2 = segmented `Seg` toggles. Not combo-boxes unless a list+ is long.+ - Live values in `Font.Mono`; tiny UPPERCASE section/knob labels.+- **Live follow:** call `ctx.SetInstLiveViz(Refresh)` and register knobs via+ `ctx.AddInstFader(...)` (InstKnob does this for you); `RefreshSynthLive()` (driven by+ the playhead tick) re-reads params so automation playback moves the UI. Keep a+ `readouts` list of `Action` for numeric captions / graphs and call them in `Refresh`.++Colours/tokens: never hardcode — reuse the `DeviceCardKit` brushes (`Card2`, `BorderDef`,+`Brass`, `Teal`, `Sunken`, `TextPrimary/Secondary/Tertiary`, `AccentBright`), in scope via+`using static Nota.App.DeviceCardKit;` — along with `SimpleCard`, `KnobCell`, `ChipRow`,+`Labeled`, `Glyph`, `Pct`, `NoteName`. See `nota-design`.++## 4. Presets & verification++- **Factory presets:** instruments use `Inst("<group>", N, "Name", ("paramid", v), …)`;+ audio/MIDI effects use `Fx(…)` / `Midi(…)` with **param NAMES** (not ids) in+ `FactoryPresetCatalog.cs` (values normalized 0..1 for the newer devices; bipolar+ knobs neutral at 0.5). ~6 covering the useful range.+- **Smoke test** (`tests/Nota.SmokeTest/Program.cs`): assert kind/`builtinKind`,+ name, param count, param round-trip, clone (duplicate the track), and that each+ mode renders audible + finite (RMS>0). Instruments add a track + note; effects+ do `AddBuiltinDevice(track, kind)` over an audio clip and check `DeviceName`/+ `DeviceGetParam`. Run `dotnet run --project tests/Nota.SmokeTest`.+- **Visual check** (no click automation on macOS — see `nota-ui-verify`): add a+ temporary `NOTA_DEBUG_SESSION`-guarded block at the end of+ `MainWindow.OnDataContextChanged` (a `DispatcherTimer` firing ~2.5 s). For an+ instrument add its track; for an effect add an **audio** track ++ `Engine.AddBuiltinDevice(t, kind)` (an audio track has no instrument card, so the+ effect card is first and not pushed off-screen); then `ShowDevices(t)`. Launch+ with the env var, `screencapture`, crop with `sips`, then **revert the hook and+ rebuild.** To shoot a non-default tab, briefly flip the tab's default `Content`.++Build native (`cmake --build build --target nota_engine`) and managed+(`dotnet build src/managed/Nota.App`) after each layer; the C ABI is wildcard-+exported so a new `_nota_*` function needs no export-list edit.diff --git a/.gemini/skills/nota-pr/SKILL.md b/.gemini/skills/nota-pr/SKILL.mdnew file mode 100644index 00000000..fbb43dc1--- /dev/null+++ b/.gemini/skills/nota-pr/SKILL.md@@ -0,0 +1,124 @@+---+name: nota-pr+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the contributor's own git identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".+user-invocable: true+---++# Opening a pull request++A Nota PR is reviewed by reading its description, so the description carries the proof: what+changed, why, and what it looks like or costs before and after. Images and benchmark charts+never go into `develop` — they live on the orphan **`pr-assets`** branch (see+`CONTRIBUTING.md` § Images for pull requests) and are embedded by raw URL.++## 1. Branch and commit++- Branch from `develop` (never `main`): `git checkout -b <type>/<slug>` — `fix/…`, `feat/…`,+ `docs/…`, `chore/…`. If the work is already on `develop` uncommitted, create the branch+ first; the working tree comes along.+- `scripts/build.sh` (or `build-linux.sh` / `build-win.ps1`) must pass — it runs the smoke test.+- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a body+ that says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no+ "Generated with" line) in commits or the PR body.+- Author and committer: whoever makes the change, from their own git config. Never set+ `user.name` / `user.email` / `--author` to someone else's identity.+- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change they+ describe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.++## 2. Decide what evidence the PR needs++| The change… | Attach |+|---|---|+| alters anything the user sees (a window, panel, device card, menu, theme, layout, custom-drawn view) | **before / after screenshots**, same size, theme and content |+| aims at or may affect performance (engine render path, DSP, threads, allocation, CPU, memory, startup) | **benchmark**: before vs after (and vs the last good build when fixing a regression), with charts + a table |+| both | both |+| neither (docs, refactor with no runtime effect, CI) | nothing — say so in the Summary |++When unsure whether a change is user-visible, run the app and look.++## 3. Screenshots (UI changes)++1. Capture **before** on the base commit and **after** on the branch, with the same window size,+ theme (default Studio Dark unless the change is theme-specific — then one pair per theme),+ interface scale and project content. Reuse the capture tooling the `nota-design` /+ `nota-docs` skills describe (headless Avalonia render or the app's own capture hook) rather+ than hand screenshots, so both shots are pixel-comparable.+2. Name them `<what>-before.png` / `<what>-after.png`; a side-by-side `<what>-both.png` is+ welcome for small changes.++## 4. Benchmarks (performance changes)++Two layers, and a performance change needs both:++- **Regression guards** — `tests/Nota.SmokeTest/RenderPoolTests.cs`, part of every smoke run+ (`scripts/build.sh`, CI on all three platforms; alone: `dotnet run --project+ tests/Nota.SmokeTest -c Release -- --perf`). Hardware-independent checks: render threads+ idle at ~0 CPU (their own thread clocks), parallel vs single-thread CPU ratios while playing+ and bouncing, bounce not slower than one thread, bit-identical output, tracks edited while+ rendering. When you touch the render path, threading or allocation, keep these green; when+ you fix a performance bug, add a guard here that fails on the old code (prove it: put the+ old behaviour back briefly and watch the check fail).+- **Benchmark numbers** for the PR description, below.++The engine benchmark is in the repo:++- `scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...` — links+ `scripts/bench/engine-bench.cpp` against each Release `libnota_engine` and runs idle, offline+ render (bounce) and real-time-paced scenarios for audio and synth tracks, interleaving the+ builds run by run. Writes `results.csv` + `machine.txt`.+- `scripts/bench-chart.py <out-dir> <label>="Display name" ...` — medians, three charts+ (`cpu-playing`, `bounce-time`, `bounce-cpu`; SVG + 2x PNG) and `summary.md` (tables + machine).++Recipe:++1. Build each revision you compare **in Release**, each in its own checkout so nothing is shared:+ `git worktree add --detach /tmp/nota-<label> <commit>`, then configure + `ninja nota_engine` in+ its `src/native/nota.engine/build`. Revisions before the CPM switch (#212) need+ `git submodule update --init --recursive --depth 1` first. The branch itself can use the main+ `build/` dir (it must stay Release).+2. Copy each `libnota_engine.*` into its own folder (`/tmp/bench/libs/<label>/`) so later rebuilds+ don't change what you measured.+3. Run on a quiet machine, on power, ≥3 runs: `scripts/bench-engine.sh -r 3 /tmp/bench/out+ before=… after=…`. Look at the spread in `results.csv`; rerun if runs disagree a lot.+4. Chart it: `scripts/bench-chart.py /tmp/bench/out before="Before" after="This PR"`. Open the+ PNGs and check them (labels, overlap) before attaching.+5. Report honestly: put regressions in the table too and say why they're acceptable or what+ follows up. A benchmark also needs the commits measured and the machine (from `machine.txt`).++If the change needs a scenario the harness lacks, extend `engine-bench.cpp` (stick to C ABI+functions every compared build exports) and the scenario list in `bench-engine.sh`, in the same PR.++## 5. Put the assets on pr-assets++One folder per PR, named after the change or issue (`fix-pr212-review/`, `issue-223/`). Commit on+top of `pr-assets` — never force-push or rewrite it; old PRs link to its files.++```sh+git fetch origin pr-assets+git worktree add /tmp/nota-assets origin/pr-assets -B pr-assets+mkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/+git -C /tmp/nota-assets add <folder>+git -C /tmp/nota-assets commit -m "Images for <change>"+git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \+ push https://github.com/nota-daw/nota.git HEAD:pr-assets+git worktree remove /tmp/nota-assets+```++For benchmarks commit the CSV and `summary.md` next to the charts, so the numbers stay checkable.+Embed with `https://raw.githubusercontent.com/nota-daw/nota/pr-assets/<folder>/<file>.png`.++## 6. Push and open the PR++- Push over HTTPS (SSH push to nota-daw/nota is denied):+ `git -c credential.helper= -c credential.helper='!gh auth git-credential' push -u https://github.com/nota-daw/nota.git <branch>`,+ then `git fetch origin <branch> && git branch -u origin/<branch>`.+- `gh pr create --repo nota-daw/nota --base develop --head <branch> --title "<commit-style title>" --body-file <file>`.+- Body: follow `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Spec, Checklist — tick only what was+ actually done; leave platforms you didn't build unticked). Add sections as needed:+ - **Screenshots** — a table, before | after:+ `| Before | After |` / `|---|---|` / `|  |  |`+ - **Benchmark** — the charts, the `summary.md` tables, the commits measured, the machine, and+ a sentence on how to reproduce (`scripts/bench-engine.sh …`).+ - **Testing** — what was run and what was not.+ - Link the issue (`Fixes #N` / `Refs #N`) and, for review follow-ups, the PR being followed up.+- Base is `develop`. Don't enable auto-merge; don't merge.diff --git a/.gemini/skills/nota-shortcuts/SKILL.md b/.gemini/skills/nota-shortcuts/SKILL.mdnew file mode 100644index 00000000..416d537b--- /dev/null+++ b/.gemini/skills/nota-shortcuts/SKILL.md@@ -0,0 +1,66 @@+---+name: nota-shortcuts+description: Keep the Preferences → Shortcuts screen in sync with the app's real keyboard/mouse bindings. Run this WHENEVER you add, remove, or change a keyboard shortcut or mouse gesture (transport keys, editing commands, piano-roll keys, the computer-keyboard note map, device drag, etc.) — the Shortcuts pane is a hand-maintained list and silently drifts from the handlers otherwise. Handles: finding every place bindings are defined, updating the on-screen list, and visually verifying it.+user-invocable: true+---++# Keeping the Shortcuts screen honest++Nota shows its keyboard/mouse shortcuts in **Preferences → Shortcuts**. That list is+**hand-written**, not generated from the handlers — so every time the input handling+changes, the screen must be updated by hand or it lies to the user. This skill is the+checklist for doing that.++**Trigger:** you touched anything that changes what a key or mouse gesture does — a new+hotkey, a re-mapped key, a removed command, a changed computer-keyboard note layout, a new+drag gesture. If your change added/removed/moved a binding, you are not done until the+Shortcuts pane matches.++## 1. The on-screen list (what to edit)++`src/managed/Nota.App/PreferencesWindow.cs` → the static **`ShortcutGroups`** array (feeds+`ShortcutsPane`). It's grouped: `TRANSPORT`, `ARRANGEMENT & EDITING`, `PIANO ROLL`,+`PLAY NOTES (COMPUTER KEYBOARD)`, `MOUSE`. Each row is `(Key, Action)`; the `Key` string is+split on spaces and each token becomes its own mono key-cap (`/` and `·` stay plain+separators) — as long as every token is a key: no lower-case letters, or one of `Space`+`Return` `Delete` `Tab` `Esc` (`IsKeyToken`). Anything else (`Drag note edge`, `Face+buttons`) is a gesture and shows as plain text. The `Action` is a short sentence. Use `⌘` for Meta/Ctrl, `⇧`+for Shift, `⌥` for Alt, and the arrow glyphs `← → ↑ ↓`. Keep actions imperative and terse+(design language: sentence case, `·`/` / ` as separators).++## 2. The source of truth (where bindings actually live)++Read these and reconcile the list against them — do **not** trust the existing pane text:++| Bindings | File |+|---|---|+| Transport (Space/Return), global editing (A, R, M, ⌘M, ⌘G/⌘⇧G, ⌘C/X/V, Delete, Tab, Esc) and the **computer-keyboard note map** (`KeyToPitch`) | `src/managed/Nota.App/MainWindow.Input.cs` |+| Piano-roll note editing (arrows, ⇧ octave, ⌘A/⌘D, ⌘C/X/V, Delete, Esc) | `src/managed/Nota.App/PianoRollView.cs` (its `OnKeyDown`) |+| Arrangement lane / clip gestures (double-click, drag) | `src/managed/Nota.App/ArrangementView*.cs` |+| Device reorder drag | `src/managed/Nota.App/DeviceChainView.cs`, `DeviceCards/…` |++`KeyToPitch` is the note layout: bare letters play notes, and `A` is **deliberately not** a+note (it toggles automation mode) — so the "Play notes" rows must never list `A`. When that+map changes, update the `PLAY NOTES` group (white vs. black keys, and the starting octave).++## 3. Procedure++1. List, from your own diff, every binding you added/changed/removed.+2. Open the source-of-truth file(s) above and confirm the *current* behaviour of each key in+ the affected group — including ones you didn't touch, since the list may already be stale.+3. Edit `ShortcutGroups` so every row matches. Add a row for a new binding, delete a row for a+ removed one, fix the key-cap or wording for a changed one. Put it in the right group.+4. Build: `dotnet build src/managed/Nota.App -c Debug`.+5. Visually verify (see [nota-ui-verify] memory): the pane can't be reached by a click in a+ headless run, so temporarily open it via an env-guarded hook in+ `MainWindow.OnDataContextChanged` (`new PreferencesWindow(new SettingsViewModel(settings),+ _vm).Show(this)`), and select the Shortcuts section (index 8 — count the sidebar entries, it moves as pages are added) — e.g. a temporary env read+ in front of the constructor's `Select(0)`. Screenshot with `screencapture -x -o -l<winid>`+ (get the id from the `winlist` swift helper), check the rows read correctly, then **revert+ the temp hooks** and rebuild.++## 4. Don't forget++- If the change is user-visible, it also wants a `CHANGELOG.md` entry under `## [Unreleased]`.+- Keep the pane concise — it's a reference, not a manual. Group related keys onto one cap+ (`⌘C ⌘X ⌘V`) rather than three rows when the action is one idea.diff --git a/.gemini/skills/release/SKILL.md b/.gemini/skills/release/SKILL.mdnew file mode 100644index 00000000..8c85be7e--- /dev/null+++ b/.gemini/skills/release/SKILL.md@@ -0,0 +1,289 @@+---+name: release+description: Cut a Nota release in three phases. `prepare` (on a release/X.Y.Z branch from develop) promotes CHANGELOG.md [Unreleased] to a dated version, writes the curated EN + RU release notes in release-notes/ (the one source for the GitHub release and the news channels), bumps the app and engine versions, makes the release image and the PR texts. `tag` (on main, after the user merged the release PR into develop and the develop → main PR) creates the vX.Y.Z tag. `verify` (after the user pushed the tag) waits for the build and checks the GitHub draft against the curated notes. Run this when the user asks to release, ship, cut a version, tag a release or check a release build.+user-invocable: true+---++# Cutting a Nota release++Two files describe a release, for two readers:++- **`CHANGELOG.md`** is the raw working log. Entries land under `## [Unreleased]` as work+ merges ("what we did, we write"), so it can repeat itself or hold changes that a later+ entry undid. At release time it is only promoted to `## [X.Y.Z] — date` and is never+ rewritten. The CI guard requires the section, and What's New falls back to it for a+ version without curated notes.+- **`release-notes/X.Y.Z.en.md`** and **`release-notes/X.Y.Z.ru.md`** are the curated+ text: summarised, deduplicated, checked against the code. **Everything published comes+ from them**, and the app bundles the EN file for its What's New window, so the notes must+ be committed on the release branch before the tag is built. They hold a summary, the+ full Added / Changed / Fixed list with a commit link on each item, and the contributors+ (format in P4). `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:++ | target | where it goes | full list |+ |-----------|-------------------------------------------------|-----------|+ | `github` | GitHub release body (the workflow uses this) | yes |+ | `post-en` | English news channels | no |+ | `post-ru` | Russian news channels | no |++The release runs through the branches like this. **The user does every commit, push and PR+by hand.** This skill never commits, pushes or opens a PR (see the user-commits rule).++```+release/X.Y.Z ── /release prepare ── user commits, pushes, opens PR → develop (squash)+develop ── CI green, user merges ── user opens PR develop → main (merge commit)+main ── CI green, user merges ── /release tag ── user pushes the tag+CI ── release.yml builds 6 files + draft release ── /release verify ── user publishes+```++`develop` and `main` are protected (rulesets): changes land only through a pull request+with the `macOS`, `Windows` and `Linux` CI checks green; `develop` takes squash merges,+`main` takes merge commits only, so `develop` → `main` never rewrites history. Release+tags `v*` can be created only by maintainers.++**Argument** (`/release <phase> [bump]`): the phase is `prepare` (default), `tag` or+`verify`. For `prepare` the bump is `minor` or `patch` (see step P2).++---++## Phase 1 — `prepare` (on a `release/X.Y.Z` branch from `develop`)++### P1. Preflight. Stop if any check fails++1. On `develop`: `git rev-parse --abbrev-ref HEAD`.+2. The tree is clean (`git status --porcelain` is empty). Otherwise ask the user to commit+ or stash first, so the release changes stay separate.+3. Up to date: `git fetch origin`, then `git rev-list --left-right --count origin/develop...HEAD`+ must show `0` behind and `0` ahead (unpushed commits on `develop` can't reach it any+ more except through a pull request).+4. `## [Unreleased]` has real entries.+5. Once the version is chosen (P2), create the branch: `git switch -c release/X.Y.Z`. This is+ the only branch operation the skill does itself; every later step edits files on it.++### P2. Choose the bump++The app and the engine always move together, by the same kind of bump:++| bump | when | app | engine |+|---------|----------------------------------------------|-----------------|-----------------|+| `minor` | a major feature (new device, view, workflow) | 0.51.2 → 0.52.1 | 0.30.3 → 0.31.1 |+| `patch` | fixes, polish, small additions | 0.51.2 → 0.51.3 | 0.30.3 → 0.30.4 |++A component that resets starts at **1, never 0**. If the user gave no bump, propose one+from the `[Unreleased]` content and confirm it with them. Preview it with+`scripts/release-bump.sh <bump> --dry-run`. It refuses a version whose tag already exists.++### P3. Promote CHANGELOG.md++Rename `## [Unreleased]` to `## [X.Y.Z] — YYYY-MM-DD` (date from `date +%F`). Add a fresh+empty `## [Unreleased]` above it. **Don't touch the entries**: no Highlights and no+rewording. The changelog stays the honest log. Keep the preamble and older sections as they+are.++### P4. Write the curated notes, EN and RU++This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and+`release-notes/X.Y.Z.ru.md`. Each has four parts, in this order:++1. **Summary**: the lede and the numbered headline features, for someone who reads only+ this part.+2. **Full list**: every user-facing change of the release, grouped as Added / Changed /+ Fixed / Removed.+3. **Commit links**: each full-list item ends with a link to its commit.+4. **Contributors**: everyone who has a commit in the release, linked to their GitHub+ profile.++Steps:++1. **Gather.**+ - The previous tag is the highest version tag:+ `git tag --list 'v*' --sort=-v:refname | head -1`. Don't use `git describe` on+ `develop`: release tags sit on `main`'s merge commits, which `develop` doesn't+ contain, so `describe` returns a tag several releases old.+ - Read the whole `[X.Y.Z]` section you just promoted.+ - `scripts/release-credits.sh <prev-tag> origin/develop commits` lists every commit of+ the release (short sha, sha, subject). It's the checklist for the full list.+ - `scripts/release-credits.sh <prev-tag> origin/develop contributors` prints the+ ready Contributors line. It asks GitHub for every commit's authors and co-authors+ (needs `gh` signed in) and leaves out bots and AI co-authors.+2. **Reconcile.** Merge entries that describe the same thing. Where entries conflict (a+ shortcut reassigned twice, a feature added and then reworked), **the code decides**:+ read the handler, the default or the UI and describe what ships. Drop anything that+ was added and then removed within the same release. Then build the full list from the+ commits:+ - Each user-facing change is one item, linked to the commit(s) that brought it. A fix+ and its follow-up make one item with both links.+ - Leave out internal or mechanical commits (refactors, CI, tests, release chores)+ unless a user can feel them. Their authors are still contributors.+ - Walk the `commits` output once more at the end: every user-facing commit must be in+ an item.+3. **Write.** Each language natively, not as a translation. Format: bold titles and `•`+ bullets, no `#` headings, so the text pastes into Telegram as is. The two comment+ markers say where the full list and the contributors start, whatever the language.+ They are invisible on GitHub, and `release-notes.sh` strips them.++ ```+ <!-- SPDX-License-Identifier: AGPL-3.0-only -->+ One or two sentences on what defines this release.++ **1. Biggest user-facing win**+ A short paragraph: what it is and why a musician cares. Not every changelog detail.++ **2. Next feature**+ …++ <!-- changes -->+ **Added**+ • A new capability, one line ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))++ **Changed**+ • A behaviour users must know: a moved shortcut, a changed default ([e4f5a6b](…), [c7d8e9f](…))++ **Fixed**+ • What no longer goes wrong, said from the user's side ([0a1b2c3](…))++ **Removed**+ • …++ <!-- contributors -->+ **Contributors**+ [@login](https://github.com/login), [@other](https://github.com/other)+ ```++ Rules for the format:+ - Rank the summary's sections by importance. A patch release can have just the lede+ before the full list.+ - Groups go in the order Added, Changed, Fixed, Removed; leave out empty groups.+ Inside a group, put the most noticeable changes first.+ - A commit link's text is the 7-character short sha and its URL takes the full sha+ from the `commits` output. These are `develop`'s squash commits. They become part of+ `main` through the develop → main merge, so the links keep working after the release.+ - New notes have no **Also** block: the full list replaces it, so nothing is listed+ twice.+ - RU titles: **Добавлено**, **Изменено**, **Исправлено**, **Удалено**, **Участники**.+ The EN and RU files have the same groups, the items in the same order with the same+ links, and the same contributors.+ - Contributors: paste the `contributors` line. Resolve every `warn:` line it printed+ on stderr:+ - An author with no GitHub login can be a second address of someone already listed+ (the user's work email, for example). Drop that name.+ - Otherwise, find the login and link it, or keep the plain name.+ - Don't add or remove people by hand otherwise.+ - Leave out the title and the download link, because `release-notes.sh` adds them per+ target. Use the user's product language: "track", "device card", "piano roll", not+ class names.+4. Show the user the three renders and iterate until they approve. The rest of the+ release depends on this text.+ - `scripts/release-notes.sh X.Y.Z github` has all four parts.+ - `post-en` and `post-ru` have the summary and the contributors but no full list. A+ Telegram message holds 4096 characters, and the posts end with the link to the+ GitHub release, which has the full list.++ The app bundles the EN file. What's New shows the summary, then "All changes" with the+ groups, then the contributors, and the links in it are clickable. The smoke test checks+ that every full-list item of a shipped notes file ends in a commit link.++### P5. Bump the versions++`scripts/release-bump.sh <bump>` writes `VERSION` and `src/native/nota.engine/VERSION`+(both without a trailing newline, read with `.Trim()` / CMake). The CI checks the tag against+`VERSION`, so the two must agree.++### P6. Feature list and docs++- Run `nota-features` in `audit` mode: fold this version's entries into `FEATURES.md` and+ set its header to `X.Y.Z`. That change goes into the release commit.+- Run `nota-docs` in `audit` mode over the same entries. Its changes are committed in+ `../nota-docs`. Missing docs don't block the release; list them in the report.++### P7. Release image++Build a 16:9 poster in `../media/news/X.Y.Z-src/` (outside the repo). Start from the last+release's `poster.html` (`ls -d ../media/news/*-src | sort -V | tail -1`) and copy its+fonts.++- Header: the logo, `Nota X.Y.Z` (version in brass), a one-line subtitle taken from the+ notes' lede, and a mono tag row with the 2–4 headline features.+- Two or three cards with real screenshots of the headline features. Shoot them from the+ app (see the UI-verify recipe, with an isolated `NOTA_DATA_DIR`) or reuse fresh shots+ from `../nota-docs`. Use Ember Graphite colours (`nota-design`).+- Render it at 2×:++ ```bash+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \+ --hide-scrollbars --window-size=1280,720 --force-device-scale-factor=2 \+ --screenshot="$PWD/../media/news/X.Y.Z.png" "file://$PWD/../media/news/X.Y.Z-src/poster.html"+ ```++- Look at the PNG (Read it) and check for overlaps, clipped text or empty space before+ showing it to the user. Also save the rendered posts next to it as+ `../media/news/X.Y.Z.en.md` and `X.Y.Z.ru.md` (the output of `post-en` / `post-ru`).++### P8. Hand over to the user++Don't commit. Give the user:++- the version change (`app a → b`, `engine c → d`) and the list of changed files:+ `CHANGELOG.md`, `VERSION`, `src/native/nota.engine/VERSION`, `FEATURES.md`,+ `release-notes/X.Y.Z.{en,ru}.md`,+- the commit message `(chore) Release X.Y.Z` and the push command+ `git push -u origin release/X.Y.Z`,+- the **PR into develop**: title `(chore) Release X.Y.Z` (it becomes the squash commit+ message), body = a short list of the changed files,+- the **PR text** for develop → main, opened after the first one is merged. Title+ `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github` (summary,+ full list and contributors), so the reviewer reads exactly what will be published. Merge it with **Create a merge commit**+ (the only method `main` allows),+- the image path and any docs gaps,+- the next step: merge both PRs once CI is green, then run `/release tag`.++---++## Phase 2 — `tag` (on `main`, after the merge)++1. If the user is still on develop, tell them to run `git switch main && git pull --ff-only`.+ Don't switch branches on their tree yourself if it has changes.+2. Run `scripts/release-tag.sh`. It repeats the CI guard locally (on main, clean, equal to+ `origin/main`, the tag is free locally and on origin, the `## [X.Y.Z]` section and both+ notes files exist) and then creates the annotated tag `vX.Y.Z`. **It doesn't push.**+3. Give the user the push command and the Actions link+ (`https://github.com/nota-daw/nota/actions/workflows/release.yml`):++ ```bash+ git push origin vX.Y.Z+ ```++If the script fails, report its message as is. Common causes: the PR isn't merged yet, or+local main is behind. After the tag, `develop` needs no sync: the merge commit on `main`+already has `develop` as a parent.++---++## Phase 3 — `verify` (after the tag push)++1. Find the run: `gh run list --repo nota-daw/nota --workflow release.yml --limit 3`. Wait+ for it with `gh run watch <id> --repo nota-daw/nota --exit-status` (run it in the+ background, because a build takes about 20–30 min). Don't poll in a loop.+2. If a job failed, show its log tail: `gh run view <id> --log-failed`.+3. When it's green, run `scripts/release-verify.sh X.Y.Z`. It checks that the draft body+ equals `release-notes.sh X.Y.Z github` word for word and that all six files are+ attached (dmg arm64/x86_64, exe x64/arm64, AppImage x86_64/aarch64).+4. Report the result. If the body differs (someone edited the draft, or the notes changed+ after the tag), show the diff and fix it at the source. Don't edit the draft by hand to+ make it match. The user reviews the draft and publishes it themselves, then posts+ `../media/news/X.Y.Z.{en,ru}.md` with `X.Y.Z.png` to the channels.++---++## Don't++- Don't commit, push, open PRs, push tags or publish the release. All of these are the+ user's steps.+- Don't reword or summarise inside `CHANGELOG.md`. Curated text goes only to+ `release-notes/`.+- Don't write published text anywhere except `release-notes/`. GitHub and the channels+ must come from the same files.+- Don't type the contributors or commit shas from memory. Take them from+ `scripts/release-credits.sh`, and resolve its warnings instead of ignoring them.+- Don't bump only one of app or engine, and don't reset a component to 0.+- Don't hard-code the date or reuse an existing version or tag.diff --git a/.github/skills/nota-design/SKILL.md b/.github/skills/nota-design/SKILL.mdnew file mode 100644index 00000000..0b931c2f--- /dev/null+++ b/.github/skills/nota-design/SKILL.md@@ -0,0 +1,176 @@+---+name: nota-design+description: Nota's UI design language — "Studio": the work carries the colour, the interface steps back — neutral greys on dark 1px seams, one orange accent reserved for what is live or chosen, sentence-case labels, in colour themes (Studio Dark — the default — Studio Light, Ember Graphite, Ember Paper). Use whenever building or restyling any Nota UI (windows, panels, controls, device cards, custom-drawn views like the piano roll / waveform / arrangement) so everything stays visually consistent. Points at the authoritative token files and the full guideline rather than restating values.+user-invocable: true+---++# Nota design language — Studio++The work carries the colour; the interface steps back. Neutral greys stepped in a+few exact tones (well · ground · panel · raised), flat panels butted against dark 1px+seams, small crisp type, and **one orange accent that appears only where something is+live or chosen**. Colour is a **theme**: one fixed look, dark or light, that gives every+token a value — Studio Dark (the default), Studio Light, Ember Graphite, Ember Paper. The+structure (layout, type, geometry, where the accent goes) is the same in every theme.+Preferences → Appearance picks a theme or Follow system (a dark-mode and a light-mode+theme); the switch is live. `DESIGN.md` is the guideline, plus the exceptions+the project accepted.++## Read these first — do not work from memory++| File | What it gives you |+|---|---|+| `DESIGN.md` | **The guideline.** Rules, colour themes and the readability bar, every Studio token value, elevation, type scales, number setting, controls and states, device cards, shell, the tests, accepted exceptions, known drift. Start here. |+| `DESIGN.html` | The same thing rendered — swatches, control specimens, a device card at true size, a theme toggle. Generated by `scripts/design-html.py`. |+| `src/managed/Nota.App/Theme/Themes/*.json` | **Definitive colour**: one file per theme, one value per token (incl. shadow colours and Fluent's accent ramp). |+| `src/managed/Nota.App/Theme/NotaTheme.axaml` | **Definitive** geometry, type classes, control styles. Holds no colour. |+| `Theme/NotaPalette.cs` · `NotaColourTheme.cs` · `NotaThemeService.cs` | The token slots (the catalogue) and helpers (`Wash`, `InkOn`, `Ink`, `Derived`) · loading and validating themes · applying a theme: slots re-tinted, the same brushes published as `Brush.*`, `Shadow.*` built. |+| `Theme/NotaGeometry.cs` · `NotaFonts.cs` · `NotaText.cs` · `NotaNum.cs` | Radii/sizes/spacing · Geist typefaces and type scale · sentence-case labels · number formatting. |+| `DeviceCardKit.cs`, `Controls/` | The shared controls and card builders; `Controls/NotaGraph.cs` for graph windows. |+| `tests/Nota.SmokeTest/DesignTokenCheck*.cs` | The guard tests (incl. `RunStudio`, `RunThemes`, `RunLabels`, `RunIcons`) and their ratchet lists (`*AllowList.txt`, which only shrink) — run the smoke test after any UI change. |++If `DESIGN.md` / `DESIGN.html` disagree with the theme files, **the theme files win** and+the docs need fixing. Say so rather than propagating the drift.++> This skill deliberately does **not** restate token values. An earlier version did, and+> it drifted a whole palette out of date. Read the files.++## Non-negotiables++Most of these are enforced by `DesignTokenCheck`; the smoke test fails when one breaks.++- **No literals in views.** XAML: `{DynamicResource Brush.*}` / `{DynamicResource Shadow.*}`+ (a `StaticResource` cannot follow a theme change) and+ `{StaticResource Radius.*|Control.*|Space.*}`. C#: `NotaPalette` (a slot,+ `Wash(slot, alpha)`, `InkOn(fill)`, `Ink("#hex")` for a one-off device hue),+ `NotaRadius`, `NotaSize`, `NotaSpace`, `NotaFonts`, `NotaType`. No hex outside `Ink()`,+ no RGB typed as numbers, no `Colors.X` / `Brushes.X` except `Transparent`, no font+ family names, no `new BoxShadows` in a view.+- **Nothing may snapshot a colour.** `new SolidColorBrush(slot.Color)`, a+ `static readonly Color` or brush built from the palette, or a static array of palette+ colours freezes the view in one theme. Use the slot, `Wash`, `InkOn`, `Derived`, a+ property, or read `.Color` inside `Render`. Track colours:+ `ArrangementView.TrackBrush(index)`.+- **Accent = live or chosen, only.** Playing, selected, the playhead, the loop, a toggle+ that is on, a chosen segment, menu hover, the device power switch, and a value control+ *while hovered or dragged*. If it is orange and none of those, it is wrong. **Resting+ values are neutral `VizInk`** — knob arcs, fader and slider fills, value bars, graph+ curves, waveforms. A modulation arc keeps its source chroma. There is no second accent.+- **Semantic fills with derived ink.** Mute on = `Mute` (amber), solo on = `Solo` (blue),+ arm / record on = `Record` (red), solid, with `NotaPalette.InkOn(fill)` for the text or+ glyph — never a fixed label colour on a themed fill. Green is positive status and the+ meter's safe range. Graph chromas (viz ink · teal · rose · blue) live only inside graphs.+- **Seam between, rule within.** Panels meet on `Seam` and so do keys in a segmented+ group; items inside a panel are divided by `Rule` (separators, field edges, graph+ frames).+- **Flat docked, blur only floating.** No gradients, glow or textures. Depth is a tone+ step + a 1px seam + the `Shadow.Raised` top bevel on raised controls. Only a floating+ layer drawn in the main window (`Shadow.Popover`, `Shadow.Modal`) carries a blur; menus+ and popups get a seam ring only (Avalonia clips a popup's shadow at its window edge).+- **Radii 2 / 3 / 4.** `Radius.Clip`/`Badge` 2 for inner keys, rows, clips, menu items;+ `Control`/`Tile`/`Panel`/`Body`/`Pill` 3 for controls, cards, graph windows, popovers;+ `Modal` 4 for modals only; `Docked` 0; `Bar` 1 for bars inside a plot.+- **Geist for words, Geist Mono for every number a user reads.** Names are never mono.+ Nothing under 7 px.+- **Sentence case, no tracking — every label.** Menu items, command titles, palette+ headings, window titles, tooltips, buttons: "Save as…", "Export audio", "Recent". Capitals+ stay only on acronyms and units (`NotaText.Fixed`), "Nota …" product and device names,+ the view names (Arrangement, Session, Modular, Mixer), proper nouns, and a page after+ "Settings: ". Route labels through `NotaText.Label` (it sentence-cases caps literals and+ keeps acronyms and units: `LFO rate`, `Gain dB`). Never `ToUpperInvariant()` a label,+ never set `LetterSpacing`. `RunLabels` fails on an all-caps or Title Case literal;+ `LabelAllowList.txt` is for data only (preset, mode, proper names).+- **Opacity is not a state.** Disabled and muted take the next ink step; use+ `Inactive.Set` for a subtree. The only allowed `Opacity` is a drag ghost.+- **State changes colour only** — never size, border width or position. Hover and colour+ transitions 120 ms ease-out; meters, playhead and spectra are never animated.+- **Numbers are set, not printed.** The app installs a display culture (point decimal,+ U+2212 minus — typed literals too, `"−12"`, never `"-12"`). Put a thin space (` ` in+ source) before units, keep precision fixed (dB one decimal, tempo two, percent whole, Hz+ up to 999 then `3.2 k`) — use `NotaNum` helpers. Ranges take an en dash, closed between+ plain numbers (`1–127`), spaced when an endpoint has a space (`20 Hz – 20 kHz`).+- **Every icon is a `Glyph`.** `Controls/Glyph.cs` is the one icon set: path kinds on a+ 16-unit grid, scaled as a whole (never `Stretch.Uniform`); stroked parts take the shared+ pen (round caps and joins, `max(1.2, size × 1.5/16)`), filled parts the ink (transport+ shapes, the Arrangement / Session view keys, OS marks, `StarFilled`, carets, Snap). A+ missing icon is a new `GlyphKind` with a one-line comment, never a path in a view —+ `RunIcons` fails on `Geometry.Parse`, `Data="M…"` or a path string outside `Glyph.cs`.+ No unicode symbols (`■ ▶ ● ✓ ★ ▾`…) and no emoji as text. `·` separates meta; `→` in+ prose is fine.+- **Copy:** English. Labels one word where it fits, no vowel-dropped contractions+ (`Feedback`, not `Fdbk`; `Freq`/`Reso`/`Thresh` are allowed). Tooltips short and+ verb-first. Empty states are one Ink 5 line.++## Device cards++- **700 × 260** (`DeviceCardKit.CardH`; width exceptions are listed in `DESIGN.md`): panel+ body, radius 3, seam frame.+- **Header 22** (`BuildCardShell` in `DeviceChainView.Shell.cs` — every card uses it,+ racks, the generic instrument card, plug-ins and Sends included; never build a header of+ your own): a raised strip with the `Shadow.Raised` bevel, in fixed slots **name · preset ·+ badges · power**. The preset picker `‹ Name ⌄ ›` is centred in the header between two+ equal halves (name left, badges and power right), only when the device has presets; the badges — the+ type badge (mono, muted, sentence case) and the card's accessories (`HeaderExtra`: Learn,+ S / L) — right-aligned; the power switch (accent while on) last, its slot reserved even+ on a card that cannot be bypassed. A/B, move and delete go in the right-click menu.+- **Body:** inset 6; columns choice → work → output. **Sections are+ `DeviceCardKit.Section(body)`** — no fill, no frame, a 1 px `Rule` on a top or left edge+ facing a neighbouring section (found from the layout, or pass `SectionEdge`); never a+ framed `Border` box. Graph windows and wells keep their frames; chips, tiles, pads and+ readouts are not sections. Titled in `DeviceSection` (muted 600). Device text keeps the+ device scale (7.5–10.5 px) because the frame is kept.+- Values at rest neutral, the accent only for what is live or chosen; modulation shows its+ source chroma; graphs go through `NotaGraph` (well, rule frame, radius 3, `VizGrid`,+ `VizInk` primary curve, accent only on the active node, corner axis labels, no fills+ under curves).++## Adding a control++Reuse before writing: `Knob` (sizes snap to 34/36/44), `DeviceCardKit.KnobCell` (53 tall),+`SwitchTrack` / `DeviceCardKit.Switch` (18 × 10), `DeviceCardKit.Segments`, `SliderTrack` /+`DeviceCardKit.SliderRow`, `MiniFader`, `PanBar`, `VFader`, `DragNumber`, `MeterBar` /+`StereoMeter` / `GrMeter`, `Glyph`, `NaBadge`. Sizes and specs: `DESIGN.md` § Controls.++A new value control **must** match the interaction contract:++- Vertical drag, up increases, full range over ~140 px; Shift/Ctrl/⌘ for fine steps;+ `ns-resize`; a click never jumps the value; no horizontal drag (except a horizontal+ slider along its own axis, `SliderTrack`)+- Double-click restores the default+- Left button only — right-click must bubble to the CV-modulate / MIDI Learn menu+- `GestureBegin` / `GestureEnd` bracket `BeginAutomationWrite` / `EndAutomationWrite`+- Register with `MidiLearn.Bind`+- Live-follow refresher that **skips while dragging**+- Mono readout so width does not jump; the value is always visible, not only in a tooltip+- Its value drawn in `VizInk` at rest and the accent only while hovered or dragged++## Applying it (Avalonia)++- `NotaTheme.axaml` is merged in `App.axaml`; `NotaThemeService` applies the colour theme+ (resolved from settings by `Nota.Application.Appearance`) to both layers. `NotaNum.Install()` runs in `App.Initialize`.+- Buttons: default (raised, seam border, bevel), `primary` (weight and one tone step —+ not colour), `ghost`, `cell` (a readout well), `chip`, `tp-icon`, `tp-play`; a+ `ToggleButton` that is checked is a solid accent key with derived ink.+ `ToggleButton.seg` inside `Border.segmented` (keys butted on 1px seams).+ Containers: `Border.Panel`, `Border.Card`, `Border.well`, `Border.transport`,+ `Border.console`. Fields: `TextBox.field`, `TextBox.search`.+- Text: shell `Title`, `Heading`, `Name`, `Caption`, `SectionLabel`, `CellLabel`,+ `Readout`, `Value`, `Eyebrow`; device `DeviceName`, `DeviceSection`, `RowLabel`,+ `KnobLabel`, `KnobValue`, `Axis`.+- Elevation: `BindResource(Border.BoxShadowProperty, "Shadow.Raised" | "Shadow.Sunken" |+ "Shadow.Popover" | "Shadow.Modal")` — never a literal.++## When you change a token++1. Change the value in each theme file in `Theme/Themes/` it should change in (both Studio+ themes at least). A **new** token is a `T(nameof(X))` slot in `NotaPalette`, a value in+ **every** theme file (the smoke test names a file that lacks it), and a `KeyMap` entry+ if XAML uses it.+2. Every theme must still pass the readability bar (`DESIGN.md` § Readability bar).+3. Run `python3 scripts/design-html.py` and update the table in `DESIGN.md`.+4. Check every theme — in the app and in `DESIGN.html` (`?variant=light`, `?variant=ember-paper`…).++## When you add a theme++Add `Theme/Themes/<id>.json` (every token; `kind` dark or light) and append the id to+`NotaThemes.BuiltInOrder`. Nothing else names a theme. Run the smoke test (`RunThemes`).diff --git a/.github/skills/nota-docs/SKILL.md b/.github/skills/nota-docs/SKILL.mdnew file mode 100644index 00000000..b648ce49--- /dev/null+++ b/.github/skills/nota-docs/SKILL.md@@ -0,0 +1,134 @@+---+name: nota-docs+description: Keep the user documentation (sibling repo ../nota-docs, Astro Starlight, EN + RU) in sync with the app. Run this WHENEVER you add, change or remove a user-visible feature — a new device or parameter, a new view/panel/window, a changed workflow, a moved menu item, a new or re-mapped shortcut, a new Preferences option — i.e. whenever you write a CHANGELOG [Unreleased] entry. Also run it from /release to catch anything that slipped. Handles: finding the affected pages, editing the EN page and its RU twin, re-shooting screenshots (nota-design mockups or the headless app), regenerating the shortcuts page, and building/checking the site.+user-invocable: true+---++# Keeping Nota Docs honest++The user manual lives in **`../nota-docs`** (relative to this repo; GitHub `nota-daw/nota-docs`),+built with Astro Starlight in **English (root) and Russian (`/ru/`)**. It is written by hand,+so every user-visible change in this repo must be mirrored there or the manual lies. The+overall structure and conventions are in `../nota-docs/PLAN.md` — read it once if you have+not.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+`Added` / `Changed` / `Removed` almost always need a docs edit; `Fixed` only when the fix+changes what the docs describe. Pure refactors, perf and internal changes need nothing.++**Argument** (`/nota-docs <arg>`, optional): a feature name, a changelog line, or `audit`+(reconcile *all* `[Unreleased]` entries — used by `/release`). No argument → the change you+just made in this session.++If the page that should cover the change is still a stub (`status: todo`) and you are not+writing it now, append `{page, change, version}` to the `pending:` list at the bottom+of `../nota-docs/coverage.yml` so the stage that writes that page picks it up, tell the user,+and stop.++## 1. Work out what changed for the user++From the diff and the CHANGELOG entry, list concretely: new/renamed UI labels, new+parameters with ranges and defaults, new menu items and where they sit, new shortcuts,+changed behaviour, removed things. Take names and numbers **from the code** (the device's+DSP class and card under `src/managed/Nota.App/DeviceCards/…`, menus in `MainWindow.axaml`,+`PreferencesWindow.cs`), never from memory or the mockup — the changelog itself can be+contradicted by a later entry.++## 2. Find the pages++1. `../nota-docs/coverage.yml` maps features and source paths → page slugs. Look up every+ file you touched and every feature you named.+2. Grep page frontmatter `sources:` in `../nota-docs/src/content/docs/**/*.mdx` for the+ touched paths, and grep page bodies for the old UI label / old shortcut.+3. Nothing found → it is a new feature. Decide its place in the sidebar (see `PLAN.md`),+ copy `templates/page.mdx` (or `templates/device.mdx`) into both+ `src/content/docs/<slug>.mdx` and `src/content/docs/ru/<slug>.mdx`, and add it to+ `coverage.yml`. The sidebar autogenerates per directory (order via `sidebar.order`); only a+ brand-new top-level section needs an entry in `astro.config.mjs`.++Typical fan-out — check all that apply:+- the feature's own page (device, view, panel, preference pane);+- the overview that lists it (Devices index, Views index, "Main window tour");+- `reference/shortcuts` — regenerated, see step 4;+- the glossary, if you introduced a term;+- tutorials that walk through the changed flow (the old steps may no longer work);+- a new built-in device or a renamed device page → the slug maps in+ `src/managed/Nota.App/NotaDocs.cs` (`Instruments` / `AudioEffects` / `MidiEffects`, indexed by+ engine kind) so the device header's Documentation item opens the right page.++## 3. Edit EN, then RU++- English page under `src/content/docs/<slug>.mdx`, Russian twin at+ `src/content/docs/ru/<slug>.mdx` — **same path, same structure, same screenshots**. Never+ leave one language behind; `scripts/check.mjs` fails on a missing or stale twin.+- A stub page (`status: todo`) you fill in becomes `status: draft` (or `done` once its+ screenshots are in); drop the "Being written" aside.+- Bump `updated:` in both frontmatters to the version in `VERSION` (plus `since:` on new+ pages); add any new source paths to `sources:`.+- Style: short, second person, like the CHANGELOG. UI names exactly as on screen in+ **bold**, keys via `<Kbd>`. In Russian, UI names stay in English (the app is English); the+ explanation is native Russian, not a word-for-word translation.+- Removed feature → delete the text and its screenshots; removed page → delete both+ languages, the sidebar entry and the `coverage.yml` entry, and fix links into it.++## 4. Screenshots and generated pages++`../nota-docs/shots/manifest.yml` lists every image (its header documents the scenes and+args). `npm run shots -- <id-prefix> …` retakes them into `src/assets/shots/{dark,light}/`.++- **app** shots render the real UI headlessly (`shots/app`, both themes, 2×, user/device names+ scrubbed). They build against this repo's `src/managed/Nota.App`, so build the app first if+ you changed it. **design** shots come from `../nota-design` (dark only).+- UI that changed visibly → retake its ids (e.g. `npm run shots -- devices/audio-effects/shutter`).+- New device → add `devices/<group>/<slug>/card` (`scene: device` with its kind id) plus one+ shot per tab you document (`args: {tab: "<tab text>"}`, a chain like `"L>Env"` when a size+ switch comes first, `preset` for an interesting state). Write the page from+ `templates/device.mdx`; facts come from the engine header's top comment and `paramName`,+ the card file's header comment and labels, and `FactoryPresetCatalog` — give a range only+ when the code states it.+- New window / view / Settings page → a new scene in `shots/app/Scenes.cs` if none fits; keep+ it deterministic (demo song, no real user data).+- Mockup no longer matches the code → switch that id to `source: app`; never document the mockup.+- A scene breaks after an app refactor (renamed private method, control name) → fix the+ harness; it reflects into `MainWindow` / `PreferencesWindow` privates on purpose.+- Shortcut changed → `npm run shortcuts` regenerates `reference/shortcuts` (EN + RU) from+ `PreferencesWindow.ShortcutGroups`; run the `nota-shortcuts` skill first so that list is+ right.++## 5. Verify and commit++```bash+cd ../nota-docs+npm run build+npm run check+```++Node may not be on PATH (Homebrew's node isn't linked on this Mac) — use+`/opt/homebrew/Cellar/node/*/bin`. The dev server is the `nota-docs` entry in this repo's+`.claude/launch.json` (preview_start).++Both must pass (broken links, missing RU twin, image id not in manifest, `updated:` older+than a touched source). Look at the changed pages in `npm run preview` via the built-in+browser when screenshots or layout changed.++Commit in **`../nota-docs`**, separately from the app repo: `(docs) <what changed>`, no+Claude attribution trailer. Don't push unless the user asked.++## 6. Report++List the pages changed (EN + RU), screenshots re-shot, anything you could not document+(e.g. a scene the harness can't render) and the gaps you left in `coverage.yml`.++## /release audit mode++Go through every `Added` / `Changed` / `Removed` entry of `[Unreleased]`, check each against+the docs as above, fix what's missing, then `npm run build && npm run check`. Report+the coverage to the user before the tag is created; missing docs do not block a release, but+say so plainly.++## Don't+- Don't document plans, mockup-only features or anything not in the code.+- Don't update only one language.+- Don't hand-edit the generated shortcuts page.+- Don't copy CHANGELOG prose verbatim — the changelog says what changed, the docs say how+ to use it now.diff --git a/.github/skills/nota-features/SKILL.md b/.github/skills/nota-features/SKILL.mdnew file mode 100644index 00000000..7fe279a8--- /dev/null+++ b/.github/skills/nota-features/SKILL.md@@ -0,0 +1,104 @@+---+name: nota-features+description: Keep FEATURES.md (the consolidated "what Nota can do" list in the repo root) in sync with the app. Run this WHENEVER you add, change or remove a user-visible capability — a new device or parameter, a new view/panel/window, a new workflow or editing command, a new MCP tool, a new export option, a new platform/build/CI capability — i.e. whenever you write a CHANGELOG [Unreleased] Added/Changed/Removed entry. Also run it from /release in `audit` mode to catch anything that slipped and bump the "as of version" line.+user-invocable: true+---++# Keeping FEATURES.md honest++`FEATURES.md` is the single page that answers "what can Nota do *right now*". It is written+by hand and is not generated from the changelog, so it drifts unless every feature change is+folded into it. It describes **what is implemented in the code**, not plans, and it is a+**current-state** document: no history, no "now", no "previously", no version numbers per+item — that is the CHANGELOG's job.++**Trigger:** you wrote (or are about to write) a `CHANGELOG.md` entry under `[Unreleased]`.+- `Added` → almost always a new bullet or an extension of an existing one.+- `Changed` → rewrite the bullet that describes the old behaviour so it describes the new.+- `Removed` → delete the mention (search the whole file — features get cross-referenced).+- `Fixed` → only if the fix changes what the list claims (a limit lifted, a platform now+ supported). Pure bug fixes, refactors, perf and internals need nothing.++**Argument** (`/nota-features <arg>`, optional): a feature name, a changelog line, or+`audit` (reconcile everything since the version in the file's header — used by `/release`).+No argument → the change you just made in this session.++## 1. Find where it belongs++Read the Contents list at the top of `FEATURES.md` and pick the section by what the user+sees, not by which code you touched:++| Change | Section |+|---|---|+| OS support, installers, auto-update, audio/MIDI backends | Platforms and distribution |+| Projects, saving, version history, transport, tempo, loop, metronome | Project and transport |+| Arrangement / Session / Modular / clip editors / piano roll behaviour | Views |+| Track types, routing, sends, groups, mixer window | Tracks and mixer |+| Note editing, MIDI input, MIDI Learn, controllers | MIDI and virtual instruments |+| Recording, audio clips, warp, stretch, stems | Audio: recording, clips, warp |+| Automation lanes, envelopes, modulation | Automation |+| A built-in instrument / audio effect / MIDI effect / rack | Built-in devices → the matching `###` subsection |+| VST3/AU hosting, plugin scanning, plugin windows | Plugin hosting |+| Browser tabs, sample library, presets, smart samples | Browser and assets |+| Render / bounce / stems export | Export |+| Windows, themes, menus, dialogs, Nota Remote UI | Windows and interface |+| A new Preferences option | Preferences |+| A new or changed MCP tool | MCP / AI control (also mention it on the feature's own bullet if it has one, as existing device bullets do: "MCP `read_sampler` / `set_sampler`") |+| Build scripts, CI, tests, licensing | Other |++Before writing, `grep -n` the file for the feature's name and its key words — the feature+may already be partly described (often it is an extension of an existing bullet, e.g. a new+parameter on a device). **Extend the existing bullet rather than adding a duplicate.** If a+genuinely new top-level area appears, add a `##` section *and* its Contents link (anchor =+GitHub slug of the heading).++## 2. Write it in the file's voice++Match the surrounding bullets — read the neighbours first.+- One bullet per feature; **bold** the feature's name at the start, then a dash or colon and+ what it does. Nested bullets only for sub-features of one thing (see Transport).+- English, present tense, plain language a musician understands. State capabilities and+ user-facing names (menu items, tab names, button labels exactly as in the UI), shortcuts+ in the app's glyphs (⌘ ⇧ ⌥, "Cmd/Ctrl" where the file already does).+- Concrete over vague: parameter names, modes, counts ("25 factory presets", "Poly 16 /+ Mono / Legato") — but verify each number in the code/presets, don't copy it blindly from+ the changelog.+- Condense. The changelog entry explains the change; FEATURES states the result in roughly+ half the words. No rationale, no "fixes", no internal class names (file paths only in+ Other / Platforms, as already done there).+- Built-in devices: follow the existing device bullet shape — what it is · its main controls+ and modes · tabs/sizes of the card · preset count · MCP tools if any.+- Hard-wrap at ~90 columns like the rest of the file.++## 3. Verify against the code++The changelog can be ahead of, or behind, reality. For each claim you add, confirm it in the+source (device kind registration, the view/menu code, the MCP tool list in the MCP server,+the preset folder). If something in the changelog was later reverted or is behind a flag+that is off by default, leave it out (or say "experimental, off by default" if the user can+turn it on).++## 4. `audit` mode (from /release)++1. Read the version in the header line ("as of version **X.Y.Z**").+2. Collect every `CHANGELOG.md` entry newer than that version: all `## [A.B.C]` sections+ above `## [X.Y.Z]`, plus `[Unreleased]` / the section being released right now.+3. For each `Added` / `Changed` / `Removed` entry (and relevant `Fixed`), check whether+ `FEATURES.md` reflects it; fix what is missing or stale per sections 1–3.+4. Update the header: set the version to the one being released (or the latest released+ version when run outside a release), keep "(plus changes in development on `main`)".+5. Report the list of entries you added/changed in FEATURES.md and anything you+ deliberately skipped (and why).++## 5. Finish++- Re-read the edited section as a whole: no duplicates, no contradictions with other+ sections, Contents still matches the `##` headings.+- The SPDX header on line 1 stays.+- Commit FEATURES.md together with the feature (or the release commit in audit mode);+ don't make a separate commit unless the user asks.++## Don't+- Don't paste changelog entries verbatim, and don't add dates or version tags to items.+- Don't describe planned, unmerged or disabled-by-default work as available.+- Don't reorganize or restyle sections you weren't asked to touch.diff --git a/.github/skills/nota-instrument/SKILL.md b/.github/skills/nota-instrument/SKILL.mdnew file mode 100644index 00000000..81ffc46e--- /dev/null+++ b/.github/skills/nota-instrument/SKILL.md@@ -0,0 +1,238 @@+---+name: nota-instrument+description: How to build a Nota built-in instrument, audio effect or MIDI effect end-to-end — the DSP class, the kind-registration checklist across the C++ engine and C# managed layers, and the device-card UI design approach (signal-chain panels, tabs, the shared gauge knob, interactive graphs, using the card space well). Use whenever adding or reworking a built-in synth / audio effect / MIDI effect or its editor. Reference implementations: Nota Volt (instrument), Nota Vintage / Auto Filter (audio effect), Nota Arp (MIDI effect).+user-invocable: true+---++# Building a Nota built-in instrument, effect or MIDI effect++This skill covers **all three built-in device families** — an **instrument**+(the track's sound source), an **audio effect** (an insert `Device`), and a+**MIDI effect** (a `MidiDevice` that transforms notes before the instrument).+The DSP conventions (§1) and card design (§3) are shared; only the base class,+the **registration path (§2)** and the **card interface (§3)** differ — effects+and MIDI effects register through a much lighter path than instruments.++The canonical example is **Nota Volt** (virtual-analog synth, kind 6):+`src/native/nota.engine/src/devices/instruments/VoltSynth.h` + `.cpp` (DSP) + `DeviceCards/Instruments/VoltInstrumentCard.cs` (UI).+Its editor is the reference build of the card layout — **read it first when designing+a synth UI, together with `DESIGN.md` § Device cards and the rendered specimens in+`DESIGN.html`.** Good+effect exemplars: **Auto Filter** and **Nota Vintage** (audio, `: public Device`),+**Nota Arp** (MIDI, `: public MidiDevice`). Also load the `nota-design` skill.++Built-in **instruments** (`kind()` ≥ 0): 0 Synth, 1 Sampler, 2 Physical (modal),+3 Instrument Rack, 4 Drum Rack, 5 Aurora (wavetable), 6 Volt, 7 Bass. **Audio+effects** (`builtinKind()`): 0 EQ, 1 Compressor, 2 Reverb, 3 Delay, 4 Utility,+5 Effect Rack, 6 Amp, 7 Auto Filter, 8 Vintage. **MIDI effects** (`midiKind()`):+0 Arp, + Chord / Scale / Note Length / Velocity / Random. **Grep the current+registration for the next free kind before picking one** — this list drifts.++## 1. DSP class (`.h` + `.cpp` pair)++Put the device in its family folder — `src/native/nota.engine/src/devices/+instruments/<Name>.h` + `.cpp` (`final : public Instrument`), `devices/effects/`+(audio effect, `: public Device`, in-place stereo `process(buf, frames)`), or+`devices/midi_fx/` (`: public MidiDevice`, MIDI effect) — and add both files to+`src/native/nota.engine/CMakeLists.txt`. The header declares, the TU implements;+**every new file carries the AGPL SPDX two-line header. Allocation-free after+construction** (pre-size buffers). Rules:++- **Parameters via the plugin-param interface** (`pluginParamCount/Id/Name/Get/Set/+ IndexOfId`). Values are **normalized 0..1** in `std::atomic<float> pn_[N]`+ (audio-thread read). Denormalise inside `render()` to musical units+ (`expMap(v, lo, hi)` for time/cutoff/rate; bipolar = `(v-0.5)*2`; discrete =+ `round(v*(n-1))`). This gives **automation, persist and clone for free** — the+ engine already routes `PluginParam` + `deviceIndex<0` to `instrument->pluginParamSet`.+- **Param order = the persisted state layout — APPEND ONLY.** `getState`/`setState`+ serialize `N` little-endian floats; `setState` tolerates a shorter/longer blob.+ `clone()` copies `pn_` + sample rate. Ids are stable strings; names are display.+- **DSP conventions:** 16 voices, per-sample outer loop when modulation must stay+ smooth; recompute expensive filter coefficients at control rate (every ~16+ samples), not per sample — control-rate math stays `std`-exact, `FastMath`+ applies only to downstream/published sample values. Steal the quietest voice. polyBLEP saw/square if you+ care about aliasing (Volt/Aurora do); a TPT/Cytomic SVF gives LP/HP/BP/Notch+ from one filter (`dsp/primitives/` has the shared SVF, ladder, biquad, delay,+ oscillator, envelope, oversampler and convolution blocks — reuse them, don't+ re-implement). `kind()` returns the new integer; `displayName()` the label.+ Support auto-sleep (`hasTail()`/`isIdle()`/`wake()`): sleep only fully decayed+ blocks, never a frozen loop; the engine never skips `process()` — your own+ skip must advance phases so the device resumes seamlessly.++## 2. Registration checklist (mirror an existing kind)++Grep the exemplar and copy every site. **Instruments** carry the most sites+(they need their own track + C ABI); **audio/MIDI effects register through a much+lighter path — see the end of this section.**++### Instruments (`grep -rn Volt` / `grep -rn Aurora`)++**Native:** `Engine.h` decl `add<Name>Track`; `Engine_Devices.cpp` (the method ++`#include` + `cloneInstrument` switch + `makeBuiltinInstrument` switch);+`devices/racks/RackCore.h` `makeInstrument` switch + include; C ABI+`nota_engine_add_<name>_track` in `src/abi/nota_engine_track.cpp` **and** the decl in+`include/nota/nota_engine.h` (the `_nota_*` export list is a wildcard — no change).++**Managed:** `NativeMethods.Tracks.cs` (`[LibraryImport]`), `NotaEngine.Tracks.cs`+(wrapper), `IAudioEngine.cs` (interface); `Nota.Application/Palette/BuiltinDeviceCatalog.cs`+(the one device list the browser and the command palette read: name, `Kind = N`, sub text **and+a semantic descriptor** — role, aliases, character, sound/source, genre, a one-line+description; the palette smoke test `--palette` fails without a role and aliases), and its+browser category in `Nota.Application/Palette/DeviceCategories.cs` (the category chip it is listed+under — Synths, Dynamics…; the `-- design: browser --` check fails until it has one);+`DeviceInsertService.CreateInstrumentTrack` in Nota.Presentation (`N => Engine.Add…` — the+one place drag & drop, the browser and the palette create the track);+`ProjectService.cs` (`{ Kind: N }`) + `PresetService.cs` (`N =>`); rack/drum+"add chain / add pad" menus in `DeviceCards/Rack/RackCardView.cs`+(`AddChainButton`, `ShowAddPadMenu`).++**Automation menu:** built-in instruments (`TrackInstrumentKind >= 0`) must list+their params *directly, grouped* via `BuildBuiltinInstrumentAutoMenu`+(`ArrangementView.Automation.cs`) — NOT the hosted-plugin "Choose parameter…/Learn"+picker (that path made empty-id lanes → "drew a curve, no effect").++### Audio effects (`grep -rn AutoFilter` / `grep -rn Vintage`) — much lighter++No track, no C ABI, no `Engine.h` method: effects are added generically by+`addTrackBuiltinDevice(trackId, kind)`. Only:+- **Native:** the `.h`/`.cpp` pair in `devices/effects/` with `: public Device` and `builtinKind()` returning the kind,+ then register that kind in the **three switches** in `Engine_Devices.cpp` —+ `addTrackBuiltinDevice` **+** `cloneDevice` **+** `makeBuiltinDevice` — plus the+ `#include`. Params use the plain `Device` interface (`paramCount/paramName/+ paramMin/paramMax/getParam/setParam`); **prefer normalized 0..1** (mirror+ AutoFilter/Vintage, not the older raw-unit Amp/EQ). Persist / clone / automation+ are **generic** through the base `Device` (by `builtinKind()` + params) — no+ `getState`/`setState`, no per-kind managed persist code.+- **Managed:** `DeviceCardFactory` `[kind] = new NameDeviceBody()`; a+ `BuiltinDeviceCatalog.cs` entry (`AudioEffect`, kind N, with its semantic descriptor —+ role, aliases, character, source, task) and its category in `DeviceCategories.cs`. The add/drop path (`DeviceInsertService`) is+ already generic. Factory presets get their descriptor from their folder and name+ (`PresetDescriptors`); a new folder whose name isn't vocabulary goes into its folder map.++### MIDI effects (`grep -rn Arpeggiator` / `grep -rn MidiScale`)++Mirror an existing `MidiDevice` (e.g. `devices/midi_fx/Arpeggiator.h`) with `midiKind()`; register+in the engine's MIDI-device factory + `MidiDeviceCardFactory` `[kind]` + a `MidiEffect`+entry with its descriptor in `BuiltinDeviceCatalog.cs` (and its category in `DeviceCategories.cs`). Params/persist/clone are generic like audio effects. Cards sit+**before** the instrument in the chain.++## 3. Editor card architecture++Cards are **strategy classes under `src/managed/Nota.App/DeviceCards/`**, resolved by+a factory and handed a `DeviceCardContext` — `DeviceChainView` is a thin orchestrator+(row + registries + the 60 Hz `RefreshSynthLive` tick) and builds nothing itself.+To add an editor, write a class and register it — no `switch` to edit (open/closed):++- **Instrument** (kind ≥ 0, the track's instrument): `class NameInstrumentCard :+ IInstrumentCard` in `DeviceCards/Instruments/`, `Control Build(DeviceCardContext ctx)`;+ register `[kind] = new NameInstrumentCard()` in `InstrumentCardFactory`.+- **Audio effect** (device): `class NameDeviceBody : IDeviceBody` (`double Width`,+ optional `bool AutoWidth => true` to size the card to its content,+ `Control Build(ctx, deviceIndex)`) in `DeviceCards/Bodies/`; register in+ `DeviceCardFactory`. The shared device shell (bypass/reorder/remove) wraps it —+ the body has NO instrument live-follow; use `ctx.AddDeviceRefresher(a)` for the+ 60 Hz visual and read/write params with `engine.DeviceGetParam/DeviceSetParam` ++ `BeginAutomationWrite/EndAutomationWrite` (see `AutoFilterDeviceBody`/`VintageDeviceBody`).+- **MIDI effect**: `class NameMidiBody : IMidiDeviceBody` in `DeviceCards/Midi/`;+ register in `MidiDeviceCardFactory`. The racks live in `DeviceCards/Rack/RackCardView.cs`.++Everything a card needs comes through **`ctx`** (never reach into the view): `ctx.Engine`,+`ctx.TrackId`; `ctx.AddDeviceRefresher(a)` for a 60 Hz visual; `ctx.AddInstFader(i,knob,val)`++ `ctx.SetInstLiveViz(refresh)` for instrument live-follow; `ctx.NotifyChanged()` /+`ctx.RequestRebuild()` / `ctx.RequestPresetSave(i)`. Stateless strategies are singletons —+all per-rebuild state stays behind `ctx`. Shared builders: `DeviceParamControls` (param+faders + sidechain), `InstrumentControls.InstKnob`, `SamplerEditor`.++Follow the mockup language:++- **A device card is a fixed rectangle**, height `CardH` (260, shared by all cards)+ — content taller than that is clipped (`ClipToBounds`). **Gotcha:+ `SimpleCard(title, width, body)` — the 2nd arg is WIDTH; height is always CardH.**+- **Use the working space deliberately — no dead space, nothing overflowing.**+ Fill the card's width with content and don't leave a half-empty card or let+ panels spill past the edge. Size each panel to its own controls, then make the+ card track that: either set `Width` to the sum of the panels, or (audio effects)+ set `AutoWidth => true` so the card sizes to content exactly — the safest way to+ guarantee "it all fits". Lay bordered **islands** side by side and give a large+ interactive graph its **own** framed island next to the knob panels (Nota Vintage:+ CHARACTER / WEAR / SHAPE). If the content genuinely can't fit 260px tall at a sane+ width, **split into tabs** (below) rather than shrinking every control. Always+ do the visual check and trim leftover margins.+- **If there's more than one logical section, use tabs** inside the card (e.g.+ Signal Path / Modulation) with a segmented toggle styled like the Devices/Clip+ segment, swapping a `ContentControl`. One section = one horizontal row that fits+ 260px tall.+- **Card sizes (S / L) are views of ONE device, never two devices.** When a mockup gives a+ device a mini (S, 260) and a full (L) size (Nota Arp is the reference):+ - **Presets belong to the device, not to the size.** Both sizes show the same preset+ picker with the **full** preset list and the **same current preset** — pick a preset in+ L, flip to S, it is still selected there (and vice versa). S may edit fewer params, but+ a preset still sets all of them. Never swap the picker for another control in S; the+ shell's `ShellSpec.Compact` only narrows it (and hides the type badge).+ - Every value is shared; S just exposes a subset (e.g. 4 knobs). No per-size params.+ - The size itself is **editor state**: store it in an appended param (`View`, 0 = L,+ 1 = S) so it persists with the project and clones, but keep it out of presets (in-place+ preset apply skips `View`), and out of the automation menu.+ - Plumbing (MIDI effects): `IMidiDeviceBody.WidthFor(engine, track, index)` returns 260/700+ from `View`; `HeaderAccessory(ctx, index)` puts the S/L toggle (and L-only extras) in the+ shell header; the toggle writes `View` and calls `ctx.RequestRebuild()`. Per-card UI+ state that should survive the rebuild (active tab, selected lane) lives in a static map+ keyed by (track, index), not in the singleton body.+ - Plumbing (instruments, Nota Synth is the reference): append a `"view"` plugin param to the+ DSP (its default in the constructor is the instrument's default size — Synth opens as S);+ `InstrumentView` (Nota.Application) finds/reads/writes it, and presets, A/B, the automation+ menu (by id) and the rack chain card (by the name "View") already skip it. The card implements+ `IInstrumentCard.WidthFor(engine, track)` + `HeaderAccessory(ctx)` with+ `MidiCardHeader.SizeToggle(ctx, isMini, setMini)`; the shell goes compact under 300px.+- **Lay panels as a signal chain**: bordered titled sections left→right with `▸`+ arrows (Osc → Noise → Filter → Amp). Each panel = `Border` (SurfaceCard fill,+ 1px border, radius 7) with a bold section title.+- **Controls, in order of preference for space:**+ - The shared **gauge `Knob`** via `InstrumentControls.InstKnob(ctx, idx, id, name, refresh, size, cellW, arc)`+ — 270° groove + value arc + pointer. Pass a teal `arc` for **modulation-depth**+ knobs (env/lfo/key amounts, velocity, vibrato); amber (default) for everything+ else. Double-click resets to the param default.+ - **`KnobGrid(cols, …)`** packs knobs into centered rows (2×2, or vertical for+ 1 col) to shrink a panel; a partial last row stays centred.+ - **Interactive graphs are controls, not decoration**: a drag ADSR editor+ (`VoltEnv`) and a drag filter response (`VoltFilter`, X=cutoff / Y=reso, curve+ follows the type, with grid + fill + freq/dB axes + cutoff handle). They replace+ ~a dozen knobs and should FILL their panel via a `DockPanel` (header docked+ top, graph stretches).+ - **Selectors:** waveform = icon chips (`WaveIcon`), filter type = text chips,+ small A/B or Fil1/Fil2 = segmented `Seg` toggles. Not combo-boxes unless a list+ is long.+ - Live values in `Font.Mono`; tiny UPPERCASE section/knob labels.+- **Live follow:** call `ctx.SetInstLiveViz(Refresh)` and register knobs via+ `ctx.AddInstFader(...)` (InstKnob does this for you); `RefreshSynthLive()` (driven by+ the playhead tick) re-reads params so automation playback moves the UI. Keep a+ `readouts` list of `Action` for numeric captions / graphs and call them in `Refresh`.++Colours/tokens: never hardcode — reuse the `DeviceCardKit` brushes (`Card2`, `BorderDef`,+`Brass`, `Teal`, `Sunken`, `TextPrimary/Secondary/Tertiary`, `AccentBright`), in scope via+`using static Nota.App.DeviceCardKit;` — along with `SimpleCard`, `KnobCell`, `ChipRow`,+`Labeled`, `Glyph`, `Pct`, `NoteName`. See `nota-design`.++## 4. Presets & verification++- **Factory presets:** instruments use `Inst("<group>", N, "Name", ("paramid", v), …)`;+ audio/MIDI effects use `Fx(…)` / `Midi(…)` with **param NAMES** (not ids) in+ `FactoryPresetCatalog.cs` (values normalized 0..1 for the newer devices; bipolar+ knobs neutral at 0.5). ~6 covering the useful range.+- **Smoke test** (`tests/Nota.SmokeTest/Program.cs`): assert kind/`builtinKind`,+ name, param count, param round-trip, clone (duplicate the track), and that each+ mode renders audible + finite (RMS>0). Instruments add a track + note; effects+ do `AddBuiltinDevice(track, kind)` over an audio clip and check `DeviceName`/+ `DeviceGetParam`. Run `dotnet run --project tests/Nota.SmokeTest`.+- **Visual check** (no click automation on macOS — see `nota-ui-verify`): add a+ temporary `NOTA_DEBUG_SESSION`-guarded block at the end of+ `MainWindow.OnDataContextChanged` (a `DispatcherTimer` firing ~2.5 s). For an+ instrument add its track; for an effect add an **audio** track ++ `Engine.AddBuiltinDevice(t, kind)` (an audio track has no instrument card, so the+ effect card is first and not pushed off-screen); then `ShowDevices(t)`. Launch+ with the env var, `screencapture`, crop with `sips`, then **revert the hook and+ rebuild.** To shoot a non-default tab, briefly flip the tab's default `Content`.++Build native (`cmake --build build --target nota_engine`) and managed+(`dotnet build src/managed/Nota.App`) after each layer; the C ABI is wildcard-+exported so a new `_nota_*` function needs no export-list edit.diff --git a/.github/skills/nota-pr/SKILL.md b/.github/skills/nota-pr/SKILL.mdnew file mode 100644index 00000000..fbb43dc1--- /dev/null+++ b/.github/skills/nota-pr/SKILL.md@@ -0,0 +1,124 @@+---+name: nota-pr+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the contributor's own git identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".+user-invocable: true+---++# Opening a pull request++A Nota PR is reviewed by reading its description, so the description carries the proof: what+changed, why, and what it looks like or costs before and after. Images and benchmark charts+never go into `develop` — they live on the orphan **`pr-assets`** branch (see+`CONTRIBUTING.md` § Images for pull requests) and are embedded by raw URL.++## 1. Branch and commit++- Branch from `develop` (never `main`): `git checkout -b <type>/<slug>` — `fix/…`, `feat/…`,+ `docs/…`, `chore/…`. If the work is already on `develop` uncommitted, create the branch+ first; the working tree comes along.+- `scripts/build.sh` (or `build-linux.sh` / `build-win.ps1`) must pass — it runs the smoke test.+- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a body+ that says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no+ "Generated with" line) in commits or the PR body.+- Author and committer: whoever makes the change, from their own git config. Never set+ `user.name` / `user.email` / `--author` to someone else's identity.+- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change they+ describe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.++## 2. Decide what evidence the PR needs++| The change… | Attach |+|---|---|+| alters anything the user sees (a window, panel, device card, menu, theme, layout, custom-drawn view) | **before / after screenshots**, same size, theme and content |+| aims at or may affect performance (engine render path, DSP, threads, allocation, CPU, memory, startup) | **benchmark**: before vs after (and vs the last good build when fixing a regression), with charts + a table |+| both | both |+| neither (docs, refactor with no runtime effect, CI) | nothing — say so in the Summary |++When unsure whether a change is user-visible, run the app and look.++## 3. Screenshots (UI changes)++1. Capture **before** on the base commit and **after** on the branch, with the same window size,+ theme (default Studio Dark unless the change is theme-specific — then one pair per theme),+ interface scale and project content. Reuse the capture tooling the `nota-design` /+ `nota-docs` skills describe (headless Avalonia render or the app's own capture hook) rather+ than hand screenshots, so both shots are pixel-comparable.+2. Name them `<what>-before.png` / `<what>-after.png`; a side-by-side `<what>-both.png` is+ welcome for small changes.++## 4. Benchmarks (performance changes)++Two layers, and a performance change needs both:++- **Regression guards** — `tests/Nota.SmokeTest/RenderPoolTests.cs`, part of every smoke run+ (`scripts/build.sh`, CI on all three platforms; alone: `dotnet run --project+ tests/Nota.SmokeTest -c Release -- --perf`). Hardware-independent checks: render threads+ idle at ~0 CPU (their own thread clocks), parallel vs single-thread CPU ratios while playing+ and bouncing, bounce not slower than one thread, bit-identical output, tracks edited while+ rendering. When you touch the render path, threading or allocation, keep these green; when+ you fix a performance bug, add a guard here that fails on the old code (prove it: put the+ old behaviour back briefly and watch the check fail).+- **Benchmark numbers** for the PR description, below.++The engine benchmark is in the repo:++- `scripts/bench-engine.sh [-r runs] <out-dir> <label>=<engine-lib-dir> ...` — links+ `scripts/bench/engine-bench.cpp` against each Release `libnota_engine` and runs idle, offline+ render (bounce) and real-time-paced scenarios for audio and synth tracks, interleaving the+ builds run by run. Writes `results.csv` + `machine.txt`.+- `scripts/bench-chart.py <out-dir> <label>="Display name" ...` — medians, three charts+ (`cpu-playing`, `bounce-time`, `bounce-cpu`; SVG + 2x PNG) and `summary.md` (tables + machine).++Recipe:++1. Build each revision you compare **in Release**, each in its own checkout so nothing is shared:+ `git worktree add --detach /tmp/nota-<label> <commit>`, then configure + `ninja nota_engine` in+ its `src/native/nota.engine/build`. Revisions before the CPM switch (#212) need+ `git submodule update --init --recursive --depth 1` first. The branch itself can use the main+ `build/` dir (it must stay Release).+2. Copy each `libnota_engine.*` into its own folder (`/tmp/bench/libs/<label>/`) so later rebuilds+ don't change what you measured.+3. Run on a quiet machine, on power, ≥3 runs: `scripts/bench-engine.sh -r 3 /tmp/bench/out+ before=… after=…`. Look at the spread in `results.csv`; rerun if runs disagree a lot.+4. Chart it: `scripts/bench-chart.py /tmp/bench/out before="Before" after="This PR"`. Open the+ PNGs and check them (labels, overlap) before attaching.+5. Report honestly: put regressions in the table too and say why they're acceptable or what+ follows up. A benchmark also needs the commits measured and the machine (from `machine.txt`).++If the change needs a scenario the harness lacks, extend `engine-bench.cpp` (stick to C ABI+functions every compared build exports) and the scenario list in `bench-engine.sh`, in the same PR.++## 5. Put the assets on pr-assets++One folder per PR, named after the change or issue (`fix-pr212-review/`, `issue-223/`). Commit on+top of `pr-assets` — never force-push or rewrite it; old PRs link to its files.++```sh+git fetch origin pr-assets+git worktree add /tmp/nota-assets origin/pr-assets -B pr-assets+mkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/+git -C /tmp/nota-assets add <folder>+git -C /tmp/nota-assets commit -m "Images for <change>"+git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \+ push https://github.com/nota-daw/nota.git HEAD:pr-assets+git worktree remove /tmp/nota-assets+```++For benchmarks commit the CSV and `summary.md` next to the charts, so the numbers stay checkable.+Embed with `https://raw.githubusercontent.com/nota-daw/nota/pr-assets/<folder>/<file>.png`.++## 6. Push and open the PR++- Push over HTTPS (SSH push to nota-daw/nota is denied):+ `git -c credential.helper= -c credential.helper='!gh auth git-credential' push -u https://github.com/nota-daw/nota.git <branch>`,+ then `git fetch origin <branch> && git branch -u origin/<branch>`.+- `gh pr create --repo nota-daw/nota --base develop --head <branch> --title "<commit-style title>" --body-file <file>`.+- Body: follow `.github/PULL_REQUEST_TEMPLATE.md` (Summary, Spec, Checklist — tick only what was+ actually done; leave platforms you didn't build unticked). Add sections as needed:+ - **Screenshots** — a table, before | after:+ `| Before | After |` / `|---|---|` / `|  |  |`+ - **Benchmark** — the charts, the `summary.md` tables, the commits measured, the machine, and+ a sentence on how to reproduce (`scripts/bench-engine.sh …`).+ - **Testing** — what was run and what was not.+ - Link the issue (`Fixes #N` / `Refs #N`) and, for review follow-ups, the PR being followed up.+- Base is `develop`. Don't enable auto-merge; don't merge.diff --git a/.github/skills/nota-shortcuts/SKILL.md b/.github/skills/nota-shortcuts/SKILL.mdnew file mode 100644index 00000000..416d537b--- /dev/null+++ b/.github/skills/nota-shortcuts/SKILL.md@@ -0,0 +1,66 @@+---+name: nota-shortcuts+description: Keep the Preferences → Shortcuts screen in sync with the app's real keyboard/mouse bindings. Run this WHENEVER you add, remove, or change a keyboard shortcut or mouse gesture (transport keys, editing commands, piano-roll keys, the computer-keyboard note map, device drag, etc.) — the Shortcuts pane is a hand-maintained list and silently drifts from the handlers otherwise. Handles: finding every place bindings are defined, updating the on-screen list, and visually verifying it.+user-invocable: true+---++# Keeping the Shortcuts screen honest++Nota shows its keyboard/mouse shortcuts in **Preferences → Shortcuts**. That list is+**hand-written**, not generated from the handlers — so every time the input handling+changes, the screen must be updated by hand or it lies to the user. This skill is the+checklist for doing that.++**Trigger:** you touched anything that changes what a key or mouse gesture does — a new+hotkey, a re-mapped key, a removed command, a changed computer-keyboard note layout, a new+drag gesture. If your change added/removed/moved a binding, you are not done until the+Shortcuts pane matches.++## 1. The on-screen list (what to edit)++`src/managed/Nota.App/PreferencesWindow.cs` → the static **`ShortcutGroups`** array (feeds+`ShortcutsPane`). It's grouped: `TRANSPORT`, `ARRANGEMENT & EDITING`, `PIANO ROLL`,+`PLAY NOTES (COMPUTER KEYBOARD)`, `MOUSE`. Each row is `(Key, Action)`; the `Key` string is+split on spaces and each token becomes its own mono key-cap (`/` and `·` stay plain+separators) — as long as every token is a key: no lower-case letters, or one of `Space`+`Return` `Delete` `Tab` `Esc` (`IsKeyToken`). Anything else (`Drag note edge`, `Face+buttons`) is a gesture and shows as plain text. The `Action` is a short sentence. Use `⌘` for Meta/Ctrl, `⇧`+for Shift, `⌥` for Alt, and the arrow glyphs `← → ↑ ↓`. Keep actions imperative and terse+(design language: sentence case, `·`/` / ` as separators).++## 2. The source of truth (where bindings actually live)++Read these and reconcile the list against them — do **not** trust the existing pane text:++| Bindings | File |+|---|---|+| Transport (Space/Return), global editing (A, R, M, ⌘M, ⌘G/⌘⇧G, ⌘C/X/V, Delete, Tab, Esc) and the **computer-keyboard note map** (`KeyToPitch`) | `src/managed/Nota.App/MainWindow.Input.cs` |+| Piano-roll note editing (arrows, ⇧ octave, ⌘A/⌘D, ⌘C/X/V, Delete, Esc) | `src/managed/Nota.App/PianoRollView.cs` (its `OnKeyDown`) |+| Arrangement lane / clip gestures (double-click, drag) | `src/managed/Nota.App/ArrangementView*.cs` |+| Device reorder drag | `src/managed/Nota.App/DeviceChainView.cs`, `DeviceCards/…` |++`KeyToPitch` is the note layout: bare letters play notes, and `A` is **deliberately not** a+note (it toggles automation mode) — so the "Play notes" rows must never list `A`. When that+map changes, update the `PLAY NOTES` group (white vs. black keys, and the starting octave).++## 3. Procedure++1. List, from your own diff, every binding you added/changed/removed.+2. Open the source-of-truth file(s) above and confirm the *current* behaviour of each key in+ the affected group — including ones you didn't touch, since the list may already be stale.+3. Edit `ShortcutGroups` so every row matches. Add a row for a new binding, delete a row for a+ removed one, fix the key-cap or wording for a changed one. Put it in the right group.+4. Build: `dotnet build src/managed/Nota.App -c Debug`.+5. Visually verify (see [nota-ui-verify] memory): the pane can't be reached by a click in a+ headless run, so temporarily open it via an env-guarded hook in+ `MainWindow.OnDataContextChanged` (`new PreferencesWindow(new SettingsViewModel(settings),+ _vm).Show(this)`), and select the Shortcuts section (index 8 — count the sidebar entries, it moves as pages are added) — e.g. a temporary env read+ in front of the constructor's `Select(0)`. Screenshot with `screencapture -x -o -l<winid>`+ (get the id from the `winlist` swift helper), check the rows read correctly, then **revert+ the temp hooks** and rebuild.++## 4. Don't forget++- If the change is user-visible, it also wants a `CHANGELOG.md` entry under `## [Unreleased]`.+- Keep the pane concise — it's a reference, not a manual. Group related keys onto one cap+ (`⌘C ⌘X ⌘V`) rather than three rows when the action is one idea.diff --git a/.github/skills/release/SKILL.md b/.github/skills/release/SKILL.mdnew file mode 100644index 00000000..8c85be7e--- /dev/null+++ b/.github/skills/release/SKILL.md@@ -0,0 +1,289 @@+---+name: release+description: Cut a Nota release in three phases. `prepare` (on a release/X.Y.Z branch from develop) promotes CHANGELOG.md [Unreleased] to a dated version, writes the curated EN + RU release notes in release-notes/ (the one source for the GitHub release and the news channels), bumps the app and engine versions, makes the release image and the PR texts. `tag` (on main, after the user merged the release PR into develop and the develop → main PR) creates the vX.Y.Z tag. `verify` (after the user pushed the tag) waits for the build and checks the GitHub draft against the curated notes. Run this when the user asks to release, ship, cut a version, tag a release or check a release build.+user-invocable: true+---++# Cutting a Nota release++Two files describe a release, for two readers:++- **`CHANGELOG.md`** is the raw working log. Entries land under `## [Unreleased]` as work+ merges ("what we did, we write"), so it can repeat itself or hold changes that a later+ entry undid. At release time it is only promoted to `## [X.Y.Z] — date` and is never+ rewritten. The CI guard requires the section, and What's New falls back to it for a+ version without curated notes.+- **`release-notes/X.Y.Z.en.md`** and **`release-notes/X.Y.Z.ru.md`** are the curated+ text: summarised, deduplicated, checked against the code. **Everything published comes+ from them**, and the app bundles the EN file for its What's New window, so the notes must+ be committed on the release branch before the tag is built. They hold a summary, the+ full Added / Changed / Fixed list with a commit link on each item, and the contributors+ (format in P4). `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:++ | target | where it goes | full list |+ |-----------|-------------------------------------------------|-----------|+ | `github` | GitHub release body (the workflow uses this) | yes |+ | `post-en` | English news channels | no |+ | `post-ru` | Russian news channels | no |++The release runs through the branches like this. **The user does every commit, push and PR+by hand.** This skill never commits, pushes or opens a PR (see the user-commits rule).++```+release/X.Y.Z ── /release prepare ── user commits, pushes, opens PR → develop (squash)+develop ── CI green, user merges ── user opens PR develop → main (merge commit)+main ── CI green, user merges ── /release tag ── user pushes the tag+CI ── release.yml builds 6 files + draft release ── /release verify ── user publishes+```++`develop` and `main` are protected (rulesets): changes land only through a pull request+with the `macOS`, `Windows` and `Linux` CI checks green; `develop` takes squash merges,+`main` takes merge commits only, so `develop` → `main` never rewrites history. Release+tags `v*` can be created only by maintainers.++**Argument** (`/release <phase> [bump]`): the phase is `prepare` (default), `tag` or+`verify`. For `prepare` the bump is `minor` or `patch` (see step P2).++---++## Phase 1 — `prepare` (on a `release/X.Y.Z` branch from `develop`)++### P1. Preflight. Stop if any check fails++1. On `develop`: `git rev-parse --abbrev-ref HEAD`.+2. The tree is clean (`git status --porcelain` is empty). Otherwise ask the user to commit+ or stash first, so the release changes stay separate.+3. Up to date: `git fetch origin`, then `git rev-list --left-right --count origin/develop...HEAD`+ must show `0` behind and `0` ahead (unpushed commits on `develop` can't reach it any+ more except through a pull request).+4. `## [Unreleased]` has real entries.+5. Once the version is chosen (P2), create the branch: `git switch -c release/X.Y.Z`. This is+ the only branch operation the skill does itself; every later step edits files on it.++### P2. Choose the bump++The app and the engine always move together, by the same kind of bump:++| bump | when | app | engine |+|---------|----------------------------------------------|-----------------|-----------------|+| `minor` | a major feature (new device, view, workflow) | 0.51.2 → 0.52.1 | 0.30.3 → 0.31.1 |+| `patch` | fixes, polish, small additions | 0.51.2 → 0.51.3 | 0.30.3 → 0.30.4 |++A component that resets starts at **1, never 0**. If the user gave no bump, propose one+from the `[Unreleased]` content and confirm it with them. Preview it with+`scripts/release-bump.sh <bump> --dry-run`. It refuses a version whose tag already exists.++### P3. Promote CHANGELOG.md++Rename `## [Unreleased]` to `## [X.Y.Z] — YYYY-MM-DD` (date from `date +%F`). Add a fresh+empty `## [Unreleased]` above it. **Don't touch the entries**: no Highlights and no+rewording. The changelog stays the honest log. Keep the preamble and older sections as they+are.++### P4. Write the curated notes, EN and RU++This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and+`release-notes/X.Y.Z.ru.md`. Each has four parts, in this order:++1. **Summary**: the lede and the numbered headline features, for someone who reads only+ this part.+2. **Full list**: every user-facing change of the release, grouped as Added / Changed /+ Fixed / Removed.+3. **Commit links**: each full-list item ends with a link to its commit.+4. **Contributors**: everyone who has a commit in the release, linked to their GitHub+ profile.++Steps:++1. **Gather.**+ - The previous tag is the highest version tag:+ `git tag --list 'v*' --sort=-v:refname | head -1`. Don't use `git describe` on+ `develop`: release tags sit on `main`'s merge commits, which `develop` doesn't+ contain, so `describe` returns a tag several releases old.+ - Read the whole `[X.Y.Z]` section you just promoted.+ - `scripts/release-credits.sh <prev-tag> origin/develop commits` lists every commit of+ the release (short sha, sha, subject). It's the checklist for the full list.+ - `scripts/release-credits.sh <prev-tag> origin/develop contributors` prints the+ ready Contributors line. It asks GitHub for every commit's authors and co-authors+ (needs `gh` signed in) and leaves out bots and AI co-authors.+2. **Reconcile.** Merge entries that describe the same thing. Where entries conflict (a+ shortcut reassigned twice, a feature added and then reworked), **the code decides**:+ read the handler, the default or the UI and describe what ships. Drop anything that+ was added and then removed within the same release. Then build the full list from the+ commits:+ - Each user-facing change is one item, linked to the commit(s) that brought it. A fix+ and its follow-up make one item with both links.+ - Leave out internal or mechanical commits (refactors, CI, tests, release chores)+ unless a user can feel them. Their authors are still contributors.+ - Walk the `commits` output once more at the end: every user-facing commit must be in+ an item.+3. **Write.** Each language natively, not as a translation. Format: bold titles and `•`+ bullets, no `#` headings, so the text pastes into Telegram as is. The two comment+ markers say where the full list and the contributors start, whatever the language.+ They are invisible on GitHub, and `release-notes.sh` strips them.++ ```+ <!-- SPDX-License-Identifier: AGPL-3.0-only -->+ One or two sentences on what defines this release.++ **1. Biggest user-facing win**+ A short paragraph: what it is and why a musician cares. Not every changelog detail.++ **2. Next feature**+ …++ <!-- changes -->+ **Added**+ • A new capability, one line ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))++ **Changed**+ • A behaviour users must know: a moved shortcut, a changed default ([e4f5a6b](…), [c7d8e9f](…))++ **Fixed**+ • What no longer goes wrong, said from the user's side ([0a1b2c3](…))++ **Removed**+ • …++ <!-- contributors -->+ **Contributors**+ [@login](https://github.com/login), [@other](https://github.com/other)+ ```++ Rules for the format:+ - Rank the summary's sections by importance. A patch release can have just the lede+ before the full list.+ - Groups go in the order Added, Changed, Fixed, Removed; leave out empty groups.+ Inside a group, put the most noticeable changes first.+ - A commit link's text is the 7-character short sha and its URL takes the full sha+ from the `commits` output. These are `develop`'s squash commits. They become part of+ `main` through the develop → main merge, so the links keep working after the release.+ - New notes have no **Also** block: the full list replaces it, so nothing is listed+ twice.+ - RU titles: **Добавлено**, **Изменено**, **Исправлено**, **Удалено**, **Участники**.+ The EN and RU files have the same groups, the items in the same order with the same+ links, and the same contributors.+ - Contributors: paste the `contributors` line. Resolve every `warn:` line it printed+ on stderr:+ - An author with no GitHub login can be a second address of someone already listed+ (the user's work email, for example). Drop that name.+ - Otherwise, find the login and link it, or keep the plain name.+ - Don't add or remove people by hand otherwise.+ - Leave out the title and the download link, because `release-notes.sh` adds them per+ target. Use the user's product language: "track", "device card", "piano roll", not+ class names.+4. Show the user the three renders and iterate until they approve. The rest of the+ release depends on this text.+ - `scripts/release-notes.sh X.Y.Z github` has all four parts.+ - `post-en` and `post-ru` have the summary and the contributors but no full list. A+ Telegram message holds 4096 characters, and the posts end with the link to the+ GitHub release, which has the full list.++ The app bundles the EN file. What's New shows the summary, then "All changes" with the+ groups, then the contributors, and the links in it are clickable. The smoke test checks+ that every full-list item of a shipped notes file ends in a commit link.++### P5. Bump the versions++`scripts/release-bump.sh <bump>` writes `VERSION` and `src/native/nota.engine/VERSION`+(both without a trailing newline, read with `.Trim()` / CMake). The CI checks the tag against+`VERSION`, so the two must agree.++### P6. Feature list and docs++- Run `nota-features` in `audit` mode: fold this version's entries into `FEATURES.md` and+ set its header to `X.Y.Z`. That change goes into the release commit.+- Run `nota-docs` in `audit` mode over the same entries. Its changes are committed in+ `../nota-docs`. Missing docs don't block the release; list them in the report.++### P7. Release image++Build a 16:9 poster in `../media/news/X.Y.Z-src/` (outside the repo). Start from the last+release's `poster.html` (`ls -d ../media/news/*-src | sort -V | tail -1`) and copy its+fonts.++- Header: the logo, `Nota X.Y.Z` (version in brass), a one-line subtitle taken from the+ notes' lede, and a mono tag row with the 2–4 headline features.+- Two or three cards with real screenshots of the headline features. Shoot them from the+ app (see the UI-verify recipe, with an isolated `NOTA_DATA_DIR`) or reuse fresh shots+ from `../nota-docs`. Use Ember Graphite colours (`nota-design`).+- Render it at 2×:++ ```bash+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \+ --hide-scrollbars --window-size=1280,720 --force-device-scale-factor=2 \+ --screenshot="$PWD/../media/news/X.Y.Z.png" "file://$PWD/../media/news/X.Y.Z-src/poster.html"+ ```++- Look at the PNG (Read it) and check for overlaps, clipped text or empty space before+ showing it to the user. Also save the rendered posts next to it as+ `../media/news/X.Y.Z.en.md` and `X.Y.Z.ru.md` (the output of `post-en` / `post-ru`).++### P8. Hand over to the user++Don't commit. Give the user:++- the version change (`app a → b`, `engine c → d`) and the list of changed files:+ `CHANGELOG.md`, `VERSION`, `src/native/nota.engine/VERSION`, `FEATURES.md`,+ `release-notes/X.Y.Z.{en,ru}.md`,+- the commit message `(chore) Release X.Y.Z` and the push command+ `git push -u origin release/X.Y.Z`,+- the **PR into develop**: title `(chore) Release X.Y.Z` (it becomes the squash commit+ message), body = a short list of the changed files,+- the **PR text** for develop → main, opened after the first one is merged. Title+ `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github` (summary,+ full list and contributors), so the reviewer reads exactly what will be published. Merge it with **Create a merge commit**+ (the only method `main` allows),+- the image path and any docs gaps,+- the next step: merge both PRs once CI is green, then run `/release tag`.++---++## Phase 2 — `tag` (on `main`, after the merge)++1. If the user is still on develop, tell them to run `git switch main && git pull --ff-only`.+ Don't switch branches on their tree yourself if it has changes.+2. Run `scripts/release-tag.sh`. It repeats the CI guard locally (on main, clean, equal to+ `origin/main`, the tag is free locally and on origin, the `## [X.Y.Z]` section and both+ notes files exist) and then creates the annotated tag `vX.Y.Z`. **It doesn't push.**+3. Give the user the push command and the Actions link+ (`https://github.com/nota-daw/nota/actions/workflows/release.yml`):++ ```bash+ git push origin vX.Y.Z+ ```++If the script fails, report its message as is. Common causes: the PR isn't merged yet, or+local main is behind. After the tag, `develop` needs no sync: the merge commit on `main`+already has `develop` as a parent.++---++## Phase 3 — `verify` (after the tag push)++1. Find the run: `gh run list --repo nota-daw/nota --workflow release.yml --limit 3`. Wait+ for it with `gh run watch <id> --repo nota-daw/nota --exit-status` (run it in the+ background, because a build takes about 20–30 min). Don't poll in a loop.+2. If a job failed, show its log tail: `gh run view <id> --log-failed`.+3. When it's green, run `scripts/release-verify.sh X.Y.Z`. It checks that the draft body+ equals `release-notes.sh X.Y.Z github` word for word and that all six files are+ attached (dmg arm64/x86_64, exe x64/arm64, AppImage x86_64/aarch64).+4. Report the result. If the body differs (someone edited the draft, or the notes changed+ after the tag), show the diff and fix it at the source. Don't edit the draft by hand to+ make it match. The user reviews the draft and publishes it themselves, then posts+ `../media/news/X.Y.Z.{en,ru}.md` with `X.Y.Z.png` to the channels.++---++## Don't++- Don't commit, push, open PRs, push tags or publish the release. All of these are the+ user's steps.+- Don't reword or summarise inside `CHANGELOG.md`. Curated text goes only to+ `release-notes/`.+- Don't write published text anywhere except `release-notes/`. GitHub and the channels+ must come from the same files.+- Don't type the contributors or commit shas from memory. Take them from+ `scripts/release-credits.sh`, and resolve its warnings instead of ignoring them.+- Don't bump only one of app or engine, and don't reset a component to 0.+- Don't hard-code the date or reuse an existing version or tag.diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 5a780edc..a47ba959 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -26,6 +26,14 @@ concurrency:cancel-in-progress: truejobs:+ agent-skills:+ name: Agent skills in sync+ runs-on: ubuntu-24.04+ steps:+ - uses: actions/checkout@v5+ - name: Check the skill copies for other agents+ run: bash scripts/sync-agent-skills.sh --check+macos:name: macOSruns-on: macos-26diff --git a/AGENTS.md b/AGENTS.mdindex 03052283..dca7f003 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -17,8 +17,10 @@ restrictions).`specs/000-example/` shows a completed run. Trivial work — typos, small fixes, docedits — skips the spec and goes straight to the change.- Bug reports go through the speckit `bug-assess` → `bug-fix` → `bug-test` commands.-- The `nota-*` skills in `.claude/skills/` and `.agents/skills/` (design, docs,- features, instrument, shortcuts, release, pr) encode project-specific workflows — prefer- them over improvising.+- The `nota-*` skills (design, docs, features, instrument, shortcuts, release, pr)+ encode project-specific workflows — prefer them over improvising. Every agent finds+ them in its own skill directory (`.agents/skills/`, `.github/skills/`,+ `.cursor/skills/`, `.gemini/skills/`); those are copies. The source is+ `.claude/skills/`: edit a skill there, then run `scripts/sync-agent-skills.sh`.- Before any pull request: `scripts/build.sh` (or the Linux/Windows siblings) must pass;it runs the smoke test that drives the engine end-to-end.diff --git a/CLAUDE.md b/CLAUDE.mdindex 17292be8..cf87145e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,5 +20,7 @@ restrictions).- Bug reports go through `/speckit-bug-assess` → `/speckit-bug-fix` → `/speckit-bug-test`.- The `nota-*` skills in `.claude/skills/` (design, docs, features, instrument,shortcuts, release, pr) encode project-specific workflows — prefer them over improvising.+ `.claude/skills/` is their source; after editing one, run `scripts/sync-agent-skills.sh`+ to refresh the copies other agents read (CI checks they match).- Before any pull request: `scripts/build.sh` (or the Linux/Windows siblings) must pass;it runs the smoke test that drives the engine end-to-end.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a8a24ffc..118810b8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -84,7 +84,13 @@ Two things govern agents working here: the project constitution at`.specify/memory/constitution.md` (principles distilled from this document and[`ARCHITECTURE.md`](ARCHITECTURE.md)), and this document — which remains canonical forhumans. You don't need an AI agent to contribute: writing `spec.md` and `plan.md` by-hand from the templates in `.specify/templates/` is equally welcome. Typos, small fixes+hand from the templates in `.specify/templates/` is equally welcome.++The project skills (`nota-design`, `nota-docs`, `nota-features`, `nota-instrument`,+`nota-pr`, `nota-shortcuts`, `release`) are written once in `.claude/skills/` and copied+into the directories the other agents read (`.agents/skills/`, `.github/skills/`,+`.cursor/skills/`, `.gemini/skills/`). Edit the source, then run+`scripts/sync-agent-skills.sh`; CI fails if a copy is out of date. Typos, small fixesand doc edits don't need a spec — just open the pull request.## Buildingdiff --git a/scripts/sync-agent-skills.sh b/scripts/sync-agent-skills.shnew file mode 100755index 00000000..069e9965--- /dev/null+++ b/scripts/sync-agent-skills.sh@@ -0,0 +1,72 @@+#!/usr/bin/env bash+# SPDX-License-Identifier: AGPL-3.0-only+#+# Copies the project skills (nota-* and release) from .claude/skills/ — the one source —+# into the skill directories the other agents read: .agents/skills (Codex and other+# agents that use the shared location), .github/skills (Copilot), .cursor/skills (Cursor)+# and .gemini/skills (Gemini CLI). Edit the skills under .claude/skills/ only, then run+# this script. Spec Kit's speckit-* skills are managed by Spec Kit and are left alone.+#+# Usage: scripts/sync-agent-skills.sh # write the copies+# scripts/sync-agent-skills.sh --check # fail if any copy is missing or stale (CI)++set -euo pipefail+cd "$(dirname "$0")/.."++SOURCE=.claude/skills+TARGETS=(.agents/skills .github/skills .cursor/skills .gemini/skills)++check=0+case "${1:-}" in+ --check) check=1 ;;+ "") ;;+ *) echo "usage: $0 [--check]" >&2; exit 2 ;;+esac++# The project's own skills: everything under .claude/skills except Spec Kit's.+skills=()+for dir in "$SOURCE"/*/; do+ name=$(basename "$dir")+ case "$name" in speckit-*) continue ;; esac+ skills+=("$name")+done++is_project_skill() {+ local s+ for s in "${skills[@]}"; do [ "$s" = "$1" ] && return 0; done+ return 1+}++stale=0+for target in "${TARGETS[@]}"; do+ for name in "${skills[@]}"; do+ if [ "$check" = 1 ]; then+ if ! diff -r "$SOURCE/$name" "$target/$name" >/dev/null 2>&1; then+ echo "stale: $target/$name"+ stale=1+ fi+ else+ rm -rf "${target:?}/$name"+ mkdir -p "$target"+ cp -R "$SOURCE/$name" "$target/$name"+ fi+ done+ # A project skill removed or renamed in the source leaves no copy behind.+ for dir in "$target"/nota-*/ "$target"/release/; do+ [ -d "$dir" ] || continue+ name=$(basename "$dir")+ is_project_skill "$name" && continue+ if [ "$check" = 1 ]; then+ echo "orphaned: $target/$name"+ stale=1+ else+ rm -rf "${target:?}/$name"+ fi+ done+done++if [ "$check" = 1 ] && [ "$stale" = 1 ]; then+ echo "error: agent skill copies are out of date — run scripts/sync-agent-skills.sh" >&2+ exit 1+fi+[ "$check" = 1 ] || echo "synced ${#skills[@]} skills into ${TARGETS[*]}"