docs: desktop UI guidelines and dev-app-verify skill

.claude/skills/dev-app-verify/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: dev-app-verify
+description: Drive and screenshot the running Rocket.Chat Desktop dev app (yarn start) through the main-process inspector on port 9339 — trigger menu items (Simulate Download/Update), evaluate in the renderer DOM, capture titlebar screenshots. Use whenever a UI change needs runtime/visual verification that component tests can't see (paint, clipping, colors, animation, layout).
+---
+
+Follow `skills/dev-app-verify/SKILL.md` (repo root) — the canonical,
+agent-agnostic version of this runbook. It contains the ready-made inspector
+script, menu-triggering and DOM-truth recipes, and the three pitfalls that
+produce false alarms (window occlusion freezing `capturePage`, watcher
+restarts killing in-flight state, singleton-lock wedges).
+
+This stub exists so Claude Code auto-discovers the skill; keeping the body in
+one place prevents the two copies from drifting.

.claude/skills/electron-bump/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: electron-bump
+description: Upgrade the Electron version in Rocket.Chat.Electron safely. Detects breaking changes between the current and target Electron release, produces a migration plan gated on user approval, applies the fixes (using GitNexus impact analysis to find every affected callsite), bumps coupled config (electron-builder bundle id, CI node-version, @types/node), runs lint + tests, and opens a ready PR from a fresh branch off master. Trigger when the user says "bump electron", "upgrade electron", "update electron to X", "/electron-bump", or asks to move to a newer Electron release.
+---
+
+# Electron Version Bump
+
+Automates a safe Electron upgrade for **this repo** (Rocket.Chat.Electron). Plan-gated: research → plan → **STOP for approval** → apply → PR.
+
+## Invocation
+
+```
+/electron-bump [version]
+```
+
+- `version` given (e.g. `41.2.0`) → target that exact release.
+- `version` omitted → resolve **latest stable** from npm (`npm view electron version`), confirm it with the user before proceeding.
+- Never silently skip across multiple majors. If target is 2+ majors ahead of current, warn and ask whether to step through intermediate majors one at a time.
+
+## Hard rules
+
+- Branch from **master**, never edit master directly. Use a worktree (see CLAUDE.md § Worktrees) so the user's working dir is untouched.
+- Plan-gated: do NOT apply any code/config edit until the user approves the migration plan.
+- This is an Orchestrator task: delegate research to `researcher`, edits to `builder-*`, test runs to `watcher`/`tester`. Don't solo the implementation.
+- Never commit/push without explicit user permission for the commit step (PR creation is the approved end-state of this skill, but confirm before `git push` if not already authorized this session).
+- GitNexus is authoritative for "what calls this Electron API". Query it before grepping.
+
+---
+
+## Phase 0 — Resolve versions & freshness
+
+1. Read current versions:
+   - `node -p "require('./package.json').devDependencies.electron"` → CURRENT.
+   - `node -p "require('./package.json').devDependencies['electron-builder']"` → builder version.
+2. Resolve TARGET (arg or `npm view electron version`).
+3. Classify the jump: **patch** (z), **minor** (y), or **major** (x). This drives effort:
+   - **patch / minor within same major** → historically package.json + yarn.lock only, no code changes. Light path.
+   - **major** → expect API breaks, code adaptation, @types/node bump, README/builder updates. Full path.
+4. Ensure GitNexus index is fresh: if any GitNexus tool warns stale, run `npx gitnexus analyze --skip-agents-md` in background and continue.
+
+---
+
+## Phase 1 — Detect breaking changes (research, parallel)
+
+Dispatch a `researcher` to gather the authoritative breaking-changes list, and a `finder` to confirm the current coupled surface (it may have drifted since this skill was written).
+
+**Researcher brief** — fetch and distill, for the range CURRENT → TARGET:
+- Electron breaking-changes doc: `https://www.electronjs.org/docs/latest/breaking-changes` (covers planned + past removals). Also each major's release blog `https://www.electronjs.org/blog/electron-<major>-0`.
+- The bundled **Node.js** and **Chromium** versions for the target release (from `https://releases.electronjs.org/` or the release blog). Node major bump → may need `@types/node` bump + `node-version` in CI.
+- Return a flat list: every breaking/deprecated/removed API in range, each tagged `removed | behavior-change | deprecated`, with the Electron version it landed in.
+
+**Finder brief** — re-confirm the coupled surface in the repo (do not trust this doc blindly; verify):
+- Electron version declarations, electron-builder config, CI `node-version` pins.
+- Direct `from 'electron'` imports and which modules dominate.
+- Presence of Electron-coupled patches in `.yarn/patches/` or `patches/`.
+- Any native deps needing rebuild (node-gyp/prebuild).
+
+### Coupled-surface hint map (WHERE to look — never trust any value here as current)
+
+This lists the *kinds of places* coupled to the Electron version, so the finder knows where to look. It is a hint map, not a source of truth: every concrete value (version numbers, bundle ids, pinned Node) MUST come from the finder reading the repo live this run, never from this table. Treat anything specific below as "last seen" only.
+
+| What | Where | Notes |
+|------|-------|-------|
+| Electron version | `package.json` → `devDependencies.electron` | primary |
+| electron-builder | `package.json` → `devDependencies.electron-builder` | must stay compatible with target Electron major |
+| Builder config | `electron-builder.json` | inspect live. A `mac.bundleVersion` (and similar build ids) exists here but is an APP build id, NOT Electron-coupled — do not bump it for an Electron upgrade unless packaging actually requires it. |
+| CI Node pin | `.github/workflows/build-release.yml`, `pull-request-build.yml`, `validate-pr.yml` | `node-version:` key; bump if target's bundled Node major changes |
+| @types/node | `package.json` | bump to match bundled Node major on major Electron bumps |
+| Runtime version read | `src/ui/main/serverView/index.ts` (`process.versions.electron`) | sanity-check still valid |
+| Cert docs | `docs/corporate-certificate-configuration.md` | references Node TLS API availability per Electron version |
+
+**Patches**: none Electron-coupled as of E40 (`@ewsjs/xhr` and `@kayahr/jest-electron-runner` are unrelated — see CLAUDE.md). **Native deps**: none (pure JS/TS, no ABI risk). Re-verify both via the finder.
+
+### High-risk API zones (churn often here)
+
+GitNexus-query each before assuming safe. Known hot callsites as of E40:
+
+| API | Risk | Known callsites |
+|-----|------|-----------------|
+| `session.setPermissionRequestHandler` | HIGH | `src/ui/main/serverView/index.ts`, `src/videoCallWindow/ipc.ts` |
+| `desktopCapturer.getSources` | MEDIUM | `src/screenSharing/*` |
+| `contextBridge` | MEDIUM | `src/preload.ts`, `src/videoCallWindow/preload/index.ts` |
+| `screen` / display | MEDIUM | `src/logViewerWindow/ipc.ts`, `src/videoCallWindow/ipc.ts` |
+
+Not currently used (skip unless re-introduced): `webContents.printToPDF`, `remote` module, `BrowserView`/`WebContentsView`.
+
+---
+
+## Phase 2 — Map breaking changes to THIS codebase via GitNexus
+
+For each breaking/removed/changed API the researcher returned, find whether and where the repo uses it. **Use GitNexus, not raw grep** (CLAUDE.md mandate):
+
+1. `mcp__gitnexus__query({ query: "<api or concept>", repo: "Rocket.Chat.Electron" })` to find execution flows touching it.
+2. For each concrete symbol/callsite, `mcp__gitnexus__context({ name: "<symbol>", repo: "Rocket.Chat.Electron" })` for the 360° view.
+3. `mcp__gitnexus__impact({ target: "<symbol>", direction: "upstream", repo: "Rocket.Chat.Electron" })` to get the blast radius before editing. **Report HIGH/CRITICAL risk to the user.**
+
+Produce, per breaking change, one of:
+- **Not used** — no action.
+- **Used, mechanical fix** — exact files + line-level change.
+- **Used, needs judgment** — flag for the plan, describe the decision.
+
+---
+
+## Phase 3 — Write the migration plan & STOP
+
+Write the plan to a **dedicated, non-colliding** file: `.localdev/workflow/electron-bump-<TARGET-major>.md` (e.g. `electron-bump-42.md`). Do NOT write to `.localdev/workflow/todo.md` — it may already hold an unrelated active plan, and clobbering it loses live work. If the dedicated file already exists from a prior attempt, overwrite that one (it's yours). Present a summary to the user. The plan MUST contain:
+
+- Version delta: CURRENT → TARGET, bundled Node/Chromium delta, jump class.
+- Breaking changes **that affect this repo**, each with: affected files, GitNexus blast radius, proposed fix, risk.
+- Coupled config edits required (builder bundle id, CI node-version, @types/node) — only the ones actually needed for this delta.
+- Test/verification plan (lint, `*.spec.ts` renderer, `*.main.spec.ts` main, cross-platform note).
+- Anything ambiguous → list as an open question.
+
+**STOP. Do not proceed to Phase 4 until the user approves.** If the plan has open questions, ask them now.
+
+---
+
+## Phase 4 — Branch & apply (after approval)
+
+1. Create worktree off master:
+   ```bash
+   mkdir -p ../Rocket.Chat.Electron-worktrees
+   git worktree add ../Rocket.Chat.Electron-worktrees/electron-<TARGET> -b chore/electron-<TARGET> master
+   ```
+   Work in that worktree for the rest of the skill.
+2. Bump the version:
+   - `package.json` → `devDependencies.electron` = TARGET (and `electron-builder` if the plan calls for it).
+   - `@types/node` if Node major changed.
+   - `yarn install` to regenerate `yarn.lock` (dispatch `watcher` — install is noisy).
+3. Apply coupled config edits from the plan (builder bundle id, CI `node-version`).
+4. Apply code fixes:
+   - Dispatch `builder-fast` for single scoped edits, `builder-smart` for non-trivial API adaptations, `builder-trivial` only for the same edit across 5+ sites.
+   - Serialize builders by file. Re-run `mcp__gitnexus__impact` mentally against each edit's blast radius.
+5. Update docs only if the plan flagged them (README version table, cert doc).
+
+---
+
+## Phase 5 — Verify
+
+Dispatch `watcher`/`tester` (keep noisy output out of orchestrator context):
+
+1. `yarn lint` — ESLint + TS typecheck (`npx tsc --noEmit` if needed).
+2. `yarn test` — full Jest suite (renderer + main). Note: RTL specs need fake timers (see project memory `lesson_rtl_jest_electron_timer_leak`); a leaked timer orphans electron procs. Don't loop per-builder full runs — batch-verify once.
+3. If a local build is cheap enough, smoke `yarn build`. Full packaging (electron-builder, Windows signing) is CI's job — do NOT attempt local Windows/MSI builds.
+4. Any failure → diagnose root cause, fix, re-verify. Do not mark done with red tests.
+
+Definition of Done: version bumped everywhere the plan listed, lint green, tests green, no orphaned Electron API usage left from the breaking-changes list.
+
+---
+
+## Phase 6 — Commit & PR
+
+1. Run `mcp__gitnexus__detect_changes()` to confirm only the expected symbols/flows changed (CLAUDE.md mandate).
+2. Show the user the diff summary, confirm the commit.
+3. Commit with conventional message: `chore: update Electron from <CURRENT> to <TARGET> (#<PR>)` — match the repo's historical style (see PRs #3285, #3179). Body lists breaking-change adaptations for a major bump; minimal for patch/minor.
+4. Push the branch.
+5. Open a **ready (non-draft)** PR: `gh pr create --base master --label build-artifacts`. Base is **master** (repo default). Apply the `build-artifacts` label here because an Electron bump changes packaging and reviewers must smoke-test the built installers — this is exactly the case the label is for. PR body:
+   - What changed: version delta, bundled Node/Chromium.
+   - Breaking changes addressed (bullet list, frame as adaptation not regression).
+   - Verification: lint + tests pass; CI will run cross-platform builds.
+6. After the PR is open, suggest `npx gitnexus analyze --skip-agents-md` (background) to refresh the index for the changed code.
+
+---
+
+## Effort shortcut
+
+- **Patch/minor within same major**: Phases 1–2 usually find nothing in-repo. Plan is short ("no code changes, bump + lockfile"), still gated. Phases 4–6 are package.json + yarn.lock + verify + PR. Match PR #3285's minimal shape.
+- **Major**: full path, expect code adaptation + @types/node + builder bundle + README, like PR #3179.

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required.
+
+> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+node .gitnexus/run.cjs analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
+
+### status — Check index freshness
+
+```bash
+node .gitnexus/run.cjs status
+```
+
+Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+node .gitnexus/run.cjs clean
+```
+
+Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+node .gitnexus/run.cjs wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+node .gitnexus/run.cjs list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

.claude/skills/gitnexus/gitnexus-debugging/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. query({query: "<error or symptom>"})            → Find related execution flows
+2. context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**query** — find code related to error:
+
+```
+query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**context** — full context for a suspect:
+
+```
+context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```