Merge pull request 'feat: MCP server catalog core -- signed, validated, resolvable (#10, #61)' (#65) from feat/10-catalog-core into main

Publish SHA-256 checksums for every release artifact and sign them with a
domain-separated Ed25519 signature. Skips signing (loudly) if the key secret
is absent rather than failing the release. README documents verification and
states the limit plainly: this proves the file is the one we published; it
does not remove Gatekeeper/SmartScreen warnings.

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Lint (ruff)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format --check
+        run: ruff format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    name: Tests (py${{ matrix.python }} / ${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.12", "3.13"]
+        include:
+          # Windows tests on 3.12 only — the version the release binaries ship
+          # with. The self-hosted Windows runner blocks setup-python's install
+          # script (PowerShell execution policy), so it uses the host's `py`
+          # launcher + venv, same as release.yml.
+          - os: windows-latest
+            python: "3.12"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }} (Linux)
+        if: runner.os == 'Linux'
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Set up Python venv (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          py -${{ matrix.python }} -m venv .venv
+          Add-Content -Path $env:GITHUB_PATH -Value "$env:GITHUB_WORKSPACE\.venv\Scripts"
+
+      # bcc_core has no GUI imports, so the test suite needs no PySide6 —
+      # keeps CI fast and avoids Qt system-library headaches on the runner.
+      # cryptography is for tests/test_checksums.py (release signing helper).
+      - name: Install test dependencies
+        run: pip install pytest cryptography
+
+      - name: Run tests
+        run: python -m pytest -v

.github/workflows/release.yml

@@ -107,11 +107,72 @@ jobs:
       contents: write
 
     steps:
+      # Needed for scripts/sign_checksums.py — the release job otherwise
+      # only downloads build artifacts, it doesn't check out the repo.
+      - name: Checkout
+        uses: actions/checkout@v4
+
       - name: Download all artifacts
         uses: actions/download-artifact@v3
         with:
           path: artifacts
 
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # download-artifact@v3 nests each artifact under a directory named
+      # after it (artifacts/<name>/<name>). Flatten into one directory so
+      # SHA256SUMS lists plain filenames, matching what `sha256sum -c`
+      # expects when run from inside an extracted release download.
+      - name: Collect release files
+        run: |
+          mkdir -p release-files
+          find artifacts -type f -exec cp {} release-files/ \;
+          ls -la release-files
+
+      - name: Generate SHA256SUMS
+        run: python3 scripts/sign_checksums.py generate release-files --out release-files/SHA256SUMS
+
+      # ── Sign the checksum manifest (best-effort) ──────────────────────
+      #
+      # BCC binaries are not code-signed (no budget for a paid cert). This
+      # is the free half: a checksum manifest, detached-signed with
+      # Ed25519, so a tampered download is detectable by anyone who
+      # checks. It does NOT remove Gatekeeper/SmartScreen warnings.
+      #
+      # The private key is a repo secret (RELEASE_SIGNING_KEY, base64 raw
+      # Ed25519 seed) generated via the Catalog Console (#62). If it's not
+      # set, we still publish the release — just without a .sig — rather
+      # than fail the release outright.
+      - name: Check for signing key
+        id: signing
+        run: |
+          if [ -n "${{ secrets.RELEASE_SIGNING_KEY }}" ]; then
+            echo "has_key=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_key=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install signing dependencies
+        if: steps.signing.outputs.has_key == 'true'
+        run: pip install cryptography
+
+      - name: Sign SHA256SUMS
+        if: steps.signing.outputs.has_key == 'true'
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+        run: |
+          python3 scripts/sign_checksums.py sign \
+            --sums release-files/SHA256SUMS \
+            --out release-files/SHA256SUMS.sig
+
+      - name: Warn — release will be unsigned
+        if: steps.signing.outputs.has_key != 'true'
+        run: |
+          echo "::warning::RELEASE_SIGNING_KEY secret is not set — this release is being published WITHOUT a signed SHA256SUMS.sig. Add the secret (base64 raw Ed25519 seed, generated via the Catalog Console, #62) before the next tag."
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -119,7 +180,9 @@ jobs:
           draft: false
           prerelease: false
           generate_release_notes: false
-          files: artifacts/**/*
+          files: |
+            artifacts/**/*
+            release-files/SHA256SUMS*
           body: |
             ## Better Claude Config ${{ github.ref_name }}
 
@@ -139,5 +202,8 @@ jobs:
             xattr -cr /Applications/BetterClaudeConfig.app
             ```
 
+            ### Verifying your download
+            Every release includes `SHA256SUMS` (and, when the signing key is configured, a detached `SHA256SUMS.sig`). See [Verifying your download](https://git.avezzano.io/the_og/better-claude-config#verifying-your-download) in the README for commands. This proves you got the file we published — it does not remove Gatekeeper/SmartScreen warnings.
+
             ### Requirements
             No Python installation needed — the app is self-contained.

.gitignore

@@ -5,6 +5,12 @@ __pycache__/
 .venv/
 venv/
 
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
 # PyInstaller / build
 build/
 dist/

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# Install once with: pip install pre-commit && pre-commit install
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json

CLAUDE.md

@@ -8,10 +8,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Install runtime dependency
 pip install -r requirements.txt
 python bcc.py          # run the GUI
-python test_core.py    # run unit tests (23 tests, no GUI needed)
+
+# Test & lint (no GUI / PySide6 needed — tests only exercise bcc_core)
+pip install -r requirements-dev.txt
+python -m pytest       # unit tests in tests/
+ruff check .           # lint
+ruff format .          # format (CI enforces ruff format --check)
 
 # Build a self-contained binary
-pip install -r requirements-dev.txt
 python scripts/build_icons.py   # regenerate icons/app.icns + icons/app.ico if needed
 pyinstaller bcc.spec
 # macOS  → dist/BetterClaudeConfig.app
@@ -19,7 +23,7 @@ pyinstaller bcc.spec
 # Linux  → dist/BetterClaudeConfig
 ```
 
-Requires Python 3.10+. Runtime dependency: `PySide6>=6.6`. Build-time: `pyinstaller>=6.0`, `pillow>=10.0`.
+Requires Python 3.10+. Runtime dependency: `PySide6>=6.6`. Tooling config (ruff, pytest, project metadata) lives in `pyproject.toml`. CI (`.github/workflows/ci.yml`) runs lint + tests on every push/PR; releases build on tag push (`release.yml`).
 
 ## Architecture
 
@@ -27,9 +31,9 @@ The codebase is split into two layers:
 
 **`bcc_core.py`** — All logic with no GUI imports. Contains:
 - `Profile` / `ServerEntry` dataclasses (the data model)
-- `discover_profiles()` — scans the platform's app-support directory for `Claude*` folders (Claude Desktop) **and** always adds `~/.claude/settings.json` (Claude Code, cross-platform)
+- `discover_profiles()` — scans the platform's app-support directory for `Claude*` folders (Claude Desktop) **and** always adds `~/.claude.json` (Claude Code user scope — what `claude mcp add` writes). `~/.claude/settings.json` is NOT a server config (it rejects `mcpServers` with a schema error) and is only surfaced, labelled legacy, if servers are found parked in it. Project-scope `.mcp.json` files can be opened via Add config…
 - `load_config` / `extract_servers` / `apply_servers` / `write_config` — the read/write pipeline; writes are atomic with rotating timestamped backups in `.bcc_backups/`
-- `parse_pasted_json()` — accepts three JSON shapes (full config, inner map, or bare server object)
+- `parse_pasted_json()` / `parse_pasted_json_verbose()` — accepts three JSON shapes (full config, inner map, or bare server object). Input does not have to be valid JSON: `repair_json_text()` auto-fixes markdown fences, surrounding prose, `//` `/* */` `#` comments, trailing/missing commas, smart quotes, single quotes, unquoted keys, Python/JS literals, and unclosed braces. The verbose variant also returns human-readable notes describing every repair applied (shown live in the paste dialog)
 - `check_dependency()` / `diagnostics_text()` / `pin_command_path()` — PATH resolution logic; distinguishes "found on normal PATH" (ok) vs "found only on augmented PATH" (warn) vs "not found" (missing). Uses an `lru_cache`-memoized `augmented_path()` that extends the inherited PATH with common runtime locations (nvm, homebrew, cargo, volta, etc.)
 - `test_remote()` — synchronous HTTP reachability check, intended to run off the UI thread
 

HANDOFF.md

@@ -0,0 +1,95 @@
+# HANDOFF — BCC feature backlog implementation
+
+For the Claude Code agent working in this repo. Read this whole file, then
+CLAUDE.md, before touching code. A supervising Claude session watches this
+project through the Gitea MCP (issues, PRs, CI runs on git.avezzano.io), so
+keep all state in Gitea where it can be seen: issues for work items, PRs for
+changes, comments for decisions.
+
+## Step 0 — sync state
+
+`main` may contain local commits that aren't on origin yet (the previous
+session couldn't push). Run `git status` / `git log origin/main..main`; if
+there are unpushed commits, **push them first** and confirm CI goes green
+before starting anything.
+
+## Step 1 — file the backlog as issues
+
+Create one Gitea issue per item in the backlog table below (`tea` CLI or the
+API — you have full credentials). Prefix titles with the ID (e.g.
+"[#2] Stdio server spawn-test"). Create labels P0/P1/P2 first if they don't
+exist. Copy each item's full section from `../bcc-feature-requests.md`
+(sibling of this repo folder) into the issue body — it has problem statements,
+evidence, proposed fixes, and acceptance criteria.
+
+**Corrections to that document — do not re-implement:**
+- "Doc correction: README Claude Code path" — DONE (commit `b16c0fd`).
+- Item 1 (secret masking) — MOSTLY DONE (commit `6dee318`): env/header values
+  masked via delegate + Show-secrets toggle, Add-dialog password echo,
+  diagnostics args redaction (`redact_args`). **Only remainder:** the warning
+  badge when a secret-shaped value sits in `args` instead of `env`. File the
+  issue scoped to just that.
+
+## Step 2 — work the backlog
+
+| Order | ID | Item | Priority | Notes |
+|---|---|---|---|---|
+| 1 | 2 | Stdio server spawn-test | P0 | Spawn with timeout, capture stderr; core logic in bcc_core (GUI-free, testable) |
+| 2 | 3 | Backup restore UI | P0 | List `.bcc_backups/`, preview/diff, restore through normal atomic-write path |
+| 3 | 4 | Stale-file protection | P0 | mtime/hash at load, re-check before write, prompt on conflict |
+| 4 | 1r | Secret-in-args warning badge | P0 | Remainder of item 1; `is_secret_key`/`_is_secret_value` already exist in bcc_core |
+| 5 | 8 | Duplicate-name conflict on paste/import | P1 | VERIFY FIRST: check `paste_json`/`dropEvent` in bcc.py for silent overwrite; file findings on the issue before coding |
+| 6 | 5 | Cross-client support (Cursor/Windsurf/VS Code) | P1 | VS Code uses `servers` not `mcpServers` — needs a read/write adapter, not just paths |
+| 7 | 6 | In-app MCP log viewer | P1 | Platform log paths in the doc |
+| 8 | 7 | Windows MSIX path detection | P1 | Can't test locally on macOS — unit-test the detection logic, note that in the PR |
+| 9 | 9 | Restart Claude Desktop button | P1 | Platform-specific process handling; scope to Desktop only |
+| 10 | 10 | Server catalog / one-click add | P2 | Design pass first — post a proposal as an issue comment before building |
+
+## Workflow rules
+
+- **Branch per issue** off `main`: `feat/<issue-number>-short-slug` (or
+  `fix/`). One issue per PR. Reference the issue in the PR description
+  (`Closes #N`).
+- **Before every commit:** `python -m pytest` (all green), `ruff check .`,
+  `ruff format .`. CI enforces all three.
+- **Conventional commits** (`feat:`, `fix:`, `test:`, `docs:`, `chore:`) —
+  match the existing history's style: body explains the why.
+- **Merge only with green CI.** If the supervising session has flagged
+  something on the PR, resolve it before merging.
+
+## Architecture guardrails (violating these fails review)
+
+1. **The cardinal rule:** config writes only ever touch `mcpServers` and
+   `_disabledMcpServers`. Every other key is preserved verbatim, in order.
+   This matters extra for `~/.claude.json`, which holds conversation history
+   and project state.
+2. **Core/GUI split:** all logic in `bcc_core.py` (no GUI imports, unit-
+   testable); `bcc.py` stays a thin PySide6 shell. New logic gets tests in
+   `tests/` — they run without PySide6, keep it that way.
+3. **No new runtime dependencies** without posting the justification on the
+   issue first. PySide6 is currently the only one.
+4. **Writes are atomic + backed up** — route any new disk writes through
+   `write_config()`.
+5. Secrets never appear in diagnostics output or logs — use `redact_args`/
+   `is_secret_key` from bcc_core.
+
+## Current state (as of this handoff)
+
+- **92 tests** in `tests/test_core.py`, ruff clean, CI = lint + pytest (py3.10/3.12).
+- `main` = `ece049c` (PR #16 merged). No unpushed commits.
+- **Completed items:** #2 (spawn-test, PR #11), #3 (backup restore UI, PR #14),
+  #4 (stale-file protection, PR #15), #1r (secret-in-args warning, PR #16).
+- **Next item:** #8 — duplicate-name conflict handling. **VERIFY FIRST:** read
+  `paste_json` and `dropEvent` in `bcc.py` to check whether pasting/dropping a
+  server with a name that already exists silently overwrites it; file your
+  findings as a comment on issue #8 before writing any code.
+- Recent features you should know exist: lenient JSON repair
+  (`repair_json_text`, `parse_pasted_json_verbose`, `repair_config_file` +
+  RepairDialog), ArgsEdit numbered gutter + `split_suspicious_args`,
+  resizable splitters with QSettings persistence, secret masking, Claude Code
+  profile at `~/.claude.json` (settings.json only as "legacy" when it holds
+  parked servers), backup restore UI (RestoreDialog, `list_backups`,
+  `backup_diff`, `restore_backup`), stale-file protection (StaleDialog,
+  `config_mtime`, `external_change_summary`).
+- GUI can't be smoke-tested in CI; note in each PR whether you ran
+  `python bcc.py` locally and what you checked.

README.md

@@ -19,6 +19,65 @@ Pre-built self-contained binaries are attached to every [GitHub Release](../../r
 
 > **macOS Gatekeeper note:** the app is not notarized. On first launch, right-click → **Open**, or run `xattr -cr /Applications/BetterClaudeConfig.app` in a terminal.
 
+## Verifying your download
+
+BCC isn't code-signed — there's no budget for a paid certificate (macOS
+Developer ID, Windows Authenticode). Instead, every release publishes a
+`SHA256SUMS` file listing the checksum of each archive, detached-signed with
+Ed25519 as `SHA256SUMS.sig`. Both are attached to the release alongside the
+binaries.
+
+**What this proves:** the file you downloaded is byte-for-byte what we
+published, and the manifest itself was signed by our release key.
+
+**What this does NOT do:** it does not make the binary "safe," and it does
+**not** remove the macOS Gatekeeper or Windows SmartScreen warning — those
+are only suppressed by a paid OS-vendor certificate, which this project
+doesn't have. Verifying checksums is about detecting tampering in transit or
+on a mirror, not about vouching for the software.
+
+**Release signing public key** (Ed25519, base64, raw 32 bytes):
+
+```
+<PLACEHOLDER — AJ: paste the public key from the Catalog Console (#62) here>
+```
+
+### macOS / Linux
+
+```bash
+# From inside the folder you downloaded the release files into:
+sha256sum -c SHA256SUMS
+```
+
+If your `sha256sum` complains about missing files, download `SHA256SUMS`
+into the same directory as the archive you downloaded — it lists every
+platform's archive, and only the one(s) present will be checked.
+
+To also verify the manifest's signature (optional, requires Python +
+`pip install cryptography` and a checkout of this repo):
+
+```bash
+python3 scripts/sign_checksums.py verify \
+  --sums SHA256SUMS --sig SHA256SUMS.sig \
+  --pubkey-b64 "<the public key above>"
+```
+
+### Windows (PowerShell)
+
+```powershell
+Get-FileHash .\BetterClaudeConfig-Windows.zip -Algorithm SHA256
+```
+
+Compare the printed hash (case-insensitively) against the matching line in
+`SHA256SUMS`.
+
+### If a release has no `SHA256SUMS.sig`
+
+The signing key is a repo secret that has to be configured manually; if a
+release is missing the `.sig` file, the checksums themselves are still
+valid and safe to check against — the release workflow only skips signing,
+never checksum generation.
+
 ## Run from source
 
 ```bash
@@ -32,12 +91,17 @@ python bcc.py
 
 - **Auto-discovers installs** — scans the platform's app-support folder for any
   `Claude*` directory (so `Claude` and `Claude-Work` both show up) **and** finds
-  Claude Code at `~/.claude/settings.json`. Use **Add config…** to point at any
+  Claude Code's user-scope config at `~/.claude.json` (the file `claude mcp add`
-  other file manually.
+  writes). Use **Add config…** to point at any other file manually — e.g. a
+  project's `.mcp.json`.
 - **Form-based editing** — name, command, args (one per line), env vars, or for
   remote servers: URL, transport, and headers. No raw JSON.
-- **Paste JSON** — drop in any snippet from an MCP doc (full `mcpServers` block,
+- **Paste JSON — even broken JSON** — drop in any snippet from an MCP doc (full
-  inner map, or a single bare server object); it's parsed and merged.
+  `mcpServers` block, inner map, or a single bare server object); it's parsed
+  and merged. The paste box parses as you type and auto-repairs the stuff docs
+  and chat windows love to break: markdown fences, surrounding prose, comments,
+  trailing or missing commas, smart quotes, single quotes, unquoted keys, and
+  unclosed braces — and tells you exactly what it fixed before you commit.
 - **Drag & drop** a `.json` file onto the window to import servers from it.
 - **Copy to ▸** — copy the selected server straight into your *other* install.
 - **Active / Disabled sections** — servers are shown in two labelled lists with
@@ -76,7 +140,9 @@ After saving, **restart that Claude install** for changes to take effect.
 | Windows | `%APPDATA%`                      |
 | Linux   | `~/.config`                      |
 
-**Claude Code** (all platforms): `~/.claude/settings.json`
+**Claude Code** (all platforms): `~/.claude.json` (user scope). If servers are
+found parked in `~/.claude/settings.json` — where Claude Code ignores them — that
+file is also listed, marked *legacy*, so you can copy them over.
 
 ## Files
 
@@ -85,6 +151,7 @@ After saving, **restart that Claude install** for changes to take effect.
 - `test_core.py` — unit suite for the core (`python test_core.py`).
 - `bcc.spec` — PyInstaller build spec (cross-platform).
 - `scripts/build_icons.py` — regenerates `icons/app.icns` and `icons/app.ico` from source PNGs.
+- `scripts/sign_checksums.py` — generates and Ed25519-signs the release `SHA256SUMS` manifest (see [Verifying your download](#verifying-your-download)).
 
 ## Building from source
 

bcc.spec

@@ -31,7 +31,7 @@ a = Analysis(
     ["bcc.py"],
     pathex=[],
     binaries=[],
-    datas=[],
+    datas=[("icons", "icons"), ("data/catalog.json", "data")],
     hiddenimports=[],
     hookspath=[],
     hooksconfig={},
@@ -78,8 +78,8 @@ if sys.platform == "darwin":
         info_plist={
             "CFBundleName": "Better Claude Config",
             "CFBundleDisplayName": "Better Claude Config",
-            "CFBundleShortVersionString": "1.0.0",
+            "CFBundleShortVersionString": "1.3.0",
-            "CFBundleVersion": "1.0.0",
+            "CFBundleVersion": "1.3.0",
             "NSHighResolutionCapable": True,
             "NSRequiresAquaSystemAppearance": False,  # supports dark mode
             "LSMinimumSystemVersion": "11.0",
@@ -98,7 +98,7 @@ else:
         debug=False,
         bootloader_ignore_signals=False,
         strip=False,
-        upx=True,
+        upx=False,    # UPX can strip icon resources from the PE on Windows
         upx_exclude=[],
         runtime_tmpdir=None,
         console=False,

data/catalog.json

@@ -0,0 +1,454 @@
+{
+  "schema": 1,
+  "version": 1,
+  "updated": "2026-07-12",
+  "signed_at": "2026-07-12T21:35:19Z",
+  "servers": [
+    {
+      "id": "filesystem",
+      "display": "Filesystem",
+      "description": "Lets Claude read, write, search, and edit files in directories you explicitly allow.",
+      "category": "files",
+      "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
+      "stars": 85995,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem@2026.7.10",
+          "<ALLOWED_DIR>"
+        ]
+      },
+      "placeholders": {
+        "<ALLOWED_DIR>": "Absolute path to a directory the server may read/write. Add more directories as additional args."
+      },
+      "env_required": {},
+      "docs_url": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
+      "notes": "Part of the official modelcontextprotocol/servers reference monorepo (star count is for the whole repo). Clients that support MCP 'roots' can also grant directories dynamically instead of via args.",
+      "last_release": "2026-07-10"
+    },
+    {
+      "id": "fetch",
+      "display": "Fetch",
+      "description": "Fetches a URL and converts the page to clean markdown so Claude can read web content.",
+      "category": "dev",
+      "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/fetch",
+      "stars": 85995,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "mcp-server-fetch@2026.7.10"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/modelcontextprotocol/servers/tree/main/src/fetch",
+      "notes": "Can access local/internal IPs, so treat as a mild security risk on untrusted networks. Add '--ignore-robots-txt' or '--user-agent=...' as extra args if needed.",
+      "last_release": "2026-07-10"
+    },
+    {
+      "id": "memory",
+      "display": "Memory",
+      "description": "Gives Claude a persistent knowledge-graph memory that survives across conversations.",
+      "category": "ai",
+      "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/memory",
+      "stars": 85995,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-memory@2026.7.4"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/modelcontextprotocol/servers/tree/main/src/memory",
+      "notes": "Stores entities/relations as a local JSON knowledge graph (path configurable via MEMORY_FILE_PATH env var).",
+      "last_release": "2026-07-04"
+    },
+    {
+      "id": "sequential-thinking",
+      "display": "Sequential Thinking",
+      "description": "Gives Claude a structured, step-by-step reasoning tool for breaking down complex problems.",
+      "category": "ai",
+      "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking",
+      "stars": 85995,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-sequential-thinking@2026.7.4"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking",
+      "notes": "Set DISABLE_THOUGHT_LOGGING=true to stop it from printing each thought step to the console.",
+      "last_release": "2026-07-04"
+    },
+    {
+      "id": "git",
+      "display": "Git",
+      "description": "Lets Claude read history, diff, branch, and search a local git repository.",
+      "category": "dev",
+      "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/git",
+      "stars": 85995,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "mcp-server-git@2026.7.10",
+          "--repository",
+          "<REPO_PATH>"
+        ]
+      },
+      "placeholders": {
+        "<REPO_PATH>": "Absolute path to the local git repository"
+      },
+      "env_required": {},
+      "docs_url": "https://github.com/modelcontextprotocol/servers/tree/main/src/git",
+      "notes": "Operates on a local checkout only; it does not talk to GitHub/GitLab APIs (pair with the GitHub or GitLab server for that).",
+      "last_release": "2026-07-10"
+    },
+    {
+      "id": "github",
+      "display": "GitHub",
+      "description": "Lets Claude read repos/code, and manage issues, pull requests, and Actions on GitHub.",
+      "category": "code-hosting",
+      "homepage": "https://github.com/github/github-mcp-server",
+      "stars": 30202,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "docker",
+        "args": [
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "GITHUB_PERSONAL_ACCESS_TOKEN",
+          "ghcr.io/github/github-mcp-server:v1.0.1"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+      },
+      "docs_url": "https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/README.md",
+      "notes": "The old '@modelcontextprotocol/server-github' npm package is discontinued (deprecated April 2025). GitHub now ships a Docker-based local server (requires Docker installed/running) plus a hosted remote server at https://api.githubcopilot.com/mcp/ that supports OAuth or PAT auth without Docker."
+    },
+    {
+      "id": "playwright",
+      "display": "Playwright",
+      "description": "Lets Claude drive a real browser (click, type, navigate, screenshot) using Playwright's accessibility-tree snapshots.",
+      "category": "browser",
+      "homepage": "https://github.com/microsoft/playwright-mcp",
+      "stars": 34000,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "@playwright/mcp@0.0.78"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/microsoft/playwright-mcp#readme",
+      "notes": "Maintained by the Playwright team at Microsoft. Add '--isolated' for a throwaway profile, or '--browser firefox|webkit|msedge' to change engine. A persistent browser profile is used by default so logins carry over between sessions.",
+      "last_release": "2026-07-09"
+    },
+    {
+      "id": "chrome-devtools",
+      "display": "Chrome DevTools",
+      "description": "Lets Claude control Chrome and use real DevTools features: performance traces, network inspection, console logs, screenshots.",
+      "category": "browser",
+      "homepage": "https://github.com/ChromeDevTools/chrome-devtools-mcp",
+      "stars": 45000,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "chrome-devtools-mcp@1.5.0"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme",
+      "notes": "Maintained by the Google Chrome DevTools team; only officially supports Google Chrome / Chrome for Testing. Exposes the browser's content to the MCP client, so avoid sensitive sites while connected. Add '--slim --headless' for a minimal 3-tool basic-automation mode.",
+      "last_release": "2026-07-03"
+    },
+    {
+      "id": "postgres",
+      "display": "Postgres MCP Pro",
+      "description": "Lets Claude query, inspect schema, and analyze/tune performance of a PostgreSQL database.",
+      "category": "database",
+      "homepage": "https://github.com/crystaldba/postgres-mcp",
+      "stars": 2400,
+      "official": false,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "postgres-mcp@0.3.0",
+          "--access-mode=restricted"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "DATABASE_URI": ""
+      },
+      "docs_url": "https://github.com/crystaldba/postgres-mcp#readme",
+      "notes": "The official reference Postgres server was archived by the MCP team; this community server (Crystal DBA) is the most capable/most-referenced replacement, adding index tuning and EXPLAIN-plan analysis. Use --access-mode=restricted for read-only/production use. Docker image also available (crystaldba/postgres-mcp). Catalog ships --access-mode=restricted (read-only); switch to unrestricted yourself if you want writes.",
+      "last_release": "2025-05-16"
+    },
+    {
+      "id": "n8n",
+      "display": "n8n",
+      "description": "Build, validate, and deploy n8n workflows with full node documentation for the AI.",
+      "category": "infra",
+      "homepage": "https://github.com/czlonkowski/n8n-mcp",
+      "stars": 22257,
+      "official": false,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "n8n-mcp@2.63.2"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "MCP_MODE": "",
+        "N8N_API_URL": "",
+        "N8N_API_KEY": ""
+      },
+      "docs_url": "https://github.com/czlonkowski/n8n-mcp",
+      "notes": "Set MCP_MODE=stdio (required for Claude Desktop, prevents debug logs from breaking the protocol). N8N_API_URL/N8N_API_KEY are optional — without them you still get full node documentation, validation, and template search; with them you get live workflow create/update/execute against your own n8n instance. A hosted free-tier alternative exists at dashboard.n8n-mcp.com.",
+      "last_release": "2026-07-09"
+    },
+    {
+      "id": "notion",
+      "display": "Notion",
+      "description": "Read, search, and edit Notion pages, databases, and comments from your AI assistant.",
+      "category": "productivity",
+      "homepage": "https://github.com/makenotion/notion-mcp-server",
+      "stars": 4400,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@notionhq/notion-mcp-server@2.4.1"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "NOTION_TOKEN": ""
+      },
+      "docs_url": "https://developers.notion.com/docs/mcp",
+      "notes": "Notion is prioritizing its hosted remote MCP (OAuth, https://mcp.notion.com/mcp) and may eventually sunset this local package, but the stdio server still works today and is the simplest way to get a static config with an internal-integration token.",
+      "last_release": "2026-06-22"
+    },
+    {
+      "id": "obsidian",
+      "display": "Obsidian",
+      "description": "Read, search, and edit notes in your Obsidian vault.",
+      "category": "personal",
+      "homepage": "https://github.com/MarkusPfundstein/mcp-obsidian",
+      "stars": 4067,
+      "official": false,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "mcp-obsidian@0.2.2"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "OBSIDIAN_API_KEY": "",
+        "OBSIDIAN_HOST": "",
+        "OBSIDIAN_PORT": ""
+      },
+      "docs_url": "https://github.com/MarkusPfundstein/mcp-obsidian",
+      "notes": "Requires the Obsidian Local REST API community plugin installed and enabled in Obsidian; copy the API key from the plugin settings. OBSIDIAN_HOST defaults to 127.0.0.1 and OBSIDIAN_PORT to 27124 if omitted.",
+      "last_release": "2025-04-01"
+    },
+    {
+      "id": "brave-search",
+      "display": "Brave Search",
+      "description": "Search the web, news, images, and videos using Brave's independent search index.",
+      "category": "search",
+      "homepage": "https://github.com/brave/brave-search-mcp-server",
+      "stars": 1288,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@brave/brave-search-mcp-server@2.0.85",
+          "--transport",
+          "stdio"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "BRAVE_API_KEY": ""
+      },
+      "docs_url": "https://github.com/brave/brave-search-mcp-server",
+      "notes": "Official Brave server; replaced the old archived modelcontextprotocol/servers brave-search entry (now in modelcontextprotocol/servers-archived). Get an API key from the Brave Search API dashboard.",
+      "last_release": "2026-06-15"
+    },
+    {
+      "id": "tavily",
+      "display": "Tavily",
+      "description": "AI-optimized web search, extract, map, and crawl API built for LLM agents.",
+      "category": "search",
+      "homepage": "https://github.com/tavily-ai/tavily-mcp",
+      "stars": 2206,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "tavily-mcp@0.2.21"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "TAVILY_API_KEY": ""
+      },
+      "docs_url": "https://github.com/tavily-ai/tavily-mcp",
+      "notes": "Tavily also offers a hosted remote MCP endpoint (mcp.tavily.com) with OAuth as an alternative to running the local npx server.",
+      "last_release": "2026-07-10"
+    },
+    {
+      "id": "home-assistant",
+      "display": "Home Assistant",
+      "description": "Control smart home devices, query states, and troubleshoot automations in Home Assistant.",
+      "category": "smart-home",
+      "homepage": "https://github.com/voska/hass-mcp",
+      "stars": 308,
+      "official": false,
+      "setup": "basic",
+      "config": {
+        "command": "docker",
+        "args": [
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "HA_URL",
+          "-e",
+          "HA_TOKEN",
+          "voska/hass-mcp:0.5.0"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {
+        "HA_URL": "",
+        "HA_TOKEN": ""
+      },
+      "docs_url": "https://github.com/voska/hass-mcp",
+      "notes": "HA_URL example: http://homeassistant.local:8123 (use http://host.docker.internal:8123 if HA runs in Docker on the same machine). HA_TOKEN is a Home Assistant long-lived access token from your profile page. A more actively developed alternative is the community 'HA-MCP' integration (homeassistant-ai/ha-mcp, ~3.9k stars), but it installs inside Home Assistant itself via HACS rather than as an external stdio process, so it doesn't fit this catalog's launch-line format."
+    },
+    {
+      "id": "kubernetes",
+      "display": "Kubernetes",
+      "description": "Lets Claude inspect and manage Kubernetes/OpenShift resources — pods, deployments, logs, Helm releases — using your local kubeconfig.",
+      "category": "infra",
+      "homepage": "https://github.com/containers/kubernetes-mcp-server",
+      "stars": 1626,
+      "official": false,
+      "setup": "basic",
+      "config": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "kubernetes-mcp-server@0.0.64"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://github.com/containers/kubernetes-mcp-server#readme",
+      "notes": "Not an official Kubernetes SIG project, but a Go-native (no kubectl dependency) implementation maintained under the 'containers' GitHub org (Podman/Red Hat-adjacent) that's widely regarded as the most capable K8s MCP server, supporting Kubernetes and OpenShift. Uses your existing ~/.kube/config automatically; add --read-only to prevent writes.",
+      "last_release": "2026-07-10"
+    },
+    {
+      "id": "aws-api-mcp-server",
+      "display": "AWS API MCP Server (AWS Labs)",
+      "description": "Lets your AI assistant run AWS CLI commands to inspect and manage AWS resources across virtually every AWS service.",
+      "category": "cloud",
+      "homepage": "https://github.com/awslabs/mcp",
+      "stars": 9431,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "awslabs.aws-api-mcp-server@1.3.46"
+        ]
+      },
+      "placeholders": {},
+      "env_required": {},
+      "docs_url": "https://awslabs.github.io/mcp/servers/aws-api-mcp-server",
+      "notes": "AWS credentials are NOT set in this MCP config — configure them beforehand via `aws configure` (or set AWS_API_MCP_PROFILE_NAME to pick a named profile) so boto3's standard credential chain can find them. Optional env vars: AWS_REGION (default us-east-1), READ_OPERATIONS_ONLY=true to block all mutating AWS calls. AWS notes this server is being superseded by a newer unified AWS MCP server referenced in their agent-toolkit docs.",
+      "last_release": "2026-06-25"
+    },
+    {
+      "id": "grafana",
+      "display": "Grafana",
+      "description": "Query dashboards, datasources, alerts and incidents in Grafana from your AI assistant.",
+      "category": "observability",
+      "homepage": "https://github.com/grafana/mcp-grafana",
+      "stars": 3227,
+      "official": true,
+      "setup": "basic",
+      "config": {
+        "command": "uvx",
+        "args": [
+          "mcp-grafana@0.17.1"
+        ],
+        "env": {
+          "GRAFANA_URL": "<GRAFANA_URL>"
+        }
+      },
+      "placeholders": {
+        "<GRAFANA_URL>": "Your Grafana instance URL, e.g. http://localhost:3000 or https://yourstack.grafana.net"
+      },
+      "env_required": {
+        "GRAFANA_SERVICE_ACCOUNT_TOKEN": ""
+      },
+      "docs_url": "https://grafana.com/docs/grafana/latest/developer-resources/mcp/",
+      "notes": "Requires Grafana 9.0+ for full functionality — datasource-related tools may not work correctly on older versions.",
+      "last_release": "2026-07-07"
+    },
+    {
+      "id": "slack",
+      "display": "Slack",
+      "description": "Search Slack messages, files, and members, and send messages or manage channels from your AI assistant.",
+      "category": "communication",
+      "homepage": "https://slack.com/help/articles/48855576908307-Guide-to-the-Slack-MCP-server",
+      "stars": null,
+      "official": true,
+      "setup": "link-only",
+      "env_required": {},
+      "docs_url": "https://docs.slack.dev/changelog/2026/02/17/slack-mcp/",
+      "notes": "Slack's own MCP server went GA Feb 17, 2026 (streamable HTTP at https://mcp.slack.com/mcp, OAuth). No stdio one-liner is published because it's a hosted, permissioned connector. A well-known community alternative, korotovsky/slack-mcp-server (~1.6k GitHub stars, MIT, not an official Slack product), supports stdio/SSE/HTTP with bot or browser-session tokens and no app-install requirement if a stdio option is preferred."
+    }
+  ]
+}

pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "better-claude-config"
+version = "1.3.0"
+description = "Cross-platform GUI for editing the mcpServers block of Claude Desktop and Claude Code configs"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "PySide6>=6.6",
+    "cryptography>=42.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "pre-commit>=3.5",
+]
+build = [
+    "pyinstaller>=6.0",
+    "pillow>=10.0",
+]
+
+[project.urls]
+Repository = "https://git.avezzano.io/the_og/better-claude-config"
+
+# ---------------------------------------------------------------------------
+# Tooling
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501",   # line length handled pragmatically; GUI strings run long
+    "SIM108", # ternary rewrites hurt readability in places
+    "RUF001", # UI strings intentionally use typographic glyphs (−, →, ↳)
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"bcc.py" = ["F405", "F403"]  # Qt star-import style if ever used

requirements-dev.txt

@@ -4,3 +4,8 @@ PySide6>=6.6
 # Build / packaging
 pyinstaller>=6.0
 pillow>=10.0        # generates icons/app.ico during CI (Windows build)
+
+# Test / lint
+pytest>=8.0
+ruff>=0.6
+cryptography>=42.0   # release checksum signing (scripts/sign_checksums.py)

scripts/build_icons.py

@@ -10,13 +10,11 @@ Requirements:
     pip install pillow          # for .ico
     iconutil                   # built into macOS; for .icns
 """
+
 from __future__ import annotations
 
-import os
-import platform
 import shutil
 import subprocess
-import sys
 import tempfile
 from pathlib import Path
 
@@ -32,22 +30,83 @@ def build_ico():
         print("Pillow not installed — skipping .ico generation (pip install pillow)")
         return
 
-    sizes = [16, 32, 48, 64, 128, 256]
+    import io
-    imgs = []
+    import struct
+
+    sizes = [16, 24, 32, 48, 64, 128, 256]
+    images: list[tuple[int, object]] = []
     for s in sizes:
         p = SRC / f"icon-{s}.png"
         if not p.exists():
             print(f"  Missing {p.name}, skipping")
             continue
-        imgs.append(Image.open(p).convert("RGBA"))
+        images.append((s, Image.open(p).convert("RGBA")))
 
-    if not imgs:
+    if not images:
         print("  No source PNGs found — cannot build .ico")
         return
 
+    # Write the ICO manually so that entries ≤ 128 px use uncompressed BMP DIB
+    # and the 256 px entry uses PNG.  Pillow's ICO saver stores all sizes as
+    # PNG-compressed ("Vista icon" format), which PyInstaller's Windows
+    # resource-updater cannot embed — it silently falls back to its default icon.
+
+    def bmp_dib(img: object) -> bytes:
+        """Return a BMP DIB (BITMAPINFOHEADER + BGRA rows + AND mask)."""
+        w, h = img.size
+        # biHeight is doubled: top half = XOR mask (color), bottom = AND mask
+        hdr = struct.pack(
+            "<IiiHHIIiiII",
+            40,  # biSize
+            w,
+            h * 2,  # biHeight (doubled per ICO convention)
+            1,  # biPlanes
+            32,  # biBitCount
+            0,  # biCompression (BI_RGB)
+            0,  # biSizeImage (0 ok for BI_RGB)
+            0,
+            0,
+            0,
+            0,
+        )
+        pix = img.load()
+        rows = bytearray()
+        for y in range(h - 1, -1, -1):  # bottom-up
+            for x in range(w):
+                r, g, b, a = pix[x, y]
+                rows += bytes([b, g, r, a])
+        # AND mask: 1 bit/pixel, rows padded to 32-bit boundary, all 0 (use alpha)
+        mask_row = ((w + 31) // 32) * 4
+        and_mask = bytes(mask_row * h)
+        return hdr + bytes(rows) + and_mask
+
+    def png_bytes(img: object) -> bytes:
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+
+    blobs: list[tuple[int, bytes]] = []
+    for s, img in images:
+        blobs.append((s, bmp_dib(img) if s < 256 else png_bytes(img)))
+
+    n = len(blobs)
+    dir_offset = 6 + n * 16  # ICONDIR (6) + n × ICONDIRENTRY (16)
+
+    out = bytearray()
+    out += struct.pack("<HHH", 0, 1, n)  # ICONDIR
+
+    cur = dir_offset
+    for s, blob in blobs:
+        w = h = s % 256  # 256 is stored as 0 in the byte field
+        out += struct.pack("<BBBBHHII", w, h, 0, 0, 1, 32, len(blob), cur)
+        cur += len(blob)
+
+    for _, blob in blobs:
+        out += blob
+
     dest = OUT / "app.ico"
-    imgs[-1].save(dest, format="ICO", append_images=imgs[:-1])
+    dest.write_bytes(out)
-    print(f"  Generated {dest.relative_to(ROOT)}  ({dest.stat().st_size // 1024 + 1} KB)")
+    print(f"  Generated {dest.relative_to(ROOT)}  ({len(out) // 1024 + 1} KB)")
 
 
 def build_icns():

scripts/sign_checksums.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""
+Generate a SHA256SUMS file for release artifacts and sign it with Ed25519.
+
+BCC ships PyInstaller binaries that are not code-signed (no budget for a
+macOS Developer ID / Windows Authenticode certificate). This script provides
+the free half of supply-chain integrity: a checksum manifest, detached-signed
+so downloaders can verify the file they got is the file we published.
+
+This does NOT remove Gatekeeper/SmartScreen warnings and does NOT prove the
+binary is safe to run -- only that it matches what the release signing key
+attested to.
+
+Usage:
+    # Hash every file in a directory into a SHA256SUMS-format manifest.
+    python scripts/sign_checksums.py generate <dir> --out SHA256SUMS
+
+    # Sign a manifest, producing a detached signature.
+    # Private key comes from $RELEASE_SIGNING_KEY (base64 raw Ed25519 seed)
+    # unless --key-b64 is given explicitly (mostly for tests).
+    python scripts/sign_checksums.py sign --sums SHA256SUMS --out SHA256SUMS.sig
+
+    # Verify a manifest against a detached signature and a public key.
+    python scripts/sign_checksums.py verify --sums SHA256SUMS --sig SHA256SUMS.sig \
+        --pubkey-b64 <base64 raw Ed25519 public key>
+
+The private key is generated and rotated via the Catalog Console (#62) --
+this script never generates or stores a key itself.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import os
+import sys
+from pathlib import Path
+
+# Domain separation prefix: ties every signature to "a BCC release checksum
+# manifest" so a signature can never be replayed against an unrelated
+# message signed by the same key.
+DOMAIN_PREFIX = b"bcc-release-v1|"
+
+CHUNK_SIZE = 1024 * 1024
+
+
+def sha256_file(path: Path) -> str:
+    """Return the lowercase hex SHA-256 digest of a file's contents."""
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        while chunk := fh.read(CHUNK_SIZE):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_checksums_text(files: dict[str, str]) -> str:
+    """Build a sha256sum(1)-compatible manifest body.
+
+    `files` maps filename -> hex digest. Entries are sorted by filename for
+    a deterministic, diffable output. Format matches `sha256sum` exactly:
+    "<hash>  <filename>\n" (two spaces, no path components).
+    """
+    lines = [f"{digest}  {name}" for name, digest in sorted(files.items())]
+    body = "\n".join(lines)
+    return body + "\n" if body else ""
+
+
+def generate_checksums(directory: Path, *, exclude: set[str] | None = None) -> str:
+    """Hash every regular file directly inside `directory` (non-recursive)
+    and return the SHA256SUMS text. Filenames are recorded without any
+    directory prefix so the manifest can be verified from inside the
+    directory it describes.
+    """
+    exclude = exclude or set()
+    files: dict[str, str] = {}
+    for entry in sorted(directory.iterdir()):
+        if not entry.is_file():
+            continue
+        if entry.name in exclude:
+            continue
+        files[entry.name] = sha256_file(entry)
+    return build_checksums_text(files)
+
+
+def _signing_message(sums_text: str) -> bytes:
+    """The exact bytes that get signed: the domain prefix followed by the
+    raw bytes of the SHA256SUMS file content."""
+    return DOMAIN_PREFIX + sums_text.encode("utf-8")
+
+
+def sign_checksums(seed_b64: str, sums_text: str) -> bytes:
+    """Sign `sums_text` with the Ed25519 private key encoded (base64, raw
+    32-byte seed) in `seed_b64`. Returns the raw 64-byte signature."""
+    # Imported lazily so `generate` mode (used on every CI run) never
+    # requires the `cryptography` package to be installed.
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    seed = base64.b64decode(seed_b64)
+    if len(seed) != 32:
+        raise ValueError(f"expected a 32-byte raw Ed25519 seed, got {len(seed)} bytes")
+    private_key = Ed25519PrivateKey.from_private_bytes(seed)
+    return private_key.sign(_signing_message(sums_text))
+
+
+def verify_checksums(pubkey_b64: str, sums_text: str, signature: bytes) -> bool:
+    """Verify `signature` over `sums_text` against the base64-encoded raw
+    32-byte Ed25519 public key. Returns True/False; never raises for a bad
+    signature (only for malformed inputs)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    pubkey_bytes = base64.b64decode(pubkey_b64)
+    if len(pubkey_bytes) != 32:
+        raise ValueError(
+            f"expected a 32-byte raw Ed25519 public key, got {len(pubkey_bytes)} bytes"
+        )
+    public_key = Ed25519PublicKey.from_public_bytes(pubkey_bytes)
+    try:
+        public_key.verify(signature, _signing_message(sums_text))
+        return True
+    except InvalidSignature:
+        return False
+
+
+def public_key_b64_from_seed(seed_b64: str) -> str:
+    """Derive the base64 raw public key from a base64 raw seed. Handy for
+    local key-pair sanity checks; not used by the release workflow."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    seed = base64.b64decode(seed_b64)
+    private_key = Ed25519PrivateKey.from_private_bytes(seed)
+    raw = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return base64.b64encode(raw).decode("ascii")
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+def _cmd_generate(args: argparse.Namespace) -> int:
+    directory = Path(args.directory)
+    exclude = {"SHA256SUMS", "SHA256SUMS.sig"}
+    text = generate_checksums(directory, exclude=exclude)
+    out_path = Path(args.out)
+    out_path.write_text(text, encoding="utf-8")
+    print(f"Wrote {out_path} ({len(text.splitlines())} entries)")
+    return 0
+
+
+def _cmd_sign(args: argparse.Namespace) -> int:
+    seed_b64 = args.key_b64 or os.environ.get(args.key_env, "")
+    if not seed_b64:
+        print(
+            f"error: no signing key provided (checked --key-b64 and ${args.key_env})",
+            file=sys.stderr,
+        )
+        return 1
+    sums_text = Path(args.sums).read_text(encoding="utf-8")
+    signature = sign_checksums(seed_b64, sums_text)
+    Path(args.out).write_bytes(signature)
+    print(f"Wrote {args.out} ({len(signature)} bytes)")
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    pubkey_b64 = args.pubkey_b64 or os.environ.get(args.pubkey_env, "")
+    if not pubkey_b64:
+        print(
+            f"error: no public key provided (checked --pubkey-b64 and ${args.pubkey_env})",
+            file=sys.stderr,
+        )
+        return 1
+    sums_text = Path(args.sums).read_text(encoding="utf-8")
+    signature = Path(args.sig).read_bytes()
+    ok = verify_checksums(pubkey_b64, sums_text, signature)
+    if ok:
+        print("OK: signature is valid")
+        return 0
+    print("FAILED: signature is invalid", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    p_gen = sub.add_parser(
+        "generate", help="hash every file in a directory into a SHA256SUMS manifest"
+    )
+    p_gen.add_argument("directory", help="directory whose files should be hashed (non-recursive)")
+    p_gen.add_argument("--out", required=True, help="path to write the SHA256SUMS manifest to")
+    p_gen.set_defaults(func=_cmd_generate)
+
+    p_sign = sub.add_parser("sign", help="detached-sign a SHA256SUMS manifest with Ed25519")
+    p_sign.add_argument("--sums", required=True, help="path to the SHA256SUMS manifest to sign")
+    p_sign.add_argument("--out", required=True, help="path to write the detached signature to")
+    p_sign.add_argument(
+        "--key-b64", default=None, help="base64 raw Ed25519 seed (overrides --key-env)"
+    )
+    p_sign.add_argument(
+        "--key-env",
+        default="RELEASE_SIGNING_KEY",
+        help="environment variable holding the base64 seed (default: RELEASE_SIGNING_KEY)",
+    )
+    p_sign.set_defaults(func=_cmd_sign)
+
+    p_verify = sub.add_parser(
+        "verify", help="verify a SHA256SUMS manifest against a detached signature"
+    )
+    p_verify.add_argument("--sums", required=True, help="path to the SHA256SUMS manifest")
+    p_verify.add_argument("--sig", required=True, help="path to the detached signature")
+    p_verify.add_argument(
+        "--pubkey-b64", default=None, help="base64 raw Ed25519 public key (overrides --pubkey-env)"
+    )
+    p_verify.add_argument(
+        "--pubkey-env",
+        default="RELEASE_SIGNING_PUBKEY",
+        help="environment variable holding the base64 public key (default: RELEASE_SIGNING_PUBKEY)",
+    )
+    p_verify.set_defaults(func=_cmd_verify)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

test_core.py

@@ -1,92 +0,0 @@
-import json, tempfile, shutil
-from pathlib import Path
-import bcc_core as c
-
-tmp = Path(tempfile.mkdtemp())
-ok = []
-
-def check(name, cond):
-    ok.append(cond)
-    print(("PASS" if cond else "FAIL"), "-", name)
-
-# ---- 1. discovery (monkeypatch the base dir) ----
-base = tmp / "AppSupport"
-for d in ("Claude", "Claude-Work", "NotClaude"):
-    (base / d).mkdir(parents=True)
-(base / "Claude" / c.CONFIG_FILENAME).write_text("{}")
-# Claude-Work has no config yet; NotClaude shouldn't match
-c.app_support_base = lambda: base
-profs = c.discover_profiles()
-labels = sorted(p.label for p in profs)
-check("discovers Claude + Claude-Work, not NotClaude",
-      "Claude" in labels and "Claude-Work" in labels and "NotClaude" not in labels)
-check("flags missing config file", any(p.label=="Claude-Work" and not p.config_exists for p in profs))
-
-# ---- 2. write preserves OTHER keys + order, only touches mcpServers ----
-cfgpath = tmp / "real.json"
-original = {
-    "globalShortcut": "Cmd+Shift+Space",
-    "mcpServers": {"old": {"command": "node", "args": ["x.js"]}},
-    "someOtherTool": {"keep": True},
-}
-cfgpath.write_text(json.dumps(original, indent=2))
-cfg = c.load_config(cfgpath)
-servers = c.extract_servers(cfg)
-# add a new one, disable the old one
-servers.append(c.ServerEntry("brave", {"command": "npx", "args": ["-y", "@x/brave"]}, True))
-servers[0].enabled = False
-c.apply_servers(cfg, servers)
-c.write_config(cfgpath, cfg)
-written = json.loads(cfgpath.read_text())
-keys = list(written.keys())
-check("preserved globalShortcut", written.get("globalShortcut") == "Cmd+Shift+Space")
-check("preserved someOtherTool", written.get("someOtherTool") == {"keep": True})
-check("disabled server parked in _disabledMcpServers", "old" in written.get("_disabledMcpServers", {}))
-check("enabled server in mcpServers", "brave" in written.get("mcpServers", {}))
-check("old not in active mcpServers", "old" not in written.get("mcpServers", {}))
-check("key order kept (globalShortcut before mcpServers)", keys.index("globalShortcut") < keys.index("mcpServers"))
-check("backup created", (cfgpath.parent / c.BACKUP_DIRNAME).is_dir() and any((cfgpath.parent / c.BACKUP_DIRNAME).iterdir()))
-
-# ---- 3. paste parser, all shapes ----
-full = '{"mcpServers": {"a": {"command": "node", "args": ["a.js"]}}}'
-check("parse full config shape", list(c.parse_pasted_json(full)) == ["a"])
-inner = '{"b": {"command": "uvx", "args": ["mcp-server-git"]}}'
-check("parse inner block shape", list(c.parse_pasted_json(inner)) == ["b"])
-bare = '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}'
-parsed = c.parse_pasted_json(bare)
-check("parse bare server + suggests name 'filesystem'", "filesystem" in parsed)
-remote = '{"url": "https://mcp.asana.com/sse"}'
-check("parse remote, suggests host name", "mcp" in c.parse_pasted_json(remote))
-try:
-    c.parse_pasted_json('{"junk": 5}')
-    check("rejects junk", False)
-except ValueError:
-    check("rejects junk", True)
-
-# ---- 4. validation ----
-bad = [c.ServerEntry("", {"command": "x"}, True),
-       c.ServerEntry("dup", {"command": "x"}, True),
-       c.ServerEntry("dup", {"command": "x"}, True),
-       c.ServerEntry("r", {"url": ""}, True),
-       c.ServerEntry("nocmd", {"command": ""}, True)]
-probs = c.validate_servers(bad)
-check("validation catches empty name", any("empty name" in p for p in probs))
-check("validation catches duplicate", any("Duplicate" in p for p in probs))
-check("validation catches missing url", any("no URL" in p for p in probs))
-check("validation catches missing command", any("no command" in p for p in probs))
-check("valid set passes clean", c.validate_servers([c.ServerEntry("good", {"command":"node"}, True)]) == [])
-
-# ---- 5. dependency check (python3 exists; bogusxyz does not) ----
-r_ok = c.check_dependency({"command": "python3"})
-check("dep check finds python3", r_ok["status"] == "ok")
-r_missing = c.check_dependency({"command": "definitely-not-real-binary-xyz"})
-check("dep check flags missing", r_missing["status"] == "missing")
-r_remote = c.check_dependency({"url": "https://example.com/mcp"})
-check("dep check marks remote", r_remote["status"] == "remote")
-# windows-style wrapper: cmd /c npx ...  -> should look past cmd to npx
-r_wrap = c.check_dependency({"command": "cmd", "args": ["/c", "definitely-not-real-xyz", "foo"]})
-check("dep check sees through shell wrapper", "definitely-not-real-xyz" in r_wrap["label"])
-
-print()
-print(f"{sum(ok)}/{len(ok)} passed")
-shutil.rmtree(tmp)

tests/test_checksums.py

@@ -0,0 +1,234 @@
+"""Tests for scripts/sign_checksums.py: SHA256SUMS generation and detached
+Ed25519 signing/verification for release artifacts."""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+import sign_checksums as sc
+
+cryptography = pytest.importorskip("cryptography")
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey  # noqa: E402
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat  # noqa: E402
+
+
+def _make_keypair() -> tuple[str, str]:
+    """Return (seed_b64, pubkey_b64) for a fresh Ed25519 keypair."""
+    private_key = Ed25519PrivateKey.generate()
+    seed = private_key.private_bytes_raw()
+    pubkey = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    return base64.b64encode(seed).decode("ascii"), base64.b64encode(pubkey).decode("ascii")
+
+
+# --------------------------------------------------------------------------- #
+# sha256_file / build_checksums_text / generate_checksums
+# --------------------------------------------------------------------------- #
+def test_sha256_file_matches_hashlib(tmp_path):
+    f = tmp_path / "a.txt"
+    f.write_bytes(b"hello world")
+    import hashlib
+
+    assert sc.sha256_file(f) == hashlib.sha256(b"hello world").hexdigest()
+
+
+def test_build_checksums_text_sorted_and_formatted():
+    files = {"zeta.zip": "aa" * 32, "alpha.zip": "bb" * 32}
+    text = sc.build_checksums_text(files)
+    lines = text.splitlines()
+    assert lines[0].endswith("alpha.zip")
+    assert lines[1].endswith("zeta.zip")
+    # Standard sha256sum format: hash, two spaces, filename.
+    assert lines[0] == f"{'bb' * 32}  alpha.zip"
+
+
+def test_build_checksums_text_empty():
+    assert sc.build_checksums_text({}) == ""
+
+
+def test_generate_checksums_from_directory(tmp_path):
+    (tmp_path / "b.bin").write_bytes(b"second")
+    (tmp_path / "a.bin").write_bytes(b"first")
+    (tmp_path / "subdir").mkdir()
+    (tmp_path / "subdir" / "ignored.bin").write_bytes(b"nested, not hashed")
+
+    text = sc.generate_checksums(tmp_path)
+    lines = text.splitlines()
+    assert len(lines) == 2
+    assert lines[0].endswith("a.bin")
+    assert lines[1].endswith("b.bin")
+    assert "subdir" not in text
+
+
+def test_generate_checksums_excludes_manifest_files(tmp_path):
+    (tmp_path / "archive.zip").write_bytes(b"payload")
+    (tmp_path / "SHA256SUMS").write_text("stale")
+    (tmp_path / "SHA256SUMS.sig").write_bytes(b"stale-sig")
+
+    text = sc.generate_checksums(tmp_path, exclude={"SHA256SUMS", "SHA256SUMS.sig"})
+    assert "archive.zip" in text
+    assert "SHA256SUMS" not in text.replace("archive.zip", "")
+
+
+# --------------------------------------------------------------------------- #
+# sign_checksums / verify_checksums
+# --------------------------------------------------------------------------- #
+def test_sign_then_verify_roundtrip():
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "deadbeef" * 8 + "  BetterClaudeConfig-Linux.tar.gz\n"
+
+    signature = sc.sign_checksums(seed_b64, sums_text)
+    assert len(signature) == 64
+    assert sc.verify_checksums(pubkey_b64, sums_text, signature) is True
+
+
+def test_verify_rejects_tampered_checksums():
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "aa" * 32 + "  file.zip\n"
+    signature = sc.sign_checksums(seed_b64, sums_text)
+
+    tampered = "bb" * 32 + "  file.zip\n"
+    assert sc.verify_checksums(pubkey_b64, tampered, signature) is False
+
+
+def test_verify_rejects_wrong_key():
+    seed_b64, _ = _make_keypair()
+    _, other_pubkey_b64 = _make_keypair()
+    sums_text = "cc" * 32 + "  file.zip\n"
+    signature = sc.sign_checksums(seed_b64, sums_text)
+
+    assert sc.verify_checksums(other_pubkey_b64, sums_text, signature) is False
+
+
+def test_domain_prefix_is_applied():
+    """The signed message must be prefixed, not the raw manifest bytes --
+    otherwise a signature over this manifest could be replayed as a
+    signature over an unrelated message with the same bytes elsewhere."""
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_text = "11" * 32 + "  file.zip\n"
+
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey as PK
+
+    seed = base64.b64decode(seed_b64)
+    raw_signature = PK.from_private_bytes(seed).sign(sums_text.encode("utf-8"))
+
+    # A signature over the raw (unprefixed) bytes must NOT verify via our
+    # domain-separated verify function.
+    assert sc.verify_checksums(pubkey_b64, sums_text, raw_signature) is False
+
+    # But our own sign_checksums() output does verify.
+    good_signature = sc.sign_checksums(seed_b64, sums_text)
+    assert sc.verify_checksums(pubkey_b64, sums_text, good_signature) is True
+
+
+def test_sign_checksums_rejects_bad_seed_length():
+    bad_seed_b64 = base64.b64encode(b"too-short").decode("ascii")
+    with pytest.raises(ValueError):
+        sc.sign_checksums(bad_seed_b64, "irrelevant\n")
+
+
+def test_verify_checksums_rejects_bad_pubkey_length():
+    seed_b64, _ = _make_keypair()
+    sig = sc.sign_checksums(seed_b64, "irrelevant\n")
+    bad_pubkey_b64 = base64.b64encode(b"too-short").decode("ascii")
+    with pytest.raises(ValueError):
+        sc.verify_checksums(bad_pubkey_b64, "irrelevant\n", sig)
+
+
+def test_public_key_b64_from_seed_matches_generated_pubkey():
+    seed_b64, pubkey_b64 = _make_keypair()
+    assert sc.public_key_b64_from_seed(seed_b64) == pubkey_b64
+
+
+# --------------------------------------------------------------------------- #
+# CLI (end-to-end, via subprocess so argparse wiring is exercised too)
+# --------------------------------------------------------------------------- #
+SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "sign_checksums.py"
+
+
+def _run(*args, env=None):
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), *args],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def test_cli_generate_sign_verify_roundtrip(tmp_path, monkeypatch):
+    seed_b64, pubkey_b64 = _make_keypair()
+
+    release_dir = tmp_path / "release-files"
+    release_dir.mkdir()
+    (release_dir / "BetterClaudeConfig-Linux.tar.gz").write_bytes(b"fake archive contents")
+    (release_dir / "BetterClaudeConfig-macOS.zip").write_bytes(b"fake zip contents")
+
+    sums_path = release_dir / "SHA256SUMS"
+    sig_path = release_dir / "SHA256SUMS.sig"
+
+    gen = _run("generate", str(release_dir), "--out", str(sums_path))
+    assert gen.returncode == 0, gen.stderr
+    assert sums_path.exists()
+    body = sums_path.read_text()
+    assert "BetterClaudeConfig-Linux.tar.gz" in body
+    assert "BetterClaudeConfig-macOS.zip" in body
+
+    sign = _run("sign", "--sums", str(sums_path), "--out", str(sig_path), "--key-b64", seed_b64)
+    assert sign.returncode == 0, sign.stderr
+    assert sig_path.exists()
+    assert sig_path.stat().st_size == 64
+
+    verify = _run(
+        "verify",
+        "--sums",
+        str(sums_path),
+        "--sig",
+        str(sig_path),
+        "--pubkey-b64",
+        pubkey_b64,
+    )
+    assert verify.returncode == 0, verify.stderr
+    assert "OK" in verify.stdout
+
+
+def test_cli_sign_without_key_fails_loudly(tmp_path):
+    sums_path = tmp_path / "SHA256SUMS"
+    sums_path.write_text("aa" * 32 + "  file.zip\n")
+    sig_path = tmp_path / "SHA256SUMS.sig"
+
+    import os
+
+    env = {k: v for k, v in os.environ.items() if k != "RELEASE_SIGNING_KEY"}
+    result = _run("sign", "--sums", str(sums_path), "--out", str(sig_path), env=env)
+
+    assert result.returncode != 0
+    assert not sig_path.exists(), "must never write a bogus/empty signature file"
+    assert "no signing key" in result.stderr.lower()
+
+
+def test_cli_verify_detects_tampering(tmp_path):
+    seed_b64, pubkey_b64 = _make_keypair()
+    sums_path = tmp_path / "SHA256SUMS"
+    sums_path.write_text("aa" * 32 + "  file.zip\n")
+    sig_path = tmp_path / "SHA256SUMS.sig"
+
+    _run("sign", "--sums", str(sums_path), "--out", str(sig_path), "--key-b64", seed_b64)
+
+    sums_path.write_text("bb" * 32 + "  file.zip\n")  # tamper after signing
+    verify = _run(
+        "verify",
+        "--sums",
+        str(sums_path),
+        "--sig",
+        str(sig_path),
+        "--pubkey-b64",
+        pubkey_b64,
+    )
+    assert verify.returncode != 0
+    assert "FAILED" in verify.stdout + verify.stderr

tests/test_json_repair.py

@@ -0,0 +1,253 @@
+"""Tests for the lenient JSON repair pipeline (repair_json_text +
+parse_pasted_json_verbose). Every case here is a shape people actually paste
+from MCP docs, blog posts, and chat windows."""
+
+import json
+
+import pytest
+
+import bcc_core as c
+
+GOOD = {"command": "npx", "args": ["-y", "@x/brave"]}
+
+
+def assert_brave(servers):
+    assert "brave" in servers
+    assert servers["brave"]["command"] == "npx"
+
+
+# --------------------------------------------------------------------------- #
+# Valid JSON passes through untouched
+# --------------------------------------------------------------------------- #
+def test_strict_json_no_notes():
+    servers, notes = c.parse_pasted_json_verbose('{"brave": {"command": "npx", "args": []}}')
+    assert_brave(servers)
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Markdown / prose wrappers
+# --------------------------------------------------------------------------- #
+def test_markdown_fence():
+    text = 'Add this to your config:\n```json\n{"brave": {"command": "npx"}}\n```\nThen restart.'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("fence" in n for n in notes)
+
+
+def test_fence_without_language_tag():
+    text = '```\n{"brave": {"command": "npx"}}\n```'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+
+
+def test_prose_around_bare_json():
+    text = 'Paste the following: {"brave": {"command": "npx"}} and restart Claude.'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("before" in n or "after" in n for n in notes)
+
+
+# --------------------------------------------------------------------------- #
+# Comments
+# --------------------------------------------------------------------------- #
+def test_line_comments():
+    text = '{\n  // the search server\n  "brave": {"command": "npx"}\n}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("//" in n for n in notes)
+
+
+def test_block_comments():
+    text = '{ /* config */ "brave": {"command": "npx"} }'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+
+
+def test_url_with_double_slash_is_not_a_comment():
+    text = '{"remote": {"url": "https://mcp.example.com/sse"}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert servers["remote"]["url"] == "https://mcp.example.com/sse"
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Commas
+# --------------------------------------------------------------------------- #
+def test_trailing_comma_object():
+    text = '{"brave": {"command": "npx", "args": ["-y"],},}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("trailing" in n for n in notes)
+
+
+def test_missing_comma_between_servers():
+    text = '{"brave": {"command": "npx"}\n"git": {"command": "uvx"}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert "brave" in servers and "git" in servers
+    assert any("missing comma" in n for n in notes)
+
+
+def test_missing_comma_between_string_fields():
+    text = '{"brave": {"command": "npx"\n"args": ["-y"]}}'
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["args"] == ["-y"]
+
+
+# --------------------------------------------------------------------------- #
+# Quotes
+# --------------------------------------------------------------------------- #
+def test_smart_quotes():
+    text = "{“brave”: {“command”: “npx”}}"
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("smart quotes" in n for n in notes)
+
+
+def test_single_quotes():
+    text = "{'brave': {'command': 'npx', 'args': ['-y']}}"
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("single-quoted" in n for n in notes)
+
+
+def test_single_quotes_with_inner_double():
+    text = """{'brave': {'command': 'npx', 'env': {'NOTE': 'say "hi"'}}}"""
+    servers, _ = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["env"]["NOTE"] == 'say "hi"'
+
+
+# --------------------------------------------------------------------------- #
+# JS-style laxness
+# --------------------------------------------------------------------------- #
+def test_unquoted_keys():
+    text = '{brave: {command: "npx", args: ["-y"]}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("bare object keys" in n for n in notes)
+
+
+def test_python_literals():
+    text = '{"brave": {"command": "npx", "enabled": True, "extra": None}}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert servers["brave"]["enabled"] is True
+    assert servers["brave"]["extra"] is None
+    assert any("literals" in n for n in notes)
+
+
+# --------------------------------------------------------------------------- #
+# Structure damage
+# --------------------------------------------------------------------------- #
+def test_braceless_fragment():
+    text = '"brave": {"command": "npx", "args": ["-y"]}'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("wrapped" in n for n in notes)
+
+
+def test_missing_closing_braces():
+    text = '{"mcpServers": {"brave": {"command": "npx", "args": ["-y"]'
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert any("unclosed" in n for n in notes)
+
+
+def test_kitchen_sink():
+    # fence + comment + single quotes + unquoted key + trailing comma + prose
+    text = (
+        "Here's the config you need:\n"
+        "```json\n"
+        "{\n"
+        "  // brave search\n"
+        "  brave: {\n"
+        "    'command': 'npx',\n"
+        "    'args': ['-y', '@x/brave',],\n"
+        "  },\n"
+        "}\n"
+        "```\n"
+    )
+    servers, notes = c.parse_pasted_json_verbose(text)
+    assert_brave(servers)
+    assert servers["brave"]["args"] == ["-y", "@x/brave"]
+    assert len(notes) >= 4
+
+
+# --------------------------------------------------------------------------- #
+# Suspicious-args detection (several argv tokens typed on one line)
+# --------------------------------------------------------------------------- #
+def test_split_flag_and_value_on_one_line():
+    fixed, notes = c.split_suspicious_args(["--directory /path/to/server", "run", "main.py"])
+    assert fixed == ["--directory", "/path/to/server", "run", "main.py"]
+    assert len(notes) == 1
+
+
+def test_split_full_option_string():
+    fixed, notes = c.split_suspicious_args(["-y @pkg/server --port 8080"])
+    assert fixed == ["-y", "@pkg/server", "--port", "8080"]
+    assert notes
+
+
+def test_split_respects_quotes():
+    fixed, _ = c.split_suspicious_args(['--name "My Server"'])
+    assert fixed == ["--name", "My Server"]
+
+
+def test_split_leaves_legit_spaces_alone():
+    args = ["/Users/me/My Documents", "hello world", "run"]
+    fixed, notes = c.split_suspicious_args(args)
+    assert fixed == args
+    assert notes == []
+
+
+def test_split_leaves_clean_args_alone():
+    args = ["--directory", "/path/to/server", "run", "main.py"]
+    fixed, notes = c.split_suspicious_args(args)
+    assert fixed == args
+    assert notes == []
+
+
+# --------------------------------------------------------------------------- #
+# Config-file repair (load-time)
+# --------------------------------------------------------------------------- #
+def test_repair_config_file_fixes_and_reports(tmp_path):
+    p = tmp_path / "claude_desktop_config.json"
+    p.write_text(
+        '{\n  "globalShortcut": "Cmd+Space",\n'
+        "  // my servers\n"
+        '  "mcpServers": {\n'
+        '    "brave": {"command": "npx", "args": ["-y"],},\n'
+        "  },\n}"
+    )
+    cfg, notes, preview = c.repair_config_file(p)
+    assert cfg["mcpServers"]["brave"]["command"] == "npx"
+    assert cfg["globalShortcut"] == "Cmd+Space"  # unrelated keys survive
+    assert any("comment" in n for n in notes)
+    assert any("trailing" in n for n in notes)
+    assert json.loads(preview) == cfg
+    # nothing was written to disk
+    assert "//" in p.read_text()
+
+
+def test_repair_config_file_hopeless_raises(tmp_path):
+    p = tmp_path / "claude_desktop_config.json"
+    p.write_text("total nonsense, no braces at all")
+    with pytest.raises(ValueError):
+        c.repair_config_file(p)
+
+
+# --------------------------------------------------------------------------- #
+# Still fails cleanly on hopeless input
+# --------------------------------------------------------------------------- #
+def test_hopeless_input_raises_value_error():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose("this is just prose with no json at all")
+
+
+def test_junk_object_still_rejected():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose('{"junk": 5}')
+
+
+def test_empty_raises():
+    with pytest.raises(ValueError):
+        c.parse_pasted_json_verbose("   ")