feat: macOS menubar GUI (Phase 8) + config-management UX, docs restructure, sudo auto-elevation

[Behnam-RK]

Scope note: this branch started as Phase 8 (macOS menubar GUI) and grew to
include a docs restructure, a config-management UX overhaul, and sudo
auto-elevation. Each is an independent, separately-committed change; see the
commit list. Original Phase 8 write-up is preserved below, followed by the
follow-on work.

---

Part 1 — macOS menubar GUI + daemon state export (Phase 8)

Adds a macOS-only menubar app (Dezhban.app) for at-a-glance status and
click-to-control of the kill switch, plus the daemon-side state export it
reads. Implements docs/plans/phase-8-macos-gui.md.

Daemon: live state file (Go, cross-platform, stdlib-only)

• internal/state — Snapshot type + atomic writer (temp-file + rename,
  0644 world-readable) and reader. Path: /var/db/dezhban/state.json (unix) /
  %ProgramData%\dezhban\state.json (Windows).
• internal/runner — injected Publish func(state.Snapshot) callback
  (nil = no-op). Publishes on every poll, verdict transition, tunnel edge,
  endpoint refresh, and at startup. Best-effort: a write failure never affects
  enforcement.
• cmd/dezhban — defaultStatePath(), wires Publish into the real run
  path only, adds status --json merging snapshot + service/config status.

Swift menubar app (macos-gui/, AppKit + ServiceManagement only)

• NSStatusItem SF-Symbol icon (🟢 allow/guard, 🔴 block/full-block, ⚪
  stopped/stale-after-90s), 1s state-file poll, snapshot-driven menu.
• Start/Stop, Block/Unblock via the native osascript admin prompt; Launch at
  login via SMAppService; VPN-mode indicator + Open config.
• SwiftPM + build-app.sh → dist/Dezhban.app; make gui-macos.

Deviations from plan: SwiftPM + bundling script instead of an Xcode project
(build box has only Command Line Tools); VPN-mode live toggle deferred (a blind
vpn.enabled flip fails config.Validate()) — menu routes to Open config….

---

Part 2 — Docs split + VPN-primary repositioning (26c9ca2)

• Repositioning (docs only — no code/behavior/CLI/JSON changes): the always-on
  VPN interface guard is now framed as the primary/recommended mode and
  country-blocklisting as the fallback. vpn.enabled still defaults to false
  as a documented safety opt-in.
• Split the oversized README.md (346 → ~80 lines) and CLAUDE.md (205 → ~75)
  into focused docs under docs/ (modes, architecture, usage,
  development, safety, plus an index). Renamed existing docs to lower
  kebab-case; repointed every reference; removed the generic MCP tooling policy
  that duplicated the user's global config.

Part 3 — Config-management UX (a8c8be3)

• --config is now optional — resolved from the flag → $DEZHBAN_CONFIG →
  system path (/etc/dezhban/dezhban.json) → built-in defaults. dezhban config path prints the winner.
• internal/config gains a writer (Marshal/Save; durations round-trip as
  "30s"; round-trip tested).
• New commands: dezhban setup (interactive charmbracelet/huh wizard —
  reuses tunnel detection, the endpoint lockout check, and a print-rules
  preview before saving; guarded against non-TTY); dezhban config path/show/get/set/edit; dezhban completion bash|zsh|fish.
• Dependency: adds charmbracelet/huh as a second direct dependency (setup
  wizard only; daemon/enforcement path stays stdlib). CLAUDE.md's dependency
  convention updated to record it.

Part 4 — sudo auto-elevation (1d9deaa)

• Privileged commands auto-re-exec under sudo when not root (unix +
  interactive TTY), preserving $DEZHBAN_CONFIG. setup and config set/edit
  elevate just their config write. Opt out with --no-sudo or
  DEZHBAN_NO_SUDO=1. Windows and non-TTY contexts keep the clear "must run as
  root" error (terminal detected via IsTerminal, not ModeCharDevice).

---

Verification

• go build / go vet clean; go test ./... → 80 pass (adds internal/config
  Save↔Load round-trip + validation tests); host and Windows cross-builds;
  make build-all cross-compiles all 5 targets (with huh); gofmt clean;
  pre-commit hooks green.
• Config UX exercised: path discovery ($DEZHBAN_CONFIG + system path), config set/get/show/path, completion, non-TTY setup guard.
• sudo auto-elevation confirmed interactively — password prompt + successful
  unblock; --no-sudo falls back to the plain root error.
• Still needs a root + logged-in GUI session (Part 1): live daemon →
  state-file → icon flip, admin-prompt actions, login-item registration. Steps in
  the phase doc.

To try locally: make gui-macos && open dist/Dezhban.app, then
sudo ./dezhban run --config configs/dezhban.dev.json --simulate-country IR to
watch the icon flip.

🤖 Generated with Claude Code