chore(release): add Electron auto-release on app version bump

.changeset/editor-floating-arrow-release.md

@@ -0,0 +1,5 @@
+---
+"cruncher": minor
+---
+
+Autocomplete now uses fuzzy matching — suggestions appear even when you type non-contiguous characters, with matched characters highlighted in the dropdown. The token hint tooltip arrow now automatically flips direction when the card appears above the cursor (near the top of the viewport).

.claude/skills/prepare-release/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: prepare-release
 description: >
-  Finalizes and ships changes in the Cruncher monorepo: runs lint, format, tests,
-  creates changesets, updates docs, commits, and pushes.
+  Finalizes and ships changes in the Cruncher monorepo: pulls latest main,
+  creates a feature branch, runs lint/format/tests/typecheck, creates changesets,
+  updates docs, commits, opens a PR, and waits for CI to pass.
   Use this skill whenever the user says "prepare for release", "finalize changes",
-  "create changeset", "ready to ship", "commit and push", "run checks before PR",
+  "create changeset", "ready to ship", "open a PR", "run checks before PR",
   or asks to wrap up a feature/fix with all the standard pre-release steps.
   Even if only one step is mentioned (e.g. "just create the changeset"), consult
   this skill to make sure nothing is skipped.
@@ -16,7 +17,27 @@ Work through these steps in order. Each step must pass before moving on.
 
 ---
 
-## 1 — Understand what changed
+## 1 — Sync with main
+
+Make sure local main is up to date and create a feature branch for the change:
+
+```bash
+git checkout main
+git pull origin main
+```
+
+Then create a branch named after the change (use the type and short scope from the eventual commit message):
+
+```bash
+git checkout -b <type>/<short-description>
+# e.g. feat/fuzzy-autocomplete  or  fix/shadow-dom-outside-detector
+```
+
+If you are already on a non-main branch with uncommitted work, stash it first (`git stash`), sync main, create the branch from main, then pop (`git stash pop`).
+
+---
+
+## 2 — Understand what changed
 
 Read `git diff HEAD` (or the staged diff) across all modified files before doing anything else. You need to know:
 
@@ -26,18 +47,17 @@ Read `git diff HEAD` (or the staged diff) across all modified files before doing
 
 The Electron app (`cruncher`), docs (`docs-cruncher`), and tools (`cruncher-tools`) are **never published** — they never need a changeset entry.
 
-
 ---
 
-## 2 - Code cleanups
+## 3 — Code review
 
-Read the diff you written - make sure everything is as elgant as you can - make sure all algorithms are optimized!
-If you detect something wrong - immediatly report to the user - dont continue to next steps!!!
-Suggest improvements before continuing!
+Read the full diff. Make sure everything is as elegant and optimised as possible.
+**If you detect something wrong — immediately report it to the user and stop. Do not continue to the next step.**
+Suggest concrete improvements and wait for the user's go-ahead before proceeding.
 
 ---
 
-## 2 — Lint
+## 4 — Lint
 
 ```bash
 pnpm lint
@@ -47,7 +67,7 @@ Runs oxlint over `src/`. Zero warnings, zero errors required. Fix any issues bef
 
 ---
 
-## 3 — Format
+## 5 — Format
 
 ```bash
 pnpm format
@@ -57,7 +77,7 @@ Runs oxfmt in auto-fix mode. Always run the fixer (not just the checker) so the
 
 ---
 
-## 4 — Tests
+## 6 — Tests
 
 ```bash
 pnpm test
@@ -67,36 +87,49 @@ Vitest in run mode. All tests must pass. If a test fails, fix the root cause —
 
 ---
 
-## 5 — Typecheck (catches type errors)
+## 7 — Typecheck
 
 ```bash
 pnpm typecheck
 ```
 
+Zero type errors required across all packages.
 
 ---
 
-## 6 — Changesets
+## 8 — Changesets
+
+Create a changeset for **any** of these:
+- Packages under `packages/` that are published to npm
+- **`cruncher`** (`apps/cruncher`) — the Electron app always needs a changeset when it changes. Even though it is private and not published to npm, the version bump triggers the Electron build in CI via the `electron-version-changed` workflow output.
 
-Create a changeset only for packages that:
-- Live under `packages/` **and** `apps`
-- Are actually published to npm (check `.changeset/config.json` → `ignore` list)
+Packages that **never** need a changeset: `cruncher-tools`, `docs-cruncher` (both in the `ignore` list in `.changeset/config.json`).
 
-Run interactively or write the `.md` file directly in `.changeset/`:
+Write the `.md` file directly in `.changeset/` or run interactively:
 
 ```bash
 pnpm changeset
 ```
 
 ### Bump rules
-| Change type | Bump |
-|---|---|
-| New exported API, breaking interface change | `major` |
+| Change type                                        | Bump    |
+|----------------------------------------------------|---------|
+| New exported API, breaking interface change        | `major` |
 | New feature, new option, new field added to a type | `minor` |
-| Bug fix, internal refactor, perf improvement | `patch` |
+| Bug fix, internal refactor, perf improvement       | `patch` |
 
 ### Changeset format
 
+For the Electron app:
+```markdown
+---
+"cruncher": minor
+---
+
+Short user-facing summary. What the user sees or can do now.
+```
+
+For published packages:
 ```markdown
 ---
 "@cruncher/adapter-utils": minor
@@ -109,9 +142,9 @@ Keep it factual and user-focused — not a list of files touched.
 
 ---
 
-## 7 — Docs
+## 9 — Docs
 
-Update docs **only for user-visible changes** - especially Cruncher app itself at apps/cruncher/. Skip entirely if the change is internal-only (refactor, perf, test data, internal types).
+Update docs **only for user-visible changes** — especially the Cruncher app at `apps/cruncher/`. Skip entirely if the change is internal-only (refactor, perf, test data, internal types).
 
 Docs live in `docs/src/content/docs/`:
 - `getting-started/` — UI behaviour, settings, keyboard shortcuts, live mode
@@ -122,13 +155,13 @@ Docs live in `docs/src/content/docs/`:
 - Write for the **user**, not the implementer. Explain what changed from their perspective.
 - Be concise. Add or update only the paragraphs that cover the new behaviour.
 - Reuse existing Astro components (`ParamItem`, `FunctionCard`, `AdapterCard`, `CommandCard`, `ConfigField`) — don't invent new HTML.
-- Make the docs look nice - create new components if there's no matching component - that you think will look good.
+- Create a new component if none of the existing ones fit and it will look good.
 - Use Starlight CSS variables (`var(--sl-color-*)`) if custom styling is needed.
 - Never document internal implementation details (cache structure, engine internals, etc.).
 
 ---
 
-## 8 — Commit
+## 10 — Commit
 
 Stage only the files that belong to this change. Commit with a clear message that follows this pattern:
 
@@ -144,10 +177,36 @@ Common types: `feat`, `fix`, `perf`, `refactor`, `docs`, `chore`.
 
 ---
 
-## 9 — Push
+## 11 — Push and open PR
+
+Push the branch and open a pull request against `main`:
 
 ```bash
-git push origin main
+git push -u origin <branch-name>
+gh pr create --base main --title "<type>(<scope>): <short summary>" --body "$(cat <<'EOF'
+## Summary
+<bullet points — what changed and why>
+
+## Test plan
+- [ ] lint / format / tests / typecheck all pass (CI)
+- [ ] <any manual verification steps>
+EOF
+)"
 ```
 
-If the push is rejected (branch protection, required checks), tell the user rather than force-pushing.
+Return the PR URL to the user.
+
+---
+
+## 12 — Wait for CI
+
+Poll CI until all required checks pass:
+
+```bash
+gh pr checks <pr-number> --watch
+```
+
+- If checks pass → report success to the user. The PR is ready to merge.
+- If a check fails → read the failure output, fix the root cause, push a new commit, and re-watch.
+
+Do **not** merge the PR yourself unless the user explicitly asks.

.github/workflows/release.yml

@@ -22,6 +22,7 @@ jobs:
     outputs:
       published: ${{ steps.changesets.outputs.published }}
       publishedPackages: ${{ steps.changesets.outputs.publishedPackages }}
+      electron-version-changed: ${{ steps.electron-version.outputs.changed }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -59,11 +60,22 @@ jobs:
           # See: https://github.com/changesets/action/issues/542
           NODE_AUTH_TOKEN: ""
 
+      - name: Check if Electron app version changed
+        id: electron-version
+        run: |
+          PREV=$(git show HEAD~1:apps/cruncher/package.json 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(JSON.parse(d).version))" || echo "")
+          CURR=$(node -p "require('./apps/cruncher/package.json').version")
+          if [ -n "$PREV" ] && [ "$PREV" != "$CURR" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
   publish-electron:
     name: Publish Electron app (${{ matrix.os }})
     needs: release-npm
     runs-on: ${{ matrix.os }}
-    if: always() && (needs.release-npm.outputs.published == 'true' || github.event_name == 'workflow_dispatch')
+    if: always() && (needs.release-npm.outputs.published == 'true' || needs.release-npm.outputs.electron-version-changed == 'true' || github.event_name == 'workflow_dispatch')
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
@@ -94,7 +106,7 @@ jobs:
     name: Publish Electron release
     needs: [release-npm, publish-electron]
     runs-on: ubuntu-latest
-    if: always() && needs.publish-electron.result == 'success' && (needs.release-npm.outputs.published == 'true' || github.event_name == 'workflow_dispatch')
+    if: always() && needs.publish-electron.result == 'success' && (needs.release-npm.outputs.published == 'true' || needs.release-npm.outputs.electron-version-changed == 'true' || github.event_name == 'workflow_dispatch')
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

CLAUDE.md

@@ -10,8 +10,8 @@ Cruncher is a Turborepo-based monorepo containing:
 ## Build & Release
 - Uses **Changesets** for versioning and releases
 - **OIDC trusted publishing** to npm (no NPM_TOKEN needed)
-- Electron app published via `workflow_dispatch` only
-- `.changeset/config.json` ignores: `cruncher-tools`, `docs-cruncher`, `cruncher` (electron)
+- Electron app releases automatically when `apps/cruncher` version is bumped by a changeset
+- `.changeset/config.json` ignores: `cruncher-tools`, `docs-cruncher` — **`cruncher` (Electron app) is NOT ignored and needs a changeset when it changes**
 - Local testing: `pnpm local-registry` + `pnpm release:local`
 
 ## Code Style & Conventions

docs/src/content/docs/getting-started/08-ui-guide.mdx

@@ -20,7 +20,7 @@ The Cruncher window is divided into several key areas:
 
 The search header contains:
 
-- **Query Editor**: Multi-line input for your QQL query. Press `Alt+Q` to focus or use keyboard shortcut `Shift+Enter` to re-evaluate the pipeline.
+- **Query Editor**: Multi-line input for your QQL query. Press `Alt+Q` to focus or use keyboard shortcut `Shift+Enter` to re-evaluate the pipeline. As you type, an autocomplete dropdown appears with fuzzy-matched suggestions — matched characters are highlighted so you can see why each suggestion was chosen. Hover over a token to see a hint tooltip with its description and syntax.
 - **Time Range Selector**: Click to open a date/time picker, or press `Alt+T` to quickly access it.
 - **Execute Button**: Run your full search.
 - **Live Button**: Toggle real-time incremental log streaming. See [Live Mode](/getting-started/09-live-mode).