better-claude-config/HANDOFF.md

# HANDOFF — BCC feature backlog implementation

For the Claude Code agent working in this repo. Read this whole file, then
CLAUDE.md, before touching code. A supervising Claude session watches this
project through the Gitea MCP (issues, PRs, CI runs on git.avezzano.io), so
keep all state in Gitea where it can be seen: issues for work items, PRs for
changes, comments for decisions.

## Step 0 — sync state

`main` may contain local commits that aren't on origin yet (the previous
session couldn't push). Run `git status` / `git log origin/main..main`; if
there are unpushed commits, **push them first** and confirm CI goes green
before starting anything.

## Step 1 — file the backlog as issues

Create one Gitea issue per item in the backlog table below (`tea` CLI or the
API — you have full credentials). Prefix titles with the ID (e.g.
"[#2] Stdio server spawn-test"). Create labels P0/P1/P2 first if they don't
exist. Copy each item's full section from `../bcc-feature-requests.md`
(sibling of this repo folder) into the issue body — it has problem statements,
evidence, proposed fixes, and acceptance criteria.

**Corrections to that document — do not re-implement:**
- "Doc correction: README Claude Code path" — DONE (commit `b16c0fd`).
- Item 1 (secret masking) — MOSTLY DONE (commit `6dee318`): env/header values
  masked via delegate + Show-secrets toggle, Add-dialog password echo,
  diagnostics args redaction (`redact_args`). **Only remainder:** the warning
  badge when a secret-shaped value sits in `args` instead of `env`. File the
  issue scoped to just that.

## Step 2 — work the backlog

| Order | ID | Item | Priority | Notes |
|---|---|---|---|---|
| 1 | 2 | Stdio server spawn-test | P0 | Spawn with timeout, capture stderr; core logic in bcc_core (GUI-free, testable) |
| 2 | 3 | Backup restore UI | P0 | List `.bcc_backups/`, preview/diff, restore through normal atomic-write path |
| 3 | 4 | Stale-file protection | P0 | mtime/hash at load, re-check before write, prompt on conflict |
| 4 | 1r | Secret-in-args warning badge | P0 | Remainder of item 1; `is_secret_key`/`_is_secret_value` already exist in bcc_core |
| 5 | 8 | Duplicate-name conflict on paste/import | P1 | VERIFY FIRST: check `paste_json`/`dropEvent` in bcc.py for silent overwrite; file findings on the issue before coding |
| 6 | 5 | Cross-client support (Cursor/Windsurf/VS Code) | P1 | VS Code uses `servers` not `mcpServers` — needs a read/write adapter, not just paths |
| 7 | 6 | In-app MCP log viewer | P1 | Platform log paths in the doc |
| 8 | 7 | Windows MSIX path detection | P1 | Can't test locally on macOS — unit-test the detection logic, note that in the PR |
| 9 | 9 | Restart Claude Desktop button | P1 | Platform-specific process handling; scope to Desktop only |
| 10 | 10 | Server catalog / one-click add | P2 | Design pass first — post a proposal as an issue comment before building |

## Workflow rules

- **Branch per issue** off `main`: `feat/<issue-number>-short-slug` (or
  `fix/`). One issue per PR. Reference the issue in the PR description
  (`Closes #N`).
- **Before every commit:** `python -m pytest` (all green), `ruff check .`,
  `ruff format .`. CI enforces all three.
- **Conventional commits** (`feat:`, `fix:`, `test:`, `docs:`, `chore:`) —
  match the existing history's style: body explains the why.
- **Merge only with green CI.** If the supervising session has flagged
  something on the PR, resolve it before merging.

## Architecture guardrails (violating these fails review)

1. **The cardinal rule:** config writes only ever touch `mcpServers` and
   `_disabledMcpServers`. Every other key is preserved verbatim, in order.
   This matters extra for `~/.claude.json`, which holds conversation history
   and project state.
2. **Core/GUI split:** all logic in `bcc_core.py` (no GUI imports, unit-
   testable); `bcc.py` stays a thin PySide6 shell. New logic gets tests in
   `tests/` — they run without PySide6, keep it that way.
3. **No new runtime dependencies** without posting the justification on the
   issue first. PySide6 is currently the only one.
4. **Writes are atomic + backed up** — route any new disk writes through
   `write_config()`.
5. Secrets never appear in diagnostics output or logs — use `redact_args`/
   `is_secret_key` from bcc_core.

## Current state (as of this handoff)

- 58 tests in `tests/`, ruff clean, CI = lint + pytest (py3.10/3.12) on push/PR.
- Recent features you should know exist: lenient JSON repair
  (`repair_json_text`, `parse_pasted_json_verbose`, `repair_config_file` +
  RepairDialog), ArgsEdit numbered gutter + `split_suspicious_args`,
  resizable splitters with QSettings persistence, secret masking, Claude Code
  profile at `~/.claude.json` (settings.json only as "legacy" when it holds
  parked servers).
- GUI can't be smoke-tested in CI; note in each PR whether you ran
  `python bcc.py` locally and what you checked.