Overview Usage Analytics

Spec metadata:

- ID:
`overview-usage-analytics`

- Status:

approved

- Hard depends on:
`mcp-cli-bridge-and-usage-analytics`

,`procedural-memory-plan`

- Registry:

docs/specs/INDEX.md

Contract #

Usage ledger contract

• MCP server usage remains sourced from mcp_invocations

. - Skill usage gains a matching invocation ledger in SQLite.

• Skill usage writes must also update skill_meta.use_count

andskill_meta.last_used_at

. - The implementation must avoid one-off home-card counters or duplicate tracking paths.

Analytics read contract

• MCP analytics stay queryable through the existing summary route.
• Skill analytics expose a parallel summary route with the same core shape: total calls, success rate, top items, and latency percentiles.
• Both routes support time-window filtering so the overview can render a bounded “most used” view.

Overview rendering contract

• The home overview card must render from analytics ranking, not catalog order.
• The card must surface both top skills and top MCP servers in one coherent overview module.
• Presentation metadata is enriched from installed/catalog sources when available, but historical usage rows must still render when metadata is missing.

Validation requirements #

• Migration tests for the skill invocation ledger.
• Regression coverage that task-driven skill usage records invocation rows and updates procedural-memory usage fields.
• Analytics query tests for skill ranking, latency, and time filtering.
• Dashboard validation that the overview card reflects analytics-driven ranking instead of catalog popularity.