customer-presentation/docs/superpowers/plans/2026-04-27-engagement-tracking.md

# Engagement Tracking Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add server-side tracking of `login` and `timeline_view` events with device classification (mobile/tablet/desktop, OS, browser), readable via a new `bin/events.js` CLI.

**Architecture:** One unified `events` table in the existing SQLite DB (`data/fenja.sqlite`). A small UA parser in `src/ua.js` (also takes ownership of the existing `MOBILE_UA_RE` regex). A thin recorder in `src/events.js`. Wire-ups in `src/auth.js` (login) and `server.js` (timeline_view). One-line refactor to `src/sessions.js` so the new session ID flows out of `issueSession()` for the login event.

**Tech Stack:** Node 20+ ESM, Express, `better-sqlite3` (synchronous). No test framework (see "Verification" below). No new npm dependencies.

**Spec:** [`docs/superpowers/specs/2026-04-27-engagement-tracking-design.md`](../specs/2026-04-27-engagement-tracking-design.md)

## Verification approach

The project has no test suite, linter, or build step (see `CLAUDE.md`). Verification per task is one of:

- **Smoke**: `npm run dev` starts cleanly with no errors on stdout/stderr.
- **CLI inspection**: `node bin/events.js list` (after Task 2 lands) — the events CLI is itself a verification tool for later tasks.
- **Quick Node one-liner**: for pure functions like the UA parser.
- **Manual browser walk**: for end-to-end tasks (Tasks 7–8). Local dev runs at `http://127.0.0.1:3000`. Use an invite created via `node bin/invite.js add <email> <FirstName>`.
- **CHECKLIST.md walkthrough**: full manual matrix in Task 9.

Local dev requires `.env` with `PORT=3000` and `PUBLIC_ORIGIN=http://127.0.0.1:3000` (no `NODE_ENV=production` so cookies work over HTTP). See `.env.example`.

---

## File Structure

**New files:**
- `src/ua.js` — UA parser; owns `MOBILE_UA_RE` (~50 lines)
- `src/events.js` — `recordEvent()` recorder (~25 lines)
- `bin/events.js` — CLI for reading the event log (~110 lines, mirrors `bin/joins.js`)

**Modified files:**
- `src/db.js` — add `events` table, indexes, 7 prepared statements
- `src/sessions.js` — `issueSession()` returns the new session ID
- `src/auth.js` — capture session ID, record `login` event on success
- `server.js` — import `MOBILE_UA_RE` from `src/ua.js`; record `timeline_view` event in the `/timeline` handler
- `CLAUDE.md` — add `bin/events.js` to the commands block
- `OPERATIONS.md` — new section "Reading engagement events" mirroring "Reading Join-CTA clicks"
- `CHECKLIST.md` — new section "H3. After changes to engagement events"

---

## Task 1: Schema + prepared statements in `src/db.js`

**Files:**
- Modify: `src/db.js`

- [ ] **Step 1: Add the `events` table to the `db.exec` schema block**

In `src/db.js`, inside the existing `db.exec(\`...\`)` call (around line 23–59, after the `bifrost_joins` block and before the closing backtick), append:

```sql

  CREATE TABLE IF NOT EXISTS events (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    event_type  TEXT    NOT NULL,
    email       TEXT    NOT NULL,
    occurred_at INTEGER NOT NULL,
    session_id  TEXT,
    device_type TEXT,
    os          TEXT,
    browser     TEXT,
    user_agent  TEXT,
    meta        TEXT
  );

  CREATE INDEX IF NOT EXISTS idx_events_email     ON events(email);
  CREATE INDEX IF NOT EXISTS idx_events_type_time ON events(event_type, occurred_at);
```

- [ ] **Step 2: Add prepared statements to the exported `q` object**

In `src/db.js`, inside the `export const q = { ... }` block, before the `// cleanup` block (around line 175), add this section:

```js
  // events — engagement tracking. One row per landmark event
  // (login, timeline_view) with device fields parsed from the UA.
  // Read-only from the app side; written once per event, never updated.
  recordEvent: db.prepare(
    `INSERT INTO events
       (event_type, email, occurred_at, session_id, device_type, os, browser, user_agent, meta)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
  ),
  listEvents: db.prepare(
    `SELECT id, event_type, email, occurred_at, session_id, device_type, os, browser, user_agent, meta
     FROM events ORDER BY occurred_at DESC LIMIT ?`
  ),
  listEventsByType: db.prepare(
    `SELECT id, event_type, email, occurred_at, session_id, device_type, os, browser, user_agent, meta
     FROM events WHERE event_type = ? ORDER BY occurred_at DESC LIMIT ?`
  ),
  listEventsForEmail: db.prepare(
    `SELECT id, event_type, occurred_at, session_id, device_type, os, browser, meta
     FROM events WHERE email = ? ORDER BY occurred_at DESC`
  ),
  // Per-user summary: pivot login + timeline_view counts onto one row.
  summariseEvents: db.prepare(
    `SELECT email,
            SUM(CASE WHEN event_type = 'login'         THEN 1 ELSE 0 END) AS logins,
            SUM(CASE WHEN event_type = 'timeline_view' THEN 1 ELSE 0 END) AS timeline_views,
            MAX(occurred_at) AS last_seen
     FROM events
     GROUP BY email
     ORDER BY last_seen DESC`
  ),
  countEventsByType: db.prepare(
    `SELECT event_type,
            COUNT(*)              AS total,
            COUNT(DISTINCT email) AS unique_users
     FROM events GROUP BY event_type ORDER BY event_type`
  ),
  deviceBreakdown: db.prepare(
    `SELECT device_type, COUNT(*) AS n
     FROM events
     WHERE device_type IS NOT NULL
     GROUP BY device_type ORDER BY n DESC`
  ),
```

- [ ] **Step 3: Verify the server starts and the table exists**

Run:

```bash
npm run dev
```

Expected: `[bifrost] listening on 127.0.0.1:3000`. No errors. Stop the server (Ctrl-C) once you see the line.

Then verify the table was created:

```bash
node -e "import('./src/db.js').then(({default: db}) => { console.log(db.prepare(\"SELECT name FROM sqlite_master WHERE type='table' AND name='events'\").all()); console.log(db.prepare('PRAGMA table_info(events)').all()); process.exit(0); })"
```

Expected: one row `{ name: 'events' }` followed by 10 column rows (`id`, `event_type`, `email`, `occurred_at`, `session_id`, `device_type`, `os`, `browser`, `user_agent`, `meta`).

- [ ] **Step 4: Commit**

```bash
git add src/db.js
git commit -m "events: add events table and prepared statements"
```

---

## Task 2: CLI skeleton — `bin/events.js`

Build the CLI now (before the recorder) so later tasks have a verification tool.

**Files:**
- Create: `bin/events.js`

- [ ] **Step 1: Create `bin/events.js`**

```js
#!/usr/bin/env node
// ─────────────────────────────────────────────────────────────
// bin/events.js — read the engagement-event log.
//
// Records every landmark event (login, timeline_view) with the
// user's email, device fields parsed from the UA, and the session
// ID at time-of-event.
//
// Usage:
//   node bin/events.js list [--type <event>] [--limit <n>]
//   node bin/events.js summary           # per-user counts
//   node bin/events.js for <email>       # full history for one user
//   node bin/events.js stats             # totals + device breakdown
// ─────────────────────────────────────────────────────────────
import { q } from '../src/db.js';

const args = process.argv.slice(2);
const cmd = args[0];
const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;

function help() {
  console.log('Usage:');
  console.log('  events list [--type <event>] [--limit <n>]');
  console.log('  events summary           # per-user counts');
  console.log('  events for <email>       # event history for a user');
  console.log('  events stats             # totals + device breakdown');
  process.exit(1);
}

function iso(t) { return new Date(t).toISOString(); }
function shortSid(s) { return s ? `[${s.slice(0, 8)}…]` : '[—]'; }

function parseFlag(name) {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : null;
}

function parseMeta(s) {
  if (!s) return null;
  try { return JSON.parse(s); } catch { return s; }
}

function metaCompact(m) {
  if (!m) return '';
  if (typeof m !== 'object') return String(m);
  return Object.entries(m).map(([k, v]) => `${k}=${v}`).join(' ');
}

switch (cmd) {
  case 'list': {
    const type = parseFlag('--type');
    const limit = Number(parseFlag('--limit') || 200);
    const rows = type
      ? q.listEventsByType.all(type, limit)
      : q.listEvents.all(limit);
    if (rows.length === 0) { console.log('(no events yet)'); break; }
    for (const r of rows) {
      const dev = [r.device_type, r.os, r.browser].filter(Boolean).join('/') || '?';
      const meta = metaCompact(parseMeta(r.meta));
      console.log(
        `  ${iso(r.occurred_at)}  ${r.event_type.padEnd(14)}  ${r.email.padEnd(28)}  ${dev.padEnd(24)}  ${shortSid(r.session_id)}  ${meta}`
      );
    }
    console.log(`\n${rows.length} event${rows.length === 1 ? '' : 's'} shown.`);
    break;
  }

  case 'summary': {
    const rows = q.summariseEvents.all();
    if (rows.length === 0) { console.log('(no events yet)'); break; }
    console.log('  LOGINS  TIMELINE  LAST SEEN                 EMAIL');
    for (const r of rows) {
      const lg = String(r.logins).padStart(6);
      const tv = String(r.timeline_views).padStart(8);
      console.log(`  ${lg}  ${tv}  ${iso(r.last_seen)}  ${r.email}`);
    }
    console.log(`\n${rows.length} unique user${rows.length === 1 ? '' : 's'}.`);
    break;
  }

  case 'for': {
    const arg = args[1];
    if (!arg || !EMAIL_RE.test(arg)) help();
    const email = arg.trim().toLowerCase();
    const rows = q.listEventsForEmail.all(email);
    if (rows.length === 0) { console.log(`(no events for ${email})`); break; }
    console.log(`Events for ${email}:`);
    for (const r of rows) {
      const dev = [r.device_type, r.os, r.browser].filter(Boolean).join('/') || '?';
      const meta = metaCompact(parseMeta(r.meta));
      console.log(`  ${iso(r.occurred_at)}  ${r.event_type.padEnd(14)}  ${dev.padEnd(24)}  ${shortSid(r.session_id)}  ${meta}`);
    }
    console.log(`\n${rows.length} event${rows.length === 1 ? '' : 's'}.`);
    break;
  }

  case 'stats': {
    const byType = q.countEventsByType.all();
    if (byType.length === 0) { console.log('(no events yet)'); break; }
    console.log('  EVENT TYPE      TOTAL  UNIQUE USERS');
    for (const r of byType) {
      console.log(`  ${r.event_type.padEnd(14)}  ${String(r.total).padStart(5)}  ${String(r.unique_users).padStart(12)}`);
    }
    const dev = q.deviceBreakdown.all();
    if (dev.length > 0) {
      console.log('\n  DEVICE TYPE     COUNT');
      for (const r of dev) {
        console.log(`  ${r.device_type.padEnd(14)}  ${String(r.n).padStart(5)}`);
      }
    }
    break;
  }

  default:
    help();
}
```

- [ ] **Step 2: Verify the CLI runs**

```bash
node bin/events.js list
```

Expected: `(no events yet)`.

```bash
node bin/events.js summary
```

Expected: `(no events yet)`.

```bash
node bin/events.js stats
```

Expected: `(no events yet)`.

```bash
node bin/events.js
```

Expected: usage help text, exit code 1.

- [ ] **Step 3: Commit**

```bash
git add bin/events.js
git commit -m "events: add bin/events.js CLI for reading the event log"
```

---

## Task 3: UA parser — `src/ua.js`

**Files:**
- Create: `src/ua.js`

- [ ] **Step 1: Create `src/ua.js`**

```js
// ─────────────────────────────────────────────────────────────
// src/ua.js — minimal User-Agent parser.
//
// Coarse-grained classification only: device_type / os / browser.
// We deliberately do NOT pull in ua-parser-js — the project keeps a
// small dependency footprint and we only need three buckets. The raw
// UA is also stored alongside parsed fields (see src/events.js) so a
// regex miss can be re-classified later.
//
// Also owns MOBILE_UA_RE — the existing /timeline view-dispatch
// regex used by server.js. Single source of truth.
// ─────────────────────────────────────────────────────────────

// UA substrings that mean "phone-class small screen". Tablets (iPad,
// Android tablets) deliberately do NOT match — they get the desktop
// view, which matches existing behaviour in server.js.
export const MOBILE_UA_RE =
  /\b(iPhone|iPod|Android.*Mobile|Mobile.*Firefox|IEMobile|BlackBerry|Opera Mini)\b/i;

// Tablet-class devices. Order matters in parseUA(): tablet check runs
// before mobile so "iPad" doesn't accidentally fall through to desktop.
const TABLET_UA_RE = /\b(iPad|Android(?!.*Mobile))\b/i;

export function parseUA(ua) {
  if (!ua || typeof ua !== 'string') {
    return { device_type: null, os: null, browser: null };
  }

  // device_type
  let device_type = 'desktop';
  if (TABLET_UA_RE.test(ua))      device_type = 'tablet';
  else if (MOBILE_UA_RE.test(ua)) device_type = 'mobile';

  // os
  let os = 'other';
  if      (/\b(iPhone|iPad|iPod)\b/.test(ua))   os = 'iOS';
  else if (/\bAndroid\b/.test(ua))              os = 'Android';
  else if (/\bWindows\b/.test(ua))              os = 'Windows';
  else if (/Mac OS X|Macintosh/.test(ua))       os = 'macOS';
  else if (/\bLinux\b/.test(ua))                os = 'Linux';

  // browser — order matters. All Chromium UAs include "Safari/", all
  // Edge UAs include "Chrome/", so the most specific token must win.
  let browser = 'other';
  if      (/\bEdg\//.test(ua))     browser = 'Edge';
  else if (/\bFirefox\//.test(ua)) browser = 'Firefox';
  else if (/\bChrome\//.test(ua))  browser = 'Chrome';
  else if (/\bSafari\//.test(ua))  browser = 'Safari';

  return { device_type, os, browser };
}
```

- [ ] **Step 2: Verify with a Node one-liner against known UA samples**

```bash
node -e "import('./src/ua.js').then(({parseUA}) => {
  const samples = [
    ['iphone safari', 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1'],
    ['android chrome', 'Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36'],
    ['ipad safari', 'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/604.1'],
    ['mac chrome', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'],
    ['win edge', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0'],
    ['linux firefox', 'Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0'],
    ['empty', '']
  ];
  for (const [label, ua] of samples) {
    console.log(label.padEnd(16), parseUA(ua));
  }
});"
```

Expected output:

```
iphone safari    { device_type: 'mobile',  os: 'iOS',     browser: 'Safari'  }
android chrome   { device_type: 'mobile',  os: 'Android', browser: 'Chrome'  }
ipad safari      { device_type: 'tablet',  os: 'iOS',     browser: 'Safari'  }
mac chrome       { device_type: 'desktop', os: 'macOS',   browser: 'Chrome'  }
win edge         { device_type: 'desktop', os: 'Windows', browser: 'Edge'    }
linux firefox    { device_type: 'desktop', os: 'Linux',   browser: 'Firefox' }
empty            { device_type: null,      os: null,      browser: null      }
```

If any row mismatches, fix the regex before committing.

- [ ] **Step 3: Commit**

```bash
git add src/ua.js
git commit -m "events: add UA parser (device_type/os/browser)"
```

---

## Task 4: Wire UA parser back into `server.js`

Replace the inline `MOBILE_UA_RE` declaration with an import from `src/ua.js`. Keeps a single source of truth.

**Files:**
- Modify: `server.js`

- [ ] **Step 1: Import `MOBILE_UA_RE` from `src/ua.js`**

In `server.js`, near the top imports (after the `q` import around line 15), add:

```js
import { MOBILE_UA_RE } from './src/ua.js';
```

- [ ] **Step 2: Delete the inline declaration**

In `server.js`, find and remove this line (currently around line 185):

```js
const MOBILE_UA_RE = /\b(iPhone|iPod|Android.*Mobile|Mobile.*Firefox|IEMobile|BlackBerry|Opera Mini)\b/i;
```

Leave the surrounding comment block intact (it documents `wantsMobileView()`); just the `const` line goes.

- [ ] **Step 3: Verify the server still starts and the dispatch still works**

Start the server:

```bash
npm run dev
```

In another terminal (still need a session cookie — assume one already exists in `cookies.txt` from prior testing, or create one with `node bin/invite.js add yourtest@example.com Test` then `curl -X POST http://127.0.0.1:3000/auth/login -H 'Content-Type: application/json' -d '{"email":"yourtest@example.com"}' -c cookies.txt`):

```bash
# desktop UA → desktop page
curl -s -o /dev/null -w "%{http_code}\n" -b cookies.txt \
  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' \
  http://127.0.0.1:3000/timeline

# iphone UA → mobile page (different file)
curl -s -b cookies.txt \
  -A 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Safari/604.1' \
  http://127.0.0.1:3000/timeline | grep -o 'protected/mobile\|fenja-wordmark' | head -1
```

Expected:
- First curl: `200`
- Second curl: should output a string that demonstrates the mobile page was served (e.g. a CSS class or asset path unique to mobile). If `grep` finds nothing, also try `head -c 200` to inspect the first bytes — the mobile page differs from the desktop one. The exact marker doesn't matter; what matters is that the two requests return *different* HTML.

A simpler equivalence check:

```bash
diff <(curl -s -b cookies.txt -A 'Mozilla/5.0' http://127.0.0.1:3000/timeline) \
     <(curl -s -b cookies.txt -A 'iPhone' http://127.0.0.1:3000/timeline) | head -3
```

Expected: non-empty diff (the two pages differ).

Stop the server.

- [ ] **Step 4: Commit**

```bash
git add server.js
git commit -m "events: source MOBILE_UA_RE from src/ua.js"
```

---

## Task 5: Event recorder — `src/events.js`

**Files:**
- Create: `src/events.js`

- [ ] **Step 1: Create `src/events.js`**

```js
// ─────────────────────────────────────────────────────────────
// src/events.js — landmark engagement event recorder.
//
// One function: recordEvent(req, {type, email, sessionId, meta}).
// Pulls the UA off the request, parses to {device_type, os, browser},
// and inserts a row into the `events` table (see src/db.js).
//
// Synchronous — better-sqlite3 is sync and the volume on this site
// is too low to justify any queueing or try/catch. If a future event
// becomes hot-path or recording becomes a failure mode, revisit.
//
// `sessionId` is passed in explicitly (rather than read from
// req.cookies) because the `login` event happens before req.cookies
// reflects the freshly-issued session cookie.
// ─────────────────────────────────────────────────────────────
import { q } from './db.js';
import { parseUA } from './ua.js';

export function recordEvent(req, { type, email, sessionId, meta = null }) {
  const ua = req.headers['user-agent'] || '';
  const { device_type, os, browser } = parseUA(ua);
  q.recordEvent.run(
    type,
    email,
    Date.now(),
    sessionId || null,
    device_type,
    os,
    browser,
    ua || null,
    meta ? JSON.stringify(meta) : null
  );
}
```

- [ ] **Step 2: Verify the module imports cleanly**

```bash
node -e "import('./src/events.js').then(m => console.log(typeof m.recordEvent === 'function' ? 'ok' : 'missing'))"
```

Expected: `ok`.

- [ ] **Step 3: Commit**

```bash
git add src/events.js
git commit -m "events: add recordEvent helper"
```

---

## Task 6: `issueSession()` returns the new session ID

**Files:**
- Modify: `src/sessions.js`

- [ ] **Step 1: Return `id` from `issueSession()`**

In `src/sessions.js`, find `issueSession` (currently around lines 19–38). At the end of the function body, after `res.cookie(...)`, add:

```js
  return id;
```

The full function should now read:

```js
export function issueSession(req, res, email) {
  const id = randomSessionId();
  const now = Date.now();
  q.createSession.run(
    id,
    email,
    now,
    now + SESSION_TTL_MS,
    req.ip || null,
    req.get('user-agent')?.slice(0, 500) || null
  );

  res.cookie(COOKIE_NAME, id, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    path: '/',
    maxAge: SESSION_TTL_MS,
  });

  return id;
}
```

- [ ] **Step 2: Verify nothing else breaks**

The only caller is `src/auth.js:54` (`issueSession(req, res, email)`), which currently ignores any return value. Verify with a grep:

```bash
node -e "console.log(require('child_process').execSync('grep -rn issueSession src/ server.js bin/ admin/').toString())"
```

(Or use Grep tool: pattern `issueSession`, path `.`.)

Expected: only two hits — the export in `src/sessions.js` and the call in `src/auth.js`. Adding a return value is non-breaking for the existing call site.

Then start the server to confirm it boots:

```bash
npm run dev
```

Expected: `[bifrost] listening on 127.0.0.1:3000`. Stop with Ctrl-C.

- [ ] **Step 3: Commit**

```bash
git add src/sessions.js
git commit -m "sessions: issueSession returns the new session id"
```

---

## Task 7: Record `login` event in `src/auth.js`

**Files:**
- Modify: `src/auth.js`

- [ ] **Step 1: Import `recordEvent`**

In `src/auth.js`, add to the imports near the top (after the existing imports around line 16–19):

```js
import { recordEvent } from './events.js';
```

- [ ] **Step 2: Capture the new session ID and record the event**

In `src/auth.js`, find the success branch of `POST /auth/login` (currently lines 53–59):

```js
    issueSession(req, res, email);
    return res.status(200).json({
      ok: true,
      firstName: invited.first_name || null,
    });
```

Replace with:

```js
    const sessionId = issueSession(req, res, email);
    recordEvent(req, { type: 'login', email, sessionId });
    return res.status(200).json({
      ok: true,
      firstName: invited.first_name || null,
    });
```

- [ ] **Step 3: Verify a login writes a `login` row**

Start the server:

```bash
npm run dev
```

In another terminal — first ensure an invite exists (skip if you already have one):

```bash
node bin/invite.js add tracktest@example.com Track
```

Log in via curl:

```bash
curl -i -X POST http://127.0.0.1:3000/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"tracktest@example.com"}' \
  -c cookies.txt
```

Expected: `HTTP/1.1 200 OK`, body `{"ok":true,"firstName":"Track"}`.

Then read the events log:

```bash
node bin/events.js list
```

Expected: one row with `event_type=login`, your email, current timestamp, device fields populated from curl's UA (curl's UA usually parses to `desktop / other / other`), session ID present (8-char prefix shown).

```bash
node bin/events.js summary
```

Expected: one row, `LOGINS=1, TIMELINE=0`.

Stop the server.

- [ ] **Step 4: Commit**

```bash
git add src/auth.js
git commit -m "events: record login event on POST /auth/login success"
```

---

## Task 8: Record `timeline_view` event in `server.js`

**Files:**
- Modify: `server.js`

- [ ] **Step 1: Import `recordEvent`**

In `server.js`, add to the imports near the top (after the `MOBILE_UA_RE` import added in Task 4):

```js
import { recordEvent } from './src/events.js';
```

- [ ] **Step 2: Record the event in the `/timeline` handler**

In `server.js`, find the `/timeline` route (currently lines 193–198):

```js
app.get('/timeline', requireAuth, (req, res) => {
  if (wantsMobileView(req)) {
    return res.sendFile(path.join(__dirname, 'protected', 'mobile', 'index.html'));
  }
  return res.sendFile(path.join(__dirname, 'protected', 'index.html'));
});
```

Replace with:

```js
app.get('/timeline', requireAuth, (req, res) => {
  const forced = ['mobile', 'desktop'].includes((req.query.view || '').toLowerCase());
  const view = wantsMobileView(req) ? 'mobile' : 'desktop';
  recordEvent(req, {
    type: 'timeline_view',
    email: req.session.email,
    sessionId: req.session.id,
    meta: { view, forced },
  });
  if (view === 'mobile') {
    return res.sendFile(path.join(__dirname, 'protected', 'mobile', 'index.html'));
  }
  return res.sendFile(path.join(__dirname, 'protected', 'index.html'));
});
```

The `forced` boolean is derived BEFORE `wantsMobileView()` collapses the query and UA into a single answer, so we record whether the user explicitly overrode the UA guess.

- [ ] **Step 3: Verify a timeline visit writes a `timeline_view` row**

Start the server (assumes you still have `cookies.txt` from Task 7):

```bash
npm run dev
```

```bash
# desktop UA, no override
curl -s -o /dev/null -b cookies.txt \
  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' \
  http://127.0.0.1:3000/timeline

# desktop UA, forced mobile via ?view=mobile
curl -s -o /dev/null -b cookies.txt \
  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' \
  'http://127.0.0.1:3000/timeline?view=mobile'

# iphone UA, no override
curl -s -o /dev/null -b cookies.txt \
  -A 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Safari/604.1' \
  http://127.0.0.1:3000/timeline
```

Then:

```bash
node bin/events.js list --type timeline_view
```

Expected: three rows, newest first:
- `timeline_view  tracktest@example.com  mobile/iOS/Safari      [...]  view=mobile  forced=false`
- `timeline_view  tracktest@example.com  desktop/macOS/Chrome   [...]  view=mobile  forced=true`
- `timeline_view  tracktest@example.com  desktop/macOS/Chrome   [...]  view=desktop forced=false`

```bash
node bin/events.js stats
```

Expected: `login total=1`, `timeline_view total=3`, device breakdown shows both `desktop` and `mobile`.

Stop the server.

- [ ] **Step 4: Commit**

```bash
git add server.js
git commit -m "events: record timeline_view on GET /timeline with view+forced meta"
```

---

## Task 9: Documentation

**Files:**
- Modify: `CLAUDE.md`
- Modify: `OPERATIONS.md`
- Modify: `CHECKLIST.md`

- [ ] **Step 1: Add `bin/events.js` to `CLAUDE.md` commands block**

In `CLAUDE.md`, find the `## Common commands` block. Below the existing `node bin/joins.js list` line (the one ending `# (also: summary, for <email>, stats)`), append:

```bash
node bin/events.js list              # read engagement event log
                                     # (also: summary, for <email>, stats)
```

- [ ] **Step 2: Add an "events" line to the bin/* description below the commands block**

In `CLAUDE.md`, find the line describing `bin/joins.js` (under "Conventions" near the bottom):

```
- `bin/invite.js` and `bin/joins.js` are the admin CLIs — there is no web UI for either by design. `invite.js` manages the invite list; `joins.js` reads the CTA click log.
```

Replace with:

```
- `bin/invite.js`, `bin/joins.js`, and `bin/events.js` are the admin CLIs — there is no web UI for them by design. `invite.js` manages the invite list; `joins.js` reads the final-CTA click log; `events.js` reads the engagement event log (logins, timeline views).
```

- [ ] **Step 3: Add a section to `OPERATIONS.md`**

In `OPERATIONS.md`, after the "Reading Join-CTA clicks" section (which ends around line 88 with a `sqlite3` example), and before the `## Service control` section, insert the literal text below. The outer 4-backtick fence is just so this plan can show triple-backtick content inside — paste only the inner content (everything between the lines marked `<<< begin paste >>>` and `<<< end paste >>>`).

````markdown
<<< begin paste >>>
## Reading engagement events

Logins and timeline page views are logged to the `events` table. Each row carries the user's email, a timestamp, the session ID, and device fields parsed from the User-Agent (`device_type`, `os`, `browser`). Use `bin/events.js` to read it:

```bash
# Every event, newest first (filter with --type, page with --limit)
sudo -u fenja node /opt/fenja/bin/events.js list
sudo -u fenja node /opt/fenja/bin/events.js list --type login --limit 50

# One row per user — login count, timeline-view count, last seen
sudo -u fenja node /opt/fenja/bin/events.js summary

# Full event history for a single user
sudo -u fenja node /opt/fenja/bin/events.js for someone@example.com

# Totals per event type + device-type breakdown
sudo -u fenja node /opt/fenja/bin/events.js stats
```

Events recorded:

- `login` — written on `POST /auth/login` success. One row per fresh login (cookie-loss re-logins included). The `meta` column is empty.
- `timeline_view` — written on every `GET /timeline`. `meta` is `{view: "mobile"|"desktop", forced: true|false}`; `forced=true` means the user passed `?view=mobile` or `?view=desktop` to override the UA guess.

For ad-hoc SQL:

```bash
sudo -u fenja sqlite3 /opt/fenja/data/fenja.sqlite \
  "SELECT event_type, email, datetime(occurred_at/1000,'unixepoch'), device_type, os, browser FROM events ORDER BY occurred_at DESC LIMIT 50;"
```
<<< end paste >>>
````

- [ ] **Step 4: Add a CHECKLIST section**

In `CHECKLIST.md`, after the existing `## H1. After changes to the Join-CTA tracking (bifrost_joins)` section (which ends around line 111), and BEFORE the `## H2. After changes to the hidden admin page` section, insert:

```markdown
## H1b. After changes to engagement event tracking (events)

- [ ] [browser, logged out] Log in fresh via the entrance form → entrance advances to the welcome step
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js list --type login --limit 5` shows a new row with your email, current timestamp, populated device/os/browser, and a session-ID prefix
- [ ] [browser, logged in] Visit `/timeline` → page loads
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js list --type timeline_view --limit 5` shows a new row with `view=desktop forced=false` (or `view=mobile forced=false` if you tested on a phone UA)
- [ ] [browser] Visit `/timeline?view=mobile` from a desktop UA → mobile page renders
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js list --type timeline_view --limit 5` shows the most recent row with `view=mobile forced=true`
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js summary` includes your email with correct `LOGINS` and `TIMELINE` counts
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js stats` totals match what `list` shows; device breakdown reflects the views you generated
- [ ] `sudo -u fenja node /opt/fenja/bin/events.js for <yourtestemail>` shows full per-user history
- [ ] No 500s in `journalctl -u fenja -n 100` from the test traffic
```

- [ ] **Step 5: Verify the docs render correctly**

Read each modified file back briefly:

```bash
node -e "console.log(require('fs').readFileSync('CLAUDE.md','utf8').match(/node bin\/events.js[^\n]*/g))"
node -e "console.log(require('fs').readFileSync('OPERATIONS.md','utf8').includes('Reading engagement events'))"
node -e "console.log(require('fs').readFileSync('CHECKLIST.md','utf8').includes('H1b. After changes to engagement event tracking'))"
```

Expected:
- First: array of two matches (`node bin/events.js list` and `node bin/events.js list --type ...` if it matches greedy).
- Second: `true`.
- Third: `true`.

- [ ] **Step 6: Commit**

```bash
git add CLAUDE.md OPERATIONS.md CHECKLIST.md
git commit -m "events: document bin/events.js in CLAUDE.md, OPERATIONS.md, CHECKLIST.md"
```

---

## Final manual verification (do once after all tasks land)

Walk the new H1b section in `CHECKLIST.md` end-to-end against a fresh local dev server. This catches any integration issue the per-task curl checks miss (cookie persistence across browser sessions, the `Secure` cookie flag toggling on `NODE_ENV=production`, etc.).

If anything in H1b fails, fix it BEFORE merging — and propagate the fix back into the relevant task's verification step in this plan so the same gap doesn't reappear next time.

## What's intentionally NOT in this plan

(See spec § "Out of scope" for full list.)

- Failed login tracking, logout tracking
- Scroll-depth, dwell time, per-section timeline views
- Folding `bifrost_joins` into the unified `events` table
- A web UI for viewing events
- Bot/crawler filtering (everything is invite-gated)
- Deploy/migration steps — `CREATE TABLE IF NOT EXISTS` runs on the next service restart per the existing `src/db.js` boot sequence; no separate migration step needed.