[lidge-jun]

Summary

Layer 5 of the telemetry stack (base: #8304). This is the public documentation for the telemetry added in layers 2–4, following devlog/_plan/261107_telemetry_dashboard/040_docs_privacy.md.

• New guide guides/telemetry ("Telemetry and privacy", added to the Guides sidebar). It covers:
  • What is collected, with a real example payload, and what is never collected.
  • The default-on rule: nothing is sent until a person has seen the notice.
  • Why agent-driven starts never enable it, and what that guard does and does not prove.
  • Every way to turn it off: the popup, the Proxy details toggle, ocx telemetry disable, OCX_TELEMETRY=0 and DO_NOT_TRACK=1.
  • How to see the exact payload.
  • The full provider-kind and model-family rosters.
  • The UTC-day cutoff for no backfill.
  • Retention and hashing.
  • That project-wide aggregates are served publicly by GET /v1/stats, and that the collector is not deployed yet.
• reference/configuration/server.md: documents the telemetry block and both environment variables.
• guides/web-dashboard.md: gains the Proxy details telemetry row.
• Translations: the existing translated versions of those two pages in all 7 locales are updated to match. The new guide falls back to English.
• structure/telemetry.md: gains the collector and guide paths.
• The guide does not link /dashboard yet; layer 6 adds that route and link.

Review round 1

• The guide, configuration reference, all locale pages and the structure doc are updated for D1–D19:
  • the UTC-day cutoff and env opt-out marker
  • the TTY requirement and disclosure
  • dismissal recording nothing
  • preview eligibility and backoff
  • install-days and small-cohort folding
  • the self-reported, unauthenticated figures
  • the salted hourly IP hash
  • deploying the collector first
• The privacy statement in the README and code-signing.md links the guide. Merging layer 4 in conflicted with layer 2's rewrite of the same statement; this layer's linked version was kept.
• Verification at d8fc29c2c1: the docs build passes (95,036 links), and 440 docs and structure tests pass.

Review round 2

• guides/telemetry.md now says that every day covered by an env opt-out stays unsent, including each day a proxy started with OCX_TELEMETRY=0 keeps running and the day the opt-out ends (envOptOutActiveSince, feat(telemetry): default-on anonymous telemetry core with a human-only consent boundary #8300). structure/telemetry.md keeps this layer's wording plus the marker rule.
• Verification at 4b382aaec3, isolated home (env -i): typecheck, privacy scan, structure check pass; all tests/ci-workflows/docs-*.test.ts, telemetry client and guard suites 484 pass, 0 fail; docs-site build checked 95,036 internal links across 649 pages. Pushed with --no-verify (no pre-push hook exists; checks ran by hand).

Review round 3 (head b66bb7e1f9)

• Guide behaviour: the guide now describes the machine-wide installer choice, the held decline on a fresh install, the per-day distinct-install threshold, and the cf-connecting-ip key with IPv6 on the /64.
• Review fixes:
  • the dashboard switch records accept directly; only ocx telemetry enable prompts;
  • Retry-After is honoured when present, otherwise about 15–20 minutes of backoff;
  • the code-signing page drops the repeated Privacy label.
• Structure doc: structure/telemetry.md merges the lower layers' changes.
• Verification (isolated home): typecheck, privacy scan, structure check, and 549 tests pass, 0 fail. The docs-site build passes on feat(docs-site): public usage dashboard at opencodex.me/dashboard #8308's head (657 pages, 96,271 internal links checked).

Review round 4 (head 9179c5eb31)

• Service environment (Ingwannu): the guide says OCX_TELEMETRY and DO_NOT_TRACK only reach a proxy that inherits them, a background service (systemd, launchd, Task Scheduler) does not see shell exports, and ocx telemetry status asks the running proxy for the state it actually uses.
• Forged-cohort residual: documented next to the subtraction residual, matching the collector README.
• Installer: optout in any letter case; re-running a newer installer without changing the box keeps the earlier decision and does not re-apply it over a later dashboard choice.
• Verification (isolated home): typecheck, privacy scan, structure check, and 557 tests pass, 0 fail. The docs-site build passes on feat(docs-site): public usage dashboard at opencodex.me/dashboard #8308's head (657 pages, internal links checked). Pushed with --no-verify.

Round 5 (head 02524d4c7f)

• The layer 5 privacy line (README and its seven copies, code-signing en and tr, and the docs-link-targets pin) names the per-day install hash, matching layers 2 and 2b.
• The guide says only send keeps telemetry on and any other installer value turns it off.
• Verification (isolated home): typecheck, privacy scan, structure check, and 563 tests pass, 0 fail. The docs-site build passes on feat(docs-site): public usage dashboard at opencodex.me/dashboard #8308's head (657 pages, internal links checked). Pushed with --no-verify.

Round 6 (head 9e26c1df05)

• The guide notes that a background service follows a later installer opt-out once the app starts, and that ocx telemetry disable stops it at once.
• Verification (isolated home): 565 tests pass, 0 fail, plus typecheck, privacy scan and structure check. The docs-site build passes on feat(docs-site): public usage dashboard at opencodex.me/dashboard #8308's head. Pushed with --no-verify.

Round 7 (head 4be582b97c)

• The layer 5 privacy line (README, its seven copies, code-signing en and tr, and the docs-link-targets pin) lists every field sent, matching layer 2.
• Verification (isolated home): 568 tests pass, 0 fail, plus typecheck, privacy scan and structure check. The docs-site build passes (657 pages). Pushed with --no-verify.

Verification

• cd docs-site && bun run build: 649 pages built. The internal-link checker passes (95,028 links).
• bun test tests/ci-workflows/ tests/cli/cli-headless-parity.test.ts: 1,936 pass, 0 fail. This includes the docs-* claim guards and docs-link-targets.
• bun run typecheck, bun run structure:check and bun run privacy:scan: pass.
• Two independent docs reviews, with every claim checked against the code: round 1 returned NEAR-PASS (missing public-stats disclosure, a wrong config-command statement, overclaims, missing rosters), all fixed; round 2 passed, including a spot-check of the ko and ja translations.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review: 2

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: lidge-jun/opencodex
• Branch: goat/telemetry-05-docs
• File: .coderabbit.yaml
• Commit: 4be582b
• Layers: Repository YAML
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 1aa0eb4f-42a9-4a41-9bb3-4b45c082d474

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-07T16:48:12.090281Z	e9a2aba	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

Reviewed layer 5 at e63fb2e2. I compared the guide, the configuration reference, the README/code-signing privacy statement and structure/telemetry.md with the code in #8300/#8303/#8304.

What matches the code: the consent precedence table, the human-only consent paths, the env opt-out semantics including the long-running opted-out proxy, the D1 day-after-consent rule, the payload field list and closed rosters, the never-sent list, local file modes and the per-day hash. The README privacy line in this layer is accurate. It names the installer checkbox and links the guide, and it replaces the earlier "turned off at install time in that prompt" wording.

Items to update together with the collector fixes I requested on #8304:

• Guide lines 300–309 (small cohorts): once #8304 changes how folding works, this description has to change with it. Even as written today, "folds rows with fewer than 10 install-days" lets a single install that reports on 10+ days be published alone. The text should not suggest that folding protects single installs until the threshold works per day.
• Guide line 310: "can be forged within the per-IP-hash rate limit" is only a bound once IPv6 is keyed by prefix (#8304, item 2).
• Guide line 116 ("in the proxy environment"): correct, but add one sentence that a background service (systemd/launchd/Task Scheduler) does not inherit variables exported in an interactive shell, and point to ocx telemetry status to confirm the effective state.

This is a COMMENT, because the doc text has to follow the #8304 outcome. I found no factual errors in the rest of the layer. Head CI is still queued.

[lidge-jun]

@Ingwannu thanks. All three items are in the guide at 8aa3296e20:

• Small cohorts (old lines 300–309): rewritten for the per-day distinct-install threshold that feat(telemetry-collector): Cloudflare Worker + D1 collector and public stats API #8304 now enforces. It no longer suggests folding protects a single install. It says which dimensions fold into that day's other (versions, platforms, channels) and which drop sub-threshold rows (providers, models, errors, dailyByProvider).
• Forging bound (old line 310): the guide describes the cf-connecting-ip key with IPv6 collapsed to its /64 and x-forwarded-for ignored. It also documents the remaining residual a privacy review found: 9 forged reports plus one real install on the same day reach the threshold, and the sender can subtract their own share. The install stays anonymous; the rate limit raises the cost without preventing it. The collector README (feat(telemetry-collector): Cloudflare Worker + D1 collector and public stats API #8304 ab92292a46) says the same.
• Service environment (old line 116): added after the env opt-outs. The variables only reach a proxy that inherits them, a systemd/launchd/Task Scheduler service does not see shell exports, and ocx telemetry status asks the running proxy, so it shows the state that proxy actually uses.

Verification at this head (isolated home): typecheck, privacy scan, structure check, 557 tests, 0 fail; the docs-site build passes on #8308's head.