|
| 1 | +# Personal-Edition Polish Initiative |
| 2 | + |
| 3 | +**Started**: 2026-06-30 · **Owner**: Algis · **Status**: active (vertical 1 in progress) |
| 4 | + |
| 5 | +> Durable brief for the personal-edition polish push. This is the master doc that |
| 6 | +> survives a context clean — it captures **intent, scope, decisions, and the |
| 7 | +> existing foundation** for each of the 5 verticals so any future session can |
| 8 | +> resume a vertical cold. Live status/DAG is in [`../roadmap.yaml`](../roadmap.yaml) |
| 9 | +> (rendered to [`../ROADMAP.md`](../ROADMAP.md)). Each vertical gets its own |
| 10 | +> grounded `/speckit` brainstorm + spec when we reach it. |
| 11 | +
|
| 12 | +## North star |
| 13 | + |
| 14 | +Make the **personal edition** so simple and reliable that developers tell their |
| 15 | +teammates about it. Three themes cut across everything: **simpler, more reliable, |
| 16 | +more transparent.** Paid-tier and server-edition work are **on hold** (minimal |
| 17 | +priority) until this push lands. |
| 18 | + |
| 19 | +## Sequencing |
| 20 | + |
| 21 | +`ux-audit` (5) is a cross-cutting discovery pass that feeds 2/3/4. We chose to |
| 22 | +start with **Scanner + Quarantine (1)** — highest user pain, and Spec 076's |
| 23 | +detect engine gave us a foundation. Rough order: **1 → (5 discovery) → 3 / 2 / 4**. |
| 24 | +Priorities in `roadmap.yaml`: ux-audit P0, action-log P0, scanner/analytics/ |
| 25 | +registries P1. |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +## Vertical 1 — Scanner + Quarantine simplification ✅ IN PROGRESS |
| 30 | + |
| 31 | +**Goal**: One simple, reliable, deterministic scanner that works offline with |
| 32 | +zero Docker; demote the third-party-scanner mess to opt-in; single unified report. |
| 33 | + |
| 34 | +**Status**: Spec written — [`specs/077-scanner-simplification/spec.md`](../specs/077-scanner-simplification/spec.md), |
| 35 | +branch `077-scanner-simplification`. Next: `/speckit.plan`. |
| 36 | + |
| 37 | +**Decisions (locked)**: See the spec + memory `project-personal-edition-polish-initiative`. |
| 38 | +Summary: baseline = Spec 076 detect engine (always-on, offline); delete duplicate |
| 39 | +legacy `tpaRules` + legacy embedded-secret path; new **hard-tier `phrase_injection`** |
| 40 | +check preserves blocking posture for curated high-confidence phrases (rest stay |
| 41 | +soft/review-only); Docker scanners + source extraction → opt-in `security.deep_scan` |
| 42 | +(off by default, never blocks/degrades baseline); single merged report via existing |
| 43 | +`ScanFinding`/`ScanSummary`/`CalculateRiskScore` with cross-scanner consensus; |
| 44 | +baseline-only verdict; collapse MCP-2207 notification storm; remove orphaned |
| 45 | +`auto_scan_quarantined`. **Out of scope**: removing Docker plugins, touching the |
| 46 | +quarantine state machine, registry redesign. |
| 47 | + |
| 48 | +**Foundation**: `internal/security/detect/` (Spec 076), `internal/security/scanner/` |
| 49 | +(`inprocess.go`, `engine.go`, `docker.go`), `internal/runtime/tool_quarantine.go` |
| 50 | +(unchanged). Docs: `docs/features/tool-scanner.md`, `docs/features/security-scanner-plugins.md`. |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +## Vertical 2 — Action Log / Transparency (backlog, P0) |
| 55 | + |
| 56 | +**Goal**: Make the activity/action log genuinely usable — the most important |
| 57 | +signals (security, connection health, recent tool calls, errors) **at a glance**, |
| 58 | +not buried. Transparency is a core selling point. |
| 59 | + |
| 60 | +**Scope (intent)**: An at-a-glance action-log view surfacing top signals + health; |
| 61 | +tie in retention/size so the view stays fast and bounded. **Out (for now)**: SIEM |
| 62 | +export (parked epic `siem`), deep forensic tooling. |
| 63 | + |
| 64 | +**Existing foundation** (substantial): |
| 65 | +- `specs/019-activity-webui` — **shipped 73/73**. The activity Web UI already exists. |
| 66 | +- `specs/024-expand-activity-log` — **~95% (63/66)**. Activity-log backend/expansion. |
| 67 | +- `specs/073-activity-size-retention` — drafted (0/14). Retention/size work not started. |
| 68 | +- Code: `internal/httpapi/activity.go` (JSONL), activity CLI (`mcpproxy activity …`), |
| 69 | + SSE `/events`. Every response carries `X-Request-Id` for correlation. |
| 70 | + |
| 71 | +**Open questions to brainstorm when we start**: What are the "top signals" worth |
| 72 | +promoting (security findings, disconnects, denied calls, sensitive-data hits)? |
| 73 | +Is this a new default panel or a redesign of the existing activity view? How does |
| 74 | +it relate to the analytics dashboard (vertical 3) — same landing surface? |
| 75 | + |
| 76 | +--- |
| 77 | + |
| 78 | +## Vertical 3 — Analytics Dashboard as default page (backlog, P1) |
| 79 | + |
| 80 | +**Goal**: Make a **graph-first dashboard the default landing page**; show **which |
| 81 | +server / which tool drains tokens** (and calls/latency/errors), so users see value |
| 82 | +and cost at a glance. |
| 83 | + |
| 84 | +**Scope (intent)**: Per-server and per-tool token-drain graphs; promote the |
| 85 | +dashboard to the default route. **Out**: full BI/exports, cross-instance |
| 86 | +aggregation. |
| 87 | + |
| 88 | +**Existing foundation** (partial — good starting point): |
| 89 | +- `specs/069-observability-usage-graphs` — **in-flight ~62% (16/26)**. Usage-graph |
| 90 | + work already underway; the token/usage metrics likely exist. |
| 91 | +- `specs/039-connect-and-dashboard` — Approved, no tasks yet. The dashboard/connect |
| 92 | + surface concept. |
| 93 | +- Metrics context: `mcpproxy_tool_calls_total{server,tool,status}` (cardinality-safe; |
| 94 | + user_id/profile are span attrs, not labels — see memory `mcp3207…`). OTLP spans |
| 95 | + carry richer per-call attributes. |
| 96 | + |
| 97 | +**Open questions**: Where do per-tool **token** counts come from today (are tokens |
| 98 | +measured per call, or estimated)? Is 069 close enough to extend, or does the |
| 99 | +default-landing change belong to 039? What's the default time window / granularity? |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +## Vertical 4 — Registries: easier search + add-server (backlog, P1) |
| 104 | + |
| 105 | +**Goal**: Lower the friction of **finding a server in a registry and adding it** — |
| 106 | +better search, one-click add. |
| 107 | + |
| 108 | +**Scope (intent)**: Improved registry search UX; frictionless add-server flow, |
| 109 | +leaning on the official registry protocol. **Out**: marketplace metadata/telemetry |
| 110 | +(parked epic `marketplace`), custom private-registry hardening. |
| 111 | + |
| 112 | +**Existing foundation**: |
| 113 | +- `specs/071-official-registry-protocol` — **Implemented 12/12**. Official registry |
| 114 | + protocol integration is done — build on it. |
| 115 | +- `specs/070-registry-easy-upstream-add` — **early (3/24)**. The easy-add work is |
| 116 | + mostly unstarted — this is where most of the vertical lives. |
| 117 | +- Code: `Repositories.vue`, `add_from_registry.go`, `search_servers`/`list_registries` |
| 118 | + MCP tools. ~60% of a marketplace already ships (browse/search/one-click add). |
| 119 | + |
| 120 | +**Open questions**: What's the current search's weakness (ranking? filters? |
| 121 | +discoverability?)? Is "add server" friction in the UI flow, the quarantine gate, or |
| 122 | +config plumbing? Web UI only, or tray deep-links too? |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Vertical 5 — UX audit (Web UI + macOS app) (backlog, P0, cross-cutting) |
| 127 | + |
| 128 | +**Goal**: A grounded, end-to-end UX pass across the **Web UI** and the **macOS tray |
| 129 | +app** — the umbrella/discovery step that feeds concrete findings into verticals 2–4. |
| 130 | + |
| 131 | +**Scope (intent)**: Heuristic + Playwright UX sweep of the Web UI; a macOS tray UX |
| 132 | +sweep (settings parity, core flows). Produce a prioritized findings list, not a |
| 133 | +redesign. **Out**: net-new features (those become their own verticals). |
| 134 | + |
| 135 | +**Existing foundation / tooling**: |
| 136 | +- `specs/064-glass-cockpit` — **Planned (spec + plan complete)**, no tasks. This is |
| 137 | + the likely home/umbrella for the UX vision. |
| 138 | +- `specs/037-macos-swift-tray` — Draft. macOS tray. |
| 139 | +- Tooling ready: Playwright Web-UI verification (`docs/development/web-ui-verification.md`), |
| 140 | + `mcpproxy-ui-test` MCP (macOS tray a11y), `claude-in-chrome` + `computer-use` MCPs, |
| 141 | + the `mcpproxy-qa` skill. |
| 142 | + |
| 143 | +**Open questions**: Run the audit *first* (before 2–4) or interleave? What's the |
| 144 | +severity bar / output format (the repo already publishes HTML QA reports under |
| 145 | +`docs/qa/`)? Which flows are highest-traffic and worth auditing first? |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +## How to resume after a context clean |
| 150 | + |
| 151 | +1. Read this doc + [`../roadmap.yaml`](../roadmap.yaml) (or `ROADMAP.md`). |
| 152 | +2. Memory `project-personal-edition-polish-initiative` auto-loads the summary. |
| 153 | +3. For the active vertical, read its `specs/<NNN>/` spec. |
| 154 | +4. Before deep-designing a new vertical, dispatch a code explorer to ground it |
| 155 | + against the "Existing foundation" pointers above (as we did for the scanner). |
0 commit comments