qtalker---/docs/superpowers/specs/2026-07-30-hunters-and-messages-design.md

Hunters, messages, and the encounter record

Five parallel workstreams. Registering already keeps your codex and unlocks device pairing; this gives an account an identity other hunters can see, a rank that grows with real activity, simple messages between hunters, and a Codex that shows who summoned each spirit and who else has met it.

Binding rules (every workstream)

• Additive only. Nothing removed, no restructuring outside your files.
• Guests stay first-class. A wanderer- account must keep working exactly as today. Profile fields are absent/defaulted for them. Never gate the séance. Guests may NOT send messages (see S) — that is the one deliberate account-only capability besides device pairing.
• i18n parity is a hard gate. Every user-facing string via t(), keys in BOTH src/i18n/en.json and es.json. npm run pretest must pass. If you use a template key (t(\x.${v}`)) add a domain rule to src/i18n/coverage-check.mjs— base names only, it derives*Title` itself.
• Tone: in-fiction throughout (seeker / hunter / the veil / presence).
• Backend tests: cd backend && set -a && source ../.env && set +a && source venv/bin/activate && python -m pytest tests/<file> -q -p no:cacheprovider Tests use quantumancy_test automatically — never point them at the live DB.
• Frontend: npx tsc --noEmit -p ., npm run pretest, npx vitest run.
• Mobile: usable at 390px, 44px touch targets, honour @media (prefers-reduced-motion: reduce).
• Shared files: if you must touch main.py, App.tsx, schemas.py or SeancePage.tsx, keep the diff to the fewest possible lines — the integrator merges several workstreams into each and resolves conflicts.

Workstream P — profile model, rank, profile API (backend only)

Files: models/user.py, main.py (migration lines only), rank.py (new), routes/profile.py (new), schemas.py, tests.

New nullable User columns (so every existing row, guests included, stays valid). Note email ALREADY EXISTS — do not re-add it.

• display_name: str | None — shown publicly; falls back to username.
• bio: str | None (<= 280 chars) — public.
• gender: str | None — male / female / unspecified; defaults to unspecified when absent. Public.
• avatar_form: str | None — one of wisp/banshee/fairy/shade.
• avatar_hue: int | None — 0..359.
• profile_public: bool default True.

Migration: idempotent ALTER TABLE ... ADD COLUMN IF NOT EXISTS in main.py's lifespan, matching the existing style exactly.

Avatar is procedural (form + hue, rendered by the existing GhostGlyph). No uploads: no moderation surface, no EXIF, no storage. Columns are shaped so a future avatar_url slots in without changing anything else.

rank.py — pure, no DB, no I/O, fully unit-tested:

• level_for(encounters, essence, favor) -> int
• progress_for(...) -> {level, title, encounters, next_at, progress}
• Thresholds grow progressively (document the curve's reasoning in a comment; no unexplained magic table). Level 1 must be reachable from a single séance so a new hunter sees progress immediately.
• Titles, one word each, in-fiction: e.g. curious → sensitive → channeler → medium → adept → oracle.
• Total and clamped: safe for negative essence, zero encounters, absurd values.

Endpoints:

• PATCH /api/profile (auth) — update display_name, bio, gender, avatar_form, avatar_hue, profile_public, email. Validate everything (length caps, enums, hue range, email shape — mirror routes/shop.py's regex style). Rate limit modestly.
• GET /api/profile/me (auth) — own profile INCLUDING email, plus rank/progress.
• GET /api/hunters/{username} (public) — display_name, bio, gender, avatar, level/title, encounter count, joined date, and up to 12 recently-contacted entities. 404 when profile_public is False. NEVER include email.
• GET /api/hunters (public) — top ~24 public hunters by encounter count.

encounter_count = distinct entity_id in that user's EntitySighting rows. The roster's counts must come from ONE aggregate query — no N+1.

Tests: guests unaffected; email absent from both public payloads (assert explicitly); private profile 404s; validation rejects bad enums/lengths/ hues; rank maths; roster excludes private profiles.

Workstream Q — profile UI (frontend only)

Files: pages/ProfilePage.tsx + css (/profile), pages/HunterPage.tsx + css (/hunters/:username), pages/HuntersPage.tsx + css (/hunters), routes in App.tsx, one topbar link in SeancePage.tsx.

Code against P's endpoint shapes exactly as specified above; P is building in parallel and will NOT exist in your worktree. Keep all fetching in ONE module (e.g. additions to src/api.ts) so a shape change is a one-file fix. Component tests must stub fetch — never depend on a live backend.

• Own profile: edit display name, bio (live char count), gender (three chips), avatar picker (4 forms × hue slider, previewing the real GhostGlyph live), public/private toggle, optional email field with a clear "recovery only, never shown publicly" note. Await the response and show a saved state.
• Public hunter page: large glyph, display name, title + level with a progress bar, encounter count, bio, recent-entity grid (reuse Codex card styling), and a "send a message" link to /messages/:username (S owns that route; just link to it).
• Roster: grid of hunter cards linking to each profile.
• Guests (wanderer- prefix): show the page with an in-fiction prompt to claim a name — do NOT hide or break it.

Workstream S — hunter messages (backend + frontend)

Files: models/message.py (new), routes/messages.py (new), main.py (import + include_router + migration), schemas.py, pages/MessagesPage.tsx + css, pages/ThreadPage.tsx + css (or one page handling both — implementer's call), App.tsx routes, tests.

Deliberately simple: plain text, no attachments, no editing, no groups.

Model Message: id, sender_id (FK users, index), recipient_id (FK users, index), body (Text, <= 1000 chars), created_at, read_at (nullable).

Endpoints (all auth required):

• POST /api/messages — {to: <username>, body: str}. Rate limit meaningfully (e.g. 20/hour/user). Guests cannot send — return 403 with an in-fiction message telling them to claim a name. Reject empty/oversized bodies, reject sending to yourself, 404 unknown recipient. Recipients with profile_public=False still receive (privacy hides the profile, not the mailbox).
• GET /api/messages — conversation list: each correspondent with their display name/avatar, last message excerpt, unread count. ONE aggregate query for unread counts, no N+1.
• GET /api/messages/{username} — the thread, newest last, paginated (limit ~50). Marks the caller's inbound messages read.
• Unread total exposed for a badge — either on this router or as a field on GET /api/profile/me (coordinate: prefer your own GET /api/messages response so you do not depend on P).

Tests: guest send is 403; can't message yourself; unknown recipient 404; oversized body rejected; a user only ever sees their OWN threads (assert no cross-user leak — this is the security-critical one); unread counts correct; reading marks read.

UI: conversation list, a thread view with a send box, in-fiction empty states. Sanitize nothing into HTML — render message bodies as plain text.

Workstream T — the encounter record (Codex)

Files: routes/codex.py, pages/CodexEntityPage.tsx (+ css), tests.

The data ALREADY exists — Entity.discovered_by is recorded and returned, and every contact is an EntitySighting(entity_id, user_id, session_id, seen_at) row. This workstream surfaces it.

• Extend GET /api/codex/{id} with:
  • discovered_by: keep the existing username, and add whether that hunter's profile is public so the UI knows whether to link it.
  • encounters: up to 20 distinct hunters who have contacted this spirit — username, display name if set, avatar form/hue, times contacted, last seen. Newest-first. Exclude hunters whose profile_public is False from being linkable, but still count them in the total (an anonymous contact is still a contact). Include a total_encounters count.
  • ONE aggregate query for the roster — no N+1 per hunter.
• Entity page: a "who has met this spirit" section — the summoner marked distinctly as the discoverer, then the roster. Link public profiles to /hunters/{username}; render private ones as plain, unlinked text.
• Tests: discoverer surfaced; roster aggregates correctly; private hunters counted but not linkable; an entity nobody has met doesn't crash.

Workstream V — verify the unverified audit findings (read-mostly)

An earlier adversarial audit produced findings but its verifier agents all died, so NONE were confirmed. Two were later verified and fixed by hand (the mic-release leak and the EVP failure misattribution); one was REFUTED (iOS EMF works — the permission flow is correctly wired, do not "fix" it).

For EACH remaining claim below: read the actual code, decide if it is real, and ONLY fix the ones that are. Report refutations explicitly — a confidently-refuted finding is as valuable as a fix, and "fixing" working code is worse than leaving it.

1. Session cookie may lack Secure for internet visitors because uvicorn doesn't trust X-Forwarded-Proto from the off-box Cloudflare Tunnel. (Check routes/auth.py cookie logic and how it decides secure.)
2. Remounting /seance while POST /auth/guest is in flight could provision a second wanderer, orphaning the first and burning two of five hourly rate-limit slots. (Check the guestAttempted ref guard.)
3. When guest provisioning is rate-limited the visitor is redirected to /enter with no explanation of what happened.
4. Rate limiters never evict keys — unbounded memory growth in rate_limit.py over a long-running process.
5. _summon's state.entity is None check can race hardware telemetry ingestion vs. the browser's auto-summon, double-processing one logical summon (duplicate essence/item).
6. Entities minted before the traits migration are stuck at degenerate defaults (all 0.5), making trust always correct and cross_over unreachable for them. (Check whether any such rows can still exist.)

Fix only what you prove. Add a regression test for each real fix.

Integration (controller)

Merge order: P, T, S, Q, V. Controller resolves main.py / App.tsx / schemas.py / SeancePage.tsx overlaps, runs both full suites plus the i18n gate, builds, deploys, restarts the service, verifies live endpoints, and pushes.