# Overview Usage Analytics

> Source: <https://signetai.sh/docs/specs/approved/overview-usage-analytics/>
> Published: 2026-07-22 23:48:45+00:00

# 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`

and`skill_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.