# Public Adoption Stats Web Handoff

This is the implementation plan for `CoWork-OS/cowork-os-web`. It complements the main repo collector in `scripts/collect-public-adoption-stats.mjs`.

## Goal

Show acquisition and download-intent signals without adding telemetry to the installed CoWork OS app.

The website should make this distinction clear:

- Website and GitHub/npm stats measure awareness, install intent, and public traction.
- They do not measure active users, first launch, model setup, successful tasks, retention, prompts, files, emails, or generated content.

## Data Source

Consume the latest JSON generated by the main repo:

```txt
https://raw.githubusercontent.com/CoWork-OS/CoWork-OS/main/data/adoption/public-stats-latest.json
```

For build-time fetching, cache the response so website builds do not fail when GitHub is temporarily unavailable. For runtime fetching, show the previous cached value or a quiet unavailable state.

## Website Analytics

Use a privacy-friendly analytics provider such as Plausible, Umami, Cloudflare Web Analytics, or Vercel Analytics.

Required page-view coverage:

- `/`
- `/download`
- `/docs`
- `/docs/getting-started`
- `/docs/providers`
- comparison pages
- release notes pages

Required custom events:

```txt
download_macos_clicked
download_windows_clicked
download_linux_clicked
download_server_clicked
npm_command_copied
github_repo_clicked
github_release_clicked
docs_getting_started_clicked
quickstart_viewed
```

Do not collect prompts, file paths, account IDs, API keys, email metadata, or installed-app events.

## Redirect Routes

Add route handlers or pages for:

```txt
/download/macos
/download/windows
/download/linux
/download/server
/download/npm
```

Each route should:

1. Record the relevant custom event.
2. Preserve analytics source/referrer/UTM context if the analytics provider supports it.
3. Redirect to the current GitHub release asset, GitHub Releases page, or npm package page.

Fallback behavior:

- If exact latest asset resolution is unavailable, redirect to `https://github.com/CoWork-OS/CoWork-OS/releases/latest`.
- If npm route resolution is unavailable, redirect to `https://www.npmjs.com/package/cowork-os`.

## Public Stats UI

Add a stats section or page that renders:

- GitHub stars
- GitHub forks
- GitHub watchers
- latest release tag and date
- release asset downloads, lifetime
- release asset download delta since previous snapshot
- downloads by platform
- npm downloads for last day, week, and month
- GitHub views and clones when available
- top referrers and paths when available

Use this label near the stats:

> These are public adoption signals from GitHub, npm, and website analytics. They are not active-user or in-app telemetry numbers.

## Suggested Funnel

Report this funnel in the website analytics dashboard:

```txt
Homepage visit
→ Download page view
→ Download click
→ GitHub release asset download or npm download
→ Getting Started docs view
```

This is the strongest funnel available without installed-app telemetry.

## Data Contract Notes

Expected JSON fields:

```txt
generatedAt
privacy.appTelemetry
github.repo.stars
github.repo.forks
github.repo.watchers
github.releases.latestRelease.tag
github.releases.latestRelease.publishedAt
github.releases.totalAssetDownloadCount
github.releases.totalInstallAssetDownloadCount
github.releases.metadataAssetDownloadCount
github.releases.platformTotals
github.releases.assets[]
github.traffic.views
github.traffic.clones
github.traffic.referrers
github.traffic.paths
npm.latestVersion
npm.downloads.lastDay.downloads
npm.downloads.lastWeek.downloads
npm.downloads.lastMonth.downloads
deltas.releaseDownloads.totalDeltaSincePreviousSnapshot
deltas.releaseDownloads.platformDeltasSincePreviousSnapshot
```

Treat missing or `unavailable` traffic fields as normal. GitHub traffic APIs require repository access and only cover a short rolling window.
