docs(console): error-tracking.md predates the #5522 two-key telemetry gate — following it as written recreates the exact shape #5522 removed

[os-zhuang]

Found during a maintainer Q&A read on 2026-08-27 (PM session), while verifying "did the docs get updated" for the #5522 fix chain.

The problem

apps/console/docs/error-tracking.md is the pre-#5522 integration guide, and every load-bearing instruction in it now contradicts the shipped design:

the doc says	the shipped code (PR #5559 + #5982, objectstack PR #11382)
pnpm add @sentry/react and write your own src/lib/sentry.ts	Sentry integration already exists in the console; the gate is resolveSentryGate
"Initialize error tracking before React renders"	initSentry() deliberately runs in .finally() after initRuntimeConfig() — the doc's ordering is exactly the report-before-permission race #5982 eliminated
enabling = set VITE_SENTRY_DSN (build-time only)	the gate is two keys: build-time VITE_SENTRY_DSN AND the runtime permission telemetry.allowClientErrorReporting from /api/v1/runtime/config (fail-closed; server side: OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED) — the doc never mentions the runtime half
no PII stance	VITE_SENTRY_SEND_DEFAULT_PII is strict opt-in (=== 'true')

A reader following this guide today would bolt a second, ungated Sentry init onto an app that already has a gated one — rebuilding the "decision hardcoded at build time, no operator switch" shape that #5522 existed to remove, and the committed-telemetry-endpoint.test.ts ratchet would not catch it (nothing gets committed; the init is just wrong).

Task

Rewrite apps/console/docs/error-tracking.md to describe the system that exists:

1. Sentry support is built in — no installation section; delete the hand-rolled src/lib/sentry.ts / initErrorTracking() recipe entirely.
2. Enabling = the two halves, each stated with its variable name and where it lives:
   • build-time (build environment of the console, e.g. the hosting panel): VITE_SENTRY_DSN (required), optional VITE_SENTRY_SEND_DEFAULT_PII=true, VITE_SENTRY_ENVIRONMENT, VITE_SENTRY_RELEASE, VITE_SENTRY_TRACES_SAMPLE_RATE, VITE_SENTRY_REPLAY, VITE_SENTRY_ENABLED=false force-off — the authoritative comment block already in apps/console/.env.production is the source to mirror, not to duplicate freely;
   • runtime (each production server): OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED=true (truthy vocabulary 1/true/on/yes; unrecognised spelling refused at mount) or new RuntimeConfigPlugin({ allowClientErrorReporting: true }); link the canonical row in objectstack content/docs/deployment/environment-variables.mdx.
3. State the fail-closed contract in one line: either half missing ⇒ no reporting, silently, by design; ⛔ never commit a DSN (the ratchet test committed-telemetry-endpoint.test.ts enforces it).
4. Verification steps: curl <deployment>/api/v1/runtime/config → telemetry.allowClientErrorReporting: true, then a thrown test error appearing in Sentry.
5. Keep the CSP note and the source-maps CI note if still accurate; the "Option 2: Custom Error Boundary" section may stay only if it is made subject to the same runtime permission, otherwise remove it (it is a second ungated exfiltration path presented as an alternative).

Acceptance

• One file changed: apps/console/docs/error-tracking.md (plus changeset only if repo convention requires one for docs — it should not).
• Every env var named in the doc greps to a real read site in the current tree.
• No instruction in the doc, followed literally, produces an ungated telemetry path.

Refs: #5522 (the saga card) · PR #5559 · PR #5982 · objectstack#10805 / objectstack PR #11382.

[claude]

Claiming this for implementation.

• branch: claude/issue-6599-error-tracking-doc
• session: https://claude.ai/code/session_01DKWDdUJ2XNRESVVWUvcpnh
• scope: apps/console/docs/error-tracking.md only (docs)

Note for PM: the issue arrived with no assignee and no prior claim comment.

Generated by Claude Code

---

Generated by Claude Code

[claude]

os-dev-report

{
 "issue": 6599,
 "status": "done",
 "branch": "claude/issue-6599-error-tracking-doc",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6601",
 "premise_still_valid": true,
 "summary": "Rewrote apps/console/docs/error-tracking.md to describe the shipped two-key gate: the installation section and hand-rolled src/lib/sentry.ts recipe are deleted (Sentry is built in), enabling is stated as the conjunction of build-time VITE_SENTRY_DSN and the runtime permission telemetry.allowClientErrorReporting (OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENABLED, or RuntimeConfigPlugin with allowClientErrorReporting: true), the fail-closed contract is one line, and the initSentry-after-initRuntimeConfig ordering that PR #5982 established is documented for host embedders. Option 2 (Custom Error Boundary) removed as a second ungated exfiltration path, replaced by the built-in captureError/setSentryUser, which route through resolveSentryGate and no-op when it denies. Two corrections beyond the card table, both verified against the tree: the CSP section was fabricated (apps/console/index.html sets no CSP meta tag, and the doc was the ONLY file in the repo mentioning CSP at all), and VITE_ENVIRONMENT plus VITE_ERROR_ENDPOINT had zero read sites anywhere, so both are gone. The source-maps note is kept (sourcemap: false at apps/console/vite.config.ts:702 is still accurate) with --release pinned to VITE_SENTRY_RELEASE. Docs-only, one file, no changeset owed. NOTE for PM: the issue arrived with NO assignee and NO prior claim comment (PM-side half-state); I posted a claim comment naming my branch and proceeded without ever touching the assignee field.",
 "tests": "Gate union re-run AFTER the final commit cca3b38, verdicts quoted from the gates own output (exit codes captured by redirect-then-capture, never read through a pipe): check:control-bytes EXIT=0 \"OK (scanned 5451 tracked text file(s); skipped 85 binary)\"; check:doc-fences EXIT=0 \"every TypeScript block in 223 document(s) is fenced ts/tsx/typescript\"; check:shell-escape-residue EXIT=0 \"OK (4/4 root(s) resolved ... 0 occurrence(s) outside a fence)\"; check-changeset-presence EXIT=0 \"No source of a released package changed in this range, so no changeset is owed.\" ACCEPTANCE CHECK (mechanical): extracted every VITE_/OS_ token from the new doc and grepped each for a read site, excluding the doc itself and CHANGELOGs -- 11/11 backed, printed VERDICT line ALL-VARS-HAVE-READ-SITES; the two vars the OLD doc named that grep to nothing (VITE_ENVIRONMENT, VITE_ERROR_ENDPOINT) are exactly what that audit removed. NOT MEASURED, declared explicitly: of the gates above only check:control-bytes actually contains the edited file in its scan surface (it enumerates git ls-files; positive control run -- git ls-files --error-unmatch on the file succeeds). check:doc-fences, check:doc-snippets and check:doc-types all root at content/docs (doc-fences additionally takes packages/NAME/README.md) and do not descend into apps/, so their green is real but says nothing about this file. The narrowing away from a full pnpm lint is declared and carries all three required pieces of evidence: (1) scan population read from eslint.config.js itself, where every files: glob is ts/tsx only; (2) the diff is exactly one .md file, confirmed from the PR files API -- modified apps/console/docs/error-tracking.md +156 -131; (3) config invariance -- eslint cannot judge markdown at all and no ts/tsx was touched, so no untouched file can change verdict. No ablation was applicable: this is prose, and no gate asserts on this file. The substantive verification was line-by-line against resolveSentryGate in sentry.ts, runtime-config.ts, main.tsx, .env.production, vite.config.ts, and objectstack telemetry-posture.ts / runtime-config-plugin.ts.",
 "mcp_calls": "1 -- a single targeted search_issues, used only for the out-of-scope finding dedup. CHANNEL SWITCH DECLARED: repo-scoped REST reads and writes both work from this seat (issue read, comment POST, issue POST, PR POST, PR PATCH all returned 2xx), but /search/issues returns 403 \"sessions are bound to their configured repositories. Use repository-scoped endpoints\". Wide REST listing is banned, so dedup went through one MCP call. Its reading is valid rather than an empty-result artifact because a control term (error-tracking in:title) returned the known issue #6599 in the same call.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #6600: apps/console/docs/** is outside every documentation gate scan surface -- check:doc-fences, check:doc-snippets and check:doc-types all root at content/docs, so the console operator guides are checked by nothing but check:control-bytes, and eslint cannot see markdown at all. Filed unassigned with the finding label. Adjacent open cards checked and found distinct: #5174 and #5106 are .md-vs-.mdx collection WITHIN content/docs; #5250 and #5867 are about which fences inside already-covered files get read; #4148 (closed) is the same apps/** shape but specific to check-doc-links.mjs."
 ]
}

Generated by Claude Code

---

Generated by Claude Code