fix: new user detection race condition + telemetry gaps

.opencode/skills/data-viz/SKILL.md

@@ -100,6 +100,8 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - **Responsive**: `min-h-[VALUE]` on all charts. Grid stacks on mobile
 - **Animation**: Entry transitions only, `duration-300` to `duration-500`. Never continuous
 - **Accessibility**: `aria-label` on charts, WCAG AA contrast, don't rely on color alone
+- **Dynamic color safety**: When colors come from external sources (brand palettes, category maps, API data, user config), never apply them directly as text color without a contrast check. Dark colors are invisible on dark card backgrounds. Safe pattern: use the external color only for non-text elements (left border, dot, underline); always use the standard text color (white / `var(--text)`) for the label itself. If color-coded text is required, apply a minimum lightness floor: `color: hsl(from brandColor h s max(l, 60%))`
+- **Icon semantics**: Verify every icon matches its label's actual meaning, not just its visual shape. Common traps: using a rising-trend icon (📈) for metrics where lower is better (latency, error rate, cost); using achievement icons (🏆) for plain counts. When in doubt, use a neutral descriptive icon over a thematic one that could mislead
 
 ### Step 5: Interactivity & Annotations
 
@@ -133,3 +135,16 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - Pie charts > 5 slices — use horizontal bar
 - Unlabeled dual y-axes — use two separate charts
 - Truncated bar axes — always start at zero
+- Filtering or mapping over a field not confirmed to exist in the data export — an undefined field in `.filter()` or `.map()` produces empty arrays or NaN silently, not an error; always validate the exported schema matches what the chart code consumes
+
+## Pre-Delivery Checklist
+
+Before marking a dashboard complete:
+
+- [ ] Every tab / view activated — all charts render (no blank canvases, no unexpected 0–1 axes)
+- [ ] Every field referenced in chart/filter code confirmed present in the data export
+- [ ] All text readable on its background — check explicitly when colors come from external data
+- [ ] All icons match their label's meaning
+- [ ] Tooltips appear on hover for every chart
+- [ ] No chart silently receives an empty dataset — add a visible empty state or console warning
+- [ ] Mobile: grid stacks correctly, no body-level horizontal overflow

.opencode/skills/data-viz/references/component-guide.md

@@ -392,3 +392,70 @@ const CalloutLabel = ({ viewBox, label, color = "#1e293b" }: { viewBox?: { x: nu
 ```
 
 **Rules:** Never overlap data. Use `position: "insideTopRight"/"insideTopLeft"` on labels. Pair annotations with tooltips — annotation names the event, tooltip shows the value.
+
+---
+
+## Multi-Tab Dashboard — Lazy Chart Initialization
+
+Charts initialized inside a hidden container (`display:none`) render blank. Chart.js, Recharts, and Nivo all read container dimensions at mount time — a hidden container measures as `0×0`.
+
+**Rule: never initialize a chart until its container is visible.**
+
+```js
+// Vanilla JS pattern
+var _inited = {};
+
+function activateTab(name) {
+  // 1. make the tab visible first
+  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));
+  document.getElementById('tab-' + name).classList.add('active');
+  // 2. then initialize charts — only on first visit
+  if (!_inited[name]) {
+    _inited[name] = true;
+    initChartsFor(name);
+  }
+}
+
+activateTab('overview'); // init the default visible tab on page load
+```
+
+Library-specific notes:
+- **Chart.js**: canvas reads as `0×0` inside `display:none` — bars/lines never appear
+- **Recharts `ResponsiveContainer`**: reads `clientWidth = 0` — chart collapses to nothing
+- **Nivo `Responsive*`**: uses `ResizeObserver` — fires once at `0×0`, never re-fires on show
+- **React conditional rendering**: prefer `visibility:hidden` + `position:absolute` over toggling `display:none` if you want charts to stay mounted and pre-rendered
+
+---
+
+## Programmatic Dashboard Generation — Data-Code Separation
+
+When generating a standalone HTML dashboard from a script (Python, shell, etc.), never embed JSON data inside a template string that also contains JavaScript. Curly-brace collisions in f-strings / template literals cause silent JS parse failures that are hard to debug.
+
+**Wrong** — data and JS logic share one f-string, every `{` in JS must be escaped as `{{`:
+
+```python
+html = f"""
+<script>
+  const data = {json.dumps(data)};          // fine
+  const fn = () => {{ return x; }}           // must escape — easy to miss
+  const obj = {{ key: getValue() }};         // one missed escape = blank page
+</script>
+"""
+```
+
+**Right** — separate data from logic entirely:
+
+```python
+# Step 1: write data to its own file — no template string needed
+with open('data.js', 'w') as f:
+    f.write('const DATA = ' + json.dumps(data) + ';')
+
+# Step 2: HTML loads both files; app.js is static and never needs escaping
+```
+
+```html
+<script src="data.js"></script>   <!-- generated, data only -->
+<script src="app.js"></script>    <!-- static, logic only   -->
+```
+
+Benefits: `app.js` is static and independently testable; `data.js` is regenerated without touching logic; no escaping required in either file.

docs/docs/reference/security-faq.md

@@ -126,6 +126,23 @@ Or via environment variable:
 export ALTIMATE_TELEMETRY_DISABLED=true
 ```
 
+### How does Altimate Code identify users for analytics?
+
+- **Logged-in users:** Your email is SHA-256 hashed before sending. We never see your raw email.
+- **Anonymous users:** A random UUID (`crypto.randomUUID()`) is generated on first run and stored at `~/.altimate/machine-id`. This is NOT tied to your hardware, OS, or identity — it's purely random.
+- **Both identifiers** are only sent when telemetry is enabled. Disable with `ALTIMATE_TELEMETRY_DISABLED=true`.
+- **No fingerprinting:** We do not use browser fingerprinting, hardware IDs, MAC addresses, or IP-based tracking.
+
+### What happens on first launch?
+
+A single `first_launch` event is sent containing only:
+
+- The installed version (e.g., "0.5.9")
+- Whether this is a fresh install or upgrade (boolean)
+- Your anonymous machine ID (random UUID)
+
+No code, queries, file paths, or personal information is included. This event helps us understand adoption and is fully opt-out-able.
+
 ## What happens when I authenticate via a well-known URL?
 
 When you run `altimate auth login <url>`, the CLI fetches `<url>/.well-known/altimate-code` to discover the server's auth command. Before executing anything:

docs/docs/reference/telemetry.md

@@ -36,6 +36,7 @@ We collect the following categories of events:
 | `skill_used` | A skill is loaded (skill name and source — `builtin`, `global`, or `project` — no skill content) |
 | `sql_execute_failure` | A SQL execution fails (warehouse type, query type, error message, PII-masked SQL — no raw values) |
 | `core_failure` | An internal tool error occurs (tool name, category, error class, truncated error message, PII-safe input signature, and optionally masked arguments — no raw values or credentials) |
+| `first_launch` | Fired once on first CLI run after installation. Contains version and is_upgrade flag. No PII. |
 
 Each event includes a timestamp, anonymous session ID, CLI version, and an anonymous machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and never tied to any personal information).
 
@@ -88,6 +89,19 @@ We take your privacy seriously. Altimate Code telemetry **never** collects:
 
 Error messages are truncated to 500 characters and scrubbed of file paths before sending.
 
+### New User Identification
+
+Altimate Code uses two types of anonymous identifiers for analytics, depending on whether you are logged in:
+
+- **Anonymous users (not logged in):** A random UUID is generated using `crypto.randomUUID()` on first run and stored at `~/.altimate/machine-id`. This ID is not tied to your hardware, operating system, or identity — it is purely random and serves only to distinguish one machine from another in aggregate analytics.
+- **Logged-in users (OAuth):** Your email address is SHA-256 hashed before sending. The raw email is never transmitted.
+
+Both identifiers are only sent when telemetry is enabled. Disable telemetry entirely with `ALTIMATE_TELEMETRY_DISABLED=true` or the config option above.
+
+### Data Retention
+
+Telemetry data is sent to Azure Application Insights and retained according to [Microsoft's data retention policies](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-configure). We do not maintain a separate data store. To request deletion of your telemetry data, contact [email protected].
+
 ## Network
 
 Telemetry data is sent to Azure Application Insights:

packages/opencode/src/altimate/telemetry/index.ts

@@ -350,6 +350,15 @@ export namespace Telemetry {
         skill_source: "builtin" | "global" | "project"
         duration_ms: number
       }
+    // altimate_change start — first_launch event for new user counting (privacy-safe: only version + machine_id)
+    | {
+        type: "first_launch"
+        timestamp: number
+        session_id: string
+        version: string
+        is_upgrade: boolean
+      }
+    // altimate_change end
     // altimate_change start — telemetry for skill management operations
     | {
         type: "skill_created"
@@ -618,7 +627,13 @@ export namespace Telemetry {
         iKey: cfg.iKey,
         tags: {
           "ai.session.id": sid || "startup",
-          "ai.user.id": userEmail,
+          // altimate_change start — use machine_id as fallback for anonymous user identification
+          // This IMPROVES privacy: previously all anonymous users shared ai.user.id=""
+          // which made them appear as one mega-user in analytics. Using the random UUID
+          // (already sent as a custom property) gives each machine a distinct identity
+          // without any PII. machine_id is a crypto.randomUUID() stored locally.
+          "ai.user.id": userEmail || machineId || "",
+          // altimate_change end
           "ai.cloud.role": "altimate",
           "ai.application.ver": Installation.VERSION,
         },

packages/opencode/src/cli/cmd/tui/component/tips.tsx

@@ -47,26 +47,28 @@ const BEGINNER_TIPS = [
 ]
 // altimate_change end
 
-// altimate_change start — first-time user beginner tips
+// altimate_change start — first-time user beginner tips with reactive pool
 export function Tips(props: { isFirstTime?: boolean }) {
   const theme = useTheme().theme
-  const pool = props.isFirstTime ? BEGINNER_TIPS : TIPS
-  const parts = parse(pool[Math.floor(Math.random() * pool.length)])
-  // altimate_change end
+  const tip = createMemo(() => {
+    const pool = props.isFirstTime ? BEGINNER_TIPS : TIPS
+    return parse(pool[Math.floor(Math.random() * pool.length)])
+  })
 
   return (
     <box flexDirection="row" maxWidth="100%">
       <text flexShrink={0} style={{ fg: theme.warning }}>
         ● Tip{" "}
       </text>
       <text flexShrink={1}>
-        <For each={parts}>
+        <For each={tip()}>
           {(part) => <span style={{ fg: part.highlight ? theme.text : theme.textMuted }}>{part.text}</span>}
         </For>
       </text>
     </box>
   )
 }
+// altimate_change end
 
 const TIPS = [
   "Type {highlight}@{/highlight} followed by a filename to fuzzy search and attach files",

packages/opencode/src/cli/cmd/tui/routes/home.tsx

@@ -38,7 +38,13 @@ export function Home() {
     return Object.values(sync.data.mcp).filter((x) => x.status === "connected").length
   })
 
-  const isFirstTimeUser = createMemo(() => sync.data.session.length === 0)
+  // altimate_change start — fix race condition: don't show beginner UI until sessions loaded
+  const isFirstTimeUser = createMemo(() => {
+    // Don't evaluate until sessions have actually loaded (avoid flash of beginner UI)
+    if (sync.status === "loading" || sync.status === "partial") return false
+    return sync.data.session.length === 0
+  })
+  // altimate_change end
   const tipsHidden = createMemo(() => kv.get("tips_hidden", false))
   const showTips = createMemo(() => {
     // Always show tips — first-time users need guidance the most

packages/opencode/src/cli/welcome.ts

@@ -3,6 +3,9 @@ import path from "path"
 import os from "os"
 import { Installation } from "../installation"
 import { EOL } from "os"
+// altimate_change start — import Telemetry for first_launch event
+import { Telemetry } from "../altimate/telemetry"
+// altimate_change end
 
 const APP_NAME = "altimate-code"
 const MARKER_FILE = ".installed-version"
@@ -41,6 +44,16 @@ export function showWelcomeBannerIfNeeded(): void {
     // altimate_change end
     const isUpgrade = installedVersion === currentVersion && installedVersion !== "local"
 
+    // altimate_change start — track first launch for new user counting (privacy-safe: only version + machine_id)
+    Telemetry.track({
+      type: "first_launch",
+      timestamp: Date.now(),
+      session_id: "",
+      version: installedVersion,
+      is_upgrade: isUpgrade,
+    })
+    // altimate_change end
+
     if (!isUpgrade) return
 
     const tty = process.stderr.isTTY