@@ -2,8 +2,8 @@
 name: check-changes
 description: >
   Verify that CHANGES.md (Development section) reflects every commit since the
-  last release. Flag missing entries, stale entries, or commits that have no
-  corresponding changelog bullet.
+  last release. Flag missing entries, stale entries, over-long entries, or
+  commits that have no corresponding changelog bullet.
 ---
 
 # check-changes
@@ -38,13 +38,22 @@ release.
    verbatim -- it only needs to describe the same change at a short summary
    level.
 
-5. **Report findings.**
+5. **Check each bullet against the length rule.**
+   Per the "Changelog Entries" section of CONTRIBUTING.md, a bullet is at most
+   **25 words**, counted as whitespace-separated tokens with a code span
+   counting as one word. Count every bullet under `## Development` and list the
+   ones that exceed it, with their count. Do not measure released `## Version`
+   sections -- a section is frozen once cut and is never rewritten.
+
+6. **Report findings.**
    - List commits with NO changelog entry (missing entries -- these must be
      added).
    - List changelog bullets that appear to describe nothing in the commit
      history (stale or speculative entries -- flag for author review).
+   - List bullets over the 25-word limit, each with its count, and propose a
+     shorter wording.
    - If everything matches, report "CHANGES.md is current."
 
-6. **Do not edit CHANGES.md automatically.**
+7. **Do not edit CHANGES.md automatically.**
    Propose the missing bullets in your report and let the developer apply them.
    The developer owns the changelog wording.
@@ -198,6 +198,22 @@ jobs:
       - name: Test workspace
         run: cargo test --workspace
 
+      # `cargo test` WRITES the generated artifacts (ts-rs bindings, the mcp.yml
+      # JSON Schema) rather than asserting them, so a commit that changes a Rust
+      # type but forgets to commit the regenerated file is green here and only
+      # wrong afterwards. For the schema that is worse than for the bindings: it
+      # ships as a release asset that editors pin, so a stale one makes every
+      # user's editor flag correct files until someone notices.
+      - name: Fail on stale generated artifacts
+        run: |
+          git diff --exit-code -- \
+            schemas/ \
+            apps/desktop/src/renderer/services/bridge/generated/ \
+          || {
+            echo "::error::A generated artifact is out of date. Run 'cargo test' and commit the result."
+            exit 1
+          }
+
   e2e:
     name: End-to-end (CLI against the fixture)
     runs-on: ubuntu-latest
 
@@ -67,9 +67,11 @@ jobs:
         run: node scripts/check-version.mjs
 
   # ---------------------------------------------------------------------------
-  # Build: one matrix leg per (os, target). macOS covers both arches via cross
-  # targets on the arm64 runner. Linux arm64 and Windows arm64 can be added as
-  # further legs once cross-toolchains / arm runners are wired (see NOTE below).
+  # Build: one matrix leg per (os, target), covering x64 and arm64 on all three
+  # platforms. macOS and Windows reach their second arch by cross-compiling on
+  # the x64/arm64 runner they already use; Linux gets a native arm64 runner,
+  # because Tauri links the system WebKitGTK stack and cross-compiling it would
+  # mean carrying an arm64 sysroot.
   # ---------------------------------------------------------------------------
   build:
     name: Build ${{ matrix.target }}
@@ -104,15 +106,22 @@ jobs:
           - os: ubuntu-22.04
             target: x86_64-unknown-linux-gnu
             args: ""
+          # Linux arm64, built natively on the arm64 runner (free for public
+          # repositories). Same 22.04 image as the x64 leg, so both AppImages
+          # share a glibc floor.
+          - os: ubuntu-22.04-arm
+            target: aarch64-unknown-linux-gnu
+            args: ""
           # Windows x64
           - os: windows-latest
             target: x86_64-pc-windows-msvc
             args: ""
-          # NOTE: per-arch left as documented best-effort:
-          #   - Linux arm64 (aarch64-unknown-linux-gnu) needs a cross toolchain
-          #     or an arm64 runner and the arm64 webkit dev packages.
-          #   - Windows arm64 (aarch64-pc-windows-msvc) needs the arm64 MSVC
-          #     target; MakeAppx would also need ProcessorArchitecture="arm64".
+          # Windows arm64 (cross-compiled on the x64 runner, as macOS Intel is).
+          # Only the Rust target changes; Node, pnpm and the frontend build stay
+          # on the x64 image.
+          - os: windows-latest
+            target: aarch64-pc-windows-msvc
+            args: "--target aarch64-pc-windows-msvc"
 
     steps:
       - name: Checkout repository
@@ -135,9 +144,13 @@ jobs:
           DEBIAN_FRONTEND: noninteractive
         run: |
           sudo apt-get update -o DPkg::Lock::Timeout=300
-          # patchelf is dropped: the AppImage bundler needs it, but it already
-          # ships in the ubuntu runner image, so installing it is pure download.
+          # patchelf is installed explicitly: the AppImage bundler needs it,
+          # and while the x64 runner image ships it, the arm64 images carry a
+          # documented subset. A missing patchelf fails the arm64 leg, and
+          # `publish` needs every leg -- so the whole release is blocked to save
+          # one small download.
           sudo apt-get install -y -o DPkg::Lock::Timeout=300 \
+            patchelf \
             libwebkit2gtk-4.1-dev \
             libappindicator3-dev \
             librsvg2-dev
@@ -249,37 +262,16 @@ jobs:
           # with the CHANGES.md-derived notes. Per-arch selection via --target.
           args: ${{ matrix.args }}
 
-      # -----------------------------------------------------------------------
-      # Standalone CLI (skillkeeper): build and archive it for this target so it
-      # can be installed with the one-line install script (scripts/install.*),
-      # independent of the desktop bundle. The archive holds just the binary at
-      # its root and is named by target triple, so the script builds the
-      # download URL straight from the detected platform.
-      # -----------------------------------------------------------------------
-      - name: Build the CLI
-        shell: bash
-        run: cargo build --release -p skillkeeper-cli --target ${{ matrix.target }}
-
-      - name: Archive the CLI (tar.gz)
-        if: matrix.os != 'windows-latest'
-        shell: bash
-        run: |
-          mkdir -p dist-cli
-          tar -czf "dist-cli/skillkeeper-cli-${{ matrix.target }}.tar.gz" \
-            -C "target/${{ matrix.target }}/release" skillkeeper
-
-      - name: Archive the CLI (zip)
-        if: matrix.os == 'windows-latest'
-        shell: pwsh
-        run: |
-          New-Item -ItemType Directory -Force -Path dist-cli | Out-Null
-          Compress-Archive -Path "target/${{ matrix.target }}/release/skillkeeper.exe" -DestinationPath "dist-cli/skillkeeper-cli-${{ matrix.target }}.zip" -Force
-
       # -----------------------------------------------------------------------
       # Windows MSIX (MakeAppx): package the built exe + tile assets into an
       # MSIX using the appx identity dev.lorem.SkillKeeper / CN=Lorem Dev.
       # Best-effort: authored manifest + MakeAppx pack; unsigned (Store signs
       # on ingest). Does not fail the build if MakeAppx/exe are unavailable.
+      #
+      # Runs BEFORE the CLI build, and must stay there: the CLI crate's binary
+      # is also named skillkeeper.exe and lands in target/<triple>/release, the
+      # very path `tauri build --target` wrote the desktop app to. Build the CLI
+      # first and the MSIX would ship the CLI instead of the app.
       # -----------------------------------------------------------------------
       - name: Package Windows MSIX (MakeAppx)
         if: matrix.os == 'windows-latest'
@@ -303,19 +295,29 @@ jobs:
           }
           Write-Host "MSIX version: $msixVersion"
 
-          # Locate the built executable (target name = crate name skillkeeper).
-          $exe = Get-ChildItem -Path "target" -Recurse -Filter "skillkeeper.exe" |
-            Where-Object { $_.FullName -match "release" -and $_.FullName -notmatch "deps" } |
-            Select-Object -First 1
-          if (-not $exe) {
-            Write-Warning "skillkeeper.exe not found; skipping MSIX packaging."
+          # Both Windows legs package an MSIX, so the architecture has to reach
+          # the manifest AND the file name -- the publish job refuses two assets
+          # sharing a basename, and an arm64 package declaring x64 would install
+          # on neither.
+          $arch = if ("${{ matrix.target }}".StartsWith("aarch64")) { "arm64" } else { "x64" }
+          Write-Host "MSIX architecture: $arch"
+
+          # The desktop app crate and the CLI crate BOTH produce a binary named
+          # skillkeeper.exe, so a recursive search would be a coin toss between
+          # them. Take the exact path this leg's `tauri build` wrote to:
+          # target/<triple>/release when --target was passed, target/release
+          # otherwise.
+          $releaseDir = if ("${{ matrix.args }}" -match "--target") { "target/${{ matrix.target }}/release" } else { "target/release" }
+          $exePath = Join-Path $releaseDir "skillkeeper.exe"
+          if (-not (Test-Path $exePath)) {
+            Write-Warning "skillkeeper.exe not found at $exePath; skipping MSIX packaging."
             exit 0
           }
 
           $stage = Join-Path $env:RUNNER_TEMP "msix"
           $assets = Join-Path $stage "Assets"
           New-Item -ItemType Directory -Force -Path $assets | Out-Null
-          Copy-Item $exe.FullName (Join-Path $stage "skillkeeper.exe") -Force
+          Copy-Item $exePath (Join-Path $stage "skillkeeper.exe") -Force
 
           # Tile assets from the Tauri icons dir (Square* + StoreLogo).
           $iconDir = "apps/desktop/src-tauri/icons"
@@ -342,7 +344,7 @@ jobs:
             '  <Identity Name="dev.lorem.SkillKeeper"',
             '            Publisher="CN=Lorem Dev"',
             ('            Version="' + $msixVersion + '"'),
-            '            ProcessorArchitecture="x64" />',
+            ('            ProcessorArchitecture="' + $arch + '" />'),
             '  <Properties>',
             '    <DisplayName>SkillKeeper</DisplayName>',
             '    <PublisherDisplayName>Lorem Dev</PublisherDisplayName>',
@@ -378,7 +380,9 @@ jobs:
           ) -join "`r`n"
           Set-Content -Path (Join-Path $stage "AppxManifest.xml") -Value $manifest -Encoding UTF8
 
-          # Locate MakeAppx.exe from the installed Windows SDK.
+          # Locate MakeAppx.exe from the installed Windows SDK. The x64 filter
+          # picks the HOST tool, which stays x64 on both legs -- the package's
+          # own architecture is the manifest's ProcessorArchitecture, above.
           $makeappx = Get-ChildItem -Path "${env:ProgramFiles(x86)}\Windows Kits\10\bin" -Recurse -Filter "makeappx.exe" -ErrorAction SilentlyContinue |
             Where-Object { $_.FullName -match "x64" } |
             Sort-Object FullName -Descending | Select-Object -First 1
@@ -389,7 +393,7 @@ jobs:
 
           $outDir = "apps/desktop/dist-msix"
           New-Item -ItemType Directory -Force -Path $outDir | Out-Null
-          $msix = Join-Path $outDir "SkillKeeper-$msixVersion.msix"
+          $msix = Join-Path $outDir "SkillKeeper-$msixVersion-$arch.msix"
           & $makeappx.FullName pack /d $stage /p $msix /o
           # Native tools do not trip $ErrorActionPreference; check the exit code
           # explicitly so a failed pack is a real (visible) step failure instead
@@ -401,6 +405,32 @@ jobs:
           }
           Write-Host "Built MSIX: $msix"
 
+      # -----------------------------------------------------------------------
+      # Standalone CLI (skillkeeper): build and archive it for this target so it
+      # can be installed with the one-line install script (scripts/install.*),
+      # independent of the desktop bundle. The archive holds just the binary at
+      # its root and is named by target triple, so the script builds the
+      # download URL straight from the detected platform.
+      # -----------------------------------------------------------------------
+      - name: Build the CLI
+        shell: bash
+        run: cargo build --release -p skillkeeper-cli --target ${{ matrix.target }}
+
+      - name: Archive the CLI (tar.gz)
+        if: matrix.os != 'windows-latest'
+        shell: bash
+        run: |
+          mkdir -p dist-cli
+          tar -czf "dist-cli/skillkeeper-cli-${{ matrix.target }}.tar.gz" \
+            -C "target/${{ matrix.target }}/release" skillkeeper
+
+      - name: Archive the CLI (zip)
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path dist-cli | Out-Null
+          Compress-Archive -Path "target/${{ matrix.target }}/release/skillkeeper.exe" -DestinationPath "dist-cli/skillkeeper-cli-${{ matrix.target }}.zip" -Force
+
       # -----------------------------------------------------------------------
       # Upload per-target bundles + the MSIX. Covers both the default target
       # dir (linux/windows) and the cross-target dir (macOS --target).
@@ -481,6 +511,16 @@ jobs:
           echo "Staged $(find dist -type f | wc -l) files:"
           ls -1 dist
 
+      # The mcp.yml JSON Schema is generated from the Rust types by `cargo test`
+      # and committed, so it ships straight from the checkout -- no build leg
+      # produces it. It must be attached to EVERY release: the docs tell editors
+      # to read it from `releases/latest/download/mcp.schema.json`, and that URL
+      # resolves against whichever release is newest.
+      - name: Stage the mcp.yml JSON Schema
+        run: |
+          test -f schemas/mcp.schema.json
+          cp schemas/mcp.schema.json dist/mcp.schema.json
+
       # Checksum every staged asset. Written outside dist/ first so the glob
       # cannot include the (empty) checksums.txt the redirection would create.
       - name: Generate SHA-256 checksums
 
@@ -2,6 +2,41 @@
 
 ## Development
 
+## Version 0.4.1
+
+### Added
+
+- Prebuilt arm64 builds for Linux and Windows: desktop bundles, CLI archives,
+  and the one-line installers, alongside the existing x64 and macOS ones.
+- A JSON Schema for `mcp.yml`, published with every release: point an editor at
+  it for completion, hover documentation, and validation as you type.
+- Skills may ship binary files. An image, font, or compiled helper is copied,
+  hashed, and verified like any other file.
+
+### Changed
+
+- A skill with extra or oddly typed frontmatter fields installs instead of
+  being dropped: only `name` is required.
+- A one-line `description:` may hold a second colon, and a header or `env`
+  value may be a bare `{param}`.
+
+### Fixed
+
+- "Invalid YAML frontmatter" now says what is wrong and on which line of the
+  file, instead of naming only the file.
+- An `mcp.yml` that cannot be read or parsed says so, in the app's
+  notifications and on the CLI's standard error.
+- One unreadable skill no longer takes every skill after it in the repository
+  with it. It is skipped alone, and named.
+- Switching a repository's branch refreshes its skills and MCP servers, instead
+  of leaving both pages on the previous branch's contents.
+- Syncing a repository refreshes the MCP catalog too, which it had left to the
+  next visit to an MCP page.
+- Cloning a repository that needs Git LFS fails when git-lfs is missing,
+  instead of quietly leaving pointer files in place.
+- The Windows MSIX packages the desktop app; it used to pick between two
+  binaries sharing a file name.
+
 ## Version 0.4.0
 
 ### Added
 
@@ -36,6 +36,39 @@ docs: document hook consent flow
 
 ---
 
+## Changelog Entries
+
+Every user-visible change gets a bullet under `## Development` in
+[`CHANGES.md`](CHANGES.md), grouped under `### Added`, `### Changed`, or
+`### Fixed`.
+
+**Rules:**
+
+- Keep each bullet to 25 words or fewer, counted as whitespace-separated
+  tokens; a code span counts as one word whatever it contains. Wrap at the
+  file's usual width, with continuation lines indented two spaces.
+- The cap applies to `### Added`, `### Changed`, and `### Fixed` alike, and
+  only to `## Development`. A section is frozen once released.
+- English, and describe the change, not the code that made it.
+- One bullet per change. Two changes that need separate wording are two
+  bullets, never one longer one.
+
+**Examples:**
+
+```
+### Changed
+
+- A skill with extra or oddly typed frontmatter fields installs instead of
+  being dropped: only `name` is required.
+
+### Fixed
+
+- Switching a repository's branch refreshes its skills and MCP servers,
+  instead of leaving both pages on the previous branch's contents.
+```
+
+---
+
 ## Dependency Discipline
 
 Add only packages that are genuinely required for the application to work.