[Alejandro Lopez (soyalejolopez)]

Category

• New resource (script, agent, guide, analytics, skill)
• Update to an existing resource
• Bug fix
• Docs, site, or tooling

What's in this pull request?

Makes downloads countable in resource-stats.json. Follow-up to #573, which added the Download button but could only log clicks to the Clarity dashboard. Clarity's export API exposes page URLs and not custom events, so the button now opens a small page per resource, r/<slug>/download/, and each load of that page is one download.

How it works

1. The Download button on resource pages and the landing detail view links to r/<slug>/download/ instead of the file.
2. That page saves the file by itself (about half a second after load) and shows a Download again link to the same file, so it still works with scripts blocked. It logs a Clarity resource_download event and tags the resource.
3. The daily traffic workflow already exports Clarity page URLs. /r/<slug>/download/ loads are now added to each resource's daily bucket in traffic-data/clarity-views.json as downloads, then summed into resource-stats.json as downloads (with "downloads": "clarity" under sources). They are never added to views.

Download pages are noindex, point their canonical at the resource page, and stay out of the sitemap and feed. Only the 24 resources that have a Download button get one; archived resources, bundles, declarative agents and Markdown resources are unchanged.

What changed

• tools/catalog-build/stats-state.js: new downloadSlugFromClarityUrl; downloads is a valid persisted metric. The Clarity parsing, window-differencing and totalling helpers moved here from build-stats.js (unchanged behavior for views) so the whole export-to-stats path can be tested. Metric keys are written in a fixed order so reruns stay byte-stable.
• tools/catalog-build/build-stats.js: uses those helpers and writes downloads per resource.
• tools/catalog-build/site-pages.js, index.js, assets/resource-page.js, assets/resource-page.css: the download page template (header and footer are now shared helpers; the other 34 resource pages are byte-for-byte unchanged), the generator, the auto-download and event logic, and button styling.
• index.html: the landing Download button opens the counted page; the direct-file link and its separate click handler are gone.
• test-stats-state.js covers URL mapping (a download page is never a view), rolling and dated exports, window differencing including a negative difference, daily totals, and persisted-state validation. test-site-output.js covers the button, the download page markup, noindex and canonical, sitemap and feed exclusion, and the landing button.
• docs/CATALOG-METADATA.md, traffic-data/README.md, CHANGELOG.md: document the page and the new metric.

Verified

• npm run check passes.
• In a browser (local server): the button opens the counted page; the file saves with the right name (checked the HTML guide and the PDF); the page logs resource_download and a resource page still logs only resource_view; the landing button is hidden for a bundle.
• build-stats.js run against a mocked Clarity export (the real API needs a token): the 1, 2 and 3-day windows became daily buckets with views and downloads, and resource-stats.json got {"views": 9, "viewsUniques": 6, "downloads": 4} with the new source entry. The data files were restored afterwards.

Notes

• Counts start from the first daily run after this merges; Clarity keeps only three days, so earlier clicks are not recoverable.
• resource-stats.json gains sources.downloads and per-resource downloads at the next scheduled stats run. The landing page does not display downloads yet.
• Download page loads also include anyone who opens the link directly, and Clarity may drop some bot traffic, so treat the number as a trend rather than an exact tally.

Related issues

Follows #573.

Checklist

• No private, customer-specific, or unlicensed content, and no secrets
• README front matter is valid: npm ci --prefix tools/catalog-build && npm run check --prefix tools/catalog-build (passes)
• version and updated were bumped (not applicable: no resource content changed)
• Installation and usage steps were tested
• Files over 5 MB were avoided
• If this changes the Agent 365 Customer Implementation Guide or Enablement Checklist: not applicable, neither changed

See CONTRIBUTING.md for details.