docs: add Factory Dashboard metrics reference (APP-5546)

[warp-agent-staging]

Summary

Adds a dedicated metrics reference page for the Factory Dashboard, so the per-metric detail that used to live only in on-hover tooltips (APP-5546) has a durable home in the docs. This is the docs half of APP-5546; the companion client change is warpdotdev/warp-server#15643, which trims the Dashboard's info tooltips and adds a visible link to this page.

Related issues

Linear APP-5546 — "Add metrics page documentation"

Changes

• Added src/content/docs/factories/metrics-reference.mdx: a reference page covering every metric on the factory Dashboard — Total runs (including its breakdown views and their per-view counting rules, e.g. the By-model cap-at-eight-plus-Other fold and the Unknown bucket), Pull requests (opened and merged, and the direction and cause of their occasional mismatch), Autonomy, Cycle time (all four stages), Cost per PR (cost-breakdown and by-PR-size views, including all three of that view's empty/partial/full footnote states), Most expensive PRs (naming exactly which columns are backed by webhook PR facts versus by the run itself), and Scorer cards — what each counts, how it's computed (median semantics, cohort/merge-time counting, the even cost split across a run tree's PRs), its data-source coverage limits, and how to read it without drawing the wrong conclusion. Also clarifies that Self-improvement pull requests live on their own page, not as a Dashboard card.
• Wired the new page into src/sidebar.ts under Factories > Management & observability, after Measure and improve.
• Trimmed src/content/docs/factories/measure-and-improve.mdx's per-metric table into a short summary that links to the new reference, so detail is single-sourced.
• Trimmed src/content/docs/factories/factory-dashboard.mdx's Read metrics on the Dashboard page section the same way, and added the reference to its Next steps list.

Per requirement 10c/15a in warp-server's specs/factory-metrics/PRODUCT.md, the Time saved card was removed from the dashboard before this docs pass, so it is intentionally not documented as a shipped metric.

Every claim about which fields are backed by webhook-collected PR facts versus by the run/agent-config metadata itself was verified directly against TopPRsTable.tsx, CostPerPRCard.tsx, RunBreakdownCard.tsx, and run-breakdown.ts in the shipping client, not inferred from the spec alone — the spec and the UI diverge in a few places (e.g. Creator/Source/requested-Model in Most expensive PRs come from the run's root-run metadata, not from PR facts).

Validation

• npm install && npm run build — full Astro Starlight build succeeds, including the new page (dist/client/factories/metrics-reference/index.html).
• python3 .agents/skills/style_lint/style_lint.py --changed — 0 errors; 39 warnings, all pre-existing unrecognized-term notices on bolded UI terms already used across the touched files (e.g. "Dashboard", "Runs", "Secrets", "Unknown", "Other"), none introduced by the new content.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 378 files scanned, 3,859 internal links checked, 0 broken.

Screenshots

Not applicable — text-only documentation change, no UI screenshots to capture.

Unverified claims

None — every metric definition and computation detail (median semantics, cohort vs. merge-time counting, the run-tree cost split, PR-size thresholds, autonomy's human-touch definition, cycle-time stage semantics, webhook coverage caveats, and exactly which Most-expensive-PRs columns are PR-fact-backed vs. run-metadata-backed) was verified against warp-server's specs/factory-metrics/PRODUCT.md and TECH.md, and cross-checked against the live FactoryDashboard client source (AutonomyCard.tsx, PRLatencyBarsCard.tsx, CostPerPRCard.tsx, RunBreakdownCard.tsx, TopPRsTable.tsx, run-breakdown.ts, metrics-utils.ts, cost-by-size.ts) and its tests.

Follow-ups

• The companion client PR is warpdotdev/warp-server#15643 (trimmed tooltips + on-page link to this doc), tracked under APP-5546.
• Release ordering: https://docs.warp.dev/factories/metrics-reference/ 404s until this PR merges and deploys, so the server change should not roll out first. That sequencing decision is a human call, not something resolved in either PR's code.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 19, 2026 9:51pm

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.