docs: add user accounts & job history implementation plan

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/superpowers/plans/2026-03-29-user-accounts-job-history.md

@@ -0,0 +1,1256 @@
+# User Accounts & Job History — 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 magic-link authentication, associate jobs with users, and provide a history page showing past analyses.
+
+**Architecture:** Backend-first approach. Add email column to DB, build auth middleware as a FastAPI dependency, protect API routes, then wire up frontend login/history pages with session management. Demo mode auto-fills tokens so no email service needed for development.
+
+**Tech Stack:** FastAPI (Python), vanilla JS SPA, aiosqlite, HMAC-SHA256 tokens, sessionStorage
+
+**Spec:** `docs/superpowers/specs/2026-03-28-user-accounts-job-history-design.md`
+
+---
+
+## File Structure
+
+### Backend (modify)
+- `app/database.py` — add `email` column migration, `get_jobs_by_email()`, update `create_job()`
+- `app/api/auth.py` — add `get_current_user()` dependency
+- `app/api/jobs.py` — add `GET /api/jobs` list endpoint, protect routes with auth
+
+### Frontend (modify)
+- `frontend/index.html` — add login page, history page, topbar links
+- `frontend/js/api.js` — add auth header to `apiFetch()`, add `requestMagicLink()`, `verifyToken()`, `listJobs()`
+- `frontend/js/app.js` — add login/history page setup, session management, nav guard, email auto-fill
+- `frontend/css/merlx.css` — login page styles, history card styles
+
+### Tests (create/modify)
+- `tests/test_database.py` — add tests for email column and `get_jobs_by_email()`
+- `tests/test_api_auth.py` — create: test `get_current_user()` dependency
+- `tests/test_api_jobs.py` — update: test auth on existing routes, test `GET /api/jobs` list
+
+---
+
+## Task 1: Database — Add Email Column & Query
+
+**Files:**
+- Modify: `app/database.py`
+- Modify: `tests/test_database.py`
+
+- [ ] **Step 1: Write failing tests for email column and get_jobs_by_email**
+
+Add to `tests/test_database.py`:
+
+```python
+@pytest.mark.asyncio
+async def test_create_job_stores_email(temp_db_path, sample_job_request):
+    db = Database(temp_db_path)
+    await db.init()
+    job_id = await db.create_job(sample_job_request)
+    # Read raw row to confirm email column
+    async with aiosqlite.connect(temp_db_path) as conn:
+        cur = await conn.execute("SELECT email FROM jobs WHERE id = ?", (job_id,))
+        row = await cur.fetchone()
+    assert row[0] == "test@example.com"
+
+
+@pytest.mark.asyncio
+async def test_get_jobs_by_email(temp_db_path, sample_job_request):
+    db = Database(temp_db_path)
+    await db.init()
+    id1 = await db.create_job(sample_job_request)
+    id2 = await db.create_job(sample_job_request)
+    jobs = await db.get_jobs_by_email("test@example.com")
+    assert len(jobs) == 2
+    # Most recent first
+    assert jobs[0].id == id2
+    assert jobs[1].id == id1
+
+
+@pytest.mark.asyncio
+async def test_get_jobs_by_email_filters(temp_db_path, sample_job_request):
+    db = Database(temp_db_path)
+    await db.init()
+    await db.create_job(sample_job_request)
+    jobs = await db.get_jobs_by_email("other@example.com")
+    assert len(jobs) == 0
+```
+
+Add `import aiosqlite` to the top of the test file.
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/test_database.py -v -k "email"`
+Expected: FAIL — `email` column does not exist, `get_jobs_by_email` not defined
+
+- [ ] **Step 3: Implement email column and get_jobs_by_email**
+
+In `app/database.py`, update the `init()` method — after the existing `CREATE TABLE IF NOT EXISTS jobs` statement, add the migration:
+
+```python
+        # Migration: add email column if missing
+        cur = await db.execute("PRAGMA table_info(jobs)")
+        columns = {row[1] for row in await cur.fetchall()}
+        if "email" not in columns:
+            await db.execute(
+                "ALTER TABLE jobs ADD COLUMN email TEXT NOT NULL DEFAULT ''"
+            )
+            await db.commit()
+```
+
+Update the `create_job()` method — in the INSERT statement, add `email` column:
+
+Change the INSERT from:
+```python
+            await db.execute(
+                """INSERT INTO jobs (id, request_json, status, progress_json,
+                                    results_json, error, created_at, updated_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                (job_id, request.model_dump_json(), JobStatus.QUEUED.value,
+                 json.dumps(progress), "[]", None, now, now),
+            )
+```
+
+To:
+```python
+            await db.execute(
+                """INSERT INTO jobs (id, request_json, status, progress_json,
+                                    results_json, error, created_at, updated_at,
+                                    email)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (job_id, request.model_dump_json(), JobStatus.QUEUED.value,
+                 json.dumps(progress), "[]", None, now, now, request.email),
+            )
+```
+
+Add the new method after `get_next_queued_job()`:
+
+```python
+    async def get_jobs_by_email(self, email: str) -> list[Job]:
+        async with aiosqlite.connect(self._db_path) as db:
+            db.row_factory = aiosqlite.Row
+            cur = await db.execute(
+                "SELECT * FROM jobs WHERE email = ? ORDER BY created_at DESC",
+                (email,),
+            )
+            rows = await cur.fetchall()
+        return [self._row_to_job(row) for row in rows]
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/test_database.py -v`
+Expected: ALL PASS (including existing tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add app/database.py tests/test_database.py
+git commit -m "feat: add email column to jobs table and get_jobs_by_email query"
+```
+
+---
+
+## Task 2: Auth Middleware — get_current_user Dependency
+
+**Files:**
+- Modify: `app/api/auth.py`
+- Create: `tests/test_api_auth.py`
+
+- [ ] **Step 1: Write failing tests for get_current_user**
+
+Create `tests/test_api_auth.py`:
+
+```python
+"""Tests for auth middleware — get_current_user dependency."""
+import time
+import hashlib
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import create_app
+
+
+def _make_token(email: str) -> str:
+    """Mirror the backend token generation for test fixtures."""
+    secret = "aperture-dev-secret"
+    hour = int(time.time() // 3600)
+    payload = f"{email}:{hour}:{secret}"
+    return hashlib.sha256(payload.encode()).hexdigest()[:32]
+
+
+@pytest.fixture
+async def client(tmp_path):
+    app = create_app(db_path=str(tmp_path / "test.db"), run_worker=False)
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as c:
+        yield c
+
+
+@pytest.mark.asyncio
+async def test_auth_header_valid(client):
+    email = "user@example.com"
+    token = _make_token(email)
+    resp = await client.get(
+        "/api/jobs",
+        headers={"Authorization": f"Bearer {email}:{token}"},
+    )
+    assert resp.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_auth_header_missing(client):
+    resp = await client.get("/api/jobs")
+    assert resp.status_code == 401
+    assert "missing" in resp.json()["detail"].lower() or "authorization" in resp.json()["detail"].lower()
+
+
+@pytest.mark.asyncio
+async def test_auth_header_bad_token(client):
+    resp = await client.get(
+        "/api/jobs",
+        headers={"Authorization": "Bearer user@example.com:badtoken"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_auth_header_malformed(client):
+    resp = await client.get(
+        "/api/jobs",
+        headers={"Authorization": "Bearer garbage"},
+    )
+    assert resp.status_code == 401
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/test_api_auth.py -v`
+Expected: FAIL — `GET /api/jobs` endpoint doesn't exist yet, no auth middleware
+
+- [ ] **Step 3: Implement get_current_user dependency**
+
+In `app/api/auth.py`, add after the existing imports:
+
+```python
+from fastapi import Header, HTTPException
+```
+
+Then add the dependency function after the existing `verify_token` endpoint:
+
+```python
+async def get_current_user(authorization: str = Header(default=None)) -> str:
+    """FastAPI dependency: extract and verify email from Authorization header.
+
+    Expected format: Bearer <email>:<token>
+    Returns the verified email address.
+    """
+    if not authorization:
+        raise HTTPException(status_code=401, detail="Authorization header missing")
+    parts = authorization.split(" ", 1)
+    if len(parts) != 2 or parts[0] != "Bearer":
+        raise HTTPException(status_code=401, detail="Invalid authorization format")
+    payload = parts[1]
+    if ":" not in payload:
+        raise HTTPException(status_code=401, detail="Invalid token format")
+    email, token = payload.split(":", 1)
+    # Verify against current and previous hour (handle clock edge)
+    for offset in (0, -1):
+        expected = _generate_token_for_hour(email, offset)
+        if hmac.compare_digest(token, expected):
+            return email
+    raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+
+def _generate_token_for_hour(email: str, hour_offset: int = 0) -> str:
+    """Generate token for a specific hour offset (0 = current, -1 = previous)."""
+    hour = int(time.time() // 3600) + hour_offset
+    payload = f"{email}:{hour}:{SECRET}"
+    return hashlib.sha256(payload.encode()).hexdigest()[:32]
+```
+
+Also refactor the existing `_generate_token` to use the new helper:
+
+```python
+def _generate_token(email: str) -> str:
+    return _generate_token_for_hour(email, 0)
+```
+
+- [ ] **Step 4: Add GET /api/jobs list endpoint (stub for now)**
+
+In `app/api/jobs.py`, add import and the new endpoint:
+
+Add to imports:
+```python
+from app.api.auth import get_current_user
+```
+
+Add new endpoint before the existing `get_job` route:
+
+```python
+@router.get("")
+async def list_jobs(email: str = Depends(get_current_user)):
+    jobs = await _db.get_jobs_by_email(email)
+    return [
+        {
+            "id": j.id,
+            "status": j.status.value,
+            "aoi_name": j.request.aoi.name,
+            "created_at": j.created_at.isoformat(),
+            "indicator_count": len(j.request.indicator_ids),
+        }
+        for j in jobs
+    ]
+```
+
+Add `Depends` to the FastAPI import:
+```python
+from fastapi import APIRouter, HTTPException, Depends
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/test_api_auth.py -v`
+Expected: ALL PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add app/api/auth.py app/api/jobs.py tests/test_api_auth.py
+git commit -m "feat: add get_current_user auth dependency and GET /api/jobs list endpoint"
+```
+
+---
+
+## Task 3: Protect Existing Job Routes with Auth
+
+**Files:**
+- Modify: `app/api/jobs.py`
+- Modify: `tests/test_api_jobs.py`
+
+- [ ] **Step 1: Write failing tests for auth on existing routes**
+
+Update `tests/test_api_jobs.py`. First add the token helper and update the fixture:
+
+```python
+import time
+import hashlib
+
+def _make_token(email: str) -> str:
+    secret = "aperture-dev-secret"
+    hour = int(time.time() // 3600)
+    payload = f"{email}:{hour}:{secret}"
+    return hashlib.sha256(payload.encode()).hexdigest()[:32]
+
+def _auth_headers(email: str = "test@example.com") -> dict:
+    token = _make_token(email)
+    return {"Authorization": f"Bearer {email}:{token}"}
+```
+
+Add these new tests:
+
+```python
+@pytest.mark.asyncio
+async def test_submit_job_requires_auth(client, sample_job_request):
+    resp = await client.post("/api/jobs", json=sample_job_request.model_dump(mode="json"))
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_job_requires_auth(client, sample_job_request):
+    # Create a job first (with auth)
+    resp = await client.post(
+        "/api/jobs",
+        json=sample_job_request.model_dump(mode="json"),
+        headers=_auth_headers(),
+    )
+    job_id = resp.json()["id"]
+    # Try to get without auth
+    resp = await client.get(f"/api/jobs/{job_id}")
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_job_wrong_user(client, sample_job_request):
+    resp = await client.post(
+        "/api/jobs",
+        json=sample_job_request.model_dump(mode="json"),
+        headers=_auth_headers("test@example.com"),
+    )
+    job_id = resp.json()["id"]
+    resp = await client.get(
+        f"/api/jobs/{job_id}",
+        headers=_auth_headers("other@example.com"),
+    )
+    assert resp.status_code == 403
+```
+
+Update the existing passing tests to include auth headers:
+
+```python
+@pytest.mark.asyncio
+async def test_submit_job(client, sample_job_request):
+    resp = await client.post(
+        "/api/jobs",
+        json=sample_job_request.model_dump(mode="json"),
+        headers=_auth_headers(),
+    )
+    assert resp.status_code == 201
+    data = resp.json()
+    assert "id" in data
+
+
+@pytest.mark.asyncio
+async def test_get_job(client, sample_job_request):
+    resp = await client.post(
+        "/api/jobs",
+        json=sample_job_request.model_dump(mode="json"),
+        headers=_auth_headers(),
+    )
+    job_id = resp.json()["id"]
+    resp = await client.get(f"/api/jobs/{job_id}", headers=_auth_headers())
+    assert resp.status_code == 200
+    assert resp.json()["id"] == job_id
+```
+
+- [ ] **Step 2: Run tests to verify new tests fail**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/test_api_jobs.py -v`
+Expected: New auth tests FAIL (routes not yet protected)
+
+- [ ] **Step 3: Add auth dependency to existing routes**
+
+In `app/api/jobs.py`, update the submit and get endpoints:
+
+```python
+@router.post("", status_code=201)
+async def submit_job(request: JobRequest, email: str = Depends(get_current_user)):
+    job_id = await _db.create_job(request)
+    job = await _db.get_job(job_id)
+    return {"id": job.id, "status": job.status.value}
+
+
+@router.get("/{job_id}")
+async def get_job(job_id: str, email: str = Depends(get_current_user)):
+    job = await _db.get_job(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Job not found")
+    # Verify job belongs to authenticated user
+    if job.request.email != email:
+        raise HTTPException(status_code=403, detail="Not your job")
+    return {
+        "id": job.id,
+        "status": job.status.value,
+        "progress": job.progress,
+        "results": [r.model_dump() for r in job.results],
+        "created_at": job.created_at.isoformat(),
+        "updated_at": job.updated_at.isoformat(),
+        "error": job.error,
+    }
+```
+
+- [ ] **Step 4: Run all tests**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/ -v`
+Expected: ALL PASS. Check that existing tests in other files still pass (worker tests use DB directly, not API).
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add app/api/jobs.py tests/test_api_jobs.py
+git commit -m "feat: protect job API routes with auth, verify job ownership"
+```
+
+---
+
+## Task 4: Frontend API — Auth Header & New Endpoints
+
+**Files:**
+- Modify: `frontend/js/api.js`
+
+- [ ] **Step 1: Add session-aware auth header to apiFetch**
+
+In `frontend/js/api.js`, update the `apiFetch` function. Currently it looks like:
+
+```javascript
+async function apiFetch(path, opts = {}) {
+```
+
+Replace with:
+
+```javascript
+async function apiFetch(path, opts = {}) {
+  const session = JSON.parse(sessionStorage.getItem('aperture_session') || 'null');
+  if (session) {
+    opts.headers = {
+      ...opts.headers,
+      'Authorization': `Bearer ${session.email}:${session.token}`,
+    };
+  }
+```
+
+The rest of the function body stays the same.
+
+- [ ] **Step 2: Add new API functions**
+
+Add these exports at the bottom of `frontend/js/api.js`:
+
+```javascript
+export async function requestMagicLink(email) {
+  return apiFetch('/api/auth/request', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email }),
+  });
+}
+
+export async function verifyToken(email, token) {
+  return apiFetch('/api/auth/verify', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, token }),
+  });
+}
+
+export async function listJobs() {
+  return apiFetch('/api/jobs');
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add frontend/js/api.js
+git commit -m "feat: add auth header to API calls, add login and listJobs API functions"
+```
+
+---
+
+## Task 5: Frontend — Login Page HTML & CSS
+
+**Files:**
+- Modify: `frontend/index.html`
+- Modify: `frontend/css/merlx.css`
+
+- [ ] **Step 1: Add login page HTML**
+
+In `frontend/index.html`, add the login page between the `page-landing` closing `</div>` (line 111) and the `page-define-area` comment (line 114):
+
+```html
+<!-- ═══════════════════════════════════════════════════════════
+     PAGE — LOGIN
+     ═══════════════════════════════════════════════════════════ -->
+<div id="page-login" class="page">
+  <div class="login-card">
+
+    <!-- Logo -->
+    <div class="login-logo">
+      MERL<span style="color: var(--iris)">x</span>
+    </div>
+    <div style="font-family: 'DM Serif Display', serif; font-style: italic; font-size: var(--text-lg); color: var(--ink-muted); margin-bottom: var(--space-10); text-align: center;">
+      Aperture
+    </div>
+
+    <!-- State 1: Email entry -->
+    <div id="login-email-step">
+      <h2 class="login-heading">Sign in to continue</h2>
+      <div class="form-group" style="margin-bottom: var(--space-8);">
+        <label class="label" for="login-email">Email address</label>
+        <input id="login-email" class="input" type="email" placeholder="you@organisation.org" />
+      </div>
+      <button id="login-send-btn" class="btn btn-primary" style="width:100%;">
+        Send magic link
+      </button>
+      <p class="login-helper">In demo mode, the code will appear automatically.</p>
+    </div>
+
+    <!-- State 2: Token entry -->
+    <div id="login-token-step" style="display:none;">
+      <h2 class="login-heading" id="login-token-heading">Check your email</h2>
+      <div class="form-group" style="margin-bottom: var(--space-8);">
+        <label class="label" for="login-token">Verification code</label>
+        <input id="login-token" class="input" type="text" placeholder="Paste your code" />
+      </div>
+      <button id="login-verify-btn" class="btn btn-primary" style="width:100%;">
+        Verify
+      </button>
+      <a href="#" id="login-back-link" class="login-back-link">Use a different email</a>
+    </div>
+
+  </div>
+</div>
+```
+
+- [ ] **Step 2: Add login page styles**
+
+In `frontend/css/merlx.css`, add before the `/* --- Map Page --- */` section:
+
+```css
+/* --- Login Page --- */
+#page-login {
+  align-items: center;
+  justify-content: center;
+  background-color: var(--shell);
+}
+
+.login-card {
+  background-color: var(--surface);
+  border: 1px solid var(--border-light);
+  border-radius: var(--radius-lg);
+  padding: var(--space-12);
+  width: 100%;
+  max-width: 380px;
+}
+
+.login-logo {
+  font-size: 22px;
+  font-weight: 700;
+  letter-spacing: -0.3px;
+  text-align: center;
+  margin-bottom: var(--space-2);
+}
+
+.login-heading {
+  font-size: var(--text-lg);
+  font-weight: 600;
+  margin-bottom: var(--space-8);
+  letter-spacing: -0.2px;
+}
+
+.login-helper {
+  font-size: var(--text-xs);
+  color: var(--ink-faint);
+  text-align: center;
+  margin-top: var(--space-5);
+}
+
+.login-back-link {
+  display: block;
+  text-align: center;
+  margin-top: var(--space-5);
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+  text-decoration: none;
+}
+
+.login-back-link:hover {
+  color: var(--iris-dark);
+  text-decoration: underline;
+}
+```
+
+- [ ] **Step 3: Add `#page-login` height override in index.html `<style>` block**
+
+In the `<style>` block in `index.html`, add after the `#page-landing` rule:
+
+```css
+    #page-login {
+      height: 100vh;
+      align-items: center;
+      justify-content: center;
+      background-color: var(--shell);
+    }
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add frontend/index.html frontend/css/merlx.css
+git commit -m "feat: add login page HTML and CSS"
+```
+
+---
+
+## Task 6: Frontend — History Page HTML & CSS
+
+**Files:**
+- Modify: `frontend/index.html`
+- Modify: `frontend/css/merlx.css`
+
+- [ ] **Step 1: Add history page HTML**
+
+In `frontend/index.html`, add before the results page comment:
+
+```html
+<!-- ═══════════════════════════════════════════════════════════
+     PAGE — HISTORY
+     ═══════════════════════════════════════════════════════════ -->
+<div id="page-history" class="page">
+
+  <!-- Top bar -->
+  <div class="history-topbar">
+    <span class="logo">MERL<span class="x">x</span></span>
+    <h2 style="font-size: var(--text-base); font-weight: 600; color: var(--ink);">My Analyses</h2>
+    <div style="display:flex; align-items:center; gap: var(--space-5);">
+      <button id="history-new-btn" class="btn btn-primary">New analysis</button>
+      <a href="#" id="history-signout" class="topbar-link">Sign out</a>
+    </div>
+  </div>
+
+  <!-- Job list -->
+  <div id="history-list" class="history-list">
+    <!-- Populated by app.js -->
+  </div>
+
+  <!-- Empty state -->
+  <div id="history-empty" class="history-empty" style="display:none;">
+    <p>No analyses yet. Start your first one.</p>
+    <button id="history-empty-cta" class="btn btn-primary" style="margin-top: var(--space-8);">
+      New analysis
+    </button>
+  </div>
+
+</div>
+```
+
+- [ ] **Step 2: Add history page styles**
+
+In `frontend/css/merlx.css`, add before the `/* --- Results Page --- */` section:
+
+```css
+/* --- History Page --- */
+#page-history {
+  flex-direction: column;
+  height: 100vh;
+  overflow: hidden;
+}
+
+.history-topbar {
+  padding: var(--space-5) var(--space-12);
+  border-bottom: 1px solid var(--border-light);
+  background-color: var(--surface);
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.history-list {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--space-12);
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: var(--space-5);
+  align-content: start;
+}
+
+.history-card {
+  background-color: var(--surface);
+  border: 1px solid var(--border-light);
+  border-radius: var(--radius-md);
+  padding: var(--space-8);
+  cursor: pointer;
+  transition: border-color var(--motion-default) var(--ease-default),
+              background-color var(--motion-default) var(--ease-default);
+}
+
+.history-card:hover {
+  border-color: var(--border);
+  background-color: var(--shell-cool);
+}
+
+.history-card-name {
+  font-size: var(--text-base);
+  font-weight: 600;
+  color: var(--ink);
+  margin-bottom: var(--space-3);
+}
+
+.history-card-meta {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: var(--space-4);
+}
+
+.history-card-date {
+  font-family: var(--font-data);
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+}
+
+.history-card-indicators {
+  font-size: var(--text-xxs);
+  color: var(--ink-faint);
+}
+
+.history-empty {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  color: var(--ink-muted);
+  font-size: var(--text-sm);
+}
+
+.topbar-link {
+  font-size: var(--text-xs);
+  color: var(--ink-muted);
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.topbar-link:hover {
+  color: var(--ink);
+  text-decoration: underline;
+}
+```
+
+- [ ] **Step 3: Add height override in index.html `<style>` block**
+
+Add in the `<style>` block:
+
+```css
+    #page-history {
+      height: 100vh;
+      flex-direction: column;
+      overflow: hidden;
+    }
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add frontend/index.html frontend/css/merlx.css
+git commit -m "feat: add history page HTML and CSS"
+```
+
+---
+
+## Task 7: Frontend — Topbar Links on Existing Pages
+
+**Files:**
+- Modify: `frontend/index.html`
+
+- [ ] **Step 1: Add "My analyses" and "Sign out" links to existing topbars**
+
+In `frontend/index.html`, update the **indicators page topbar** — add links in the right-side div. Find the indicators topbar right-side div (contains only the Back button) and update:
+
+```html
+    <div style="display:flex; align-items:center; gap: var(--space-5);">
+      <a href="#" class="topbar-link nav-my-analyses">My analyses</a>
+      <a href="#" class="topbar-link nav-signout">Sign out</a>
+      <button id="indicators-back-btn" class="btn btn-secondary">Back</button>
+    </div>
+```
+
+Update the **results page topbar** — add links before the "New analysis" button:
+
+```html
+  <div class="results-topbar">
+    <span class="logo">MERL<span class="x">x</span></span>
+    <h2 style="font-size: var(--text-base); font-weight: 600; color: var(--ink);">Results Dashboard</h2>
+    <div style="display:flex; align-items:center; gap: var(--space-5);">
+      <a href="#" class="topbar-link nav-my-analyses">My analyses</a>
+      <a href="#" class="topbar-link nav-signout">Sign out</a>
+      <button
+        class="btn btn-secondary"
+        id="results-new-btn"
+        style="font-size: var(--text-xs);"
+      >
+        New analysis
+      </button>
+    </div>
+  </div>
+```
+
+Remove the `onclick="window.location.reload()"` from the results new analysis button (we'll wire it up in JS).
+
+- [ ] **Step 2: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add frontend/index.html
+git commit -m "feat: add My analyses and Sign out links to topbars"
+```
+
+---
+
+## Task 8: Frontend — Session Management, Nav Guard & Login Logic
+
+**Files:**
+- Modify: `frontend/js/app.js`
+
+- [ ] **Step 1: Add session state and imports**
+
+At the top of `frontend/js/app.js`, update the import line:
+
+```javascript
+import { submitJob, getJob, requestMagicLink, verifyToken, listJobs } from './api.js';
+```
+
+Add `session` to the state object:
+
+```javascript
+const state = {
+  session: null,   // { email, token }
+  aoi: null,
+  timeRange: null,
+  indicators: [],
+  jobId: null,
+  jobData: null,
+};
+```
+
+- [ ] **Step 2: Add session persistence helpers**
+
+Add after the state object:
+
+```javascript
+/* ── Session Persistence ────────────────────────────────── */
+
+const SESSION_KEY = 'aperture_session';
+
+function saveSession(email, token) {
+  state.session = { email, token };
+  sessionStorage.setItem(SESSION_KEY, JSON.stringify(state.session));
+}
+
+function loadSession() {
+  const raw = sessionStorage.getItem(SESSION_KEY);
+  if (raw) {
+    try { state.session = JSON.parse(raw); } catch { state.session = null; }
+  }
+}
+
+function clearSession() {
+  state.session = null;
+  sessionStorage.removeItem(SESSION_KEY);
+}
+```
+
+- [ ] **Step 3: Add nav guard to navigate()**
+
+Update the `navigate()` function. After the poll timer cleanup and before hiding pages, add:
+
+```javascript
+  // Auth guard — redirect to login if not authenticated
+  const AUTH_REQUIRED = ['define-area', 'indicators', 'confirm', 'status', 'results', 'history'];
+  if (AUTH_REQUIRED.includes(pageId) && !state.session) {
+    pageId = 'login';
+  }
+```
+
+- [ ] **Step 4: Add login and history to PAGES and pageSetup**
+
+Update the PAGES array:
+
+```javascript
+const PAGES = ['landing', 'login', 'define-area', 'indicators', 'confirm', 'status', 'results', 'history'];
+```
+
+Add to pageSetup object:
+
+```javascript
+  'login': setupLogin,
+  'history': setupHistory,
+```
+
+- [ ] **Step 5: Implement setupLogin**
+
+Add the function:
+
+```javascript
+/* ── Login Page ─────────────────────────────────────────── */
+
+let _loginInit = false;
+
+function setupLogin() {
+  if (_loginInit) return;
+  _loginInit = true;
+
+  const emailStep = document.getElementById('login-email-step');
+  const tokenStep = document.getElementById('login-token-step');
+  const emailInput = document.getElementById('login-email');
+  const tokenInput = document.getElementById('login-token');
+  const sendBtn = document.getElementById('login-send-btn');
+  const verifyBtn = document.getElementById('login-verify-btn');
+  const backLink = document.getElementById('login-back-link');
+  const heading = document.getElementById('login-token-heading');
+
+  let _loginEmail = '';
+
+  sendBtn.addEventListener('click', async () => {
+    const email = emailInput.value.trim();
+    if (!email) return;
+    sendBtn.disabled = true;
+    try {
+      const resp = await requestMagicLink(email);
+      _loginEmail = email;
+      emailStep.style.display = 'none';
+      tokenStep.style.display = 'block';
+      // Demo mode: auto-fill token
+      if (resp.demo_token) {
+        heading.textContent = 'Demo code';
+        tokenInput.value = resp.demo_token;
+      } else {
+        heading.textContent = 'Check your email';
+      }
+    } catch (err) {
+      showError(err.message || 'Failed to send magic link');
+    } finally {
+      sendBtn.disabled = false;
+    }
+  });
+
+  verifyBtn.addEventListener('click', async () => {
+    const token = tokenInput.value.trim();
+    if (!token) return;
+    verifyBtn.disabled = true;
+    try {
+      await verifyToken(_loginEmail, token);
+      saveSession(_loginEmail, token);
+      navigate('history');
+    } catch (err) {
+      showError(err.message || 'Invalid or expired code');
+    } finally {
+      verifyBtn.disabled = false;
+    }
+  });
+
+  backLink.addEventListener('click', (e) => {
+    e.preventDefault();
+    tokenStep.style.display = 'none';
+    emailStep.style.display = 'block';
+    tokenInput.value = '';
+  });
+}
+```
+
+- [ ] **Step 6: Implement setupHistory**
+
+```javascript
+/* ── History Page ────────────────────────────────────────── */
+
+let _historyInit = false;
+
+function setupHistory() {
+  const listEl = document.getElementById('history-list');
+  const emptyEl = document.getElementById('history-empty');
+
+  // Wire up buttons (once)
+  if (!_historyInit) {
+    _historyInit = true;
+    document.getElementById('history-new-btn').addEventListener('click', () => navigate('define-area'));
+    document.getElementById('history-empty-cta').addEventListener('click', () => navigate('define-area'));
+    document.getElementById('history-signout').addEventListener('click', (e) => {
+      e.preventDefault();
+      clearSession();
+      navigate('landing');
+    });
+  }
+
+  // Fetch and render jobs
+  listJobs().then(jobs => {
+    listEl.innerHTML = '';
+    if (jobs.length === 0) {
+      listEl.style.display = 'none';
+      emptyEl.style.display = 'flex';
+      return;
+    }
+    listEl.style.display = 'grid';
+    emptyEl.style.display = 'none';
+    for (const job of jobs) {
+      const card = document.createElement('div');
+      card.className = 'history-card';
+      card.setAttribute('role', 'button');
+      card.setAttribute('tabindex', '0');
+      const dateStr = new Date(job.created_at).toLocaleDateString(undefined, {
+        year: 'numeric', month: 'short', day: 'numeric',
+      });
+      card.innerHTML = `
+        <div class="history-card-name">${_esc(job.aoi_name || 'Untitled')}</div>
+        <div class="history-card-meta">
+          <span class="history-card-date">${_esc(dateStr)}</span>
+          <span><span class="badge badge-${job.status}">${_esc(job.status)}</span></span>
+        </div>
+        <div class="history-card-indicators">${job.indicator_count} indicator${job.indicator_count !== 1 ? 's' : ''}</div>
+      `;
+      card.addEventListener('click', () => {
+        state.jobId = job.id;
+        navigate(job.status === 'complete' ? 'results' : 'status');
+      });
+      card.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); card.click(); }
+      });
+      listEl.appendChild(card);
+    }
+  }).catch(err => {
+    showError('Failed to load analyses');
+  });
+}
+```
+
+- [ ] **Step 7: Wire up global topbar links and update init**
+
+Add after setupHistory:
+
+```javascript
+/* ── Global Topbar Wiring ───────────────────────────────── */
+
+function wireTopbarLinks() {
+  document.querySelectorAll('.nav-my-analyses').forEach(link => {
+    link.addEventListener('click', (e) => { e.preventDefault(); navigate('history'); });
+  });
+  document.querySelectorAll('.nav-signout').forEach(link => {
+    link.addEventListener('click', (e) => {
+      e.preventDefault();
+      clearSession();
+      navigate('landing');
+    });
+  });
+  // Results page "New analysis" button
+  const resultsNewBtn = document.getElementById('results-new-btn');
+  if (resultsNewBtn) {
+    resultsNewBtn.addEventListener('click', () => navigate('define-area'));
+  }
+}
+```
+
+Update the bottom of the file — find the `DOMContentLoaded` or the init block. The current init (at the bottom of app.js) likely starts with navigating to landing. Update it:
+
+```javascript
+/* ── Bootstrap ──────────────────────────────────────────── */
+
+document.addEventListener('DOMContentLoaded', () => {
+  loadSession();
+  wireTopbarLinks();
+  navigate('landing');
+});
+```
+
+- [ ] **Step 8: Update setupLanding to navigate to login instead of define-area**
+
+In `setupLanding()`, change the CTA click handler from:
+```javascript
+navigate('define-area')
+```
+to:
+```javascript
+navigate('login')
+```
+
+- [ ] **Step 9: Auto-fill email on confirm page**
+
+In `setupConfirm()`, after the line that populates `confirm-indicators`, add:
+
+```javascript
+  // Auto-fill email from session
+  const emailInput = document.getElementById('confirm-email');
+  if (state.session && state.session.email) {
+    emailInput.value = state.session.email;
+    emailInput.readOnly = true;
+  }
+```
+
+- [ ] **Step 10: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add frontend/js/app.js
+git commit -m "feat: add login flow, history page, session management, and nav guard"
+```
+
+---
+
+## Task 9: Integration Test — Full Flow
+
+**Files:**
+- Modify: `tests/test_api_auth.py`
+
+- [ ] **Step 1: Add end-to-end auth + job list test**
+
+Add to `tests/test_api_auth.py`:
+
+```python
+@pytest.mark.asyncio
+async def test_full_auth_and_job_list_flow(client):
+    email = "flow@example.com"
+
+    # 1. Request magic link
+    resp = await client.post("/api/auth/request", json={"email": email})
+    assert resp.status_code == 200
+    demo_token = resp.json()["demo_token"]
+
+    # 2. Verify token
+    resp = await client.post(
+        "/api/auth/verify", json={"email": email, "token": demo_token}
+    )
+    assert resp.status_code == 200
+    assert resp.json()["verified"] is True
+
+    # 3. Submit a job with auth
+    headers = {"Authorization": f"Bearer {email}:{demo_token}"}
+    job_payload = {
+        "aoi": {"name": "Test Area", "bbox": [32.5, 15.5, 32.6, 15.6]},
+        "time_range": {"start": "2025-03-01", "end": "2026-03-01"},
+        "indicator_ids": ["fires"],
+        "email": email,
+    }
+    resp = await client.post("/api/jobs", json=job_payload, headers=headers)
+    assert resp.status_code == 201
+    job_id = resp.json()["id"]
+
+    # 4. List jobs — should see the one we created
+    resp = await client.get("/api/jobs", headers=headers)
+    assert resp.status_code == 200
+    jobs = resp.json()
+    assert len(jobs) == 1
+    assert jobs[0]["id"] == job_id
+    assert jobs[0]["aoi_name"] == "Test Area"
+    assert jobs[0]["indicator_count"] == 1
+
+    # 5. Other user sees nothing
+    other_email = "other@example.com"
+    other_token = _make_token(other_email)
+    other_headers = {"Authorization": f"Bearer {other_email}:{other_token}"}
+    resp = await client.get("/api/jobs", headers=other_headers)
+    assert resp.status_code == 200
+    assert resp.json() == []
+```
+
+- [ ] **Step 2: Run all tests**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/ -v`
+Expected: ALL PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/kmini/Github/Aperture
+git add tests/test_api_auth.py
+git commit -m "test: add end-to-end auth and job list integration test"
+```
+
+---
+
+## Task 10: Final Verification
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m pytest tests/ -v --tb=short`
+Expected: ALL PASS, zero failures
+
+- [ ] **Step 2: Start the server and smoke-test manually**
+
+Run: `cd /Users/kmini/Github/Aperture && python -m uvicorn app.main:app --port 7860 --host 0.0.0.0`
+
+Verify in browser:
+1. Landing page → "Start a new analysis" → Login page appears
+2. Enter email → demo token auto-fills → Verify → History page (empty state)
+3. "New analysis" → Define Area → full flow works
+4. After job submission, "My analyses" link → History shows the job
+5. "Sign out" → returns to landing
+6. Refresh → session restored from sessionStorage
+
+- [ ] **Step 3: Final commit with all files**
+
+Ensure everything is committed. Run `git status` to check for any uncommitted changes.