feat(catalog-console): a keys status command, and complete rotation without a red main (#62 , #68 )

Two problems from issue #68's follow-up review: 1. The maintainer -- the only person who will ever use this tool -- cannot reliably tell which of the two signing keys is which or what state either is in. He already pasted a private key into a chat window because a prompt was ambiguous. That's a defect in this tool, not user error. 2. PR #71 rotates bcc_core.CATALOG_PUBKEYS, which makes data/catalog.json.sig (signed by the retired key) stop verifying and the CI catalog-signature job go red. The Console could previously only load/sign against `main`, so the only way through was to merge a red PR and fix main afterwards -- normalizing exactly the alarm fatigue this whole design exists to prevent. Task 1 -- `python catalog_console.py keys`: A plain-English-first status report for BOTH keys: purpose, where the private half lives, whether it exists locally, its fingerprint, whether that fingerprint matches every place its public half is expected to be committed (bcc_core.CATALOG_PUBKEYS, ci.yml's trust anchor, and scripts/sign_checksums.RELEASE_PUBKEYS -- checked independently, since issue #68 finding 4 was exactly bcc_core.py and ci.yml silently drifting apart), and whether data/catalog.json.sig currently verifies -- ending with the exact command to run next. Needs no passphrase and never touches private key bytes: a plaintext public-key cache (store_public_key/load_public_key) is written alongside the existing encrypted private blob at keygen time, precisely so this command can report a fingerprint without decrypting anything. The status/report logic (key_status, render_key_status_report, recommend_next_steps, fingerprint_pubkey, extract_pubkey_list_literal, extract_ci_trust_anchor_pubkey) is pure and lives in catalog_review.py; cmd_keys in catalog_console.py is a thin printer over it, per the project's existing pure-core/thin-GUI split. Task 2 -- rotation completable without a red main: ReviewWindow now offers a "current branch" source (auto-detected via `current_branch()`, or --ref to name one explicitly) alongside "main" and open PRs. Loading it runs the exact same diff-against-last-signed / rotation-detection logic "main" always used (_load_own_ref, extracted from the old hardcoded-to-main _on_load), just parameterized on the ref. Signing now pushes to session.loaded_ref, never a hardcoded "main" (commit_and_push_signed_catalog's branch param was already there -- only the call site was wrong). The ref-list computation itself is a pure function (compute_own_refs) so this seam is unit-testable without git or Qt. None of can_sign()'s guards (empty-diff, acknowledge-all, blocking-risk, TOCTOU) were touched. This lets a rotation branch be reviewed, re-attested (every entry, since the new key never vouched for any of them -- issue #68 finding 5 follow-up), signed, and pushed to ITS OWN branch before it's ever merged. Task 3 -- label the keys everywhere: PassphraseDialog now shows which key (CATALOG vs RELEASE) and its fingerprint before the passphrase field, both in its window title and its prompt text -- the exact ambiguity that led to a private key being pasted into a chat window. cmd_keygen's stored-key confirmation now reads "CATALOG private key encrypted..." / "RELEASE private key encrypted..." instead of a capitalized-lowercase kind. The reattest banner now says "CATALOG signing key" / "CATALOG key" throughout instead of "the key". PySide6's import is now guarded (try/except -> _PYSIDE6_AVAILABLE) and every GUI class definition that depends on it moved under `if _PYSIDE6_AVAILABLE:`. `keygen`, `show-seed-b64`, and the new `keys` command have no GUI dependency and now work (and are testable) in an environment without PySide6 -- which is exactly this repo's own `test` CI job (pytest + cryptography only, no PySide6). `gui` fails with a clear message instead of an ImportError stack trace if it's missing. Tests: 26 new pure-function tests in tests/test_catalog_review.py (fingerprint_pubkey, extract_pubkey_list_literal, extract_ci_trust_anchor_pubkey, key_status, recommend_next_steps, render_key_status_report) and a new tests/test_catalog_console_git.py (14 tests) covering compute_own_refs, current_branch, commit_and_push_signed_catalog's branch targeting, and catalog_sig_status_on_disk against real local git repos -- importing catalog_console.py directly, proving it works without PySide6. 400 passed, 1 skipped (pre-existing). ruff check / ruff format --check clean.
chore(#68 ): rotate signing keys, key-rotation re-attestation mode, harden show-seed-b64
2026-07-13 13:10:36 -04:00 · 2026-07-13 12:24:28 -04:00
11 changed files with 1748 additions and 1320 deletions
@@ -120,7 +120,7 @@ jobs:
      # below to the new key's base64 form, as its own reviewed change.
      - name: Verify data/catalog.json.sig
        env:
-          EXPECTED_CATALOG_PUBKEY_B64: "082NOwVB7uURkvfyS3+knJ+40Fk6C9unsF47+2uPKo4="
+          EXPECTED_CATALOG_PUBKEY_B64: "0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k="
        run: |
          python - <<'PY'
          import base64, os, pathlib, sys
@@ -90,6 +90,21 @@ key, because they protect different things and live in different places:
 | Generated with | `python catalog_console.py keygen` | `python catalog_console.py keygen --release` |
 | Exported for CI with | *(never — there is no supported way to export this key)* | `python catalog_console.py show-seed-b64 --release` |

+**Confused about which key is which, or what state either is in?** Run:
+
+```bash
+python catalog_console.py keys
+```
+
+It needs no passphrase (it never touches private key bytes) and prints a
+plain-English report for both keys: where each private half lives, whether
+it's present on this machine, its fingerprint, whether that fingerprint
+matches what's actually committed in `bcc_core.py`, `ci.yml`'s trust
+anchor, and `scripts/sign_checksums.py`, and whether
+`data/catalog.json.sig` currently verifies — ending with the exact command
+to run next for whatever state it finds. This is the check that would have
+caught [issue #68](../../issues/68)'s finding 5 incident before it happened.
+
 **Why two keys:** the catalog key is the root of trust for what BCC
 actually *executes* on a user's machine — every `command`/`args` pair in
 the shipped catalog is only there because this key signed it. If that key
@@ -110,12 +125,29 @@ refuses to run without `--release` specifically so the catalog seed can't
 be exported by habit or muscle memory.

 **Release signing public key** (Ed25519, base64, raw 32 bytes) — this is
-the RELEASE key, not the catalog key:
+the RELEASE key, which signs `SHA256SUMS` (release checksums). It does
+**not** sign `data/catalog.json` and is not the key `bcc_core.CATALOG_PUBKEYS`
+trusts:

 ```
-<PLACEHOLDER — AJ: paste the release public key from `catalog_console.py keygen --release` here>
+6BnPgJEHJFyVltFoLTCNadIsehjy00iiW8IRlC1TfhA=
 ```

+The catalog public key (Ed25519, base64, raw 32 bytes) — this is the key
+that signs `data/catalog.json` and is trusted via `bcc_core.CATALOG_PUBKEYS`
+and the CI trust anchor in `.github/workflows/ci.yml`. It is listed here
+for completeness, not because you need it to verify a download — use the
+*release* key above for that:
+
+```
+0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k=
+```
+
+Both keys above were rotated 2026-07 — see [issue #68](../../issues/68)
+finding 5. The prior (shared) key is retired and is deliberately **not**
+kept in either trust list; retaining a burned key would defeat the point
+of rotating it.
+
 ## Run from source

 ```bash
@@ -190,7 +222,7 @@ file is also listed, marked *legacy*, so you can copy them over.
 - `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)).
- `catalog_console.py` / `catalog_review.py` — **maintainer-only**, never shipped to users (excluded from `bcc.spec`; see `tests/test_catalog_console_packaging.py`). The Catalog Console: review + sign `data/catalog.json`, and generate/manage both signing keys (`keygen`, `keygen --release`) — see [Signing keys](#signing-keys).
+- `catalog_console.py` / `catalog_review.py` — **maintainer-only**, never shipped to users (excluded from `bcc.spec`; see `tests/test_catalog_console_packaging.py`). The Catalog Console: review + sign `data/catalog.json` (against `main`, an open PR, or the branch you have checked out — `--ref <branch>` to be explicit, e.g. mid key-rotation, so a rotation can be signed and pushed to its own branch *before* it's merged, never forcing a red `main`), generate/manage both signing keys (`keygen`, `keygen --release`), and report on their status (`keys`, no passphrase needed) — see [Signing keys](#signing-keys).

 ## Building from source

@@ -10,7 +10,6 @@ Run:  python mcp_manager.py

 from __future__ import annotations

-import html
 import sys
 import time
 from pathlib import Path
@@ -27,12 +26,10 @@ from PySide6.QtGui import (
    QKeySequence,
    QPainter,
    QPixmap,
-    QTextCursor,
 )
 from PySide6.QtWidgets import (
    QAbstractItemView,
    QApplication,
-    QButtonGroup,
    QCheckBox,
    QComboBox,
    QDialog,
@@ -68,26 +65,6 @@ import bcc_core as core
 # thread during drag-and-drop import, so skip anything larger than this.
 MAX_DROP_IMPORT_BYTES = 5 * 1024 * 1024  # 5 MB

-
-def plain_label(text: object) -> QLabel:
-    """A QLabel guaranteed to render `text` as plain text, never HTML.
-
-    Qt's QLabel auto-interprets HTML by default (Qt.AutoText). Every catalog
-    entry field (description, notes, display name, urls -- and especially
-    args) is attacker-influenceable: catalog.json accepts community PRs, and
-    only a valid Ed25519 signature stands between a PR and what a user sees
-    here. A `<b>` or `<img onerror=...>` in a description must render as
-    visible text, not markup -- exactly the same reasoning catalog_console.py
-    documents for its own plain_label(). Every catalog-derived string shown
-    by the Browse dialog MUST go through this helper (or an inherently
-    plain-text widget like QPlainTextEdit) rather than a bare QLabel(...).
-    """
-    label = QLabel(html.escape(str(text)))
-    label.setTextFormat(Qt.TextFormat.PlainText)
-    label.setWordWrap(True)
-    return label
-
-
 # --- One-line rebrand: change this to recolor the whole app --------------- #
 ACCENT = "#f97316"  # warm orange
 ACCENT_DIM = "#c2570b"
@@ -699,39 +676,6 @@ class ServerEditor(QFrame):
    def current_name(self) -> str:
        return self.name.text().strip()

-    def focus_target(self, target: tuple[str, int | str] | None):
-        """
-        Focus the field a catalog Add left unfilled -- `target` is whatever
-        core.first_unfilled_focus_target() returned: ("args", line_index),
-        ("env", var_name), or None (nothing to fill, so do nothing).
-
-        Only meaningful on the stdio page, which is the only page a catalog
-        entry ever populates (link-only entries never reach dump_data()).
-        """
-        if not target or self.type.currentIndex() != 0:
-            return
-        kind, value = target
-        if kind == "args":
-            self.args.setFocus()
-            cursor = self.args.textCursor()
-            cursor.movePosition(QTextCursor.MoveOperation.Start)
-            cursor.movePosition(
-                QTextCursor.MoveOperation.Down, QTextCursor.MoveMode.MoveAnchor, int(value)
-            )
-            cursor.movePosition(
-                QTextCursor.MoveOperation.EndOfLine, QTextCursor.MoveMode.KeepAnchor
-            )
-            self.args.setTextCursor(cursor)
-        elif kind == "env":
-            for r in range(self.env.table.rowCount()):
-                key_item = self.env.table.item(r, 0)
-                if key_item and key_item.text() == value:
-                    self.env.table.setCurrentCell(r, 1)
-                    val_item = self.env.table.item(r, 1)
-                    if val_item:
-                        self.env.table.editItem(val_item)
-                    break
-
    def _type_switched(self):
        self.stack.setCurrentIndex(self.type.currentIndex())
        self._emit()
@@ -1260,262 +1204,6 @@ class PasteDialog(QDialog):
            self.err.setText(str(e))


-# --------------------------------------------------------------------------- #
-# Browse catalog dialog (issue #10 phase 2): search/filter the signed,
-# bundled server catalog and add a "basic" entry through the existing
-# paste/import path, or send a "link-only" entry to its setup docs.
-#
-# Every widget here that shows catalog-derived text uses plain_label() or an
-# inherently-plain widget (QPlainTextEdit) -- see plain_label()'s docstring.
-# The dialog itself does no signature/schema work: MainWindow hands it an
-# already-verified `entries` list (bcc_core.load_bundled_catalog_entries()),
-# and an empty list here means "show the empty state", never "fall back to
-# something less trusted".
-# --------------------------------------------------------------------------- #
-class BrowseCatalogDialog(QDialog):
-    def __init__(self, parent, entries: list[dict]):
-        super().__init__(parent)
-        self.setWindowTitle("Browse catalog")
-        self.resize(880, 560)
-        self.entries = entries or []
-        self.result_entry: dict | None = None
-        self._current_entry: dict | None = None
-        self._current_homepage: str | None = None
-        self._current_docs_url: str | None = None
-        self._current_group = "All"
-
-        outer = QVBoxLayout(self)
-
-        if not self.entries:
-            # Signature verification failed, or nothing was bundled -- never
-            # show a half-trusted list, and never explain WHY beyond this;
-            # a stale/tampered catalog isn't the user's problem to diagnose.
-            msg = plain_label("Catalog unavailable.")
-            msg.setObjectName("placeholder")
-            msg.setAlignment(Qt.AlignmentFlag.AlignCenter)
-            outer.addWidget(msg, 1)
-            btns = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
-            btns.rejected.connect(self.reject)
-            outer.addWidget(btns)
-            return
-
-        search_row = QHBoxLayout()
-        self.search_box = QLineEdit()
-        self.search_box.setPlaceholderText("Search by name, description, or category…")
-        self.search_box.setClearButtonEnabled(True)
-        self.search_box.textChanged.connect(self._refresh_list)
-        search_row.addWidget(self.search_box, 1)
-        outer.addLayout(search_row)
-
-        chip_row = QHBoxLayout()
-        self._chip_group = QButtonGroup(self)
-        self._chip_group.setExclusive(True)
-        for label in core.CATALOG_CATEGORY_CHIPS:
-            btn = QPushButton(label)
-            btn.setCheckable(True)
-            btn.setChecked(label == "All")
-            btn.clicked.connect(lambda _checked=False, g=label: self._set_group(g))
-            self._chip_group.addButton(btn)
-            chip_row.addWidget(btn)
-        chip_row.addStretch()
-        outer.addLayout(chip_row)
-
-        splitter = QSplitter(Qt.Orientation.Horizontal)
-
-        left = QWidget()
-        lv = QVBoxLayout(left)
-        lv.setContentsMargins(0, 0, 0, 0)
-        self.list = QListWidget()
-        self.list.currentItemChanged.connect(self._on_selected)
-        lv.addWidget(self.list, 1)
-        splitter.addWidget(left)
-
-        right = QFrame()
-        right.setObjectName("card")
-        rv = QVBoxLayout(right)
-        self.detail_title = plain_label("")
-        self.detail_title.setObjectName("h1")
-        rv.addWidget(self.detail_title)
-        self.detail_meta = plain_label("")
-        self.detail_meta.setObjectName("muted")
-        rv.addWidget(self.detail_meta)
-        self.detail_freshness = plain_label("")
-        self.detail_freshness.setObjectName("muted")
-        rv.addWidget(self.detail_freshness)
-        self.detail_desc = plain_label("")
-        rv.addWidget(self.detail_desc)
-        self.detail_notes = plain_label("")
-        self.detail_notes.setObjectName("muted")
-        rv.addWidget(self.detail_notes)
-        self.detail_homepage_btn = QPushButton("Open homepage")
-        self.detail_homepage_btn.clicked.connect(self._open_homepage)
-        rv.addWidget(self.detail_homepage_btn)
-        rv.addWidget(plain_label("Exact command this will add:"))
-        self.detail_command_preview = QPlainTextEdit()
-        self.detail_command_preview.setObjectName("diag")
-        self.detail_command_preview.setReadOnly(True)
-        # Read-only QPlainTextEdit never interprets HTML, regardless of what
-        # a compromised/careless catalog entry's command/args contain -- this
-        # is the field that renders "the exact bytes that will be written".
-        rv.addWidget(self.detail_command_preview, 1)
-        self.detail_action_btn = QPushButton("")
-        self.detail_action_btn.setObjectName("primary")
-        self.detail_action_btn.clicked.connect(self._on_action)
-        rv.addWidget(self.detail_action_btn)
-        splitter.addWidget(right)
-
-        splitter.setSizes([360, 480])
-        outer.addWidget(splitter, 1)
-
-        btns = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
-        btns.rejected.connect(self.reject)
-        outer.addWidget(btns)
-
-        self._refresh_list()
-
-    # --- list / filtering -------------------------------------------------- #
-    def _set_group(self, group: str):
-        self._current_group = group
-        self._refresh_list()
-
-    def _visible_entries(self) -> list[dict]:
-        filtered = core.filter_catalog_entries(self.entries, self.search_box.text())
-        return core.catalog_entries_in_group(filtered, self._current_group)
-
-    def _format_row(self, entry: dict) -> str:
-        display = str(entry.get("display") or entry.get("id") or "")
-        official = "✓ " if entry.get("official") else ""
-        stars = entry.get("stars")
-        star_txt = f"   ★ {stars:,}" if isinstance(stars, int) else ""
-        group = core.catalog_category_group(entry.get("category", ""))
-        desc = str(entry.get("description") or "")
-        if len(desc) > 88:
-            desc = desc[:87] + "…"
-        # QListWidgetItem text is always rendered literally by Qt (no HTML
-        # interpretation), so no escaping is needed here -- unlike QLabel.
-        return f"{official}{display}{star_txt}\n{desc}   ·   {group}"
-
-    def _refresh_list(self):
-        self.list.blockSignals(True)
-        self.list.clear()
-        for entry in self._visible_entries():
-            item = QListWidgetItem(self._format_row(entry))
-            item.setData(Qt.ItemDataRole.UserRole, entry)
-            # Tooltips DO auto-detect rich text in Qt, so escape defensively
-            # even though descriptions are already shown, unescaped-but-safe,
-            # in the QListWidgetItem text above.
-            item.setToolTip(html.escape(str(entry.get("description", ""))))
-            self.list.addItem(item)
-        self.list.blockSignals(False)
-        if self.list.count():
-            self.list.setCurrentRow(0)
-        else:
-            self._on_selected(None, None)
-
-    # --- detail pane -------------------------------------------------------- #
-    def _on_selected(self, current, _previous=None):
-        if current is None:
-            self._current_entry = None
-            self._current_homepage = None
-            self._current_docs_url = None
-            self.detail_title.setText("")
-            self.detail_meta.setText("")
-            self.detail_freshness.setText("")
-            self.detail_desc.setText("No matching servers." if self.entries else "")
-            self.detail_notes.setText("")
-            self.detail_homepage_btn.setVisible(False)
-            self.detail_command_preview.setPlainText("")
-            self.detail_action_btn.setEnabled(False)
-            self.detail_action_btn.setText("Add")
-            return
-
-        entry = current.data(Qt.ItemDataRole.UserRole)
-        self._current_entry = entry
-        self.detail_title.setText(str(entry.get("display") or entry.get("id") or ""))
-
-        official = "✓ Official" if entry.get("official") else ""
-        stars = entry.get("stars")
-        star_txt = f"★ {stars:,}" if isinstance(stars, int) else ""
-        group = core.catalog_category_group(entry.get("category", ""))
-        meta_bits = [b for b in (official, star_txt, group) if b]
-        self.detail_meta.setText("  ·  ".join(meta_bits))
-
-        freshness = core.format_freshness_hint(entry.get("last_release"))
-        self.detail_freshness.setText(freshness)
-        self.detail_freshness.setVisible(bool(freshness))
-
-        self.detail_desc.setText(str(entry.get("description") or ""))
-
-        notes = entry.get("notes") or ""
-        self.detail_notes.setText(notes)
-        self.detail_notes.setVisible(bool(notes))
-
-        homepage = entry.get("homepage")
-        self._current_homepage = homepage if isinstance(homepage, str) else None
-        self.detail_homepage_btn.setVisible(bool(self._current_homepage))
-
-        self._current_docs_url = (
-            entry.get("docs_url") if isinstance(entry.get("docs_url"), str) else None
-        )
-
-        self.detail_command_preview.setPlainText(self._render_command_preview(entry))
-
-        if entry.get("setup") == "basic":
-            self.detail_action_btn.setText("Add")
-            self.detail_action_btn.setEnabled(True)
-        else:
-            self.detail_action_btn.setText("Open setup docs")
-            self.detail_action_btn.setEnabled(bool(self._current_docs_url))
-
-    def _render_command_preview(self, entry: dict) -> str:
-        """
-        The exact command that will be written, rendered verbatim. Every
-        value here comes straight from the (signature-verified) catalog
-        entry with no interpretation beyond str() -- this must never be the
-        place a markup-laced description sneaks back in as "helpful"
-        formatting.
-        """
-        if entry.get("setup") != "basic":
-            docs = entry.get("docs_url") or "(none provided)"
-            return (
-                "This is a hosted/managed integration -- there is no local "
-                "command to add.\n\nSetup docs:\n  " + str(docs)
-            )
-
-        config = entry.get("config") or {}
-        lines = [f"command: {config.get('command', '')}"]
-        args = config.get("args") or []
-        if args:
-            lines.append("args:")
-            lines.extend(f"  {a}" for a in args)
-        env = config.get("env") or {}
-        env_required = entry.get("env_required") or {}
-        env_keys = list(env.keys()) + [k for k in env_required if k not in env]
-        if env_keys:
-            lines.append("env (names only -- you provide the values):")
-            lines.extend(f"  {k}" for k in env_keys)
-        return "\n".join(lines)
-
-    def _open_homepage(self):
-        url = self._current_homepage
-        if url and url.startswith("https://"):
-            QDesktopServices.openUrl(QUrl(url))
-
-    def _on_action(self):
-        entry = self._current_entry
-        if not entry:
-            return
-        if entry.get("setup") == "basic":
-            self.result_entry = entry
-            self.accept()
-        else:
-            url = self._current_docs_url
-            if url and url.startswith("https://"):
-                QDesktopServices.openUrl(QUrl(url))
-            # link-only never auto-adds and never closes the dialog -- the
-            # user can keep browsing after opening the docs in their browser.
-
-
 # --------------------------------------------------------------------------- #
 # Log viewer dialog (issue #6): a read-only, auto-tailing view of a single
 # server's MCP log file. Polls on a QTimer instead of watching the filesystem
@@ -2092,10 +1780,6 @@ class MainWindow(QMainWindow):
        self.del_btn = QPushButton("Delete")
        self.del_btn.setObjectName("danger")
        self.paste_btn = QPushButton("Paste JSON...")
-        self.browse_catalog_btn = QPushButton("Browse catalog…")
-        self.browse_catalog_btn.setToolTip(
-            "Add a popular MCP server from the curated, signed catalog"
-        )
        self.copy_btn = QPushButton("Copy to ▸")
        self.undo_btn = QPushButton("Undo")
        self.undo_btn.setEnabled(False)
@@ -2108,7 +1792,6 @@ class MainWindow(QMainWindow):
        self.dup_btn.clicked.connect(self.duplicate_server)
        self.del_btn.clicked.connect(self.delete_server)
        self.paste_btn.clicked.connect(self.paste_json)
-        self.browse_catalog_btn.clicked.connect(self.browse_catalog)
        self.copy_btn.clicked.connect(self.copy_to_menu)
        self.undo_btn.clicked.connect(self._undo)
        self.test_all_btn.clicked.connect(self._test_all_servers)
@@ -2117,7 +1800,6 @@ class MainWindow(QMainWindow):
            self.dup_btn,
            self.del_btn,
            self.paste_btn,
-            self.browse_catalog_btn,
            self.copy_btn,
            self.undo_btn,
            self.test_all_btn,
@@ -2696,41 +2378,6 @@ class MainWindow(QMainWindow):
        self._mark_dirty()
        self.status.setText(f"Imported {added} added, {replaced} replaced. Review and Save.")

-    def browse_catalog(self):
-        """
-        Open the Browse-catalog dialog (issue #10 phase 2). The catalog is
-        loaded and signature-verified fresh every time the dialog opens --
-        never cached across app runs at this phase (remote fetch/cache is
-        #61, not yet built) -- so a bundled-catalog swap only takes effect
-        on next dialog open, never mid-session in a stale way.
-        """
-        entries = core.load_bundled_catalog_entries(
-            _asset_dir() / "data" / "catalog.json", _asset_dir() / "data" / "catalog.json.sig"
-        )
-        dlg = BrowseCatalogDialog(self, entries)
-        if dlg.exec() != QDialog.DialogCode.Accepted or not dlg.result_entry:
-            return
-        entry = dlg.result_entry
-        paste = core.catalog_entry_to_paste_json(entry)
-        name, data = next(iter(paste.items()))
-
-        existing_before = {s.name: i for i, s in enumerate(self.servers)}
-        self._push_undo()
-        _added, replaced = self._import_server(name, data)
-        idx = (
-            existing_before.get(name, len(self.servers) - 1) if replaced else len(self.servers) - 1
-        )
-        self._refresh_tables(select_index=idx)
-        self._mark_dirty()
-
-        target = core.first_unfilled_focus_target(data)
-        self.editor.focus_target(target)
-
-        verb = "Replaced" if replaced else "Added"
-        self.status.setText(
-            f"{verb} “{name}” from the catalog. Fill in the highlighted field and Save."
-        )
-
    def copy_to_menu(self):
        idx = self._current_index()
        if not (0 <= idx < len(self.servers)):
@@ -2809,29 +2456,6 @@ class MainWindow(QMainWindow):
            QMessageBox.warning(self, "Can't save yet", "Fix the highlighted problem first.")
            return

-        # Placeholder guard (issue #10): a catalog Add can leave a
-        # <PLACEHOLDER>-style token in args/env until the user fills it in.
-        # This warns, it does not block -- the user may be deliberately
-        # saving a stub to finish later -- but it must never save silently,
-        # since a server launched with a literal "<PLACEHOLDER>" argument
-        # just fails in a confusing way at spawn time.
-        placeholder_names = [
-            s.name for s in self.servers if core.config_has_unfilled_placeholders(s.data)
-        ]
-        if placeholder_names:
-            names = ", ".join(f"“{n}”" for n in placeholder_names)
-            ans = QMessageBox.warning(
-                self,
-                "Unfilled placeholder",
-                f"{names} still has a <PLACEHOLDER> value that hasn't been "
-                "replaced with a real value. Claude won't be able to use "
-                "it as-is.\n\nSave anyway?",
-                QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
-                QMessageBox.StandardButton.No,
-            )
-            if ans != QMessageBox.StandardButton.Yes:
-                return
-
        # Stale-file check: if the file changed on disk since we loaded it, prompt.
        # Compare mtime AND size (not mtime alone) so a concurrent external write
        # that lands within the mtime resolution window, or that restores the
@@ -31,11 +31,7 @@ a = Analysis(
    ["bcc.py"],
    pathex=[],
    binaries=[],
-    datas=[
-        ("icons", "icons"),
-        ("data/catalog.json", "data"),
-        ("data/catalog.json.sig", "data"),
-    ],
+    datas=[("icons", "icons"), ("data/catalog.json", "data")],
    hiddenimports=[],
    hookspath=[],
    hooksconfig={},
@@ -29,7 +29,6 @@ import tempfile
 import threading
 import time
 from dataclasses import dataclass
-from datetime import date
 from pathlib import Path
 from typing import NamedTuple
 from urllib.parse import urlparse
@@ -2194,7 +2193,7 @@ CATALOG_DENIED_ENV_KEYS = frozenset(
 # still trust an older key: verify_catalog_signature() accepts a match
 # against ANY key in this list.
 CATALOG_PUBKEYS: list[bytes] = [
-    base64.b64decode("082NOwVB7uURkvfyS3+knJ+40Fk6C9unsF47+2uPKo4="),
+    base64.b64decode("0s24PmkZcTT5yxNDdyTPHl5fyxArrHNPJKBjnXoQd8k="),
 ]

 # Domain-separation prefix for the signed message. The signature covers
@@ -2769,17 +2768,8 @@ def catalog_entry_to_paste_json(entry: dict) -> dict:
    """
    Convert a basic-tier catalog entry into the {name: {command, args, env}}
    shape parse_pasted_json()/_import_server() already understand, so the
-    Browse-catalog dialog can feed a selection straight into the existing
-    paste-import path instead of growing a parallel one.
-
-    `env` is seeded from two sources: config.env (rare -- e.g. grafana's
-    non-secret GRAFANA_URL) and, for every key in `env_required` not already
-    present, an empty-string placeholder. env_required is where the seed
-    data actually keeps its secret VAR NAMES (validate_catalog requires its
-    values to be "" -- never a real secret); config.env alone, without this,
-    would silently drop those names on Add for the 9 of 19 seed entries that
-    need a secret and only declare it via env_required -- the user would
-    see a server added with no field prompting them for the key it needs.
+    (future) catalog picker dialog can feed a selection straight into the
+    existing paste-import path instead of growing a parallel one.
    """
    config = entry.get("config") or {}
    name = entry.get("id") or entry.get("display") or "server"
@@ -2787,11 +2777,9 @@ def catalog_entry_to_paste_json(entry: dict) -> dict:
        "command": config.get("command", ""),
        "args": list(config.get("args") or []),
    }
-    env = dict(config.get("env") or {})
-    for key in entry.get("env_required") or {}:
-        env.setdefault(key, "")
+    env = config.get("env")
    if env:
-        data["env"] = env
+        data["env"] = dict(env)
    return {str(name): data}


@@ -2811,190 +2799,3 @@ def config_has_unfilled_placeholders(cfg: dict) -> bool:
    if isinstance(env, dict):
        values.extend(v for v in env.values() if isinstance(v, str))
    return any(_PLACEHOLDER_RE.search(v) for v in values)
-
-
-# --------------------------------------------------------------------------- #
-# Catalog: Browse-dialog helpers (issue #10 phase 2)
-#
-# Everything below is pure and GUI-free on purpose (per the design comment on
-# #10): the dialog itself should be a thin shell that calls into this module,
-# the same relationship bcc.py already has with the rest of bcc_core.py.
-# --------------------------------------------------------------------------- #
-
-# Collapses the 20-value category taxonomy from the catalog research pass
-# down to the 7 chips shown in the Browse dialog. Any category not listed
-# here (including one a future catalog entry introduces that we don't yet
-# know about) falls back to "Other" rather than raising -- an unrecognized
-# category must never make an entry disappear from the dialog.
-CATALOG_CATEGORY_GROUPS: dict[str, str] = {
-    "files": "Files & Dev",
-    "dev": "Files & Dev",
-    "code-hosting": "Files & Dev",
-    "browser": "Files & Dev",
-    "database": "Data",
-    "data": "Data",
-    "search": "Search & AI",
-    "ai": "Search & AI",
-    "cloud": "Cloud & Infra",
-    "infra": "Cloud & Infra",
-    "observability": "Cloud & Infra",
-    "productivity": "Work",
-    "communication": "Work",
-    "crm": "Work",
-    "finance": "Work",
-    "design": "Work",
-    "media": "Home & Personal",
-    "smart-home": "Home & Personal",
-    "personal": "Home & Personal",
-}
-
-# Ordered for chip display: "All" first, the 6 named groups next in the order
-# given in the #10 design comment, "Other" last as the catch-all.
-CATALOG_CATEGORY_CHIPS: tuple[str, ...] = (
-    "All",
-    "Files & Dev",
-    "Data",
-    "Search & AI",
-    "Cloud & Infra",
-    "Work",
-    "Home & Personal",
-    "Other",
-)
-
-
-def catalog_category_group(category: str) -> str:
-    """Collapse a raw catalog `category` value to one of the 7 UI chips.
-
-    Unknown/missing categories map to "Other" -- never raises, never drops
-    an entry from the list just because its category tag doesn't match one
-    of the ones known at the time this mapping was written.
-    """
-    return CATALOG_CATEGORY_GROUPS.get(str(category or "").strip().lower(), "Other")
-
-
-def catalog_entry_matches_query(entry: dict, query: str) -> bool:
-    """
-    Case-insensitive substring match against a catalog entry's id, display
-    name, description, and category. An empty/whitespace-only query matches
-    everything, so the search box doubles as "no filter" when cleared --
-    the same convention server_matches_filter() uses for the main table.
-    """
-    q = (query or "").strip().lower()
-    if not q:
-        return True
-    haystacks = (
-        str(entry.get("id", "")),
-        str(entry.get("display", "")),
-        str(entry.get("description", "")),
-        str(entry.get("category", "")),
-    )
-    return any(q in h.lower() for h in haystacks)
-
-
-def filter_catalog_entries(entries: list[dict], query: str) -> list[dict]:
-    """Return only the catalog entries that match `query` (see
-    catalog_entry_matches_query)."""
-    return [e for e in entries if catalog_entry_matches_query(e, query)]
-
-
-def catalog_entries_in_group(entries: list[dict], group: str) -> list[dict]:
-    """
-    Return only the entries whose category collapses into `group` (one of
-    CATALOG_CATEGORY_CHIPS). "All" (or a falsy/unrecognized group) returns
-    every entry unfiltered -- that's the default chip state.
-    """
-    if not group or group == "All":
-        return list(entries)
-    return [e for e in entries if catalog_category_group(e.get("category", "")) == group]
-
-
-def format_freshness_hint(last_release: str | None, today: date | None = None) -> str:
-    """
-    Turn a catalog entry's `last_release` (an ISO "YYYY-MM-DD" date, or None
-    when the registry didn't expose one) into a short freshness hint for the
-    detail pane, e.g. "Last updated 14 months ago".
-
-    Returns "" (nothing to show) when `last_release` is missing or
-    unparseable, or when it's somehow in the future relative to `today` --
-    a bogus "-3 months ago" would undermine the one signal this hint exists
-    to give the user, so we'd rather show nothing than something wrong.
-
-    `today` is an injectable override so this is exactly reproducible in
-    tests without depending on the wall clock.
-    """
-    if not last_release or not isinstance(last_release, str):
-        return ""
-    try:
-        released = date.fromisoformat(last_release)
-    except ValueError:
-        return ""
-    now = today or date.today()
-    if released > now:
-        return ""
-
-    months = (now.year - released.year) * 12 + (now.month - released.month)
-    if now.day < released.day:
-        months -= 1
-    months = max(months, 0)
-
-    if months == 0:
-        return "Last updated this month"
-    if months == 1:
-        return "Last updated 1 month ago"
-    if months < 24:
-        return f"Last updated {months} months ago"
-    years = months // 12
-    return f"Last updated {years} year{'s' if years != 1 else ''} ago"
-
-
-def first_unfilled_focus_target(data: dict) -> tuple[str, int | str] | None:
-    """
-    Given a server config dict shaped like catalog_entry_to_paste_json()'s
-    output (command/args/env), find the first thing a user must fill in
-    after a catalog Add: a <PLACEHOLDER>-style arg (checked first, since a
-    missing path/target usually blocks the server from starting at all) or
-    else the first env var the catalog left blank.
-
-    Returns ("args", index) or ("env", key), or None when there's nothing
-    left to fill (e.g. a server with no placeholders and no required env).
-    The GUI uses this to focus+select the right field right after Add,
-    instead of leaving the user to hunt for what still needs a value.
-    """
-    args = data.get("args") or []
-    for i, a in enumerate(args):
-        if isinstance(a, str) and _PLACEHOLDER_RE.search(a):
-            return ("args", i)
-
-    env = data.get("env") or {}
-    if isinstance(env, dict):
-        for k, v in env.items():
-            if not isinstance(v, str) or not v.strip() or _PLACEHOLDER_RE.search(v):
-                return ("env", k)
-
-    return None
-
-
-def load_bundled_catalog_entries(catalog_path: Path, sig_path: Path) -> list[dict]:
-    """
-    Read+verify+validate the bundled catalog.json/.sig pair from disk and
-    return its `servers` list -- or an EMPTY list if anything at all is
-    wrong: files missing/unreadable, signature doesn't verify, JSON doesn't
-    parse, or validate_catalog() finds a problem.
-
-    🔴 SECURITY: this is the load-bearing guarantee for the Browse dialog.
-    There is deliberately no partial-success path here -- a signature
-    failure must never surface a half-trusted list, only an empty one, so
-    the GUI's only job is to render "Catalog unavailable" when this comes
-    back empty. All the real trust decisions (signature, schema, command
-    allowlist) already live in resolve_catalog()/validate_catalog(); this
-    is a thin disk-reading wrapper around them so the GUI never touches
-    catalog bytes directly.
-    """
-    try:
-        raw = catalog_path.read_bytes()
-        sig = sig_path.read_bytes()
-    except OSError:
-        return []
-    data = resolve_catalog(bundled=(raw, sig), cached=None, remote=None)
-    servers = data.get("servers") if isinstance(data, dict) else None
-    return servers if isinstance(servers, list) else []
@@ -16,6 +16,8 @@ new surface" recurring-bug lesson).

 from __future__ import annotations

+import base64
+import hashlib
 import os
 import re
 from collections.abc import Callable
@@ -442,18 +444,43 @@ class ReviewSession:
    from the reviewed ref on every PR review (the bug that made the PR path
    unable to sign at all, and forced everyone onto the vacuous
    main-vs-itself path instead).
+
+    `reattest` marks a KEY-ROTATION re-attestation pass (issue #68 finding 5
+    follow-up): the currently-trusted `bcc_core.CATALOG_PUBKEYS` key changed
+    and the existing `data/catalog.json.sig` no longer verifies under it.
+    Content-wise nothing may have changed -- `diff_catalogs(old, new)` can be
+    genuinely empty -- but the NEW key has never vouched for any of this
+    catalog before, so every entry needs a first-time attestation under the
+    new key, not a diff against the old one. When `reattest` is set,
+    `changes` is built as "every entry in `new_catalog`, presented as if
+    newly added" (via `diff_catalogs(None, new_catalog)`) instead of a
+    diff against `old_catalog`, so the acknowledge-gate in `can_sign()`
+    requires re-reviewing everything the new key will sign -- which is the
+    intended cost of a key rotation, not a bypass of the empty-diff guard.
    """

    pinned_blob_sha: str
    old_catalog: dict
    new_catalog: dict
    loaded_ref: str = "main"
+    reattest: bool = False
    changes: list[EntryChange] = field(default_factory=list)
    acknowledged: set[str] = field(default_factory=set)

    def __post_init__(self) -> None:
        if not self.changes:
-            self.changes = diff_catalogs(self.old_catalog, self.new_catalog)
+            if self.reattest:
+                # Every entry in the new catalog is treated as though it
+                # were newly added -- because, under the NEW signing key,
+                # it is: nothing this key signs was ever attested by it
+                # before. Reusing diff_catalogs(None, new) (rather than a
+                # bespoke code path) means the same "added" risk predicate
+                # (risk_new_entry) and the same EntryChange shape the rest
+                # of this module and the GUI already know how to render
+                # apply here unmodified.
+                self.changes = diff_catalogs(None, self.new_catalog)
+            else:
+                self.changes = diff_catalogs(self.old_catalog, self.new_catalog)


 def start_review(
@@ -461,12 +488,14 @@ def start_review(
    old_catalog: dict,
    new_catalog: dict,
    loaded_ref: str = "main",
+    reattest: bool = False,
 ) -> ReviewSession:
    return ReviewSession(
        pinned_blob_sha=pinned_blob_sha,
        old_catalog=old_catalog,
        new_catalog=new_catalog,
        loaded_ref=loaded_ref,
+        reattest=reattest,
    )


@@ -531,6 +560,14 @@ def can_sign(session: ReviewSession, current_blob_sha: str) -> SignDecision:
       mean "nothing to sign", never "sign unlocked". (Issue #68 finding 1;
       this is what let commit b08cf21 sign all 19 entries with zero of them
       ever reviewed.)
+
+       This gate is unaffected by `session.reattest`: a key-rotation
+       re-attestation session's `changes` is built from
+       `diff_catalogs(None, new_catalog)` (see ReviewSession), which is
+       empty ONLY if the catalog itself has zero entries -- a genuinely
+       empty catalog either way. Rotation never manufactures a non-empty
+       changeset out of an empty one; it just changes *what* "non-empty"
+       is computed against.
    1. TOCTOU: `current_blob_sha` (fetched fresh, immediately before signing,
       from the ref that was actually reviewed -- see sign_precondition())
       must match the blob SHA pinned when review began. If the bytes on the
@@ -816,3 +853,243 @@ _NON_ASCII_RE = re.compile(r"[^\x00-\x7f]")

 def contains_non_ascii(s: str) -> bool:
    return bool(_NON_ASCII_RE.search(s))
+
+
+# --------------------------------------------------------------------------- #
+# Key status reporting (issue #62/#68 follow-up: "make key handling
+# comprehensible"). Pure functions only -- `catalog_console.py cmd_keys` is a
+# thin printer that gathers inputs (local key caches, source-file text, the
+# catalog + its .sig) and hands them here. NEVER touches private key bytes:
+# every input/output here is a public key, a fingerprint, or a status string.
+# --------------------------------------------------------------------------- #
+
+
+def fingerprint_pubkey(pubkey: bytes) -> str:
+    """Short, human-comparable fingerprint of a raw Ed25519 public key: the
+    first 16 hex chars of its SHA-256 digest, grouped in 4s (e.g. "3F2A 9C1B
+    44DE 08AA") so two fingerprints can be eyeballed for a mismatch the way a
+    PGP fingerprint is. Deliberately NOT the raw base64 pubkey itself in the
+    default short form (that's available via the full committed value in the
+    report) -- a fixed-width grouped hex string is easier to compare at a
+    glance and to read aloud/type over chat if needed. Never derived from,
+    and never printed alongside, any private key material.
+    """
+    digest = hashlib.sha256(pubkey).hexdigest().upper()[:16]
+    return " ".join(digest[i : i + 4] for i in range(0, len(digest), 4))
+
+
+_PUBKEY_LIST_B64_RE = re.compile(r'base64\.b64decode\(\s*"([^"]+)"\s*\)')
+
+
+def extract_pubkey_list_literal(source_text: str, var_name: str) -> list[bytes]:
+    """Best-effort extraction of a `<var_name>: list[bytes] = [...]` literal
+    (each entry a `base64.b64decode("...")` call, matching the exact style
+    bcc_core.CATALOG_PUBKEYS and scripts.sign_checksums.RELEASE_PUBKEYS are
+    both written in) straight out of Python source TEXT.
+
+    Deliberately a regex over text, not an import: `catalog_console.py keys`
+    must report on whatever ref/branch is checked out at the inspected repo
+    path, which may not be (and need not be) importable from the running
+    process's own sys.path. Returns [] if the variable isn't found in this
+    exact shape -- callers treat that as "nothing committed here", not an
+    error, since a report that can't parse a file should say so plainly
+    rather than crash the whole `keys` command over one malformed file.
+    """
+    match = re.search(
+        rf"{re.escape(var_name)}\s*:\s*list\[bytes\]\s*=\s*\[(.*?)\]", source_text, re.DOTALL
+    )
+    if not match:
+        return []
+    keys: list[bytes] = []
+    for b64 in _PUBKEY_LIST_B64_RE.findall(match.group(1)):
+        try:
+            keys.append(base64.b64decode(b64))
+        except ValueError:
+            continue
+    return keys
+
+
+_CI_TRUST_ANCHOR_RE = re.compile(r'EXPECTED_CATALOG_PUBKEY_B64:\s*"([^"]+)"')
+
+
+def extract_ci_trust_anchor_pubkey(ci_yml_text: str) -> bytes | None:
+    """Best-effort extraction of ci.yml's `EXPECTED_CATALOG_PUBKEY_B64` trust
+    anchor (issue #68 finding 4) from the workflow file's TEXT. Returns None
+    if the constant isn't found -- the `keys` report shows that plainly
+    ("not found in ci.yml") rather than raising.
+    """
+    match = _CI_TRUST_ANCHOR_RE.search(ci_yml_text)
+    if not match:
+        return None
+    try:
+        return base64.b64decode(match.group(1))
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True)
+class PubkeyLocationCheck:
+    """One place in the source tree a key's public half is expected to be
+    committed, and whether the fingerprint(s) found there match the key
+    stored locally."""
+
+    location: str
+    committed_fingerprints: tuple[str, ...]
+    status: str  # "match" | "mismatch" | "unknown" (no local key to compare against)
+
+
+@dataclass(frozen=True)
+class KeyStatus:
+    """Everything `catalog_console.py keys` reports about ONE signing key.
+    Built by key_status() below; rendered by render_key_status_report().
+    Never carries private key material -- every field here is safe to print.
+    """
+
+    kind: str  # "catalog" | "release"
+    display_name: str  # "CATALOG" | "RELEASE"
+    purpose: str  # one-line plain-English purpose
+    private_key_location: str  # human-readable, e.g. "on this machine, in the OS keychain"
+    local_exists: bool
+    local_fingerprint: str | None
+    locations: tuple[PubkeyLocationCheck, ...]
+    catalog_sig_status: str | None = None  # "valid" | "invalid" | "missing" | None (n/a)
+
+
+def key_status(
+    kind: str,
+    *,
+    display_name: str,
+    purpose: str,
+    private_key_location: str,
+    local_exists: bool,
+    local_pubkey: bytes | None,
+    locations: list[tuple[str, list[bytes]]],
+    catalog_sig_status: str | None = None,
+) -> KeyStatus:
+    """Pure assembly of a KeyStatus from already-resolved inputs (no file or
+    git I/O here -- that's catalog_console.py's job). `locations` is a list
+    of (label, committed_pubkeys) pairs, e.g.
+    [("bcc_core.CATALOG_PUBKEYS", [...]), ("ci.yml trust anchor", [...])],
+    so a key can be checked against every place its public half is expected
+    to be committed, independently -- this is the check that would have
+    caught bcc_core.CATALOG_PUBKEYS and ci.yml's trust anchor silently
+    drifting apart (issue #68 finding 4 was exactly that kind of drift).
+    """
+    checks: list[PubkeyLocationCheck] = []
+    for label, committed_pubkeys in locations:
+        fps = tuple(fingerprint_pubkey(pk) for pk in committed_pubkeys)
+        if local_pubkey is None:
+            status = "unknown"
+        elif local_pubkey in committed_pubkeys:
+            status = "match"
+        else:
+            status = "mismatch"
+        checks.append(
+            PubkeyLocationCheck(location=label, committed_fingerprints=fps, status=status)
+        )
+
+    return KeyStatus(
+        kind=kind,
+        display_name=display_name,
+        purpose=purpose,
+        private_key_location=private_key_location,
+        local_exists=local_exists,
+        local_fingerprint=fingerprint_pubkey(local_pubkey) if local_pubkey is not None else None,
+        locations=tuple(checks),
+        catalog_sig_status=catalog_sig_status,
+    )
+
+
+_LOCATION_STATUS_ICON = {"match": "✅", "mismatch": "❌", "unknown": "⚠️"}
+_LOCATION_STATUS_VERDICT = {
+    "match": "MATCHES the local private key",
+    "mismatch": "DOES NOT MATCH the local private key",
+    "unknown": "cannot compare -- no local key to check against",
+}
+_CATALOG_SIG_STATUS_LINE = {
+    "valid": "✅ data/catalog.json.sig verifies under the committed CATALOG_PUBKEYS.",
+    "invalid": (
+        "❌ data/catalog.json.sig does NOT verify under the committed CATALOG_PUBKEYS -- "
+        "the catalog needs re-signing (Load → acknowledge all → Sign)."
+    ),
+    "missing": (
+        "⚠️ data/catalog.json.sig is missing entirely -- the catalog has never been signed."
+    ),
+}
+
+
+def recommend_next_steps(statuses: list[KeyStatus]) -> list[str]:
+    """The pure "what to do next" logic behind the keys report's closing
+    section -- one concrete, runnable-looking instruction per problem found,
+    naming the exact key involved (never just "the key"). Returns a single
+    reassuring line if nothing needs attention."""
+    steps: list[str] = []
+    for s in statuses:
+        if not s.local_exists:
+            flag = " --release" if s.kind == "release" else ""
+            steps.append(
+                f"{s.display_name} key has never been generated on this machine -- run "
+                f"`python catalog_console.py keygen{flag}`."
+            )
+            continue
+        for loc in s.locations:
+            if loc.status == "mismatch":
+                steps.append(
+                    f"{s.display_name} key's local fingerprint does not match "
+                    f"{loc.location} -- update {loc.location} to the fingerprint shown "
+                    "above (or, if this is unexpected, treat the committed key as "
+                    "untrusted and investigate before doing anything else)."
+                )
+            elif loc.status == "unknown":
+                steps.append(
+                    f"{s.display_name} key's local fingerprint could not be checked against "
+                    f"{loc.location} -- re-run keygen (or, for an older install, unlock the "
+                    "key once) so its public half is cached locally."
+                )
+        if s.kind == "catalog" and s.catalog_sig_status in ("invalid", "missing"):
+            steps.append(
+                "The catalog needs re-signing: run `python catalog_console.py gui --repo .` "
+                "and Load → acknowledge every entry → Sign. If main is red because "
+                "of a key rotation, load the branch with the rotation instead of main "
+                "(current-branch / --ref source) so the fix lands before merge."
+            )
+    if not steps:
+        steps.append("Everything is consistent -- no action needed.")
+    return steps
+
+
+def render_key_status_report(statuses: list[KeyStatus]) -> str:
+    """Render a full, plain-English-first key status report as one string.
+    `catalog_console.py cmd_keys` prints this verbatim -- the CLI is a thin
+    printer over this pure function, which is what makes the report's
+    content (not just its plumbing) unit-testable."""
+    lines: list[str] = []
+    for s in statuses:
+        lines.append(f"=== {s.display_name} KEY ===")
+        lines.append(s.purpose)
+        lines.append(f"Private half lives: {s.private_key_location}")
+        if s.local_exists and s.local_fingerprint:
+            lines.append(f"Exists locally: yes (fingerprint {s.local_fingerprint})")
+        elif s.local_exists:
+            lines.append("Exists locally: yes (fingerprint unknown -- re-run keygen to cache it)")
+        else:
+            lines.append("Exists locally: no")
+        for loc in s.locations:
+            icon = _LOCATION_STATUS_ICON.get(loc.status, "?")
+            fps = (
+                ", ".join(loc.committed_fingerprints)
+                if loc.committed_fingerprints
+                else "(nothing committed here)"
+            )
+            verdict = _LOCATION_STATUS_VERDICT.get(loc.status, loc.status)
+            lines.append(f"  {icon} {loc.location}: {fps} -- {verdict}")
+        if s.catalog_sig_status is not None:
+            lines.append(
+                f"Catalog signature: {_CATALOG_SIG_STATUS_LINE.get(s.catalog_sig_status, s.catalog_sig_status)}"
+            )
+        lines.append("")
+
+    lines.append("What to do next:")
+    for step in recommend_next_steps(statuses):
+        lines.append(f"  - {step}")
+    return "\n".join(lines)
@@ -53,13 +53,17 @@ DOMAIN_PREFIX = b"bcc-release-v1|"
 # the signature on every past release: verification accepts a match against
 # ANY key here.
 #
-# Empty until the maintainer generates the release keypair (separately from
-# the catalog keypair) and pastes the public half in:
+# Populated by the maintainer via:
 #     python catalog_console.py keygen --release
-# This is intentionally NOT pre-populated with a placeholder that looks
-# like a real key -- release.yml's signing-smoke-test fails closed (loudly)
-# on an empty list rather than silently verifying against nothing.
-RELEASE_PUBKEYS: list[bytes] = []
+# Rotated 2026-07 (issue #68 finding 5 / #68 CI-exposure incident): the
+# original key was shared with the catalog key and had been exposed to CI,
+# so both keypairs were regenerated as separate, disjoint keys. This list
+# holds only the current release key -- if release.yml's signing-smoke-test
+# ever sees this list empty, it fails closed (loudly) rather than silently
+# verifying against nothing.
+RELEASE_PUBKEYS: list[bytes] = [
+    base64.b64decode("6BnPgJEHJFyVltFoLTCNadIsehjy00iiW8IRlC1TfhA="),
+]

 CHUNK_SIZE = 1024 * 1024

@@ -0,0 +1,215 @@
+"""Tests for catalog_console.py's non-Qt git plumbing and ref-resolution
+seam (issue #68 rotation-completability fix).
+
+catalog_console.py is importable here WITHOUT PySide6 -- its Qt import is
+guarded (`_PYSIDE6_AVAILABLE`) precisely so `keygen`, `show-seed-b64`,
+`keys`, and this git plumbing stay usable (and testable) wherever PySide6
+isn't installed, including this CI test job, which never installs it. If
+PySide6 genuinely isn't importable in this environment, that itself
+exercises the guard path -- see test_module_imports_without_pyside6.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import catalog_console as cc
+import catalog_review as review
+
+_SEED_CATALOG = b'{"schema": 1, "version": 1, "servers": []}'
+_SEED_SIG = b"\x00" * 64
+
+
+def _run(*args: str, cwd: Path) -> None:
+    subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
+
+
+def _init_bare_and_clone(tmp_path: Path) -> tuple[Path, Path]:
+    """A bare "origin" repo with `main` and `rotation-branch` both seeded
+    with a catalog + (dummy) signature, plus a working clone with `origin`
+    already configured -- mirroring the tokened-remote clone
+    catalog_console.py's git plumbing is always run against."""
+    origin = tmp_path / "origin.git"
+    _run("init", "--bare", str(origin), cwd=tmp_path)
+
+    seed = tmp_path / "seed"
+    _run("clone", str(origin), str(seed), cwd=tmp_path)
+    _run("config", "user.email", "test@example.com", cwd=seed)
+    _run("config", "user.name", "Test", cwd=seed)
+
+    (seed / "data").mkdir()
+    (seed / "data" / "catalog.json").write_bytes(_SEED_CATALOG)
+    (seed / "data" / "catalog.json.sig").write_bytes(_SEED_SIG)
+    _run("add", "-A", cwd=seed)
+    _run("commit", "-m", "seed", cwd=seed)
+    _run("push", "origin", "HEAD:refs/heads/main", cwd=seed)
+    _run("checkout", "-b", "rotation-branch", cwd=seed)
+    _run("push", "origin", "HEAD:refs/heads/rotation-branch", cwd=seed)
+
+    clone = tmp_path / "work"
+    _run("clone", str(origin), str(clone), cwd=tmp_path)
+    _run("config", "user.email", "test@example.com", cwd=clone)
+    _run("config", "user.name", "Test", cwd=clone)
+    return origin, clone
+
+
+# --------------------------------------------------------------------------- #
+# The module must stay importable without PySide6 -- this IS the fix that
+# lets `keys`/`keygen`/`show-seed-b64` (and this whole test file) run
+# somewhere PySide6 isn't installed.
+# --------------------------------------------------------------------------- #
+def test_module_imports_without_pyside6():
+    assert hasattr(cc, "_PYSIDE6_AVAILABLE")
+    # This CI test job never installs PySide6 (see .github/workflows/ci.yml
+    # "Install test dependencies": pytest + cryptography only) -- so on CI,
+    # this assertion is itself proof the guard is doing its job. Locally,
+    # where a maintainer's env DOES have PySide6, it's fine either way; the
+    # only real assertion this test needs is "importing the module never
+    # raises", which happened just by getting this far.
+    assert cc._PYSIDE6_AVAILABLE in (True, False)
+
+
+def test_cmd_gui_fails_soft_without_pyside6(monkeypatch, capsys):
+    if cc._PYSIDE6_AVAILABLE:
+        return  # nothing to prove where PySide6 IS available
+    import argparse
+
+    args = argparse.Namespace(repo=".", ref=None)
+    assert cc.cmd_gui(args) == 1
+    assert "PySide6" in capsys.readouterr().err
+
+
+# --------------------------------------------------------------------------- #
+# compute_own_refs: the PURE ref-resolution seam. No git, no Qt.
+# --------------------------------------------------------------------------- #
+def test_compute_own_refs_defaults_to_main_only():
+    assert cc.compute_own_refs(None, None) == ["main"]
+
+
+def test_compute_own_refs_adds_detected_branch():
+    assert cc.compute_own_refs(None, "chore/68-key-rotation") == [
+        "main",
+        "chore/68-key-rotation",
+    ]
+
+
+def test_compute_own_refs_explicit_ref_overrides_detected_branch():
+    assert cc.compute_own_refs("explicit-branch", "detected-branch") == [
+        "main",
+        "explicit-branch",
+    ]
+
+
+def test_compute_own_refs_does_not_duplicate_main():
+    assert cc.compute_own_refs(None, "main") == ["main"]
+    assert cc.compute_own_refs("main", "some-other-branch") == ["main"]
+
+
+# --------------------------------------------------------------------------- #
+# current_branch: git plumbing, no Qt.
+# --------------------------------------------------------------------------- #
+def test_current_branch_detects_checked_out_branch(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+    _run("fetch", "origin", "rotation-branch", cwd=clone)
+    _run("checkout", "-B", "rotation-branch", "origin/rotation-branch", cwd=clone)
+    assert cc.current_branch(clone) == "rotation-branch"
+
+
+def test_current_branch_none_on_detached_head(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+    commit = cc.fetch_ref(clone, "main")
+    _run("checkout", commit, cwd=clone)
+    assert cc.current_branch(clone) is None
+
+
+# --------------------------------------------------------------------------- #
+# commit_and_push_signed_catalog: MUST target the given branch, never a
+# hardcoded "main" -- issue #68's completability fix. This is exactly the
+# bug that, before the fix, would have made ReviewWindow._on_sign push a
+# PR/branch review's signature straight to main regardless of what was
+# actually reviewed.
+# --------------------------------------------------------------------------- #
+def test_commit_and_push_signed_catalog_targets_the_given_branch_not_main(tmp_path):
+    _origin, clone = _init_bare_and_clone(tmp_path)
+
+    new_raw = b'{"schema": 1, "version": 2, "servers": []}'
+    new_sig = b"\x01" * 64
+    cc.commit_and_push_signed_catalog(clone, new_raw, new_sig, branch="rotation-branch")
+
+    rotation_commit = cc.fetch_ref(clone, "rotation-branch")
+    rotation_raw, _sha = cc.read_catalog_at_commit(clone, rotation_commit)
+    assert rotation_raw == new_raw
+
+    # main on the shared origin must be COMPLETELY untouched by a sign that
+    # was reviewed and pushed against rotation-branch.
+    main_commit = cc.fetch_ref(clone, "main")
+    main_raw, _sha = cc.read_catalog_at_commit(clone, main_commit)
+    assert main_raw == _SEED_CATALOG
+
+
+def test_commit_and_push_signed_catalog_still_defaults_to_main(tmp_path):
+    """Backward-compatible default: callers that don't pass `branch` (there
+    are none left in catalog_console.py itself, but the signature keeps the
+    default for any other caller / test fixture) still push to main."""
+    _origin, clone = _init_bare_and_clone(tmp_path)
+
+    new_raw = b'{"schema": 1, "version": 2, "servers": []}'
+    new_sig = b"\x01" * 64
+    cc.commit_and_push_signed_catalog(clone, new_raw, new_sig)
+
+    main_commit = cc.fetch_ref(clone, "main")
+    main_raw, _sha = cc.read_catalog_at_commit(clone, main_commit)
+    assert main_raw == new_raw
+
+    rotation_commit = cc.fetch_ref(clone, "rotation-branch")
+    rotation_raw, _sha = cc.read_catalog_at_commit(clone, rotation_commit)
+    assert rotation_raw == _SEED_CATALOG  # untouched
+
+
+# --------------------------------------------------------------------------- #
+# catalog_sig_status_on_disk: the check behind `keys`' "does catalog.json.sig
+# currently verify?" line -- this is precisely the check that would have
+# caught the current chore/68-key-rotation state (bcc_core.CATALOG_PUBKEYS
+# rotated, data/catalog.json.sig still signed by the retired key).
+# --------------------------------------------------------------------------- #
+def test_catalog_sig_status_on_disk_valid(tmp_path):
+    seed, pub = review.generate_keypair()
+    raw = b'{"schema": 1, "version": 1, "servers": []}'
+    sig = review.sign_catalog_bytes(raw, seed)
+
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(raw)
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(sig)
+
+    assert cc.catalog_sig_status_on_disk(tmp_path, [pub]) == "valid"
+
+
+def test_catalog_sig_status_on_disk_invalid_when_pubkey_rotated(tmp_path):
+    """The exact chore/68-key-rotation scenario: signed by an OLD key, but
+    the committed pubkey list now only has the NEW key."""
+    old_seed, _old_pub = review.generate_keypair()
+    _new_seed, new_pub = review.generate_keypair()
+    raw = b'{"schema": 1, "version": 1, "servers": []}'
+    sig = review.sign_catalog_bytes(raw, old_seed)
+
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(raw)
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(sig)
+
+    assert cc.catalog_sig_status_on_disk(tmp_path, [new_pub]) == "invalid"
+
+
+def test_catalog_sig_status_on_disk_missing_when_no_sig_file(tmp_path):
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json").write_bytes(b"{}")
+    assert cc.catalog_sig_status_on_disk(tmp_path, []) == "missing"
+
+
+def test_catalog_sig_status_on_disk_missing_when_no_catalog_file(tmp_path):
+    (tmp_path / "data").mkdir()
+    (tmp_path / "data" / "catalog.json.sig").write_bytes(b"\x00" * 64)
+    assert cc.catalog_sig_status_on_disk(tmp_path, []) == "missing"
@@ -491,6 +491,98 @@ def test_sign_precondition_defaults_to_main_when_loaded_ref_unset():
    assert decision.ok is True


+# --------------------------------------------------------------------------- #
+# ReviewSession(reattest=True): key-rotation re-attestation (issue #68
+# finding 5 follow-up). After rotating bcc_core.CATALOG_PUBKEYS, the
+# existing data/catalog.json.sig no longer verifies under the new key even
+# though catalog CONTENT is unchanged -- diff_catalogs(old, new) would be
+# empty, and an empty changeset must never unlock Sign (can_sign gate 0).
+# Re-attestation mode sidesteps that correctly: instead of diffing against
+# the (now-untrustworthy) last-signed content, it treats every entry as
+# requiring a fresh acknowledgement, exactly like a brand-new catalog.
+# --------------------------------------------------------------------------- #
+def test_reattest_mode_with_unchanged_content_yields_one_change_per_entry():
+    same = _catalog(_entry(id="a"), _entry(id="b"), _entry(id="c"))
+    session = r.start_review("sha1", same, same, reattest=True)
+    assert len(session.changes) == 3
+    assert {c_.entry_id for c_ in session.changes} == {"a", "b", "c"}
+    # Presented "as if newly added" -- old_catalog plays no role here.
+    assert all(c_.status == "added" for c_ in session.changes)
+    assert all(c_.old is None for c_ in session.changes)
+
+
+def test_reattest_mode_can_sign_refuses_until_all_acknowledged_then_permits():
+    same = _catalog(_entry(id="a"), _entry(id="b"), _entry(id="c"))
+    session = r.start_review("sha1", same, same, reattest=True)
+
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is False
+    assert "acknowledged" in decision.reason.lower()
+
+    r.acknowledge_entry(session, "a")
+    r.acknowledge_entry(session, "b")
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is False  # "c" still outstanding
+    assert "acknowledged" in decision.reason.lower()
+
+    r.acknowledge_entry(session, "c")
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is True
+    assert decision.reason is None
+
+
+def test_normal_mode_with_unchanged_content_still_refuses_empty_diff():
+    """The rotation path must NOT become a general bypass of the empty-diff
+    guard: reattest=False (the default) against identical old/new catalogs
+    must behave exactly as before -- can_sign refuses with 'nothing to
+    sign', full stop."""
+    same = _catalog(_entry(id="a"), _entry(id="b"))
+    session = r.start_review("sha1", same, same)  # reattest defaults False
+    assert session.changes == []
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is False
+    assert "nothing to sign" in decision.reason.lower()
+
+
+def test_reattest_mode_still_enforces_blocking_risk_check():
+    """Re-attestation must not relax the blocking-risk gate: a
+    disallowed-command entry blocks Sign even with every entry
+    acknowledged."""
+    cat = _catalog(
+        _entry(id="a"),
+        _entry(id="evil", config={"command": "bash", "args": ["-c", "rm -rf /"]}),
+    )
+    session = r.start_review("sha1", cat, cat, reattest=True)
+    assert len(session.changes) == 2
+    r.acknowledge_entry(session, "a")
+    r.acknowledge_entry(session, "evil")
+    assert r.all_entries_acknowledged(session) is True
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is False
+    assert "blocking" in decision.reason.lower()
+
+
+def test_reattest_mode_still_enforces_toctou_pin():
+    """Re-attestation must not relax the TOCTOU blob-SHA pin: acknowledging
+    everything is not enough if the bytes moved underneath the review."""
+    same = _catalog(_entry(id="a"))
+    session = r.start_review("sha1", same, same, reattest=True)
+    r.acknowledge_entry(session, "a")
+    decision = r.can_sign(session, "sha1")
+    assert decision.ok is True  # sanity: matches when blob is unchanged
+
+    decision = r.can_sign(session, "sha2-a-new-commit-landed")
+    assert decision.ok is False
+    assert "mismatch" in decision.reason.lower() or "changed" in decision.reason.lower()
+
+
+def test_reattest_defaults_to_false():
+    """start_review()'s reattest parameter defaults to False -- normal
+    (diff-based) review is the default behaviour, never silently entered."""
+    session = r.start_review("sha1", _catalog(), _catalog(_entry()))
+    assert session.reattest is False
+
+
 # --------------------------------------------------------------------------- #
 # find_last_signed_catalog_raw: what source=main diffs against
 # --------------------------------------------------------------------------- #
@@ -693,3 +785,245 @@ def test_contains_non_ascii_true():

 def test_contains_non_ascii_false():
    assert r.contains_non_ascii("package") is False
+
+
+# --------------------------------------------------------------------------- #
+# fingerprint_pubkey
+# --------------------------------------------------------------------------- #
+def test_fingerprint_pubkey_is_deterministic():
+    pub = b"\x01" * 32
+    assert r.fingerprint_pubkey(pub) == r.fingerprint_pubkey(pub)
+
+
+def test_fingerprint_pubkey_differs_for_different_keys():
+    assert r.fingerprint_pubkey(b"\x01" * 32) != r.fingerprint_pubkey(b"\x02" * 32)
+
+
+def test_fingerprint_pubkey_never_contains_the_key_bytes_themselves():
+    pub = b"\x42" * 32
+    fp = r.fingerprint_pubkey(pub)
+    assert pub.hex() not in fp.lower().replace(" ", "")
+
+
+# --------------------------------------------------------------------------- #
+# extract_pubkey_list_literal / extract_ci_trust_anchor_pubkey: text parsing
+# for `catalog_console.py keys`, exercised here with no file I/O.
+# --------------------------------------------------------------------------- #
+def test_extract_pubkey_list_literal_single_key():
+    _seed, pub = r.generate_keypair()
+    import base64
+
+    text = (
+        "CATALOG_PUBKEYS: list[bytes] = [\n"
+        f'    base64.b64decode("{base64.b64encode(pub).decode()}"),\n'
+        "]\n"
+    )
+    assert r.extract_pubkey_list_literal(text, "CATALOG_PUBKEYS") == [pub]
+
+
+def test_extract_pubkey_list_literal_multiple_keys():
+    import base64
+
+    pubs = [r.generate_keypair()[1] for _ in range(2)]
+    body = ",\n".join(f'    base64.b64decode("{base64.b64encode(p).decode()}")' for p in pubs)
+    text = f"RELEASE_PUBKEYS: list[bytes] = [\n{body},\n]\n"
+    assert r.extract_pubkey_list_literal(text, "RELEASE_PUBKEYS") == pubs
+
+
+def test_extract_pubkey_list_literal_missing_variable_returns_empty():
+    assert r.extract_pubkey_list_literal("some unrelated text", "CATALOG_PUBKEYS") == []
+
+
+def test_extract_pubkey_list_literal_does_not_match_a_different_variable():
+    import base64
+
+    _seed, pub = r.generate_keypair()
+    text = f'OTHER_PUBKEYS: list[bytes] = [base64.b64decode("{base64.b64encode(pub).decode()}")]\n'
+    assert r.extract_pubkey_list_literal(text, "CATALOG_PUBKEYS") == []
+
+
+def test_extract_ci_trust_anchor_pubkey_found():
+    import base64
+
+    _seed, pub = r.generate_keypair()
+    text = f'          EXPECTED_CATALOG_PUBKEY_B64: "{base64.b64encode(pub).decode()}"\n'
+    assert r.extract_ci_trust_anchor_pubkey(text) == pub
+
+
+def test_extract_ci_trust_anchor_pubkey_missing_returns_none():
+    assert r.extract_ci_trust_anchor_pubkey("no anchor here") is None
+
+
+# --------------------------------------------------------------------------- #
+# key_status / render_key_status_report / recommend_next_steps
+# --------------------------------------------------------------------------- #
+def _kw(**overrides):
+    base = dict(
+        kind="catalog",
+        display_name="CATALOG",
+        purpose="Signs the catalog.",
+        private_key_location="on this machine",
+        local_exists=True,
+        local_pubkey=b"\x01" * 32,
+        locations=[("bcc_core.CATALOG_PUBKEYS", [b"\x01" * 32])],
+        catalog_sig_status="valid",
+    )
+    base.update(overrides)
+    return base
+
+
+def test_key_status_reports_match_when_local_pubkey_in_committed_list():
+    status = r.key_status(**_kw())
+    assert status.locations[0].status == "match"
+
+
+def test_key_status_reports_mismatch_when_local_pubkey_not_in_committed_list():
+    status = r.key_status(**_kw(locations=[("bcc_core.CATALOG_PUBKEYS", [b"\x02" * 32])]))
+    assert status.locations[0].status == "mismatch"
+
+
+def test_key_status_reports_unknown_when_no_local_pubkey():
+    status = r.key_status(**_kw(local_pubkey=None, local_exists=False))
+    assert status.locations[0].status == "unknown"
+    assert status.local_fingerprint is None
+
+
+def test_key_status_never_carries_a_local_fingerprint_when_key_absent():
+    status = r.key_status(**_kw(local_pubkey=None, local_exists=False))
+    assert status.local_exists is False
+    assert status.local_fingerprint is None
+
+
+def test_key_status_fingerprint_matches_fingerprint_pubkey_helper():
+    pub = b"\x03" * 32
+    status = r.key_status(**_kw(local_pubkey=pub, locations=[("x", [pub])]))
+    assert status.local_fingerprint == r.fingerprint_pubkey(pub)
+
+
+def test_key_status_checks_multiple_locations_independently():
+    """A key can match one committed location and mismatch another -- this
+    is exactly the drift issue #68 finding 4 was about (bcc_core.py and
+    ci.yml silently disagreeing on the trust anchor)."""
+    pub = b"\x04" * 32
+    other = b"\x05" * 32
+    status = r.key_status(
+        **_kw(
+            local_pubkey=pub,
+            locations=[
+                ("bcc_core.CATALOG_PUBKEYS", [pub]),
+                ("ci.yml trust anchor", [other]),
+            ],
+        )
+    )
+    assert status.locations[0].status == "match"
+    assert status.locations[1].status == "mismatch"
+
+
+def test_recommend_next_steps_flags_never_generated_key():
+    status = r.key_status(**_kw(local_exists=False, local_pubkey=None, locations=[]))
+    steps = r.recommend_next_steps([status])
+    assert any("keygen" in s and "CATALOG" in s for s in steps)
+
+
+def test_recommend_next_steps_release_key_uses_release_flag():
+    status = r.key_status(
+        kind="release",
+        display_name="RELEASE",
+        purpose="Signs checksums.",
+        private_key_location="not generated yet",
+        local_exists=False,
+        local_pubkey=None,
+        locations=[],
+    )
+    steps = r.recommend_next_steps([status])
+    assert any("keygen --release" in s for s in steps)
+
+
+def test_recommend_next_steps_flags_mismatch_by_location_name():
+    status = r.key_status(**_kw(locations=[("bcc_core.CATALOG_PUBKEYS", [b"\x99" * 32])]))
+    steps = r.recommend_next_steps([status])
+    assert any("bcc_core.CATALOG_PUBKEYS" in s and "CATALOG" in s for s in steps)
+
+
+def test_recommend_next_steps_flags_invalid_catalog_signature():
+    status = r.key_status(**_kw(catalog_sig_status="invalid"))
+    steps = r.recommend_next_steps([status])
+    assert any("re-signing" in s for s in steps)
+
+
+def test_recommend_next_steps_flags_missing_catalog_signature():
+    status = r.key_status(**_kw(catalog_sig_status="missing"))
+    steps = r.recommend_next_steps([status])
+    assert any("re-signing" in s for s in steps)
+
+
+def test_recommend_next_steps_all_clear_when_nothing_wrong():
+    status = r.key_status(**_kw())
+    steps = r.recommend_next_steps([status])
+    assert steps == ["Everything is consistent -- no action needed."]
+
+
+def test_recommend_next_steps_release_key_has_no_catalog_signature_advice():
+    """A mismatched RELEASE key must never trigger catalog-signing advice --
+    the two keys' remediation paths must not bleed into each other."""
+    status = r.key_status(
+        kind="release",
+        display_name="RELEASE",
+        purpose="Signs checksums.",
+        private_key_location="on this machine",
+        local_exists=True,
+        local_pubkey=b"\x06" * 32,
+        locations=[("scripts/sign_checksums.py RELEASE_PUBKEYS", [b"\x07" * 32])],
+        catalog_sig_status=None,
+    )
+    steps = r.recommend_next_steps([status])
+    assert not any("re-signing" in s for s in steps)
+    assert any("RELEASE" in s for s in steps)
+
+
+def test_render_key_status_report_never_prints_private_key_material():
+    """The report string must be built ONLY from public inputs. Sanity
+    check: no field on KeyStatus/PubkeyLocationCheck is capable of holding
+    private key bytes in the first place (there's no such field to leak),
+    and the render function only touches fields that exist -- this test
+    guards against a future field addition reintroducing that risk."""
+    status = r.key_status(**_kw())
+    text = r.render_key_status_report([status])
+    assert "CATALOG" in text
+    assert (
+        "purpose" not in text.lower() or "Signs the catalog." in text
+    )  # sanity, not a real secret
+    # No 64-hex-char (or longer) run anywhere -- a raw 32-byte seed/sig
+    # would show up as one if it were ever accidentally interpolated in.
+    import re as _re
+
+    assert not _re.search(r"[0-9a-fA-F]{64,}", text)
+
+
+def test_render_key_status_report_names_the_specific_key_not_generic_the_key():
+    status = r.key_status(**_kw())
+    text = r.render_key_status_report([status])
+    assert "CATALOG KEY" in text
+    assert "the key" not in text.lower()
+
+
+def test_render_key_status_report_includes_catalog_signature_line_only_for_catalog():
+    catalog_status = r.key_status(**_kw())
+    release_status = r.key_status(
+        kind="release",
+        display_name="RELEASE",
+        purpose="Signs checksums.",
+        private_key_location="on this machine",
+        local_exists=True,
+        local_pubkey=b"\x08" * 32,
+        locations=[("scripts/sign_checksums.py RELEASE_PUBKEYS", [b"\x08" * 32])],
+        catalog_sig_status=None,
+    )
+    text = r.render_key_status_report([catalog_status, release_status])
+    assert text.count("Catalog signature:") == 1
+
+
+def test_render_key_status_report_ends_with_what_to_do_next_section():
+    status = r.key_status(**_kw())
+    text = r.render_key_status_report([status])
+    assert "What to do next:" in text
@@ -2357,43 +2357,6 @@ def test_catalog_entry_to_paste_json_includes_env_when_present():
    assert c.validate_catalog(malicious) != []


-def test_catalog_entry_to_paste_json_seeds_env_required_keys():
-    # Regression: env_required is where the seed data actually keeps its
-    # secret VAR NAMES (postgres/github/notion/etc. all declare their secret
-    # here with config.env left empty) -- catalog_entry_to_paste_json must
-    # surface those names as blank env rows, not silently drop them.
-    entry = _minimal_catalog()["servers"][0]
-    entry["env_required"] = {"DATABASE_URI": ""}
-    result = c.catalog_entry_to_paste_json(entry)
-    assert result["widget"]["env"] == {"DATABASE_URI": ""}
-
-
-def test_catalog_entry_to_paste_json_config_env_wins_over_env_required_default():
-    entry = _minimal_catalog()["servers"][0]
-    entry["config"]["env"] = {"GRAFANA_URL": "<GRAFANA_URL>"}
-    entry["env_required"] = {"GRAFANA_URL": "", "GRAFANA_SERVICE_ACCOUNT_TOKEN": ""}
-    result = c.catalog_entry_to_paste_json(entry)
-    assert result["widget"]["env"] == {
-        "GRAFANA_URL": "<GRAFANA_URL>",
-        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "",
-    }
-
-
-def test_catalog_entry_to_paste_json_real_postgres_entry_seeds_database_uri():
-    """End-to-end regression against the actual shipped postgres entry,
-    which needs DATABASE_URI via env_required and has no config.env at
-    all -- this is exactly the shape that was silently dropping the env
-    field before catalog_entry_to_paste_json accounted for env_required."""
-    root = Path(__file__).resolve().parent.parent
-    raw = (root / "data" / "catalog.json").read_bytes()
-    data = c.load_catalog(raw)
-    entry = next(s for s in data["servers"] if s["id"] == "postgres")
-    result = c.catalog_entry_to_paste_json(entry)
-    assert result["postgres"]["env"] == {"DATABASE_URI": ""}
-    # And the focus-target helper now has something to point the user at.
-    assert c.first_unfilled_focus_target(result["postgres"]) == ("env", "DATABASE_URI")
-
-
 def test_config_has_unfilled_placeholders_true_for_token():
    cfg = {"command": "npx", "args": ["-y", "server", "<ALLOWED_DIR>"]}
    assert c.config_has_unfilled_placeholders(cfg) is True
@@ -2407,310 +2370,3 @@ def test_config_has_unfilled_placeholders_false_after_fill():
 def test_config_has_unfilled_placeholders_checks_env_too():
    cfg = {"command": "uvx", "args": ["mcp-grafana"], "env": {"GRAFANA_URL": "<GRAFANA_URL>"}}
    assert c.config_has_unfilled_placeholders(cfg) is True
-
-
-# --------------------------------------------------------------------------- #
-# Browse-catalog dialog helpers (issue #10 phase 2)
-# --------------------------------------------------------------------------- #
-
-
-# --- catalog_category_group / CATALOG_CATEGORY_GROUPS --------------------- #
-@pytest.mark.parametrize(
-    "category,expected_group",
-    [
-        ("files", "Files & Dev"),
-        ("dev", "Files & Dev"),
-        ("code-hosting", "Files & Dev"),
-        ("browser", "Files & Dev"),
-        ("database", "Data"),
-        ("data", "Data"),
-        ("search", "Search & AI"),
-        ("ai", "Search & AI"),
-        ("cloud", "Cloud & Infra"),
-        ("infra", "Cloud & Infra"),
-        ("observability", "Cloud & Infra"),
-        ("productivity", "Work"),
-        ("communication", "Work"),
-        ("crm", "Work"),
-        ("finance", "Work"),
-        ("design", "Work"),
-        ("media", "Home & Personal"),
-        ("smart-home", "Home & Personal"),
-        ("personal", "Home & Personal"),
-    ],
-)
-def test_catalog_category_group_maps_every_taxonomy_value(category, expected_group):
-    assert c.catalog_category_group(category) == expected_group
-
-
-def test_catalog_category_group_unknown_falls_back_to_other():
-    assert c.catalog_category_group("some-future-category-nobody-has-seen-yet") == "Other"
-    assert c.catalog_category_group("") == "Other"
-    assert c.catalog_category_group(None) == "Other"
-
-
-def test_catalog_category_group_is_case_insensitive():
-    assert c.catalog_category_group("Files") == "Files & Dev"
-    assert c.catalog_category_group("DATABASE") == "Data"
-
-
-def test_shipped_catalog_categories_all_have_a_known_group():
-    """Regression: every category actually used in data/catalog.json must
-    collapse to one of the 7 chips, never silently drop an entry."""
-    root = Path(__file__).resolve().parent.parent
-    raw = (root / "data" / "catalog.json").read_bytes()
-    data = c.load_catalog(raw)
-    for entry in data["servers"]:
-        group = c.catalog_category_group(entry["category"])
-        assert group in c.CATALOG_CATEGORY_CHIPS
-
-
-# --- catalog_entry_matches_query / filter_catalog_entries ------------------ #
-def _catalog_entries():
-    return [
-        {
-            "id": "filesystem",
-            "display": "Filesystem",
-            "description": "Read/write access to local directories you choose.",
-            "category": "files",
-        },
-        {
-            "id": "postgres",
-            "display": "Postgres MCP Pro",
-            "description": "Query and inspect a PostgreSQL database.",
-            "category": "database",
-        },
-        {
-            "id": "slack",
-            "display": "Slack",
-            "description": "Search messages and send messages from your assistant.",
-            "category": "communication",
-        },
-    ]
-
-
-def test_catalog_entry_matches_query_empty_matches_everything():
-    entries = _catalog_entries()
-    assert c.filter_catalog_entries(entries, "") == entries
-    assert c.filter_catalog_entries(entries, "   ") == entries
-
-
-def test_catalog_entry_matches_query_matches_id():
-    result = c.filter_catalog_entries(_catalog_entries(), "postgres")
-    assert [e["id"] for e in result] == ["postgres"]
-
-
-def test_catalog_entry_matches_query_matches_display_case_insensitive():
-    result = c.filter_catalog_entries(_catalog_entries(), "SLACK")
-    assert [e["id"] for e in result] == ["slack"]
-
-
-def test_catalog_entry_matches_query_matches_description():
-    result = c.filter_catalog_entries(_catalog_entries(), "PostgreSQL database")
-    assert [e["id"] for e in result] == ["postgres"]
-
-
-def test_catalog_entry_matches_query_matches_category():
-    result = c.filter_catalog_entries(_catalog_entries(), "database")
-    assert [e["id"] for e in result] == ["postgres"]
-
-
-def test_catalog_entry_matches_query_no_match_returns_empty():
-    assert c.filter_catalog_entries(_catalog_entries(), "kubernetes") == []
-
-
-def test_catalog_entries_in_group_all_returns_everything():
-    entries = _catalog_entries()
-    assert c.catalog_entries_in_group(entries, "All") == entries
-    assert c.catalog_entries_in_group(entries, "") == entries
-    assert c.catalog_entries_in_group(entries, None) == entries
-
-
-def test_catalog_entries_in_group_filters_by_collapsed_category():
-    result = c.catalog_entries_in_group(_catalog_entries(), "Data")
-    assert [e["id"] for e in result] == ["postgres"]
-
-    result = c.catalog_entries_in_group(_catalog_entries(), "Work")
-    assert [e["id"] for e in result] == ["slack"]
-
-
-# --- format_freshness_hint -------------------------------------------------- #
-def test_format_freshness_hint_none_returns_empty_string():
-    assert c.format_freshness_hint(None) == ""
-    assert c.format_freshness_hint("") == ""
-
-
-def test_format_freshness_hint_unparseable_returns_empty_string():
-    assert c.format_freshness_hint("not-a-date") == ""
-
-
-def test_format_freshness_hint_this_month():
-    assert (
-        c.format_freshness_hint("2026-07-01", today=c.date(2026, 7, 12))
-        == "Last updated this month"
-    )
-
-
-def test_format_freshness_hint_one_month_singular():
-    assert (
-        c.format_freshness_hint("2026-06-01", today=c.date(2026, 7, 12))
-        == "Last updated 1 month ago"
-    )
-
-
-def test_format_freshness_hint_months_ago():
-    # Exactly 14 full months elapsed, no day-of-month remainder to round off.
-    assert (
-        c.format_freshness_hint("2025-01-15", today=c.date(2026, 3, 15))
-        == "Last updated 14 months ago"
-    )
-
-
-def test_format_freshness_hint_rounds_down_partial_month():
-    # 2025-05-16 -> 2026-07-12 is 13 full months, not 14: the 14th month
-    # would only complete on 2026-07-16.
-    assert (
-        c.format_freshness_hint("2025-05-16", today=c.date(2026, 7, 12))
-        == "Last updated 13 months ago"
-    )
-
-
-def test_format_freshness_hint_years_ago():
-    assert (
-        c.format_freshness_hint("2024-01-01", today=c.date(2026, 7, 12))
-        == "Last updated 2 years ago"
-    )
-
-
-def test_format_freshness_hint_23_months_stays_in_months_not_years():
-    # The switch to "N years ago" happens at 24 full months, not 12 -- the
-    # whole point of this hint is the granular "14 months ago" phrasing the
-    # design comment on #10 asked for, so 13-23 months must stay in months.
-    assert (
-        c.format_freshness_hint("2024-08-12", today=c.date(2026, 7, 12))
-        == "Last updated 23 months ago"
-    )
-
-
-def test_format_freshness_hint_future_date_returns_empty_string():
-    # A last_release "in the future" relative to `today` is nonsensical --
-    # show nothing rather than a misleading negative offset.
-    assert c.format_freshness_hint("2027-01-01", today=c.date(2026, 7, 12)) == ""
-
-
-# --- first_unfilled_focus_target -------------------------------------------- #
-def test_first_unfilled_focus_target_prefers_placeholder_arg():
-    data = {
-        "command": "npx",
-        "args": ["-y", "server", "<ALLOWED_DIR>"],
-        "env": {"API_KEY": ""},
-    }
-    assert c.first_unfilled_focus_target(data) == ("args", 2)
-
-
-def test_first_unfilled_focus_target_falls_back_to_first_blank_env():
-    data = {"command": "uvx", "args": ["mcp-grafana"], "env": {"GRAFANA_URL": ""}}
-    assert c.first_unfilled_focus_target(data) == ("env", "GRAFANA_URL")
-
-
-def test_first_unfilled_focus_target_none_when_fully_filled():
-    data = {"command": "npx", "args": ["-y", "server"], "env": {"API_KEY": "sk-real-value"}}
-    assert c.first_unfilled_focus_target(data) is None
-
-
-def test_first_unfilled_focus_target_none_for_config_with_no_env_or_args():
-    assert c.first_unfilled_focus_target({"command": "npx", "args": []}) is None
-
-
-# --- load_bundled_catalog_entries ------------------------------------------- #
-def test_load_bundled_catalog_entries_valid_signature(tmp_path, monkeypatch):
-    priv = Ed25519PrivateKey.generate()
-    pub = priv.public_key().public_bytes_raw()
-    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
-
-    raw, sig = _signed(_minimal_catalog(version=1), priv)
-    catalog_path = tmp_path / "catalog.json"
-    sig_path = tmp_path / "catalog.json.sig"
-    catalog_path.write_bytes(raw)
-    sig_path.write_bytes(sig)
-
-    entries = c.load_bundled_catalog_entries(catalog_path, sig_path)
-    assert len(entries) == 1
-    assert entries[0]["id"] == "widget"
-
-
-def test_load_bundled_catalog_entries_tampered_payload_returns_empty_list(tmp_path, monkeypatch):
-    priv = Ed25519PrivateKey.generate()
-    pub = priv.public_key().public_bytes_raw()
-    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
-
-    raw, sig = _signed(_minimal_catalog(version=1), priv)
-    tampered = bytearray(raw)
-    tampered[-2] ^= 0xFF  # flip a byte inside the trailing bytes, still valid-ish JSON shape
-    catalog_path = tmp_path / "catalog.json"
-    sig_path = tmp_path / "catalog.json.sig"
-    catalog_path.write_bytes(bytes(tampered))
-    sig_path.write_bytes(sig)
-
-    assert c.load_bundled_catalog_entries(catalog_path, sig_path) == []
-
-
-def test_load_bundled_catalog_entries_wrong_key_returns_empty_list(tmp_path, monkeypatch):
-    priv = Ed25519PrivateKey.generate()
-    other_priv = Ed25519PrivateKey.generate()
-    other_pub = other_priv.public_key().public_bytes_raw()
-    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [other_pub])
-
-    raw, sig = _signed(_minimal_catalog(version=1), priv)  # signed by the WRONG key
-    catalog_path = tmp_path / "catalog.json"
-    sig_path = tmp_path / "catalog.json.sig"
-    catalog_path.write_bytes(raw)
-    sig_path.write_bytes(sig)
-
-    assert c.load_bundled_catalog_entries(catalog_path, sig_path) == []
-
-
-def test_load_bundled_catalog_entries_missing_files_returns_empty_list(tmp_path):
-    assert c.load_bundled_catalog_entries(tmp_path / "nope.json", tmp_path / "nope.json.sig") == []
-
-
-def test_load_bundled_catalog_entries_missing_sig_returns_empty_list(tmp_path, monkeypatch):
-    priv = Ed25519PrivateKey.generate()
-    pub = priv.public_key().public_bytes_raw()
-    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
-
-    raw, _sig = _signed(_minimal_catalog(version=1), priv)
-    catalog_path = tmp_path / "catalog.json"
-    catalog_path.write_bytes(raw)
-    missing_sig_path = tmp_path / "catalog.json.sig"  # never written
-
-    assert c.load_bundled_catalog_entries(catalog_path, missing_sig_path) == []
-
-
-def test_load_bundled_catalog_entries_invalid_but_signed_returns_empty_list(tmp_path, monkeypatch):
-    """A payload that verifies but fails validate_catalog() (disallowed
-    command) must still come back empty -- signing is necessary, not
-    sufficient."""
-    priv = Ed25519PrivateKey.generate()
-    pub = priv.public_key().public_bytes_raw()
-    monkeypatch.setattr(c, "CATALOG_PUBKEYS", [pub])
-
-    raw, sig = _signed(_catalog_with({"config": {"command": "bash", "args": []}}), priv)
-    catalog_path = tmp_path / "catalog.json"
-    sig_path = tmp_path / "catalog.json.sig"
-    catalog_path.write_bytes(raw)
-    sig_path.write_bytes(sig)
-
-    assert c.load_bundled_catalog_entries(catalog_path, sig_path) == []
-
-
-def test_load_bundled_catalog_entries_real_shipped_catalog():
-    """End-to-end regression against the actual bundled data/catalog.json +
-    .sig, using the real CATALOG_PUBKEYS (no monkeypatch) -- this is what
-    the Browse dialog actually calls on startup."""
-    root = Path(__file__).resolve().parent.parent
-    entries = c.load_bundled_catalog_entries(
-        root / "data" / "catalog.json", root / "data" / "catalog.json.sig"
-    )
-    assert len(entries) == 19
-    assert {e["id"] for e in entries} >= {"filesystem", "github", "slack", "postgres"}